1/* Creation of subprocesses, communicating via pipes.
2   Copyright (C) 2001-2003, 2006, 2008-2012 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 <http://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
30extern "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   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 * Note: When writing to a child process, it is useful to ignore the SIGPIPE
83 * signal and the EPIPE error code.
84 */
85extern pid_t create_pipe_out (const char *progname,
86                              const char *prog_path, char **prog_argv,
87                              const char *prog_stdout, bool null_stderr,
88                              bool slave_process, bool exit_on_error,
89                              int fd[1]);
90
91/* Open a pipe for input from a child process.
92 * The child's stdin comes from a file.
93 *
94 *           read        system                write
95 *    parent  <-   fd[0]   <-   STDOUT_FILENO   <-   child
96 *
97 */
98extern pid_t create_pipe_in (const char *progname,
99                             const char *prog_path, char **prog_argv,
100                             const char *prog_stdin, bool null_stderr,
101                             bool slave_process, bool exit_on_error,
102                             int fd[1]);
103
104/* Open a bidirectional pipe.
105 *
106 *           write       system                read
107 *    parent  ->   fd[1]   ->   STDIN_FILENO    ->   child
108 *    parent  <-   fd[0]   <-   STDOUT_FILENO   <-   child
109 *           read        system                write
110 *
111 * Note: When writing to a child process, it is useful to ignore the SIGPIPE
112 * signal and the EPIPE error code.
113 *
114 * Note: The parent process must be careful to avoid deadlock.
115 * 1) If you write more than PIPE_MAX bytes or, more generally, if you write
116 *    more bytes than the subprocess can handle at once, the subprocess
117 *    may write its data and wait on you to read it, but you are currently
118 *    busy writing.
119 * 2) When you don't know ahead of time how many bytes the subprocess
120 *    will produce, the usual technique of calling read (fd, buf, BUFSIZ)
121 *    with a fixed BUFSIZ will, on Linux 2.2.17 and on BSD systems, cause
122 *    the read() call to block until *all* of the buffer has been filled.
123 *    But the subprocess cannot produce more data until you gave it more
124 *    input.  But you are currently busy reading from it.
125 */
126extern pid_t create_pipe_bidi (const char *progname,
127                               const char *prog_path, char **prog_argv,
128                               bool null_stderr,
129                               bool slave_process, bool exit_on_error,
130                               int fd[2]);
131
132/* The name of the "always silent" device.  */
133#if (defined _WIN32 || defined __WIN32__) && ! defined __CYGWIN__
134/* Native Windows API.  */
135# define DEV_NULL "NUL"
136#else
137/* Unix API.  */
138# define DEV_NULL "/dev/null"
139#endif
140
141
142#ifdef __cplusplus
143}
144#endif
145
146
147#endif /* _SPAWN_PIPE_H */
148