GETMSG
Section: POSIX Programmer's Manual (3P)
Updated: 2013
Index
Return to Main Contents
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.
SEE ALSO
Section 2.6,
STREAMS,
poll(),
putmsg(),
read(),
write()
The Base Definitions volume of POSIX.1-2008,
<stropts.h>
COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 7, Copyright (C) 2013 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group.
(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) 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.unix.org/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 .
Index
- PROLOG
-
- NAME
-
- SYNOPSIS
-
- DESCRIPTION
-
- RETURN VALUE
-
- ERRORS
-
- EXAMPLES
-
- Getting Any Message
-
- Getting the First Message off the Queue
-
- APPLICATION USAGE
-
- RATIONALE
-
- FUTURE DIRECTIONS
-
- SEE ALSO
-
- COPYRIGHT
-
|
|
- Running on 
-
:
: 