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