HP-UX Reference (11i v1 05/09) - 2 System Calls (vol 5)

s
stream(2) stream(2)
NAME
stream: open(), close(), read(), readv(), write(), writev(), ioctl(), select(), signal() - STREAMS enhancements
to standard system calls
DESCRIPTION
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
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,orO_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(),orputpmsg() 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
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). Dis-
mantling 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 dev-
ice (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() func-
tion 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 descrip-
tor 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(),orgetpmsg() 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(),orgetpmsg() 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 mes-
sage, read() returns the zero-byte message to the stream so it can be processed by a subsequent
HP-UX 11i Version 1: September 2005 − 1 − Hewlett-Packard Company Section 2−−409