# getmsg

## PROLOG



           This manual page is part of the POSIX Programmer's Manual.  The
           Linux implementation of this interface may differ (consult the
           corresponding Linux manual page for details of Linux behavior), or
           the interface may not be implemented on Linux.
    


## NAME



           getmsg, getpmsg — receive next message from a STREAMS file
           (**STREAMS**)
    


## SYNOPSIS



           #include <stropts.h>
    
           int getmsg(int _fildes_ , struct strbuf *restrict _ctlptr_ ,
               struct strbuf *restrict _dataptr_ , int *restrict _flagsp_);
           int getpmsg(int _fildes_ , struct strbuf *restrict _ctlptr_ ,
               struct strbuf *restrict _dataptr_ , int *restrict _bandp_ ,
               int *restrict _flagsp_);
    


## DESCRIPTION



           The _getmsg_() function shall retrieve the contents of a message
           located at the head of the STREAM head read queue associated with
           a STREAMS file and place the contents into one or more buffers.
           The message contains either a data part, a control part, or both.
           The data and control parts of the message shall be placed into
           separate buffers, as described below. The semantics of each part
           are defined by the originator of the message.
    
           The _getpmsg_() function shall be equivalent to _getmsg_(), except
           that it provides finer control over the priority of the messages
           received. Except where noted, all requirements on _getmsg_() also
           pertain to _getpmsg_().
    
           The _fildes_ argument specifies a file descriptor referencing a
           STREAMS-based file.
    
           The _ctlptr_ and _dataptr_ arguments each point to a **strbuf** structure,
           in which the _buf_ member points to a buffer in which the data or
           control information is to be placed, and the _maxlen_ member
           indicates the maximum number of bytes this buffer can hold. On
           return, the _len_ member shall contain the number of bytes of data
           or control information actually received. The _len_ member shall be
           set to 0 if there is a zero-length control or data part and _len_
           shall be set to -1 if no data or control information is present in
           the message.
    
           When _getmsg_() is called, _flagsp_ should point to an integer that
           indicates the type of message the process is able to receive. This
           is described further below.
    
           The _ctlptr_ argument is used to hold the control part of the
           message, and _dataptr_ is used to hold the data part of the message.
           If _ctlptr_ (or _dataptr_) is a null pointer or the _maxlen_ member is
           -1, the control (or data) part of the message shall not be
           processed and shall be left on the STREAM head read queue, and if
           the _ctlptr_ (or _dataptr_) is not a null pointer, _len_ shall be set to
           -1. If the _maxlen_ member is set to 0 and there is a zero-length
           control (or data) part, that zero-length part shall be removed
           from the read queue and _len_ shall be set to 0. If the _maxlen_
           member is set to 0 and there are more than 0 bytes of control (or
           data) information, that information shall be left on the read
           queue and _len_ shall be set to 0. If the _maxlen_ member in _ctlptr_
           (or _dataptr_) is less than the control (or data) part of the
           message, _maxlen_ bytes shall be retrieved. In this case, the
           remainder of the message shall be left on the STREAM head read
           queue and a non-zero return value shall be provided.
    
           By default, _getmsg_() shall process the first available message on
           the STREAM head read queue. However, a process may choose to
           retrieve only high-priority messages by setting the integer
           pointed to by _flagsp_ to RS_HIPRI. In this case, _getmsg_() shall
           only process the next message if it is a high-priority message.
           When the integer pointed to by _flagsp_ is 0, any available message
           shall be retrieved. In this case, on return, the integer pointed
           to by _flagsp_ shall be set to RS_HIPRI if a high-priority message
           was retrieved, or 0 otherwise.
    
           For _getpmsg_(), the flags are different. The _flagsp_ argument points
           to a bitmask with the following mutually-exclusive flags defined:
           MSG_HIPRI, MSG_BAND, and MSG_ANY.  Like _getmsg_(), _getpmsg_() shall
           process the first available message on the STREAM head read queue.
           A process may choose to retrieve only high-priority messages by
           setting the integer pointed to by _flagsp_ to MSG_HIPRI and the
           integer pointed to by _bandp_ to 0. In this case, _getpmsg_() shall
           only process the next message if it is a high-priority message.
           In a similar manner, a process may choose to retrieve a message
           from a particular priority band by setting the integer pointed to
           by _flagsp_ to MSG_BAND and the integer pointed to by _bandp_ to the
           priority band of interest. In this case, _getpmsg_() shall only
           process the next message if it is in a priority band equal to, or
           greater than, the integer pointed to by _bandp_ , or if it is a high-
           priority message. If a process wants to get the first message off
           the queue, the integer pointed to by _flagsp_ should be set to
           MSG_ANY and the integer pointed to by _bandp_ should be set to 0. On
           return, if the message retrieved was a high-priority message, the
           integer pointed to by _flagsp_ shall be set to MSG_HIPRI and the
           integer pointed to by _bandp_ shall be set to 0. Otherwise, the
           integer pointed to by _flagsp_ shall be set to MSG_BAND and the
           integer pointed to by _bandp_ shall be set to the priority band of
           the message.
    
           If O_NONBLOCK is not set, _getmsg_() and _getpmsg_() shall block until
           a message of the type specified by _flagsp_ is available at the
           front of the STREAM head read queue. If O_NONBLOCK is set and a
           message of the specified type is not present at the front of the
           read queue, _getmsg_() and _getpmsg_() shall fail and set _errno_ to
           **[EAGAIN]**.
    
           If a hangup occurs on the STREAM from which messages are
           retrieved, _getmsg_() and _getpmsg_() shall continue to operate
           normally, as described above, until the STREAM head read queue is
           empty. Thereafter, they shall return 0 in the _len_ members of
           _ctlptr_ and _dataptr_.
    


