getmsg(S)                      6 January 1993                      getmsg(S)


 Name

    getmsg - get next message off a stream

 Syntax


    cc  . . .  -lc


    #include  <sys/stropts.h>

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


 Description

    The getmsg system call retrieves the contents of a message 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.

    The fd argument specifies a file descriptor referencing an open stream.
    ctrlptr and dataptr each point to a strbuf structure which contains the
    following members:

               int maxlen;       /* maximum buffer length */
               int len;          /* length of data        */
               char *buf;        /* ptr to buffer         */

    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 RSHIPRI and
    is used  as described below.

    The ctrlptr argument is used to hold the control part from the message
    and dataptr is used to hold the data part from the message.  If ctrlptr
    (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 ctrlptr 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
    non-zero return value is provided, as described  below under ``Diagnos-
    tics''.  If information is retrieved from a priority message, flags is
    set to RSHIPRI on return.

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

    If ONONBLOCK 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 ONONBLOCK 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 continues to operate normally, as described above, until the
    stream head read queue is empty.  Thereafter, it returns 0 in the len
    fields of ctrlptr and dataptr.

    The getmsg system call fails if one or more of the following is true:

    [EAGAIN]     The ONONBLOCK 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]     ctrlptr, 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 multiplexer.

    [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.

 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 retrieves the remainder
    of the message.

 See also

    Intro(S), read(S), poll(S), putmsg(S), write(S)

 Standards conformance

    getmsg is conformant with:
    AT&T SVID Issue 2.