GETMSG(2) GETMSG(2)
NAME
getmsg - get next message off a stream
SYNOPSIS
#include <stropts.h>
int getmsg(fd, ctlptr, dataptr, flags)
int fd;
struct strbuf *ctlptr;
struct strbuf *dataptr;
int *flags;
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.
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 */
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
Page 1 May 1989
GETMSG(2) GETMSG(2)
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 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 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 DIAGNOSTICS. 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 message available on the stream head read queue.
However, a user 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 priority
message.
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 fails if one or more of the following are true:
Page 2 May 1989
GETMSG(2) GETMSG(2)
[EAGAIN] The O_NDELAY flag is set, and no messages are
available.
[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, 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, or
the stream referenced by fd is linked under a
multiplexor.
[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.
SEE ALSO
intro(2), read(2), poll(2), putmsg(2), write(2).
STREAMS Primer
STREAMS Programmer's Guide
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 is waiting for
retrieval. A return value of MORECTL|MOREDATA indicates
that both types of information remain. Subsequent getmsg
calls will retrieve the remainder of the message.
Page 3 May 1989