1*a325d9c4SApple OSS Distributions.\" $NetBSD: pipe.2,v 1.6 1995/02/27 12:35:27 cgd Exp $ 2*a325d9c4SApple OSS Distributions.\" 3*a325d9c4SApple OSS Distributions.\" Copyright (c) 1980, 1991, 1993 4*a325d9c4SApple OSS Distributions.\" The Regents of the University of California. All rights reserved. 5*a325d9c4SApple OSS Distributions.\" 6*a325d9c4SApple OSS Distributions.\" Redistribution and use in source and binary forms, with or without 7*a325d9c4SApple OSS Distributions.\" modification, are permitted provided that the following conditions 8*a325d9c4SApple OSS Distributions.\" are met: 9*a325d9c4SApple OSS Distributions.\" 1. Redistributions of source code must retain the above copyright 10*a325d9c4SApple OSS Distributions.\" notice, this list of conditions and the following disclaimer. 11*a325d9c4SApple OSS Distributions.\" 2. Redistributions in binary form must reproduce the above copyright 12*a325d9c4SApple OSS Distributions.\" notice, this list of conditions and the following disclaimer in the 13*a325d9c4SApple OSS Distributions.\" documentation and/or other materials provided with the distribution. 14*a325d9c4SApple OSS Distributions.\" 3. All advertising materials mentioning features or use of this software 15*a325d9c4SApple OSS Distributions.\" must display the following acknowledgement: 16*a325d9c4SApple OSS Distributions.\" This product includes software developed by the University of 17*a325d9c4SApple OSS Distributions.\" California, Berkeley and its contributors. 18*a325d9c4SApple OSS Distributions.\" 4. Neither the name of the University nor the names of its contributors 19*a325d9c4SApple OSS Distributions.\" may be used to endorse or promote products derived from this software 20*a325d9c4SApple OSS Distributions.\" without specific prior written permission. 21*a325d9c4SApple OSS Distributions.\" 22*a325d9c4SApple OSS Distributions.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23*a325d9c4SApple OSS Distributions.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24*a325d9c4SApple OSS Distributions.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25*a325d9c4SApple OSS Distributions.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26*a325d9c4SApple OSS Distributions.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27*a325d9c4SApple OSS Distributions.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28*a325d9c4SApple OSS Distributions.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29*a325d9c4SApple OSS Distributions.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30*a325d9c4SApple OSS Distributions.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31*a325d9c4SApple OSS Distributions.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32*a325d9c4SApple OSS Distributions.\" SUCH DAMAGE. 33*a325d9c4SApple OSS Distributions.\" 34*a325d9c4SApple OSS Distributions.\" @(#)pipe.2 8.1 (Berkeley) 6/4/93 35*a325d9c4SApple OSS Distributions.\" 36*a325d9c4SApple OSS Distributions.Dd February 17, 2011 37*a325d9c4SApple OSS Distributions.Dt PIPE 2 38*a325d9c4SApple OSS Distributions.Os BSD 4 39*a325d9c4SApple OSS Distributions.Sh NAME 40*a325d9c4SApple OSS Distributions.Nm pipe 41*a325d9c4SApple OSS Distributions.Nd create descriptor pair for interprocess communication 42*a325d9c4SApple OSS Distributions.Sh SYNOPSIS 43*a325d9c4SApple OSS Distributions.Fd #include <unistd.h> 44*a325d9c4SApple OSS Distributions.Ft int 45*a325d9c4SApple OSS Distributions.Fo pipe 46*a325d9c4SApple OSS Distributions.Fa "int fildes[2]" 47*a325d9c4SApple OSS Distributions.Fc 48*a325d9c4SApple OSS Distributions.Sh DESCRIPTION 49*a325d9c4SApple OSS DistributionsThe 50*a325d9c4SApple OSS Distributions.Fn pipe 51*a325d9c4SApple OSS Distributionsfunction 52*a325d9c4SApple OSS Distributionscreates a 53*a325d9c4SApple OSS Distributions.Em pipe 54*a325d9c4SApple OSS Distributions(an object that allows unidirectional data flow) 55*a325d9c4SApple OSS Distributionsand allocates a pair of file descriptors. 56*a325d9c4SApple OSS DistributionsThe first descriptor connects to the 57*a325d9c4SApple OSS Distributions.Em read end 58*a325d9c4SApple OSS Distributionsof the pipe; 59*a325d9c4SApple OSS Distributionsthe second connects to the 60*a325d9c4SApple OSS Distributions.Em write end . 61*a325d9c4SApple OSS Distributions.Pp 62*a325d9c4SApple OSS DistributionsData written to 63*a325d9c4SApple OSS Distributions.Fa fildes[1] 64*a325d9c4SApple OSS Distributionsappears on (i.e., can be read from) 65*a325d9c4SApple OSS Distributions.Fa fildes[0] . 66*a325d9c4SApple OSS DistributionsThis allows the output of one program to be 67*a325d9c4SApple OSS Distributionssent 68*a325d9c4SApple OSS Distributionsto another program: 69*a325d9c4SApple OSS Distributionsthe source's standard output is set up 70*a325d9c4SApple OSS Distributionsto be the write end of the pipe; 71*a325d9c4SApple OSS Distributionsthe sink's standard input is set up 72*a325d9c4SApple OSS Distributionsto be the read end of the pipe. 73*a325d9c4SApple OSS DistributionsThe pipe itself persists 74*a325d9c4SApple OSS Distributionsuntil all of its associated descriptors are closed. 75*a325d9c4SApple OSS Distributions.Pp 76*a325d9c4SApple OSS DistributionsA pipe whose read or write end has been closed is considered 77*a325d9c4SApple OSS Distributions.Em widowed . 78*a325d9c4SApple OSS DistributionsWriting on such a pipe causes the writing process to receive 79*a325d9c4SApple OSS Distributionsa 80*a325d9c4SApple OSS Distributions.Dv SIGPIPE 81*a325d9c4SApple OSS Distributionssignal. 82*a325d9c4SApple OSS DistributionsWidowing a pipe is the only way to deliver end-of-file to a reader: 83*a325d9c4SApple OSS Distributionsafter the reader consumes any buffered data, reading a widowed pipe 84*a325d9c4SApple OSS Distributionsreturns a zero count. 85*a325d9c4SApple OSS Distributions.Pp 86*a325d9c4SApple OSS DistributionsThe generation of the 87*a325d9c4SApple OSS Distributions.Dv SIGPIPE 88*a325d9c4SApple OSS Distributionssignal can be suppressed using the 89*a325d9c4SApple OSS Distributions.Dv F_SETNOSIGPIPE 90*a325d9c4SApple OSS Distributionsfcntl command. 91*a325d9c4SApple OSS Distributions.Sh RETURN VALUES 92*a325d9c4SApple OSS DistributionsOn successful creation of the pipe, zero is returned. Otherwise, 93*a325d9c4SApple OSS Distributionsa value of -1 is returned and the variable 94*a325d9c4SApple OSS Distributions.Va errno 95*a325d9c4SApple OSS Distributionsset to indicate the 96*a325d9c4SApple OSS Distributionserror. 97*a325d9c4SApple OSS Distributions.Sh ERRORS 98*a325d9c4SApple OSS DistributionsThe 99*a325d9c4SApple OSS Distributions.Fn pipe 100*a325d9c4SApple OSS Distributionscall will fail if: 101*a325d9c4SApple OSS Distributions.Bl -tag -width Er 102*a325d9c4SApple OSS Distributions.\" =========== 103*a325d9c4SApple OSS Distributions.It Bq Er EFAULT 104*a325d9c4SApple OSS DistributionsThe 105*a325d9c4SApple OSS Distributions.Fa fildes 106*a325d9c4SApple OSS Distributionsbuffer is in an invalid area of the process's address 107*a325d9c4SApple OSS Distributionsspace. 108*a325d9c4SApple OSS Distributions.\" =========== 109*a325d9c4SApple OSS Distributions.It Bq Er EMFILE 110*a325d9c4SApple OSS DistributionsToo many descriptors are active. 111*a325d9c4SApple OSS Distributions.\" =========== 112*a325d9c4SApple OSS Distributions.It Bq Er ENFILE 113*a325d9c4SApple OSS DistributionsThe system file table is full. 114*a325d9c4SApple OSS Distributions.El 115*a325d9c4SApple OSS Distributions.Sh SEE ALSO 116*a325d9c4SApple OSS Distributions.Xr sh 1 , 117*a325d9c4SApple OSS Distributions.Xr fork 2 , 118*a325d9c4SApple OSS Distributions.Xr read 2 , 119*a325d9c4SApple OSS Distributions.Xr socketpair 2 , 120*a325d9c4SApple OSS Distributions.Xr fcntl 2 , 121*a325d9c4SApple OSS Distributions.Xr write 2 122*a325d9c4SApple OSS Distributions.Sh HISTORY 123*a325d9c4SApple OSS DistributionsA 124*a325d9c4SApple OSS Distributions.Fn pipe 125*a325d9c4SApple OSS Distributionsfunction call appeared in 126*a325d9c4SApple OSS Distributions.At v6 . 127