Man Pages

getmsg(3p) - phpMan getmsg(3p) - phpMan

Command: man perldoc info search(apropos)  


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



PROLOG
       This manual page is part of the POSIX Programmer's Manual.  The Linux implementation of this interface may dif-
       fer (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 dat-
       aptr) 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  pro-
       cess  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 inte-
       ger 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 inte-
       ger 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. Subse-
       quent 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  mes-
       sage.  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  informa-
       tion 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
       None.

SEE ALSO
       STREAMS, poll(), putmsg(), read(), write(), the Base Definitions volume of IEEE Std 1003.1-2001, <stropts.h>

COPYRIGHT
       Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2003 Edition, Stan-
       dard  for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifica-
       tions Issue 6, Copyright (C) 2001-2003 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 .



IEEE/The Open Group                  2003                           GETMSG(3P)