pipe - the pipe device

bind '#|' dir

dir/data
dir/data1

Description

The pipe device provides a mechanism for inter-process I/O. Two interfaces are provided, data and data1.

The interfaces are symmetric. A pair of pipes is provided.
The interfaces are cross-connected. Data written to one can be read back from the other.

Creating

A pipe is created by binding the pipe device into the namespace. The pipe device is specified by the vertical bar character, | (not a capital 'I' or '1' although they look similar in some typefaces).

bind '#|' dir

Each binding allocates a fresh pipe.

Opening

Opening the data or data1 file returns a file descriptor that can be used for input, output, or for obtaining information about the pipe.

Writing

Each write to a pipe deposits data that can be sequentially read on the other interface.

Message Boundaries and Atomicity

Each write to a pipe interface is preserved as a distinct message. The message boundaries will influence the grouping of data when the other pipe interface is read.

The maximum message size is 128*1024 bytes . Writes of larger amounts will be partitioned into messages of that size (plus any residual).

Multiple concurrent writers are guaranteed that their data will be written atomically as long as each write is less than the maximum message size. Large writes will be partitioned into multiple messages and those may be interleaved with the data from other writers.

Writers to pipe interfaces on remotely mounted portions of the namespace have their guarantee of atomicity lowered to that of the Styx protocol, 8*1024 bytes (Sys->ATOMICIO).

A write of zero bytes into a pipe will result in a zero-length message that will become part of the data sequence delivered to readers. A zero-length message is interpreted by readers as an EOF condition.

High Water Mark

If the level of unread data on a pipe exceeds a high water mark (currently 32*1024 bytes), any further writes will suspend the writing process until some reading process has reduced the amount of unread data to below the low water mark (currently half of the high water mark)

Reading

Reading one interface of a pipe returns data that was written to the other interface.

Data Order

Data is read sequentially, in the order written (fifo).

Reads are destructive. Once read, the pipe cannot be re-read to obtain the same data.

Random access is not allowed. The current position in these files is ignored. Operations by sys->seek have no effect.

Closed State

When the last reference to one of the FDs goes away, the pipe enters the closed state. In that state, remaining data can be read from the other end. An EOF condition is returned to the reader only if there is a writer at the other end of the pipe (unless there was an explicit write of zero bytes by the writer).

The following example illustrates that the cat command does not receive an EOF the first time around, because there is not a writer at the other end of the pipe. When more data is written to the pipe, the cat command receives an EOF and exits after writing the pipe data to standard output.

$ bind '#|' /tmp
$ cd /tmp
$ echo more > data
$ echo more > data
$ echo more > data
$ cat data1&
$ more
more
more
$ ps
       1        1        evb    release     1K Sh[$Sys]
      72       71        evb    release     2K Cat[$Sys]
      73        1        evb      ready     2K Ps[$Sys]
$ echo still more > data
still more
$ ps
       1        1        evb    release     1K Sh[$Sys]
      75        1        evb      ready     2K Ps[$Sys]

Writes to a closed pipe generate an exception with the message:

	write on closed pipe

Continued attempts to read a closed pipe will result in an error.

Pipe Status

Pipe attributes can be obtained by applying the stat (or fstat) system calls to either of the pipe interfaces.

The length member of the returned Dir adt represents the total byte count to be read on that interface. Thus, a write to one interface increases the length of the other.

The Dir adt also includes permissions for the interface. These permissions are not enforced by the pipe device.

De-allocation

A pipe persists until it is unmounted from the file to which it was bound. Open file descriptors to an unmounted pipe remain valid.

As long as it remains mounted, a pipe may be opened and used repeatedly for inter-process communcation. When all the FDs acquired from open calls have been closed again, the pipe returns to its original state, ready to be opened again.