STREAMS-UX Programmer's Guide (February 2007)

STREAMS Mechanism and System Calls
Reading From a Stream
Chapter 2
26
read (2) ignores message boundaries. It continues to retrieve data from the stream until the
requested number of bytes is retrieved, there is no more data to be retrieved, or a
zero-length message is encountered in the stream.
If read (2) terminates on finding a zero-length message, it will place that message block
back on the stream to be retrieved by next read (2) call. read (2) then returns the control
back to the calling application. However, if a zero-byte message is read as the first message
on a STREAM, the message is removed from the STREAM and zero is returned, regardless
of the read mode.
Message Nondiscard Mode:
The read (2) system call will retrieve data from the stream until the requested number of
bytes have been retrieved, or a message boundary is encountered.
If bytes remain in the current message at the end of a successful read (2) system call, they
are left in the STREAM. Those bytes will be retrieved by a subsequent read (2).
If a zero-byte message is read as the first message on a STREAM, the message is removed
from the STREAM and zero is returned. If the zero-length message is not a first message,
read (2) discards that message and continues to read the next message.
Message Discard Mode:
This mode differs from the message nondiscard mode in the way partially read messages
are handled. If bytes remain in the current message at the end of a successful read, they are
discarded. A subsequent read (2) call begins at the next message boundary.
Zero-length messages are handled in the same manner as in the corresponding
message-nondiscard mode.
The choice of read modes depends on the desired user application functionality. Most
applications need to read all the data from a stream. This makes the byte-stream mode the
most commonly used option.
Control Modes
Control Normal Mode:
The default control mode. It enables read (2) to process data only. read (2) fails if a message
containing a control part is encountered. This default action can be changed by placing the
stream in either control data mode or control discard mode with the I_SRDOPT ioctl (2) call.
Control Data Mode:
Enables read (2) to convert the control part of the message to data and send it back to the
calling application. This mode has limited use. Most applications that need to retrieve
control information will use getmsg (2) or getpmsg (2).
Control Discard Mode:
Enables read (2) to discard the control part of a message and continues to read the data
part. This mode is useful for applications that have to use read (2), and the stream head
read-queue contains messages with both control and data components.