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 @comment unistd.h
  57 @comment POSIX.1
  58 @deftypefun int pipe (int @var{filedes}@t{[2]})
  59 The @code{pipe} function creates a pipe and puts the file descriptors
  60 for the reading and writing ends of the pipe (respectively) into
  61 @code{@var{filedes}[0]} and @code{@var{filedes}[1]}.
  62
  63 An easy way to remember that the input end comes first is that file
  64 descriptor @code{0} is standard input, and file descriptor @code{1} is
  65 standard output.
  66
  67 If successful, @code{pipe} returns a value of @code{0}.  On failure,
  68 @code{-1} is returned.  The following @code{errno} error conditions are
  69 defined for this function:
  70
  71 @table @code
  72 @item EMFILE
  73 The process has too many files open.
  74
  75 @item ENFILE
  76 There are too many open files in the entire system.  @xref{Error Codes},
  77 for more information about @code{ENFILE}.  This error never occurs in
  78 the GNU system.
  79 @end table
  80 @end deftypefun
  81
  82 Here is an example of a simple program that creates a pipe.  This program
  83 uses the @code{fork} function (@pxref{Creating a Process}) to create
  84 a child process.  The parent process writes data to the pipe, which is
  85 read by the child process.
  86
  87 @smallexample
  88 @include pipe.c.texi
  89 @end smallexample
  90
  91 @node Pipe to a Subprocess
  92 @section Pipe to a Subprocess
  93 @cindex creating a pipe to a subprocess
  94 @cindex pipe to a subprocess
  95 @cindex filtering i/o through subprocess
  96
  97 A common use of pipes is to send data to or receive data from a program
  98 being run as subprocess.  One way of doing this is by using a combination of
  99 @code{pipe} (to create the pipe), @code{fork} (to create the subprocess),
 100 @code{dup2} (to force the subprocess to use the pipe as its standard input
 101 or output channel), and @code{exec} (to execute the new program).  Or,
 102 you can use @code{popen} and @code{pclose}.
 103
 104 The advantage of using @code{popen} and @code{pclose} is that the
 105 interface is much simpler and easier to use.  But it doesn't offer as
 106 much flexibility as using the low-level functions directly.
 107
 108 @comment stdio.h
 109 @comment POSIX.2, SVID, BSD
 110 @deftypefun {FILE *} popen (const char *@var{command}, const char *@var{mode})
 111 The @code{popen} function is closely related to the @code{system}
 112 function; see @ref{Running a Command}.  It executes the shell command
 113 @var{command} as a subprocess.  However, instead of waiting for the
 114 command to complete, it creates a pipe to the subprocess and returns a
 115 stream that corresponds to that pipe.
 116
 117 If you specify a @var{mode} argument of @code{"r"}, you can read from the
 118 stream to retrieve data from the standard output channel of the subprocess.
 119 The subprocess inherits its standard input channel from the parent process.
 120
 121 Similarly, if you specify a @var{mode} argument of @code{"w"}, you can
 122 write to the stream to send data to the standard input channel of the
 123 subprocess.  The subprocess inherits its standard output channel from
 124 the parent process.
 125
 126 In the event of an error, @code{popen} returns a null pointer.  This
 127 might happen if the pipe or stream cannot be created, if the subprocess
 128 cannot be forked, or if the program cannot be executed.
 129 @end deftypefun
 130
 131 @comment stdio.h
 132 @comment POSIX.2, SVID, BSD
 133 @deftypefun int pclose (FILE *@var{stream})
 134 The @code{pclose} function is used to close a stream created by @code{popen}.
 135 It waits for the child process to terminate and returns its status value,
 136 as for the @code{system} function.
 137 @end deftypefun
 138
 139 Here is an example showing how to use @code{popen} and @code{pclose} to
 140 filter output through another program, in this case the paging program
 141 @code{more}.
 142
 143 @smallexample
 144 @include popen.c.texi
 145 @end smallexample
 146
 147 @node FIFO Special Files
 148 @section FIFO Special Files
 149 @cindex creating a FIFO special file
 150 @cindex interprocess communication, with FIFO
 151
 152 A FIFO special file is similar to a pipe, except that it is created in a
 153 different way.  Instead of being an anonymous communications channel, a
 154 FIFO special file is entered into the file system by calling
 155 @code{mkfifo}.
 156
 157 Once you have created a FIFO special file in this way, any process can
 158 open it for reading or writing, in the same way as an ordinary file.
 159 However, it has to be open at both ends simultaneously before you can
 160 proceed to do any input or output operations on it.  Opening a FIFO for
 161 reading normally blocks until some other process opens the same FIFO for
 162 writing, and vice versa.
 163
 164 The @code{mkfifo} function is declared in the header file
 165 @file{sys/stat.h}.
 166 @pindex sys/stat.h
 167
 168 @comment sys/stat.h
 169 @comment POSIX.1
 170 @deftypefun int mkfifo (const char *@var{filename}, mode_t @var{mode})
 171 The @code{mkfifo} function makes a FIFO special file with name
 172 @var{filename}.  The @var{mode} argument is used to set the file's
 173 permissions; see @ref{Setting Permissions}.
 174
 175 The normal, successful return value from @code{mkfifo} is @code{0}.  In
 176 the case of an error, @code{-1} is returned.  In addition to the usual
 177 file name errors (@pxref{File Name Errors}), the following
 178 @code{errno} error conditions are defined for this function:
 179
 180 @table @code
 181 @item EEXIST
 182 The named file already exists.
 183
 184 @item ENOSPC
 185 The directory or file system cannot be extended.
 186
 187 @item EROFS
 188 The directory that would contain the file resides on a read-only file
 189 system.
 190 @end table
 191 @end deftypefun
 192
 193 @node Pipe Atomicity
 194 @section Atomicity of Pipe I/O
 195
 196 Reading or writing pipe data is @dfn{atomic} if the size of data written
 197 is not greater than @code{PIPE_BUF}.  This means that the data transfer
 198 seems to be an instantaneous unit, in that nothing else in the system
 199 can observe a state in which it is partially complete.  Atomic I/O may
 200 not begin right away (it may need to wait for buffer space or for data),
 201 but once it does begin, it finishes immediately.
 202
 203 Reading or writing a larger amount of data may not be atomic; for
 204 example, output data from other processes sharing the descriptor may be
 205 interspersed.  Also, once @code{PIPE_BUF} characters have been written,
 206 further writes will block until some characters are read.
 207
 208 @xref{Limits for Files}, for information about the @code{PIPE_BUF}
 209 parameter.