1.\" Copyright (c) 1980, 1991 Regents of the University of California. 2.\" All rights reserved. 3.\" 4.\" %sccs.include.redist.man% 5.\" 6.\" @(#)pipe.2 6.3 (Berkeley) 03/10/91 7.\" 8.Dd 9.Dt PIPE 2 10.Os BSD 4 11.Sh NAME 12.Nm pipe 13.Nd create descriptor pair for interprocess communication 14.Sh SYNOPSIS 15.Fd #include <unistd.h> 16.Ft int 17.Fn pipe "int *fildes" 18.Sh DESCRIPTION 19The 20.Fn pipe 21function 22creates a 23.Em pipe , 24which is an object allowing 25unidirectional data flow, 26and allocates a pair of file descriptors. 27The first descriptor connects to the 28.Em read end 29of the pipe, 30and the second connects to the 31.Em write end , 32so that data written to 33.Fa fildes[1] 34appears on (i.e., can be read from) 35.Fa fildes[0] . 36This allows the output of one program to be 37sent 38to another program: 39the source's standard output is set up to be 40the write end of the pipe, 41and the sink's standard input is set up to be 42the read end of the pipe. 43The pipe itself persists until all its associated descriptors are 44closed. 45.Pp 46A pipe whose read or write end has been closed is considered 47.Em widowed . 48Writing on such a pipe causes the writing process to receive 49a 50.Dv SIGPIPE 51signal. 52Widowing a pipe is the only way to deliver end-of-file to a reader: 53after the reader consumes any buffered data, reading a widowed pipe 54returns a zero count. 55.Pp 56Pipes are really a special case of the 57.Xr socketpair 2 58call and, in fact, are implemented as such in the system. 59.Sh RETURN VALUES 60On successful creation of the pipe, zero is returned. Otherwise, 61a value of -1 is returned and the variable 62.Va errno 63set to indicate the 64error. 65.Sh ERRORS 66The 67.Fn pipe 68call will fail if: 69.Bl -tag -width [EMFILE] 70.It Bq Er EMFILE 71Too many descriptors are active. 72.It Bq Er ENFILE 73The system file table is full. 74.It Bq Er EFAULT 75The 76.Fa fildes 77buffer is in an invalid area of the process's address 78space. 79.El 80.Sh SEE ALSO 81.Xr sh 1 , 82.Xr read 2 , 83.Xr write 2 , 84.Xr fork 2 , 85.Xr socketpair 2 86.Sh HISTORY 87A 88.Nm 89function call appeared in Version 6 AT&T UNIX. 90