.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.