COHERENT manpages
This page displays the COHERENT manpage for getmsg() [Get the next message from a stream].
List of available manpages
Index
getmsg() -- System Call (libc) Get the next message from a stream #include <stropts.h> int getmsg (fd, ctlptr, dataptr, flagsp) int fd; struct strbuf *ctlptr, dataptr; int *flagsp; getmsg() retrieves a message from a STREAMS file, and writes it into the buffer or buffers that you specify. The message must contain a data part, a control part, or both. getmsg() writes each part into its own buffer, as described below. The STREAMS module that generated the message defines the semantics of each part. fd gives the file descriptor that references the stream whose message is being retrieved. ctlptr and dataptr each point to a structure of type strbuf, which contains the following members: int maxlen; Maximum buffer length int len; Length of data void *buf; Pointer to buffer ctlptr holds the message's control part, and dataptr its data part. buf points to the buffer into which the data or control information is to be written, and maxlen gives the maximum number of bytes the buffer can hold. getmsg() initializes len to the number of bytes of data or control information that it actually wrote into buf. It sets len to zero if the part in question has a length of zero; and it sets len to -1 if the message does not contain the part in question. flagsp points to an integer that indicates the type of messages you can receive; this is discussed in detail below. getmsg() has special behaviors, corresponding to the settings of ctlptr and dataptr, and of the structures to which they point: -> If either ctlptr or dataptr is NULL, or if maxlen equals -1, getmsg() does not process the corresponding part of the message. The message is left on the stream head's read queue. -> If ctlptr or dataptr is not NULL, but the message does not have a corresponding part, getmsg() sets len to -1. -> If maxlen equals zero and there is a zero-length control or data part, getmsg() removes the zero-length part from the read queue and sets len to zero If maxlen equals zero and the corresponding section contains more than zero bytes of information, getmsg() leaves that information on the read queue and sets len to zero. -> If maxlen is less than than the corresponding part of the message (the control part for ctlptr and the data part for dataptr), getmsg() retrieves maxlen bytes. It leaves the remainder of the message on the stream head's read queue and returns and a non-zero return value. Details are given below. Flags The following summarizes what flags are available, and what they mean. -> By default, getmsg() processes the first available message on the stream head's read queue. However, you can choose to retrieve only a high- priority message: just insert RS_HIPRI into the integer to which flagsp points. In this case, getmsg() processes the next message only if it is a high-priority message. -> If the integer to which flagsp points equals zero, getmsg() retrieves any message available on the stream head's read queue. In this case, if getmsg() retrieves a high-priority message, it sets to the integer to which flagsp points to RS_HIPRI; if the message does not have high priority, it sets that integer to zero. -> If flags O_NDELAY and O_NONBLOCK are not set as part of the global settings for fd (for details, see the Lexicon entry for open()), getmsg() blocks execution of your program until a message of the type specified by flagsp is available on the stream head's read queue. If either O_NDELAY or O_NONBLOCK has been set and a message of the specified type is not at the top of the queue, getmsg() fails and sets errno to EAGAIN. If a hangup occurs on the stream from which messages are to be retrieved, getmsg() operates normally until the stream head's read queue is empty. Thereafter, it returns zero in the len fields of both ctlptr and dataptr. Return Values If all goes well, getmsg() returns a non-negative value. Zero indicates that a full message was read successfully. MORECTL and MOREDATA indicate, respectively, that more control information or more data are awaiting retrieval; whereas MORECTL | MOREDATA indicates that more of both types information remain in the queue, to be retrieved by subsequent calls to getmsg(). However, if a message of higher priority has come into the stream head's read queue, the next call to getmsg() retrieves that higher-priority message and the information remaining from the partially retrieved message remains on the queue. Errors getmsg() fails if any of the following conditions are true: -> Either of the flags O_NDELAY or O_NONBLOCK is set but no message is available. getmsg() sets errno to EAGAIN. -> fd is not a valid file descriptor. getmsg() sets errno to EBADF. -> The next message in the read queue is not valie for getmsg() to read. getmsg() sets errno to EBADMSG. -> ctlptr, dataptr, or flagsp contains an illegal address. getmsg() sets errno to EFAULT. -> A signal was caught as getmsg() was executing. getmsg() sets errno to EINTR. -> flagsp holds an unrecognized value, or the stream referenced by fd is linked under a multiplexor. getmsg() sets errno to EINVAL. -> fd does not describe a stream. getmsg() sets errno to ENOSTR. getmsg() also fails if the stream header receives a STREAMS error message before getmsg() tries to read it. getmsg() then returns the value in the STREAMS error message. See Also libc, putmsg(), STREAMS, stropts.h