GIO Reference Manual: GSubprocess

## GSubprocess GSubprocess — Child processes |

## Functions

GSubprocess * | g_subprocess_new ()
GSubprocess * | g_subprocess_newv ()
const gchar * | g_subprocess_get_identifier ()
GOutputStream * | g_subprocess_get_stdin_pipe ()
GInputStream * | g_subprocess_get_stdout_pipe ()
GInputStream * | g_subprocess_get_stderr_pipe ()
gboolean | g_subprocess_wait ()
void | g_subprocess_wait_async ()
gboolean | g_subprocess_wait_finish ()
gboolean | g_subprocess_wait_check ()
void | g_subprocess_wait_check_async ()
gboolean | g_subprocess_wait_check_finish ()
gboolean | g_subprocess_get_successful ()
gboolean | g_subprocess_get_if_exited ()
gint | g_subprocess_get_exit_status ()
gboolean | g_subprocess_get_if_signaled ()
gint | g_subprocess_get_term_sig ()
gint | g_subprocess_get_status ()
void | g_subprocess_send_signal ()
void | g_subprocess_force_exit ()
gboolean | g_subprocess_communicate ()
void | g_subprocess_communicate_async ()
gboolean | g_subprocess_communicate_finish ()
gboolean | g_subprocess_communicate_utf8 ()
void | g_subprocess_communicate_utf8_async ()
gboolean | g_subprocess_communicate_utf8_finish ()

## Properties

GStrv | argv | Write / Construct Only
GSubprocessFlags | flags | Write / Construct Only

## Types and Values

| GSubprocess
enum | GSubprocessFlags

## Object Hierarchy

        GFlags
        ╰── GSubprocessFlags
        GObject
        ╰── GSubprocess

## Implemented Interfaces

GSubprocess implements GInitable.

## Includes

    #include <gio/gio.h>

## Description

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.

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

## Functions

### g_subprocess_new ()

    GSubprocess *
    g_subprocess_new (GSubprocessFlags flags,
                      GError **error,
                      const gchar *argv0,
                      ...);

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.

The argument list must be terminated with `NULL`.

#### Parameters

flags | flags that define the behaviour of the subprocess |
error | return location for an error, or `NULL`. | [allow-none]
argv0 | first commandline argument to pass to the subprocess, followed by more arguments, followed by `NULL` |

#### Returns

A newly created GSubprocess, or `NULL` on error (and `error` will be set)

Since 2.40

### g_subprocess_newv ()

    GSubprocess *
    g_subprocess_newv (const gchar * const *argv,
                       GSubprocessFlags flags,
                       GError **error);

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

The argument list is expected to be `NULL`-terminated.

#### Parameters

argv | commandline arguments for the subprocess. | [array zero-terminated=1][element-type utf8]
flags | flags that define the behaviour of the subprocess |
error | return location for an error, or `NULL`. | [allow-none]

#### Returns

A newly created GSubprocess, or `NULL` on error (and `error` will be set)

Since 2.40

### g_subprocess_get_identifier ()

    const gchar *
    g_subprocess_get_identifier (GSubprocess *subprocess);

On UNIX, returns the process ID as a decimal string. On Windows, returns the result of `GetProcessId()` also as a string.

#### Parameters

subprocess | a GSubprocess |

### g_subprocess_get_stdin_pipe ()

    GOutputStream *
    g_subprocess_get_stdin_pipe (GSubprocess *subprocess);

Gets the GOutputStream that you can write to in order to give data to the stdin of `subprocess` .

The process must have been created with `G_SUBPROCESS_FLAGS_STDIN_PIPE`.

#### Parameters

subprocess | a GSubprocess |

#### Returns

the stdout pipe.

[transfer none]

Since 2.40

### g_subprocess_get_stdout_pipe ()

    GInputStream *
    g_subprocess_get_stdout_pipe (GSubprocess *subprocess);

