summaryrefslogtreecommitdiffstats
path: root/man7/pipe.7
diff options
context:
space:
mode:
Diffstat (limited to 'man7/pipe.7')
-rw-r--r--man7/pipe.7407
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)