101 lines
2.2 KiB
Groff
101 lines
2.2 KiB
Groff
.TH PIPE 3
|
|
.SH NAME
|
|
pipe \- create an interprocess channel
|
|
.SH SYNOPSIS
|
|
.B #include <u.h>
|
|
.br
|
|
.B #include <libc.h>
|
|
.PP
|
|
.B
|
|
int pipe(int fd[2])
|
|
.SH DESCRIPTION
|
|
.I Pipe
|
|
creates a buffered channel for interprocess I/O communication.
|
|
Two file descriptors are returned in
|
|
.IR fd .
|
|
Data written to
|
|
.B fd[1]
|
|
is available for reading from
|
|
.B fd[0]
|
|
and data written to
|
|
.B fd[0]
|
|
is available for reading from
|
|
.BR fd[1] .
|
|
.PP
|
|
After the pipe has been established,
|
|
cooperating processes
|
|
created by subsequent
|
|
.MR fork 2
|
|
calls may pass data through the
|
|
pipe with
|
|
.I read
|
|
and
|
|
.I write
|
|
calls.
|
|
.\" The bytes placed on a pipe
|
|
.\" by one
|
|
.\" .I write
|
|
.\" are contiguous even if many processes are writing.
|
|
.\" 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.
|
|
.\" .PP
|
|
.\" The number of bytes available to a
|
|
.\" .IR read (3)
|
|
.\" is reported
|
|
.\" in the
|
|
.\" .B Length
|
|
.\" field returned by
|
|
.\" .I fstat
|
|
.\" or
|
|
.\" .I dirfstat
|
|
.\" on a pipe (see
|
|
.\" .IR stat (3)).
|
|
.PP
|
|
When all the data has been read from a pipe and the writer has closed the pipe or exited,
|
|
.MR read 3
|
|
will return 0 bytes. Writes to a pipe with no reader will generate a note
|
|
.BR "sys: write on closed pipe" .
|
|
.SH SOURCE
|
|
.B \*9/src/lib9/pipe.c
|
|
.SH SEE ALSO
|
|
.MR intro 3 ,
|
|
.MR read 3
|
|
.SH DIAGNOSTICS
|
|
Sets
|
|
.IR errstr .
|
|
.SH BUGS
|
|
If a read or a write of a pipe is interrupted, some unknown
|
|
number of bytes may have been transferred.
|
|
.PP
|
|
.I Pipe
|
|
is a macro defined as
|
|
.I p9pipe
|
|
to avoid name conflicts with Unix's
|
|
.I pipe
|
|
system call.
|
|
.PP
|
|
Unix pipes are not guaranteed to be bidirectional.
|
|
In order to ensure a bidirectional channel,
|
|
.I p9pipe
|
|
creates Unix domain sockets via the
|
|
.MR socketpair 2
|
|
instead of Unix pipes.
|
|
.PP
|
|
The implementation of pipes as Unix domain sockets
|
|
causes problems with some Unix implementations of
|
|
.BR /dev/fd ,
|
|
Unix's dup device. If a Unix domain socket is open as file
|
|
descriptor 0, some implementations disallow the opening of
|
|
.BR /dev/fd/0 ;
|
|
instead one must
|
|
.MR connect 2
|
|
to it.
|
|
If this functionality is important
|
|
(as it is for
|
|
.MR rc 1 ),
|
|
one must
|
|
.B #undef
|
|
.B pipe
|
|
and fall back on the (possibly unidirectional) Unix pipes.
|