10564b1175
groff 1.23.0 added .MR to its -man macro package. The NEWS file states
that the inclusion of the macro "was prompted by its introduction to
Plan 9 from User Space's troff in August 2020." From d32deab it seems
that the name for Plan 9 from User Space's implementation was suggested
by groff maintainer G. Brandon Robinson.
Not sure if the intention was to make these definitions compatible, but
it would be nice if they were.
Currently, Plan 9 from User Space's .MR expects its second argument to
be parenthesized. groff's .MR does not. This results in extra
parentheses appearing in manual references when viewing Plan 9 from User
Space's manual pages on a system using groff.
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.
|