STREAMS-UX Programmer's Guide (February 2007)

STREAMS Mechanism and System Calls
Reading From a Stream
Chapter 2
28
• If a buffer pointer is null or the corresponding maxlen is -1, the message is not be processed, and remains
on the stream head read queue. If the buffer pointer is null, the corresponding len field returned is set to
-1.
•If buf is not null, len is greater than 0, and len is equal to or less than maxlen, len bytes are retrieved by
getmsg (2), or getpmsg (2), and the return value of the function is set to len. However, if maxlen is less
than len and greater than 0, only maxlen bytes are retrieved, and the return value of the function is set
to maxlen. The remaining bytes are left on the stream head read queue .
•If maxlen is set to 0, and there is a zero length control or data message in the buffer, the zero-length part
is removed from the stream head read queue.
Message Priorities and Bands
By default, getmsg (2) retrieves the first message from the stream head. However, a process can retrieve only
high-priority messages by setting the flagsp argument to RS_HIPRI. In this case, getmsg (2) will only retrieve
high priority messages. A flagsp value of 0 will cause getmsg (2) to read all messages from the stream.
The getmsg (2) system call enables the user applications to select between high priority and ordinary
messages. It operates in the Read all messages and Read High priority messages modes. If an application
needs finer control over ordinary messages, the getpmsg (2) call should be used.
By default, getpmsg (2) will also process the first available message on the stream. However, the flagsp for
getpmsg (2) is a bitwise-OR of the three mutually exclusive constants MSG_HIPRI, MSG_BAND, and MSG_ANY.
The following list describes the combination of flagsp and bandp values that enable the user application to
select different groups of messages:
• An application can retrieve only high-priority message by setting flagsp to MSG_HIPRI and bandp to 0.
getpmsg (2) reads only high priority messages from the stream, and leave the rest of the messages on the
stream. The bandp value is ignored.
• An application can retrieve messages for a particular priority band by setting flagsp to MSG_BAND and
bandp to the desired band priority value. Band messages fall into priority bands ranging from 1 to 255.
The getpmsg (2) system call processes the next message only if it is a band priority value equal to or
greater than the specified bandp value, or if it is a high priority message. All other messages are left on
the stream.
• If a process must retrieve the first message, set the integer pointed by bandp to zero and flagsp to
MSG_ANY.
•If O_NONBLOCK is not set, getmsg() and getpmsg() does not block until a message of the type specified by
flagsp is available at the front of the stream head read queue. If O_NONBLOCK is set and a message of the
specified type is not present at the front of the stream head read queue, getmsg() and getpmsg() fail and
set errno to [EAGAIN].