{ "content": [ { "type": "text", "text": "# pipe(7) (man)\n\n**Summary:** pipe - overview of pipes and FIFOs\n\n## See Also\n\n- mkfifo(1)\n- dup(2)\n- fcntl(2)\n- open(2)\n- poll(2)\n- select(2)\n- socketpair(2)\n- splice(2)\n- stat(2)\n- tee(2)\n- vmsplice(2)\n- mkfifo(3)\n- epoll(7)\n- fifo(7)\n\n## Section Outline\n\n- **NAME** (2 lines)\n- **DESCRIPTION** (16 lines) — 5 subsections\n - I/O on pipes and FIFOs (23 lines)\n - Pipe capacity (21 lines)\n - /proc files (72 lines)\n - Open file status flags (8 lines)\n - Portability notes (42 lines)\n- **SEE ALSO** (3 lines)\n- **COLOPHON** (7 lines)\n\n## Full Content\n\n### NAME\n\npipe - overview of pipes and FIFOs\n\n### DESCRIPTION\n\nPipes and FIFOs (also known as named pipes) provide a unidirectional interprocess communica‐\ntion channel. A pipe has a read end and a write end. Data written to the write end of a\npipe can be read from the read end of the pipe.\n\nA pipe is created using pipe(2), which creates a new pipe and returns two file descriptors,\none referring to the read end of the pipe, the other referring to the write end. Pipes can\nbe used to create a communication channel between related processes; see pipe(2) for an exam‐\nple.\n\nA FIFO (short for First In First Out) has a name within the filesystem (created using mk‐‐\nfifo(3)), and is opened using open(2). Any process may open a FIFO, assuming the file per‐\nmissions allow it. The read end is opened using the ORDONLY flag; the write end is opened\nusing the OWRONLY flag. See fifo(7) for further details. Note: although FIFOs have a path‐\nname in the filesystem, I/O on FIFOs does not involve operations on the underlying device (if\nthere is one).\n\n#### I/O on pipes and FIFOs\n\nThe only difference between pipes and FIFOs is the manner in which they are created and\nopened. Once these tasks have been accomplished, I/O on pipes and FIFOs has exactly the same\nsemantics.\n\nIf a process attempts to read from an empty pipe, then read(2) will block until data is\navailable. If a process attempts to write to a full pipe (see below), then write(2) blocks\nuntil sufficient data has been read from the pipe to allow the write to complete. Nonblock‐\ning I/O is possible by using the fcntl(2) FSETFL operation to enable the ONONBLOCK open\nfile status flag.\n\nThe communication channel provided by a pipe is a byte stream: there is no concept of message\nboundaries.\n\nIf all file descriptors referring to the write end of a pipe have been closed, then an at‐\ntempt to read(2) from the pipe will see end-of-file (read(2) will return 0). If all file de‐\nscriptors referring to the read end of a pipe have been closed, then a write(2) will cause a\nSIGPIPE signal to be generated for the calling process. If the calling process is ignoring\nthis signal, then write(2) fails with the error EPIPE. An application that uses pipe(2) and\nfork(2) should use suitable close(2) calls to close unnecessary duplicate file descriptors;\nthis ensures that end-of-file and SIGPIPE/EPIPE are delivered when appropriate.\n\nIt is not possible to apply lseek(2) to a pipe.\n\n#### Pipe capacity\n\nA pipe has a limited capacity. If the pipe is full, then a write(2) will block or fail, de‐\npending on whether the ONONBLOCK flag is set (see below). Different implementations have\ndifferent limits for the pipe capacity. Applications should not rely on a particular capac‐\nity: an application should be designed so that a reading process consumes data as soon as it\nis available, so that a writing process does not remain blocked.\n\nIn Linux versions before 2.6.11, the capacity of a pipe was the same as the system page size\n(e.g., 4096 bytes on i386). Since Linux 2.6.11, the pipe capacity is 16 pages (i.e., 65,536\nbytes in a system with a page size of 4096 bytes). Since Linux 2.6.35, the default pipe ca‐\npacity is 16 pages, but the capacity can be queried and set using the fcntl(2) FGETPIPESZ\nand FSETPIPESZ operations. See fcntl(2) for more information.\n\nThe following ioctl(2) operation, which can be applied to a file descriptor that refers to\neither end of a pipe, places a count of the number of unread bytes in the pipe in the int\nbuffer pointed to by the final argument of the call:\n\nioctl(fd, FIONREAD, &nbytes);\n\nThe FIONREAD operation is not specified in any standard, but is provided on many implementa‐\ntions.\n\n#### /proc files\n\nOn Linux, the following files control how much memory can be used for pipes:\n\n/proc/sys/fs/pipe-max-pages (only in Linux 2.6.34)\nAn upper limit, in pages, on the capacity that an unprivileged user (one without the\nCAPSYSRESOURCE capability) can set for a pipe.\n\nThe default value for this limit is 16 times the default pipe capacity (see above);\nthe lower limit is two pages.\n\nThis interface was removed in Linux 2.6.35, in favor of /proc/sys/fs/pipe-max-size.\n\n/proc/sys/fs/pipe-max-size (since Linux 2.6.35)\nThe maximum size (in bytes) of individual pipes that can be set by users without the\nCAPSYSRESOURCE capability. The value assigned to this file may be rounded upward,\nto reflect the value actually employed for a convenient implementation. To determine\nthe rounded-up value, display the contents of this file after assigning a value to it.\n\nThe default value for this file is 1048576 (1 MiB). The minimum value that can be as‐\nsigned to this file is the system page size. Attempts to set a limit less than the\npage size cause write(2) to fail with the error EINVAL.\n\nSince Linux 4.9, the value on this file also acts as a ceiling on the default capacity\nof a new pipe or newly opened FIFO.\n\n/proc/sys/fs/pipe-user-pages-hard (since Linux 4.5)\nThe hard limit on the total size (in pages) of all pipes created or set by a single\nunprivileged user (i.e., one with neither the CAPSYSRESOURCE nor the CAPSYSADMIN\ncapability). So long as the total number of pages allocated to pipe buffers for this\nuser is at this limit, attempts to create new pipes will be denied, and attempts to\nincrease a pipe's capacity will be denied.\n\nWhen the value of this limit is zero (which is the default), no hard limit is applied.\n\n/proc/sys/fs/pipe-user-pages-soft (since Linux 4.5)\nThe soft limit on the total size (in pages) of all pipes created or set by a single\nunprivileged user (i.e., one with neither the CAPSYSRESOURCE nor the CAPSYSADMIN\ncapability). So long as the total number of pages allocated to pipe buffers for this\nuser is at this limit, individual pipes created by a user will be limited to one page,\nand attempts to increase a pipe's capacity will be denied.\n\nWhen the value of this limit is zero, no soft limit is applied. The default value for\nthis file is 16384, which permits creating up to 1024 pipes with the default capacity.\n\nBefore Linux 4.9, some bugs affected the handling of the pipe-user-pages-soft and pipe-user-\npages-hard limits; see BUGS.\n\nPIPEBUF\nPOSIX.1 says that write(2)s of less than PIPEBUF bytes must be atomic: the output data is\nwritten to the pipe as a contiguous sequence. Writes of more than PIPEBUF bytes may be\nnonatomic: the kernel may interleave the data with data written by other processes. POSIX.1\nrequires PIPEBUF to be at least 512 bytes. (On Linux, PIPEBUF is 4096 bytes.) The precise\nsemantics depend on whether the file descriptor is nonblocking (ONONBLOCK), whether there\nare multiple writers to the pipe, and on n, the number of bytes to be written:\n\nONONBLOCK disabled, n <= PIPEBUF\nAll n bytes are written atomically; write(2) may block if there is not room for n\nbytes to be written immediately\n\nONONBLOCK enabled, n <= PIPEBUF\nIf there is room to write n bytes to the pipe, then write(2) succeeds immediately,\nwriting all n bytes; otherwise write(2) fails, with errno set to EAGAIN.\n\nONONBLOCK disabled, n > PIPEBUF\nThe write is nonatomic: the data given to write(2) may be interleaved with write(2)s\nby other process; the write(2) blocks until n bytes have been written.\n\nONONBLOCK enabled, n > PIPEBUF\nIf the pipe is full, then write(2) fails, with errno set to EAGAIN. Otherwise, from 1\nto n bytes may be written (i.e., a \"partial write\" may occur; the caller should check\nthe return value from write(2) to see how many bytes were actually written), and these\nbytes may be interleaved with writes by other processes.\n\n#### Open file status flags\n\nThe only open file status flags that can be meaningfully applied to a pipe or FIFO are ONON‐‐\nBLOCK and OASYNC.\n\nSetting the OASYNC flag for the read end of a pipe causes a signal (SIGIO by default) to be\ngenerated when new input becomes available on the pipe. The target for delivery of signals\nmust be set using the fcntl(2) FSETOWN command. On Linux, OASYNC is supported for pipes\nand FIFOs only since kernel 2.6.\n\n#### Portability notes\n\nOn some systems (but not Linux), pipes are bidirectional: data can be transmitted in both di‐\nrections between the pipe ends. POSIX.1 requires only unidirectional pipes. Portable appli‐\ncations should avoid reliance on bidirectional pipe semantics.\n\nBUGS\nBefore Linux 4.9, some bugs affected the handling of the pipe-user-pages-soft and pipe-user-\npages-hard limits when using the fcntl(2) FSETPIPESZ operation to change a pipe's capacity:\n\n(1) When increasing the pipe capacity, the checks against the soft and hard limits were made\nagainst existing consumption, and excluded the memory required for the increased pipe\ncapacity. The new increase in pipe capacity could then push the total memory used by\nthe user for pipes (possibly far) over a limit. (This could also trigger the problem\ndescribed next.)\n\nStarting with Linux 4.9, the limit checking includes the memory required for the new\npipe capacity.\n\n(2) The limit checks were performed even when the new pipe capacity was less than the exist‐\ning pipe capacity. This could lead to problems if a user set a large pipe capacity, and\nthen the limits were lowered, with the result that the user could no longer decrease the\npipe capacity.\n\nStarting with Linux 4.9, checks against the limits are performed only when increasing a\npipe's capacity; an unprivileged user can always decrease a pipe's capacity.\n\n(3) The accounting and checking against the limits were done as follows:\n\n(a) Test whether the user has exceeded the limit.\n(b) Make the new pipe buffer allocation.\n(c) Account new allocation against the limits.\n\nThis was racey. Multiple processes could pass point (a) simultaneously, and then allo‐\ncate pipe buffers that were accounted for only in step (c), with the result that the\nuser's pipe buffer allocation could be pushed over the limit.\n\nStarting with Linux 4.9, the accounting step is performed before doing the allocation,\nand the operation fails if the limit would be exceeded.\n\nBefore Linux 4.9, bugs similar to points (1) and (3) could also occur when the kernel allo‐\ncated memory for a new pipe buffer; that is, when calling pipe(2) and when opening a previ‐\nously unopened FIFO.\n\n### SEE ALSO\n\nmkfifo(1), dup(2), fcntl(2), open(2), pipe(2), poll(2), select(2), socketpair(2), splice(2),\nstat(2), tee(2), vmsplice(2), mkfifo(3), epoll(7), fifo(7)\n\n### COLOPHON\n\nThis page is part of release 5.10 of the Linux man-pages project. A description of the\nproject, information about reporting bugs, and the latest version of this page, can be found\nat https://www.kernel.org/doc/man-pages/.\n\n\n\nLinux 2017-09-15 PIPE(7)\n\n" } ], "structuredContent": { "command": "pipe", "section": "7", "mode": "man", "summary": "pipe - overview of pipes and FIFOs", "synopsis": null, "flags": [], "examples": [], "see_also": [ { "name": "mkfifo", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/mkfifo/1/json" }, { "name": "dup", "section": "2", "url": "https://www.chedong.com/phpMan.php/man/dup/2/json" }, { "name": "fcntl", "section": "2", "url": "https://www.chedong.com/phpMan.php/man/fcntl/2/json" }, { "name": "open", "section": "2", "url": "https://www.chedong.com/phpMan.php/man/open/2/json" }, { "name": "poll", "section": "2", "url": "https://www.chedong.com/phpMan.php/man/poll/2/json" }, { "name": "select", "section": "2", "url": "https://www.chedong.com/phpMan.php/man/select/2/json" }, { "name": "socketpair", "section": "2", "url": "https://www.chedong.com/phpMan.php/man/socketpair/2/json" }, { "name": "splice", "section": "2", "url": "https://www.chedong.com/phpMan.php/man/splice/2/json" }, { "name": "stat", "section": "2", "url": "https://www.chedong.com/phpMan.php/man/stat/2/json" }, { "name": "tee", "section": "2", "url": "https://www.chedong.com/phpMan.php/man/tee/2/json" }, { "name": "vmsplice", "section": "2", "url": "https://www.chedong.com/phpMan.php/man/vmsplice/2/json" }, { "name": "mkfifo", "section": "3", "url": "https://www.chedong.com/phpMan.php/man/mkfifo/3/json" }, { "name": "epoll", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/epoll/7/json" }, { "name": "fifo", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/fifo/7/json" } ], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "DESCRIPTION", "lines": 16, "subsections": [ { "name": "I/O on pipes and FIFOs", "lines": 23 }, { "name": "Pipe capacity", "lines": 21 }, { "name": "/proc files", "lines": 72 }, { "name": "Open file status flags", "lines": 8 }, { "name": "Portability notes", "lines": 42 } ] }, { "name": "SEE ALSO", "lines": 3, "subsections": [] }, { "name": "COLOPHON", "lines": 7, "subsections": [] } ] } }