1 cfa37a7b 2004-04-10 devnull .TH PIPE 3
  2 cfa37a7b 2004-04-10 devnull .SH NAME
  3 cfa37a7b 2004-04-10 devnull pipe \- create an interprocess channel
  4 cfa37a7b 2004-04-10 devnull .SH SYNOPSIS
  5 cfa37a7b 2004-04-10 devnull .B #include <u.h>
  6 cfa37a7b 2004-04-10 devnull .br
  7 cfa37a7b 2004-04-10 devnull .B #include <libc.h>
  8 cfa37a7b 2004-04-10 devnull .PP
  9 cfa37a7b 2004-04-10 devnull .B
 10 cfa37a7b 2004-04-10 devnull int pipe(int fd[2])
 11 cfa37a7b 2004-04-10 devnull .SH DESCRIPTION
 12 cfa37a7b 2004-04-10 devnull .I Pipe
 13 cfa37a7b 2004-04-10 devnull creates a buffered channel for interprocess I/O communication.
 14 cfa37a7b 2004-04-10 devnull Two file descriptors are returned in
 15 cfa37a7b 2004-04-10 devnull .IR fd .
 16 cfa37a7b 2004-04-10 devnull Data written to
 17 cfa37a7b 2004-04-10 devnull .B fd[1]
 18 cfa37a7b 2004-04-10 devnull is available for reading from
 19 cfa37a7b 2004-04-10 devnull .B fd[0]
 20 cfa37a7b 2004-04-10 devnull and data written to
 21 cfa37a7b 2004-04-10 devnull .B fd[0]
 22 cfa37a7b 2004-04-10 devnull is available for reading from
 23 cfa37a7b 2004-04-10 devnull .BR fd[1] .
 24 cfa37a7b 2004-04-10 devnull .PP
 25 cfa37a7b 2004-04-10 devnull After the pipe has been established,
 26 cfa37a7b 2004-04-10 devnull cooperating processes
 27 cfa37a7b 2004-04-10 devnull created by subsequent
 28 d32deab1 2020-08-16 rsc .MR fork (2)
 29 cfa37a7b 2004-04-10 devnull calls may pass data through the
 30 cfa37a7b 2004-04-10 devnull pipe with
 31 cfa37a7b 2004-04-10 devnull .I read
 32 cfa37a7b 2004-04-10 devnull and
 33 cfa37a7b 2004-04-10 devnull .I write
 34 cfa37a7b 2004-04-10 devnull calls.
 35 058b0118 2005-01-03 devnull .\" The bytes placed on a pipe
 36 058b0118 2005-01-03 devnull .\" by one 
 37 058b0118 2005-01-03 devnull .\" .I write
 38 058b0118 2005-01-03 devnull .\" are contiguous even if many processes are writing.
 39 058b0118 2005-01-03 devnull .\" Write boundaries are preserved: each read terminates
 40 058b0118 2005-01-03 devnull .\" when the read buffer is full or after reading the last byte
 41 058b0118 2005-01-03 devnull .\" of a write, whichever comes first.
 42 058b0118 2005-01-03 devnull .\" .PP
 43 058b0118 2005-01-03 devnull .\" The number of bytes available to a
 44 058b0118 2005-01-03 devnull .\" .IR read (3)
 45 058b0118 2005-01-03 devnull .\" is reported
 46 058b0118 2005-01-03 devnull .\" in the
 47 058b0118 2005-01-03 devnull .\" .B Length
 48 058b0118 2005-01-03 devnull .\" field returned by
 49 058b0118 2005-01-03 devnull .\" .I fstat
 50 058b0118 2005-01-03 devnull .\" or
 51 058b0118 2005-01-03 devnull .\" .I dirfstat
 52 058b0118 2005-01-03 devnull .\" on a pipe (see
 53 058b0118 2005-01-03 devnull .\" .IR stat (3)).
 54 cfa37a7b 2004-04-10 devnull .PP
 55 cfa37a7b 2004-04-10 devnull When all the data has been read from a pipe and the writer has closed the pipe or exited,
 56 d32deab1 2020-08-16 rsc .MR read (3)
 57 cfa37a7b 2004-04-10 devnull will return 0 bytes.  Writes to a pipe with no reader will generate a note
 58 cfa37a7b 2004-04-10 devnull .BR "sys: write on closed pipe" .
 59 cfa37a7b 2004-04-10 devnull .SH SOURCE
 60 c3674de4 2005-01-11 devnull .B \*9/src/lib9/pipe.c
 61 cfa37a7b 2004-04-10 devnull .SH SEE ALSO
 62 d32deab1 2020-08-16 rsc .MR intro (3) ,
 63 d32deab1 2020-08-16 rsc .MR read (3)
 64 cfa37a7b 2004-04-10 devnull .SH DIAGNOSTICS
 65 cfa37a7b 2004-04-10 devnull Sets
 66 cfa37a7b 2004-04-10 devnull .IR errstr .
 67 cfa37a7b 2004-04-10 devnull .SH BUGS
 68 cfa37a7b 2004-04-10 devnull If a read or a write of a pipe is interrupted, some unknown
 69 cfa37a7b 2004-04-10 devnull number of bytes may have been transferred.
 70 058b0118 2005-01-03 devnull .PP
 71 058b0118 2005-01-03 devnull .I Pipe
 72 058b0118 2005-01-03 devnull is a macro defined as
 73 058b0118 2005-01-03 devnull .I p9pipe
 74 058b0118 2005-01-03 devnull to avoid name conflicts with Unix's
 75 058b0118 2005-01-03 devnull .I pipe
 76 058b0118 2005-01-03 devnull system call.
 77 058b0118 2005-01-03 devnull .PP
 78 058b0118 2005-01-03 devnull Unix pipes are not guaranteed to be bidirectional.
 79 058b0118 2005-01-03 devnull In order to ensure a bidirectional channel,
 80 058b0118 2005-01-03 devnull .I p9pipe
 81 058b0118 2005-01-03 devnull creates Unix domain sockets via the
 82 d32deab1 2020-08-16 rsc .MR socketpair (2)
 83 058b0118 2005-01-03 devnull instead of Unix pipes.
 84 058b0118 2005-01-03 devnull .PP
 85 058b0118 2005-01-03 devnull The implementation of pipes as Unix domain sockets
 86 058b0118 2005-01-03 devnull causes problems with some Unix implementations of
 87 058b0118 2005-01-03 devnull .BR /dev/fd ,
 88 058b0118 2005-01-03 devnull Unix's dup device.  If a Unix domain socket is open as file
 89 058b0118 2005-01-03 devnull descriptor 0, some implementations disallow the opening of
 90 058b0118 2005-01-03 devnull .BR /dev/fd/0 ;
 91 058b0118 2005-01-03 devnull instead one must
 92 d32deab1 2020-08-16 rsc .MR connect (2)
 93 058b0118 2005-01-03 devnull to it.
 94 058b0118 2005-01-03 devnull If this functionality is important
 95 058b0118 2005-01-03 devnull (as it is for
 96 d32deab1 2020-08-16 rsc .MR rc (1) ),
 97 058b0118 2005-01-03 devnull one must
 98 058b0118 2005-01-03 devnull .B #undef
 99 058b0118 2005-01-03 devnull .B pipe
100 058b0118 2005-01-03 devnull and fall back on the (possibly unidirectional) Unix pipes.