STREAMS

STREAMS provides a uniform mechanism for implementing networking services and other character-based I/O. The STREAMS interface provides direct access to protocol modules. A STREAM is typically a full-duplex connection between a process and an open device or pseudo-device. However, since pipes may be STREAMS-based, a STREAM can be a full-duplex connection between two processes. The STREAM itself exists entirely within the implementation and provides a general character I/O interface for processes. It optionally includes one or more intermediate processing modules that are interposed between the process end of the STREAM (STREAM head) and a device driver at the end of the STREAM (STREAM end).

STREAMS I/O is based on messages. Messages flow in both directions in a STREAM. A given module need not understand and process every message in the STREAM, but every module in the STREAM handles every message. Each module accepts messages from one of its neighbour modules in the STREAM, and passes them to the other neighbour. For example, a line discipline module may transform the data. Data flow through the intermediate modules is bidirectional, with all modules handling, and optionally processing, all messages. There are three types of messages:

• data messages containing actual data for input or output

• control data containing instructions for the STREAMS modules and underlying implementation

• other messages, which include file descriptors.

The interface between the STREAM and the rest of the implementation is provided by a set of functions at the STREAM head. When a process calls write(), putmsg(), putpmsg() or ioctl(), messages are sent down the STREAM, and read(), getmsg() or getpmsg() accepts data from the STREAM and passes it to a process. Data intended for the device at the downstream end of the STREAM is packaged into messages and sent downstream, while data and signals from the device are composed into messages by the device driver and sent upstream to the STREAM head.

When a STREAMS-based device is opened, a STREAM is created that contains two modules: the STREAM head module and the STREAM end (driver) module. If pipes are STREAMS-based in an implementation, when a pipe is created, two STREAMS are created, each containing a STREAM head module. Other modules are added to the STREAM using ioctl(). New modules are "pushed" onto the STREAM one at a time in last-in, first-out (LIFO) style, as though the STREAM was a push-down stack.

 Priority

Message types are classified according to their queueing priority and may be normal (non-priority), priority, or high-priority messages. A message belongs to a particular priority band that determines its ordering when placed on a queue. Normal messages have a priority band of 0 and are always placed at the end of the queue following all other messages in the queue. High-priority messages are always placed at the head of the queue, but will be discarded if there is already a high-priority message in the queue. Their priority band is ignored; they are high-priority by virtue of their type. Priority messages have a priority band greater than 0. Priority messages are always placed after any messages of the same or higher priority. High-priority and priority messages are used to send control and data information outside the normal flow of control. By convention, high-priority messages are not affected by flow control. Normal and priority messages have separate flow controls.

 Message Parts

A process may access STREAMS messages that contain a data part, control part, or both. The data part is that information which is transmitted over the communication medium and the control information is used by the local STREAMS modules. The other types of messages are used between modules and are not accessible to processes. Messages containing only a data part are accessible via putmsg(), putpmsg(), getmsg(), getpmsg(), read() or write(). Messages containing a control part with or without a data part are accessible via calls to putmsg(), putpmsg(), getmsg() or getpmsg().

 Accessing STREAMS

A process accesses STREAMS-based files using the standard functions open(), close(), read(), write(), ioctl(), pipe(), putmsg(), putpmsg(), getmsg(), getpmsg() or poll(). Refer to the applicable function definitions for general properties and errors.

Calls to ioctl() are used to perform control functions with the STREAMS-based device associated with the file descriptor fildes. The arguments command and arg are passed to the STREAMS file designated by fildes and are interpreted by the STREAM head. Certain combinations of these arguments may be passed to a module or driver in the STREAM.

Since these STREAMS requests are a subset of ioctl(), they are subject to the errors described there.

STREAMS modules and drivers can detect errors, sending an error message to the STREAM head, thus causing subsequent functions to fail and set errno to the value specified in the message. In addition, STREAMS modules and drivers can elect to fail a particular ioctl() request alone by sending a negative acknowledgement message to the STREAM head. This causes just the pending ioctl() request to fail and set errno to the value specified in the message.