1 .\" Copyright (C) 2005 Michael Kerrisk <mtk.manpages@gmail.com>
3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .TH pipe 7 (date) "Linux man-pages (unreleased)"
7 pipe \- overview of pipes and FIFOs
9 Pipes and FIFOs (also known as named pipes)
10 provide a unidirectional interprocess communication channel.
15 Data written to the write end of a pipe can be read
16 from the read end of the pipe.
18 A pipe is created using
20 which creates a new pipe and returns two file descriptors,
21 one referring to the read end of the pipe,
22 the other referring to the write end.
23 Pipes can be used to create a communication channel between related
28 A FIFO (short for First In First Out) has a name within the filesystem
33 Any process may open a FIFO, assuming the file permissions allow it.
34 The read end is opened using the
36 flag; the write end is opened using the
43 although FIFOs have a pathname in the filesystem,
44 I/O on FIFOs does not involve operations on the underlying device
46 .SS I/O on pipes and FIFOs
47 The only difference between pipes and FIFOs is the manner in which
48 they are created and opened.
49 Once these tasks have been accomplished,
50 I/O on pipes and FIFOs has exactly the same semantics.
52 If a process attempts to read from an empty pipe, then
54 will block until data is available.
55 If a process attempts to write to a full pipe (see below), then
57 blocks until sufficient data has been read from the pipe
58 to allow the write to complete.
60 Nonblocking I/O is possible by using the
63 operation to enable the
65 open file status flag or by opening a
69 If any process has the pipe open for writing, reads fail with
71 otherwise\[em]with no potential writers\[em]reads succeed and return empty.
73 The communication channel provided by a pipe is a
75 there is no concept of message boundaries.
77 If all file descriptors referring to the write end of a pipe
78 have been closed, then an attempt to
80 from the pipe will see end-of-file
83 If all file descriptors referring to the read end of a pipe
84 have been closed, then a
88 signal to be generated for the calling process.
89 If the calling process is ignoring this signal, then
93 An application that uses
99 calls to close unnecessary duplicate file descriptors;
100 this ensures that end-of-file and
102 are delivered when appropriate.
104 It is not possible to apply
108 A pipe has a limited capacity.
109 If the pipe is full, then a
111 will block or fail, depending on whether the
113 flag is set (see below).
114 Different implementations have different limits for the pipe capacity.
115 Applications should not rely on a particular capacity:
116 an application should be designed so that a reading process consumes data
117 as soon as it is available,
118 so that a writing process does not remain blocked.
120 Before Linux 2.6.11, the capacity of a pipe was the same as
121 the system page size (e.g., 4096 bytes on i386).
122 Since Linux 2.6.11, the pipe capacity is 16 pages
123 (i.e., 65,536 bytes in a system with a page size of 4096 bytes).
124 Since Linux 2.6.35, the default pipe capacity is 16 pages,
125 but the capacity can be queried and set using the
133 for more information.
137 operation, which can be applied to a file descriptor
138 that refers to either end of a pipe,
139 places a count of the number of unread bytes in the pipe in the
141 buffer pointed to by the final argument of the call:
145 ioctl(fd, FIONREAD, &nbytes);
151 operation is not specified in any standard,
152 but is provided on many implementations.
155 On Linux, the following files control how much memory can be used for pipes:
157 .IR /proc/sys/fs/pipe\-max\-pages " (only in Linux 2.6.34)"
158 .\" commit b492e95be0ae672922f4734acf3f5d35c30be948
159 An upper limit, in pages, on the capacity that an unprivileged user
165 The default value for this limit is 16 times the default pipe capacity
166 (see above); the lower limit is two pages.
168 This interface was removed in Linux 2.6.35, in favor of
169 .IR /proc/sys/fs/pipe\-max\-size .
171 .IR /proc/sys/fs/pipe\-max\-size " (since Linux 2.6.35)"
172 .\" commit ff9da691c0498ff81fdd014e7a0731dab2337dac
173 The maximum size (in bytes) of individual pipes that can be set
174 .\" This limit is not checked on pipe creation, where the capacity is
175 .\" always PIPE_DEF_BUFS, regardless of pipe-max-size
179 The value assigned to this file may be rounded upward,
180 to reflect the value actually employed for a convenient implementation.
181 To determine the rounded-up value,
182 display the contents of this file after assigning a value to it.
184 The default value for this file is 1048576 (1\ MiB).
185 The minimum value that can be assigned to this file is the system page size.
186 Attempts to set a limit less than the page size cause
188 to fail with the error
192 .\" commit 086e774a57fba4695f14383c0818994c0b31da7c
193 the value on this file also acts as a ceiling on the default capacity
194 of a new pipe or newly opened FIFO.
196 .IR /proc/sys/fs/pipe\-user\-pages\-hard " (since Linux 4.5)"
197 .\" commit 759c01142a5d0f364a462346168a56de28a80f52
198 The hard limit on the total size (in pages) of all pipes created or set by
199 a single unprivileged user (i.e., one with neither the
204 So long as the total number of pages allocated to pipe buffers
205 for this user is at this limit,
206 attempts to create new pipes will be denied,
207 and attempts to increase a pipe's capacity will be denied.
209 When the value of this limit is zero (which is the default),
210 no hard limit is applied.
211 .\" The default was chosen to avoid breaking existing applications that
212 .\" make intensive use of pipes (e.g., for splicing).
214 .IR /proc/sys/fs/pipe\-user\-pages\-soft " (since Linux 4.5)"
215 .\" commit 759c01142a5d0f364a462346168a56de28a80f52
216 The soft limit on the total size (in pages) of all pipes created or set by
217 a single unprivileged user (i.e., one with neither the
222 So long as the total number of pages allocated to pipe buffers
223 for this user is at this limit,
224 individual pipes created by a user will be limited to one page,
225 and attempts to increase a pipe's capacity will be denied.
227 When the value of this limit is zero, no soft limit is applied.
228 The default value for this file is 16384,
229 which permits creating up to 1024 pipes with the default capacity.
231 Before Linux 4.9, some bugs affected the handling of the
232 .I pipe\-user\-pages\-soft
234 .I pipe\-user\-pages\-hard
238 POSIX.1 says that writes of less than
240 bytes must be atomic: the output data is written to the pipe as a
244 bytes may be nonatomic: the kernel may interleave the data
245 with data written by other processes.
248 to be at least 512 bytes.
252 The precise semantics depend on whether the file descriptor is nonblocking
254 whether there are multiple writers to the pipe, and on
256 the number of bytes to be written:
258 \fBO_NONBLOCK\fP disabled, \fIn\fP <= \fBPIPE_BUF\fP
261 bytes are written atomically;
263 may block if there is not room for
265 bytes to be written immediately
267 \fBO_NONBLOCK\fP enabled, \fIn\fP <= \fBPIPE_BUF\fP
268 If there is room to write
270 bytes to the pipe, then
272 succeeds immediately, writing all
281 \fBO_NONBLOCK\fP disabled, \fIn\fP > \fBPIPE_BUF\fP
282 The write is nonatomic: the data given to
284 may be interleaved with
291 bytes have been written.
293 \fBO_NONBLOCK\fP enabled, \fIn\fP > \fBPIPE_BUF\fP
294 If the pipe is full, then
302 bytes may be written (i.e., a "partial write" may occur;
303 the caller should check the return value from
305 to see how many bytes were actually written),
306 and these bytes may be interleaved with writes by other processes.
307 .SS Open file status flags
308 The only open file status flags that can be meaningfully applied to
316 flag for the read end of a pipe causes a signal
318 by default) to be generated when new input becomes available on the pipe.
319 The target for delivery of signals must be set using the
325 is supported for pipes and FIFOs only since Linux 2.6.
326 .SS Portability notes
327 On some systems (but not Linux), pipes are bidirectional:
328 data can be transmitted in both directions between the pipe ends.
329 POSIX.1 requires only unidirectional pipes.
330 Portable applications should avoid reliance on
331 bidirectional pipe semantics.
333 Before Linux 4.9, some bugs affected the handling of the
334 .I pipe\-user\-pages\-soft
336 .I pipe\-user\-pages\-hard
337 limits when using the
340 operation to change a pipe's capacity:
341 .\" These bugs where remedied by a series of patches, in particular,
342 .\" commit b0b91d18e2e97b741b294af9333824ecc3fadfd8 and
343 .\" commit a005ca0e6813e1d796a7422a7e31d8b8d6555df1
345 When increasing the pipe capacity, the checks against the soft and
346 hard limits were made against existing consumption,
347 and excluded the memory required for the increased pipe capacity.
348 The new increase in pipe capacity could then push the total
349 memory used by the user for pipes (possibly far) over a limit.
350 (This could also trigger the problem described next.)
352 Starting with Linux 4.9,
353 the limit checking includes the memory required for the new pipe capacity.
355 The limit checks were performed even when the new pipe capacity was
356 less than the existing pipe capacity.
357 This could lead to problems if a user set a large pipe capacity,
358 and then the limits were lowered, with the result that the user could
359 no longer decrease the pipe capacity.
361 Starting with Linux 4.9, checks against the limits
362 are performed only when increasing a pipe's capacity;
363 an unprivileged user can always decrease a pipe's capacity.
365 The accounting and checking against the limits were done as follows:
369 Test whether the user has exceeded the limit.
371 Make the new pipe buffer allocation.
373 Account new allocation against the limits.
378 Multiple processes could pass point (1) simultaneously,
379 and then allocate pipe buffers that were accounted for only in step (3),
380 with the result that the user's pipe buffer
381 allocation could be pushed over the limit.
383 Starting with Linux 4.9,
384 the accounting step is performed before doing the allocation,
385 and the operation fails if the limit would be exceeded.
387 Before Linux 4.9, bugs similar to points (a) and (c) could also occur
388 when the kernel allocated memory for a new pipe buffer;
389 that is, when calling
391 and when opening a previously unopened FIFO.