getmsg(2) DG/UX R4.11MU05 getmsg(2)
NAME
getmsg, getpmsg - get a message from a stream
SYNOPSIS
#include <stropts.h>
int getmsg (fildes, controlinfoptr, datainfoptr, flagsptr)
int fildes;
struct strbuf * controlinfoptr;
struct strbuf * datainfoptr;
int * flagsptr;
int getpmsg(fildes, controlinfoptr, datainfoptr, bandptr, flagsptr)
int fildes;
struct strbuf * controlinfoptr;
struct strbuf * datainfoptr;
int * bandptr;
int * flagsptr;
where:
fildes File descriptor
controlinfoptr A pointer to a structure describing the control
buffer or NULL, if there is no control buffer
datainfoptr A pointer to a structure describing the data buffer
or NULL, if there is no data buffer
bandptr On input, specifies the minimum band message to
retrieve. On output, the band of the message
retrieved.
flagsptr On input, the type of message desired; on output,
the type of message retrieved
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.
fildes specifies a file descriptor referencing an open stream.
controlinfoptr and datainfoptr each point to a strbuf structure,
which contains the following members:
buf Pointer to the first byte of the control or data buffer.
maxlen The maximum size, in bytes, of the buffer or a negative
number, if information of that type is not requested.
len Ignored on input. On output, contains the number of bytes of
control or data information placed in the buffer or -1, if
there is no information of that type present in the message
or that type of information was not requested. This field is
valid on output only if the status OK is returned.
The control buffer is used to hold the control part of the message
(those message blocks before the first block of type M_DATA;
typically either M_PCPROTO or M_PROTO blocks). The data buffer is
used to hold the data part of the message (any blocks after and
including the first M_DATA block). If a strbuf pointer is NULL or
"maxlen" is negative, the corresponding part of the message is not
processed and is left on the stream. If the control (or data)
"maxlen" is 0 and the first control (or data) block has a data buffer
of length 0, that block is removed from the message and the control
(or data) "len" is set to 0. If "maxlen" is 0 and the first block of
the corresponding type has a non-zero buffer, however, the block is
left on the message and "len" is set to 0. If "maxlen" is less than
the length of the corresponding portion of the message, "maxlen"
bytes are retrieved and placed in the caller's buffer. The remainder
of the message is left on the stream and a non-zero return value is
provided as described under RETURN VALUE.
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 flagsptr to
RSHIPRI. In this case, getmsg processes the next message only if it
is a high priority message. If the integer pointed to by flagsptr
is 0, getmsg retrieves any message available on the stream head read
queue. In this case, on return, the integer pointed to by flagsptr
will be set to RSHIPRI if a high priority message was retrieved, or
0 otherwise.
For getpmsg, the flags are different. flagsptr points to a bitmask
with the following mutually-exclusive flags defined: MSGHIPRI,
MSGBAND, and MSGANY. 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 flagsptr to MSGHIPRI and the integer pointed to by
bandptr 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 flagsptr to MSGBAND and the
integer pointed to by bandptr 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
bandptr, 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
flagsptr should be set to MSGANY and the integer pointed to by
bandptr should be set to 0. On return, if the message retrieved was
a high-priority message, the integer pointed to by flagsptr will be
set to MSGHIPRI and the integer pointed to by bandptr will be set
to 0. Otherwise, the integer pointed to by flagsptr will be set to
MSGBAND and the integer pointed to by bandptr will be set to the
priority band of the message.
If ONDELAY and ONONBLOCK are clear, getmsg blocks until a message
of the type specified by flagsp is available on the stream head read
queue. If ONDELAY or ONONBLOCK 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.
ACCESS CONTROL
fildes must be open for reading.
RETURN VALUE
-1 An error occurred. errno is set to indicate the error.
0 An entire message was successfully read.
MORECTL A message was partially read. More control information is
waiting for retrieval.
MOREDATA A message was partially read. More data information is
waiting for retrieval.
MORECTL | MOREDATA
A message was partially read. More control and data
information is waiting for retrieval.
DIAGNOSTICS
Errno may be set to one of the following error codes:
EAGAIN The O_NDELAY or O_NONBLOCK flag was set and a message of
the requested type was not available.
EBADF fildes is not a valid, active descriptor open for reading.
EBADMSG The message at the head of the stream is not a type that is
retrievable by getmsg(2).
EFAULT The arguments pointed to by controlinfoptr,
datainfoptr, and flagsptr do not lie entirely within the
caller's readable and writable address space.
EINTR A signal was caught during the getmsg call.
EINVAL An illegal value was specified by *flagsptr
EINVAL The stream referred to by fildes is linked under a
multiplexor.
ENOSTR fildes does not refer to a stream.
SEE ALSO
putmsg(2).
NOTE
The user should avoid using ONDELAY and instead use ONONBLOCK.
Licensed material--property of copyright holder(s)