From fc22b3d6507c6745911b9dfcc68f1e665ae13dbc Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 15 Apr 2024 21:43:11 +0200 Subject: Adding upstream version 4.22.0. Signed-off-by: Daniel Baumann --- upstream/fedora-rawhide/man7/pipe.7 | 407 ++++++++++++++++++++++++++++++++++++ 1 file changed, 407 insertions(+) create mode 100644 upstream/fedora-rawhide/man7/pipe.7 (limited to 'upstream/fedora-rawhide/man7/pipe.7') diff --git a/upstream/fedora-rawhide/man7/pipe.7 b/upstream/fedora-rawhide/man7/pipe.7 new file mode 100644 index 00000000..0fd53f9b --- /dev/null +++ b/upstream/fedora-rawhide/man7/pipe.7 @@ -0,0 +1,407 @@ +.\" Copyright (C) 2005 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pipe 7 2023-10-31 "Linux man-pages 6.06" +.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) -- cgit v1.2.3