GETMSG(2) System Calls Manual GETMSG(2)
getmsg - get next message from a stream
int getmsg(fd, ctlptr, dataptr, flags)
struct strbuf *ctlptr;
struct strbuf *dataptr;
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 mes-
sage are placed into separate buffers, as described below. The seman-
tics of each part is defined by the STREAMS module that generated the
fd specifies a file descriptor referencing an open stream. ctlptr and
dataptr each point to a strbuf structure that contains the following
int maxlen; /* maximum buffer length */
int len; /* length of data */
char *buf; /* ptr to buffer */
where 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 is 0 if there is a zero-
length control or data part, or is -1 if no data or control information
is present in the message. flags may be set to the values 0 or
RS_HIPRI and is used as described below.
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
a NULL pointer 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
and 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 con-
trol 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. If information is retrieved from a priority message,
flags is set to RS_HIPRI on return.
By default, getmsg() processes the first priority or non-priority mes-
sage available on the stream head read queue. However, a process may
choose to retrieve only priority messages by setting flags to RS_HIPRI.
In this case, getmsg() will only process the next message if it is a
If O_NDELAY has not been set, getmsg() blocks until a message, of the
type(s) specified by flags (priority or either), is available on the
stream head read queue. If O_NDELAY has been set and a message of the
specified type(s) 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() will continue to operate normally, as described
above, until the stream head read queue is empty. Thereafter, it will
return 0 in the len fields of ctlptr and dataptr.
getmsg() returns a non-negative value on success:
0 A full message was read successfully.
MORECTL More control information is waiting for
retrieval. Subsequent getmsg() calls
will retrieve the rest of the message.
MOREDATA More data are waiting for retrieval.
Subsequent getmsg() calls will retrieve
the rest of the message.
MORECTL | MOREDATA Both types of information remain.
On failure, getmsg() returns -1 and sets errno to indicate the error.
EAGAIN The O_NDELAY flag is set, and no messages are available.
EBADF fd is not a valid file descriptor open for reading.
EBADMSG The queued message to be read is not valid for getmsg().
EFAULT ctlptr, dataptr, or flags 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 flags.
The stream referenced by fd is linked under a multi-
ENOSTR A stream is not associated with fd.
A 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.
intro(2), poll(2), putmsg(2), read(2V), write(2V)
21 January 1990 GETMSG(2)