pipe.3 (2219B)
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.