stream(2)

Open Enhancements

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 STREAMS-based 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:

Close Enhancements

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 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

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:

When attempting to read a STREAMS device and encountering a zero-byte 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:

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:

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 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:

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

Refer to the streamio(7) man page for a description of STREAMS ioctl() functionality.

Select Enhancements

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

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.