getmsg(2) DG/UX 4.30 getmsg(2)
NAME
getmsg - Get a message from a stream.
SYNOPSIS
#include <stropts.h>
int getmsg (filedes, control_info_ptr, data_info_ptr, priority_ptr)
int filedes;
struct strbuf * control_info_ptr;
struct strbuf * data_info_ptr;
int * priority_ptr;
PARAMETERS
filedes File descriptor
control_info_ptr
A pointer to a structure describing the
control buffer or NULL, if there is no
control buffer.
data_info_ptr A pointer to a structure describing the data
buffer or NULL, if there is no data buffer.
priority_ptr On input, the type of message desired. On
output, the type of message retrieved.
DESCRIPTION
<Fildes> is a valid, active descriptor refering to an open
streams file. This function retrieves the contents of the
first message on the stream head read queue and places the
contents in the buffers described by <control_info_ptr> and
<data_info_ptr>. <Control_info_ptr> and <Data_info_ptr>
point to strbuf structures that contain the following
fields:
* buf - Pointer to the first byte of the control or
data buffer.
* maxlen - The 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.
Licensed material--property of copyright holder(s) Page 1
getmsg(2) DG/UX 4.30 getmsg(2)
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
an strbuf pointer is NULL or "maxlen" is negative, the
corresponding part of the message is not processed and is
left on the stream. It is legitimate to request neither
part of the message. If the control "maxlen" is 0 and the
first control block has a data buffer of length 0, that
block is removed from the message and the control "len" is
set to 0. The same holds true for the data part. 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.
On input, *<flags> must be either RS_HIPRI or 0. If it is
RS_HIPRI, only a message of type M_PCPROTO will be
retrieved. Otherwise, any message type but M_PASSFP is
retrieved. On output, *<flags> is set to RS_HIPRI if part
of a M_PCPROTO message is retrieved and to 0, otherwise. If
neither control nor data information is requested, *<flags>
reflects the type of the first message on the stream head's
read queue in a similar manner.
If a message of the type requested is not the first one on
the queue and neither the O_NDELAY nor O_NONBLOCK flag of
the descriptor has been set, this function waits until a
message of that type is at the head of the queue. If the
message is not available but O_NDELAY or O_NONBLOCK is set,
the function fails and errno is set to EAGAIN.
If a hangup occurs on the stream, this function operates as
described above as long as there is a message of the
requested priority at the head of the queue. Thereafter, it
returns 0 in both "len" fields and *<priority>, and the
return value 0.
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.
Licensed material--property of copyright holder(s) Page 2
getmsg(2) DG/UX 4.30 getmsg(2)
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.
EXCEPTIONS
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().
EFAULT The arguments pointed to by
<control_info_ptr>, <data_info_ptr>, and
<priority_ptr> 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
*<priority_ptr>
EINVAL The stream referred to by <fildes> is linked
under a multiplexor.
ENOSTR <Fildes> does not refer to a stream.
SEE ALSO
The related system calls: putmsg
Licensed material--property of copyright holder(s) Page 3