diff options
Diffstat (limited to 'man7/pipe.7')
| -rw-r--r-- | man7/pipe.7 | 407 |
1 files changed, 0 insertions, 407 deletions
diff --git a/man7/pipe.7 b/man7/pipe.7 deleted file mode 100644 index bebb856..0000000 --- a/man7/pipe.7 +++ /dev/null @@ -1,407 +0,0 @@ -.\" Copyright (C) 2005 Michael Kerrisk <mtk.manpages@gmail.com> -.\" -.\" SPDX-License-Identifier: Linux-man-pages-copyleft -.\" -.TH pipe 7 2023-10-31 "Linux man-pages 6.7" -.SH NAME -pipe \- overview of pipes and FIFOs -.SH DESCRIPTION -Pipes and FIFOs (also known as named pipes) -provide a unidirectional interprocess communication channel. -A pipe has a -.I read end -and a -.IR "write end" . -Data written to the write end of a pipe can be read -from the read end of the pipe. -.P -A pipe is created using -.BR pipe (2), -which creates a new pipe and returns two file descriptors, -one referring to the read end of the pipe, -the other referring to the write end. -Pipes can be used to create a communication channel between related -processes; see -.BR pipe (2) -for an example. -.P -A FIFO (short for First In First Out) has a name within the filesystem -(created using -.BR mkfifo (3)), -and is opened using -.BR open (2). -Any process may open a FIFO, assuming the file permissions allow it. -The read end is opened using the -.B O_RDONLY -flag; the write end is opened using the -.B O_WRONLY -flag. -See -.BR fifo (7) -for further details. -.IR Note : -although FIFOs have a pathname in the filesystem, -I/O on FIFOs does not involve operations on the underlying device -(if there is one). -.SS I/O on pipes and FIFOs -The only difference between pipes and FIFOs is the manner in which -they are created and opened. -Once these tasks have been accomplished, -I/O on pipes and FIFOs has exactly the same semantics. -.P -If a process attempts to read from an empty pipe, then -.BR read (2) -will block until data is available. -If a process attempts to write to a full pipe (see below), then -.BR write (2) -blocks until sufficient data has been read from the pipe -to allow the write to complete. -.P -Nonblocking I/O is possible by using the -.BR fcntl (2) -.B F_SETFL -operation to enable the -.B O_NONBLOCK -open file status flag or by opening a -.BR fifo (7) -with -.BR O_NONBLOCK . -If any process has the pipe open for writing, reads fail with -.BR EAGAIN ; -otherwise\[em]with no potential writers\[em]reads succeed and return empty. -.P -The communication channel provided by a pipe is a -.IR "byte stream" : -there is no concept of message boundaries. -.P -If all file descriptors referring to the write end of a pipe -have been closed, then an attempt to -.BR read (2) -from the pipe will see end-of-file -.RB ( read (2) -will return 0). -If all file descriptors referring to the read end of a pipe -have been closed, then a -.BR write (2) -will cause a -.B SIGPIPE -signal to be generated for the calling process. -If the calling process is ignoring this signal, then -.BR write (2) -fails with the error -.BR EPIPE . -An application that uses -.BR pipe (2) -and -.BR fork (2) -should use suitable -.BR close (2) -calls to close unnecessary duplicate file descriptors; -this ensures that end-of-file and -.BR SIGPIPE / EPIPE -are delivered when appropriate. -.P -It is not possible to apply -.BR lseek (2) -to a pipe. -.SS Pipe capacity -A pipe has a limited capacity. -If the pipe is full, then a -.BR write (2) -will block or fail, depending on whether the -.B O_NONBLOCK -flag is set (see below). -Different implementations have different limits for the pipe capacity. -Applications should not rely on a particular capacity: -an application should be designed so that a reading process consumes data -as soon as it is available, -so that a writing process does not remain blocked. -.P -Before Linux 2.6.11, the capacity of a pipe was the same as -the system page size (e.g., 4096 bytes on i386). -Since Linux 2.6.11, the pipe capacity is 16 pages -(i.e., 65,536 bytes in a system with a page size of 4096 bytes). -Since Linux 2.6.35, the default pipe capacity is 16 pages, -but the capacity can be queried and set using the -.BR fcntl (2) -.B F_GETPIPE_SZ -and -.B F_SETPIPE_SZ -operations. -See -.BR fcntl (2) -for more information. -.P -The following -.BR ioctl (2) -operation, which can be applied to a file descriptor -that refers to either end of a pipe, -places a count of the number of unread bytes in the pipe in the -.I int -buffer pointed to by the final argument of the call: -.P -.in +4n -.EX -ioctl(fd, FIONREAD, &nbytes); -.EE -.in -.P -The -.B FIONREAD -operation is not specified in any standard, -but is provided on many implementations. -.\" -.SS /proc files -On Linux, the following files control how much memory can be used for pipes: -.TP -.IR /proc/sys/fs/pipe\-max\-pages " (only in Linux 2.6.34)" -.\" commit b492e95be0ae672922f4734acf3f5d35c30be948 -An upper limit, in pages, on the capacity that an unprivileged user -(one without the -.B CAP_SYS_RESOURCE -capability) -can set for a pipe. -.IP -The default value for this limit is 16 times the default pipe capacity -(see above); the lower limit is two pages. -.IP -This interface was removed in Linux 2.6.35, in favor of -.IR /proc/sys/fs/pipe\-max\-size . -.TP -.IR /proc/sys/fs/pipe\-max\-size " (since Linux 2.6.35)" -.\" commit ff9da691c0498ff81fdd014e7a0731dab2337dac -The maximum size (in bytes) of individual pipes that can be set -.\" This limit is not checked on pipe creation, where the capacity is -.\" always PIPE_DEF_BUFS, regardless of pipe-max-size -by users without the -.B CAP_SYS_RESOURCE -capability. -The value assigned to this file may be rounded upward, -to reflect the value actually employed for a convenient implementation. -To determine the rounded-up value, -display the contents of this file after assigning a value to it. -.IP -The default value for this file is 1048576 (1\ MiB). -The minimum value that can be assigned to this file is the system page size. -Attempts to set a limit less than the page size cause -.BR write (2) -to fail with the error -.BR EINVAL . -.IP -Since Linux 4.9, -.\" commit 086e774a57fba4695f14383c0818994c0b31da7c -the value on this file also acts as a ceiling on the default capacity -of a new pipe or newly opened FIFO. -.TP -.IR /proc/sys/fs/pipe\-user\-pages\-hard " (since Linux 4.5)" -.\" commit 759c01142a5d0f364a462346168a56de28a80f52 -The hard limit on the total size (in pages) of all pipes created or set by -a single unprivileged user (i.e., one with neither the -.B CAP_SYS_RESOURCE -nor the -.B CAP_SYS_ADMIN -capability). -So long as the total number of pages allocated to pipe buffers -for this user is at this limit, -attempts to create new pipes will be denied, -and attempts to increase a pipe's capacity will be denied. -.IP -When the value of this limit is zero (which is the default), -no hard limit is applied. -.\" The default was chosen to avoid breaking existing applications that -.\" make intensive use of pipes (e.g., for splicing). -.TP -.IR /proc/sys/fs/pipe\-user\-pages\-soft " (since Linux 4.5)" -.\" commit 759c01142a5d0f364a462346168a56de28a80f52 -The soft limit on the total size (in pages) of all pipes created or set by -a single unprivileged user (i.e., one with neither the -.B CAP_SYS_RESOURCE -nor the -.B CAP_SYS_ADMIN -capability). -So long as the total number of pages allocated to pipe buffers -for this user is at this limit, -individual pipes created by a user will be limited to one page, -and attempts to increase a pipe's capacity will be denied. -.IP -When the value of this limit is zero, no soft limit is applied. -The default value for this file is 16384, -which permits creating up to 1024 pipes with the default capacity. -.P -Before Linux 4.9, some bugs affected the handling of the -.I pipe\-user\-pages\-soft -and -.I pipe\-user\-pages\-hard -limits; see BUGS. -.\" -.SS PIPE_BUF -POSIX.1 says that writes of less than -.B PIPE_BUF -bytes must be atomic: the output data is written to the pipe as a -contiguous sequence. -Writes of more than -.B PIPE_BUF -bytes may be nonatomic: the kernel may interleave the data -with data written by other processes. -POSIX.1 requires -.B PIPE_BUF -to be at least 512 bytes. -(On Linux, -.B PIPE_BUF -is 4096 bytes.) -The precise semantics depend on whether the file descriptor is nonblocking -.RB ( O_NONBLOCK ), -whether there are multiple writers to the pipe, and on -.IR n , -the number of bytes to be written: -.TP -\fBO_NONBLOCK\fP disabled, \fIn\fP <= \fBPIPE_BUF\fP -All -.I n -bytes are written atomically; -.BR write (2) -may block if there is not room for -.I n -bytes to be written immediately -.TP -\fBO_NONBLOCK\fP enabled, \fIn\fP <= \fBPIPE_BUF\fP -If there is room to write -.I n -bytes to the pipe, then -.BR write (2) -succeeds immediately, writing all -.I n -bytes; otherwise -.BR write (2) -fails, with -.I errno -set to -.BR EAGAIN . -.TP -\fBO_NONBLOCK\fP disabled, \fIn\fP > \fBPIPE_BUF\fP -The write is nonatomic: the data given to -.BR write (2) -may be interleaved with -.BR write (2)s -by other process; -the -.BR write (2) -blocks until -.I n -bytes have been written. -.TP -\fBO_NONBLOCK\fP enabled, \fIn\fP > \fBPIPE_BUF\fP -If the pipe is full, then -.BR write (2) -fails, with -.I errno -set to -.BR EAGAIN . -Otherwise, from 1 to -.I n -bytes may be written (i.e., a "partial write" may occur; -the caller should check the return value from -.BR write (2) -to see how many bytes were actually written), -and these bytes may be interleaved with writes by other processes. -.SS Open file status flags -The only open file status flags that can be meaningfully applied to -a pipe or FIFO are -.B O_NONBLOCK -and -.BR O_ASYNC . -.P -Setting the -.B O_ASYNC -flag for the read end of a pipe causes a signal -.RB ( SIGIO -by default) to be generated when new input becomes available on the pipe. -The target for delivery of signals must be set using the -.BR fcntl (2) -.B F_SETOWN -command. -On Linux, -.B O_ASYNC -is supported for pipes and FIFOs only since Linux 2.6. -.SS Portability notes -On some systems (but not Linux), pipes are bidirectional: -data can be transmitted in both directions between the pipe ends. -POSIX.1 requires only unidirectional pipes. -Portable applications should avoid reliance on -bidirectional pipe semantics. -.SS BUGS -Before Linux 4.9, some bugs affected the handling of the -.I pipe\-user\-pages\-soft -and -.I pipe\-user\-pages\-hard -limits when using the -.BR fcntl (2) -.B F_SETPIPE_SZ -operation to change a pipe's capacity: -.\" These bugs where remedied by a series of patches, in particular, -.\" commit b0b91d18e2e97b741b294af9333824ecc3fadfd8 and -.\" commit a005ca0e6813e1d796a7422a7e31d8b8d6555df1 -.IP (a) 5 -When increasing the pipe capacity, the checks against the soft and -hard limits were made against existing consumption, -and excluded the memory required for the increased pipe capacity. -The new increase in pipe capacity could then push the total -memory used by the user for pipes (possibly far) over a limit. -(This could also trigger the problem described next.) -.IP -Starting with Linux 4.9, -the limit checking includes the memory required for the new pipe capacity. -.IP (b) -The limit checks were performed even when the new pipe capacity was -less than the existing pipe capacity. -This could lead to problems if a user set a large pipe capacity, -and then the limits were lowered, with the result that the user could -no longer decrease the pipe capacity. -.IP -Starting with Linux 4.9, checks against the limits -are performed only when increasing a pipe's capacity; -an unprivileged user can always decrease a pipe's capacity. -.IP (c) -The accounting and checking against the limits were done as follows: -.RS -.IP (1) 5 -.PD 0 -Test whether the user has exceeded the limit. -.IP (2) -Make the new pipe buffer allocation. -.IP (3) -Account new allocation against the limits. -.PD -.RE -.IP -This was racey. -Multiple processes could pass point (1) simultaneously, -and then allocate pipe buffers that were accounted for only in step (3), -with the result that the user's pipe buffer -allocation could be pushed over the limit. -.IP -Starting with Linux 4.9, -the accounting step is performed before doing the allocation, -and the operation fails if the limit would be exceeded. -.P -Before Linux 4.9, bugs similar to points (a) and (c) could also occur -when the kernel allocated memory for a new pipe buffer; -that is, when calling -.BR pipe (2) -and when opening a previously unopened FIFO. -.SH SEE ALSO -.BR mkfifo (1), -.BR dup (2), -.BR fcntl (2), -.BR open (2), -.BR pipe (2), -.BR poll (2), -.BR select (2), -.BR socketpair (2), -.BR splice (2), -.BR stat (2), -.BR tee (2), -.BR vmsplice (2), -.BR mkfifo (3), -.BR epoll (7), -.BR fifo (7) |