X-Git-Url: https://git.subgeniuskitty.com/unix-history/.git/blobdiff_plain/1c15e88899094343f75aeba04122cd96a96b428e..af359dea2e5ab3e937b62107ecd6a51d78189ed7:/usr/src/lib/libc/sys/pipe.2 diff --git a/usr/src/lib/libc/sys/pipe.2 b/usr/src/lib/libc/sys/pipe.2 index aa130993cf..a34cd34ee8 100644 --- a/usr/src/lib/libc/sys/pipe.2 +++ b/usr/src/lib/libc/sys/pipe.2 @@ -1,80 +1,115 @@ -.\" Copyright (c) 1980 Regents of the University of California. -.\" All rights reserved. The Berkeley software License Agreement -.\" specifies the terms and conditions for redistribution. +.\" Copyright (c) 1980, 1991 Regents of the University of California. +.\" All rights reserved. .\" -.\" @(#)pipe.2 6.2 (Berkeley) 8/26/85 +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. .\" -.TH PIPE 2 "August 26, 1985" -.UC 4 -.SH NAME -pipe \- create an interprocess communication channel -.SH SYNOPSIS -.nf -.ft B -pipe(fildes) -int fildes[2]; -.fi -.ft R -.SH DESCRIPTION +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)pipe.2 6.3 (Berkeley) 3/10/91 +.\" +.Dd March 10, 1991 +.Dt PIPE 2 +.Os BSD 4 +.Sh NAME +.Nm pipe +.Nd create descriptor pair for interprocess communication +.Sh SYNOPSIS +.Fd #include +.Ft int +.Fn pipe "int *fildes" +.Sh DESCRIPTION The -.I pipe -system call -creates an I/O mechanism called a pipe. -The file descriptors returned can -be used in read and write operations. -When the pipe is written using the descriptor -.IR fildes [1] -up to 4096 bytes of data are buffered -before the writing process is suspended. -A read using the descriptor -.IR fildes [0] -will pick up the data. -.PP -It is assumed that after the -pipe has been set up, -two (or more) -cooperating processes -(created by subsequent -.I fork -calls) -will pass data through the -pipe with -.I read -and -.I write -calls. -.PP -The shell has a syntax -to set up a linear array of processes -connected by pipes. -.PP -Read calls on an empty -pipe (no buffered data) with only one end -(all write file descriptors closed) -returns an end-of-file. -.PP +.Fn pipe +function +creates a +.Em pipe , +which is an object allowing +unidirectional data flow, +and allocates a pair of file descriptors. +The first descriptor connects to the +.Em read end +of the pipe, +and the second connects to the +.Em write end , +so that data written to +.Fa fildes[1] +appears on (i.e., can be read from) +.Fa fildes[0] . +This allows the output of one program to be +sent +to another program: +the source's standard output is set up to be +the write end of the pipe, +and the sink's standard input is set up to be +the read end of the pipe. +The pipe itself persists until all its associated descriptors are +closed. +.Pp +A pipe whose read or write end has been closed is considered +.Em widowed . +Writing on such a pipe causes the writing process to receive +a +.Dv SIGPIPE +signal. +Widowing a pipe is the only way to deliver end-of-file to a reader: +after the reader consumes any buffered data, reading a widowed pipe +returns a zero count. +.Pp Pipes are really a special case of the -.IR socketpair (2) +.Xr socketpair 2 call and, in fact, are implemented as such in the system. -.PP -A signal is generated if a write on a pipe with only one end is attempted. -.SH "RETURN VALUE -The function value zero is returned if the -pipe was created; \-1 if an error occurred. -.SH ERRORS -The \fIpipe\fP call will fail if: -.TP 15 -[EMFILE] +.Sh RETURN VALUES +On successful creation of the pipe, zero is returned. Otherwise, +a value of -1 is returned and the variable +.Va errno +set to indicate the +error. +.Sh ERRORS +The +.Fn pipe +call will fail if: +.Bl -tag -width [EMFILE] +.It Bq Er EMFILE Too many descriptors are active. -.TP 15 -[ENFILE] +.It Bq Er ENFILE The system file table is full. -.TP 15 -[EFAULT] -The \fIfildes\fP buffer is in an invalid area of the process's address +.It Bq Er EFAULT +The +.Fa fildes +buffer is in an invalid area of the process's address space. -.SH "SEE ALSO" -sh(1), read(2), write(2), fork(2), socketpair(2) -.SH BUGS -Should more than 4096 bytes be necessary in any -pipe among a loop of processes, deadlock will occur. +.El +.Sh SEE ALSO +.Xr sh 1 , +.Xr read 2 , +.Xr write 2 , +.Xr fork 2 , +.Xr socketpair 2 +.Sh HISTORY +A +.Nm +function call appeared in Version 6 AT&T UNIX.