stream.2 (2010 09)

s
stream(2) stream(2)
subsequent read(), getmsg(),orgetpmsg()
call. If no data was read, read() consumes
the message.
• If the read mode is message-discard or message-nondiscard, the
read() function returns zero,
and then consumes the message.
The
read() function reads the data at the front of the stream head read queue. It reads both priority
band and normal data.
The
read() function processes control messages according to the STREAMS read flags:
RPROTNORM,
RPROTDAT, and RPROTDIS. The default is for
RPROTNORM to be set; however, the user can change this
by issuing the
I_SRDOPT ioctl() call. The
read() function’s behavior for each read flag is described
below:
• If
RPROTNORM is set, a read from a stream can only process data messages. It cannot process
any type of control message and fails if such a message is encountered at the stream head.
• If
RPROTDAT is set, read() processes both data and control messages. The
read() function
delivers data in both data and control messages.
• If
RPROTDIS is set, read() consumes any control messages and retrieves data from data mes-
sages only.
The following is also true for reads to STREAMS devices. If the
O_NONBLOCK flag is clear, and no mes-
sage is waiting to be read on the stream, the read() function blocks until a message arrives at the
stream head. If the O_NONBLOCK flag is set, and no message is waiting to be read on the stream, the
read() function fails and returns [ERANGE].
A read from a STREAMS device may fail for one or more of the following STREAMS-specific conditions:
[EAGAIN] No message is waiting to be read on the stream, and the
O_NONBLOCK flag is set.
[EBADMSG] A message is waiting to be read, but it is not a data message and the
RPROTNORM
flag is set.
[EINVAL] The stream is linked to a multiplexor.
A read from a STREAMS device also fails if an error message is received at the stream head. In this case,
errno is set to the value returned in the error message.
If a hangup occurs on the stream being read, the
read() function continues its operations until the
stream read queues are empty. Thereafter, it returns a value of 0 (zero).
Write and Writev Enhancements
In this section,
write() refers to both write() and writev(). When writing to a STREAMS device,
the write() function sends ordinary, priority band zero, data. Other aspects of the write() function’s
behavior are determined by the packet size that the stream will accept.
If nbytes is not within the top module’s minimum and maximum packet size range,
write() will return
[ERANGE]. Two exceptions exist, however, in which
write() does not return an error. The first excep-
tion is if nbytes is too large and either the maximum packet size is infinite or the minimum packet size is
less than or equal to zero. The second exception occurs if nbytes is too small and the minimum packet
size is less than or equal to zero. With either exception, write() does not return [ERANGE], and
transfers the data.
The
write() function may send the user’s data buffer in multiple messages. The maximum amount of
data that write() sends in one message is the lower value of the top module’s maximum packet size and
STRMSGSZ. If the maximum packet size is infinite, write() compares half of the top module’s high
water mark to STRMSGSZ instead. If the high water mark is less than or equal to zero, the page size is
used.
If a zero-length buffer (nbytes is 0) is passed to
write(), zero bytes are sent to the stream and zero
bytes are returned.
The following is also true for writes to STREAMS devices. If the
O_NONBLOCK flag is clear, and the
stream cannot accept data (the stream head write queue is full due to flow control conditions), the
write() function blocks until data can be accepted. If the O_NONBLOCK flag is set, and the stream
cannot accept data, the write() function fails, and returns [EAGAIN]. If the O_NONBLOCK flag is set,
and the stream cannot accept data, but part of the buffer has already been written, the write() func-
tion terminates and returns the number of bytes written.
2 Hewlett-Packard Company − 2 − HP-UX 11i Version 3: September 2010