mirror of https://github.com/mkerrisk/man-pages
279 lines
10 KiB
Plaintext
279 lines
10 KiB
Plaintext
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "GETMSG" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" getmsg
|
|
.SH NAME
|
|
getmsg, getpmsg \- receive next message from a STREAMS file (\fBSTREAMS\fP)
|
|
.SH SYNOPSIS
|
|
.LP
|
|
\fB#include <stropts.h>
|
|
.br
|
|
.sp
|
|
int getmsg(int\fP \fIfildes\fP\fB, struct strbuf *restrict\fP \fIctlptr\fP\fB,
|
|
.br
|
|
\ \ \ \ \ \ struct strbuf *restrict\fP \fIdataptr\fP\fB, int *restrict\fP
|
|
\fIflagsp\fP\fB);
|
|
.br
|
|
int getpmsg(int\fP \fIfildes\fP\fB, struct strbuf *restrict\fP \fIctlptr\fP\fB,
|
|
.br
|
|
\ \ \ \ \ \ struct strbuf *restrict\fP \fIdataptr\fP\fB, int *restrict\fP
|
|
\fIbandp\fP\fB,
|
|
.br
|
|
\ \ \ \ \ \ int *restrict\fP \fIflagsp\fP\fB); \fP
|
|
\fB
|
|
.br
|
|
\fP
|
|
.SH DESCRIPTION
|
|
.LP
|
|
The \fIgetmsg\fP() 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.
|
|
.LP
|
|
The \fIgetpmsg\fP() function shall be equivalent to \fIgetmsg\fP(),
|
|
except that it provides finer control over the priority of
|
|
the messages received. Except where noted, all requirements on \fIgetmsg\fP()
|
|
also pertain to \fIgetpmsg\fP().
|
|
.LP
|
|
The \fIfildes\fP argument specifies a file descriptor referencing
|
|
a STREAMS-based file.
|
|
.LP
|
|
The \fIctlptr\fP and \fIdataptr\fP arguments each point to a \fBstrbuf\fP
|
|
structure, in which the \fIbuf\fP member points to
|
|
a buffer in which the data or control information is to be placed,
|
|
and the \fImaxlen\fP member indicates the maximum number of
|
|
bytes this buffer can hold. On return, the \fIlen\fP member shall
|
|
contain the number of bytes of data or control information
|
|
actually received. The \fIlen\fP member shall be set to 0 if there
|
|
is a zero-length control or data part and \fIlen\fP shall be
|
|
set to -1 if no data or control information is present in the message.
|
|
.LP
|
|
When \fIgetmsg\fP() is called, \fIflagsp\fP should point to an integer
|
|
that indicates the type of message the process is able
|
|
to receive. This is described further below.
|
|
.LP
|
|
The \fIctlptr\fP argument is used to hold the control part of the
|
|
message, and \fIdataptr\fP is used to hold the data part of
|
|
the message. If \fIctlptr\fP (or \fIdataptr\fP) is a null pointer
|
|
or the \fImaxlen\fP 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 \fIctlptr\fP (or \fIdataptr\fP)
|
|
is not a null pointer, \fIlen\fP shall be set to -1. If the \fImaxlen\fP
|
|
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 \fIlen\fP shall be set to 0. If the \fImaxlen\fP
|
|
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 \fIlen\fP shall be set to 0. If the \fImaxlen\fP member
|
|
in \fIctlptr\fP (or \fIdataptr\fP) is less than the control
|
|
(or data) part of the message, \fImaxlen\fP 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.
|
|
.LP
|
|
By default, \fIgetmsg\fP() 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 \fIflagsp\fP to RS_HIPRI. In this case,
|
|
\fIgetmsg\fP() shall only process the next message if it is a high-priority
|
|
message. When the integer pointed to by \fIflagsp\fP
|
|
is 0, any available message shall be retrieved. In this case, on return,
|
|
the integer pointed to by \fIflagsp\fP shall be set to
|
|
RS_HIPRI if a high-priority message was retrieved, or 0 otherwise.
|
|
.LP
|
|
For \fIgetpmsg\fP(), the flags are different. The \fIflagsp\fP argument
|
|
points to a bitmask with the following
|
|
mutually-exclusive flags defined: MSG_HIPRI, MSG_BAND, and MSG_ANY.
|
|
Like \fIgetmsg\fP(), \fIgetpmsg\fP() 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 \fIflagsp\fP to MSG_HIPRI and the integer pointed
|
|
to by \fIbandp\fP to 0. In this case, \fIgetpmsg\fP()
|
|
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 \fIflagsp\fP to MSG_BAND and the integer pointed to
|
|
by \fIbandp\fP to the priority band of interest. In this case, \fIgetpmsg\fP()
|
|
shall only process the next message if it is in a
|
|
priority band equal to, or greater than, the integer pointed to by
|
|
\fIbandp\fP, 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 \fIflagsp\fP should be set to MSG_ANY and the integer
|
|
pointed to by \fIbandp\fP should be set to 0. On return, if the message
|
|
retrieved was a high-priority message, the integer pointed
|
|
to by \fIflagsp\fP shall be set to MSG_HIPRI and the integer pointed
|
|
to by \fIbandp\fP shall be set to 0. Otherwise, the integer
|
|
pointed to by \fIflagsp\fP shall be set to MSG_BAND and the integer
|
|
pointed to by \fIbandp\fP shall be set to the priority band
|
|
of the message.
|
|
.LP
|
|
If O_NONBLOCK is not set, \fIgetmsg\fP() and \fIgetpmsg\fP() shall
|
|
block until a message of the type specified by
|
|
\fIflagsp\fP 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, \fIgetmsg\fP() and \fIgetpmsg\fP()
|
|
shall fail and set \fIerrno\fP to [EAGAIN].
|
|
.LP
|
|
If a hangup occurs on the STREAM from which messages are retrieved,
|
|
\fIgetmsg\fP() and \fIgetpmsg\fP() shall continue to
|
|
operate normally, as described above, until the STREAM head read queue
|
|
is empty. Thereafter, they shall return 0 in the \fIlen\fP
|
|
members of \fIctlptr\fP and \fIdataptr\fP.
|
|
.SH RETURN VALUE
|
|
.LP
|
|
Upon successful completion, \fIgetmsg\fP() and \fIgetpmsg\fP() 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
|
|
\fIgetmsg\fP() and \fIgetpmsg\fP() 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
|
|
\fIgetmsg\fP() or \fIgetpmsg\fP() shall retrieve that higher-priority
|
|
message before retrieving the remainder of the previous
|
|
message.
|
|
.LP
|
|
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 \fIgetmsg\fP() and \fIgetpmsg\fP() 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 \fIgetmsg\fP() or \fIgetpmsg\fP() shall
|
|
retrieve the higher-priority message before retrieving the remainder
|
|
of the message that was put back.
|
|
.LP
|
|
Upon failure, \fIgetmsg\fP() and \fIgetpmsg\fP() shall return -1 and
|
|
set \fIerrno\fP to indicate the error.
|
|
.SH ERRORS
|
|
.LP
|
|
The \fIgetmsg\fP() and \fIgetpmsg\fP() functions shall fail if:
|
|
.TP 7
|
|
.B EAGAIN
|
|
The O_NONBLOCK flag is set and no messages are available.
|
|
.TP 7
|
|
.B EBADF
|
|
The \fIfildes\fP argument is not a valid file descriptor open for
|
|
reading.
|
|
.TP 7
|
|
.B EBADMSG
|
|
The queued message to be read is not valid for \fIgetmsg\fP() or \fIgetpmsg\fP()
|
|
or a pending file descriptor is at the
|
|
STREAM head.
|
|
.TP 7
|
|
.B EINTR
|
|
A signal was caught during \fIgetmsg\fP() or \fIgetpmsg\fP().
|
|
.TP 7
|
|
.B EINVAL
|
|
An illegal value was specified by \fIflagsp\fP, or the STREAM or multiplexer
|
|
referenced by \fIfildes\fP is linked (directly
|
|
or indirectly) downstream from a multiplexer.
|
|
.TP 7
|
|
.B ENOSTR
|
|
A STREAM is not associated with \fIfildes\fP.
|
|
.sp
|
|
.LP
|
|
In addition, \fIgetmsg\fP() and \fIgetpmsg\fP() shall fail if the
|
|
STREAM head had processed an asynchronous error before the
|
|
call. In this case, the value of \fIerrno\fP does not reflect the
|
|
result of \fIgetmsg\fP() or \fIgetpmsg\fP() but reflects the
|
|
prior error.
|
|
.LP
|
|
\fIThe following sections are informative.\fP
|
|
.SH EXAMPLES
|
|
.SS Getting Any Message
|
|
.LP
|
|
In the following example, the value of \fIfd\fP is assumed to refer
|
|
to an open STREAMS file. The call to \fIgetmsg\fP()
|
|
retrieves any available message on the associated STREAM-head read
|
|
queue, returning control and data information to the buffers
|
|
pointed to by \fIctrlbuf\fP and \fIdatabuf\fP, respectively.
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fB#include <stropts.h>
|
|
\&...
|
|
int fd;
|
|
char ctrlbuf[128];
|
|
char databuf[512];
|
|
struct strbuf ctrl;
|
|
struct strbuf data;
|
|
int flags = 0;
|
|
int ret;
|
|
.sp
|
|
|
|
ctrl.buf = ctrlbuf;
|
|
ctrl.maxlen = sizeof(ctrlbuf);
|
|
.sp
|
|
|
|
data.buf = databuf;
|
|
data.maxlen = sizeof(databuf);
|
|
.sp
|
|
|
|
ret = getmsg (fd, &ctrl, &data, &flags);
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.SS Getting the First Message off the Queue
|
|
.LP
|
|
In the following example, the call to \fIgetpmsg\fP() retrieves the
|
|
first available message on the associated STREAM-head read
|
|
queue.
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fB#include <stropts.h>
|
|
\&...
|
|
.sp
|
|
|
|
int fd;
|
|
char ctrlbuf[128];
|
|
char databuf[512];
|
|
struct strbuf ctrl;
|
|
struct strbuf data;
|
|
int band = 0;
|
|
int flags = MSG_ANY;
|
|
int ret;
|
|
.sp
|
|
|
|
ctrl.buf = ctrlbuf;
|
|
ctrl.maxlen = sizeof(ctrlbuf);
|
|
.sp
|
|
|
|
data.buf = databuf;
|
|
data.maxlen = sizeof(databuf);
|
|
.sp
|
|
|
|
ret = getpmsg (fd, &ctrl, &data, &band, &flags);
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.SH APPLICATION USAGE
|
|
.LP
|
|
None.
|
|
.SH RATIONALE
|
|
.LP
|
|
None.
|
|
.SH FUTURE DIRECTIONS
|
|
.LP
|
|
None.
|
|
.SH SEE ALSO
|
|
.LP
|
|
\fISTREAMS\fP , \fIpoll\fP() , \fIputmsg\fP() , \fIread\fP() , \fIwrite\fP()
|
|
, the Base
|
|
Definitions volume of IEEE\ Std\ 1003.1-2001, \fI<stropts.h>\fP
|
|
.SH 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 .
|