getmsg(2) UNIX System V getmsg(2)
NAME
getmsg - get next message off a stream
SYNOPSIS
#include <stropts.h>
int getmsg(int fd, struct strbuf *ctlptr,
struct strbuf *dataptr, int *flagsp);
int getpmsg(int fd, struct strbuf *ctlptr,
struct strbuf *dataptr, int *bandp, int *flagsp);
DESCRIPTION
getmsg 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 function getpmsg does the same thing as getmsg, but provides finer
control over the priority of the messages received. Except where noted,
all information pertaining to getmsg also pertains to getpmsg.
fd specifies a file descriptor referencing an open stream. ctlptr and
dataptr 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 */
buf points to a buffer in which the data or control information is to be
placed, and maxlen indicates the maximum number of bytes this buffer can
hold. On return, len contains the number of bytes of data or control
information actually received, or 0 if there is a zero-length control or
data part, or -1 if no data or control information is present in the
message. flagsp should point to an integer that indicates the type of
message the user is able to receive. This is described later.
ctlptr is used to hold the control part from the message and dataptr is
used to hold the data part from the message. If ctlptr (or dataptr) is
NULL or the maxlen field 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 field 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 field 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 field in ctlptr or dataptr is
less than, respectively, the control or data part of the message, maxlen
10/89 Page 1
getmsg(2) UNIX System V getmsg(2)
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 DIAGNOSTICS.
By default, getmsg processes the first available message on the stream
head read queue. However, a user may choose to retrieve only high
priority messages by setting the integer pointed 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 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 0 otherwise.
For getpmsg, the flags are different. flagsp 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
fields of ctlptr and dataptr.
getmsg or getpmsg will fail if one or more of the following are true:
EAGAIN The O_NDELAY or O_NONBLOCK flag is set, and no messages
are available.
Page 2 10/89
getmsg(2) UNIX System V getmsg(2)
EBADF fd is not a valid file descriptor open for reading.
EBADMSG Queued message to be read is not valid for getmsg.
EFAULT ctlptr, dataptr, bandp, or flagsp points to a location
outside the allocated address space.
EINTR A signal was caught during the getmsg system call.
EINVAL An illegal value was specified in flagsp, or the stream
referenced by fd is linked under a multiplexor.
ENOSTR A stream is not associated with fd.
getmsg 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.
SEE ALSO
intro(2), poll(2), putmsg(2), read(2), write(2).
Programmer's Guide: STREAMS.
DIAGNOSTICS
Upon successful completion, a non-negative value is returned. 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 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
come in on 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.
10/89 Page 3