diff options
| author | Michael Kerrisk <mtk.manpages@gmail.com> | 2005-12-08 18:52:42 +0000 |
|---|---|---|
| committer | Michael Kerrisk <mtk.manpages@gmail.com> | 2005-12-08 18:52:42 +0000 |
| commit | 2adb3bd6da6ac78be61f5047a45cd2b47f710d04 (patch) | |
| tree | 1172e63ef8776bdd9426bca04079e7f8ab2d4b28 /man7/pipe.7 | |
| parent | 7b5c3d0a78a9718130ef57ceaef6b98fb9029279 (diff) | |
| download | man-pages-2adb3bd6da6ac78be61f5047a45cd2b47f710d04.tar.gz | |
New page providing overview of pipes and FIFOs.
Diffstat (limited to 'man7/pipe.7')
| -rw-r--r-- | man7/pipe.7 | 226 |
1 files changed, 226 insertions, 0 deletions
diff --git a/man7/pipe.7 b/man7/pipe.7 new file mode 100644 index 0000000000..c10cd29b3a --- /dev/null +++ b/man7/pipe.7 @@ -0,0 +1,226 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (C) 2005 Michael Kerrisk <mtk-manpages@gmx.net> +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH PIPE 7 2005-12-08 "Linux 2.6.15" "Linux Programmer's Manual" +.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 +by a process that has the read end of the pipe open. + +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 only allow communication between related processes: +one process creates the pipe, and then allows another process to inherit +duplicate file descriptors referring to the pipe as a result of calling +.BR fork (2). + +A FIFO (short for First In First Out) has a name within the file +system (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 (4) +for further details. +.IR Note : +although FIFOs have a pathname in the file system, +I/O on FIFOs does not involve disk operations. +.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. +I/O is performed using +.BR read (2) +and +.BR write (2). + +The communication channel provided by a pipe is a +.IR "byte stream" : +there is no concept of message boundaries; +data can be read and written in arbitrary amounts. + +By default, I/O on pipes and FIFOs is blocking. +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. +Non-blocking I/O is possible by using the +.BR fcntl (2) +.B F_SETFL +operation to enable the +.B O_NONBLOCK +open file status flag. + +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. + +It is not possible to use +.BR lseek (2) +to randomly access the bytes in 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. + +In Linux versions before 2.6.11, the capacity of a pipe was the same as +the system page size (e.g., 4096 bytes on x86). +Since Linux 2.6.11, the pipe capacity is 65536 bytes. +.SS PIPE_BUF +POSIX.1 says that +.BR write (2)s +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 non-atomic: 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 non-blocking +.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 non-atomic: 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 "Portability notes" +On some systems (but not Linux), pipes are bidirectional: +data can be transmitted in both directions between the pipe ends. +According to POSIX.1, pipes only need to be unidirectional. +Portable applications should avoid reliance on +bidirectional pipe semantics. +.SH "SEE ALSO" +.BR dup (2), +.BR fcntl (2), +.BR open (2), +.BR pipe (2), +.BR poll (2), +.BR select (2), +.BR socketpair (2), +.BR stat (2), +.BR mkfifo (3), +.BR fifo (4), +.BR epoll (4) |