Function
GLibspawn_async_with_pipes_and_fds
since: 2.68
Declaration
gboolean
g_spawn_async_with_pipes_and_fds (
const gchar* working_directory,
const gchar* const* argv,
const gchar* const* envp,
GSpawnFlags flags,
GSpawnChildSetupFunc child_setup,
gpointer user_data,
gint stdin_fd,
gint stdout_fd,
gint stderr_fd,
const gint* source_fds,
const gint* target_fds,
gsize n_fds,
GPid* child_pid_out,
gint* stdin_pipe_out,
gint* stdout_pipe_out,
gint* stderr_pipe_out,
GError** error
)
Description
Executes a child program asynchronously (your program will not block waiting for the child to exit).
The child program is specified by the only argument that must be
provided, argv. argv should be a NULL-terminated array of strings,
to be passed as the argument vector for the child. The first string
in argv is of course the name of the program to execute. By default,
the name of the program must be a full path. If flags contains the
G_SPAWN_SEARCH_PATH flag, the PATH environment variable is used to
search for the executable. If flags contains the
G_SPAWN_SEARCH_PATH_FROM_ENVP flag, the PATH variable from envp
is used to search for the executable. If both the
G_SPAWN_SEARCH_PATH and G_SPAWN_SEARCH_PATH_FROM_ENVP flags are
set, the PATH variable from envp takes precedence over the
environment variable.
If the program name is not a full path and G_SPAWN_SEARCH_PATH flag
is not used, then the program will be run from the current directory
(or working_directory, if specified); this might be unexpected or even
dangerous in some cases when the current directory is world-writable.
On Windows, note that all the string or string vector arguments to
this function and the other g_spawn*() functions are in UTF-8, the
GLib file name encoding. Unicode characters that are not part of
the system codepage passed in these arguments will be correctly
available in the spawned program only if it uses wide character API
to retrieve its command line. For C programs built with Microsoft’s
tools it is enough to make the program have a wmain() instead of
main(). wmain() has a wide character argument vector as parameter.
At least currently, mingw doesn’t support wmain(), so if you use
mingw to develop the spawned program, it should call
g_win32_get_command_line() to get arguments in UTF-8.
On Windows the low-level child process creation API CreateProcess()
doesn’t use argument vectors, but a command line. The C runtime
library’s spawn*() family of functions (which g_spawn_async_with_pipes()
eventually calls) paste the argument vector elements together into
a command line, and the C runtime startup code does a corresponding
reconstruction of an argument vector from the command line, to be
passed to main(). Complications arise when you have argument vector
elements that contain spaces or double quotes. The spawn*() functions
don’t do any quoting or escaping, but on the other hand the startup
code does do unquoting and unescaping in order to enable receiving
arguments with embedded spaces or double quotes. To work around this
asymmetry, g_spawn_async_with_pipes() will do quoting and escaping on
argument vector elements that need it before calling the C runtime
spawn() function.
The returned child_pid on Windows is a handle to the child
process, not its identifier. Process handles and process
identifiers are different concepts on Windows.
envp is a NULL-terminated array of strings, where each string
has the form KEY=VALUE. This will become the child’s environment.
If envp is NULL, the child inherits its parent’s environment.
flags should be the bitwise OR of any flags you want to affect the
function’s behaviour. The G_SPAWN_DO_NOT_REAP_CHILD means that the
child will not automatically be reaped; you must use a child watch
(g_child_watch_add()) to be notified about the death of the child process,
otherwise it will stay around as a zombie process until this process exits.
Eventually you must call g_spawn_close_pid() on the child_pid, in order to
free resources which may be associated with the child process. (On Unix,
using a child watch is equivalent to calling waitpid() or handling
the SIGCHLD signal manually. On Windows, calling g_spawn_close_pid()
is equivalent to calling CloseHandle() on the process handle returned
in child_pid). See g_child_watch_add().
Open UNIX file descriptors marked as FD_CLOEXEC will be automatically
closed in the child process. G_SPAWN_LEAVE_DESCRIPTORS_OPEN means that
other open file descriptors will be inherited by the child; otherwise all
descriptors except stdin/stdout/stderr will be closed before calling exec()
in the child. G_SPAWN_SEARCH_PATH means that argv[0] need not be an
absolute path, it will be looked for in the PATH environment
variable. G_SPAWN_SEARCH_PATH_FROM_ENVP means need not be an
absolute path, it will be looked for in the PATH variable from
envp. If both G_SPAWN_SEARCH_PATH and G_SPAWN_SEARCH_PATH_FROM_ENVP
are used, the value from envp takes precedence over the environment.
G_SPAWN_CHILD_INHERITS_STDIN means that the child will inherit the parent’s
standard input (by default, the child’s standard input is attached to
/dev/null). G_SPAWN_STDIN_FROM_DEV_NULL explicitly imposes the default
behavior. Both flags cannot be enabled at the same time and, in both cases,
the stdin_pipe_out argument is ignored.
G_SPAWN_STDOUT_TO_DEV_NULL means that the child’s standard output
will be discarded (by default, it goes to the same location as the parent’s
standard output). G_SPAWN_CHILD_INHERITS_STDOUT explicitly imposes the
default behavior. Both flags cannot be enabled at the same time and, in
both cases, the stdout_pipe_out argument is ignored.
G_SPAWN_STDERR_TO_DEV_NULL means that the child’s standard error
will be discarded (by default, it goes to the same location as the parent’s
standard error). G_SPAWN_CHILD_INHERITS_STDERR explicitly imposes the
default behavior. Both flags cannot be enabled at the same time and, in
both cases, the stderr_pipe_out argument is ignored.
It is valid to pass the same FD in multiple parameters (e.g. you can pass
a single FD for both stdout_fd and stderr_fd, and include it in
source_fds too).
source_fds and target_fds allow zero or more FDs from this process to be
remapped to different FDs in the spawned process. If n_fds is greater than
zero, source_fds and target_fds must both be non-NULL and the same length.
Each FD in source_fds is remapped to the FD number at the same index in
target_fds. The source and target FD may be equal to simply propagate an FD
to the spawned process. FD remappings are processed after standard FDs, so
any target FDs which equal stdin_fd, stdout_fd or stderr_fd will overwrite
them in the spawned process.
source_fds is supported on Windows since 2.72.
G_SPAWN_FILE_AND_ARGV_ZERO means that the first element of argv is
the file to execute, while the remaining elements are the actual
argument vector to pass to the file. Normally g_spawn_async_with_pipes()
uses argv[0] as the file to execute, and passes all of argv to the child.
child_setup and user_data are a function and user data. On POSIX
platforms, the function is called in the child after GLib has
performed all the setup it plans to perform (including creating
pipes, closing file descriptors, etc.) but before calling exec().
That is, child_setup is called just before calling exec() in the
child. Obviously actions taken in this function will only affect
the child, not the parent.
On Windows, there is no separate fork() and exec() functionality.
Child processes are created and run with a single API call,
CreateProcess(). There is no sensible thing child_setup
could be used for on Windows so it is ignored and not called.
If non-NULL, child_pid will on Unix be filled with the child’s
process ID. You can use the process ID to send signals to the child,
or to use g_child_watch_add() (or waitpid()) if you specified the
G_SPAWN_DO_NOT_REAP_CHILD flag. On Windows, child_pid will be
filled with a handle to the child process only if you specified the
G_SPAWN_DO_NOT_REAP_CHILD flag. You can then access the child
process using the Win32 API, for example wait for its termination
with the WaitFor*() functions, or examine its exit code with
GetExitCodeProcess(). You should close the handle with CloseHandle()
or g_spawn_close_pid() when you no longer need it.
If non-NULL, the stdin_pipe_out, stdout_pipe_out, stderr_pipe_out
locations will be filled with file descriptors for writing to the child’s
standard input or reading from its standard output or standard error.
The caller of g_spawn_async_with_pipes() must close these file descriptors
when they are no longer in use. If these parameters are NULL, the
corresponding pipe won’t be created.
If stdin_pipe_out is NULL, the child’s standard input is attached to
/dev/null unless G_SPAWN_CHILD_INHERITS_STDIN is set.
If stderr_pipe_out is NULL, the child’s standard error goes to the same
location as the parent’s standard error unless G_SPAWN_STDERR_TO_DEV_NULL
is set.
If stdout_pipe_out is NULL, the child’s standard output goes to the same
location as the parent’s standard output unless G_SPAWN_STDOUT_TO_DEV_NULL
is set.
error can be NULL to ignore errors, or non-NULL to report errors.
If an error is set, the function returns FALSE. Errors are reported
even if they occur in the child (for example if the executable in
`argv[0]is not found). Typically themessagefield of returned
errors should be displayed to users. Possible errors are those from
theG_SPAWN_ERROR` domain.
If an error occurs, child_pid, stdin_pipe_out, stdout_pipe_out,
and stderr_pipe_out will not be filled with valid values.
If child_pid is not NULL and an error does not occur then the returned
process reference must be closed using g_spawn_close_pid().
On modern UNIX platforms, GLib can use an efficient process launching
codepath driven internally by posix_spawn(). This has the advantage of
avoiding the fork-time performance costs of cloning the parent process
address space, and avoiding associated memory overcommit checks that are
not relevant in the context of immediately executing a distinct process.
This optimized codepath will be used provided that the following conditions
are met:
G_SPAWN_DO_NOT_REAP_CHILDis setG_SPAWN_LEAVE_DESCRIPTORS_OPENis setG_SPAWN_SEARCH_PATH_FROM_ENVPis not setworking_directoryisNULLchild_setupisNULL- The program is of a recognised binary format, or has a shebang. Otherwise, GLib will have to execute the program through the shell, which is not done using the optimized codepath.
If you are writing a GTK application, and the program you are spawning is a
graphical application too, then to ensure that the spawned program opens its
windows on the right screen, you may want to use GdkAppLaunchContext,
GAppLaunchContext, or set the DISPLAY environment variable.
Available since: 2.68
Parameters
working_directory-
Type:
const gchar*Child’s current working directory, or
NULLto inherit parent’s, in the GLib file name encoding.The argument can be NULL.The data is owned by the caller of the function. The value is a platform-native string, using the preferred OS encoding on Unix and UTF-8 on Windows. argv-
Type: An array of
filenameChild’s argument vector, in the GLib file name encoding; it must be non-empty and
NULL-terminated.The array must be NULL-terminated.The data is owned by the caller of the function. Each element is a platform-native string, using the preferred OS encoding on Unix and UTF-8 on Windows.. envp-
Type: An array of
filenamechild's environment, or `NULL` to inherit parent's, in the GLib file name encoding.The argument can be NULL.The array must be NULL-terminated.The data is owned by the caller of the function. Each element is a platform-native string, using the preferred OS encoding on Unix and UTF-8 on Windows.. flags-
Type:
GSpawnFlagsFlags from
GSpawnFlags. child_setup-
Type:
GSpawnChildSetupFuncFunction to run in the child just before
exec().The argument can be NULL. user_data-
Type:
gpointerUser data for
child_setup.The argument can be NULL.The data is owned by the caller of the function. stdin_fd-
Type:
gintFile descriptor to use for child’s stdin, or
-1. stdout_fd-
Type:
gintFile descriptor to use for child’s stdout, or
-1. stderr_fd-
Type:
gintFile descriptor to use for child’s stderr, or
-1. source_fds-
Type: An array of
gintArray of FDs from the parent process to make available in the child process.
The argument can be NULL.The length of the array is specified in the n_fdsargument.The data is owned by the caller of the function. target_fds-
Type: An array of
gintArray of FDs to remap
source_fdsto in the child process.The argument can be NULL.The length of the array is specified in the n_fdsargument.The data is owned by the caller of the function. n_fds-
Type:
gsizeNumber of FDs in
source_fdsandtarget_fds. child_pid_out-
Type:
GPidReturn location for child process ID, or
NULL.The argument will be set by the function. The argument can be NULL.The caller of the function takes ownership of the returned data, and is responsible for freeing it. stdin_pipe_out-
Type:
gint*Return location for file descriptor to write to child’s stdin, or
NULL.The argument will be set by the function. The argument can be NULL. stdout_pipe_out-
Type:
gint*Return location for file descriptor to read child’s stdout, or
NULL.The argument will be set by the function. The argument can be NULL. stderr_pipe_out-
Type:
gint*Return location for file descriptor to read child’s stderr, or
NULL.The argument will be set by the function. The argument can be NULL. error-
Type:
GError **The return location for a recoverable error.
The argument can be NULL.If the return location is not NULL, then you must initialize it to aNULLGError*.The argument will be left initialized to NULLby the function if there are no errors.In case of error, the argument will be set to a newly allocated GError; the caller will take ownership of the data, and be responsible for freeing it.