stream(2)stream(2)NAME
stream: open(), close(), read(), readv(), write(), writev(), ioctl(),
select(), signal() - STREAMS enhancements to standard system calls
DESCRIPTION
The and system calls are enhanced to support STREAMS. The new func‐
tionality 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 flag values that are OR-ed with the or flag val‐
ues. The values of the other flags are not applicable to STREAMS
devices and have no effect on them.
The values of the flags affect the operations of STREAMS-based device
drivers, when the or functions are used. After the stream is open,
these flags can be modified by calling (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:
A hangup occurred while the
function was attempting to open the stream.
The system was unable to allocate a
stream.
The device has not been generated into the system as a
STREAMS device.
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 function will
succeed immediately, but the stream will remain open. See documenta‐
tion in streamio(7). Dismantling includes popping any modules on the
stream and closing the driver. If flag is set, and there are no sig‐
nals posted for the stream, the function waits for output to drain on
each module's or driver's non-empty write queue. waits for each module
or driver for the amount of time set by the (see the streamio(7) man
page). The default is 15 seconds per module or driver. If the 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 signal for events associated with that device (see "Signal
Enhancements" below), unregisters the calling process for the events
associated with the stream.
Read and Readv Enhancements
In this section, refers to both and For STREAMS devices, the function
operates in accordance with the read mode of the file. STREAMS has
three read modes: byte-stream mode, message-nondiscard mode, and mes‐
sage-discard mode. The default is byte-stream mode; however, the user
can change this by issuing the call. The user can also test for the
current read mode by issuing the call. See the streamio(7) man page
for more information about these calls. The 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 or
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 or
call.
When attempting to read a STREAMS device and encountering a zero-byte
message:
· If the read mode is byte-stream, the 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, returns the zero-byte message to the stream so
it can be processed by a subsequent or call. If no data was
read, consumes the message.
· If the read mode is message-discard or message-nondiscard,
the function returns zero, and then consumes the message.
The function reads the data at the front of the stream head read queue.
It reads both priority band and normal data.
The function processes control messages according to the STREAMS read
flags: and The default is for to be set; however, the user can change
this by issuing the call. The function's behavior for each read flag
is described below:
· If is set, a read from a stream can only process data mes‐
sages. It cannot process any type of control message and
fails if such a message is encountered at the stream head.
· If is set, processes both data and control messages. The
function delivers data in both data and control messages.
· If is set, consumes any control messages and retrieves data
from data messages only.
The following is also true for reads to STREAMS devices. If the flag
is clear, and no message is waiting to be read on the stream, the func‐
tion blocks until a message arrives at the stream head. If the flag is
set, and no message is waiting to be read on the stream, the function
fails and returns
A read from a STREAMS device may fail for one or more of the following
STREAMS-specific conditions:
No message is waiting to be read on the
stream, and the flag is set.
A message is waiting to be read, but it is not a data message
and the
flag is set.
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, is set to the value returned in the
error message.
If a hangup occurs on the stream being read, the 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, refers to both and When writing to a STREAMS device,
the function sends ordinary, priority band zero, data. Other aspects
of the 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, will return Two exceptions exist, however, in which 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, does not return and transfers the data.
The function may send the user's data buffer in multiple messages. The
maximum amount of data that sends in one message is the lower value of
the top module's maximum packet size and If the maximum packet size is
infinite, compares half of the top module's high water mark to 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 zero bytes are sent
to the stream and zero bytes are returned.
The following is also true for writes to STREAMS devices. If the flag
is clear, and the stream cannot accept data (the stream head write
queue is full due to flow control conditions), the function blocks
until data can be accepted. If the flag is set, and the stream cannot
accept data, the function fails, and returns If the flag is set, and
the stream cannot accept data, but part of the buffer has already been
written, the function terminates and returns the number of bytes writ‐
ten.
A write to a STREAMS device may fail for one or more of the following
STREAMS-specific conditions:
The flag is set, and the stream cannot accept data
because it is flow controlled.
The function attempts to write to a stream that is
linked below a multiplexor.
A hangup occurs on a
stream while the function is writing to the
stream.
The nbytes parameter is not within the allowable
range.
The system call will also fail if an error message has been received at
the stream head of the stream to which the function is attempting to
write. In this case, the function returns with set to the value
included in the error message.
Ioctl Enhancements
Refer to the streamio(7) man page for a description of STREAMS func‐
tionality.
Select Enhancements
The system call checks the status of STREAMS devices. does not provide
as much information for STREAMS devices as A program calls so that it
can wait for events on both STREAMS and non-STREAMS devices. If
returns an event for a STREAMS device, the program can call to get more
information. Refer to the poll(2) man page for more information about
returns a read event if a or event exists on the stream. In other
words, 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.
returns a write event if a or event exists on the stream. This means
that returns a write event if normal data can be written without block‐
ing 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.
returns an exception event if a event exists on the stream. More
specifically, returns an exception event if a high-priority message is
waiting to be read.
Signal Enhancements
A new signal, has been added for STREAMS. Processes register to
receive a signal for events that occur on a STREAMS device (see the
signal(2) man page and in the streamio(7) man page). The default
action is to ignore the signal, not to terminate the process.
SEE ALSOclose(2), fcntl(2), getmsg(2), open(2), poll(2), putmsg(2), read(2),
signal(2), select(2), write(2), streamio(7), and
stream(2)