Gets the GInputStream from which to read the stdout output of `subprocess` .

The process must have been created with `G_SUBPROCESS_FLAGS_STDOUT_PIPE`.

#### Parameters

subprocess | a GSubprocess |

#### Returns

the stdout pipe.

[transfer none]

Since 2.40

### g_subprocess_get_stderr_pipe ()

    GInputStream *
    g_subprocess_get_stderr_pipe (GSubprocess *subprocess);

Gets the GInputStream from which to read the stderr output of `subprocess` .

The process must have been created with `G_SUBPROCESS_FLAGS_STDERR_PIPE`.

#### Parameters

subprocess | a GSubprocess |

#### Returns

the stderr pipe.

[transfer none]

Since 2.40

### g_subprocess_wait ()

    gboolean
    g_subprocess_wait (GSubprocess *subprocess,
                       GCancellable *cancellable,
                       GError **error);

Synchronously wait for the subprocess to terminate.

After the process terminates you can query its exit status with functions such as `g_subprocess_get_if_exited()` and `g_subprocess_get_exit_status()`.

This function does not fail in the case of the subprocess having abnormal termination. See `g_subprocess_wait_check()` for that.

#### Parameters

subprocess | a GSubprocess |
cancellable | a GCancellable |
error | a GError |

#### Returns

`TRUE` on success, `FALSE` if `cancellable` was cancelled

Since 2.40

### g_subprocess_wait_async ()

    void
    g_subprocess_wait_async (GSubprocess *subprocess,
                             GCancellable *cancellable,
                             GAsyncReadyCallback callback,
                             gpointer user_data);

Wait for the subprocess to terminate.

This is the asynchronous version of `g_subprocess_wait()`.

#### Parameters

subprocess | a GSubprocess |
cancellable | a GCancellable, or `NULL` |
callback | a GAsyncReadyCallback to call when the operation is complete |
user_data | user_data for `callback` |

Since 2.40

### g_subprocess_wait_finish ()

    gboolean
    g_subprocess_wait_finish (GSubprocess *subprocess,
                              GAsyncResult *result,
                              GError **error);

Collects the result of a previous call to `g_subprocess_wait_async()`.

#### Parameters

subprocess | a GSubprocess |
result | the GAsyncResult passed to your GAsyncReadyCallback |
error | a pointer to a `NULL` GError, or `NULL` |

#### Returns

`TRUE` if successful, or `FALSE` with `error` set

Since 2.40

### g_subprocess_wait_check ()

    gboolean
    g_subprocess_wait_check (GSubprocess *subprocess,
                             GCancellable *cancellable,
                             GError **error);

Combines `g_subprocess_wait()` with `g_spawn_check_exit_status()`.

#### Parameters

subprocess | a GSubprocess |
cancellable | a GCancellable |
error | a GError |

#### Returns

`TRUE` on success, `FALSE` if process exited abnormally, or `cancellable` was cancelled

Since 2.40

### g_subprocess_wait_check_async ()

    void
    g_subprocess_wait_check_async (GSubprocess *subprocess,
                                   GCancellable *cancellable,
                                   GAsyncReadyCallback callback,
                                   gpointer user_data);

Combines `g_subprocess_wait_async()` with `g_spawn_check_exit_status()`.

This is the asynchronous version of `g_subprocess_wait_check()`.

#### Parameters

subprocess | a GSubprocess |
cancellable | a GCancellable, or `NULL` |
callback | a GAsyncReadyCallback to call when the operation is complete |
user_data | user_data for `callback` |

Since 2.40

### g_subprocess_wait_check_finish ()

    gboolean
    g_subprocess_wait_check_finish (GSubprocess *subprocess,
                                    GAsyncResult *result,
                                    GError **error);

Collects the result of a previous call to `g_subprocess_wait_check_async()`.

#### Parameters

