Subprocess

Object Hierarchy:

Description:

[ CCode ( type_id = "g_subprocess_get_type ()" ) ]
[ Version ( since = "2.40" ) ]
public sealed class Subprocess : Object, Initable

`GSubprocess` allows the creation of and interaction with child processes.

Processes can be communicated with using standard GIO-style APIs (ie: [class@Gio.InputStream], [class@Gio.OutputStream]). 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 [ method@Gio.OutputStream.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 [method@Gio.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. [ method@Gio.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 [ctor@Gio.Subprocess.new]. The [class@Gio.SubprocessLauncher] 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 [ctor@Gio.Subprocess.new], followed by [method@Gio.Subprocess.wait_async] or [ method@Gio.Subprocess.wait]. After the process exits, the status can be checked using functions such as [method@Gio.Subprocess.get_if_exited] ( which are similar to the familiar `WIFEXITED`-style POSIX macros).

Namespace: GLib

Package: gio-2.0

Content:

Properties:

public string[] argv { construct; }
Argument vector.
public SubprocessFlags flags { construct; }
Subprocess flags.

Creation methods:

public Subprocess (SubprocessFlags flags, ...) throws Error
Create a new process with the given flags and varargs argument list.
public Subprocess.newv (string[] argv, SubprocessFlags flags) throws Error
Create a new process with the given flags and argument list.

Methods:

public bool communicate (Bytes? stdin_buf, Cancellable? cancellable, out Bytes? stdout_buf, out Bytes? stderr_buf) throws Error
Communicate with the subprocess until it terminates, and all input and output has been completed.
public async bool communicate_async (Bytes? stdin_buf, Cancellable? cancellable, out Bytes? stdout_buf, out Bytes? stderr_buf) throws Error
Asynchronous version of communicate.
public bool communicate_utf8 (string? stdin_buf, Cancellable? cancellable, out string? stdout_buf, out string? stderr_buf) throws Error
Like communicate, but validates the output of the process as UTF-8, and returns it as a regular NUL terminated string.
public async bool communicate_utf8_async (string? stdin_buf, Cancellable? cancellable, out string? stdout_buf, out string? stderr_buf) throws Error
Asynchronous version of communicate_utf8.
public void force_exit ()
Use an operating-system specific method to attempt an immediate, forceful termination of the process.
public int get_exit_status ()
Check the exit status of the subprocess, given that it exited normally.
public unowned string? get_identifier ()
On UNIX, returns the process ID as a decimal string.
public bool get_if_exited ()
Check if the given subprocess exited normally (ie: by way of exit or return from main).
public bool get_if_signaled ()
Check if the given subprocess terminated in response to a signal.
public int get_status ()
Gets the raw status code of the process, as from waitpid.
public unowned InputStream? get_stderr_pipe ()
Gets the InputStream from which to read the stderr output of this.
public unowned OutputStream? get_stdin_pipe ()
Gets the OutputStream that you can write to in order to give data to the stdin of this.
public unowned InputStream? get_stdout_pipe ()
Gets the InputStream from which to read the stdout output of this.
public bool get_successful ()
Checks if the process was "successful".
public int get_term_sig ()
Get the signal number that caused the subprocess to terminate, given that it terminated due to a signal.
public void send_signal (int signal_num)
Sends the UNIX signal signal_num to the subprocess, if it is still running.
public bool wait (Cancellable? cancellable = null) throws Error
Synchronously wait for the subprocess to terminate.
public async bool wait_async (Cancellable? cancellable = null) throws Error
Wait for the subprocess to terminate.
public bool wait_check (Cancellable? cancellable = null) throws Error
Combines wait with check_wait_status.
public async bool wait_check_async (Cancellable? cancellable = null) throws Error
Combines wait_async with check_wait_status.

Inherited Members:

All known members inherited from class GLib.Object

All known members inherited from interface GLib.Initable

@new
init

new_valist

newv