1 files changed, 74 insertions, 0 deletions
diff --git a/man/man3/pipe.3 b/man/man3/pipe.3
new file mode 100644
index 00000000..85bdfb2e
--- /dev/null
+++ b/man/man3/pipe.3
@@ -0,0 +1,74 @@
+.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
+.IR 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 (2)
+is reported
+in the
+.B Length
+field returned by
+.I fstat
+or
+.I dirfstat
+on a pipe (see
+.IR stat (2)).
+.PP
+When all the data has been read from a pipe and the writer has closed the pipe or exited,
+.IR read (2)
+will return 0 bytes.  Writes to a pipe with no reader will generate a note
+.BR "sys: write on closed pipe" .
+.SH SOURCE
+.B /sys/src/libc/9syscall
+.SH SEE ALSO
+.IR intro (2),
+.IR read (2),
+.IR pipe (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.
+.br
+When a read from a pipe returns 0 bytes, it usually means end of file
+but is indistinguishable from reading the result of an explicit
+write of zero bytes.