Gio.Subprocess
Description: Reference for Gio.Subprocess

### Class

# GioSubprocess

since: 2.40

#### Description [src]

    final class Gio.Subprocess : GObject.Object
      implements Gio.Initable {
      /* 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

#### Ancestors

- GObject

#### Implements

- GInitable

#### 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

###### g_subprocess_newv

Create a new process with the given flags and argument list.

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_finish

Complete an invocation of g_subprocess_communicate_async().

###### 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_status

Gets the raw status code of the process, as from waitpid().

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

Synchronously wait for the subprocess to terminate.

since: 2.40

###### g_subprocess_wait_async

Wait for the subprocess to terminate.

since: 2.40

###### g_subprocess_wait_check

Combines `g_subprocess_wait()` with g_spawn_check_wait_status().

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 GObject (43)

Please see GObject for a full list of methods.

##### Methods inherited from GInitable (1)

###### g_initable_init

Initializes the object implementing the interface.

since: 2.22

#### Properties

###### Gio.Subprocess:argv

Argument vector.

since: 2.40

###### Gio.Subprocess:flags

Subprocess flags.

since: 2.40

#### 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.