Debian Codegraph @

upstream/debian-unstable/man2/pipe.2

raw
1 .\" Copyright 2005-2008, Michael Kerrisk <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH pipe 2 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 pipe, pipe2 \- create pipe
9 .SH LIBRARY
10 Standard C library
11 .RI ( libc ,\~ \-lc )
12 .SH SYNOPSIS
13 .nf
14 .B #include <unistd.h>
15 .P
16 .BI "int pipe(int " pipefd [2]);
17 .P
18 .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
19 .BR "#include <fcntl.h>" " /* Definition of " O_* " constants */"
20 .B #include <unistd.h>
21 .P
22 .BI "int pipe2(int " pipefd "[2], int " flags );
23 .P
24 /* On Alpha, IA-64, MIPS, SuperH, and SPARC/SPARC64, pipe() has the
25 following prototype; see VERSIONS */
26 .P
27 .B #include <unistd.h>
28 .P
29 .B struct fd_pair {
30 .B " long fd[2];"
31 .B "};"
32 .B struct fd_pair pipe(void);
33 .fi
34 .SH DESCRIPTION
35 .BR pipe ()
36 creates a pipe, a unidirectional data channel that
37 can be used for interprocess communication.
38 The array
39 .I pipefd
40 is used to return two file descriptors referring to the ends of the pipe.
41 .I pipefd[0]
42 refers to the read end of the pipe.
43 .I pipefd[1]
44 refers to the write end of the pipe.
45 Data written to the write end of the pipe is buffered by the kernel
46 until it is read from the read end of the pipe.
47 For further details, see
48 .BR pipe (7).
49 .P
50 If
51 .I flags
52 is 0, then
53 .BR pipe2 ()
54 is the same as
55 .BR pipe ().
56 The following values can be bitwise ORed in
57 .I flags
58 to obtain different behavior:
59 .TP
60 .B O_CLOEXEC
61 Set the close-on-exec
62 .RB ( FD_CLOEXEC )
63 flag on the two new file descriptors.
64 See the description of the same flag in
65 .BR open (2)
66 for reasons why this may be useful.
67 .TP
68 .BR O_DIRECT " (since Linux 3.4)"
69 .\" commit 9883035ae7edef3ec62ad215611cb8e17d6a1a5d
70 Create a pipe that performs I/O in "packet" mode.
71 Each
72 .BR write (2)
73 to the pipe is dealt with as a separate packet, and
74 .BR read (2)s
75 from the pipe will read one packet at a time.
76 Note the following points:
77 .RS
78 .IP \[bu] 3
79 Writes of greater than
80 .B PIPE_BUF
81 bytes (see
82 .BR pipe (7))
83 will be split into multiple packets.
84 The constant
85 .B PIPE_BUF
86 is defined in
87 .IR <limits.h> .
88 .IP \[bu]
89 If a
90 .BR read (2)
91 specifies a buffer size that is smaller than the next packet,
92 then the requested number of bytes are read,
93 and the excess bytes in the packet are discarded.
94 Specifying a buffer size of
95 .B PIPE_BUF
96 will be sufficient to read the largest possible packets
97 (see the previous point).
98 .IP \[bu]
99 Zero-length packets are not supported.
100 (A
101 .BR read (2)
102 that specifies a buffer size of zero is a no-op, and returns 0.)
103 .RE
104 .IP
105 Older kernels that do not support this flag will indicate this via an
106 .B EINVAL
107 error.
108 .IP
109 Since Linux 4.5,
110 .\" commit 0dbf5f20652108106cb822ad7662c786baaa03ff
111 .\" FIXME . But, it is not possible to specify O_DIRECT when opening a FIFO
112 it is possible to change the
113 .B O_DIRECT
114 setting of a pipe file descriptor using
115 .BR fcntl (2).
116 .TP
117 .B O_NONBLOCK
118 Set the
119 .B O_NONBLOCK
120 file status flag on the open file descriptions
121 referred to by the new file descriptors.
122 Using this flag saves extra calls to
123 .BR fcntl (2)
124 to achieve the same result.
125 .TP
126 .B O_NOTIFICATION_PIPE
127 Since Linux 5.8,
128 .\" commit c73be61cede5882f9605a852414db559c0ebedfd
129 general notification mechanism is built on the top of the pipe where
130 kernel splices notification messages into pipes opened by user space.
131 The owner of the pipe has to tell the kernel which sources of events to watch
132 and filters can also be applied to select
133 which subevents should be placed into the pipe.
134 .SH RETURN VALUE
135 On success, zero is returned.
136 On error, \-1 is returned,
137 .I errno
138 is set to indicate the error, and
139 .I pipefd
140 is left unchanged.
141 .P
142 On Linux (and other systems),
143 .BR pipe ()
144 does not modify
145 .I pipefd
146 on failure.
147 A requirement standardizing this behavior was added in POSIX.1-2008 TC2.
148 .\" http://austingroupbugs.net/view.php?id=467
149 The Linux-specific
150 .BR pipe2 ()
151 system call
152 likewise does not modify
153 .I pipefd
154 on failure.
155 .SH ERRORS
156 .TP
157 .B EFAULT
158 .I pipefd
159 is not valid.
160 .TP
161 .B EINVAL
162 .RB ( pipe2 ())
163 Invalid value in
164 .IR flags .
165 .TP
166 .B EMFILE
167 The per-process limit on the number of open file descriptors has been reached.
168 .TP
169 .B ENFILE
170 The system-wide limit on the total number of open files has been reached.
171 .TP
172 .B ENFILE
173 The user hard limit on memory that can be allocated for pipes
174 has been reached
175 and the caller is not privileged;
176 see
177 .BR pipe (7).
178 .TP
179 .B ENOPKG
180 .RB ( pipe2 ())
181 .B O_NOTIFICATION_PIPE
182 was passed in
183 .I flags
184 and support for notifications
185 .RB ( CONFIG_WATCH_QUEUE )
186 is not compiled into the kernel.
187 .SH VERSIONS
188 .\" See http://math-atlas.sourceforge.net/devel/assembly/64.psabi.1.33.ps.Z
189 .\" for example, section 3.2.1 "Registers and the Stack Frame".
190 The System V ABI on some architectures
191 allows the use of more than one register
192 for returning multiple values;
193 several architectures
194 (namely, Alpha, IA-64, MIPS, SuperH, and SPARC/SPARC64)
195 (ab)use this feature in order to implement the
196 .BR pipe ()
197 system call in a functional manner:
198 the call doesn't take any arguments and returns
199 a pair of file descriptors as the return value on success.
200 The glibc
201 .BR pipe ()
202 wrapper function transparently deals with this.
203 See
204 .BR syscall (2)
205 for information regarding registers used for storing second file descriptor.
206 .SH STANDARDS
207 POSIX.1-2024.
208 .SH HISTORY
209 .TP
210 .BR pipe ()
211 POSIX.1-2001.
212 .TP
213 .BR pipe2 ()
214 POSIX.1-2024.
215 Linux 2.6.27,
216 glibc 2.9.
217 .SH EXAMPLES
218 .\" fork.2 refers to this example program.
219 The following program creates a pipe, and then
220 .BR fork (2)s
221 to create a child process;
222 the child inherits a duplicate set of file
223 descriptors that refer to the same pipe.
224 After the
225 .BR fork (2),
226 each process closes the file descriptors that it doesn't need for the pipe
227 (see
228 .BR pipe (7)).
229 The parent then writes the string contained in the program's
230 command-line argument to the pipe,
231 and the child reads this string a byte at a time from the pipe
232 and echoes it on standard output.
233 .SS Program source
234 .\" SRC BEGIN (pipe.c)
235 .EX
236 #include <err.h>
237 #include <stdio.h>
238 #include <stdlib.h>
239 #include <string.h>
240 #include <sys/types.h>
241 #include <sys/wait.h>
242 #include <unistd.h>
243 \&
244 int
245 main(int argc, char *argv[])
246 {
247 int pipefd[2];
248 char buf;
249 pid_t cpid;
250 \&
251 if (argc != 2) {
252 fprintf(stderr, "Usage: %s <string>\[rs]n", argv[0]);
253 exit(EXIT_FAILURE);
254 }
255 \&
256 if (pipe(pipefd) == \-1)
257 err(EXIT_FAILURE, "pipe");
258 \&
259 cpid = fork();
260 if (cpid == \-1)
261 err(EXIT_FAILURE, "fork");
262 \&
263 if (cpid == 0) { /* Child reads from pipe */
264 if (close(pipefd[1]) == \-1) /* Close unused write end */
265 err(EXIT_FAILURE, "close");
266 \&
267 while (read(pipefd[0], &buf, 1) > 0) {
268 if (write(STDOUT_FILENO, &buf, 1) != 1)
269 err(EXIT_FAILURE, "write");
270 }
271 \&
272 if (write(STDOUT_FILENO, "\[rs]n", 1) != 1)
273 err(EXIT_FAILURE, "write");
274 if (close(pipefd[0]) == \-1)
275 err(EXIT_FAILURE, "close");
276 _exit(EXIT_SUCCESS);
277 \&
278 } else { /* Parent writes argv[1] to pipe */
279 if (close(pipefd[0]) == \-1) /* Close unused read end */
280 err(EXIT_FAILURE, "close");
281 if (write(pipefd[1], argv[1], strlen(argv[1])) != strlen(argv[1]))
282 err(EXIT_FAILURE, "write");
283 if (close(pipefd[1]) == \-1) /* Reader will see EOF */
284 err(EXIT_FAILURE, "close");
285 if (wait(NULL) == \-1) /* Wait for child */
286 err(EXIT_FAILURE, "wait");
287 exit(EXIT_SUCCESS);
288 }
289 }
290 .EE
291 .\" SRC END
292 .SH SEE ALSO
293 .BR fork (2),
294 .BR read (2),
295 .BR socketpair (2),
296 .BR splice (2),
297 .BR tee (2),
298 .BR vmsplice (2),
299 .BR write (2),
300 .BR popen (3),
301 .BR pipe (7)