STREAMS Programming Guide

Chapter 6 Pipes and Queues

This chapter covers communication between processes using STREAMS-based pipes and named pipes. Discussion is limited to communications between applications.

Overview of Pipes and FIFOs

A pipe in the SunOS 5.6 system is a mechanism that provides a communication path between multiple processes. Prior to SunOS 5.0, SunOS had standard pipes and named pipes (also called FIFOs). With standard pipes, one end was opened for reading and the other end for writing, so data flow was unidirectional. FIFOs had only one end and typically one process opened the file for reading and another process opened the file for writing. Data written into the FIFO by the writer could then be read by the reader.

To provide greater support and development flexibility for networked applications, pipes and FIFOs are STREAMS-based in SunOS 5. The interface is unchanged but the underlying implementation is changed. When a pipe is created through the pipe(2) interface, two Streams are opened and connected. Data flow is serial.

The remainder of this chapter uses the terms pipe and STREAMS-based pipe interchangeably to mean a STREAMS-based pipe.

Note -

After both ends of a FIFO have been opened, there is no guarantee that further calls to open() O_RDONLY (O_WRONLY) will synchronize with later calls to open() O_WRONLY (O_RDONLY) until both ends of the FIFO have been closed by all readers and writers. Any data written into a FIFO will be lost if both ends of the FIFO are closed before the data is read.

Creating and Opening Pipes and FIFOs

A named pipe, also called a FIFO, is a pipe identified by an entry in a file system's name space. FIFOs are created using mknod(2), mkfifo(3C), or the mknod(1M) command. They are removed using unlink(2) or the rm(1) command.

FIFOs look like regular file system nodes, but are distinguished from them by a p in the first column when the ls -l command is run.

	/usr/sbin/mknod xxx pls -l xxx
prw-r--r-- 1 guest other 0 Aug 26 10:55 xxx
echoput>>xxx &put>
[1] 8733
cat xxx
hello world
[1]  + Done
rm xxx

FIFOs are unidirectional: that is, one end of the FIFO is used for writing data, the other for reading data. FIFOs allow simple one-way interprocess communication between unrelated processes. Modules may be pushed onto a FIFO. Data written to the FIFO is passed down the write side of the module and back up the read side as shown in Figure 6-1.

Figure 6-1 Pushing Modules on a STREAMS-based FIFO


FIFOs are opened in the same manner as other file system nodes with open(2). Any data written to the FIFO can be read from the same file descriptor in the first-in, first-out manner (serial, sequentially). Modules can also be pushed on the FIFO. See open(2) for the restrictions that apply when opening a FIFO. If O_NDELAY or O_NONBLOCK is not specified, an open on a FIFO blocks until both a reader and a writer are present.

Named or mounted Streams provide a more powerful interface for interprocess communications than does a FIFO. See "Named Streams" for details.

A STREAMS-based pipe, also referred to as an anonymous pipe, is created using pipe(2) which returns two file descriptors--fd[0] and fd[1], each with its own Stream head. The ends of the pipe are constructed so that data written to either end of a pipe may be read from the opposite end.

STREAMS modules can be added to a pipe with I_PUSH ioctl(2). A module can be pushed onto one or both ends of the pipe (see Figure 6-2). However, if a module is pushed onto one end of the pipe, that module cannot be popped from the other end.

Figure 6-2 Pushing Modules on a STREAMS-based Pipe


Using Pipes and FIFOs

Pipes and FIFOs can be accessed through the operating system routines read(2), write(2), ioctl(2), close(2), putmsg(2), putpmsg(2), getmsg(2), getpmsg(2), and poll(2). For FIFOs, open(2) is also used.

Reading From a Pipe or FIFO

read(2) or getmsg(2)) are used to read from a pipe or FIFO. Data can be read from either end of a pipe. On success, the read(2) returns the number of bytes read and buffered. When the end of the data is reached, read(2) returns 0.

When a user process attempts to read from an empty pipe (or FIFO), the following happens:

Writing to a Pipe or FIFO

When a user process calls write(2), data is sent down the associated Stream. If the pipe or FIFO is empty (no modules pushed), data written is placed on the read queue of the other Stream for pipes, and on the read queue of the same Stream for FIFOs. Since the size of a pipe is the number of unread data bytes, the written data is reflected in the size of the other end of the pipe.

Zero-Length Writes

If a user process issues write(2) with 0 as the number of bytes to send a pipe or FIFO, 0 is returned, and, by default, no message is sent down the Stream. However, if a user must send a zero-length message downstream, SNDZERO ioctl(2) can be used to change this default behavior. If SNDZERO is set in the Stream head, write(2) requests of 0 bytes generate a zero-length message and sends the message down the Stream. If SNDZERO is not set, no message is generated and 0 is returned to the user.

The SNDZERO bit may be changed by theI_SWROPT ioctl(2). If the arg in the ioctl(2) has SNDZERO set, the bit is turned on. If the arg is set to 0, the SNDZERO bit is turned off.

The I_GWROPT ioctl(2) is used to get the current write settings.

Atomic Writes

If multiple processes simultaneously write to the same pipe, data from one process can be interleaved with data from another process, if modules are pushed on the pipe or the write is greater than PIPE_BUF. The order of data written is not necessarily the order of data read. To ensure that writes of less than PIPE_BUF bytes are not interleaved with data written by other processes, any modules pushed on the pipe should have a maximum packet size of at least PIPE_BUF.

