.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
.TH "GETMSG" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" getmsg
.SH 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.
.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 .
|
