STREAMS-UX Programmer's Guide (February 2007)

STREAMS Mechanism and System Calls
Writing to a Stream
Chapter 2
22
The minimum and maximum acceptable STREAMS packet sizes are defined by the topmost module in the
stream. A STREAMS packet is a segment of a message written to the stream. The length of a packet must be
less than or equal to the maximum packet size defined in the topmost module.
The following conditions apply to STREAMS packet size:
•If nbytes falls within the packet size range, nbytes will be written.
•If nbytes exceeds the maximum packet size, and the minimum packet size value is 0, write (2) will split
the input buffer into segments of the maximum allowed packet size, and send them downstream. The last
segment can be less than the maximum packet size.
•If nbytes is not within the acceptable packet size range, and the minimum packet size value is not 0,
write (2) fails with an appropriate errno.
• write (2) enables the user application to write zero-length messages to a regular stream. The concept of
zero-length messages may be relevant to some applications that want to use them as terminators and
associated conditions. write (2) of a zero-length message to a STREAMS-based pipe writes nothing to the
pipe, and still returns a 0 back to the application. The I_SWROPT ioctl (2) command overrides this default
behavior. Appendix A, “STREAMS IOCTL Commands,” describes the relevant ioctl (2) commands.
Streams Flow Control Conditions
A stream can encounter internal limits when applications attempt to write new messages to it. The following
conditions should be noted for STREAMS write (2) calls:
• If the stream was opened without the O_NDELAY or O_NONBLOCK flag, and the buffer is either not written to
the stream at all or partially written to the stream when the stream-full condition occurs, write (2) will
block until data can be accepted.
• If the stream was opened with the O_NDELAY or O_NONBLOCK flag, and the stream-full condition occurs
before any data from the buffer is written to the stream, write (2) will return -1, and set errno
appropriately.
• If the stream was opened with the O_NDELAY or O_NONBLOCK flag and the buffer has been partially written
when the stream-full condition occurs, write (2) will successfully terminate and return to the application
with the actual number of bytes written to the stream.
In many respects, a write (2) operation to a STREAMS device (i.e., to a stream opened on a STREAMS device)
is identical with write (2) on a file.