Note -

PIPE_BUF is an implementation-specific constant that specifies the maximum number of bytes that are atomic when writing to a pipe. When writing to a pipe, write requests of PIPE_BUF or fewer bytes are not interleaved with data from other processes doing writes to the same pipe. However, write requests of more than PIPE_BUF bytes may have data interleaved on arbitrary byte boundaries with writes by other processes whether or not the O_NONBLOCK or O_NDELAY flag is set.

If the module packet size is at least the size of PIPE_BUF, the Stream-head packages the data in such a way that the first message is at least PIPE_BUF bytes. The remaining data may be packaged into smaller or equal-sized blocks depending on buffer availability. If the first module on the Stream cannot support a packet of PIPE_BUF, atomic writes on the pipe cannot be guaranteed.

Closing a Pipe or FIFO

close(2) closes a pipe or FIFO and dismantles its associated Streams. On the last close of one end of a pipe, an M_HANGUP message is sent to the other end of the pipe. Subsequent read(2) or getmsg(2) calls on that Stream head return the number of bytes read and zero when there are no more data. Subsequent write(2) or putmsg(2) requests fail with errno set to EPIPE. If the other end of the pipe is mounted, the last close of the pipe forces it to be unmounted.

Flushing Pipes and FIFOs

When the flush request is initiated from an ioctl(2) or from flushq(9F), the FLUSHR or the FLUSHW bits of an M_FLUSH message must be switched. Bits are switchedd at the point where the M_FLUSH message is passed from a write queue to a read queue. This point is also known as the midpoint of the pipe.

The midpoint of a pipe is not always easily detectable, especially if there are numerous modules pushed on either end of the pipe. In that case, some mechanism needs to intercept all messages passing through the Stream. If the message is an M_FLUSH message and it is at the Stream midpoint, the flush bits need to be switched.

This bit switching is handled by the pipemod module. pipemod should be pushed onto a pipe or FIFO where flushing of any kind will take place. The pipemod(7M) module can be pushed on either end of the pipe. The only requirement is that it is pushed onto an end that previously did not have modules on it. That is, pipemod(7M) must be the first module pushed onto a pipe so that it is at the midpoint of the pipe itself.

The pipemod(7M) module handles only M_FLUSH messages. All other messages are passed to the next module using the putnext(9F) utility routine. If an M_FLUSH message is passed to pipemod(7M) and the FLUSHR and FLUSHW bits are set, the message is not processed but is passed to the next module using putnext(9F). If only the FLUSHR bit is set, it is turned off and the FLUSHW bit is set. The message is then passed to the next module, using putnext(9F). Similarly, if the FLUSHW bit was the only bit set in the M_FLUSH message, it is turned off and the FLUSHR bit is turned on. The message is then passed to the next module on the Stream.

The pipemod(7M) module can be pushed on any Stream if it requires the bit switching.

Named Streams

It can be useful to name a Stream or STREAMS-based pipe by associating the Stream with an existing node in the file system name space. This allows unrelated processes to open the pipe and exchange data with the application. The following interfaces support naming a Stream or STREAMS-based pipe.


Attaches a Stream file descriptor to a node in the file system name space, thus naming the Stream.


Detaches a named Stream file descriptor from its node in the file system name space, thus unnaming the Stream.


Tests whether a file descriptor is associated with a Stream.

Passing File Descriptors

Named Streams are useful for passing file descriptors between unrelated processes on the same machine. A user process can send a file descriptor to another process by invoking the I_SENDFD ioctl(2) on one end of a named Stream. This sends a message containing a file pointer to the Stream head at the other end of the pipe. Another process can retrieve the message containing the file pointer by a I_RECVFD ioctl(2) call on the other end of the pipe.

Unique Connections

With named pipes, client processes may communicate with a server process using the module connld that lets a client process get a unique, non-multiplexed connection to a server. The connld(7M) module can be pushed onto the named end of the pipe. If the named end of the pipe is then opened by a client, a new pipe is created. One file descriptor for the new pipe is passed back to a client (named Stream) as the file descriptor from open(2) and the other file descriptor is passed to the server using I_RECUFD ioctl(2). The server and the client may then communicate through a new pipe.

Figure 6-3 shows a server process that has created a pipe and pushed the connld module on the other end. The server then invokes the fattach(3C) routine to name the other end /usr/toserv.

Figure 6-3 Server Sets Up a Pipe


Figure 6-4 Processes X and Y Open /usr/toserv


When process X (procx) opens /usr/toserv, it gains a unique connection to the server process that was at one end of the original STREAMS-based pipe. When process Y (procy) does the same, it also gains a unique connection to the server. As shown in Figure 6-4, the server process has access to three separate pipes through three file descriptors.

connld(7M) is a STREAMS-based module that has open, close, and put procedures.

When the named Stream is opened, the open routine of connld(7M) is called. The open fails if:

The open is not complete and will block until the server process has received the file descriptor using the ioctl I_RECVFD. The setting of the O_NDELAY or O_NONBLOCK flag has no impact on the open.

connld(7M) does not process messages. All messages are passed to the next object in the Stream. The read, write, put routines call putnext(9F) to send the message up or down the Stream.