1 .\" Copyright (C) 2005 Michael Kerrisk <mtk.manpages@gmail.com>
3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .TH PIPE 7 2021-08-27 "Linux" "Linux Programmer's Manual"
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.
59 Nonblocking I/O is possible by using the
62 operation to enable the
64 open file status flag.
66 The communication channel provided by a pipe is a
68 there is no concept of message boundaries.
70 If all file descriptors referring to the write end of a pipe
71 have been closed, then an attempt to
73 from the pipe will see end-of-file
76 If all file descriptors referring to the read end of a pipe
77 have been closed, then a
81 signal to be generated for the calling process.
82 If the calling process is ignoring this signal, then
86 An application that uses
92 calls to close unnecessary duplicate file descriptors;
93 this ensures that end-of-file and
95 are delivered when appropriate.
97 It is not possible to apply
101 A pipe has a limited capacity.
102 If the pipe is full, then a
104 will block or fail, depending on whether the
106 flag is set (see below).
107 Different implementations have different limits for the pipe capacity.
108 Applications should not rely on a particular capacity:
109 an application should be designed so that a reading process consumes data
110 as soon as it is available,
111 so that a writing process does not remain blocked.
113 In Linux versions before 2.6.11, the capacity of a pipe was the same as
114 the system page size (e.g., 4096 bytes on i386).
115 Since Linux 2.6.11, the pipe capacity is 16 pages
116 (i.e., 65,536 bytes in a system with a page size of 4096 bytes).
117 Since Linux 2.6.35, the default pipe capacity is 16 pages,
118 but the capacity can be queried and set using the
126 for more information.
130 operation, which can be applied to a file descriptor
131 that refers to either end of a pipe,
132 places a count of the number of unread bytes in the pipe in the
134 buffer pointed to by the final argument of the call:
138 ioctl(fd, FIONREAD, &nbytes);
144 operation is not specified in any standard,
145 but is provided on many implementations.
148 On Linux, the following files control how much memory can be used for pipes:
150 .IR /proc/sys/fs/pipe\-max\-pages " (only in Linux 2.6.34)"
151 .\" commit b492e95be0ae672922f4734acf3f5d35c30be948
152 An upper limit, in pages, on the capacity that an unprivileged user
158 The default value for this limit is 16 times the default pipe capacity
159 (see above); the lower limit is two pages.
161 This interface was removed in Linux 2.6.35, in favor of
162 .IR /proc/sys/fs/pipe\-max\-size .
164 .IR /proc/sys/fs/pipe\-max\-size " (since Linux 2.6.35)"
165 .\" commit ff9da691c0498ff81fdd014e7a0731dab2337dac
166 The maximum size (in bytes) of individual pipes that can be set
167 .\" This limit is not checked on pipe creation, where the capacity is
168 .\" always PIPE_DEF_BUFS, regardless of pipe-max-size
172 The value assigned to this file may be rounded upward,
173 to reflect the value actually employed for a convenient implementation.
174 To determine the rounded-up value,
175 display the contents of this file after assigning a value to it.
177 The default value for this file is 1048576 (1\ MiB).
178 The minimum value that can be assigned to this file is the system page size.
179 Attempts to set a limit less than the page size cause
181 to fail with the error
185 .\" commit 086e774a57fba4695f14383c0818994c0b31da7c
186 the value on this file also acts as a ceiling on the default capacity
187 of a new pipe or newly opened FIFO.
189 .IR /proc/sys/fs/pipe\-user\-pages\-hard " (since Linux 4.5)"
190 .\" commit 759c01142a5d0f364a462346168a56de28a80f52
191 The hard limit on the total size (in pages) of all pipes created or set by
192 a single unprivileged user (i.e., one with neither the
197 So long as the total number of pages allocated to pipe buffers
198 for this user is at this limit,
199 attempts to create new pipes will be denied,
200 and attempts to increase a pipe's capacity will be denied.
202 When the value of this limit is zero (which is the default),
203 no hard limit is applied.
204 .\" The default was chosen to avoid breaking existing applications that
205 .\" make intensive use of pipes (e.g., for splicing).
207 .IR /proc/sys/fs/pipe\-user\-pages\-soft " (since Linux 4.5)"
208 .\" commit 759c01142a5d0f364a462346168a56de28a80f52
209 The soft limit on the total size (in pages) of all pipes created or set by
210 a single unprivileged user (i.e., one with neither the
215 So long as the total number of pages allocated to pipe buffers
216 for this user is at this limit,
217 individual pipes created by a user will be limited to one page,
218 and attempts to increase a pipe's capacity will be denied.
220 When the value of this limit is zero, no soft limit is applied.
221 The default value for this file is 16384,
222 which permits creating up to 1024 pipes with the default capacity.
224 Before Linux 4.9, some bugs affected the handling of the
225 .I pipe\-user\-pages\-soft
227 .I pipe\-user\-pages\-hard
231 POSIX.1 says that writes of less than
233 bytes must be atomic: the output data is written to the pipe as a
237 bytes may be nonatomic: the kernel may interleave the data
238 with data written by other processes.
241 to be at least 512 bytes.
245 The precise semantics depend on whether the file descriptor is nonblocking
247 whether there are multiple writers to the pipe, and on
249 the number of bytes to be written:
251 \fBO_NONBLOCK\fP disabled, \fIn\fP <= \fBPIPE_BUF\fP
254 bytes are written atomically;
256 may block if there is not room for
258 bytes to be written immediately
260 \fBO_NONBLOCK\fP enabled, \fIn\fP <= \fBPIPE_BUF\fP
261 If there is room to write
263 bytes to the pipe, then
265 succeeds immediately, writing all
274 \fBO_NONBLOCK\fP disabled, \fIn\fP > \fBPIPE_BUF\fP
275 The write is nonatomic: the data given to
277 may be interleaved with
284 bytes have been written.
286 \fBO_NONBLOCK\fP enabled, \fIn\fP > \fBPIPE_BUF\fP
287 If the pipe is full, then
295 bytes may be written (i.e., a "partial write" may occur;
296 the caller should check the return value from
298 to see how many bytes were actually written),
299 and these bytes may be interleaved with writes by other processes.
300 .SS Open file status flags
301 The only open file status flags that can be meaningfully applied to
309 flag for the read end of a pipe causes a signal
311 by default) to be generated when new input becomes available on the pipe.
312 The target for delivery of signals must be set using the
318 is supported for pipes and FIFOs only since kernel 2.6.
319 .SS Portability notes
320 On some systems (but not Linux), pipes are bidirectional:
321 data can be transmitted in both directions between the pipe ends.
322 POSIX.1 requires only unidirectional pipes.
323 Portable applications should avoid reliance on
324 bidirectional pipe semantics.
326 Before Linux 4.9, some bugs affected the handling of the
327 .I pipe\-user\-pages\-soft
329 .I pipe\-user\-pages\-hard
330 limits when using the
333 operation to change a pipe's capacity:
334 .\" These bugs where remedied by a series of patches, in particular,
335 .\" commit b0b91d18e2e97b741b294af9333824ecc3fadfd8 and
336 .\" commit a005ca0e6813e1d796a7422a7e31d8b8d6555df1
338 When increasing the pipe capacity, the checks against the soft and
339 hard limits were made against existing consumption,
340 and excluded the memory required for the increased pipe capacity.
341 The new increase in pipe capacity could then push the total
342 memory used by the user for pipes (possibly far) over a limit.
343 (This could also trigger the problem described next.)
345 Starting with Linux 4.9,
346 the limit checking includes the memory required for the new pipe capacity.
348 The limit checks were performed even when the new pipe capacity was
349 less than the existing pipe capacity.
350 This could lead to problems if a user set a large pipe capacity,
351 and then the limits were lowered, with the result that the user could
352 no longer decrease the pipe capacity.
354 Starting with Linux 4.9, checks against the limits
355 are performed only when increasing a pipe's capacity;
356 an unprivileged user can always decrease a pipe's capacity.
358 The accounting and checking against the limits were done as follows:
363 Test whether the user has exceeded the limit.
365 Make the new pipe buffer allocation.
367 Account new allocation against the limits.
372 Multiple processes could pass point (a) simultaneously,
373 and then allocate pipe buffers that were accounted for only in step (c),
374 with the result that the user's pipe buffer
375 allocation could be pushed over the limit.
377 Starting with Linux 4.9,
378 the accounting step is performed before doing the allocation,
379 and the operation fails if the limit would be exceeded.
381 Before Linux 4.9, bugs similar to points (1) and (3) could also occur
382 when the kernel allocated memory for a new pipe buffer;
383 that is, when calling
385 and when opening a previously unopened FIFO.
projects / thirdparty / man-pages.git / blob