:right-sidebar: True

Subprocess
===================================================================

.. currentmodule:: gi.repository.Gio


.. versionadded:: 2.40




.. class:: Subprocess(**properties: ~typing.Any)
   :no-contents-entry:


Superclasses: :class:`~gi.repository.GObject.Object`



Implemented Interfaces: :class:`~gi.repository.Gio.Initable`



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

Processes can be communicated with using standard GIO-style APIs (ie:
:obj:`~gi.repository.Gio.InputStream`\, :obj:`~gi.repository.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
:obj:`~gi.repository.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 :obj:`~gi.repository.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.  :obj:`~gi.repository.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 :obj:`~gi.repository.Gio.Subprocess.new`\. The
:obj:`~gi.repository.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
:obj:`~gi.repository.Gio.Subprocess.new`\, followed by :obj:`~gi.repository.Gio.Subprocess.wait_async` or
:obj:`~gi.repository.Gio.Subprocess.wait`\.  After the process exits, the status can be
checked using functions such as :obj:`~gi.repository.Gio.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.


Constructors
------------

.. rst-class:: interim-class

.. class:: Subprocess
   :no-index:


   .. classmethod:: new(argv: list[str], flags: ~gi.repository.Gio.SubprocessFlags) -> ~gi.repository.Gio.Subprocess

      Create a new process with the given flags and varargs argument
      list.  By default, matching the :func:`~gi.repository.GLib.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 :const:`None`.


      .. versionadded:: 2.40





      :param argv: 

      :param flags: flags that define the behaviour of the subprocess








Methods
-------

.. rst-class:: interim-class

.. class:: Subprocess
   :no-index:


   .. method:: communicate(stdin_buf: ~gi.repository.GLib.Bytes | None = None, cancellable: ~gi.repository.Gio.Cancellable | None = None) -> ~typing.Tuple[bool, ~gi.repository.GLib.Bytes | None, ~gi.repository.GLib.Bytes | None]

      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
      :const:`~gi.repository.Gio.SubprocessFlags.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 :const:`~gi.repository.Gio.SubprocessFlags.STDOUT_PIPE` or
      :const:`~gi.repository.Gio.SubprocessFlags.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 :const:`~gi.repository.Gio.SubprocessFlags.STDOUT_PIPE`,
      ``stdout_buf`` will contain the data read from stdout.  Otherwise, for
      subprocesses not created with :const:`~gi.repository.Gio.SubprocessFlags.STDOUT_PIPE`,
      ``stdout_buf`` will be set to :const:`None`.  Similar provisions apply to
      ``stderr_buf`` and :const:`~gi.repository.Gio.SubprocessFlags.STDERR_PIPE`.

      As usual, any output variable may be given as :const:`None` to ignore it.

      If you desire the stdout and stderr data to be interleaved, create
      the subprocess with :const:`~gi.repository.Gio.SubprocessFlags.STDOUT_PIPE` and
      :const:`~gi.repository.Gio.SubprocessFlags.STDERR_MERGE`.  The merged result will be returned
      in ``stdout_buf`` and ``stderr_buf`` will be set to :const:`None`.

      In case of any error (including cancellation), :const:`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 :const:`True` is returned, the subprocess has exited and the
      exit status inspection APIs (eg: :func:`~gi.repository.Gio.Subprocess.get_if_exited`,
      :func:`~gi.repository.Gio.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).


      .. versionadded:: 2.40





      :param stdin_buf: data to send to the stdin of the subprocess, or :const:`None`

      :param cancellable: a :obj:`~gi.repository.Gio.Cancellable`




   .. method:: communicate_async(stdin_buf: ~gi.repository.GLib.Bytes | None = None, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> None

      Asynchronous version of :func:`~gi.repository.Gio.Subprocess.communicate`.  Complete
      invocation with :func:`~gi.repository.Gio.Subprocess.communicate_finish`.






      :param stdin_buf: Input data, or :const:`None`

      :param cancellable: Cancellable

      :param callback: Callback

      :param user_data: User data




   .. method:: communicate_finish(result: ~gi.repository.Gio.AsyncResult) -> ~typing.Tuple[bool, ~gi.repository.GLib.Bytes | None, ~gi.repository.GLib.Bytes | None]

      Complete an invocation of :func:`~gi.repository.Gio.Subprocess.communicate_async`.






      :param result: Result




   .. method:: communicate_utf8(stdin_buf: str | None = None, cancellable: ~gi.repository.Gio.Cancellable | None = None) -> ~typing.Tuple[bool, str | None, str | None]

      Like :func:`~gi.repository.Gio.Subprocess.communicate`, but validates the output of the
      process as UTF-8, and returns it as a regular NUL terminated string.

      On error, ``stdout_buf`` and ``stderr_buf`` will be set to undefined values and
      should not be used.






      :param stdin_buf: data to send to the stdin of the subprocess, or :const:`None`

      :param cancellable: a :obj:`~gi.repository.Gio.Cancellable`




   .. method:: communicate_utf8_async(stdin_buf: str | None = None, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> None

      Asynchronous version of :func:`~gi.repository.Gio.Subprocess.communicate_utf8`.  Complete
      invocation with :func:`~gi.repository.Gio.Subprocess.communicate_utf8_finish`.






      :param stdin_buf: Input data, or :const:`None`

      :param cancellable: Cancellable

      :param callback: Callback

      :param user_data: User data




   .. method:: communicate_utf8_finish(result: ~gi.repository.Gio.AsyncResult) -> ~typing.Tuple[bool, str | None, str | None]

      Complete an invocation of :func:`~gi.repository.Gio.Subprocess.communicate_utf8_async`.






      :param result: Result




   .. method:: force_exit() -> None

      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 :func:`~gi.repository.Gio.Subprocess.wait` to monitor the status of
      the process after calling this function.

      On Unix, this function sends %SIGKILL.


      .. versionadded:: 2.40








   .. method:: get_exit_status() -> int

      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 :func:`~gi.repository.Gio.Subprocess.wait` and
      unless :func:`~gi.repository.Gio.Subprocess.get_if_exited` returned :const:`True`.


      .. versionadded:: 2.40








   .. method:: get_identifier() -> str | None

      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 :const:`None`.


      .. versionadded:: 2.40








   .. method:: get_if_exited() -> bool

      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 :func:`~gi.repository.Gio.Subprocess.wait` has
      returned.


      .. versionadded:: 2.40








   .. method:: get_if_signaled() -> bool

      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 :func:`~gi.repository.Gio.Subprocess.wait` has
      returned.


      .. versionadded:: 2.40








   .. method:: get_status() -> int

      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 :func:`~gi.repository.GLib.spawn_check_wait_status`.

      It is more likely that you want to use :func:`~gi.repository.Gio.Subprocess.get_if_exited`
      followed by :func:`~gi.repository.Gio.Subprocess.get_exit_status`.

      It is an error to call this function before :func:`~gi.repository.Gio.Subprocess.wait` has
      returned.


      .. versionadded:: 2.40








   .. method:: get_stderr_pipe() -> ~gi.repository.Gio.InputStream | None

      Gets the :obj:`~gi.repository.Gio.InputStream` from which to read the stderr output of
      ``subprocess``\.

      The process must have been created with :const:`~gi.repository.Gio.SubprocessFlags.STDERR_PIPE`,
      otherwise :const:`None` will be returned.


      .. versionadded:: 2.40








   .. method:: get_stdin_pipe() -> ~gi.repository.Gio.OutputStream | None

      Gets the :obj:`~gi.repository.Gio.OutputStream` that you can write to in order to give data
      to the stdin of ``subprocess``\.

      The process must have been created with :const:`~gi.repository.Gio.SubprocessFlags.STDIN_PIPE` and
      not :const:`~gi.repository.Gio.SubprocessFlags.STDIN_INHERIT`, otherwise :const:`None` will be returned.


      .. versionadded:: 2.40








   .. method:: get_stdout_pipe() -> ~gi.repository.Gio.InputStream | None

      Gets the :obj:`~gi.repository.Gio.InputStream` from which to read the stdout output of
      ``subprocess``\.

      The process must have been created with :const:`~gi.repository.Gio.SubprocessFlags.STDOUT_PIPE`,
      otherwise :const:`None` will be returned.


      .. versionadded:: 2.40








   .. method:: get_successful() -> bool

      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 :func:`~gi.repository.Gio.Subprocess.wait` has
      returned.


      .. versionadded:: 2.40








   .. method:: get_term_sig() -> int

      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 :func:`~gi.repository.Gio.Subprocess.wait` and
      unless :func:`~gi.repository.Gio.Subprocess.get_if_signaled` returned :const:`True`.


      .. versionadded:: 2.40








   .. method:: send_signal(signal_num: int) -> None

      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.


      .. versionadded:: 2.40





      :param signal_num: the signal number to send




   .. method:: wait(cancellable: ~gi.repository.Gio.Cancellable | None = None) -> bool

      Synchronously wait for the subprocess to terminate.

      After the process terminates you can query its exit status with
      functions such as :func:`~gi.repository.Gio.Subprocess.get_if_exited` and
      :func:`~gi.repository.Gio.Subprocess.get_exit_status`.

      This function does not fail in the case of the subprocess having
      abnormal termination.  See :func:`~gi.repository.Gio.Subprocess.wait_check` for that.

      Cancelling ``cancellable`` doesn't kill the subprocess.  Call
      :func:`~gi.repository.Gio.Subprocess.force_exit` if it is desirable.


      .. versionadded:: 2.40





      :param cancellable: a :obj:`~gi.repository.Gio.Cancellable`




   .. method:: wait_async(cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> None

      Wait for the subprocess to terminate.

      This is the asynchronous version of :func:`~gi.repository.Gio.Subprocess.wait`.


      .. versionadded:: 2.40





      :param cancellable: a :obj:`~gi.repository.Gio.Cancellable`\, or :const:`None`

      :param callback: a :obj:`~gi.repository.Gio.AsyncReadyCallback` to call when the operation is complete

      :param user_data: user_data for ``callback``




   .. method:: wait_check(cancellable: ~gi.repository.Gio.Cancellable | None = None) -> bool

      Combines :func:`~gi.repository.Gio.Subprocess.wait` with :func:`~gi.repository.GLib.spawn_check_wait_status`.


      .. versionadded:: 2.40





      :param cancellable: a :obj:`~gi.repository.Gio.Cancellable`




   .. method:: wait_check_async(cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> None

      Combines :func:`~gi.repository.Gio.Subprocess.wait_async` with :func:`~gi.repository.GLib.spawn_check_wait_status`.

      This is the asynchronous version of :func:`~gi.repository.Gio.Subprocess.wait_check`.


      .. versionadded:: 2.40





      :param cancellable: a :obj:`~gi.repository.Gio.Cancellable`\, or :const:`None`

      :param callback: a :obj:`~gi.repository.Gio.AsyncReadyCallback` to call when the operation is complete

      :param user_data: user_data for ``callback``




   .. method:: wait_check_finish(result: ~gi.repository.Gio.AsyncResult) -> bool

      Collects the result of a previous call to
      :func:`~gi.repository.Gio.Subprocess.wait_check_async`.


      .. versionadded:: 2.40





      :param result: the :obj:`~gi.repository.Gio.AsyncResult` passed to your :obj:`~gi.repository.Gio.AsyncReadyCallback`




   .. method:: wait_finish(result: ~gi.repository.Gio.AsyncResult) -> bool

      Collects the result of a previous call to
      :func:`~gi.repository.Gio.Subprocess.wait_async`.


      .. versionadded:: 2.40





      :param result: the :obj:`~gi.repository.Gio.AsyncResult` passed to your :obj:`~gi.repository.Gio.AsyncReadyCallback`








Properties
----------

.. rst-class:: interim-class

.. class:: Subprocess
   :no-index:
   

   .. attribute:: props.argv
      :type: list[str]

      The type of the None singleton.



      .. versionadded:: 2.40





   .. attribute:: props.flags
      :type: ~gi.repository.Gio.SubprocessFlags

      The type of the None singleton.



      .. versionadded:: 2.40