*** UNIX MANUAL PAGE BROWSER ***

getmsg(2) System Calls Manual getmsg(2) NAME getmsg, getpmsg - Receives the next message from a Stream LIBRARY Standard C Library (libc.so, libc.a) SYNOPSIS #include <stropts.h> int getmsg( int fd, struct strbuf *ctlptr, struct strbuf *dataptr, long *flags); int getpmsg( int fd, struct strbuf *ctlptr, struct str- buf *dataptr, int *band, long *flags); STANDARDS Interfaces documented on this reference page conform to industry stan- dards as follows: getmsg(): XPG4-UNIX getpmsg(): 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 holds the control part of the message. This strbuf structure is described in the DESCRIPTION section. Points to a strbuf structure that holds the data part of the message. This strbuf structure is described in the DESCRIPTION section. Points to an inte- ger that indicates the priority band of the message that the user is able to retrieve. Points to an integer that indicates the type of mes- sage the user is able to retrieve. DESCRIPTION The getmsg() and getpmsg() functions retrieve the contents of messages. These messages are located at the Stream head read queue associated with a STREAMS file. Messages must contain a control part or a data part, or both. The control and data parts of the message are placed into separate user-specified buffers, pointed at by ctlptr and dataptr respectively. The open Stream specifies the format and semantics of the message's control and data parts. The getpmsg() function provides better control over the priority of the messages received. Except where specified, all information about the getmsg() function also ap- plies to the getpmsg() function. The ctlptr and dataptr parameters each point to a strbuf structure that contains three members. This structure is defined in <sys/stropts.h> as: struct strbuf { int maxlen; /* maximum buffer length */ int len; /* length of data */ char *buf /* ptr to buffer */ }; The members are: Specifies the maximum number of bytes buf can hold. Points to the buffer where the control or data information is to reside. On return, contains the num- ber of bytes of control or data information that has actually been re- ceived. The len parameter is set to 0 (zero) if there is a zero-length data or control part; otherwise, len is set to -1 if no control or data information is contained in the message. The members of this structure are also affected by the following. If the maxlen field is set to 0 (zero), and the control or data part is of zero-length, that zero-length part is deleted from the read queue of the Stream head, and len is set to 0 (zero). If the maxlen field is set to 0 (zero), and if the size of the control or data part is greater than 0 (zero), that part remains on the read queue and len is set to 0 (zero). If the maxlen field for either the ctlptr or dataptr structure is less than the size of the control or data part of the message, maxlen bytes are retrieved and the rest of the message remains on the Stream head read queue. A nonzero value is then returned. If the maxlen member is -1, or if ctlptr or dataptr parameter is a null pointer, the getmsg() function does not process the control or the data part of the message. The unprocessed part(s) then remains on the Stream head queue. If ctlptr or dataptr is not a null pointer, and if the read queue at the Stream head has no corresponding message control or data part, len is set to -1. One of the major differences between the getmsg() and getpmsg() func- tions, in addition to the band parameter, is how the flags parameter is used to collect messages. The getmsg() function processes messages as follows: By default, the getmsg() function processes the first message that is available on the Stream head queue. If you set the flags para- meter to 0 (zero), any message will be retrieved. On return, the inte- ger pointed to by the flags parameter will be set to RS_HIPRI if a high-priority message was retrieved; otherwise, a value of 0 (zero) is returned. If you set the flags parameter to RS_HIPRI, the getmsg() function retrieves only the high-priority messages. The getmsg() func- tion then only processes the next message if it is a high-priority mes- sage. The getpmsg() function flags parameter points to a bitmask with the mu- tually-exclusive flags MSG_HIPRI, MSG_BAND, and MSG_ANY defined. The getpmsg() function processes messages as follows: By default, the getpmsg() function processes the first available message on the Stream head read queue. If you set the integer pointed at by the flags para- meter to MSG_HIPRI, and set the integer pointed to by the band parame- ter to 0 (zero), the getpmsg() function retrieves only high-priority messages. The getpmsg() function then only processes the next message if it is a high-priority message. If you set the integer pointed to by the flags parameter to MSG_BAND, and set the integer pointed to by the band parameter to the desired priority band, the getpmsg() function re- trieves a message from that band. The getpmsg() function then only processes the next message if it is in a high-priority message, or if its priority band is at least equal to the integer pointed to by band. If you set the integer pointed to by the flags parameter to MSG_ANY, and set the integer pointed to by the band parameter to 0 (zero), the getpmsg() function retrieves only the first message off the queue. When the getpmsg() function returns, it then sets the flags and band parameters according to the type of message that was retrieved. If the message was not a high-priority one, the integer pointed to by the flags parameter is set to MSG_BAND and the integer pointed to by band is set to the band of the message. If the message was a high-priority one, the integer pointed to by the flags is set to MSG_HIPRI and the integer pointed to by band will be set to 0 (zero). If the O_NDELAY or O_NONBLOCK flags are set and a message of the speci- fied type is not present at the front of the read queue, the getmsg() function fails. If the O_NDELAY or O_NONBLOCK flags are not set for the read() operation, the getmsg() function blocks until a message is available at the front of the Stream head read queue. This message's type is specified by flags. [Digital] Current industry standards do not define the O_NDELAY flag. It is included in the preceding paragraphs for System V compatibility. If the Stream from which the messages are being retrieved experiences a hangup, the getmsg() function does not fail. Instead, it will contin- ues as usual until the read queue of the Stream head is empty. Subse- quent calls will return a value of 0 (zero) in the len fields for the ctlptr and dataptr structures. RETURN VALUES Upon successful completion, the getmsg() and getmsg() functions return nonnegative values, as follows: Indicates that a full message was suc- cessfully read. Indicates that more control information is waiting for retrieval. Indicates that more data is waiting for retrieval. Indi- cates that both types of information remain. Later calls to getmsg() then retrieve the rest of the message. Note, however, that higher-pri- ority messages, although they may arrive later on the queue, take a higher precedence. In other words, if a message comes in later on the read queue, the next call to the getmsg() function retrieves that higher-priority message first. The rest of the earlier partial message is retrieved afterwards. Upon failure, the getmsg() function returns a value of -1, and sets er- rno to indicate an error. ERRORS Both the getmsg() and getpmsg() functions fail if a STREAMS error mes- sage is delivered to the Stream head read queue before the call. In this instance, the STREAMS error message contains the value of the re- turned error. In addition, if any of the following conditions occurs, the getmsg() function sets errno to the corresponding value: The O_NDELAY or O_NON- BLOCK flag is set, and no messages are currently available. [Digital] Current industry standards do not define the O_NDELAY flag. It is included in the preceding paragraph for System V compatibility. An illegal address has been specified in ctlptr or dataptr. The fd parameter is not a valid file descriptor open for reading. The message on the read queue is not a con- trol or data message, or a file descriptor is pending at the Stream head. The getmsg() or getpmsg() function was interrupted by a signal that was caught. An illegal value was specified by the flags parameter, or the Stream referenced by fd is linked under a multiplexor. A Stream is not associated with the fd pa- rameter. RELATED INFORMATION Interfaces: streamio(7). Functions: poll(2), putmsg(2), read(2), write(2). Standards: standards(5) delim off getmsg(2)