1.\" $OpenBSD: pipe.2,v 1.17 2014/08/31 01:42:36 guenther Exp $ 2.\" $NetBSD: pipe.2,v 1.6 1995/02/27 12:35:27 cgd Exp $ 3.\" 4.\" Copyright (c) 1980, 1991, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" @(#)pipe.2 8.1 (Berkeley) 6/4/93 32.\" 33.Dd $Mdocdate: August 31 2014 $ 34.Dt PIPE 2 35.Os 36.Sh NAME 37.Nm pipe , 38.Nm pipe2 39.Nd create descriptor pair for interprocess communication 40.Sh SYNOPSIS 41.In unistd.h 42.Ft int 43.Fn pipe "int fildes[2]" 44.In fcntl.h 45.In unistd.h 46.Ft int 47.Fn pipe2 "int fildes[2]" "int flags" 48.Sh DESCRIPTION 49The 50.Fn pipe 51function creates a 52.Em pipe , 53which is an object allowing unidirectional data flow, 54and allocates a pair of file descriptors. 55The first descriptor connects to the 56.Em read end 57of the pipe, 58and the second connects to the 59.Em write end , 60so that data written to 61.Fa fildes[1] 62appears on (i.e., can be read from) 63.Fa fildes[0] . 64This allows the output of one program to be sent to another program: 65the source's standard output is set up to be the write end of the pipe, 66and the sink's standard input is set up to be the read end of the pipe. 67The pipe itself persists until all its associated descriptors are closed. 68.Pp 69A pipe whose read or write end has been closed is considered 70.Em widowed . 71Writing on such a pipe causes the writing process to receive a 72.Dv SIGPIPE 73signal. 74Widowing a pipe is the only way to deliver end-of-file to a reader: 75after the reader consumes any buffered data, reading a widowed pipe 76returns a zero count. 77.Pp 78The 79.Fn pipe2 80function is identical to 81.Fn pipe 82except that the non-blocking I/O mode on both ends of the pipe is 83determined by the 84.Dv O_NONBLOCK 85flag in the 86.Fa flags 87argument and the close-on-exec flag on both the new file descriptors 88is determined by the 89.Dv O_CLOEXEC 90flag in the 91.Fa flags 92argument. 93.Sh RETURN VALUES 94On successful creation of the pipe, zero is returned. 95Otherwise, a value of \-1 is returned and the variable 96.Va errno 97set to indicate the error. 98.Sh ERRORS 99.Fn pipe 100and 101.Fn pipe2 102will succeed unless: 103.Bl -tag -width Er 104.It Bq Er EMFILE 105Too many descriptors are active. 106.It Bq Er ENFILE 107The system file table is full. 108.It Bq Er EFAULT 109The 110.Fa fildes 111buffer is in an invalid area of the process's address space. 112.El 113.Pp 114In addition, 115.Fn pipe2 116may return the following error: 117.Bl -tag -width Er 118.It Bq Er EINVAL 119.Fa flags 120is invalid. 121.El 122.Sh SEE ALSO 123.Xr sh 1 , 124.Xr fork 2 , 125.Xr read 2 , 126.Xr socketpair 2 , 127.Xr write 2 128.Sh STANDARDS 129The 130.Fn pipe 131function conforms to 132.St -p1003.1-2008 . 133The 134.Fn pipe2 135function is expected to conform to a future revision of that standard. 136.Pp 137As an extension, the pipe provided is actually capable of moving 138data bidirectionally. 139This is compatible with SVR4. 140However, this is non-POSIX behaviour which should not be relied on, 141for reasons of portability. 142.Sh HISTORY 143A 144.Fn pipe 145function call appeared in 146.At v3 . 147Since 148.At v4 , 149it allocates two distinct file descriptors. 150The 151.Fn pipe2 152function appeared in 153.Ox 5.7 . 154