HP-UX Reference (11i v1 00/12) - 2 System Calls (vol 5)

__________________________________________________________________________________________________________________________________________________________________________________________________
__________________________________________________________________________________________________________________________________________________________________________________________________
STANDARD Printed by: Nora Chuang [nchuang] STANDARD
/build/1111/BRICK/man2/!!!intro.2
________________________________________________________________
___ ___
s
stream(2) stream(2)
• 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 exception
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 can-
not 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() function ter-
minates and returns the number of bytes written.
A write to a STREAMS device may fail for one or more of the following STREAMS-specific conditions:
Section 2−−388 − 2 − HP-UX Release 11i: December 2000
___
___