Branch data Line data Source code
1 : : /* gspawn.c - Process launching
2 : : *
3 : : * Copyright 2000 Red Hat, Inc.
4 : : * g_execvpe implementation based on GNU libc execvp:
5 : : * Copyright 1991, 92, 95, 96, 97, 98, 99 Free Software Foundation, Inc.
6 : : *
7 : : * SPDX-License-Identifier: LGPL-2.1-or-later
8 : : *
9 : : * This library is free software; you can redistribute it and/or
10 : : * modify it under the terms of the GNU Lesser General Public
11 : : * License as published by the Free Software Foundation; either
12 : : * version 2.1 of the License, or (at your option) any later version.
13 : : *
14 : : * This library is distributed in the hope that it will be useful,
15 : : * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 : : * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17 : : * Lesser General Public License for more details.
18 : : *
19 : : * You should have received a copy of the GNU Lesser General Public License
20 : : * along with this library; if not, see <http://www.gnu.org/licenses/>.
21 : : */
22 : :
23 : : #include "config.h"
24 : :
25 : : #include "gspawn.h"
26 : : #include "gspawn-private.h"
27 : :
28 : : #include "gmessages.h"
29 : : #include "gshell.h"
30 : :
31 : : #define INHERITS_OR_NULL_STDIN (G_SPAWN_STDIN_FROM_DEV_NULL | G_SPAWN_CHILD_INHERITS_STDIN)
32 : : #define INHERITS_OR_NULL_STDOUT (G_SPAWN_STDOUT_TO_DEV_NULL | G_SPAWN_CHILD_INHERITS_STDOUT)
33 : : #define INHERITS_OR_NULL_STDERR (G_SPAWN_STDERR_TO_DEV_NULL | G_SPAWN_CHILD_INHERITS_STDERR)
34 : :
35 : : /**
36 : : * g_spawn_async:
37 : : * @working_directory: (type filename) (nullable): child's current working
38 : : * directory, or %NULL to inherit parent's
39 : : * @argv: (array zero-terminated=1) (element-type filename):
40 : : * child's argument vector
41 : : * @envp: (array zero-terminated=1) (element-type filename) (nullable):
42 : : * child's environment, or %NULL to inherit parent's
43 : : * @flags: flags from #GSpawnFlags
44 : : * @child_setup: (scope async) (closure user_data) (nullable): function to run
45 : : * in the child just before `exec()`
46 : : * @user_data: user data for @child_setup
47 : : * @child_pid: (out) (optional): return location for child process reference, or %NULL
48 : : * @error: return location for error
49 : : *
50 : : * Executes a child program asynchronously.
51 : : *
52 : : * See g_spawn_async_with_pipes() for a full description; this function
53 : : * simply calls the g_spawn_async_with_pipes() without any pipes.
54 : : *
55 : : * You should call g_spawn_close_pid() on the returned child process
56 : : * reference when you don't need it any more.
57 : : *
58 : : * If you are writing a GTK application, and the program you are spawning is a
59 : : * graphical application too, then to ensure that the spawned program opens its
60 : : * windows on the right screen, you may want to use #GdkAppLaunchContext,
61 : : * #GAppLaunchContext, or set the %DISPLAY environment variable.
62 : : *
63 : : * Note that the returned @child_pid on Windows is a handle to the child
64 : : * process and not its identifier. Process handles and process identifiers
65 : : * are different concepts on Windows.
66 : : *
67 : : * Returns: %TRUE on success, %FALSE if error is set
68 : : **/
69 : : gboolean
70 : 38 : g_spawn_async (const gchar *working_directory,
71 : : gchar **argv,
72 : : gchar **envp,
73 : : GSpawnFlags flags,
74 : : GSpawnChildSetupFunc child_setup,
75 : : gpointer user_data,
76 : : GPid *child_pid,
77 : : GError **error)
78 : : {
79 : 38 : return g_spawn_async_with_pipes (working_directory,
80 : : argv, envp,
81 : : flags,
82 : : child_setup,
83 : : user_data,
84 : : child_pid,
85 : : NULL, NULL, NULL,
86 : : error);
87 : : }
88 : :
89 : : /**
90 : : * g_spawn_sync:
91 : : * @working_directory: (type filename) (nullable): child's current working
92 : : * directory, or %NULL to inherit parent's
93 : : * @argv: (array zero-terminated=1) (element-type filename):
94 : : * child's argument vector, which must be non-empty and %NULL-terminated
95 : : * @envp: (array zero-terminated=1) (element-type filename) (nullable):
96 : : * child's environment, or %NULL to inherit parent's
97 : : * @flags: flags from #GSpawnFlags
98 : : * @child_setup: (scope call) (closure user_data) (nullable): function to run
99 : : * in the child just before `exec()`
100 : : * @user_data: user data for @child_setup
101 : : * @standard_output: (out) (array zero-terminated=1) (element-type guint8) (optional): return location for child output, or %NULL
102 : : * @standard_error: (out) (array zero-terminated=1) (element-type guint8) (optional): return location for child error messages, or %NULL
103 : : * @wait_status: (out) (optional): return location for child wait status, as returned by waitpid(), or %NULL
104 : : * @error: return location for error, or %NULL
105 : : *
106 : : * Executes a child synchronously (waits for the child to exit before returning).
107 : : *
108 : : * All output from the child is stored in @standard_output and @standard_error,
109 : : * if those parameters are non-%NULL. Note that you must set the
110 : : * %G_SPAWN_STDOUT_TO_DEV_NULL and %G_SPAWN_STDERR_TO_DEV_NULL flags when
111 : : * passing %NULL for @standard_output and @standard_error.
112 : : *
113 : : * If @wait_status is non-%NULL, the platform-specific status of
114 : : * the child is stored there; see the documentation of
115 : : * g_spawn_check_wait_status() for how to use and interpret this.
116 : : * On Unix platforms, note that it is usually not equal
117 : : * to the integer passed to `exit()` or returned from `main()`.
118 : : *
119 : : * Note that it is invalid to pass %G_SPAWN_DO_NOT_REAP_CHILD in
120 : : * @flags, and on POSIX platforms, the same restrictions as for
121 : : * g_child_watch_source_new() apply.
122 : : *
123 : : * If an error occurs, no data is returned in @standard_output,
124 : : * @standard_error, or @wait_status.
125 : : *
126 : : * This function calls g_spawn_async_with_pipes() internally; see that
127 : : * function for full details on the other parameters and details on
128 : : * how these functions work on Windows.
129 : : *
130 : : * Returns: %TRUE on success, %FALSE if an error was set
131 : : */
132 : : gboolean
133 : 320 : g_spawn_sync (const gchar *working_directory,
134 : : gchar **argv,
135 : : gchar **envp,
136 : : GSpawnFlags flags,
137 : : GSpawnChildSetupFunc child_setup,
138 : : gpointer user_data,
139 : : gchar **standard_output,
140 : : gchar **standard_error,
141 : : gint *wait_status,
142 : : GError **error)
143 : : {
144 : 320 : g_return_val_if_fail (argv != NULL, FALSE);
145 : 320 : g_return_val_if_fail (argv[0] != NULL, FALSE);
146 : 320 : g_return_val_if_fail (!(flags & G_SPAWN_DO_NOT_REAP_CHILD), FALSE);
147 : 320 : g_return_val_if_fail (standard_output == NULL ||
148 : : !(flags & G_SPAWN_STDOUT_TO_DEV_NULL), FALSE);
149 : 320 : g_return_val_if_fail (standard_error == NULL ||
150 : : !(flags & G_SPAWN_STDERR_TO_DEV_NULL), FALSE);
151 : :
152 : 320 : return g_spawn_sync_impl (working_directory, argv, envp, flags, child_setup,
153 : : user_data, standard_output, standard_error,
154 : : wait_status, error);
155 : : }
156 : :
157 : : /**
158 : : * g_spawn_async_with_pipes:
159 : : * @working_directory: (type filename) (nullable): child's current working
160 : : * directory, or %NULL to inherit parent's, in the GLib file name encoding
161 : : * @argv: (array zero-terminated=1) (element-type filename): child's argument
162 : : * vector, in the GLib file name encoding; it must be non-empty and %NULL-terminated
163 : : * @envp: (array zero-terminated=1) (element-type filename) (nullable):
164 : : * child's environment, or %NULL to inherit parent's, in the GLib file
165 : : * name encoding
166 : : * @flags: flags from #GSpawnFlags
167 : : * @child_setup: (scope async) (closure user_data) (nullable): function to run
168 : : * in the child just before `exec()`
169 : : * @user_data: user data for @child_setup
170 : : * @child_pid: (out) (optional): return location for child process ID, or %NULL
171 : : * @standard_input: (out) (optional): return location for file descriptor to write to child's stdin, or %NULL
172 : : * @standard_output: (out) (optional): return location for file descriptor to read child's stdout, or %NULL
173 : : * @standard_error: (out) (optional): return location for file descriptor to read child's stderr, or %NULL
174 : : * @error: return location for error
175 : : *
176 : : * Identical to g_spawn_async_with_pipes_and_fds() but with `n_fds` set to zero,
177 : : * so no FD assignments are used.
178 : : *
179 : : * Returns: %TRUE on success, %FALSE if an error was set
180 : : */
181 : : gboolean
182 : 466 : g_spawn_async_with_pipes (const gchar *working_directory,
183 : : gchar **argv,
184 : : gchar **envp,
185 : : GSpawnFlags flags,
186 : : GSpawnChildSetupFunc child_setup,
187 : : gpointer user_data,
188 : : GPid *child_pid,
189 : : gint *standard_input,
190 : : gint *standard_output,
191 : : gint *standard_error,
192 : : GError **error)
193 : : {
194 : 466 : return g_spawn_async_with_pipes_and_fds (working_directory,
195 : : (const gchar * const *) argv,
196 : : (const gchar * const *) envp,
197 : : flags,
198 : : child_setup, user_data,
199 : : -1, -1, -1,
200 : : NULL, NULL, 0,
201 : : child_pid,
202 : : standard_input,
203 : : standard_output,
204 : : standard_error,
205 : : error);
206 : : }
207 : :
208 : : /**
209 : : * g_spawn_async_with_pipes_and_fds:
210 : : * @working_directory: (type filename) (nullable): child's current working
211 : : * directory, or %NULL to inherit parent's, in the GLib file name encoding
212 : : * @argv: (array zero-terminated=1) (element-type filename): child's argument
213 : : * vector, in the GLib file name encoding; it must be non-empty and %NULL-terminated
214 : : * @envp: (array zero-terminated=1) (element-type filename) (nullable):
215 : : * child's environment, or %NULL to inherit parent's, in the GLib file
216 : : * name encoding
217 : : * @flags: flags from #GSpawnFlags
218 : : * @child_setup: (scope async) (closure user_data) (nullable): function to run
219 : : * in the child just before `exec()`
220 : : * @user_data: user data for @child_setup
221 : : * @stdin_fd: file descriptor to use for child's stdin, or `-1`
222 : : * @stdout_fd: file descriptor to use for child's stdout, or `-1`
223 : : * @stderr_fd: file descriptor to use for child's stderr, or `-1`
224 : : * @source_fds: (array length=n_fds) (nullable): array of FDs from the parent
225 : : * process to make available in the child process
226 : : * @target_fds: (array length=n_fds) (nullable): array of FDs to remap
227 : : * @source_fds to in the child process
228 : : * @n_fds: number of FDs in @source_fds and @target_fds
229 : : * @child_pid_out: (out) (optional): return location for child process ID, or %NULL
230 : : * @stdin_pipe_out: (out) (optional): return location for file descriptor to write to child's stdin, or %NULL
231 : : * @stdout_pipe_out: (out) (optional): return location for file descriptor to read child's stdout, or %NULL
232 : : * @stderr_pipe_out: (out) (optional): return location for file descriptor to read child's stderr, or %NULL
233 : : * @error: return location for error
234 : : *
235 : : * Executes a child program asynchronously (your program will not
236 : : * block waiting for the child to exit).
237 : : *
238 : : * The child program is specified by the only argument that must be
239 : : * provided, @argv. @argv should be a %NULL-terminated array of strings,
240 : : * to be passed as the argument vector for the child. The first string
241 : : * in @argv is of course the name of the program to execute. By default,
242 : : * the name of the program must be a full path. If @flags contains the
243 : : * %G_SPAWN_SEARCH_PATH flag, the `PATH` environment variable is used to
244 : : * search for the executable. If @flags contains the
245 : : * %G_SPAWN_SEARCH_PATH_FROM_ENVP flag, the `PATH` variable from @envp
246 : : * is used to search for the executable. If both the
247 : : * %G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP flags are
248 : : * set, the `PATH` variable from @envp takes precedence over the
249 : : * environment variable.
250 : : *
251 : : * If the program name is not a full path and %G_SPAWN_SEARCH_PATH flag
252 : : * is not used, then the program will be run from the current directory
253 : : * (or @working_directory, if specified); this might be unexpected or even
254 : : * dangerous in some cases when the current directory is world-writable.
255 : : *
256 : : * On Windows, note that all the string or string vector arguments to
257 : : * this function and the other `g_spawn*()` functions are in UTF-8, the
258 : : * GLib file name encoding. Unicode characters that are not part of
259 : : * the system codepage passed in these arguments will be correctly
260 : : * available in the spawned program only if it uses wide character API
261 : : * to retrieve its command line. For C programs built with Microsoft's
262 : : * tools it is enough to make the program have a `wmain()` instead of
263 : : * `main()`. `wmain()` has a wide character argument vector as parameter.
264 : : *
265 : : * At least currently, mingw doesn't support `wmain()`, so if you use
266 : : * mingw to develop the spawned program, it should call
267 : : * g_win32_get_command_line() to get arguments in UTF-8.
268 : : *
269 : : * On Windows the low-level child process creation API `CreateProcess()`
270 : : * doesn't use argument vectors, but a command line. The C runtime
271 : : * library's `spawn*()` family of functions (which g_spawn_async_with_pipes()
272 : : * eventually calls) paste the argument vector elements together into
273 : : * a command line, and the C runtime startup code does a corresponding
274 : : * reconstruction of an argument vector from the command line, to be
275 : : * passed to `main()`. Complications arise when you have argument vector
276 : : * elements that contain spaces or double quotes. The `spawn*()` functions
277 : : * don't do any quoting or escaping, but on the other hand the startup
278 : : * code does do unquoting and unescaping in order to enable receiving
279 : : * arguments with embedded spaces or double quotes. To work around this
280 : : * asymmetry, g_spawn_async_with_pipes() will do quoting and escaping on
281 : : * argument vector elements that need it before calling the C runtime
282 : : * `spawn()` function.
283 : : *
284 : : * The returned @child_pid on Windows is a handle to the child
285 : : * process, not its identifier. Process handles and process
286 : : * identifiers are different concepts on Windows.
287 : : *
288 : : * @envp is a %NULL-terminated array of strings, where each string
289 : : * has the form `KEY=VALUE`. This will become the child's environment.
290 : : * If @envp is %NULL, the child inherits its parent's environment.
291 : : *
292 : : * @flags should be the bitwise OR of any flags you want to affect the
293 : : * function's behaviour. The %G_SPAWN_DO_NOT_REAP_CHILD means that the
294 : : * child will not automatically be reaped; you must use a child watch
295 : : * (g_child_watch_add()) to be notified about the death of the child process,
296 : : * otherwise it will stay around as a zombie process until this process exits.
297 : : * Eventually you must call g_spawn_close_pid() on the @child_pid, in order to
298 : : * free resources which may be associated with the child process. (On Unix,
299 : : * using a child watch is equivalent to calling waitpid() or handling
300 : : * the `SIGCHLD` signal manually. On Windows, calling g_spawn_close_pid()
301 : : * is equivalent to calling `CloseHandle()` on the process handle returned
302 : : * in @child_pid). See g_child_watch_add().
303 : : *
304 : : * Open UNIX file descriptors marked as `FD_CLOEXEC` will be automatically
305 : : * closed in the child process. %G_SPAWN_LEAVE_DESCRIPTORS_OPEN means that
306 : : * other open file descriptors will be inherited by the child; otherwise all
307 : : * descriptors except stdin/stdout/stderr will be closed before calling `exec()`
308 : : * in the child. %G_SPAWN_SEARCH_PATH means that @argv[0] need not be an
309 : : * absolute path, it will be looked for in the `PATH` environment
310 : : * variable. %G_SPAWN_SEARCH_PATH_FROM_ENVP means need not be an
311 : : * absolute path, it will be looked for in the `PATH` variable from
312 : : * @envp. If both %G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP
313 : : * are used, the value from @envp takes precedence over the environment.
314 : : *
315 : : * %G_SPAWN_CHILD_INHERITS_STDIN means that the child will inherit the parent's
316 : : * standard input (by default, the child's standard input is attached to
317 : : * `/dev/null`). %G_SPAWN_STDIN_FROM_DEV_NULL explicitly imposes the default
318 : : * behavior. Both flags cannot be enabled at the same time and, in both cases,
319 : : * the @stdin_pipe_out argument is ignored.
320 : : *
321 : : * %G_SPAWN_STDOUT_TO_DEV_NULL means that the child's standard output
322 : : * will be discarded (by default, it goes to the same location as the parent's
323 : : * standard output). %G_SPAWN_CHILD_INHERITS_STDOUT explicitly imposes the
324 : : * default behavior. Both flags cannot be enabled at the same time and, in
325 : : * both cases, the @stdout_pipe_out argument is ignored.
326 : : *
327 : : * %G_SPAWN_STDERR_TO_DEV_NULL means that the child's standard error
328 : : * will be discarded (by default, it goes to the same location as the parent's
329 : : * standard error). %G_SPAWN_CHILD_INHERITS_STDERR explicitly imposes the
330 : : * default behavior. Both flags cannot be enabled at the same time and, in
331 : : * both cases, the @stderr_pipe_out argument is ignored.
332 : : *
333 : : * It is valid to pass the same FD in multiple parameters (e.g. you can pass
334 : : * a single FD for both @stdout_fd and @stderr_fd, and include it in
335 : : * @source_fds too).
336 : : *
337 : : * @source_fds and @target_fds allow zero or more FDs from this process to be
338 : : * remapped to different FDs in the spawned process. If @n_fds is greater than
339 : : * zero, @source_fds and @target_fds must both be non-%NULL and the same length.
340 : : * Each FD in @source_fds is remapped to the FD number at the same index in
341 : : * @target_fds. The source and target FD may be equal to simply propagate an FD
342 : : * to the spawned process. FD remappings are processed after standard FDs, so
343 : : * any target FDs which equal @stdin_fd, @stdout_fd or @stderr_fd will overwrite
344 : : * them in the spawned process.
345 : : *
346 : : * @source_fds is supported on Windows since 2.72.
347 : : *
348 : : * %G_SPAWN_FILE_AND_ARGV_ZERO means that the first element of @argv is
349 : : * the file to execute, while the remaining elements are the actual
350 : : * argument vector to pass to the file. Normally g_spawn_async_with_pipes()
351 : : * uses @argv[0] as the file to execute, and passes all of @argv to the child.
352 : : *
353 : : * @child_setup and @user_data are a function and user data. On POSIX
354 : : * platforms, the function is called in the child after GLib has
355 : : * performed all the setup it plans to perform (including creating
356 : : * pipes, closing file descriptors, etc.) but before calling `exec()`.
357 : : * That is, @child_setup is called just before calling `exec()` in the
358 : : * child. Obviously actions taken in this function will only affect
359 : : * the child, not the parent.
360 : : *
361 : : * On Windows, there is no separate `fork()` and `exec()` functionality.
362 : : * Child processes are created and run with a single API call,
363 : : * `CreateProcess()`. There is no sensible thing @child_setup
364 : : * could be used for on Windows so it is ignored and not called.
365 : : *
366 : : * If non-%NULL, @child_pid will on Unix be filled with the child's
367 : : * process ID. You can use the process ID to send signals to the child,
368 : : * or to use g_child_watch_add() (or `waitpid()`) if you specified the
369 : : * %G_SPAWN_DO_NOT_REAP_CHILD flag. On Windows, @child_pid will be
370 : : * filled with a handle to the child process only if you specified the
371 : : * %G_SPAWN_DO_NOT_REAP_CHILD flag. You can then access the child
372 : : * process using the Win32 API, for example wait for its termination
373 : : * with the `WaitFor*()` functions, or examine its exit code with
374 : : * `GetExitCodeProcess()`. You should close the handle with `CloseHandle()`
375 : : * or g_spawn_close_pid() when you no longer need it.
376 : : *
377 : : * If non-%NULL, the @stdin_pipe_out, @stdout_pipe_out, @stderr_pipe_out
378 : : * locations will be filled with file descriptors for writing to the child's
379 : : * standard input or reading from its standard output or standard error.
380 : : * The caller of g_spawn_async_with_pipes() must close these file descriptors
381 : : * when they are no longer in use. If these parameters are %NULL, the
382 : : * corresponding pipe won't be created.
383 : : *
384 : : * If @stdin_pipe_out is %NULL, the child's standard input is attached to
385 : : * `/dev/null` unless %G_SPAWN_CHILD_INHERITS_STDIN is set.
386 : : *
387 : : * If @stderr_pipe_out is NULL, the child's standard error goes to the same
388 : : * location as the parent's standard error unless %G_SPAWN_STDERR_TO_DEV_NULL
389 : : * is set.
390 : : *
391 : : * If @stdout_pipe_out is NULL, the child's standard output goes to the same
392 : : * location as the parent's standard output unless %G_SPAWN_STDOUT_TO_DEV_NULL
393 : : * is set.
394 : : *
395 : : * @error can be %NULL to ignore errors, or non-%NULL to report errors.
396 : : * If an error is set, the function returns %FALSE. Errors are reported
397 : : * even if they occur in the child (for example if the executable in
398 : : * `@argv[0]` is not found). Typically the `message` field of returned
399 : : * errors should be displayed to users. Possible errors are those from
400 : : * the %G_SPAWN_ERROR domain.
401 : : *
402 : : * If an error occurs, @child_pid, @stdin_pipe_out, @stdout_pipe_out,
403 : : * and @stderr_pipe_out will not be filled with valid values.
404 : : *
405 : : * If @child_pid is not %NULL and an error does not occur then the returned
406 : : * process reference must be closed using g_spawn_close_pid().
407 : : *
408 : : * On modern UNIX platforms, GLib can use an efficient process launching
409 : : * codepath driven internally by `posix_spawn()`. This has the advantage of
410 : : * avoiding the fork-time performance costs of cloning the parent process
411 : : * address space, and avoiding associated memory overcommit checks that are
412 : : * not relevant in the context of immediately executing a distinct process.
413 : : * This optimized codepath will be used provided that the following conditions
414 : : * are met:
415 : : *
416 : : * 1. %G_SPAWN_DO_NOT_REAP_CHILD is set
417 : : * 2. %G_SPAWN_LEAVE_DESCRIPTORS_OPEN is set
418 : : * 3. %G_SPAWN_SEARCH_PATH_FROM_ENVP is not set
419 : : * 4. @working_directory is %NULL
420 : : * 5. @child_setup is %NULL
421 : : * 6. The program is of a recognised binary format, or has a shebang.
422 : : * Otherwise, GLib will have to execute the program through the
423 : : * shell, which is not done using the optimized codepath.
424 : : *
425 : : * If you are writing a GTK application, and the program you are spawning is a
426 : : * graphical application too, then to ensure that the spawned program opens its
427 : : * windows on the right screen, you may want to use #GdkAppLaunchContext,
428 : : * #GAppLaunchContext, or set the `DISPLAY` environment variable.
429 : : *
430 : : * Returns: %TRUE on success, %FALSE if an error was set
431 : : *
432 : : * Since: 2.68
433 : : */
434 : : gboolean
435 : 739 : g_spawn_async_with_pipes_and_fds (const gchar *working_directory,
436 : : const gchar * const *argv,
437 : : const gchar * const *envp,
438 : : GSpawnFlags flags,
439 : : GSpawnChildSetupFunc child_setup,
440 : : gpointer user_data,
441 : : gint stdin_fd,
442 : : gint stdout_fd,
443 : : gint stderr_fd,
444 : : const gint *source_fds,
445 : : const gint *target_fds,
446 : : gsize n_fds,
447 : : GPid *child_pid_out,
448 : : gint *stdin_pipe_out,
449 : : gint *stdout_pipe_out,
450 : : gint *stderr_pipe_out,
451 : : GError **error)
452 : : {
453 : 739 : g_return_val_if_fail (argv != NULL, FALSE);
454 : 739 : g_return_val_if_fail (argv[0] != NULL, FALSE);
455 : : /* can’t both inherit and set pipes to /dev/null */
456 : 739 : g_return_val_if_fail ((flags & INHERITS_OR_NULL_STDIN) != INHERITS_OR_NULL_STDIN, FALSE);
457 : 739 : g_return_val_if_fail ((flags & INHERITS_OR_NULL_STDOUT) != INHERITS_OR_NULL_STDOUT, FALSE);
458 : 739 : g_return_val_if_fail ((flags & INHERITS_OR_NULL_STDERR) != INHERITS_OR_NULL_STDERR, FALSE);
459 : : /* can’t use pipes and stdin/stdout/stderr FDs */
460 : 739 : g_return_val_if_fail (stdin_pipe_out == NULL || stdin_fd < 0, FALSE);
461 : 739 : g_return_val_if_fail (stdout_pipe_out == NULL || stdout_fd < 0, FALSE);
462 : 739 : g_return_val_if_fail (stderr_pipe_out == NULL || stderr_fd < 0, FALSE);
463 : :
464 : 739 : return g_spawn_async_with_pipes_and_fds_impl (working_directory, argv,
465 : : envp, flags, child_setup,
466 : : user_data, stdin_fd, stdout_fd,
467 : : stderr_fd,
468 : : source_fds, target_fds, n_fds,
469 : : child_pid_out, stdin_pipe_out,
470 : : stdout_pipe_out,
471 : : stderr_pipe_out, error);
472 : : }
473 : :
474 : : /**
475 : : * g_spawn_async_with_fds:
476 : : * @working_directory: (type filename) (nullable): child's current working directory, or %NULL to inherit parent's, in the GLib file name encoding
477 : : * @argv: (array zero-terminated=1): child's argument vector, in the GLib file name encoding;
478 : : * it must be non-empty and %NULL-terminated
479 : : * @envp: (array zero-terminated=1) (nullable): child's environment, or %NULL to inherit parent's, in the GLib file name encoding
480 : : * @flags: flags from #GSpawnFlags
481 : : * @child_setup: (scope async) (closure user_data) (nullable): function to run
482 : : * in the child just before `exec()`
483 : : * @user_data: user data for @child_setup
484 : : * @child_pid: (out) (optional): return location for child process ID, or %NULL
485 : : * @stdin_fd: file descriptor to use for child's stdin, or `-1`
486 : : * @stdout_fd: file descriptor to use for child's stdout, or `-1`
487 : : * @stderr_fd: file descriptor to use for child's stderr, or `-1`
488 : : * @error: return location for error
489 : : *
490 : : * Executes a child program asynchronously.
491 : : *
492 : : * Identical to g_spawn_async_with_pipes_and_fds() but with `n_fds` set to zero,
493 : : * so no FD assignments are used.
494 : : *
495 : : * Returns: %TRUE on success, %FALSE if an error was set
496 : : *
497 : : * Since: 2.58
498 : : */
499 : : gboolean
500 : 98 : g_spawn_async_with_fds (const gchar *working_directory,
501 : : gchar **argv,
502 : : gchar **envp,
503 : : GSpawnFlags flags,
504 : : GSpawnChildSetupFunc child_setup,
505 : : gpointer user_data,
506 : : GPid *child_pid,
507 : : gint stdin_fd,
508 : : gint stdout_fd,
509 : : gint stderr_fd,
510 : : GError **error)
511 : : {
512 : 98 : g_return_val_if_fail (stdout_fd < 0 ||
513 : : !(flags & G_SPAWN_STDOUT_TO_DEV_NULL), FALSE);
514 : 98 : g_return_val_if_fail (stderr_fd < 0 ||
515 : : !(flags & G_SPAWN_STDERR_TO_DEV_NULL), FALSE);
516 : : /* can't inherit stdin if we have an input pipe. */
517 : 98 : g_return_val_if_fail (stdin_fd < 0 ||
518 : : !(flags & G_SPAWN_CHILD_INHERITS_STDIN), FALSE);
519 : :
520 : 98 : return g_spawn_async_with_pipes_and_fds (working_directory,
521 : : (const gchar * const *) argv,
522 : : (const gchar * const *) envp,
523 : : flags, child_setup, user_data,
524 : : stdin_fd, stdout_fd, stderr_fd,
525 : : NULL, NULL, 0,
526 : : child_pid,
527 : : NULL, NULL, NULL,
528 : : error);
529 : : }
530 : :
531 : : /**
532 : : * g_spawn_command_line_sync:
533 : : * @command_line: (type filename): a command line
534 : : * @standard_output: (out) (array zero-terminated=1) (element-type guint8) (optional): return location for child output
535 : : * @standard_error: (out) (array zero-terminated=1) (element-type guint8) (optional): return location for child errors
536 : : * @wait_status: (out) (optional): return location for child wait status, as returned by waitpid()
537 : : * @error: return location for errors
538 : : *
539 : : * A simple version of g_spawn_sync() with little-used parameters
540 : : * removed, taking a command line instead of an argument vector.
541 : : *
542 : : * See g_spawn_sync() for full details.
543 : : *
544 : : * The @command_line argument will be parsed by g_shell_parse_argv().
545 : : *
546 : : * Unlike g_spawn_sync(), the %G_SPAWN_SEARCH_PATH flag is enabled.
547 : : * Note that %G_SPAWN_SEARCH_PATH can have security implications, so
548 : : * consider using g_spawn_sync() directly if appropriate.
549 : : *
550 : : * Possible errors are those from g_spawn_sync() and those
551 : : * from g_shell_parse_argv().
552 : : *
553 : : * If @wait_status is non-%NULL, the platform-specific status of
554 : : * the child is stored there; see the documentation of
555 : : * g_spawn_check_wait_status() for how to use and interpret this.
556 : : * On Unix platforms, note that it is usually not equal
557 : : * to the integer passed to `exit()` or returned from `main()`.
558 : : *
559 : : * On Windows, please note the implications of g_shell_parse_argv()
560 : : * parsing @command_line. Parsing is done according to Unix shell rules, not
561 : : * Windows command interpreter rules.
562 : : * Space is a separator, and backslashes are
563 : : * special. Thus you cannot simply pass a @command_line containing
564 : : * canonical Windows paths, like "c:\\program files\\app\\app.exe", as
565 : : * the backslashes will be eaten, and the space will act as a
566 : : * separator. You need to enclose such paths with single quotes, like
567 : : * "'c:\\program files\\app\\app.exe' 'e:\\folder\\argument.txt'".
568 : : *
569 : : * Returns: %TRUE on success, %FALSE if an error was set
570 : : **/
571 : : gboolean
572 : 58 : g_spawn_command_line_sync (const gchar *command_line,
573 : : gchar **standard_output,
574 : : gchar **standard_error,
575 : : gint *wait_status,
576 : : GError **error)
577 : : {
578 : : gboolean retval;
579 : 58 : gchar **argv = NULL;
580 : :
581 : 58 : g_return_val_if_fail (command_line != NULL, FALSE);
582 : :
583 : : /* This will return a runtime error if @command_line is the empty string. */
584 : 58 : if (!g_shell_parse_argv (command_line,
585 : : NULL, &argv,
586 : : error))
587 : 0 : return FALSE;
588 : :
589 : 58 : retval = g_spawn_sync (NULL,
590 : : argv,
591 : : NULL,
592 : : G_SPAWN_SEARCH_PATH,
593 : : NULL,
594 : : NULL,
595 : : standard_output,
596 : : standard_error,
597 : : wait_status,
598 : : error);
599 : 58 : g_strfreev (argv);
600 : :
601 : 58 : return retval;
602 : : }
603 : :
604 : : /**
605 : : * g_spawn_command_line_async:
606 : : * @command_line: (type filename): a command line
607 : : * @error: return location for errors
608 : : *
609 : : * A simple version of g_spawn_async() that parses a command line with
610 : : * g_shell_parse_argv() and passes it to g_spawn_async().
611 : : *
612 : : * Runs a command line in the background. Unlike g_spawn_async(), the
613 : : * %G_SPAWN_SEARCH_PATH flag is enabled, other flags are not. Note
614 : : * that %G_SPAWN_SEARCH_PATH can have security implications, so
615 : : * consider using g_spawn_async() directly if appropriate. Possible
616 : : * errors are those from g_shell_parse_argv() and g_spawn_async().
617 : : *
618 : : * The same concerns on Windows apply as for g_spawn_command_line_sync().
619 : : *
620 : : * Returns: %TRUE on success, %FALSE if error is set
621 : : **/
622 : : gboolean
623 : 12 : g_spawn_command_line_async (const gchar *command_line,
624 : : GError **error)
625 : : {
626 : : gboolean retval;
627 : 12 : gchar **argv = NULL;
628 : :
629 : 12 : g_return_val_if_fail (command_line != NULL, FALSE);
630 : :
631 : : /* This will return a runtime error if @command_line is the empty string. */
632 : 12 : if (!g_shell_parse_argv (command_line,
633 : : NULL, &argv,
634 : : error))
635 : 0 : return FALSE;
636 : :
637 : 12 : retval = g_spawn_async (NULL,
638 : : argv,
639 : : NULL,
640 : : G_SPAWN_SEARCH_PATH,
641 : : NULL,
642 : : NULL,
643 : : NULL,
644 : : error);
645 : 12 : g_strfreev (argv);
646 : :
647 : 12 : return retval;
648 : : }
649 : :
650 : : /**
651 : : * g_spawn_check_wait_status:
652 : : * @wait_status: A platform-specific wait status as returned from g_spawn_sync()
653 : : * @error: a #GError
654 : : *
655 : : * Set @error if @wait_status indicates the child exited abnormally
656 : : * (e.g. with a nonzero exit code, or via a fatal signal).
657 : : *
658 : : * The g_spawn_sync() and g_child_watch_add() family of APIs return the
659 : : * status of subprocesses encoded in a platform-specific way.
660 : : * On Unix, this is guaranteed to be in the same format waitpid() returns,
661 : : * and on Windows it is guaranteed to be the result of GetExitCodeProcess().
662 : : *
663 : : * Prior to the introduction of this function in GLib 2.34, interpreting
664 : : * @wait_status required use of platform-specific APIs, which is problematic
665 : : * for software using GLib as a cross-platform layer.
666 : : *
667 : : * Additionally, many programs simply want to determine whether or not
668 : : * the child exited successfully, and either propagate a #GError or
669 : : * print a message to standard error. In that common case, this function
670 : : * can be used. Note that the error message in @error will contain
671 : : * human-readable information about the wait status.
672 : : *
673 : : * The @domain and @code of @error have special semantics in the case
674 : : * where the process has an "exit code", as opposed to being killed by
675 : : * a signal. On Unix, this happens if WIFEXITED() would be true of
676 : : * @wait_status. On Windows, it is always the case.
677 : : *
678 : : * The special semantics are that the actual exit code will be the
679 : : * code set in @error, and the domain will be %G_SPAWN_EXIT_ERROR.
680 : : * This allows you to differentiate between different exit codes.
681 : : *
682 : : * If the process was terminated by some means other than an exit
683 : : * status (for example if it was killed by a signal), the domain will be
684 : : * %G_SPAWN_ERROR and the code will be %G_SPAWN_ERROR_FAILED.
685 : : *
686 : : * This function just offers convenience; you can of course also check
687 : : * the available platform via a macro such as %G_OS_UNIX, and use
688 : : * WIFEXITED() and WEXITSTATUS() on @wait_status directly. Do not attempt
689 : : * to scan or parse the error message string; it may be translated and/or
690 : : * change in future versions of GLib.
691 : : *
692 : : * Prior to version 2.70, g_spawn_check_exit_status() provides the same
693 : : * functionality, although under a misleading name.
694 : : *
695 : : * Returns: %TRUE if child exited successfully, %FALSE otherwise (and
696 : : * @error will be set)
697 : : *
698 : : * Since: 2.70
699 : : */
700 : : gboolean
701 : 196 : g_spawn_check_wait_status (gint wait_status,
702 : : GError **error)
703 : : {
704 : 196 : return g_spawn_check_wait_status_impl (wait_status, error);
705 : : }
706 : :
707 : : /**
708 : : * g_spawn_check_exit_status:
709 : : * @wait_status: A status as returned from g_spawn_sync()
710 : : * @error: a #GError
711 : : *
712 : : * An old name for g_spawn_check_wait_status(), deprecated because its
713 : : * name is misleading.
714 : : *
715 : : * Despite the name of the function, @wait_status must be the wait status
716 : : * as returned by g_spawn_sync(), g_subprocess_get_status(), `waitpid()`,
717 : : * etc. On Unix platforms, it is incorrect for it to be the exit status
718 : : * as passed to `exit()` or returned by g_subprocess_get_exit_status() or
719 : : * `WEXITSTATUS()`.
720 : : *
721 : : * Returns: %TRUE if child exited successfully, %FALSE otherwise (and
722 : : * @error will be set)
723 : : *
724 : : * Since: 2.34
725 : : *
726 : : * Deprecated: 2.70: Use g_spawn_check_wait_status() instead, and check whether your code is conflating wait and exit statuses.
727 : : */
728 : : gboolean
729 : 0 : g_spawn_check_exit_status (gint wait_status,
730 : : GError **error)
731 : : {
732 : 0 : return g_spawn_check_wait_status (wait_status, error);
733 : : }
734 : :
735 : : /**
736 : : * g_spawn_close_pid:
737 : : * @pid: The process reference to close
738 : : *
739 : : * On some platforms, notably Windows, the #GPid type represents a resource
740 : : * which must be closed to prevent resource leaking. g_spawn_close_pid()
741 : : * is provided for this purpose. It should be used on all platforms, even
742 : : * though it doesn't do anything under UNIX.
743 : : **/
744 : : void
745 : 187 : g_spawn_close_pid (GPid pid)
746 : : {
747 : 187 : g_spawn_close_pid_impl (pid);
748 : 187 : }
|
