Provided by: manpages-posix-dev_2.16-1_all 
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
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,
Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base
Specifications 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(P)