| Skip Navigation Links | |
| Exit Print View | |
 | man pages section 2: System Calls Oracle Solaris 11 Information Library |
| Skip Navigation Links | |
| Exit Print View | |
| man pages section 2: System Calls Oracle Solaris 11 Information Library |
- send a message on a stream
#include <stropts.h>intputmsg(intfildes,const struct strbuf *ctlptr,const struct strbuf *dataptr,intflags);
intputpmsg(intfildes,const struct strbuf *ctlptr,const struct strbuf *dataptr,intband,intflags);
Theputmsg() function creates a message from user-specified buffer(s) and sendsthe message to a streams file. The message may contain either adata part, a control part, or both. The data and control partsto be sent are distinguished by placement in separate buffers, as describedbelow. The semantics of each part is defined by the streams modulethat receives the message.
Theputpmsg() function does the same thing asputmsg(), but provides theuser the ability to send messages in different priority bands. Except wherenoted, all information pertaining toputmsg() also pertains toputpmsg().
Thefildes argument specifies a file descriptor referencing an open stream. Thectlptr anddataptr arguments each point to astrbuf structure, which containsthe following members:
int maxlen; /* not used here */int len; /* length of data */void *buf; /* ptr to buffer */
Thectlptr argument points to the structure describing the control part, ifany, to be included in the message. Thebuf member in thestrbuf structure points to the buffer where the control information resides, andthelen member indicates the number of bytes to be sent. Themaxlenmember is not used inputmsg() (seegetmsg(2)). In a similar manner,dataptr specifies the data, if any, to be included in themessage. Theflags argument indicates what type of message should besent and is described later.
To send the data part of a message,dataptr must not beNULL, and thelen member ofdataptr must have a valueof 0 or greater. To send the control part of a message,the corresponding values must be set forctlptr. No data (control) partis sent if eitherdataptr (ctlptr) isNULL or thelenmember ofdataptr (ctlptr) is negative.
Forputmsg(), if a control part is specified, andflags is settoRS_HIPRI, a high priority message is sent. If no controlpart is specified, andflags is set toRS_HIPRI,putmsg() fails and setserrno toEINVAL. Ifflags is set to 0, a normal (non-priority)message is sent. If no control part and no data part arespecified, andflags is set to 0, no message is sent,and 0 is returned.
The stream head guarantees that the control part of a message generatedbyputmsg() is at least 64 bytes in length.
Forputpmsg(), the flags are different. Theflags argument is abitmask with the following mutually-exclusive flags defined:MSG_HIPRI andMSG_BAND. Ifflagsis set to 0,putpmsg() fails and setserrno toEINVAL. If acontrol part is specified andflags is set toMSG_HIPRI andbandis set to 0, a high-priority message is sent. Ifflags isset toMSG_HIPRI and either no control part is specified orbandis set to a non-zero value,putpmsg() fails and setserrno toEINVAL. If flags is set toMSG_BAND, then a message is sentin the priority band specified byband. If a control part and datapart are not specified andflags is set toMSG_BAND, no messageis sent and 0 is returned.
Normally,putmsg() will block if the stream write queue is full due to internal flow control conditions. For high-priority messages,putmsg() doesnot block on this condition. For other messages,putmsg() does notblock when the write queue is full andO_NDELAY orO_NONBLOCK isset. Instead, it fails and setserrno toEAGAIN.
Theputmsg() orputpmsg() function also blocks, unless prevented by lack ofinternal resources, waiting for the availability of message blocks in thestream, regardless of priority or whetherO_NDELAY orO_NONBLOCK has been specified.No partial message is sent.
Upon successful completion,0 is returned. Otherwise,-1 is returned anderrnois set to indicate the error.
Theputmsg() andputpmsg() functions will fail if:
A non-priority message was specified, theO_NDELAY orO_NONBLOCK flag is set and the stream write queue is full due to internal flow control conditions.
Thefildes argument is not a valid file descriptor open for writing.
Thectlptr ordataptr argument points to an illegal address.
A signal was caught during the execution of theputmsg() function.
An undefined value was specified inflags;flags is set toRS_HIPRI and no control part was supplied; or the stream referenced byfildes is linked below a multiplexor.
Buffers could not be allocated for the message that was to be created due to insufficient streams memory resources.
Thefildes argument is not associated with a stream.
A hangup condition was generated downstream for the specified stream, or the other end of the pipe is closed.
Thefildes argument refers to a streams-based pipe and the other end of the pipe is closed. ASIGPIPE signal is generated for the calling thread. This error condition occurs only with SUS-conforming applications. Seestandards(5).
The size of the data part of the message does not fall within the range specified by the maximum and minimum packet sizes of the topmost stream module. This value is also returned if the control part of the message is larger than the maximum configured size of the control part of a message, or if the data part of a message is larger than the maximum configured size of the data part of a message.
In addition,putmsg() andputpmsg() will fail if the stream head hadprocessed an asynchronous error before the call. In this case, thevalue oferrno does not reflect the result ofputmsg() orputpmsg()but reflects the prior error.
Theputpmsg() function will fail if:
Theflags argument is set toMSG_HIPRI andband is non-zero.
Seeattributes(5) for descriptions of the following attributes:
|
Intro(2),getmsg(2),poll(2),read(2),write(2),attributes(5),standards(5)
Copyright © 2011, Oracle and/or its affiliates. All rights reserved.Legal Notices |   |