582 lines
15 KiB
HTML
582 lines
15 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of PIPE</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>PIPE</H1>
|
|
Section: Linux Programmer's Manual (7)<BR>Updated: 2017-09-15<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
pipe - overview of pipes and FIFOs
|
|
<A NAME="lbAC"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
Pipes and FIFOs (also known as named pipes)
|
|
provide a unidirectional interprocess communication channel.
|
|
A pipe has a
|
|
<I>read end</I>
|
|
|
|
and a
|
|
<I>write end</I>.
|
|
|
|
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
|
|
<B><A HREF="/cgi-bin/man/man2html?2+pipe">pipe</A></B>(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
|
|
<B><A HREF="/cgi-bin/man/man2html?2+pipe">pipe</A></B>(2)
|
|
|
|
for an example.
|
|
<P>
|
|
|
|
A FIFO (short for First In First Out) has a name within the filesystem
|
|
(created using
|
|
<B><A HREF="/cgi-bin/man/man2html?3+mkfifo">mkfifo</A></B>(3)),
|
|
|
|
and is opened using
|
|
<B><A HREF="/cgi-bin/man/man2html?2+open">open</A></B>(2).
|
|
|
|
Any process may open a FIFO, assuming the file permissions allow it.
|
|
The read end is opened using the
|
|
<B>O_RDONLY</B>
|
|
|
|
flag; the write end is opened using the
|
|
<B>O_WRONLY</B>
|
|
|
|
flag.
|
|
See
|
|
<B><A HREF="/cgi-bin/man/man2html?7+fifo">fifo</A></B>(7)
|
|
|
|
for further details.
|
|
<I>Note</I>:
|
|
|
|
although FIFOs have a pathname in the filesystem,
|
|
I/O on FIFOs does not involve operations on the underlying device
|
|
(if there is one).
|
|
<A NAME="lbAD"> </A>
|
|
<H3>I/O on pipes and FIFOs</H3>
|
|
|
|
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
|
|
<B><A HREF="/cgi-bin/man/man2html?2+read">read</A></B>(2)
|
|
|
|
will block until data is available.
|
|
If a process attempts to write to a full pipe (see below), then
|
|
<B><A HREF="/cgi-bin/man/man2html?2+write">write</A></B>(2)
|
|
|
|
blocks until sufficient data has been read from the pipe
|
|
to allow the write to complete.
|
|
Nonblocking I/O is possible by using the
|
|
<B><A HREF="/cgi-bin/man/man2html?2+fcntl">fcntl</A></B>(2)
|
|
|
|
<B>F_SETFL</B>
|
|
|
|
operation to enable the
|
|
<B>O_NONBLOCK</B>
|
|
|
|
open file status flag.
|
|
<P>
|
|
|
|
The communication channel provided by a pipe is a
|
|
<I>byte stream</I>:
|
|
|
|
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
|
|
<B><A HREF="/cgi-bin/man/man2html?2+read">read</A></B>(2)
|
|
|
|
from the pipe will see end-of-file
|
|
(<B><A HREF="/cgi-bin/man/man2html?2+read">read</A></B>(2)
|
|
|
|
will return 0).
|
|
If all file descriptors referring to the read end of a pipe
|
|
have been closed, then a
|
|
<B><A HREF="/cgi-bin/man/man2html?2+write">write</A></B>(2)
|
|
|
|
will cause a
|
|
<B>SIGPIPE</B>
|
|
|
|
signal to be generated for the calling process.
|
|
If the calling process is ignoring this signal, then
|
|
<B><A HREF="/cgi-bin/man/man2html?2+write">write</A></B>(2)
|
|
|
|
fails with the error
|
|
<B>EPIPE</B>.
|
|
|
|
An application that uses
|
|
<B><A HREF="/cgi-bin/man/man2html?2+pipe">pipe</A></B>(2)
|
|
|
|
and
|
|
<B><A HREF="/cgi-bin/man/man2html?2+fork">fork</A></B>(2)
|
|
|
|
should use suitable
|
|
<B><A HREF="/cgi-bin/man/man2html?2+close">close</A></B>(2)
|
|
|
|
calls to close unnecessary duplicate file descriptors;
|
|
this ensures that end-of-file and
|
|
<B>SIGPIPE</B>/<B>EPIPE</B>
|
|
|
|
are delivered when appropriate.
|
|
<P>
|
|
|
|
It is not possible to apply
|
|
<B><A HREF="/cgi-bin/man/man2html?2+lseek">lseek</A></B>(2)
|
|
|
|
to a pipe.
|
|
<A NAME="lbAE"> </A>
|
|
<H3>Pipe capacity</H3>
|
|
|
|
A pipe has a limited capacity.
|
|
If the pipe is full, then a
|
|
<B><A HREF="/cgi-bin/man/man2html?2+write">write</A></B>(2)
|
|
|
|
will block or fail, depending on whether the
|
|
<B>O_NONBLOCK</B>
|
|
|
|
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>
|
|
|
|
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 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
|
|
<B><A HREF="/cgi-bin/man/man2html?2+fcntl">fcntl</A></B>(2)
|
|
|
|
<B>F_GETPIPE_SZ</B>
|
|
|
|
and
|
|
<B>F_SETPIPE_SZ</B>
|
|
|
|
operations.
|
|
See
|
|
<B><A HREF="/cgi-bin/man/man2html?2+fcntl">fcntl</A></B>(2)
|
|
|
|
for more information.
|
|
<P>
|
|
|
|
The following
|
|
<B><A HREF="/cgi-bin/man/man2html?2+ioctl">ioctl</A></B>(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</I>
|
|
|
|
buffer pointed to by the final argument of the call:
|
|
<P>
|
|
|
|
<BR> ioctl(fd, FIONREAD, &nbytes);
|
|
<P>
|
|
|
|
The
|
|
<B>FIONREAD</B>
|
|
|
|
operation is not specified in any standard,
|
|
but is provided on many implementations.
|
|
|
|
<A NAME="lbAF"> </A>
|
|
<H3>/proc files</H3>
|
|
|
|
On Linux, the following files control how much memory can be used for pipes:
|
|
<DL COMPACT>
|
|
<DT id="1"><I>/proc/sys/fs/pipe-max-pages</I> (only in Linux 2.6.34)
|
|
|
|
<DD>
|
|
|
|
An upper limit, in pages, on the capacity that an unprivileged user
|
|
(one without the
|
|
<B>CAP_SYS_RESOURCE</B>
|
|
|
|
capability)
|
|
can set for a pipe.
|
|
<DT id="2"><DD>
|
|
The default value for this limit is 16 times the default pipe capacity
|
|
(see above); the lower limit is two pages.
|
|
<DT id="3"><DD>
|
|
This interface was removed in Linux 2.6.35, in favor of
|
|
<I>/proc/sys/fs/pipe-max-size</I>.
|
|
|
|
<DT id="4"><I>/proc/sys/fs/pipe-max-size</I> (since Linux 2.6.35)
|
|
|
|
<DD>
|
|
|
|
The maximum size (in bytes) of individual pipes that can be set
|
|
|
|
|
|
by users without the
|
|
<B>CAP_SYS_RESOURCE</B>
|
|
|
|
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.
|
|
<DT id="5"><DD>
|
|
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
|
|
<B><A HREF="/cgi-bin/man/man2html?2+write">write</A></B>(2)
|
|
|
|
to fail with the error
|
|
<B>EINVAL</B>.
|
|
|
|
<DT id="6"><DD>
|
|
Since Linux 4.9,
|
|
|
|
the value on this file also acts as a ceiling on the default capacity
|
|
of a new pipe or newly opened FIFO.
|
|
<DT id="7"><I>/proc/sys/fs/pipe-user-pages-hard</I> (since Linux 4.5)
|
|
|
|
<DD>
|
|
|
|
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</B>
|
|
|
|
nor the
|
|
<B>CAP_SYS_ADMIN</B>
|
|
|
|
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.
|
|
<DT id="8"><DD>
|
|
When the value of this limit is zero (which is the default),
|
|
no hard limit is applied.
|
|
|
|
|
|
<DT id="9"><I>/proc/sys/fs/pipe-user-pages-soft</I> (since Linux 4.5)
|
|
|
|
<DD>
|
|
|
|
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</B>
|
|
|
|
nor the
|
|
<B>CAP_SYS_ADMIN</B>
|
|
|
|
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.
|
|
<DT id="10"><DD>
|
|
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.
|
|
</DL>
|
|
<P>
|
|
|
|
Before Linux 4.9, some bugs affected the handling of the
|
|
<I>pipe-user-pages-soft</I>
|
|
|
|
and
|
|
<I>pipe-user-pages-hard</I>
|
|
|
|
limits; see BUGS.
|
|
|
|
<A NAME="lbAG"> </A>
|
|
<H3>PIPE_BUF</H3>
|
|
|
|
POSIX.1 says that
|
|
<B><A HREF="/cgi-bin/man/man2html?2+write">write</A></B>(2)s
|
|
|
|
of less than
|
|
<B>PIPE_BUF</B>
|
|
|
|
bytes must be atomic: the output data is written to the pipe as a
|
|
contiguous sequence.
|
|
Writes of more than
|
|
<B>PIPE_BUF</B>
|
|
|
|
bytes may be nonatomic: the kernel may interleave the data
|
|
with data written by other processes.
|
|
POSIX.1 requires
|
|
<B>PIPE_BUF</B>
|
|
|
|
to be at least 512 bytes.
|
|
(On Linux,
|
|
<B>PIPE_BUF</B>
|
|
|
|
is 4096 bytes.)
|
|
The precise semantics depend on whether the file descriptor is nonblocking
|
|
(<B>O_NONBLOCK</B>),
|
|
|
|
whether there are multiple writers to the pipe, and on
|
|
<I>n</I>,
|
|
|
|
the number of bytes to be written:
|
|
<DL COMPACT>
|
|
<DT id="11"><B>O_NONBLOCK</B> disabled, <I>n</I> <= <B>PIPE_BUF</B><DD>
|
|
All
|
|
<I>n</I>
|
|
|
|
bytes are written atomically;
|
|
<B><A HREF="/cgi-bin/man/man2html?2+write">write</A></B>(2)
|
|
|
|
may block if there is not room for
|
|
<I>n</I>
|
|
|
|
bytes to be written immediately
|
|
<DT id="12"><B>O_NONBLOCK</B> enabled, <I>n</I> <= <B>PIPE_BUF</B><DD>
|
|
If there is room to write
|
|
<I>n</I>
|
|
|
|
bytes to the pipe, then
|
|
<B><A HREF="/cgi-bin/man/man2html?2+write">write</A></B>(2)
|
|
|
|
succeeds immediately, writing all
|
|
<I>n</I>
|
|
|
|
bytes; otherwise
|
|
<B><A HREF="/cgi-bin/man/man2html?2+write">write</A></B>(2)
|
|
|
|
fails, with
|
|
<I>errno</I>
|
|
|
|
set to
|
|
<B>EAGAIN</B>.
|
|
|
|
<DT id="13"><B>O_NONBLOCK</B> disabled, <I>n</I> > <B>PIPE_BUF</B><DD>
|
|
The write is nonatomic: the data given to
|
|
<B><A HREF="/cgi-bin/man/man2html?2+write">write</A></B>(2)
|
|
|
|
may be interleaved with
|
|
<B><A HREF="/cgi-bin/man/man2html?2+write">write</A></B>(2)s
|
|
|
|
by other process;
|
|
the
|
|
<B><A HREF="/cgi-bin/man/man2html?2+write">write</A></B>(2)
|
|
|
|
blocks until
|
|
<I>n</I>
|
|
|
|
bytes have been written.
|
|
<DT id="14"><B>O_NONBLOCK</B> enabled, <I>n</I> > <B>PIPE_BUF</B><DD>
|
|
If the pipe is full, then
|
|
<B><A HREF="/cgi-bin/man/man2html?2+write">write</A></B>(2)
|
|
|
|
fails, with
|
|
<I>errno</I>
|
|
|
|
set to
|
|
<B>EAGAIN</B>.
|
|
|
|
Otherwise, from 1 to
|
|
<I>n</I>
|
|
|
|
bytes may be written (i.e., a "partial write" may occur;
|
|
the caller should check the return value from
|
|
<B><A HREF="/cgi-bin/man/man2html?2+write">write</A></B>(2)
|
|
|
|
to see how many bytes were actually written),
|
|
and these bytes may be interleaved with writes by other processes.
|
|
</DL>
|
|
<A NAME="lbAH"> </A>
|
|
<H3>Open file status flags</H3>
|
|
|
|
The only open file status flags that can be meaningfully applied to
|
|
a pipe or FIFO are
|
|
<B>O_NONBLOCK</B>
|
|
|
|
and
|
|
<B>O_ASYNC</B>.
|
|
|
|
<P>
|
|
|
|
Setting the
|
|
<B>O_ASYNC</B>
|
|
|
|
flag for the read end of a pipe causes a signal
|
|
(<B>SIGIO</B>
|
|
|
|
by default) to be generated when new input becomes available on the pipe.
|
|
The target for delivery of signals must be set using the
|
|
<B><A HREF="/cgi-bin/man/man2html?2+fcntl">fcntl</A></B>(2)
|
|
|
|
<B>F_SETOWN</B>
|
|
|
|
command.
|
|
On Linux,
|
|
<B>O_ASYNC</B>
|
|
|
|
is supported for pipes and FIFOs only since kernel 2.6.
|
|
<A NAME="lbAI"> </A>
|
|
<H3>Portability notes</H3>
|
|
|
|
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.
|
|
<A NAME="lbAJ"> </A>
|
|
<H3>BUGS</H3>
|
|
|
|
Before Linux 4.9, some bugs affected the handling of the
|
|
<I>pipe-user-pages-soft</I>
|
|
|
|
and
|
|
<I>pipe-user-pages-hard</I>
|
|
|
|
limits when using the
|
|
<B><A HREF="/cgi-bin/man/man2html?2+fcntl">fcntl</A></B>(2)
|
|
|
|
<B>F_SETPIPE_SZ</B>
|
|
|
|
operation to change a pipe's capacity:
|
|
|
|
|
|
|
|
<DL COMPACT>
|
|
<DT id="15">(1)<DD>
|
|
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.)
|
|
<DT id="16"><DD>
|
|
Starting with Linux 4.9,
|
|
the limit checking includes the memory required for the new pipe capacity.
|
|
<DT id="17">(2)<DD>
|
|
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.
|
|
<DT id="18"><DD>
|
|
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.
|
|
<DT id="19">(3)<DD>
|
|
The accounting and checking against the limits were done as follows:
|
|
<DT id="20"><DD>
|
|
<DL COMPACT><DT id="21"><DD>
|
|
|
|
<DL COMPACT>
|
|
<DT id="22">(a)<DD>
|
|
Test whether the user has exceeded the limit.
|
|
<DT id="23">(b)<DD>
|
|
Make the new pipe buffer allocation.
|
|
<DT id="24">(c)<DD>
|
|
Account new allocation against the limits.
|
|
|
|
</DL>
|
|
</DL>
|
|
|
|
<DT id="25"><DD>
|
|
This was racey.
|
|
Multiple processes could pass point (a) simultaneously,
|
|
and then allocate pipe buffers that were accounted for only in step (c),
|
|
with the result that the user's pipe buffer
|
|
allocation could be pushed over the limit.
|
|
<DT id="26"><DD>
|
|
Starting with Linux 4.9,
|
|
the accounting step is performed before doing the allocation,
|
|
and the operation fails if the limit would be exceeded.
|
|
</DL>
|
|
<P>
|
|
|
|
Before Linux 4.9, bugs similar to points (1) and (3) could also occur
|
|
when the kernel allocated memory for a new pipe buffer;
|
|
that is, when calling
|
|
<B><A HREF="/cgi-bin/man/man2html?2+pipe">pipe</A></B>(2)
|
|
|
|
and when opening a previously unopened FIFO.
|
|
<A NAME="lbAK"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?1+mkfifo">mkfifo</A></B>(1),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+dup">dup</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+fcntl">fcntl</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+open">open</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+pipe">pipe</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+poll">poll</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+select">select</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+socketpair">socketpair</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+splice">splice</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+stat">stat</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+tee">tee</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+vmsplice">vmsplice</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+mkfifo">mkfifo</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?7+epoll">epoll</A></B>(7),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?7+fifo">fifo</A></B>(7)
|
|
|
|
<A NAME="lbAL"> </A>
|
|
<H2>COLOPHON</H2>
|
|
|
|
This page is part of release 5.05 of the Linux
|
|
<I>man-pages</I>
|
|
|
|
project.
|
|
A description of the project,
|
|
information about reporting bugs,
|
|
and the latest version of this page,
|
|
can be found at
|
|
<A HREF="https://www.kernel.org/doc/man-pages/.">https://www.kernel.org/doc/man-pages/.</A>
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="27"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="28"><A HREF="#lbAC">DESCRIPTION</A><DD>
|
|
<DL>
|
|
<DT id="29"><A HREF="#lbAD">I/O on pipes and FIFOs</A><DD>
|
|
<DT id="30"><A HREF="#lbAE">Pipe capacity</A><DD>
|
|
<DT id="31"><A HREF="#lbAF">/proc files</A><DD>
|
|
<DT id="32"><A HREF="#lbAG">PIPE_BUF</A><DD>
|
|
<DT id="33"><A HREF="#lbAH">Open file status flags</A><DD>
|
|
<DT id="34"><A HREF="#lbAI">Portability notes</A><DD>
|
|
<DT id="35"><A HREF="#lbAJ">BUGS</A><DD>
|
|
</DL>
|
|
<DT id="36"><A HREF="#lbAK">SEE ALSO</A><DD>
|
|
<DT id="37"><A HREF="#lbAL">COLOPHON</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:06:09 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|