lib/spawn-pipe.h

   1 /* Creation of subprocesses, communicating via pipes.
   2    Copyright (C) 2001-2003, 2006, 2008-2021 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 3 of the License, or
   8    (at your option) 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, see <https://www.gnu.org/licenses/>.  */
  17
  18 #ifndef _SPAWN_PIPE_H
  19 #define _SPAWN_PIPE_H
  20
  21 /* Get pid_t.  */
  22 #include <stdlib.h>
  23 #include <unistd.h>
  24 #include <sys/types.h>
  25
  26 #include <stdbool.h>
  27
  28
  29 #ifdef __cplusplus
  30 extern "C" {
  31 #endif
  32
  33
  34 /* All these functions create a subprocess and don't wait for its termination.
  35    They return the process id of the subprocess.  They also return in fd[]
  36    one or two file descriptors for communication with the subprocess.
  37    If the subprocess creation fails: if exit_on_error is true, the main
  38    process exits with an error message; otherwise, an error message is given
  39    if null_stderr is false, then -1 is returned, with errno set, and fd[]
  40    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    progname is the name of the program to be executed by the subprocess, used
  46    for error messages.
  47    prog_path is the file name of the program to be executed by the subprocess.
  48    If it contains no slashes, a search is conducted in $PATH.  An operating
  49    system dependent suffix is added, if necessary.
  50    prog_argv is the array of strings that the subprocess shall receive in
  51    argv[].  It is a NULL-terminated array.  prog_argv[0] should normally be
  52    identical to prog_path.
  53
  54    If directory is not NULL, the subprocess is started in that directory.  If
  55    prog_path is a relative file name, it resolved before changing to that
  56    directory.  The current directory of the current process remains unchanged.
  57
  58    If slave_process is true, the child process will be terminated when its
  59    creator receives a catchable fatal signal or exits normally.  If
  60    slave_process is false, the child process will continue running in this
  61    case, until it is lucky enough to attempt to communicate with its creator
  62    and thus get a SIGPIPE signal.
  63
  64    If exit_on_error is false, a child process id of -1 should be treated the
  65    same way as a subprocess which accepts no input, produces no output and
  66    terminates with exit code 127.  Why?  Some errors during posix_spawnp()
  67    cause the function posix_spawnp() to return an error code; some other
  68    errors cause the subprocess to exit with return code 127.  It is
  69    implementation dependent which error is reported which way.  The caller
  70    must treat both cases as equivalent.
  71
  72    It is recommended that no signal is blocked or ignored (i.e. have a
  73    signal handler with value SIG_IGN) while any of these functions is called.
  74    The reason is that child processes inherit the mask of blocked signals
  75    from their parent (both through posix_spawn() and fork()/exec());
  76    likewise, signals ignored in the parent are also ignored in the child
  77    (except possibly for SIGCHLD).  And POSIX:2001 says [in the description
  78    of exec()]:
  79        "it should be noted that many existing applications wrongly
  80         assume that they start with certain signals set to the default
  81         action and/or unblocked. In particular, applications written
  82         with a simpler signal model that does not include blocking of
  83         signals, such as the one in the ISO C standard, may not behave
  84         properly if invoked with some signals blocked. Therefore, it is
  85         best not to block or ignore signals across execs without explicit
  86         reason to do so, and especially not to block signals across execs
  87         of arbitrary (not closely co-operating) programs."  */
  88
  89 /* Open a pipe for output to a child process.
  90  * The child's stdout goes to a file.
  91  *
  92  *           write       system                read
  93  *    parent  ->   fd[0]   ->   STDIN_FILENO    ->   child
  94  *
  95  * Note: When writing to a child process, it is useful to ignore the SIGPIPE
  96  * signal and the EPIPE error code.
  97  */
  98 extern pid_t create_pipe_out (const char *progname,
  99                               const char *prog_path,
 100                               const char * const *prog_argv,
 101                               const char *directory,
 102                               const char *prog_stdout, bool null_stderr,
 103                               bool slave_process, bool exit_on_error,
 104                               int fd[1]);
 105
 106 /* Open a pipe for input from a child process.
 107  * The child's stdin comes from a file.
 108  *
 109  *           read        system                write
 110  *    parent  <-   fd[0]   <-   STDOUT_FILENO   <-   child
 111  *
 112  */
 113 extern pid_t create_pipe_in (const char *progname,
 114                              const char *prog_path,
 115                              const char * const *prog_argv,
 116                              const char *directory,
 117                              const char *prog_stdin, bool null_stderr,
 118                              bool slave_process, bool exit_on_error,
 119                              int fd[1]);
 120
 121 /* Open a bidirectional pipe.
 122  *
 123  *           write       system                read
 124  *    parent  ->   fd[1]   ->   STDIN_FILENO    ->   child
 125  *    parent  <-   fd[0]   <-   STDOUT_FILENO   <-   child
 126  *           read        system                write
 127  *
 128  * Note: When writing to a child process, it is useful to ignore the SIGPIPE
 129  * signal and the EPIPE error code.
 130  *
 131  * Note: The parent process must be careful to avoid deadlock.
 132  * 1) If you write more than PIPE_MAX bytes or, more generally, if you write
 133  *    more bytes than the subprocess can handle at once, the subprocess
 134  *    may write its data and wait on you to read it, but you are currently
 135  *    busy writing.
 136  * 2) When you don't know ahead of time how many bytes the subprocess
 137  *    will produce, the usual technique of calling read (fd, buf, BUFSIZ)
 138  *    with a fixed BUFSIZ will, on Linux 2.2.17 and on BSD systems, cause
 139  *    the read() call to block until *all* of the buffer has been filled.
 140  *    But the subprocess cannot produce more data until you gave it more
 141  *    input.  But you are currently busy reading from it.
 142  */
 143 extern pid_t create_pipe_bidi (const char *progname,
 144                                const char *prog_path,
 145                                const char * const *prog_argv,
 146                                const char *directory,
 147                                bool null_stderr,
 148                                bool slave_process, bool exit_on_error,
 149                                int fd[2]);
 150
 151 /* The name of the "always silent" device.  */
 152 #if defined _WIN32 && ! defined __CYGWIN__
 153 /* Native Windows API.  */
 154 # define DEV_NULL "NUL"
 155 #else
 156 /* Unix API.  */
 157 # define DEV_NULL "/dev/null"
 158 #endif
 159
 160
 161 #ifdef __cplusplus
 162 }
 163 #endif
 164
 165
 166 #endif /* _SPAWN_PIPE_H */