getmsg() fetches the contents of a message located in the read queue of the stream head of a STREAMS file, and writes them to a buffer specified by the user. The message contains either a data section, a control section or both. The data and control sections of the message are written to separate buffers, as described below. The semantics of the sections are defined via the STREAMS module which generated the message.
The getpmsg() function does the same as getmsg(), but it performs a more precise check on the priority of the messages received. Unless otherwise indicated, all information concerning getmsg() also applies to getpmsg().
fildes specifies a file descriptor that points to an open stream.
ctlptr and dataptr each reference an strbuf structure which has the following elements:
int maxlen; /* Maximum buffer size */
int len; /* Length of the data */
char *buf; /* Pointer to the buffer */
buf points to a buffer to which the data or control information is to be written. maxlen denotes the highest possible number of bytes that this buffer can hold. On return, len contains the number of bytes of the data or control information that was actually received, or the value is 0 if the control or data section has a null length, or the value is -1 if a message does not contain any data or control information.
If getmsg() is called, flagsp should reference an integer which indicates the type of message the user can receive. This is described later.
ctlptr is used to receive the control section of the message and dataptr is used to receive the data section. If ctlptr (or dataptr) is zero or the maxlen field is -1, the control (or data) section of the message is not processed and remains in the read queue of the stream head. If ctlptr (or dataptr) is not zero and there is no corresponding control (or data) section of the message in the read queue of the stream head, len is set to -1. If the maxlen field is set to 0 and there is a control (or data) section with a null length, this null-length section is removed from the read queue and len is set to 0. If the maxlen field is set to 0 and there are more than 0 bytes of control (or data) information, this information remains in the read queue and len is set to 0. If the maxlen field in ctlptr or dataptr is smaller than the control or data section of the message, maxlen bytes will be fetched. In this case the remainder of the message is left in the read queue of the stream head and a non-zero return value is supplied (see return value).
By default getmsg() processes the first message available in the read queue. If the integer to which flagsp points is set to RS_HIPRI, the process only receives high-priority messages. In this case, getmsg() only processes the next message if it has high priority. If the integer referenced by flagsp is 0, getmsg() places each available message in the read queue of the stream head. In this case on return, the integer referred to by flagsp is set to RS_HIPRI if a high-priority message was encountered, otherwise it is set to 0.
The options for getpmsg() are different from those for getmsg(). flagsp references a bit mask with the following options, which are mutually exclusive: MSG_HIPRI, MSG_BAND and MSG_ANY. Like getmsg(), getpmsg() processes the next message to become available in the read queue of the stream head. The user in turn can choose to receive only high-priority messages by setting the integer referenced by flagsp to MSG_HIPRI and the integer referenced by bandp to 0. In this case, getpmsg() only processes the next message if it is high-priority. Similarly, the user can call up a message from a special priority range by setting the integer referenced by flagsp to MSG_BAND, and the integer referenced by bandp to the desired priority range. In this case, getpmsg() only processes the next message if it is in a priority range greater than or equal to the integer referenced by bandp, or if it is a high-priority message. If a user only wants to call the first message in the queue, the integer referenced by flagsp should be set to MSG_ANY, and the integer referenced by bandp should be set to 0. If the message received was a high-priority one, on return the integer referenced by flagsp is set to MSG_HIPRI, and the integer referenced by bandp is set to 0. With all other messages the integer referenced by flagsp is set to MSG_BAND, and the integer referenced by bandp is set to the priority range of the message.
If O_NDELAY and O_NONBLOCK were not set, getmsg() and getpmsg() block until there is a message of the type specified by flagsp in the read queue of the stream head. If O_NDELAY or O_NONBLOCK was set and there is no message of the specified type in the read queue, getmsg() and getpmsg() are unsuccessful and errno is set to EAGAIN.
If a stream from which the messages are to be fetched experiences a loss of connection, getmsg() and getpmsg() continue to work normally, as described above, until the read queue is empty. Afterwards, 0 is returned in the len fields of ctlptr and dataptr.
If a message is not fully read with a getmsg() or getpmsg() call, the rest of the message can be fetched with subsequent getmsg() or getpmsg() calls. If, however, a high-priority message arrives in the stream head of the read queue, the next getmsg() or getpmsg() call gives priority to this message before processing the rest of the partial message received previously.
