1.\" $OpenBSD: pipe.2,v 1.18 2014/12/10 19:30:22 schwarze 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: December 10 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 94.Rv -std 95.Sh ERRORS 96.Fn pipe 97and 98.Fn pipe2 99will succeed unless: 100.Bl -tag -width Er 101.It Bq Er EMFILE 102Too many descriptors are active. 103.It Bq Er ENFILE 104The system file table is full. 105.It Bq Er EFAULT 106The 107.Fa fildes 108buffer is in an invalid area of the process's address space. 109.El 110.Pp 111In addition, 112.Fn pipe2 113may return the following error: 114.Bl -tag -width Er 115.It Bq Er EINVAL 116.Fa flags 117is invalid. 118.El 119.Sh SEE ALSO 120.Xr sh 1 , 121.Xr fork 2 , 122.Xr read 2 , 123.Xr socketpair 2 , 124.Xr write 2 125.Sh STANDARDS 126The 127.Fn pipe 128function conforms to 129.St -p1003.1-2008 . 130The 131.Fn pipe2 132function is expected to conform to a future revision of that standard. 133.Pp 134As an extension, the pipe provided is actually capable of moving 135data bidirectionally. 136This is compatible with SVR4. 137However, this is non-POSIX behaviour which should not be relied on, 138for reasons of portability. 139.Sh HISTORY 140A 141.Fn pipe 142function call appeared in 143.At v3 . 144Since 145.At v4 , 146it allocates two distinct file descriptors. 147The 148.Fn pipe2 149function appeared in 150.Ox 5.7 . 151