jcs.org
jcs's openbsd hax
openbsd
1.\" $OpenBSD: pipe.2,v 1.20 2025/08/04 17:34:07 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: August 4 2025 $
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,
83close-on-exec flag,
84and close-on-fork flag of both new file descriptors are determined by the
85.Dv O_NONBLOCK , O_CLOEXEC ,
86and
87.Dv O_CLOFORK
88flags in the
89.Fa flags
90argument, respectively.
91.Sh RETURN VALUES
92.Rv -std
93.Sh ERRORS
94.Fn pipe
95and
96.Fn pipe2
97will succeed unless:
98.Bl -tag -width Er
99.It Bq Er EMFILE
100Too many descriptors are active.
101.It Bq Er ENFILE
102The system file table is full.
103.It Bq Er EFAULT
104The
105.Fa fildes
106buffer is in an invalid area of the process's address space.
107.El
108.Pp
109In addition,
110.Fn pipe2
111may return the following error:
112.Bl -tag -width Er
113.It Bq Er EINVAL
114.Fa flags
115is invalid.
116.El
117.Sh SEE ALSO
118.Xr sh 1 ,
119.Xr fork 2 ,
120.Xr read 2 ,
121.Xr socketpair 2 ,
122.Xr write 2
123.Sh STANDARDS
124The
125.Fn pipe
126and
127.Fn pipe2
128functions conform to
129.St -p1003.1-2024 .
130.Pp
131As an extension, the pipe provided is actually capable of moving
132data bidirectionally.
133This is compatible with SVR4.
134However, this is non-POSIX behaviour which should not be relied on,
135for reasons of portability.
136.Sh HISTORY
137A
138.Fn pipe
139function call appeared in
140.At v3 .
141Since
142.At v4 ,
143it allocates two distinct file descriptors.
144The
145.Fn pipe2
146function appeared in
147.Ox 5.7 .