| 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) |