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