GETMSG(2) System Calls GETMSG(2)
NAME
getmsg, getpmsg - get next message off a stream
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 retrieves the contents of a message (see
Intro(2))
located at the stream head read queue from a STREAMS file, and places
the contents into user specified buffer(s). The message must contain
either a data part, a control part, or both. The data and control parts
of the message are placed into separate buffers, as described below. The
semantics of each part is defined by the STREAMS module that generated
the message.
The
getpmsg() function behaved like
getmsg(), but provides finer control
over the priority of the messages received. Except where noted, all
information pertaining to
getmsg() also pertains to
getpmsg().
The
fildes argument specifies a file descriptor referencing an open
stream. The
ctlptr and
dataptr arguments each point to a
strbuf structure, which contains the following members:
int maxlen; /* maximum buffer length */
int len; /* length of data */
char *buf; /* ptr to buffer */
The
buf member points to a buffer into 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 contains
the number of bytes of data or control information actually received; 0
if there is a zero-length control or data part; or -1 if no data or
control information is present in the message. The
flagsp argument should
point to an integer that indicates the type of message the user is able
to receive, as described below.
The
ctlptr argument holds the control part from the message and the
dataptr argument holds the data part from the message. If
ctlptr (or
dataptr) is
NULL or the
maxlen member is -1, the control (or data) part
of the message is not processed and is left on the stream head read
queue. If
ctlptr (or
dataptr) is not
NULL and there is no corresponding
control (or data) part of the messages on the stream head read queue,
len is 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 is removed from the read
queue and
len is set to 0. If the
maxlen member is set to 0 and there are
more than zero bytes of control (or data) information, that information
is left on the read queue and
len is set to 0. If the
maxlen member in
ctlptr or
dataptr is less than, respectively, the control or data part
of the message,
maxlen bytes are retrieved. In this case, the remainder
of the message is left on the stream head read queue and a non-zero
return value is provided, as described below under
RETURN VALUES.
By default,
getmsg() processes the first available message on the stream
head read queue. A user may, however, choose to retrieve only high
priority messages by setting the integer pointed to by
flagsp to
RS_HIPRI. In this case,
getmsg() processes the next message only if it
is a high priority message.
If the integer pointed to by
flagsp is 0,
getmsg() retrieves any message
available on the stream head read queue. In this case, on return, the
integer pointed to by
flagsp will be set to
RS_HIPRI if a high priority
message was retrieved, or to 0 otherwise.
For
getpmsg(), the
flagsp argument points to a bitmask with the following
mutually-exclusive flags defined:
MSG_HIPRI,
MSG_BAND, and
MSG_ANY. Like
getmsg(),
getpmsg() processes the first available message on the stream
head read queue. A user 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() will only
process the next message if it is a high-priority message. In a similar
manner, a user 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() will 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 user just 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 will be set to
MSG_HIPRI and the integer pointed to by
bandp will
be set to 0. Otherwise, the integer pointed to by
flagsp will be set to
MSG_BAND and the integer pointed to by
bandp will be set to the priority
band of the message.
If
O_NDELAY and
O_NONBLOCK are clear,
getmsg() blocks until a message of
the type specified by
flagsp is available on the stream head read queue.
If
O_NDELAY or
O_NONBLOCK has been set and a message of the specified
type is not present on the read queue,
getmsg() fails and sets
errno to
EAGAIN.
If a hangup occurs on the stream from which messages are to be retrieved,
getmsg() continues to operate normally, as described above, until the
stream head read queue is empty. Thereafter, it returns 0 in the
len member of
ctlptr and
dataptr.
RETURN VALUES
Upon successful completion, a non-negative value is returned. A return
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 are
waiting for retrieval. A return value of
MORECTL |
MOREDATA indicates
that both types of information remain. Subsequent
getmsg() calls retrieve
the remainder of the message. However, if a message of higher priority
has been received by the stream head read queue, the next call to
getmsg() will retrieve that higher priority message before retrieving the
remainder of the previously received partial message.
ERRORS
The
getmsg() and
getpmsg() functions will fail if:
EAGAIN The
O_NDELAY or
O_NONBLOCK flag is set and no messages are
available.
EBADF The
fildes argument is not a valid file descriptor open for
reading.
EBADMSG Queued message to be read is not valid for
getmsg.
EFAULT The
ctlptr,
dataptr,
bandp, or
flagsp argument points to an
illegal address.
EINTR A signal was caught during the execution of the
getmsg function.
EINVAL An illegal value was specified in
flagsp, or the stream
referenced by
fildes is linked under a multiplexor.
ENOSTR A stream is not associated with
fildes.
The
getmsg() function can also fail if a STREAMS error message had been
received at the stream head before the call to
getmsg(). The error
returned is the value contained in the STREAMS error message.
ATTRIBUTES
See
attributes(7) for descriptions of the following attributes:
+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | Standard |
+--------------------+-----------------+
SEE ALSO
Intro(2),
poll(2),
putmsg(2),
read(2),
write(2),
attributes(7),
standards(7) STREAMS Programming Guide November 1, 2001
GETMSG(2)