GETMSG(2-SysV)      RISC/os Reference Manual       GETMSG(2-SysV)



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 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 max-
     imum 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 con-
     trol (or data) information, that information is left on the



                         Printed 1/15/91                   Page 1

GETMSG(2-SysV)      RISC/os Reference Manual       GETMSG(2-SysV)



     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 non-zero return value is pro-
     vided, as described below under DIAGNOSTICS. 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 mes-
     sages by setting flags to RS_HIPRI.  In this case, getmsg
     will only process the next message if it is a priority mes-
     sage.

     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 read-
               ing.

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

     [ENOSTR]  A stream is not associated with fd.





 Page 2                  Printed 1/15/91

GETMSG(2-SysV)      RISC/os Reference Manual       GETMSG(2-SysV)



     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).
     STREAMS Primer
     STREAMS Programmer's Guide

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.




































                         Printed 1/15/91                   Page 3