getmsg(2)getmsg(2)NAME
getmsg, getpmsg - Receive the next message from a Stream
SYNOPSIS
#include <stropts.h>
int getmsg(
int fd,
struct strbuf *ctlptr,
struct strbuf *dataptr,
int *flags ); int getpmsg(
int fd,
struct strbuf *ctlptr,
struct strbuf *dataptr,
int *band,
int *flags );
LIBRARY
Standard C Library (libc)
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
getmsg(), getpmsg(): XSH4.2, XSH5.0
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
Specifies a file descriptor that references an open Stream. Points to
a strbuf structure that holds the control part of the message. This
strbuf structure is described in the DESCRIPTION section. Points to a
strbuf structure that holds the data part of the message. This strbuf
structure is described in the DESCRIPTION section. Points to an inte‐
ger that indicates the priority band of the message that the user is
able to retrieve. Points to an integer that indicates the type of mes‐
sage the user is able to retrieve.
DESCRIPTION
The getmsg() and getpmsg() functions retrieve the contents of messages.
These messages are located at the Stream head read queue associated
with a STREAMS file. Messages must contain a control part or a data
part, or both. The control and data parts of the message are placed
into separate user-specified buffers, pointed at by ctlptr and dataptr
respectively. The open Stream specifies the format and semantics of the
message's control and data parts. The getpmsg() function provides bet‐
ter control over the priority of the messages received. Except where
specified, all information about the getmsg() function also applies to
the getpmsg() function. The semantics of both the control and data
parts of the message is defined by the STREAMS module that created the
message.
The ctlptr and dataptr parameters each point to a strbuf structure that
contains three members. This structure is defined in <sys/stropts.h>
as:
struct strbuf {
int maxlen; /* maximum buffer length */
int len; /* length of data */
char *buf /* ptr to buffer */ };
The members are: Specifies the maximum number of bytes buf can hold.
Points to the buffer where the control or data information is to
reside. On return, contains the number of bytes of control or data
information that has actually been received. The len parameter is set
to 0 (zero) if there is a zero-length data or control part; otherwise,
len is set to -1 if no control or data information is contained in the
message.
The members of this structure are also affected by the following. If
the maxlen field is set to 0 (zero), and the control or data part is of
zero-length, that zero-length part is deleted from the read queue of
the Stream head, and len is set to 0 (zero). If the maxlen field is
set to 0 (zero), and if the size of the control or data part is greater
than 0 (zero), that part remains on the read queue and len is set to 0
(zero). If the maxlen field for either the ctlptr or dataptr structure
is less than the size of the control or data part of the message,
maxlen bytes are retrieved and the rest of the message remains on the
Stream head read queue. A nonzero value is then returned. If the
maxlen member is -1, or if ctlptr or dataptr parameter is a null
pointer, the getmsg() function does not process the control or the data
part of the message. The unprocessed part(s) then remains on the Stream
head queue. If ctlptr or dataptr is not a null pointer, and if the
read queue at the Stream head has no corresponding message control or
data part, len is set to -1.
One of the major differences between the getmsg() and getpmsg() func‐
tions, in addition to the band parameter, is how the flags parameter is
used to collect messages. The getmsg() function processes messages as
follows: By default, the getmsg() function processes the first message
that is available on the Stream head queue. If you set the flags
parameter to 0 (zero), any message will be retrieved. On return, the
integer pointed to by the flags parameter will be set to RS_HIPRI if a
high-priority message was retrieved; otherwise, a value of 0 (zero) is
returned. If you set the flags parameter to RS_HIPRI, the getmsg()
function retrieves only the high-priority messages. The getmsg() func‐
tion then only processes the next message if it is a high-priority mes‐
sage.
The getpmsg() function flags parameter points to a bitmask with the
mutually-exclusive options MSG_HIPRI, MSG_BAND, and MSG_ANY defined.
The getpmsg() function processes messages as follows: By default, the
getpmsg() function processes the first available message on the Stream
head read queue. If you set the integer pointed at by the flags param‐
eter to MSG_HIPRI, and set the integer pointed to by the band parameter
to 0 (zero), the getpmsg() function retrieves only high-priority mes‐
sages. The getpmsg() function then only processes the next message if
it is a high-priority message. If you set the integer pointed to by
the flags parameter to MSG_BAND, and set the integer pointed to by the
band parameter to the desired priority band, the getpmsg() function
retrieves a message from that band. The getpmsg() function then only
processes the next message if it is in a high-priority message, or if
its priority band is at least equal to the integer pointed to by band.
If you set the integer pointed to by the flags parameter to MSG_ANY,
and set the integer pointed to by the band parameter to 0 (zero), the
getpmsg() function retrieves only the first message off the queue.
When the getpmsg() function returns, it then sets the flags and band
parameters according to the type of message that was retrieved. If the
message was not a high-priority one, the integer pointed to by the
flags parameter is set to MSG_BAND and the integer pointed to by band
is set to the band of the message. If the message was a high-priority
one, the integer pointed to by the flags is set to MSG_HIPRI and the
integer pointed to by band will be set to 0 (zero).
If the O_NDELAY or O_NONBLOCK flags are set and a message of the speci‐
fied type is not present at the front of the read queue, the getmsg()
function fails. If the O_NDELAY or O_NONBLOCK options are not set for
the read() operation, the getmsg() function blocks until a message is
available at the front of the Stream head read queue. This message's
type is specified by flags.
[Tru64 UNIX] Current industry standards do not define the O_NDELAY
option. It is included in the preceding paragraphs for System V com‐
patibility.
If the Stream from which the messages are being retrieved experiences a
hangup, the getmsg() function does not fail. Instead, it will continues
as usual until the read queue of the Stream head is empty. Subsequent
calls will return a value of 0 (zero) in the len fields for the ctlptr
and dataptr structures.
RETURN VALUES
Upon successful completion, the getmsg() and getmsg() functions return
nonnegative values, as follows: Indicates that a full message was suc‐
cessfully read. Indicates that more control information is waiting for
retrieval. Indicates that more data is waiting for retrieval. Indi‐
cates that both types of information remain. Later calls to getmsg()
then retrieve the rest of the message. Note, however, that higher-pri‐
ority messages, although they may arrive later on the queue, take a
higher precedence. In other words, if a message comes in later on the
read queue, the next call to the getmsg() function retrieves that
higher-priority message first. The rest of the earlier partial message
is retrieved afterwards.
Upon failure, the getmsg() function returns a value of -1, and sets
errno to indicate an error.
ERRORS
Both the getmsg() and getpmsg() functions fail if a STREAMS error mes‐
sage is delivered to the Stream head read queue before the call. In
this instance, the STREAMS error message contains the value of the
returned error.
In addition, if any of the following conditions occurs, the getmsg()
function sets errno to the corresponding value: The O_NDELAY or O_NON‐
BLOCK flag is set, and no messages are currently available.
[Tru64 UNIX] Current industry standards do not define the
O_NDELAY flag. It is included in the preceding paragraph for
System V compatibility. An illegal address has been specified
in ctlptr or dataptr. The fd parameter is not a valid file
descriptor open for reading. The message on the read queue is
not a control or data message, or a file descriptor is pending
at the Stream head. The getmsg() or getpmsg() function was
interrupted by a signal that was caught. An illegal value was
specified by the flags parameter, or the Stream referenced by fd
is linked under a multiplexor. A Stream is not associated with
the fd parameter.
SEE ALSO
Functions: poll(2), putmsg(2), read(2), write(2)
Interfaces: streamio(7)
Standards: standards(5)
Network Programmer's Guide
getmsg(2)
