manual/pipe.texi

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