GETMSG(3)                  POSIX Programmer's Manual                 GETMSG(3)



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

NNAAMMEE
       getmsg, getpmsg -- receive next message from a STREAMS file (SSTTRREEAAMMSS)

SSYYNNOOPPSSIISS
       #include <stropts.h>

       int getmsg(int _f_i_l_d_e_s, struct strbuf *restrict _c_t_l_p_t_r,
           struct strbuf *restrict _d_a_t_a_p_t_r, int *restrict _f_l_a_g_s_p);
       int getpmsg(int _f_i_l_d_e_s, struct strbuf *restrict _c_t_l_p_t_r,
           struct strbuf *restrict _d_a_t_a_p_t_r, int *restrict _b_a_n_d_p,
           int *restrict _f_l_a_g_s_p);

DDEESSCCRRIIPPTTIIOONN
       The _g_e_t_m_s_g() 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 _g_e_t_p_m_s_g() function shall be equivalent to _g_e_t_m_s_g(), except that it
       provides finer control over the priority of the messages received.
       Except where noted, all requirements on _g_e_t_m_s_g() also pertain to
       _g_e_t_p_m_s_g().

       The _f_i_l_d_e_s argument specifies a file descriptor referencing a STREAMS-
       based file.

       The _c_t_l_p_t_r and _d_a_t_a_p_t_r arguments each point to a ssttrrbbuuff structure, in
       which the _b_u_f member points to a buffer in which the data or control
       information is to be placed, and the _m_a_x_l_e_n member indicates the
       maximum number of bytes this buffer can hold. On return, the _l_e_n member
       shall contain the number of bytes of data or control information
       actually received. The _l_e_n member shall be set to 0 if there is a zero-
       length control or data part and _l_e_n shall be set to -1 if no data or
       control information is present in the message.

       When _g_e_t_m_s_g() is called, _f_l_a_g_s_p should point to an integer that
       indicates the type of message the process is able to receive. This is
       described further below.

       The _c_t_l_p_t_r argument is used to hold the control part of the message,
       and _d_a_t_a_p_t_r is used to hold the data part of the message. If _c_t_l_p_t_r (or
       _d_a_t_a_p_t_r) is a null pointer or the _m_a_x_l_e_n 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 _c_t_l_p_t_r (or _d_a_t_a_p_t_r) is not a
       null pointer, _l_e_n shall be set to -1. If the _m_a_x_l_e_n 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 _l_e_n shall be set to 0. If
       the _m_a_x_l_e_n 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 _l_e_n shall be set to 0. If the _m_a_x_l_e_n member in _c_t_l_p_t_r
       (or _d_a_t_a_p_t_r) is less than the control (or data) part of the message,
       _m_a_x_l_e_n 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, _g_e_t_m_s_g() 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 _f_l_a_g_s_p to
       RS_HIPRI. In this case, _g_e_t_m_s_g() shall only process the next message if
       it is a high-priority message.  When the integer pointed to by _f_l_a_g_s_p
       is 0, any available message shall be retrieved. In this case, on
       return, the integer pointed to by _f_l_a_g_s_p shall be set to RS_HIPRI if a
       high-priority message was retrieved, or 0 otherwise.

       For _g_e_t_p_m_s_g(), the flags are different. The _f_l_a_g_s_p argument points to a
       bitmask with the following mutually-exclusive flags defined: MSG_HIPRI,
       MSG_BAND, and MSG_ANY.  Like _g_e_t_m_s_g(), _g_e_t_p_m_s_g() 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 _f_l_a_g_s_p to MSG_HIPRI and the integer pointed to by _b_a_n_d_p
       to 0. In this case, _g_e_t_p_m_s_g() 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 _f_l_a_g_s_p to MSG_BAND and the integer pointed to by
       _b_a_n_d_p to the priority band of interest. In this case, _g_e_t_p_m_s_g() shall
       only process the next message if it is in a priority band equal to, or
       greater than, the integer pointed to by _b_a_n_d_p, 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 _f_l_a_g_s_p should be set to MSG_ANY and
       the integer pointed to by _b_a_n_d_p should be set to 0. On return, if the
       message retrieved was a high-priority message, the integer pointed to
       by _f_l_a_g_s_p shall be set to MSG_HIPRI and the integer pointed to by _b_a_n_d_p
       shall be set to 0. Otherwise, the integer pointed to by _f_l_a_g_s_p shall be
       set to MSG_BAND and the integer pointed to by _b_a_n_d_p shall be set to the
       priority band of the message.

       If O_NONBLOCK is not set, _g_e_t_m_s_g() and _g_e_t_p_m_s_g() shall block until a
       message of the type specified by _f_l_a_g_s_p 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, _g_e_t_m_s_g()
       and _g_e_t_p_m_s_g() shall fail and set _e_r_r_n_o to [[EEAAGGAAIINN]].

       If a hangup occurs on the STREAM from which messages are retrieved,
       _g_e_t_m_s_g() and _g_e_t_p_m_s_g() shall continue to operate normally, as described
       above, until the STREAM head read queue is empty. Thereafter, they
       shall return 0 in the _l_e_n members of _c_t_l_p_t_r and _d_a_t_a_p_t_r.

