|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
PROLOG | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | RATIONALE | FUTURE DIRECTIONS | SEE ALSO | COPYRIGHT |
|
|
|
GETMSG(3P) POSIX Programmer's Manual GETMSG(3P)
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.
getmsg, getpmsg — receive next message from a STREAMS file
(STREAMS)
#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);
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.
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.
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.
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);
None.
None.
The getmsg() and getpmsg() functions may be removed in a future
version.
Section 2.6, STREAMS, poll(3p), putmsg(3p), read(3p), write(3p)
The Base Definitions volume of POSIX.1‐2017, stropts.h(0p)
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(3P)
Pages that refer to this page: stropts.h(0p), getpmsg(3p), ioctl(3p), poll(3p), putmsg(3p)
|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|