Debian Codegraph @

upstream/debian-unstable/man7/pipe.7

raw
1 .\" Copyright 2005, 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 7 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 pipe \- overview of pipes and FIFOs
9 .SH DESCRIPTION
10 Pipes and FIFOs (also known as named pipes)
11 provide a unidirectional interprocess communication channel.
12 A pipe has a
13 .I read end
14 and a
15 .IR "write end" .
16 Data written to the write end of a pipe can be read
17 from the read end of the pipe.
18 .P
19 A pipe is created using
20 .BR pipe (2),
21 which creates a new pipe and returns two file descriptors,
22 one referring to the read end of the pipe,
23 the other referring to the write end.
24 Pipes can be used to create a communication channel between related
25 processes;
26 see
27 .BR pipe (2)
28 for an example.
29 .P
30 A FIFO (short for First In First Out) has a name within the filesystem
31 (created using
32 .BR mkfifo (3)),
33 and is opened using
34 .BR open (2).
35 Any process may open a FIFO, assuming the file permissions allow it.
36 The read end is opened using the
37 .B O_RDONLY
38 flag;
39 the write end is opened using the
40 .B O_WRONLY
41 flag.
42 See
43 .BR fifo (7)
44 for further details.
45 .IR Note :
46 although FIFOs have a pathname in the filesystem,
47 I/O on FIFOs does not involve operations on the underlying device
48 (if there is one).
49 .SS I/O on pipes and FIFOs
50 The only difference between pipes and FIFOs is the manner in which
51 they are created and opened.
52 Once these tasks have been accomplished,
53 I/O on pipes and FIFOs has exactly the same semantics.
54 .P
55 If a process attempts to read from an empty pipe, then
56 .BR read (2)
57 will block until data is available.
58 If a process attempts to write to a full pipe (see below), then
59 .BR write (2)
60 blocks until sufficient data has been read from the pipe
61 to allow the write to complete.
62 .P
63 Nonblocking I/O is possible by using the
64 .BR fcntl (2)
65 .B F_SETFL
66 operation to enable the
67 .B O_NONBLOCK
68 open file status flag or by opening a
69 .BR fifo (7)
70 with
71 .BR O_NONBLOCK .
72 If any process has the pipe open for writing, reads fail with
73 .BR EAGAIN ;
74 otherwise\[em]with no potential writers\[em]reads succeed and return empty.
75 .P
76 The communication channel provided by a pipe is a
77 .IR "byte stream" :
78 there is no concept of message boundaries.
79 .P
80 If all file descriptors referring to the write end of a pipe
81 have been closed, then an attempt to
82 .BR read (2)
83 from the pipe will see end-of-file
84 .RB ( read (2)
85 will return 0).
86 If all file descriptors referring to the read end of a pipe
87 have been closed, then a
88 .BR write (2)
89 will cause a
90 .B SIGPIPE
91 signal to be generated for the calling process.
92 If the calling process is ignoring this signal, then
93 .BR write (2)
94 fails with the error
95 .BR EPIPE .
96 An application that uses
97 .BR pipe (2)
98 and
99 .BR fork (2)
100 should use suitable
101 .BR close (2)
102 calls to close unnecessary duplicate file descriptors;
103 this ensures that end-of-file and
104 .BR SIGPIPE / EPIPE
105 are delivered when appropriate.
106 .P
107 It is not possible to apply
108 .BR lseek (2)
109 to a pipe.
110 .SS Pipe capacity
111 A pipe has a limited capacity.
112 If the pipe is full, then a
113 .BR write (2)
114 will block or fail, depending on whether the
115 .B O_NONBLOCK
116 flag is set (see below).
117 Different implementations have different limits for the pipe capacity.
118 Applications should not rely on a particular capacity:
119 an application should be designed so that a reading process consumes data
120 as soon as it is available,
121 so that a writing process does not remain blocked.
122 .P
123 Before Linux 2.6.11, the capacity of a pipe was the same as
124 the system page size (e.g., 4096 bytes on i386).
125 Since Linux 2.6.11, the pipe capacity is 16 pages
126 (i.e., 65,536 bytes in a system with a page size of 4096 bytes).
127 Since Linux 2.6.35, the default pipe capacity is 16 pages,
128 but the capacity can be queried and set using the
129 .BR fcntl (2)
130 .B F_GETPIPE_SZ
131 and
132 .B F_SETPIPE_SZ
133 operations.
134 See
135 .BR fcntl (2)
136 for more information.
137 Since Linux 4.5, the default pipe capacity is lower than 16 pages when the
138 .I pipe\-user\-pages\-soft
139 limit is exceeded.
140 .P
141 The following
142 .BR ioctl (2)
143 operation, which can be applied to a file descriptor
144 that refers to either end of a pipe,
145 places a count of the number of unread bytes in the pipe in the
146 .I int
147 buffer pointed to by the final argument of the call:
148 .P
149 .in +4n
150 .EX
151 ioctl(fd, FIONREAD, &nbytes);
152 .EE
153 .in
154 .P
155 The
156 .B FIONREAD
157 operation is not specified in any standard,
158 but is provided on many implementations.
159 .\"
160 .SS /proc files
161 On Linux, the following files control how much memory can be used for pipes:
162 .TP
163 .IR /proc/sys/fs/pipe\-max\-pages " (only in Linux 2.6.34)"
164 .\" commit b492e95be0ae672922f4734acf3f5d35c30be948
165 An upper limit, in pages, on the capacity that an unprivileged user
166 (one without the
167 .B CAP_SYS_RESOURCE
168 capability)
169 can set for a pipe.
170 .IP
171 The default value for this limit is 16 times the default pipe capacity
172 (see above);
173 the lower limit is two pages.
174 .IP
175 This interface was removed in Linux 2.6.35, in favor of
176 .IR /proc/sys/fs/pipe\-max\-size .
177 .TP
178 .IR /proc/sys/fs/pipe\-max\-size " (since Linux 2.6.35)"
179 .\" commit ff9da691c0498ff81fdd014e7a0731dab2337dac
180 The maximum size (in bytes) of individual pipes that can be set
181 .\" This limit is not checked on pipe creation, where the capacity is
182 .\" always PIPE_DEF_BUFS, regardless of pipe-max-size
183 by users without the
184 .B CAP_SYS_RESOURCE
185 capability.
186 The value assigned to this file may be rounded upward,
187 to reflect the value actually employed for a convenient implementation.
188 To determine the rounded-up value,
189 display the contents of this file after assigning a value to it.
190 .IP
191 The default value for this file is 1048576 (1\ MiB).
192 The minimum value that can be assigned to this file is the system page size.
193 Attempts to set a limit less than the page size cause
194 .BR write (2)
195 to fail with the error
196 .BR EINVAL .
197 .IP
198 Since Linux 4.9,
199 .\" commit 086e774a57fba4695f14383c0818994c0b31da7c
200 the value on this file also acts as a ceiling on the default capacity
201 of a new pipe or newly opened FIFO.
202 .TP
203 .IR /proc/sys/fs/pipe\-user\-pages\-hard " (since Linux 4.5)"
204 .\" commit 759c01142a5d0f364a462346168a56de28a80f52
205 The hard limit on the total size (in pages) of all pipes created or set by
206 a single unprivileged user (i.e., one with neither the
207 .B CAP_SYS_RESOURCE
208 nor the
209 .B CAP_SYS_ADMIN
210 capability).
211 So long as the total number of pages allocated to pipe buffers
212 for this user is at this limit,
213 attempts to create new pipes will be denied,
214 and attempts to increase a pipe's capacity will be denied.
215 .IP
216 When the value of this limit is zero (which is the default),
217 no hard limit is applied.
218 .\" The default was chosen to avoid breaking existing applications that
219 .\" make intensive use of pipes (e.g., for splicing).
220 .TP
221 .IR /proc/sys/fs/pipe\-user\-pages\-soft " (since Linux 4.5)"
222 .\" commit 759c01142a5d0f364a462346168a56de28a80f52
223 The soft limit on the total size (in pages) of all pipes created or set by
224 a single unprivileged user (i.e., one with neither the
225 .B CAP_SYS_RESOURCE
226 nor the
227 .B CAP_SYS_ADMIN
228 capability).
229 So long as the total number of pages allocated to pipe buffers
230 for this user is at this limit,
231 individual pipes created by a user will be
232 limited to two pages
233 (one page before Linux 5.14),
234 and attempts to increase a pipe's capacity will be denied.
235 .IP
236 When the value of this limit is zero, no soft limit is applied.
237 The default value for this file is 16384,
238 which permits creating up to 1024 pipes with the default capacity.
239 .P
240 Before Linux 4.9, some bugs affected the handling of the
241 .I pipe\-user\-pages\-soft
242 and
243 .I pipe\-user\-pages\-hard
244 limits;
245 see BUGS.
246 .\"
247 .SS PIPE_BUF
248 POSIX.1 says that writes of less than
249 .B PIPE_BUF
250 bytes must be atomic: the output data is written to the pipe as a
251 contiguous sequence.
252 Writes of more than
253 .B PIPE_BUF
254 bytes may be nonatomic: the kernel may interleave the data
255 with data written by other processes.
256 POSIX.1 requires
257 .B PIPE_BUF
258 to be at least 512 bytes.
259 (On Linux,
260 .B PIPE_BUF
261 is 4096 bytes.)
262 The precise semantics depend on whether the file descriptor is nonblocking
263 .RB ( O_NONBLOCK ),
264 whether there are multiple writers to the pipe, and on
265 .IR n ,
266 the number of bytes to be written:
267 .TP
268 .BR O_NONBLOCK " disabled, \f[I]n\f[] <= " PIPE_BUF
269 All
270 .I n
271 bytes are written atomically;
272 .BR write (2)
273 may block if there is not room for
274 .I n
275 bytes to be written immediately
276 .TP
277 .BR O_NONBLOCK " enabled, \f[I]n\f[] <= " PIPE_BUF
278 If there is room to write
279 .I n
280 bytes to the pipe, then
281 .BR write (2)
282 succeeds immediately, writing all
283 .I n
284 bytes;
285 otherwise
286 .BR write (2)
287 fails, with
288 .I errno
289 set to
290 .BR EAGAIN .
291 .TP
292 .BR O_NONBLOCK " disabled, \f[I]n\f[] > " PIPE_BUF
293 The write is nonatomic: the data given to
294 .BR write (2)
295 may be interleaved with
296 .BR write (2)s
297 by other process;
298 the
299 .BR write (2)
300 blocks until
301 .I n
302 bytes have been written.
303 .TP
304 .BR O_NONBLOCK " enabled, \f[I]n\f[] > " PIPE_BUF
305 If the pipe is full, then
306 .BR write (2)
307 fails, with
308 .I errno
309 set to
310 .BR EAGAIN .
311 Otherwise, from 1 to
312 .I n
313 bytes may be written (i.e., a "partial write" may occur;
314 the caller should check the return value from
315 .BR write (2)
316 to see how many bytes were actually written),
317 and these bytes may be interleaved with writes by other processes.
318 .SS Open file status flags
319 The only open file status flags that can be meaningfully applied to
320 a pipe or FIFO are
321 .B O_NONBLOCK
322 and
323 .BR O_ASYNC .
324 .P
325 Setting the
326 .B O_ASYNC
327 flag for the read end of a pipe causes a signal
328 .RB ( SIGIO
329 by default) to be generated when new input becomes available on the pipe.
330 The target for delivery of signals must be set using the
331 .BR fcntl (2)
332 .B F_SETOWN
333 command.
334 On Linux,
335 .B O_ASYNC
336 is supported for pipes and FIFOs only since Linux 2.6.
337 .SS Portability notes
338 On some systems (but not Linux), pipes are bidirectional:
339 data can be transmitted in both directions between the pipe ends.
340 POSIX.1 requires only unidirectional pipes.
341 Portable applications should avoid reliance on
342 bidirectional pipe semantics.
343 .SS BUGS
344 Before Linux 4.9, some bugs affected the handling of the
345 .I pipe\-user\-pages\-soft
346 and
347 .I pipe\-user\-pages\-hard
348 limits when using the
349 .BR fcntl (2)
350 .B F_SETPIPE_SZ
351 operation to change a pipe's capacity:
352 .\" These bugs where remedied by a series of patches, in particular,
353 .\" commit b0b91d18e2e97b741b294af9333824ecc3fadfd8 and
354 .\" commit a005ca0e6813e1d796a7422a7e31d8b8d6555df1
355 .IP (a) 5
356 When increasing the pipe capacity, the checks against the soft and
357 hard limits were made against existing consumption,
358 and excluded the memory required for the increased pipe capacity.
359 The new increase in pipe capacity could then push the total
360 memory used by the user for pipes (possibly far) over a limit.
361 (This could also trigger the problem described next.)
362 .IP
363 Starting with Linux 4.9,
364 the limit checking includes the memory required for the new pipe capacity.
365 .IP (b)
366 The limit checks were performed even when the new pipe capacity was
367 less than the existing pipe capacity.
368 This could lead to problems if a user set a large pipe capacity,
369 and then the limits were lowered, with the result that the user could
370 no longer decrease the pipe capacity.
371 .IP
372 Starting with Linux 4.9, checks against the limits
373 are performed only when increasing a pipe's capacity;
374 an unprivileged user can always decrease a pipe's capacity.
375 .IP (c)
376 The accounting and checking against the limits were done as follows:
377 .RS
378 .IP (1) 5
379 .PD 0
380 Test whether the user has exceeded the limit.
381 .IP (2)
382 Make the new pipe buffer allocation.
383 .IP (3)
384 Account new allocation against the limits.
385 .PD
386 .RE
387 .IP
388 This was racey.
389 Multiple processes could pass point (1) simultaneously,
390 and then allocate pipe buffers that were accounted for only in step (3),
391 with the result that the user's pipe buffer
392 allocation could be pushed over the limit.
393 .IP
394 Starting with Linux 4.9,
395 the accounting step is performed before doing the allocation,
396 and the operation fails if the limit would be exceeded.
397 .P
398 Before Linux 4.9, bugs similar to points (a) and (c) could also occur
399 when the kernel allocated memory for a new pipe buffer;
400 that is, when calling
401 .BR pipe (2)
402 and when opening a previously unopened FIFO.
403 .SH SEE ALSO
404 .BR mkfifo (1),
405 .BR dup (2),
406 .BR fcntl (2),
407 .BR open (2),
408 .BR pipe (2),
409 .BR poll (2),
410 .BR select (2),
411 .BR socketpair (2),
412 .BR splice (2),
413 .BR stat (2),
414 .BR tee (2),
415 .BR vmsplice (2),
416 .BR mkfifo (3),
417 .BR epoll (7),
418 .BR fifo (7)