RREETTUURRNN VVAALLUUEE
       Upon successful completion, _g_e_t_m_s_g() and _g_e_t_p_m_s_g() 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 _g_e_t_m_s_g() and _g_e_t_p_m_s_g() 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 _g_e_t_m_s_g() or _g_e_t_p_m_s_g() 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 _g_e_t_m_s_g() and _g_e_t_p_m_s_g() 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 _g_e_t_m_s_g() or _g_e_t_p_m_s_g()
       shall retrieve the higher-priority message before retrieving the
       remainder of the message that was put back.

       Upon failure, _g_e_t_m_s_g() and _g_e_t_p_m_s_g() shall return -1 and set _e_r_r_n_o to
       indicate the error.

EERRRROORRSS
       The _g_e_t_m_s_g() and _g_e_t_p_m_s_g() functions shall fail if:

       EEAAGGAAIINN The O_NONBLOCK flag is set and no messages are available.

       EEBBAADDFF  The _f_i_l_d_e_s argument is not a valid file descriptor open for
              reading.

       EEBBAADDMMSSGG
              The queued message to be read is not valid for _g_e_t_m_s_g() or
              _g_e_t_p_m_s_g() or a pending file descriptor is at the STREAM head.

       EEIINNTTRR  A signal was caught during _g_e_t_m_s_g() or _g_e_t_p_m_s_g().

       EEIINNVVAALL An illegal value was specified by _f_l_a_g_s_p, or the STREAM or
              multiplexer referenced by _f_i_l_d_e_s is linked (directly or
              indirectly) downstream from a multiplexer.

       EENNOOSSTTRR A STREAM is not associated with _f_i_l_d_e_s.

       In addition, _g_e_t_m_s_g() and _g_e_t_p_m_s_g() shall fail if the STREAM head had
       processed an asynchronous error before the call. In this case, the
       value of _e_r_r_n_o does not reflect the result of _g_e_t_m_s_g() or _g_e_t_p_m_s_g() but
       reflects the prior error.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

EEXXAAMMPPLLEESS
   GGeettttiinngg AAnnyy MMeessssaaggee
       In the following example, the value of _f_d is assumed to refer to an
       open STREAMS file. The call to _g_e_t_m_s_g() retrieves any available message
       on the associated STREAM-head read queue, returning control and data
       information to the buffers pointed to by _c_t_r_l_b_u_f and _d_a_t_a_b_u_f,
       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);

   GGeettttiinngg tthhee FFiirrsstt MMeessssaaggee ooffff tthhee QQuueeuuee
       In the following example, the call to _g_e_t_p_m_s_g() 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);

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       None.

RRAATTIIOONNAALLEE
       None.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       The _g_e_t_m_s_g() and _g_e_t_p_m_s_g() functions may be removed in a future
       version.

SSEEEE AALLSSOO
       _S_e_c_t_i_o_n _2_._6, _S_T_R_E_A_M_S, _p_o_l_l(), _p_u_t_m_s_g(), _r_e_a_d(), _w_r_i_t_e()

       The Base Definitions volume of POSIX.1-2017, <<ssttrrooppttss..hh>>

CCOOPPYYRRIIGGHHTT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1-2017, Standard for Information Technology --
       Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the
       Institute of Electrical and Electronics Engineers, Inc and The Open
       Group.  In the event of any discrepancy between this version and the
       original IEEE and The Open Group Standard, the original IEEE and The
       Open Group Standard is the referee document. The original Standard can
       be obtained online at http://www.opengroup.org/unix/online.html .

       Any typographical or formatting errors that appear in this page are
       most likely to have been introduced during the conversion of the source
       files to man page format. To report such errors, see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .



IEEE/The Open Group                  2017                            GETMSG(3)
