plan9port/man/man3/pipe.3

.TH PIPE 3
.SH NAME
pipe \- create an interprocess channel
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.PP
.B
int pipe(int fd[2])
.SH DESCRIPTION
.I Pipe
creates a buffered channel for interprocess I/O communication.
Two file descriptors are returned in
.IR fd .
Data written to
.B fd[1]
is available for reading from
.B fd[0]
and data written to
.B fd[0]
is available for reading from
.BR fd[1] .
.PP
After the pipe has been established,
cooperating processes
created by subsequent
.MR fork (2)
calls may pass data through the
pipe with
.I read
and
.I write
calls.
.\" The bytes placed on a pipe
.\" by one 
.\" .I write
.\" are contiguous even if many processes are writing.
.\" Write boundaries are preserved: each read terminates
.\" when the read buffer is full or after reading the last byte
.\" of a write, whichever comes first.
.\" .PP
.\" The number of bytes available to a
.\" .IR read (3)
.\" is reported
.\" in the
.\" .B Length
.\" field returned by
.\" .I fstat
.\" or
.\" .I dirfstat
.\" on a pipe (see
.\" .IR stat (3)).
.PP
When all the data has been read from a pipe and the writer has closed the pipe or exited,
.MR read (3)
will return 0 bytes.  Writes to a pipe with no reader will generate a note
.BR "sys: write on closed pipe" .
.SH SOURCE
.B \*9/src/lib9/pipe.c
.SH SEE ALSO
.MR intro (3) ,
.MR read (3)
.SH DIAGNOSTICS
Sets
.IR errstr .
.SH BUGS
If a read or a write of a pipe is interrupted, some unknown
number of bytes may have been transferred.
.PP
.I Pipe
is a macro defined as
.I p9pipe
to avoid name conflicts with Unix's
.I pipe
system call.
.PP
Unix pipes are not guaranteed to be bidirectional.
In order to ensure a bidirectional channel,
.I p9pipe
creates Unix domain sockets via the
.MR socketpair (2)
instead of Unix pipes.
.PP
The implementation of pipes as Unix domain sockets
causes problems with some Unix implementations of
.BR /dev/fd ,
Unix's dup device.  If a Unix domain socket is open as file
descriptor 0, some implementations disallow the opening of
.BR /dev/fd/0 ;
instead one must
.MR connect (2)
to it.
If this functionality is important
(as it is for
.MR rc (1) ),
one must
.B #undef
.B pipe
and fall back on the (possibly unidirectional) Unix pipes.