mirror of https://github.com/mkerrisk/man-pages
227 lines
6.5 KiB
Groff
227 lines
6.5 KiB
Groff
|
.\" 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)
|