Class
GioSubprocess
since: 2.40
Description
final class Gio.Subprocess : GObject.Object {
/* No available fields */
}GSubprocess allows the creation of and interaction with child processes.
Processes can be communicated with using standard GIO-style APIs (ie:
GInputStream, GOutputStream). There are GIO-style APIs
to wait for process termination (ie: cancellable and with an asynchronous variant).
There is an API to force a process to terminate, as well as a race-free API for sending UNIX signals to a subprocess.
One major advantage that GIO brings over the core GLib library is
comprehensive API for asynchronous I/O, such
g_output_stream_splice_async(). This makes GSubprocess
significantly more powerful and flexible than equivalent APIs in
some other languages such as the subprocess.py
included with Python. For example, using GSubprocess one could
create two child processes, reading standard output from the first,
processing it, and writing to the input stream of the second, all
without blocking the main loop.
A powerful g_subprocess_communicate() API is provided similar to the
communicate() method of subprocess.py. This enables very easy
interaction with a subprocess that has been opened with pipes.
GSubprocess defaults to tight control over the file descriptors open
in the child process, avoiding dangling-FD issues that are caused by
a simple fork()/exec(). The only open file descriptors in the
spawned process are ones that were explicitly specified by the
GSubprocess API (unless G_SUBPROCESS_FLAGS_INHERIT_FDS was specified).
GSubprocess will quickly reap all child processes as they exit,
avoiding ‘zombie processes’ remaining around for long periods of
time. g_subprocess_wait() can be used to wait for this to happen,
but it will happen even without the call being explicitly made.
As a matter of principle, GSubprocess has no API that accepts
shell-style space-separated strings. It will, however, match the
typical shell behaviour of searching the PATH for executables that do
not contain a directory separator in their name. By default, the PATH
of the current process is used. You can specify
G_SUBPROCESS_FLAGS_SEARCH_PATH_FROM_ENVP to use the PATH of the
launcher environment instead.
GSubprocess attempts to have a very simple API for most uses (ie:
spawning a subprocess with arguments and support for most typical
kinds of input and output redirection). See g_subprocess_new(). The
GSubprocessLauncher API is provided for more complicated cases
(advanced types of redirection, environment variable manipulation,
change of working directory, child setup functions, etc).
A typical use of GSubprocess will involve calling
g_subprocess_new(), followed by g_subprocess_wait_async() or
g_subprocess_wait(). After the process exits, the status can be
checked using functions such as g_subprocess_get_if_exited() (which
are similar to the familiar WIFEXITED-style POSIX macros).
Note that as of GLib 2.82, creating a GSubprocess causes the signal
SIGPIPE to be ignored for the remainder of the program. If you are writing
a command-line utility that uses GSubprocess, you may need to take into
account the fact that your program will not automatically be killed
if it tries to write to stdout after it has been closed.
Available since: 2.40
Constructors
g_subprocess_new
Create a new process with the given flags and varargs argument
list. By default, matching the g_spawn_async() defaults, the
child’s stdin will be set to the system null device, and
stdout/stderr will be inherited from the parent. You can use
flags to control this behavior.
since: 2.40
Instance methods
g_subprocess_communicate
Communicate with the subprocess until it terminates, and all input and output has been completed.
since: 2.40
g_subprocess_communicate_async
Asynchronous version of g_subprocess_communicate(). Complete invocation with g_subprocess_communicate_finish().
g_subprocess_communicate_utf8
Like g_subprocess_communicate(), but validates the output of the process as UTF-8, and returns it as a regular NUL terminated string.
g_subprocess_communicate_utf8_async
Asynchronous version of g_subprocess_communicate_utf8(). Complete invocation with g_subprocess_communicate_utf8_finish().
g_subprocess_communicate_utf8_finish
Complete an invocation of g_subprocess_communicate_utf8_async().
g_subprocess_force_exit
Use an operating-system specific method to attempt an immediate,
forceful termination of the process. There is no mechanism to
determine whether or not the request itself was successful;
however, you can use g_subprocess_wait() to monitor the status of
the process after calling this function.
since: 2.40
g_subprocess_get_exit_status
Check the exit status of the subprocess, given that it exited
normally. This is the value passed to the exit() system call or the
return value from main.
since: 2.40
g_subprocess_get_identifier
On UNIX, returns the process ID as a decimal string.
On Windows, returns the result of GetProcessId() also as a string.
If the subprocess has terminated, this will return NULL.
since: 2.40
g_subprocess_get_if_exited
Check if the given subprocess exited normally (ie: by way of exit()
or return from main()).
since: 2.40
g_subprocess_get_if_signaled
Check if the given subprocess terminated in response to a signal.
since: 2.40
g_subprocess_get_stderr_pipe
Gets the GInputStream from which to read the stderr output of
subprocess.
since: 2.40
g_subprocess_get_stdin_pipe
Gets the GOutputStream that you can write to in order to give data
to the stdin of subprocess.
since: 2.40
g_subprocess_get_stdout_pipe
Gets the GInputStream from which to read the stdout output of
subprocess.
since: 2.40
g_subprocess_get_successful
Checks if the process was “successful”. A process is considered
successful if it exited cleanly with an exit status of 0, either by
way of the exit() system call or return from main().
since: 2.40
g_subprocess_get_term_sig
Get the signal number that caused the subprocess to terminate, given that it terminated due to a signal.
since: 2.40
g_subprocess_send_signal
Sends the UNIX signal signal_num to the subprocess, if it is still running.
since: 2.40
g_subprocess_wait_check_async
Combines g_subprocess_wait_async() with g_spawn_check_wait_status().
since: 2.40
g_subprocess_wait_check_finish
Collects the result of a previous call to g_subprocess_wait_check_async().
since: 2.40
g_subprocess_wait_finish
Collects the result of a previous call to g_subprocess_wait_async().
since: 2.40
Methods inherited from GInitable (1)
Signals
Signals inherited from GObject (1)
GObject::notify
The notify signal is emitted on an object when one of its properties has its value set through g_object_set_property(), g_object_set(), et al.