1 .TH PIPE 3
2 .SH NAME
3 pipe \- create an interprocess channel
4 .SH SYNOPSIS
5 .B #include <u.h>
6 .br
7 .B #include <libc.h>
8 .PP
9 .B
10 int pipe(int fd[2])
11 .SH DESCRIPTION
12 .I Pipe
13 creates a buffered channel for interprocess I/O communication.
14 Two file descriptors are returned in
15 .IR fd .
16 Data written to
17 .B fd[1]
18 is available for reading from
19 .B fd[0]
20 and data written to
21 .B fd[0]
22 is available for reading from
23 .BR fd[1] .
24 .PP
25 After the pipe has been established,
26 cooperating processes
27 created by subsequent
28 .IR fork (3)
29 calls may pass data through the
30 pipe with
31 .I read
32 and
33 .I write
34 calls.
35 The bytes placed on a pipe
36 by one 
37 .I write
38 are contiguous even if many processes are writing.
39 Write boundaries are preserved: each read terminates
40 when the read buffer is full or after reading the last byte
41 of a write, whichever comes first.
42 .PP
43 The number of bytes available to a
44 .IR read (3)
45 is reported
46 in the
47 .B Length
48 field returned by
49 .I fstat
50 or
51 .I dirfstat
52 on a pipe (see
53 .IR stat (3)).
54 .PP
55 When all the data has been read from a pipe and the writer has closed the pipe or exited,
56 .IR read (3)
57 will return 0 bytes.  Writes to a pipe with no reader will generate a note
58 .BR "sys: write on closed pipe" .
59 .SH SOURCE
60 .B /sys/src/libc/9syscall
61 .SH SEE ALSO
62 .IR intro (3),
63 .IR read (3),
64 .IR pipe (3)
65 .SH DIAGNOSTICS
66 Sets
67 .IR errstr .
68 .SH BUGS
69 If a read or a write of a pipe is interrupted, some unknown
70 number of bytes may have been transferred.
71 .br
72 When a read from a pipe returns 0 bytes, it usually means end of file
73 but is indistinguishable from reading the result of an explicit
74 write of zero bytes.