GETMSG(2) INTERACTIVE UNIX System 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
The getmsg system call 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 fd argument 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 max-
imum 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.
The ctlptr argument 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, 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
Rev. C Software Development Set Page 1
GETMSG(2) INTERACTIVE UNIX System GETMSG(2)
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 mes-
sages by setting flags to RS_HIPRI. In this case, getmsg
will only process the next message if it is a priority mes-
sage.
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.
The getmsg system call fails if one or more of the following
is true:
[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 loca-
tion 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
multiplexer.
[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.
Rev. C Software Development Set Page 2
GETMSG(2) INTERACTIVE UNIX System GETMSG(2)
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.
Rev. C Software Development Set Page 3