luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-01-11 23:16:14 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: Move the GSubprocess SECTION

Browse Source 
Move it to the struct docs.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3037
This commit is contained in:
Philip Withnall 2023-11-14 14:27:01 +00:00
parent 7f6a126f39
commit b480a733c0
2 changed files with 25 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
gio/giotypes.h
View File

@ -625,13 +625,6 @@ typedef GType (*GDBusProxyTypeFunc) (GDBusObjectManagerClient *manager,
typedef struct _GTestDBus GTestDBus;
/**
* GSubprocess:
*
* A child process.
*
* Since: 2.40
*/
typedef struct _GSubprocess GSubprocess;
/**
* GSubprocessLauncher:

54
gio/gsubprocess.c
View File

@ -17,18 +17,14 @@
*/
/**
* SECTION:gsubprocess
* @title: GSubprocess
* @short_description: Child processes
* @include: gio/gio.h
* @see_also: #GSubprocessLauncher
* GSubprocess:
*
* #GSubprocess allows the creation of and interaction with child
* `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
* [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
@ -36,50 +32,50 @@
*
* 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
* [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
* 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
* 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
* `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
* `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,
* `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
* 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
* 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
* `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:
* `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
* 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
* 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).
* 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).
*
* Since: 2.40
**/