## RETURN VALUE



           Upon successful completion, _getmsg_() and _getpmsg_() shall return a
           non-negative value. 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 the bitwise-logical OR of MORECTL and MOREDATA
           indicates that both types of information remain. Subsequent
           _getmsg_() and _getpmsg_() calls shall retrieve the remainder of the
           message. However, if a message of higher priority has come in on
           the STREAM head read queue, the next call to _getmsg_() or _getpmsg_()
           shall retrieve that higher-priority message before retrieving the
           remainder of the previous message.
    
           If the high priority control part of the message is consumed, the
           message shall be placed back on the queue as a normal message of
           band 0. Subsequent _getmsg_() and _getpmsg_() calls shall retrieve the
           remainder of the message. If, however, a priority message arrives
           or already exists on the STREAM head, the subsequent call to
           _getmsg_() or _getpmsg_() shall retrieve the higher-priority message
           before retrieving the remainder of the message that was put back.
    
           Upon failure, _getmsg_() and _getpmsg_() shall return -1 and set _errno_
           to indicate the error.
    


## ERRORS



           The _getmsg_() and _getpmsg_() functions shall fail if:
    
           **EAGAIN** The O_NONBLOCK flag is set and no messages are available.
    
           **EBADF** The _fildes_ argument is not a valid file descriptor open for
                  reading.
    
           **EBADMSG**
                  The queued message to be read is not valid for _getmsg_() or
                  _getpmsg_() or a pending file descriptor is at the STREAM
                  head.
    
           **EINTR** A signal was caught during _getmsg_() or _getpmsg_().
    
           **EINVAL** An illegal value was specified by _flagsp_ , or the STREAM or
                  multiplexer referenced by _fildes_ is linked (directly or
                  indirectly) downstream from a multiplexer.
    
           **ENOSTR** A STREAM is not associated with _fildes_.
    
           In addition, _getmsg_() and _getpmsg_() shall fail if the STREAM head
           had processed an asynchronous error before the call. In this case,
           the value of _errno_ does not reflect the result of _getmsg_() or
           _getpmsg_() but reflects the prior error.
    
           _The following sections are informative._
    


## EXAMPLES



       **Getting Any Message**
           In the following example, the value of _fd_ is assumed to refer to
           an open STREAMS file. The call to _getmsg_() retrieves any available
           message on the associated STREAM-head read queue, returning
           control and data information to the buffers pointed to by _ctrlbuf_
           and _databuf_ , respectively.
    
               #include <stropts.h>
               ...
               int fd;
               char ctrlbuf[128];
               char databuf[512];
               struct strbuf ctrl;
               struct strbuf data;
               int flags = 0;
               int ret;
    
               ctrl.buf = ctrlbuf;
               ctrl.maxlen = sizeof(ctrlbuf);
    
               data.buf = databuf;
               data.maxlen = sizeof(databuf);
    
               ret = getmsg (fd, &ctrl, &data, &flags);
    
       **Getting the First Message off the Queue**
           In the following example, the call to _getpmsg_() retrieves the
           first available message on the associated STREAM-head read queue.
    
               #include <stropts.h>
               ...
    
               int fd;
               char ctrlbuf[128];
               char databuf[512];
               struct strbuf ctrl;
               struct strbuf data;
               int band = 0;
               int flags = MSG_ANY;
               int ret;
    
               ctrl.buf = ctrlbuf;
               ctrl.maxlen = sizeof(ctrlbuf);
    
               data.buf = databuf;
               data.maxlen = sizeof(databuf);
    
               ret = getpmsg (fd, &ctrl, &data, &band, &flags);
    


## APPLICATION USAGE



           None.
    


## RATIONALE



           None.
    


## FUTURE DIRECTIONS



           The _getmsg_() and _getpmsg_() functions may be removed in a future
           version.
    


* * *