Debian Codegraph @

lib/spawn-pipe.h

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