GETMSG(2)                            SysV                            GETMSG(2)



NAME
     getmsg - get next message off a Stream

SYNOPSIS
     #include <stropts.h>

     int getmsg(fd, ctlptr, dataptr, flags)
     int fd;
     struct strbuf *ctlptr;
     struct strbuf *dataptr;
     int *flags;

DESCRIPTION
     getmsg retrieves the contents of a message (see intro(2)) located at the
     Stream head read queue from a STREAMS file and places the contents into
     user-specified buffer(s).  The message must contain either a data part, a
     control part, or both.  The data and control parts of the message are
     placed into separate buffers, as described below.  The semantics of each
     part is defined by the STREAMS module that generated the message.

     fd specifies a file descriptor referencing an open Stream.  ctlptr and
     dataptr each point to a strbuf structure that contains the following
     members:

          struct strbuf {
               int  maxlen;   /* no. of bytes in buffer */
               int  len; /* no. of bytes returned */
               char *buf;     /* pointer to data */
          };

     where buf points to a buffer in which the data or control information is
     to be placed, and maxlen indicates the maximum number of bytes this
     buffer can hold.  On return, len contains the number of bytes of data or
     control information actually received, or is 0 if there is a zero-length
     control or data part, or is -1 if no data or control information is
     present in the message.  flags may be set to the values 0 or RS_HIPRI and
     is used  as described below.

     ctlptr is used to hold the control part from the message, and dataptr is
     used to hold the data part from the message.  If ctlptr (or dataptr) is
     NULL or the maxlen field is -1, the control (or data) part of the message
     is not processed and is left on the Stream head read queue and len is set
     to -1.  If the maxlen field is set to 0 and there is a zero-length
     control (or data) part, that zero-length part 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 zero bytes of control (or data) information, that information
     is left on the read queue and len is set to 0.  If the maxlen field in
     ctlptr or dataptr is less than, respectively, the control or data part of
     the message, maxlen bytes are retrieved.  In this case, the remainder of
     the message is left on the Stream head read queue and a nonzero return
     value is provided, as described under "RETURN VALUE." If information is
     retrieved from a priority message, flags is set to RS_HIPRI on return.

     By default, getmsg processes the first priority or non-priority message
     available on the Stream head read queue.  However, a user may choose to
     retrieve only priority messages by setting flags to RS_HIPRI.  In this
     case, getmsg will only process the next message if it is a priority
     message.

     If O_NDELAY has not been set, getmsg blocks until a message, of the
     type(s) specified by flags (priority or either), is available on the

     Stream head read queue.  If O_NDELAY has been set and a message of the
     specified type(s) is not present on the read queue, getmsg fails and sets
     errno to EAGAIN.

     If a hangup occurs on the Stream from which messages are to be retrieved,
     getmsg will continue to operate normally, as described above, until the
     Stream head read queue is empty.  Thereafter, it will return 0 in the len
     fields of ctlptr and dataptr.

ERRORS
     getmsg fails if one or more of the following are true:

     [EAGAIN]    The O_NDELAY flag is set, and no messages are available.

     [EBADF]     fd is not a valid file descriptor open for reading.

     [EBADMSG]   Queued message to be read is not valid for getmsg.

     [EFAULT]    ctlptr, dataptr, or flags points to a location outside the
                 allocated address space.

     [EINTR]     A signal was caught during the getmsg system call.

     [EINVAL]    An illegal value was specified in flags, or the Stream
                 referenced by fd is linked under a multiplexor.

     [ENOSTR]    A Stream is not associated with fd.

     A getmsg can also fail if a STREAMS error message had been received at
     the Stream head before the call to getmsg.  The error returned is the
     value contained in the STREAMS error message.

SEE ALSO
     intro(2), read(2), poll(2), putmsg(2), write(2).
     Getting Started with SysV STREAMS, Programming with SysV STREAMS.

DIAGNOSTICS
     Upon successful completion, a non-negative value is returned.  A value of
     0 indicates that a full message was read successfully.  A return value of
     MORECTL indicates that more control information is waiting for retrieval.
     A return value of MOREDATA indicates that more data is waiting for
     retrieval.  A return value of MORECTL|MOREDATA indicates that both types
     of information remain.  Subsequent getmsg calls will retrieve the
     remainder of the message.