getmsg(2)getmsg(2)NAME
getmsg, getpmsg - receive next message from a STREAMS file
SYNOPSISDESCRIPTION
The function retrieves the contents of a message located at the head of
the stream head read queue associated with a STREAMS file and places
the contents into one or more buffers. The message contains 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 originator of the message.
The function does the same thing as but provides finer control over the
priority of the messages received. Except where noted, all require‐
ments on also pertain to
The fildes argument specifies a file descriptor referencing a STREAMS-
based file.
The ctlptr and dataptr arguments each point to a structure, in which
the buf member points to a buffer in which the data or control informa‐
tion is to be placed, and the maxlen member indicates the maximum num‐
ber of bytes this buffer can hold. On return, the len member contains
the number of bytes of data or control information actually received.
The len member is set to 0 if there is a zero-length control or data
part and len is set to -1 if no data or control information is present
in the message.
When is called, flagsp should point to an integer that indicates the
type of message the process is able to receive. This is described fur‐
ther below.
The ctlptr argument is used to hold the control part of the message,
and dataptr is used to hold the data part of the message. If ctlptr
(or dataptr) is a null pointer or the maxlen members is −1, the control
(or data) part of the message is not processed and is left on the
stream head read queue, and if the ctlptr (or dataptr) is not a null
pointer, len is set to −1. If the maxlen member 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 member
is set to 0 and there are more than 0 bytes of control (or data) infor‐
mation, that information is left on the read queue and len is set to 0.
If the maxlen member in ctlptr (or dataptr) is less than the control
(or data) part of the message, maxlen bytes are retrieved. In this
case, the remainder of the message is left on the stream head read
queue and a on-zero return value is provided.
By default, processes the first available message on the stream head
read queue. However, a process may choose to retrieve only high-prior‐
ity messages by setting the integer pointed to by flagsp to In this
case, will only process the next message if it is a high-priority mes‐
sage. When the integer pointed to by flagsp is 0, any message will be
retrieved. In this case, on return, the integer pointed to by flagsp
will be set to if a high-priority message was retrieved, or 0 other‐
wise.
For the flags are different. The flagsp argument points to a bitmask
with the following mutually-exclusive flags defined. and Like pro‐
cesses the first available message on the stream head read queue. A
process may choose to retrieve only high-priority message by setting
the integer pointed to by flagsp to and the integer pointed to by bandp
to 0. In this case, will only process the next message if is a high-
priority message. In a similar manner, a process may choose to
retrieve a message from a particular priority band by setting the inte‐
ger pointed to by flagsp to and the integer pointed to by bandp to the
priority band of interest. In this case, will only process the next
message if it is in a priority band equal to, or greater than, the
integer pointed to by bandp, or if it is a high-priority message. If a
process just wants to get the first message off the queue, the integer
pointed to by bandp should be set to 0. On return, if the message
retrieved was a high-priority message, the integer pointed to by flagsp
will be set to and the integer pointed to by bandp will be set to 0.
Otherwise, the integer pointed to by flagsp will be set to and the
integer pointed to by bandp will be set to the priority band of the
message.
If is not set, and will block until a message of the type specified by
flagsp is available at the front of the stream head read queue. If is
set and a message of the specified type is not present at the front of
the read queue, and fail and set to [EAGAIN].
If a hangup occurs on the stream from which messages are to be
retrieved, and continue to operate normally, as described above, until
the stream head read queue is empty. Thereafter, they return 0 in the
len members of ctlptr and dataptr.
RETURN VALUE
Upon successful completion, and return a non-negative value. A value
of 0 indicates that a full message was read successfully. A return
value of indicates that more control information is waiting for
retrieval. A return value of indicates that more data is waiting for
retrieval. A return value of the bitwise logical OR of and indicates
that both types of information remain. Subsequent and calls retrieve
the remainder of the message. However, if a message of higher priority
has come in on the stream head read queue, the next call to or
retrieves that higher-priority message before retrieving the remainder
of the previously-received partial message.
Upon failure, and return -1 and set to indicate the error.
ERRORS
The and functions will fail if:
[EAGAIN] The flag is set and no messages are available.
[EBADF] The fildes argument is not a valid file descrip‐
tor open for reading.
[EBADMSG] The queued message to be read is not valid for or
or a pending file descriptor is at the stream
head.
[EINTR] A signal was caught during or
[EINVAL] An illegal value was specified by flagsp, or the
stream or multiplexor referenced by fildes is
linked (directly or indirectly) downstream from a
multiplexor.
[ENOSTR] A stream is not associated with fildes.
SEE ALSOpoll(2), putmsg(2), read(2), write(2), thread_safety(5), streamio(7),
<stropts.h>.
getmsg(2)