From 74de872bb95e335f46ecd6be8cfc8fa2cb242f60 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Wed, 22 Nov 2023 23:59:15 +0000 Subject: [PATCH] docs: Move the spawn SECTION Move it to a separate page. Signed-off-by: Philip Withnall Helps: #3037 --- docs/reference/glib/glib.toml.in | 1 + docs/reference/glib/meson.build | 1 + docs/reference/glib/spawn.md | 76 ++++++++++++++++++++++++++++++++ glib/gspawn.c | 61 ------------------------- 4 files changed, 78 insertions(+), 61 deletions(-) create mode 100644 docs/reference/glib/spawn.md diff --git a/docs/reference/glib/glib.toml.in b/docs/reference/glib/glib.toml.in index 2df7eb78b..2a97d54bd 100644 --- a/docs/reference/glib/glib.toml.in +++ b/docs/reference/glib/glib.toml.in @@ -68,6 +68,7 @@ content_files = [ "testing.md", "atomic.md", "threads.md", + "spawn.md", "random.md", "markup.md", "base64.md", diff --git a/docs/reference/glib/meson.build b/docs/reference/glib/meson.build index 9783c9697..d39a65bf4 100644 --- a/docs/reference/glib/meson.build +++ b/docs/reference/glib/meson.build @@ -171,6 +171,7 @@ expand_content_files = [ 'host-utils.md', 'data-structures.md', 'shell.md', + 'spawn.md', 'string-utils.md', 'unicode.md', 'uuid.md', diff --git a/docs/reference/glib/spawn.md b/docs/reference/glib/spawn.md new file mode 100644 index 000000000..f45c276e4 --- /dev/null +++ b/docs/reference/glib/spawn.md @@ -0,0 +1,76 @@ +Title: Spawning Processes +SPDX-License-Identifier: LGPL-2.1-or-later +SPDX-FileCopyrightText: 2014 Red Hat, Inc. +SPDX-FileCopyrightText: 2017 Philip Withnall + +# Spawning Processes + +GLib supports spawning of processes with an API that is more +convenient than the bare UNIX [`fork()`](man:fork(2)) and +[`exec()`](man:exec(3)). + +The `g_spawn_…()` family of functions has synchronous ([func@GLib.spawn_sync]) +and asynchronous variants ([func@GLib.spawn_async], +[func@GLib.spawn_async_with_pipes]), as well as convenience variants that take a +complete shell-like command line ([func@GLib.spawn_command_line_sync], +[func@GLib.spawn_command_line_async]). + +See [class@Gio.Subprocess] in GIO for a higher-level API that provides +stream interfaces for communication with child processes. + +An example of using [func@GLib.spawn_async_with_pipes]: +```c +const gchar * const argv[] = { "my-favourite-program", "--args", NULL }; +gint child_stdout, child_stderr; +GPid child_pid; +g_autoptr(GError) error = NULL; + +// Spawn child process. +g_spawn_async_with_pipes (NULL, argv, NULL, G_SPAWN_DO_NOT_REAP_CHILD, NULL, + NULL, &child_pid, NULL, &child_stdout, + &child_stderr, &error); +if (error != NULL) + { + g_error ("Spawning child failed: %s", error->message); + return; + } + +// Add a child watch function which will be called when the child process +// exits. +g_child_watch_add (child_pid, child_watch_cb, NULL); + +// You could watch for output on @child_stdout and @child_stderr using +// #GUnixInputStream or #GIOChannel here. + +static void +child_watch_cb (GPid pid, + gint status, + gpointer user_data) +{ + g_message ("Child %" G_PID_FORMAT " exited %s", pid, + g_spawn_check_wait_status (status, NULL) ? "normally" : "abnormally"); + + // Free any resources associated with the child here, such as I/O channels + // on its stdout and stderr FDs. If you have no code to put in the + // child_watch_cb() callback, you can remove it and the g_child_watch_add() + // call, but you must also remove the G_SPAWN_DO_NOT_REAP_CHILD flag, + // otherwise the child process will stay around as a zombie until this + // process exits. + + g_spawn_close_pid (pid); +} +``` + +## Spawn Functions + + * [func@GLib.spawn_async_with_fds] + * [func@GLib.spawn_async_with_pipes] + * [func@GLib.spawn_async_with_pipes_and_fds] + * [func@GLib.spawn_async] + * [func@GLib.spawn_sync] + * [func@GLib.spawn_check_wait_status] + * [func@GLib.spawn_check_exit_status] + * [func@GLib.spawn_command_line_async] + * [func@GLib.spawn_command_line_sync] + * [func@GLib.spawn_close_pid] + diff --git a/glib/gspawn.c b/glib/gspawn.c index ef69e4948..0720cc3b7 100644 --- a/glib/gspawn.c +++ b/glib/gspawn.c @@ -110,67 +110,6 @@ extern char **environ; #define HAVE_O_CLOEXEC 1 #endif -/** - * SECTION:spawn - * @Short_description: process launching - * @Title: Spawning Processes - * - * GLib supports spawning of processes with an API that is more - * convenient than the bare UNIX fork() and exec(). - * - * The g_spawn family of functions has synchronous (g_spawn_sync()) - * and asynchronous variants (g_spawn_async(), g_spawn_async_with_pipes()), - * as well as convenience variants that take a complete shell-like - * commandline (g_spawn_command_line_sync(), g_spawn_command_line_async()). - * - * See #GSubprocess in GIO for a higher-level API that provides - * stream interfaces for communication with child processes. - * - * An example of using g_spawn_async_with_pipes(): - * |[ - * const gchar * const argv[] = { "my-favourite-program", "--args", NULL }; - * gint child_stdout, child_stderr; - * GPid child_pid; - * g_autoptr(GError) error = NULL; - * - * // Spawn child process. - * g_spawn_async_with_pipes (NULL, argv, NULL, G_SPAWN_DO_NOT_REAP_CHILD, NULL, - * NULL, &child_pid, NULL, &child_stdout, - * &child_stderr, &error); - * if (error != NULL) - * { - * g_error ("Spawning child failed: %s", error->message); - * return; - * } - * - * // Add a child watch function which will be called when the child process - * // exits. - * g_child_watch_add (child_pid, child_watch_cb, NULL); - * - * // You could watch for output on @child_stdout and @child_stderr using - * // #GUnixInputStream or #GIOChannel here. - * - * static void - * child_watch_cb (GPid pid, - * gint status, - * gpointer user_data) - * { - * g_message ("Child %" G_PID_FORMAT " exited %s", pid, - * g_spawn_check_wait_status (status, NULL) ? "normally" : "abnormally"); - * - * // Free any resources associated with the child here, such as I/O channels - * // on its stdout and stderr FDs. If you have no code to put in the - * // child_watch_cb() callback, you can remove it and the g_child_watch_add() - * // call, but you must also remove the G_SPAWN_DO_NOT_REAP_CHILD flag, - * // otherwise the child process will stay around as a zombie until this - * // process exits. - * - * g_spawn_close_pid (pid); - * } - * ]| - */ - - static gint g_execute (const gchar *file, gchar **argv, gchar **argv_buffer,