original/man7/pipe.7

   1 .\" Copyright (C) 2005 Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM)
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .TH PIPE 7 2005-12-08 "Linux" "Linux Programmer's Manual"
  26 .SH NAME
  27 pipe \- overview of pipes and FIFOs
  28 .SH DESCRIPTION
  29 Pipes and FIFOs (also known as named pipes)
  30 provide a unidirectional interprocess communication channel.
  31 A pipe has a
  32 .I read end
  33 and a
  34 .IR "write end" .
  35 Data written to the write end of a pipe can be read
  36 from the read end of the pipe.
  37
  38 A pipe is created using
  39 .BR pipe (2),
  40 which creates a new pipe and returns two file descriptors,
  41 one referring to the read end of the pipe,
  42 the other referring to the write end.
  43 Pipes can be used to create a communication channel between related
  44 processes; see
  45 .BR pipe (2)
  46 for an example.
  47
  48 A FIFO (short for First In First Out) has a name within the filesystem
  49 (created using
  50 .BR mkfifo (3)),
  51 and is opened using
  52 .BR open (2).
  53 Any process may open a FIFO, assuming the file permissions allow it.
  54 The read end is opened using the
  55 .B O_RDONLY
  56 flag; the write end is opened using the
  57 .B O_WRONLY
  58 flag.
  59 See
  60 .BR fifo (7)
  61 for further details.
  62 .IR Note :
  63 although FIFOs have a pathname in the filesystem,
  64 I/O on FIFOs does not involve operations on the underlying device
  65 (if there is one).
  66 .SS I/O on pipes and FIFOs
  67 The only difference between pipes and FIFOs is the manner in which
  68 they are created and opened.
  69 Once these tasks have been accomplished,
  70 I/O on pipes and FIFOs has exactly the same semantics.
  71
  72 If a process attempts to read from an empty pipe, then
  73 .BR read (2)
  74 will block until data is available.
  75 If a process attempts to write to a full pipe (see below), then
  76 .BR write (2)
  77 blocks until sufficient data has been read from the pipe
  78 to allow the write to complete.
  79 Nonblocking I/O is possible by using the
  80 .BR fcntl (2)
  81 .B F_SETFL
  82 operation to enable the
  83 .B O_NONBLOCK
  84 open file status flag.
  85
  86 The communication channel provided by a pipe is a
  87 .IR "byte stream" :
  88 there is no concept of message boundaries.
  89
  90 If all file descriptors referring to the write end of a pipe
  91 have been closed, then an attempt to
  92 .BR read (2)
  93 from the pipe will see end-of-file
  94 .RB ( read (2)
  95 will return 0).
  96 If all file descriptors referring to the read end of a pipe
  97 have been closed, then a
  98 .BR write (2)
  99 will cause a
 100 .B SIGPIPE
 101 signal to be generated for the calling process.
 102 If the calling process is ignoring this signal, then
 103 .BR write (2)
 104 fails with the error
 105 .BR EPIPE .
 106 An application that uses
 107 .BR pipe (2)
 108 and
 109 .BR fork (2)
 110 should use suitable
 111 .BR close (2)
 112 calls to close unnecessary duplicate file descriptors;
 113 this ensures that end-of-file and
 114 .BR SIGPIPE / EPIPE
 115 are delivered when appropriate.
 116
 117 It is not possible to apply
 118 .BR lseek (2)
 119 to a pipe.
 120 .SS Pipe capacity
 121 A pipe has a limited capacity.
 122 If the pipe is full, then a
 123 .BR write (2)
 124 will block or fail, depending on whether the
 125 .B O_NONBLOCK
 126 flag is set (see below).
 127 Different implementations have different limits for the pipe capacity.
 128 Applications should not rely on a particular capacity:
 129 an application should be designed so that a reading process consumes data
 130 as soon as it is available,
 131 so that a writing process does not remain blocked.
 132
 133 In Linux versions before 2.6.11, the capacity of a pipe was the same as
 134 the system page size (e.g., 4096 bytes on i386).
 135 Since Linux 2.6.11, the pipe capacity is 65536 bytes.
 136 .SS PIPE_BUF
 137 POSIX.1-2001 says that
 138 .BR write (2)s
 139 of less than
 140 .B PIPE_BUF
 141 bytes must be atomic: the output data is written to the pipe as a
 142 contiguous sequence.
 143 Writes of more than
 144 .B PIPE_BUF
 145 bytes may be nonatomic: the kernel may interleave the data
 146 with data written by other processes.
 147 POSIX.1-2001 requires
 148 .B PIPE_BUF
 149 to be at least 512 bytes.
 150 (On Linux,
 151 .B PIPE_BUF
 152 is 4096 bytes.)
 153 The precise semantics depend on whether the file descriptor is nonblocking
 154 .RB ( O_NONBLOCK ),
 155 whether there are multiple writers to the pipe, and on
 156 .IR n ,
 157 the number of bytes to be written:
 158 .TP
 159 \fBO_NONBLOCK\fP disabled, \fIn\fP <= \fBPIPE_BUF\fP
 160 All
 161 .I n
 162 bytes are written atomically;
 163 .BR write (2)
 164 may block if there is not room for
 165 .I n
 166 bytes to be written immediately
 167 .TP
 168 \fBO_NONBLOCK\fP enabled, \fIn\fP <= \fBPIPE_BUF\fP
 169 If there is room to write
 170 .I n
 171 bytes to the pipe, then
 172 .BR write (2)
 173 succeeds immediately, writing all
 174 .I n
 175 bytes; otherwise
 176 .BR write (2)
 177 fails, with
 178 .I errno
 179 set to
 180 .BR EAGAIN .
 181 .TP
 182 \fBO_NONBLOCK\fP disabled, \fIn\fP > \fBPIPE_BUF\fP
 183 The write is nonatomic: the data given to
 184 .BR write (2)
 185 may be interleaved with
 186 .BR write (2)s
 187 by other process;
 188 the
 189 .BR write (2)
 190 blocks until
 191 .I n
 192 bytes have been written.
 193 .TP
 194 \fBO_NONBLOCK\fP enabled, \fIn\fP > \fBPIPE_BUF\fP
 195 If the pipe is full, then
 196 .BR write (2)
 197 fails, with
 198 .I errno
 199 set to
 200 .BR EAGAIN .
 201 Otherwise, from 1 to
 202 .I n
 203 bytes may be written (i.e., a "partial write" may occur;
 204 the caller should check the return value from
 205 .BR write (2)
 206 to see how many bytes were actually written),
 207 and these bytes may be interleaved with writes by other processes.
 208 .SS Open file status flags
 209 The only open file status flags that can be meaningfully applied to
 210 a pipe or FIFO are
 211 .B O_NONBLOCK
 212 and
 213 .BR O_ASYNC .
 214
 215 Setting the
 216 .B O_ASYNC
 217 flag for the read end of a pipe causes a signal
 218 .RB ( SIGIO
 219 by default) to be generated when new input becomes available on the pipe
 220 (see
 221 .BR fcntl (2)
 222 for details).
 223 On Linux,
 224 .B O_ASYNC
 225 is supported for pipes and FIFOs only since kernel 2.6.
 226 .SS Portability notes
 227 On some systems (but not Linux), pipes are bidirectional:
 228 data can be transmitted in both directions between the pipe ends.
 229 According to POSIX.1-2001, pipes only need to be unidirectional.
 230 Portable applications should avoid reliance on
 231 bidirectional pipe semantics.
 232 .SH SEE ALSO
 233 .BR dup (2),
 234 .BR fcntl (2),
 235 .BR open (2),
 236 .BR pipe (2),
 237 .BR poll (2),
 238 .BR select (2),
 239 .BR socketpair (2),
 240 .BR stat (2),
 241 .BR mkfifo (3),
 242 .BR epoll (7),
 243 .BR fifo (7)
 244 .SH COLOPHON
 245 This page is part of release 3.67 of the Linux
 246 .I man-pages
 247 project.
 248 A description of the project,
 249 information about reporting bugs,
 250 and the latest version of this page,
 251 can be found at
 252 \%http://www.kernel.org/doc/man\-pages/.