*** UNIX MANUAL PAGE BROWSER ***

putmsg(2) System Calls Manual putmsg(2) NAME putmsg, putpmsg - Send a message on a Stream LIBRARY Standard C Library (libc.so, libc.a) SYNOPSIS #include <stropts.h> int putmsg( int fd, const struct strbuf *ctlbuf, const struct strbuf *databuf, int flags); int putpmsg( int fd, const struct strbuf *ctlbuf, const struct strbuf *databuf, int band, int flags); STANDARDS Interfaces documented on this reference page conform to industry stan- dards as follows: putmsg(): XPG4-UNIX putpmsg(): XPG4-UNIX Refer to the standards(5) reference page for more information about in- dustry standards and associated tags. PARAMETERS Specifies a file descriptor that references an open Stream. Points to a strbuf structure that describes the control part, if any, of the mes- sage. This strbuf structure is described in the DESCRIPTION section. Points to a strbuf structure that holds the data part, if any, of the message. This strbuf structure is described in the DESCRIPTION section. Specifies the priority band. Specifies the type of message that should be sent. DESCRIPTION The putmsg() and putpmsg() functions send messages to the STREAMS file. These messages are generated from user-provided buffer(s), and must contain a control part and/or a data part. The open Stream specifies the format and semantics of the message's control and data parts. The control and data parts of the message are placed into separate buffers, pointed at by cltbuf and databuf respectively. The putpmsg() function provides more control over how messages are sent. With this function, you can send messages in different priority bands. Except where speci- fied, all information that applies to the putmsg() function also ap- plies to the putpmsg() function. The ctlbuf and databuf parameters each point to a strbuf structure that contains three members. This structure is defined in <sys/stropts.h> as: struct strbuf { int maxlen; /* max buffer length */ int len; /* length of data */ char *buf /* pointer to buffer */ }; The members are: Speci- fies the maximum number of bytes buf can hold. This field is not used by either the putmsg() or putpmsg() function. Points to the buffer where the control information is to reside. Specifies the number of bytes to be sent. A message can contain a control part or a data part, or both, depending on what is to be sent. To send one or the other, the corresponding ctlbuf or databuf parameter must be a non-null pointer and the len field of the corresponding strbuf structure must have a value of 0 (zero) or greater. A data or control part is not sent if its respec- tive databuf or ctlbuf parameter is a null pointer, or if the corre- sponding structure's len field is set to -1. One of the major differences between the putmsg() and putpmsg() func- tion, in addition to the band parameter, is how the flag parameter is used to send messages. The putmsg() function sends messages as fol- lows: If you set the flags parameter to a value of 0 (zero), a normal message (priority band equal to 0 (zero)) is sent. If you set the flags parameter to RS_HIPRI and a control part is specified, the con- trol and data (if present) is sent as a high priority message. If you set the flags parameter to RS_HIPRI and a control part is not speci- fied, putmsg() fails. If you set the flags parameter to 0 (zero) and both the control part and the data part of not specified, no message is sent and a value of 0 (zero) is returned. The putpmsg() function flags parameter is a bitmask with the mutually exclusive flags MSG_HIPRI and MSG_BAND defined. The putpmsg() function sends messages as follows: If you set flags to MSG_BAND, the control and/or data part is sent on the priority band specified by the band pa- rameter. If you set the flags parameter to MSG_HIPRI, set the band pa- rameter to 0 (zero), and specify a control part, the control and data (if present) is sent as a high-priority message. If you set the flags parameter to MSG_HIPRI, and either no control part is specified or band is set to a non-zero value, the putpmsg() function fails. If you set flags to MSG_BAND, and both a control part and data are not specified, no message is sent and a value of 0 (zero) is returned. If you set the flags parameter to 0 (zero), putpmsg() fails. Unless the message is a high priority one, the putmsg() function gener- ally blocks if the Stream write queue is full. This is because of in- ternal flow control conditions. The putmsg() function does not block on this condition for high priority messages. However, for other mes- sages, if the O_NDELAY or O_NONBLOCK flag is set for the write() opera- tion, the putmsg() function will not block when the write queue is full. Instead, it fails. In addition, unless the system runs out of internal resources, the putmsg() function will block while waiting for the availability of mes- sage blocks in the Stream. In this instance, neither the message pri- ority nor the assertion of the O_NDELAY or O_NONBLOCK flag matter. Partial messages are not sent. [Digital] Current industry standards do not define the O_NDELAY flag. It is included in the preceding paragraphs for System V compatibility. NOTES [Digital] When compiled in the X/Open UNIX environment, calls to the putmsg() and putpmsg() functions are internally renamed by prepending _E to the function name. When you are debugging a module that includes the putmsg() or putpmsg() function and for which _XOPEN_SOURCE_EXTENDED has been defined, use _Eputmsg to refer to the putmsg() call, and _Eputpmsg to refer to the putpmsg() call. See standards(5) for further information. RETURN VALUES Upon successful completion, the putmsg() functions return a value of 0 (zero). Otherwise, they return a value of -1 and errno is set to indi- cate an error. ERRORS The putmsg() function fails if the Stream head has processed a STREAM error message before either of these functions is called. In this in- stance, the STREAMS error message contains the value of the returned error. In addition, if any of the following conditions occurs, the putmsg() function sets errno to the corresponding value. For a non-priority message, the O_NDELAY or the O_NONBLOCK flag is set, and the Stream write queue is determined to be full because of the internal flow con- trol conditions. [Digital] Current industry standards do not define the O_NDELAY flag. It is included in the preceding paragraphs for System V compatibility. The system could not allocate buffers for the message to be cre- ated. The fd parameter is not invalid for writing. The putmsg() function was interrupted by a signal that was caught. An undefined message was specified in the flags parameter. For the putmsg() function, the flags parameter is RS_HIPRI or MSG_HIPRI, and the ctlbuf len parameter is less than 0 (zero). For the putpmsg() function, the flags parameter is MSG_HIPRI and the ctlbuf len parameter is less than 0 (zero) [Digital] For the putpmsg() function, the flags parameter is MSG_HIPRI and the band parameter is not 0 (zero); or the flags parameter is MSG_BAND and the band parameter is greater than the system minimum. The Stream specified by the fd parameter is linked under a mul- tiplexor. The system could not allocate buffers for the message that was to be created because of insufficient Streams memory resources. A Stream is not associated with the fd parameter. The other end of a Streams-based piped referred to by the fd pa- rameter is closed. A SIGPIPE signal is generated for the call- ing process. A hangup condition for the specified Stream was generated downstream. The size of the control part of a message is larger than the maximum configured size of the message's con- trol part; or the data part of a message is larger than the max- imum configured size of the message's data part; or the data part size of the message does not conform to the range indicated by the maximum and minimum packet sizes of the topmost Stream module. RELATED INFORMATION Functions: getmsg(2), poll(2), read(2), write(2) Interfaces: streamio(7) Standards: standards(5) delim off putmsg(2)