diff options
Diffstat (limited to 'man/3/pipe')
| -rw-r--r-- | man/3/pipe | 69 |
1 files changed, 69 insertions, 0 deletions
diff --git a/man/3/pipe b/man/3/pipe new file mode 100644 index 00000000..494e57db --- /dev/null +++ b/man/3/pipe @@ -0,0 +1,69 @@ +.TH PIPE 3 +.SH NAME +pipe \- two-way interprocess communication +.SH SYNOPSIS +.nf +.BI "bind '#|'" dir +.IB dir /data +.IB dir /data1 +.fi +.SH DESCRIPTION +A pipe provides a mechanism for interprocess I/O by +reading and writing file descriptors (see +.IR sys-read (2)). +An +.IR attach (5), +typically via +.IR sys-pipe (2) +or +.IR sys-bind (2), +allocates two files that are cross-connected: +data written to one can be read back from the other, in the same order. +.PP +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. +In particular, a write of zero bytes will result in a zero-length read, +which is usually interpreted by readers as end-of-file, but could be used +to delimit the data stream for other purposes. +.PP +Written data is buffered by the kernel and stored on internal queues +(see +.IR qio (10.2)). +The maximum block size is 128k bytes; +larger writes will be split across several blocks, which are queued separately. +Each read will return data from at most one block. +Concurrent writers are therefore guaranteed that their data will not be interleaved +with data from other writers (ie, will be written atomically) only when +each write is less than the maximum buffer size. +Writers to pipe interfaces on remotely mounted portions of the namespace have their guarantee of atomicity lowered to +.BR Sys->ATOMICIO +bytes by +.IR mnt (3). +.PP +The system mediates between producer and consumer. +Writers will block when buffered data reaches a high-water mark, currently 32k bytes, +until a reader has reduced it by half. +The length returned by +.IR sys-stat (2) +on each name +gives the number of bytes waiting to be read on the corresponding end of the pipe. +.PP +When all file descriptors on +one side of the pipe have been closed, and after any remaining data has +been read, +a reader on the other side sees end-of-file (count of zero) on a subsequent read. +Once both ends are closed, the pipe can be reused. +.PP +A pipe persists until it is unmounted and no processes have either end open. +.SH SOURCE +.B /emu/port/devpipe.c +.br +.B /os/port/devpipe.c +.SH "SEE ALSO" +.IR sys-file2chan (2), +.IR sys-pipe (2) +.SH DIAGNOSTICS +Writes to a closed pipe generate an exception +.RB ` "write on closed pipe" '. +Persistently reading a closed pipe after reading end-of-file +will result in a read error. |