manual/pipe.texi

   1 @node Pipes and FIFOs, Sockets, File System Interface, Top
   2 @c %MENU% A simple interprocess communication mechanism
   3 @chapter Pipes and FIFOs
   4
   5 @cindex pipe
   6 A @dfn{pipe} is a mechanism for interprocess communication; data written
   7 to the pipe by one process can be read by another process.  The data is
   8 handled in a first-in, first-out (FIFO) order.  The pipe has no name; it
   9 is created for one use and both ends must be inherited from the single
  10 process which created the pipe.
  11
  12 @cindex FIFO special file
  13 A @dfn{FIFO special file} is similar to a pipe, but instead of being an
  14 anonymous, temporary connection, a FIFO has a name or names like any
  15 other file.  Processes open the FIFO by name in order to communicate
  16 through it.
  17
  18 A pipe or FIFO has to be open at both ends simultaneously.  If you read
  19 from a pipe or FIFO file that doesn't have any processes writing to it
  20 (perhaps because they have all closed the file, or exited), the read
  21 returns end-of-file.  Writing to a pipe or FIFO that doesn't have a
  22 reading process is treated as an error condition; it generates a
  23 @code{SIGPIPE} signal, and fails with error code @code{EPIPE} if the
  24 signal is handled or blocked.
  25
  26 Neither pipes nor FIFO special files allow file positioning.  Both
  27 reading and writing operations happen sequentially; reading from the
  28 beginning of the file and writing at the end.
  29
  30 @menu
  31 * Creating a Pipe::             Making a pipe with the @code{pipe} function.
  32 * Pipe to a Subprocess::        Using a pipe to communicate with a
  33                                  child process.
  34 * FIFO Special Files::          Making a FIFO special file.
  35 * Pipe Atomicity::              When pipe (or FIFO) I/O is atomic.
  36 @end menu
  37
  38 @node Creating a Pipe
  39 @section Creating a Pipe
  40 @cindex creating a pipe
  41 @cindex opening a pipe
  42 @cindex interprocess communication, with pipes
  43
  44 The primitive for creating a pipe is the @code{pipe} function.  This
  45 creates both the reading and writing ends of the pipe.  It is not very
  46 useful for a single process to use a pipe to talk to itself.  In typical
  47 use, a process creates a pipe just before it forks one or more child
  48 processes (@pxref{Creating a Process}).  The pipe is then used for
  49 communication either between the parent or child processes, or between
  50 two sibling processes.
  51
  52 The @code{pipe} function is declared in the header file
  53 @file{unistd.h}.
  54 @pindex unistd.h
  55
  56 @deftypefun int pipe (int @var{filedes}@t{[2]})
  57 @standards{POSIX.1, unistd.h}
  58 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}}
  59 @c On Linux, syscall pipe2.  On HURD, call socketpair.
  60 The @code{pipe} function creates a pipe and puts the file descriptors
  61 for the reading and writing ends of the pipe (respectively) into
  62 @code{@var{filedes}[0]} and @code{@var{filedes}[1]}.
  63
  64 An easy way to remember that the input end comes first is that file
  65 descriptor @code{0} is standard input, and file descriptor @code{1} is
  66 standard output.
  67
  68 If successful, @code{pipe} returns a value of @code{0}.  On failure,
  69 @code{-1} is returned.  The following @code{errno} error conditions are
  70 defined for this function:
  71
  72 @table @code
  73 @item EMFILE
  74 The process has too many files open.
  75
  76 @item ENFILE
  77 There are too many open files in the entire system.  @xref{Error Codes},
  78 for more information about @code{ENFILE}.  This error never occurs on
  79 @gnuhurdsystems{}.
  80 @end table
  81 @end deftypefun
  82
  83 Here is an example of a simple program that creates a pipe.  This program
  84 uses the @code{fork} function (@pxref{Creating a Process}) to create
  85 a child process.  The parent process writes data to the pipe, which is
  86 read by the child process.
  87
  88 @smallexample
  89 @include pipe.c.texi
  90 @end smallexample
  91
  92 @node Pipe to a Subprocess
  93 @section Pipe to a Subprocess
  94 @cindex creating a pipe to a subprocess
  95 @cindex pipe to a subprocess
  96 @cindex filtering i/o through subprocess
  97
  98 A common use of pipes is to send data to or receive data from a program
  99 being run as a subprocess.  One way of doing this is by using a combination of
 100 @code{pipe} (to create the pipe), @code{fork} (to create the subprocess),
 101 @code{dup2} (to force the subprocess to use the pipe as its standard input
 102 or output channel), and @code{exec} (to execute the new program).  Or,
 103 you can use @code{popen} and @code{pclose}.
 104
 105 The advantage of using @code{popen} and @code{pclose} is that the
 106 interface is much simpler and easier to use.  But it doesn't offer as
 107 much flexibility as using the low-level functions directly.
 108
 109 @deftypefun {FILE *} popen (const char *@var{command}, const char *@var{mode})
 110 @standards{POSIX.2, stdio.h}
 111 @standards{SVID, stdio.h}
 112 @standards{BSD, stdio.h}
 113 @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
 114 @c popen @ascuheap @asucorrupt @acucorrupt @aculock @acsfd @acsmem
 115 @c  malloc dup @ascuheap @acsmem
 116 @c  _IO_init ok
 117 @c   _IO_no_init ok
 118 @c    _IO_old_init ok
 119 @c     _IO_lock_init ok
 120 @c  _IO_new_file_init @asucorrupt @acucorrupt @aculock @acsfd
 121 @c   _IO_link_in @asucorrupt @acucorrupt @aculock @acsfd
 122 @c     the linked list is guarded by a recursive lock;
 123 @c     it may get corrupted with async signals and cancellation
 124 @c    _IO_lock_lock dup @aculock
 125 @c    _IO_flockfile dup @aculock
 126 @c    _IO_funlockfile dup @aculock
 127 @c    _IO_lock_unlock dup @aculock
 128 @c  _IO_new_proc_open @asucorrupt @acucorrupt @aculock @acsfd
 129 @c    the linked list is guarded by a recursive lock;
 130  @c   it may get corrupted with async signals and cancellation
 131 @c   _IO_file_is_open ok
 132 @c   pipe2 dup @acsfd
 133 @c   pipe dup @acsfd
 134 @c   _IO_fork=fork @aculock
 135 @c   _IO_close=close_not_cancel dup @acsfd
 136 @c   fcntl dup ok
 137 @c   _IO_lock_lock @aculock
 138 @c   _IO_lock_unlock @aculock
 139 @c   _IO_mask_flags ok [no @mtasurace:stream, nearly but sufficiently exclusive access]
 140 @c  _IO_un_link @asucorrupt @acucorrupt @aculock @acsfd
 141 @c    the linked list is guarded by a recursive lock;
 142 @c    it may get corrupted with async signals and cancellation
 143 @c   _IO_lock_lock dup @aculock
 144 @c   _IO_flockfile dup @aculock
 145 @c   _IO_funlockfile dup @aculock
 146 @c   _IO_lock_unlock dup @aculock
 147 @c  free dup @ascuheap @acsmem
 148 The @code{popen} function is closely related to the @code{system}
 149 function; see @ref{Running a Command}.  It executes the shell command
 150 @var{command} as a subprocess.  However, instead of waiting for the
 151 command to complete, it creates a pipe to the subprocess and returns a
 152 stream that corresponds to that pipe.
 153
 154 If you specify a @var{mode} argument of @code{"r"}, you can read from the
 155 stream to retrieve data from the standard output channel of the subprocess.
 156 The subprocess inherits its standard input channel from the parent process.
 157
 158 Similarly, if you specify a @var{mode} argument of @code{"w"}, you can
 159 write to the stream to send data to the standard input channel of the
 160 subprocess.  The subprocess inherits its standard output channel from
 161 the parent process.
 162
 163 In the event of an error @code{popen} returns a null pointer.  This
 164 might happen if the pipe or stream cannot be created, if the subprocess
 165 cannot be forked, or if the program cannot be executed.
 166 @end deftypefun
 167
 168 @deftypefun int pclose (FILE *@var{stream})
 169 @standards{POSIX.2, stdio.h}
 170 @standards{SVID, stdio.h}
 171 @standards{BSD, stdio.h}
 172 @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @ascuplugin{} @asucorrupt{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
 173 @c Although the stream cannot be used after the call, even in case of
 174 @c async cancellation, because the stream must not be used after pclose
 175 @c is called, other stdio linked lists and their locks may be left in
 176 @c corrupt states; that's where the corrupt and lock annotations come
 177 @c from.
 178 @c
 179 @c pclose @ascuheap @ascuplugin @asucorrupt @asulock @acucorrupt @aculock @acsfd @acsmem
 180 @c  _IO_new_fclose @ascuheap @ascuplugin @asucorrupt @asulock @acucorrupt @aculock @acsfd @acsmem
 181 @c   _IO_un_link dup @asucorrupt @acucorrupt @aculock @acsfd
 182 @c   _IO_acquire_lock dup @aculock
 183 @c    _IO_flockfile dup @aculock
 184 @c   _IO_file_close_it @ascuheap @ascuplugin @asucorrupt @aculock @acucorrupt @acsfd @acsmem
 185 @c    _IO_file_is_open dup ok
 186 @c    _IO_do_flush @asucorrupt @ascuplugin @acucorrupt
 187 @c     _IO_do_write @asucorrupt @acucorrupt
 188 @c      new_do_write @asucorrupt @acucorrupt
 189 @c       _IO_SYSSEEK ok
 190 @c        lseek64 dup ok
 191 @c       _IO_SYSWRITE ok
 192 @c        write_not_cancel dup ok
 193 @c        write dup ok
 194 @c       _IO_adjust_column ok
 195 @c       _IO_setg dup @asucorrupt @acucorrupt [no @mtasurace:stream, locked]
 196 @c     _IO_wdo_write @asucorrupt @ascuplugin @acucorrupt
 197 @c      _IO_new_do_write=_IO_do_write dup @asucorrupt @acucorrupt
 198 @c      *cc->__codecvt_do_out @ascuplugin
 199 @c      _IO_wsetg dup @asucorrupt @acucorrupt [no @mtasurace:stream, locked]
 200 @c    _IO_unsave_markers @ascuheap @asucorrupt @acucorrupt @acsmem
 201 @c     _IO_have_backup dup ok
 202 @c     _IO_free_backup_area dup @ascuheap @asucorrupt @acucorrupt @acsmem
 203 @c    _IO_SYSCLOSE @aculock @acucorrupt @acsfd
 204 @c     _IO_lock_lock dup @aculock
 205 @c     _IO_close=close_not_cancel dup @acsfd
 206 @c     _IO_lock_unlock dup @aculock
 207 @c     _IO_waitpid=waitpid_not_cancel dup ok
 208 @c    _IO_have_wbackup ok
 209 @c    _IO_free_wbackup_area @ascuheap @asucorrupt @acucorrupt @acsmem
 210 @c     _IO_in_backup dup ok
 211 @c     _IO_switch_to_main_wget_area @asucorrupt @acucorrupt
 212 @c     free dup @ascuheap @acsmem
 213 @c    _IO_wsetb @asucorrupt @acucorrupt [no @mtasurace:stream, locked]
 214 @c    _IO_wsetg @asucorrupt @acucorrupt [no @mtasurace:stream, locked]
 215 @c    _IO_wsetp @asucorrupt @acucorrupt [no @mtasurace:stream, locked]
 216 @c    _IO_setb @asucorrupt @acucorrupt [no @mtasurace:stream, locked]
 217 @c    _IO_setg @asucorrupt @acucorrupt [no @mtasurace:stream, locked]
 218 @c    _IO_setp @asucorrupt @acucorrupt [no @mtasurace:stream, locked]
 219 @c    _IO_un_link dup @asucorrupt @acucorrupt @aculock @acsfd
 220 @c   _IO_release_lock dup @aculock
 221 @c    _IO_funlockfile dup @aculock
 222 @c   _IO_FINISH @ascuheap @ascuplugin @asucorrupt @acucorrupt @aculock @acsfd @acsmem
 223 @c    _IO_new_file_finish @ascuheap @ascuplugin @asucorrupt @acucorrupt @aculock @acsfd @acsmem
 224 @c     _IO_file_is_open dup ok
 225 @c     _IO_do_flush dup @ascuplugin @asucorrupt @acucorrupt
 226 @c     _IO_SYSCLOSE dup @aculock @acucorrupt @acsfd
 227 @c     _IO_default_finish @ascuheap @asucorrupt @acucorrupt @aculock @acsfd @acsmem
 228 @c      FREE_BUF @acsmem
 229 @c       munmap dup @acsmem
 230 @c      free dup @ascuheap @acsmem
 231 @c      _IO_un_link dup @asucorrupt @acucorrupt @aculock @acsfd
 232 @c      _IO_lock_fini ok
 233 @c       libc_lock_fini_recursive ok
 234 @c   libc_lock_lock dup @asulock @aculock
 235 @c   gconv_release_step ok
 236 @c   libc_lock_unlock dup @asulock @aculock
 237 @c   _IO_have_backup ok
 238 @c   _IO_free_backup_area @ascuheap @asucorrupt @acucorrupt @acsmem
 239 @c    _IO_in_backup ok
 240 @c    _IO_switch_to_main_get_area @asucorrupt @acucorrupt
 241 @c    free dup @ascuheap @acsmem
 242 @c   free dup @ascuheap @acsmem
 243 The @code{pclose} function is used to close a stream created by @code{popen}.
 244 It waits for the child process to terminate and returns its status value,
 245 as for the @code{system} function.
 246 @end deftypefun
 247
 248 Here is an example showing how to use @code{popen} and @code{pclose} to
 249 filter output through another program, in this case the paging program
 250 @code{more}.
 251
 252 @smallexample
 253 @include popen.c.texi
 254 @end smallexample
 255
 256 @node FIFO Special Files
 257 @section FIFO Special Files
 258 @cindex creating a FIFO special file
 259 @cindex interprocess communication, with FIFO
 260
 261 A FIFO special file is similar to a pipe, except that it is created in a
 262 different way.  Instead of being an anonymous communications channel, a
 263 FIFO special file is entered into the file system by calling
 264 @code{mkfifo}.
 265
 266 Once you have created a FIFO special file in this way, any process can
 267 open it for reading or writing, in the same way as an ordinary file.
 268 However, it has to be open at both ends simultaneously before you can
 269 proceed to do any input or output operations on it.  Opening a FIFO for
 270 reading normally blocks until some other process opens the same FIFO for
 271 writing, and vice versa.
 272
 273 The @code{mkfifo} function is declared in the header file
 274 @file{sys/stat.h}.
 275 @pindex sys/stat.h
 276
 277 @deftypefun int mkfifo (const char *@var{filename}, mode_t @var{mode})
 278 @standards{POSIX.1, sys/stat.h}
 279 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 280 @c On generic Posix, calls xmknod.
 281 The @code{mkfifo} function makes a FIFO special file with name
 282 @var{filename}.  The @var{mode} argument is used to set the file's
 283 permissions; see @ref{Setting Permissions}.
 284
 285 The normal, successful return value from @code{mkfifo} is @code{0}.  In
 286 the case of an error, @code{-1} is returned.  In addition to the usual
 287 file name errors (@pxref{File Name Errors}), the following
 288 @code{errno} error conditions are defined for this function:
 289
 290 @table @code
 291 @item EEXIST
 292 The named file already exists.
 293
 294 @item ENOSPC
 295 The directory or file system cannot be extended.
 296
 297 @item EROFS
 298 The directory that would contain the file resides on a read-only file
 299 system.
 300 @end table
 301 @end deftypefun
 302
 303 @node Pipe Atomicity
 304 @section Atomicity of Pipe I/O
 305
 306 Reading or writing pipe data is @dfn{atomic} if the size of data written
 307 is not greater than @code{PIPE_BUF}.  This means that the data transfer
 308 seems to be an instantaneous unit, in that nothing else in the system
 309 can observe a state in which it is partially complete.  Atomic I/O may
 310 not begin right away (it may need to wait for buffer space or for data),
 311 but once it does begin it finishes immediately.
 312
 313 Reading or writing a larger amount of data may not be atomic; for
 314 example, output data from other processes sharing the descriptor may be
 315 interspersed.  Also, once @code{PIPE_BUF} characters have been written,
 316 further writes will block until some characters are read.
 317
 318 @xref{Limits for Files}, for information about the @code{PIPE_BUF}
 319 parameter.