subprocess | a GSubprocess |
result | the GAsyncResult passed to your GAsyncReadyCallback |
error | a pointer to a `NULL` GError, or `NULL` |

#### Returns

`TRUE` if successful, or `FALSE` with `error` set

Since 2.40

### g_subprocess_get_successful ()

    gboolean
    g_subprocess_get_successful (GSubprocess *subprocess);

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()`.

It is an error to call this function before `g_subprocess_wait()` has returned.

#### Parameters

subprocess | a GSubprocess |

#### Returns

`TRUE` if the process exited cleanly with a exit status of 0

Since 2.40

### g_subprocess_get_if_exited ()

    gboolean
    g_subprocess_get_if_exited (GSubprocess *subprocess);

Check if the given subprocess exited normally (ie: by way of `exit()` or return from `main()`).

This is equivalent to the system WIFEXITED macro.

It is an error to call this function before `g_subprocess_wait()` has returned.

#### Parameters

subprocess | a GSubprocess |

#### Returns

`TRUE` if the case of a normal exit

Since 2.40

### g_subprocess_get_exit_status ()

    gint
    g_subprocess_get_exit_status (GSubprocess *subprocess);

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.

This is equivalent to the system WEXITSTATUS macro.

It is an error to call this function before `g_subprocess_wait()` and unless `g_subprocess_get_if_exited()` returned `TRUE`.

#### Parameters

subprocess | a GSubprocess |

#### Returns

the exit status

Since 2.40

### g_subprocess_get_if_signaled ()

    gboolean
    g_subprocess_get_if_signaled (GSubprocess *subprocess);

Check if the given subprocess terminated in response to a signal.

This is equivalent to the system WIFSIGNALED macro.

It is an error to call this function before `g_subprocess_wait()` has returned.

#### Parameters

subprocess | a GSubprocess |

#### Returns

`TRUE` if the case of termination due to a signal

Since 2.40

### g_subprocess_get_term_sig ()

    gint
    g_subprocess_get_term_sig (GSubprocess *subprocess);

Get the signal number that caused the subprocess to terminate, given that it terminated due to a signal.

This is equivalent to the system WTERMSIG macro.

It is an error to call this function before `g_subprocess_wait()` and unless `g_subprocess_get_if_signaled()` returned `TRUE`.

#### Parameters

subprocess | a GSubprocess |

#### Returns

the signal causing termination

Since 2.40

### g_subprocess_get_status ()

    gint
    g_subprocess_get_status (GSubprocess *subprocess);

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

This value has no particular meaning, but it can be used with the macros defined by the system headers such as WIFEXITED. It can also be used with `g_spawn_check_exit_status()`.

It is more likely that you want to use `g_subprocess_get_if_exited()` followed by `g_subprocess_get_exit_status()`.

It is an error to call this function before `g_subprocess_wait()` has returned.

#### Parameters

subprocess | a GSubprocess |

#### Returns

the (meaningless) `waitpid()` exit status from the kernel

Since 2.40

### g_subprocess_send_signal ()

    void
    g_subprocess_send_signal (GSubprocess *subprocess,
                              gint signal_num);

Sends the UNIX signal `signal_num` to the subprocess, if it is still running.

This API is race-free. If the subprocess has terminated, it will not be signalled.

This API is not available on Windows.

#### Parameters

subprocess | a GSubprocess |
signal_num | the signal number to send |

Since 2.40

### g_subprocess_force_exit ()

    void
    g_subprocess_force_exit (GSubprocess *subprocess);

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.

On Unix, this function sends `SIGKILL`.

#### Parameters

subprocess | a GSubprocess |

Since 2.40

### g_subprocess_communicate ()

    gboolean
    g_subprocess_communicate (GSubprocess *subprocess,
                              GBytes *stdin_buf,
                              GCancellable *cancellable,
                              GBytes **stdout_buf,
                              GBytes **stderr_buf,
                              GError **error);

Communicate with the subprocess until it terminates, and all input and output has been completed.

If `stdin_buf` is given, the subprocess must have been created with `G_SUBPROCESS_FLAGS_STDIN_PIPE`. The given data is fed to the stdin of the subprocess and the pipe is closed (ie: EOF).

At the same time (as not to cause blocking when dealing with large amounts of data), if `G_SUBPROCESS_FLAGS_STDOUT_PIPE` or `G_SUBPROCESS_FLAGS_STDERR_PIPE` were used, reads from those streams. The data that was read is returned in `stdout` and/or the `stderr` .

If the subprocess was created with `G_SUBPROCESS_FLAGS_STDOUT_PIPE`, `stdout_buf` will contain the data read from stdout. Otherwise, for subprocesses not created with `G_SUBPROCESS_FLAGS_STDOUT_PIPE`, `stdout_buf` will be set to `NULL`. Similar provisions apply to `stderr_buf` and `G_SUBPROCESS_FLAGS_STDERR_PIPE`.

As usual, any output variable may be given as `NULL` to ignore it.

If you desire the stdout and stderr data to be interleaved, create the subprocess with `G_SUBPROCESS_FLAGS_STDOUT_PIPE` and `G_SUBPROCESS_FLAGS_STDERR_MERGE`. The merged result will be returned in `stdout_buf` and `stderr_buf` will be set to `NULL`.

In case of any error (including cancellation), `FALSE` will be returned with `error` set. Some or all of the stdin data may have been written. Any stdout or stderr data that has been read will be discarded. None of the out variables (aside from `error` ) will have been set to anything in particular and should not be inspected.

In the case that `TRUE` is returned, the subprocess has exited and the exit status inspection APIs (eg: `g_subprocess_get_if_exited()`, `g_subprocess_get_exit_status()`) may be used.

You should not attempt to use any of the subprocess pipes after starting this function, since they may be left in strange states, even if the operation was cancelled. You should especially not attempt to interact with the pipes while the operation is in progress (either from another thread or if using the asynchronous version).

#### Parameters

subprocess | a GSubprocess |
stdin_buf | data to send to the stdin of the subprocess, or `NULL`. | [allow-none]
cancellable | a GCancellable |
stdout_buf | data read from the subprocess stdout. | [out]
stderr_buf | data read from the subprocess stderr. | [out]
error | a pointer to a `NULL` GError pointer, or `NULL` |

#### Returns

`TRUE` if successful

Since 2.40

### g_subprocess_communicate_async ()

    void
    g_subprocess_communicate_async (GSubprocess *subprocess,
                                    GBytes *stdin_buf,
                                    GCancellable *cancellable,
                                    GAsyncReadyCallback callback,
                                    gpointer user_data);

Asynchronous version of `g_subprocess_communicate()`. Complete invocation with `g_subprocess_communicate_finish()`.

#### Parameters

subprocess | Self |
stdin_buf | Input data, or `NULL`. | [allow-none]
cancellable | Cancellable. | [allow-none]
callback | Callback |
user_data | User data |

### g_subprocess_communicate_finish ()

    gboolean
    g_subprocess_communicate_finish (GSubprocess *subprocess,
                                     GAsyncResult *result,
                                     GBytes **stdout_buf,
                                     GBytes **stderr_buf,
                                     GError **error);

Complete an invocation of `g_subprocess_communicate_async()`.

#### Parameters

subprocess | Self |
result | Result |
stdout_buf | Return location for stdout data. | [out]
stderr_buf | Return location for stderr data. | [out]
error | Error |

### g_subprocess_communicate_utf8 ()

    gboolean
    g_subprocess_communicate_utf8 (GSubprocess *subprocess,
                                   const char *stdin_buf,
                                   GCancellable *cancellable,
                                   char **stdout_buf,
                                   char **stderr_buf,
                                   GError **error);

Like `g_subprocess_communicate()`, but validates the output of the process as UTF-8, and returns it as a regular NUL terminated string.

#### Parameters

subprocess | a GSubprocess |
stdin_buf | data to send to the stdin of the subprocess, or `NULL`. | [allow-none]
cancellable | a GCancellable |
stdout_buf | data read from the subprocess stdout. | [out]
stderr_buf | data read from the subprocess stderr. | [out]
error | a pointer to a `NULL` GError pointer, or `NULL` |

### g_subprocess_communicate_utf8_async ()

    void
    g_subprocess_communicate_utf8_async (GSubprocess *subprocess,
                                         const char *stdin_buf,
                                         GCancellable *cancellable,
                                         GAsyncReadyCallback callback,
                                         gpointer user_data);

Asynchronous version of `g_subprocess_communicate_utf()`. Complete invocation with `g_subprocess_communicate_utf8_finish()`.

#### Parameters

subprocess | Self |
stdin_buf | Input data, or `NULL`. | [allow-none]
cancellable | Cancellable |
callback | Callback |
user_data | User data |

### g_subprocess_communicate_utf8_finish ()

    gboolean
    g_subprocess_communicate_utf8_finish (GSubprocess *subprocess,
                                          GAsyncResult *result,
                                          char **stdout_buf,
                                          char **stderr_buf,
                                          GError **error);

Complete an invocation of `g_subprocess_communicate_utf8_async()`.

#### Parameters

subprocess | Self |
result | Result |
stdout_buf | Return location for stdout data. | [out]
stderr_buf | Return location for stderr data. | [out]
error | Error |

## Types and Values

### GSubprocess

    typedef struct _GSubprocess GSubprocess;

A child process.

Since 2.40

### enum GSubprocessFlags

Flags to define the behaviour of a GSubprocess.

Note that the default for stdin is to redirect from /dev/null. For stdout and stderr the default are for them to inherit the corresponding descriptor from the calling process.

Note that it is a programmer error to mix 'incompatible' flags. For example, you may not request both `G_SUBPROCESS_FLAGS_STDOUT_PIPE` and `G_SUBPROCESS_FLAGS_STDOUT_SILENCE`.

#### Members

G_SUBPROCESS_FLAGS_NONE | No flags. |
G_SUBPROCESS_FLAGS_STDIN_PIPE | create a pipe for the stdin of the spawned process that can be accessed with `g_subprocess_get_stdin_pipe()`. |
G_SUBPROCESS_FLAGS_STDIN_INHERIT | stdin is inherited from the calling process. |
G_SUBPROCESS_FLAGS_STDOUT_PIPE | create a pipe for the stdout of the spawned process that can be accessed with `g_subprocess_get_stdout_pipe()`. |
G_SUBPROCESS_FLAGS_STDOUT_SILENCE | silence the stdout of the spawned process (ie: redirect to /dev/null). |
G_SUBPROCESS_FLAGS_STDERR_PIPE | create a pipe for the stderr of the spawned process that can be accessed with `g_subprocess_get_stderr_pipe()`. |
G_SUBPROCESS_FLAGS_STDERR_SILENCE | silence the stderr of the spawned process (ie: redirect to /dev/null). |
G_SUBPROCESS_FLAGS_STDERR_MERGE | merge the stderr of the spawned process with whatever the stdout happens to be. This is a good way of directing both streams to a common log file, for example. |
G_SUBPROCESS_FLAGS_INHERIT_FDS | spawned processes will inherit the file descriptors of their parent, unless those descriptors have been explicitly marked as close-on-exec. This flag has no effect over the "standard" file descriptors (stdin, stdout, stderr). |

Since 2.40

## Property Details

### The `“argv”` property

      “argv”                     GStrv

Argument vector.

Flags: Write / Construct Only

### The `“flags”` property

      “flags”                    GSubprocessFlags

Subprocess flags.

Flags: Write / Construct Only

## See Also

GSubprocessLauncher