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 .MR fork (2)
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 .MR 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 \*9/src/lib9/pipe.c
61 .SH SEE ALSO
62 .MR intro (3) ,
63 .MR read (3)
64 .SH DIAGNOSTICS
65 Sets
66 .IR errstr .
67 .SH BUGS
68 If a read or a write of a pipe is interrupted, some unknown
69 number of bytes may have been transferred.
70 .PP
71 .I Pipe
72 is a macro defined as
73 .I p9pipe
74 to avoid name conflicts with Unix's
75 .I pipe
76 system call.
77 .PP
78 Unix pipes are not guaranteed to be bidirectional.
79 In order to ensure a bidirectional channel,
80 .I p9pipe
81 creates Unix domain sockets via the
82 .MR socketpair (2)
83 instead of Unix pipes.
84 .PP
85 The implementation of pipes as Unix domain sockets
86 causes problems with some Unix implementations of
87 .BR /dev/fd ,
88 Unix's dup device.  If a Unix domain socket is open as file
89 descriptor 0, some implementations disallow the opening of
90 .BR /dev/fd/0 ;
91 instead one must
92 .MR connect (2)
93 to it.
94 If this functionality is important
95 (as it is for
96 .MR rc (1) ),
97 one must
98 .B #undef
99 .B pipe
100 and fall back on the (possibly unidirectional) Unix pipes.