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 a 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.