getmsg, getpmsg - Receive the next message from a Stream
#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 );
Standard C Library (libc)
Interfaces documented on this reference page conform to
industry standards as follows:
getmsg(), getpmsg(): XSH4.2, XSH5.0
Refer to the standards(5) reference page for more information
about industry standards and associated tags.
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 integer that indicates the priority band of
the message that the user is able to retrieve. Points to
an integer that indicates the type of message the user is
able to retrieve.
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 better 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 zerolength
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() functions, 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() function then only processes the next
message if it is a high-priority message.
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
parameter to MSG_HIPRI, and set the integer pointed to by
the band parameter to 0 (zero), the getpmsg() function
retrieves only high-priority messages. The getpmsg() function
then only processes the next message if it is a highpriority
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 specified 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 compatibility.
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.
Upon successful completion, the getmsg() and getmsg()
functions return nonnegative values, as follows: Indicates
that a full message was successfully read. Indicates that
more control information is waiting for retrieval. Indicates
that more data is waiting for retrieval. Indicates
that both types of information remain. Later calls to
getmsg() then retrieve the rest of the message. Note, however,
that higher-priority 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.
Both the getmsg() and getpmsg() functions fail if a
STREAMS error message 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_NONBLOCK 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.
Functions: poll(2), putmsg(2), read(2), write(2)
Interfaces: streamio(7)
Standards: standards(5)
Network Programmer's Guide
getmsg(2)
[ Back ] |
