lib/pipe.h

   1 /* Creation of subprocesses, communicating via pipes.
   2    Copyright (C) 2001-2003, 2006 Free Software Foundation, Inc.
   3    Written by Bruno Haible <haible@clisp.cons.org>, 2001.
   4
   5    This program is free software; you can redistribute it and/or modify
   6    it under the terms of the GNU General Public License as published by
   7    the Free Software Foundation; either version 2, or (at your option)
   8    any later version.
   9
  10    This program is distributed in the hope that it will be useful,
  11    but WITHOUT ANY WARRANTY; without even the implied warranty of
  12    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13    GNU General Public License for more details.
  14
  15    You should have received a copy of the GNU General Public License
  16    along with this program; if not, write to the Free Software Foundation,
  17    Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.  */
  18
  19 #ifndef _PIPE_H
  20 #define _PIPE_H
  21
  22 /* Get pid_t.  */
  23 #include <stdlib.h>
  24 #include <unistd.h>
  25 #include <sys/types.h>
  26
  27 #include <stdbool.h>
  28
  29
  30 #ifdef __cplusplus
  31 extern "C" {
  32 #endif
  33
  34
  35 /* All these functions create a subprocess and don't wait for its termination.
  36    They return the process id of the subprocess.  They also return in fd[]
  37    one or two file descriptors for communication with the subprocess.
  38    If the subprocess creation fails: if exit_on_error is true, the main
  39    process exits with an error message; otherwise, an error message is given
  40    if null_stderr is false, then -1 is returned and fd[] remain uninitialized.
  41
  42    After finishing communication, the caller should call wait_subprocess()
  43    to get rid of the subprocess in the process table.
  44
  45    If slave_process is true, the child process will be terminated when its
  46    creator receives a catchable fatal signal or exits normally.  If
  47    slave_process is false, the child process will continue running in this
  48    case, until it is lucky enough to attempt to communicate with its creator
  49    and thus get a SIGPIPE signal.
  50
  51    If exit_on_error is false, a child process id of -1 should be treated the
  52    same way as a subprocess which accepts no input, produces no output and
  53    terminates with exit code 127.  Why?  Some errors during posix_spawnp()
  54    cause the function posix_spawnp() to return an error code; some other
  55    errors cause the subprocess to exit with return code 127.  It is
  56    implementation dependent which error is reported which way.  The caller
  57    must treat both cases as equivalent.
  58
  59    It is recommended that no signal is blocked or ignored (i.e. have a
  60    signal handler with value SIG_IGN) while any of these functions is called.
  61    The reason is that child processes inherit the mask of blocked signals
  62    from their parent (both through posix_spawn() and fork()/exec());
  63    likewise, signals ignored in the parent are also ignored in the child
  64    (except possibly for SIGCHLD).  And POSIX:2001 says [in the description
  65    of exec()]:
  66        "it should be noted that many existing applications wrongly
  67         assume that they start with certain signals set to the default
  68         action and/or unblocked. In particular, applications written
  69         with a simpler signal model that does not include blocking of
  70         signals, such as the one in the ISO C standard, may not behave
  71         properly if invoked with some signals blocked. Therefore, it is
  72         best not to block or ignore signals across execs without explicit
  73         reason to do so, and especially not to block signals across execs
  74         of arbitrary (not closely co-operating) programs."  */
  75
  76 /* Open a pipe for output to a child process.
  77  * The child's stdout goes to a file.
  78  *
  79  *           write       system                read
  80  *    parent  ->   fd[0]   ->   STDIN_FILENO    ->   child
  81  *
  82  */
  83 extern pid_t create_pipe_out (const char *progname,
  84                               const char *prog_path, char **prog_argv,
  85                               const char *prog_stdout, bool null_stderr,
  86                               bool slave_process, bool exit_on_error,
  87                               int fd[1]);
  88
  89 /* Open a pipe for input from a child process.
  90  * The child's stdin comes from a file.
  91  *
  92  *           read        system                write
  93  *    parent  <-   fd[0]   <-   STDOUT_FILENO   <-   child
  94  *
  95  */
  96 extern pid_t create_pipe_in (const char *progname,
  97                              const char *prog_path, char **prog_argv,
  98                              const char *prog_stdin, bool null_stderr,
  99                              bool slave_process, bool exit_on_error,
 100                              int fd[1]);
 101
 102 /* Open a bidirectional pipe.
 103  *
 104  *           write       system                read
 105  *    parent  ->   fd[1]   ->   STDIN_FILENO    ->   child
 106  *    parent  <-   fd[0]   <-   STDOUT_FILENO   <-   child
 107  *           read        system                write
 108  *
 109  */
 110 extern pid_t create_pipe_bidi (const char *progname,
 111                                const char *prog_path, char **prog_argv,
 112                                bool null_stderr,
 113                                bool slave_process, bool exit_on_error,
 114                                int fd[2]);
 115
 116 /* The name of the "always silent" device.  */
 117 #if defined _MSC_VER || defined __MINGW32__
 118 /* Native Woe32 API.  */
 119 # define DEV_NULL "NUL"
 120 #else
 121 /* Unix API.  */
 122 # define DEV_NULL "/dev/null"
 123 #endif
 124
 125
 126 #ifdef __cplusplus
 127 }
 128 #endif
 129
 130
 131 #endif /* _PIPE_H */