getmsg()" -- System Call (libc)" "

#include <stropts.h>
iinntt ggeettmmssgg ((_f_d,, _c_t_l_p_t_r,, _d_a_t_a_p_t_r,, _f_l_a_g_s_p))
iinntt _f_d;; ssttrruucctt ssttrrbbuuff **_c_t_l_p_t_r,, _d_a_t_a_p_t_r;; iinntt **_f_l_a_g_s_p;;

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:

+o

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.

+o

If ctlptr or dataptr is not NULL, but the message does not have a corresponding part, getmsg() sets len to -1.

+o

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.

+o

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

+o

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.

+o

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.

+o

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 ooppeenn(())), 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.

Return Values

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

+o

Either of the flags O_NDELAY or O_NONBLOCK is set but no message is available. getmsg() sets errno to EAGAIN.

+o

fd is not a valid file descriptor. getmsg() sets errno to EBADF.

+o

The next message in the read queue is not valie for getmsg() to read. getmsg() sets errno to EBADMSG.

+o

ctlptr, dataptr, or flagsp contains an illegal address. getmsg() sets errno to EFAULT.

+o

A signal was caught as getmsg() was executing. getmsg() sets errno to EINTR.

+o

flagsp holds an unrecognized value, or the stream referenced by fd is linked under a multiplexor. getmsg() sets errno to EINVAL.

+o

fd does not describe a stream. getmsg() sets errno to ENOSTR.

See Also

• libc,
• putmsg(),
• STREAMS,
• stropts.h