1 | /* gspawn.h - Process launching |
2 | * |
3 | * Copyright 2000 Red Hat, Inc. |
4 | * |
5 | * SPDX-License-Identifier: LGPL-2.1-or-later |
6 | * |
7 | * This library is free software; you can redistribute it and/or |
8 | * modify it under the terms of the GNU Lesser General Public |
9 | * License as published by the Free Software Foundation; either |
10 | * version 2.1 of the License, or (at your option) any later version. |
11 | * |
12 | * This library is distributed in the hope that it will be useful, |
13 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
14 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
15 | * Lesser General Public License for more details. |
16 | * |
17 | * You should have received a copy of the GNU Lesser General Public License |
18 | * along with this library; if not, see <http://www.gnu.org/licenses/>. |
19 | */ |
20 | |
21 | #ifndef __G_SPAWN_H__ |
22 | #define __G_SPAWN_H__ |
23 | |
24 | #if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION) |
25 | #error "Only <glib.h> can be included directly." |
26 | #endif |
27 | |
28 | #include <glib/gerror.h> |
29 | |
30 | G_BEGIN_DECLS |
31 | |
32 | |
33 | /* I'm not sure I remember our proposed naming convention here. */ |
34 | /** |
35 | * G_SPAWN_ERROR: |
36 | * |
37 | * Error domain for spawning processes. Errors in this domain will |
38 | * be from the #GSpawnError enumeration. See #GError for information on |
39 | * error domains. |
40 | */ |
41 | #define G_SPAWN_ERROR g_spawn_error_quark () |
42 | |
43 | /** |
44 | * GSpawnError: |
45 | * @G_SPAWN_ERROR_FORK: Fork failed due to lack of memory. |
46 | * @G_SPAWN_ERROR_READ: Read or select on pipes failed. |
47 | * @G_SPAWN_ERROR_CHDIR: Changing to working directory failed. |
48 | * @G_SPAWN_ERROR_ACCES: execv() returned `EACCES` |
49 | * @G_SPAWN_ERROR_PERM: execv() returned `EPERM` |
50 | * @G_SPAWN_ERROR_TOO_BIG: execv() returned `E2BIG` |
51 | * @G_SPAWN_ERROR_2BIG: deprecated alias for %G_SPAWN_ERROR_TOO_BIG (deprecated since GLib 2.32) |
52 | * @G_SPAWN_ERROR_NOEXEC: execv() returned `ENOEXEC` |
53 | * @G_SPAWN_ERROR_NAMETOOLONG: execv() returned `ENAMETOOLONG` |
54 | * @G_SPAWN_ERROR_NOENT: execv() returned `ENOENT` |
55 | * @G_SPAWN_ERROR_NOMEM: execv() returned `ENOMEM` |
56 | * @G_SPAWN_ERROR_NOTDIR: execv() returned `ENOTDIR` |
57 | * @G_SPAWN_ERROR_LOOP: execv() returned `ELOOP` |
58 | * @G_SPAWN_ERROR_TXTBUSY: execv() returned `ETXTBUSY` |
59 | * @G_SPAWN_ERROR_IO: execv() returned `EIO` |
60 | * @G_SPAWN_ERROR_NFILE: execv() returned `ENFILE` |
61 | * @G_SPAWN_ERROR_MFILE: execv() returned `EMFILE` |
62 | * @G_SPAWN_ERROR_INVAL: execv() returned `EINVAL` |
63 | * @G_SPAWN_ERROR_ISDIR: execv() returned `EISDIR` |
64 | * @G_SPAWN_ERROR_LIBBAD: execv() returned `ELIBBAD` |
65 | * @G_SPAWN_ERROR_FAILED: Some other fatal failure, |
66 | * `error->message` should explain. |
67 | * |
68 | * Error codes returned by spawning processes. |
69 | */ |
70 | typedef enum |
71 | { |
72 | G_SPAWN_ERROR_FORK, /* fork failed due to lack of memory */ |
73 | G_SPAWN_ERROR_READ, /* read or select on pipes failed */ |
74 | G_SPAWN_ERROR_CHDIR, /* changing to working dir failed */ |
75 | G_SPAWN_ERROR_ACCES, /* execv() returned EACCES */ |
76 | G_SPAWN_ERROR_PERM, /* execv() returned EPERM */ |
77 | G_SPAWN_ERROR_TOO_BIG,/* execv() returned E2BIG */ |
78 | G_SPAWN_ERROR_2BIG GLIB_DEPRECATED_ENUMERATOR_IN_2_32_FOR(G_SPAWN_ERROR_TOO_BIG) = G_SPAWN_ERROR_TOO_BIG, |
79 | G_SPAWN_ERROR_NOEXEC, /* execv() returned ENOEXEC */ |
80 | G_SPAWN_ERROR_NAMETOOLONG, /* "" "" ENAMETOOLONG */ |
81 | G_SPAWN_ERROR_NOENT, /* "" "" ENOENT */ |
82 | G_SPAWN_ERROR_NOMEM, /* "" "" ENOMEM */ |
83 | G_SPAWN_ERROR_NOTDIR, /* "" "" ENOTDIR */ |
84 | G_SPAWN_ERROR_LOOP, /* "" "" ELOOP */ |
85 | G_SPAWN_ERROR_TXTBUSY, /* "" "" ETXTBUSY */ |
86 | G_SPAWN_ERROR_IO, /* "" "" EIO */ |
87 | G_SPAWN_ERROR_NFILE, /* "" "" ENFILE */ |
88 | G_SPAWN_ERROR_MFILE, /* "" "" EMFLE */ |
89 | G_SPAWN_ERROR_INVAL, /* "" "" EINVAL */ |
90 | G_SPAWN_ERROR_ISDIR, /* "" "" EISDIR */ |
91 | G_SPAWN_ERROR_LIBBAD, /* "" "" ELIBBAD */ |
92 | G_SPAWN_ERROR_FAILED /* other fatal failure, error->message |
93 | * should explain |
94 | */ |
95 | } GSpawnError; |
96 | |
97 | /** |
98 | * G_SPAWN_EXIT_ERROR: |
99 | * |
100 | * Error domain used by g_spawn_check_wait_status(). The code |
101 | * will be the program exit code. |
102 | */ |
103 | #define G_SPAWN_EXIT_ERROR g_spawn_exit_error_quark () |
104 | |
105 | /** |
106 | * GSpawnChildSetupFunc: |
107 | * @data: user data passed to the function. |
108 | * |
109 | * Specifies the type of the setup function passed to g_spawn_async(), |
110 | * g_spawn_sync() and g_spawn_async_with_pipes(), which can, in very |
111 | * limited ways, be used to affect the child's execution. |
112 | * |
113 | * On POSIX platforms, the function is called in the child after GLib |
114 | * has performed all the setup it plans to perform, but before calling |
115 | * exec(). Actions taken in this function will only affect the child, |
116 | * not the parent. |
117 | * |
118 | * On Windows, the function is called in the parent. Its usefulness on |
119 | * Windows is thus questionable. In many cases executing the child setup |
120 | * function in the parent can have ill effects, and you should be very |
121 | * careful when porting software to Windows that uses child setup |
122 | * functions. |
123 | * |
124 | * However, even on POSIX, you are extremely limited in what you can |
125 | * safely do from a #GSpawnChildSetupFunc, because any mutexes that were |
126 | * held by other threads in the parent process at the time of the fork() |
127 | * will still be locked in the child process, and they will never be |
128 | * unlocked (since the threads that held them don't exist in the child). |
129 | * POSIX allows only async-signal-safe functions (see signal(7)) to be |
130 | * called in the child between fork() and exec(), which drastically limits |
131 | * the usefulness of child setup functions. |
132 | * |
133 | * In particular, it is not safe to call any function which may |
134 | * call malloc(), which includes POSIX functions such as setenv(). |
135 | * If you need to set up the child environment differently from |
136 | * the parent, you should use g_get_environ(), g_environ_setenv(), |
137 | * and g_environ_unsetenv(), and then pass the complete environment |
138 | * list to the `g_spawn...` function. |
139 | */ |
140 | typedef void (* GSpawnChildSetupFunc) (gpointer data); |
141 | |
142 | /** |
143 | * GSpawnFlags: |
144 | * @G_SPAWN_DEFAULT: no flags, default behaviour |
145 | * @G_SPAWN_LEAVE_DESCRIPTORS_OPEN: the parent's open file descriptors will |
146 | * be inherited by the child; otherwise all descriptors except stdin, |
147 | * stdout and stderr will be closed before calling exec() in the child. |
148 | * @G_SPAWN_DO_NOT_REAP_CHILD: the child will not be automatically reaped; |
149 | * you must use g_child_watch_add() yourself (or call waitpid() or handle |
150 | * `SIGCHLD` yourself), or the child will become a zombie. |
151 | * @G_SPAWN_SEARCH_PATH: `argv[0]` need not be an absolute path, it will be |
152 | * looked for in the user's `PATH`. |
153 | * @G_SPAWN_STDOUT_TO_DEV_NULL: the child's standard output will be discarded, |
154 | * instead of going to the same location as the parent's standard output. |
155 | * @G_SPAWN_STDERR_TO_DEV_NULL: the child's standard error will be discarded. |
156 | * @G_SPAWN_CHILD_INHERITS_STDIN: the child will inherit the parent's standard |
157 | * input (by default, the child's standard input is attached to `/dev/null`). |
158 | * @G_SPAWN_FILE_AND_ARGV_ZERO: the first element of `argv` is the file to |
159 | * execute, while the remaining elements are the actual argument vector |
160 | * to pass to the file. Normally g_spawn_async_with_pipes() uses `argv[0]` |
161 | * as the file to execute, and passes all of `argv` to the child. |
162 | * @G_SPAWN_SEARCH_PATH_FROM_ENVP: if `argv[0]` is not an absolute path, |
163 | * it will be looked for in the `PATH` from the passed child environment. |
164 | * Since: 2.34 |
165 | * @G_SPAWN_CLOEXEC_PIPES: create all pipes with the `O_CLOEXEC` flag set. |
166 | * Since: 2.40 |
167 | * @G_SPAWN_CHILD_INHERITS_STDOUT: the child will inherit the parent's standard output. |
168 | * Since: 2.74 |
169 | * @G_SPAWN_CHILD_INHERITS_STDERR: the child will inherit the parent's standard error. |
170 | * Since: 2.74 |
171 | * @G_SPAWN_STDIN_FROM_DEV_NULL: the child's standard input is attached to `/dev/null`. |
172 | * Since: 2.74 |
173 | * |
174 | * Flags passed to g_spawn_sync(), g_spawn_async() and g_spawn_async_with_pipes(). |
175 | */ |
176 | typedef enum |
177 | { |
178 | G_SPAWN_DEFAULT = 0, |
179 | G_SPAWN_LEAVE_DESCRIPTORS_OPEN = 1 << 0, |
180 | G_SPAWN_DO_NOT_REAP_CHILD = 1 << 1, |
181 | /* look for argv[0] in the path i.e. use execvp() */ |
182 | G_SPAWN_SEARCH_PATH = 1 << 2, |
183 | /* Dump output to /dev/null */ |
184 | G_SPAWN_STDOUT_TO_DEV_NULL = 1 << 3, |
185 | G_SPAWN_STDERR_TO_DEV_NULL = 1 << 4, |
186 | G_SPAWN_CHILD_INHERITS_STDIN = 1 << 5, |
187 | G_SPAWN_FILE_AND_ARGV_ZERO = 1 << 6, |
188 | G_SPAWN_SEARCH_PATH_FROM_ENVP = 1 << 7, |
189 | G_SPAWN_CLOEXEC_PIPES = 1 << 8, |
190 | |
191 | /** |
192 | * G_SPAWN_CHILD_INHERITS_STDOUT: |
193 | * |
194 | * The child will inherit the parent's standard output. |
195 | * |
196 | * Since: 2.74 |
197 | */ |
198 | G_SPAWN_CHILD_INHERITS_STDOUT = 1 << 9, |
199 | |
200 | /** |
201 | * G_SPAWN_CHILD_INHERITS_STDERR: |
202 | * |
203 | * The child will inherit the parent's standard error. |
204 | * |
205 | * Since: 2.74 |
206 | */ |
207 | G_SPAWN_CHILD_INHERITS_STDERR = 1 << 10, |
208 | |
209 | /** |
210 | * G_SPAWN_STDIN_FROM_DEV_NULL: |
211 | * |
212 | * The child's standard input is attached to `/dev/null`. |
213 | * |
214 | * Since: 2.74 |
215 | */ |
216 | G_SPAWN_STDIN_FROM_DEV_NULL = 1 << 11 |
217 | } GSpawnFlags; |
218 | |
219 | GLIB_AVAILABLE_IN_ALL |
220 | GQuark g_spawn_error_quark (void); |
221 | GLIB_AVAILABLE_IN_ALL |
222 | GQuark g_spawn_exit_error_quark (void); |
223 | |
224 | GLIB_AVAILABLE_IN_ALL |
225 | gboolean g_spawn_async (const gchar *working_directory, |
226 | gchar **argv, |
227 | gchar **envp, |
228 | GSpawnFlags flags, |
229 | GSpawnChildSetupFunc child_setup, |
230 | gpointer user_data, |
231 | GPid *child_pid, |
232 | GError **error); |
233 | |
234 | |
235 | /* Opens pipes for non-NULL standard_output, standard_input, standard_error, |
236 | * and returns the parent's end of the pipes. |
237 | */ |
238 | GLIB_AVAILABLE_IN_ALL |
239 | gboolean g_spawn_async_with_pipes (const gchar *working_directory, |
240 | gchar **argv, |
241 | gchar **envp, |
242 | GSpawnFlags flags, |
243 | GSpawnChildSetupFunc child_setup, |
244 | gpointer user_data, |
245 | GPid *child_pid, |
246 | gint *standard_input, |
247 | gint *standard_output, |
248 | gint *standard_error, |
249 | GError **error); |
250 | |
251 | GLIB_AVAILABLE_IN_2_68 |
252 | gboolean g_spawn_async_with_pipes_and_fds (const gchar *working_directory, |
253 | const gchar * const *argv, |
254 | const gchar * const *envp, |
255 | GSpawnFlags flags, |
256 | GSpawnChildSetupFunc child_setup, |
257 | gpointer user_data, |
258 | gint stdin_fd, |
259 | gint stdout_fd, |
260 | gint stderr_fd, |
261 | const gint *source_fds, |
262 | const gint *target_fds, |
263 | gsize n_fds, |
264 | GPid *child_pid_out, |
265 | gint *stdin_pipe_out, |
266 | gint *stdout_pipe_out, |
267 | gint *stderr_pipe_out, |
268 | GError **error); |
269 | |
270 | /* Lets you provide fds for stdin/stdout/stderr */ |
271 | GLIB_AVAILABLE_IN_2_58 |
272 | gboolean g_spawn_async_with_fds (const gchar *working_directory, |
273 | gchar **argv, |
274 | gchar **envp, |
275 | GSpawnFlags flags, |
276 | GSpawnChildSetupFunc child_setup, |
277 | gpointer user_data, |
278 | GPid *child_pid, |
279 | gint stdin_fd, |
280 | gint stdout_fd, |
281 | gint stderr_fd, |
282 | GError **error); |
283 | |
284 | /* If standard_output or standard_error are non-NULL, the full |
285 | * standard output or error of the command will be placed there. |
286 | */ |
287 | |
288 | GLIB_AVAILABLE_IN_ALL |
289 | gboolean g_spawn_sync (const gchar *working_directory, |
290 | gchar **argv, |
291 | gchar **envp, |
292 | GSpawnFlags flags, |
293 | GSpawnChildSetupFunc child_setup, |
294 | gpointer user_data, |
295 | gchar **standard_output, |
296 | gchar **standard_error, |
297 | gint *wait_status, |
298 | GError **error); |
299 | |
300 | GLIB_AVAILABLE_IN_ALL |
301 | gboolean g_spawn_command_line_sync (const gchar *command_line, |
302 | gchar **standard_output, |
303 | gchar **standard_error, |
304 | gint *wait_status, |
305 | GError **error); |
306 | GLIB_AVAILABLE_IN_ALL |
307 | gboolean g_spawn_command_line_async (const gchar *command_line, |
308 | GError **error); |
309 | |
310 | GLIB_AVAILABLE_IN_2_70 |
311 | gboolean g_spawn_check_wait_status (gint wait_status, |
312 | GError **error); |
313 | |
314 | GLIB_DEPRECATED_IN_2_70_FOR(g_spawn_check_wait_status) |
315 | gboolean g_spawn_check_exit_status (gint wait_status, |
316 | GError **error); |
317 | |
318 | GLIB_AVAILABLE_IN_ALL |
319 | void g_spawn_close_pid (GPid pid); |
320 | |
321 | G_END_DECLS |
322 | |
323 | #endif /* __G_SPAWN_H__ */ |
324 | |