stream(2) stream(2)
NAME [Toc] [Back]
stream - STREAMS enhancements to standard system calls
DESCRIPTION [Toc] [Back]
The open(), close(), read(), readv(), write(), writev(), ioctl(),
select(), and signal() system calls are enhanced to support STREAMS.
The new functionality is described below for each system call.
Open Enhancements [Toc] [Back]
When calling open for a STREAMS device, the oflag parameter can only
be constructed from the O_NONBLOCK flag values that are OR-ed with the
O_RDONLY, O_WRONLY, or O_RDWR flag values. The values of the other
flags are not applicable to STREAMS devices and have no effect on
them.
The values of the O_NONBLOCK flags affect the operations of STREAMSbased
device drivers, when the read(), write(), getmsg(), getpmsg(),
putmsg(), or putpmsg() functions are used. After the stream is open,
these flags can be modified by calling fcntl() (see the fcntl(2) man
page). The effects of the flags are device specific.
The open of a STREAMS device may fail for one or more of the following
STREAMS-specific conditions:
EIO A hangup occurred while the open() function was
attempting to open the stream.
EAGAIN The system was unable to allocate a stream.
ENODEV The device has not been generated into the system as
a STREAMS device.
ENXIO The open routine of one of the modules or drivers in
the stream failed.
Close Enhancements [Toc] [Back]
When all file descriptors associated with a STREAMS device have been
closed, the stream is dismantled. If the file descriptor is
associated with a stream that is subject to persistent links, the
close() function will succeed immediately, but the stream will remain
open. See I_PLINK documentation in streamio(7). Dismantling includes
popping any modules on the stream and closing the driver. If
O_NONBLOCK flag is set, and there are no signals posted for the
stream, the close() function waits for output to drain on each
module's or driver's non-empty write queue. close() waits for each
module or driver for the amount of time set by the I_SETCLTIME ioctl()
(see the streamio(7) man page). The default is 15 seconds per module
or driver. If the O_NONBLOCK flag is set, or there are any pending
signals, the function does not wait for output to drain and dismantles
the stream immediately. If a STREAMS device is closed, and the
calling process had previously registered to recieve a SIGPOLL signal
Hewlett-Packard Company - 1 - HP-UX 11i Version 2: August 2003
stream(2) stream(2)
for events associated with that device (see "Signal Enhancements"
below), close() unregisters the calling process for the events
associated with the stream.
Read and Readv Enhancements [Toc] [Back]
In this section, read() refers to both read() and readv(). For
STREAMS devices, the read() function operates in accordance with the
read mode of the file. STREAMS has three read modes: byte-stream mode,
message-nondiscard mode, and message-discard mode. The default is
byte-stream mode; however, the user can change this by issuing the
I_SRDOPT ioctl() call. The user can also test for the current read
mode by issuing the I_GRDOPT ioctl() call. See the streamio(7) man
page for more information about these ioctl() calls. The read()
function's behavior in each of the read modes of a STREAMS device is
as follows:
+ In byte-stream mode, the function retrieves data from the
stream associated with the file descriptor until it has
retrieved nbyte bytes, or until there is no more data to be
retrieved.
+ In message-nondiscard mode, the function retrieves data until
it reaches a message boundary. If it does not retrieve all of
the data in the message, it places the remaining data back on
the stream. This data can be retrieved by a subsequent
read(), getmsg(), or getpmsg() call.
+ In message-discard mode, the function retrieves data until it
has retrieved nbytes, or until it has reached a message
boundary. However, unread data remaining in the message is
discarded and is not available for reading by a subsequent
read(), getmsg(), or getpmsg() call.
When attempting to read a STREAMS device and encountering a zero-byte
message:
+ If the read mode is byte-stream, the read() function returns
the number of bytes of data read before encountering the
zero-byte message. If data was read before receiving the
zero-byte message, read() returns the zero-byte message to the
stream so it can be processed by a subsequent read(),
getmsg(), or getpmsg() 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.
Hewlett-Packard Company - 2 - HP-UX 11i Version 2: August 2003
stream(2) stream(2)
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 messages only.
The following is also true for reads to STREAMS devices. If the
O_NONBLOCK flag is clear, and no message 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 [Toc] [Back]
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.
Hewlett-Packard Company - 3 - HP-UX 11i Version 2: August 2003
stream(2) stream(2)
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 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() function terminates 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:
EAGAIN The O_NONBLOCK flag is set, and the stream cannot
accept write() data because it is flow controlled.
EINVAL The write() function attempts to write to a stream
that is linked below a multiplexor.
ENXIO A hangup occurs on a stream while the write()
function is writing to the stream.
ERANGE The nbytes parameter is not within the allowable
range.
The write() system call will also fail if an error message has been
received at the stream head of the stream to which the write()
function is attempting to write. In this case, the function returns
with errno set to the value included in the error message.
Ioctl Enhancements [Toc] [Back]
Hewlett-Packard Company - 4 - HP-UX 11i Version 2: August 2003
stream(2) stream(2)
Refer to the streamio(7) man page for a description of STREAMS ioctl()
functionality.
Select Enhancements [Toc] [Back]
The select() system call checks the status of STREAMS devices.
select() does not provide as much information for STREAMS devices as
poll(). A program calls select() so that it can wait for events on
both STREAMS and non-STREAMS devices. If select() returns an event
for a STREAMS device, the program can call poll() to get more
information. Refer to the poll(2) man page for more information about
poll().
select() returns a read event if a poll() POLLIN, POLLERR, POLLNVAL or
POLLHUP event exists on the stream. In other words, select() returns
a read event if a normal or priority band message is waiting to be
read, if a read error exists at the stream head, if a write error
exists at the stream head, if the stream is linked under a
multiplexor, or if a hang-up has occurred.
select() returns a write event if a poll() POLLOUT, POLLWRNORM,
POLLERR, or POLLNVAL event exists on the stream. This means that
select() returns a write event if normal data can be written without
blocking because of flow control, a read error exists at the stream
head, a write error exists at the stream head, or the stream is linked
under a multiplexor.
select() returns an exception event if a poll() POLLPRI event exists
on the stream. More specifically, select() returns an exception event
if a high-priority message is waiting to be read.
Signal Enhancements [Toc] [Back]
A new signal, SIGPOLL, has been added for STREAMS. Processes register
to receive a SIGPOLL signal for events that occur on a STREAMS device
(see the signal(2) man page and I_SETSIG in the streamio(7) man page).
The default action is to ignore the signal, not to terminate the
process.
SEE ALSO [Toc] [Back]
close(2), fcntl(2), getmsg(2), open(2), poll(2), putmsg(2), read(2),
signal(2), select(2), write(2), streamio(7), and STREAMS/UX for HP9000
Reference Manual.
Hewlett-Packard Company - 5 - HP-UX 11i Version 2: August 2003 [ Back ] |
