mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2025-01-12 07:26:15 +01:00
Move documentation to inline comments: spawn
This commit is contained in:
Javier Jardón
parent
0e27a71899
commit
c2dc66ccf2
1
docs/reference/glib/tmpl/.gitignore
vendored
1
docs/reference/glib/tmpl/.gitignore
vendored
@ -34,6 +34,7 @@ random_numbers.sgml
|
||||
relations.sgml
|
||||
sequence.sgml
|
||||
shell.sgml
|
||||
spawn.sgml
|
||||
string_chunks.sgml
|
||||
thread_pools.sgml
|
||||
threads.sgml
|
||||
|
||||
@ -1,198 +0,0 @@
|
||||
<!-- ##### SECTION Title ##### -->
|
||||
Spawning Processes
|
||||
|
||||
<!-- ##### SECTION Short_Description ##### -->
|
||||
process launching
|
||||
|
||||
<!-- ##### SECTION Long_Description ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
<!-- ##### SECTION See_Also ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
<!-- ##### SECTION Stability_Level ##### -->
|
||||
|
||||
|
||||
<!-- ##### SECTION Image ##### -->
|
||||
|
||||
|
||||
<!-- ##### ENUM GSpawnError ##### -->
|
||||
<para>
|
||||
Error codes returned by spawning processes.
|
||||
</para>
|
||||
|
||||
@G_SPAWN_ERROR_FORK: Fork failed due to lack of memory.
|
||||
@G_SPAWN_ERROR_READ: Read or select on pipes failed.
|
||||
@G_SPAWN_ERROR_CHDIR: Changing to working directory failed.
|
||||
@G_SPAWN_ERROR_ACCES: execv() returned %EACCES.
|
||||
@G_SPAWN_ERROR_PERM: execv() returned %EPERM.
|
||||
@G_SPAWN_ERROR_2BIG: execv() returned %E2BIG.
|
||||
@G_SPAWN_ERROR_NOEXEC: execv() returned %ENOEXEC.
|
||||
@G_SPAWN_ERROR_NAMETOOLONG: execv() returned %ENAMETOOLONG.
|
||||
@G_SPAWN_ERROR_NOENT: execv() returned %ENOENT.
|
||||
@G_SPAWN_ERROR_NOMEM: execv() returned %ENOMEM.
|
||||
@G_SPAWN_ERROR_NOTDIR: execv() returned %ENOTDIR.
|
||||
@G_SPAWN_ERROR_LOOP: execv() returned %ELOOP.
|
||||
@G_SPAWN_ERROR_TXTBUSY: execv() returned %ETXTBUSY.
|
||||
@G_SPAWN_ERROR_IO: execv() returned %EIO.
|
||||
@G_SPAWN_ERROR_NFILE: execv() returned %ENFILE.
|
||||
@G_SPAWN_ERROR_MFILE: execv() returned %EMFILE.
|
||||
@G_SPAWN_ERROR_INVAL: execv() returned %EINVAL.
|
||||
@G_SPAWN_ERROR_ISDIR: execv() returned %EISDIR.
|
||||
@G_SPAWN_ERROR_LIBBAD: execv() returned %ELIBBAD.
|
||||
@G_SPAWN_ERROR_FAILED: Some other fatal failure, <literal>error->message</literal> should explain.
|
||||
|
||||
<!-- ##### MACRO G_SPAWN_ERROR ##### -->
|
||||
<para>
|
||||
Error domain for spawning processes. Errors in this domain will
|
||||
be from the #GSpawnError enumeration. See #GError for information on
|
||||
error domains.
|
||||
</para>
|
||||
|
||||
|
||||
|
||||
<!-- ##### ENUM GSpawnFlags ##### -->
|
||||
<para>
|
||||
Flags passed to g_spawn_sync(), g_spawn_async() and g_spawn_async_with_pipes().
|
||||
</para>
|
||||
|
||||
@G_SPAWN_LEAVE_DESCRIPTORS_OPEN: the parent's open file descriptors will be
|
||||
inherited by the child; otherwise all descriptors except stdin/stdout/stderr
|
||||
will be closed before calling exec() in the child.
|
||||
@G_SPAWN_DO_NOT_REAP_CHILD: the child will not be automatically reaped; you
|
||||
must use g_child_watch_add() yourself (or call waitpid()
|
||||
or handle <literal>SIGCHLD</literal> yourself), or the child will become a zombie.
|
||||
@G_SPAWN_SEARCH_PATH: <literal>argv[0]</literal> need not be an absolute path,
|
||||
it will be looked for in the user's <envar>PATH</envar>.
|
||||
@G_SPAWN_STDOUT_TO_DEV_NULL: the child's standard output will be discarded,
|
||||
instead of going to the same location as the parent's standard output.
|
||||
@G_SPAWN_STDERR_TO_DEV_NULL: the child's standard error will be discarded.
|
||||
@G_SPAWN_CHILD_INHERITS_STDIN: the child will inherit the parent's standard
|
||||
input (by default, the child's standard input is attached to
|
||||
<filename>/dev/null</filename>).
|
||||
@G_SPAWN_FILE_AND_ARGV_ZERO: the first element of <literal>argv</literal> is
|
||||
the file to execute, while the remaining elements are the actual argument
|
||||
vector to pass to the file. Normally g_spawn_async_with_pipes() uses
|
||||
<literal>argv[0]</literal> as the file to execute, and passes all of
|
||||
<literal>argv</literal> to the child.
|
||||
|
||||
<!-- ##### USER_FUNCTION GSpawnChildSetupFunc ##### -->
|
||||
<para>
|
||||
Specifies the type of the setup function passed to g_spawn_async(),
|
||||
g_spawn_sync() and g_spawn_async_with_pipes(). On POSIX platforms it
|
||||
is called in the child after GLib has performed all the setup it plans
|
||||
to perform but before calling exec(). On POSIX actions taken in this
|
||||
function will thus only affect the child, not the parent.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Note that POSIX allows only async-signal-safe functions (see signal(7))
|
||||
to be called in the child between fork() and exec(), which drastically
|
||||
limits the usefulness of child setup functions.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Also note that modifying the environment from the child setup function
|
||||
may not have the intended effect, since it will get overridden by
|
||||
a non-%NULL @env argument to the <literal>g_spawn...</literal> functions.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
On Windows the function is called in the parent. Its usefulness on
|
||||
Windows is thus questionable. In many cases executing the child setup
|
||||
function in the parent can have ill effects, and you should be very
|
||||
careful when porting software to Windows that uses child setup
|
||||
functions.
|
||||
</para>
|
||||
|
||||
@user_data: user data to pass to the function.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_spawn_async_with_pipes ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@working_directory:
|
||||
@argv:
|
||||
@envp:
|
||||
@flags:
|
||||
@child_setup:
|
||||
@user_data:
|
||||
@child_pid:
|
||||
@standard_input:
|
||||
@standard_output:
|
||||
@standard_error:
|
||||
@error:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_spawn_async ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@working_directory:
|
||||
@argv:
|
||||
@envp:
|
||||
@flags:
|
||||
@child_setup:
|
||||
@user_data:
|
||||
@child_pid:
|
||||
@error:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_spawn_sync ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@working_directory:
|
||||
@argv:
|
||||
@envp:
|
||||
@flags:
|
||||
@child_setup:
|
||||
@user_data:
|
||||
@standard_output:
|
||||
@standard_error:
|
||||
@exit_status:
|
||||
@error:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_spawn_command_line_async ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@command_line:
|
||||
@error:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_spawn_command_line_sync ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@command_line:
|
||||
@standard_output:
|
||||
@standard_error:
|
||||
@exit_status:
|
||||
@error:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_spawn_close_pid ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@pid:
|
||||
|
||||
|
||||
@ -51,6 +51,15 @@
|
||||
#include "gutils.h"
|
||||
#include "glibintl.h"
|
||||
|
||||
|
||||
/**
|
||||
* SECTION:spawn
|
||||
* @Short_description: process launching
|
||||
* @Title: Spawning Processes
|
||||
*/
|
||||
|
||||
|
||||
|
||||
static gint g_execute (const gchar *file,
|
||||
gchar **argv,
|
||||
gchar **envp,
|
||||
|
||||
@ -29,9 +29,43 @@
|
||||
|
||||
G_BEGIN_DECLS
|
||||
|
||||
|
||||
/* I'm not sure I remember our proposed naming convention here. */
|
||||
/**
|
||||
* G_SPAWN_ERROR:
|
||||
*
|
||||
* Error domain for spawning processes. Errors in this domain will
|
||||
* be from the #GSpawnError enumeration. See #GError for information on
|
||||
* error domains.
|
||||
*/
|
||||
#define G_SPAWN_ERROR g_spawn_error_quark ()
|
||||
|
||||
/**
|
||||
* GSpawnError:
|
||||
* @G_SPAWN_ERROR_FORK: Fork failed due to lack of memory.
|
||||
* @G_SPAWN_ERROR_READ: Read or select on pipes failed.
|
||||
* @G_SPAWN_ERROR_CHDIR: Changing to working directory failed.
|
||||
* @G_SPAWN_ERROR_ACCES: execv() returned %EACCES.
|
||||
* @G_SPAWN_ERROR_PERM: execv() returned %EPERM.
|
||||
* @G_SPAWN_ERROR_2BIG: execv() returned %E2BIG.
|
||||
* @G_SPAWN_ERROR_NOEXEC: execv() returned %ENOEXEC.
|
||||
* @G_SPAWN_ERROR_NAMETOOLONG: execv() returned %ENAMETOOLONG.
|
||||
* @G_SPAWN_ERROR_NOENT: execv() returned %ENOENT.
|
||||
* @G_SPAWN_ERROR_NOMEM: execv() returned %ENOMEM.
|
||||
* @G_SPAWN_ERROR_NOTDIR: execv() returned %ENOTDIR.
|
||||
* @G_SPAWN_ERROR_LOOP: execv() returned %ELOOP.
|
||||
* @G_SPAWN_ERROR_TXTBUSY: execv() returned %ETXTBUSY.
|
||||
* @G_SPAWN_ERROR_IO: execv() returned %EIO.
|
||||
* @G_SPAWN_ERROR_NFILE: execv() returned %ENFILE.
|
||||
* @G_SPAWN_ERROR_MFILE: execv() returned %EMFILE.
|
||||
* @G_SPAWN_ERROR_INVAL: execv() returned %EINVAL.
|
||||
* @G_SPAWN_ERROR_ISDIR: execv() returned %EISDIR.
|
||||
* @G_SPAWN_ERROR_LIBBAD: execv() returned %ELIBBAD.
|
||||
* @G_SPAWN_ERROR_FAILED: Some other fatal failure,
|
||||
* <literal>error->message</literal> should explain.
|
||||
*
|
||||
* Error codes returned by spawning processes.
|
||||
*/
|
||||
typedef enum
|
||||
{
|
||||
G_SPAWN_ERROR_FORK, /* fork failed due to lack of memory */
|
||||
@ -58,8 +92,56 @@ typedef enum
|
||||
*/
|
||||
} GSpawnError;
|
||||
|
||||
/**
|
||||
* GSpawnChildSetupFunc:
|
||||
* @user_data: user data to pass to the function.
|
||||
*
|
||||
* Specifies the type of the setup function passed to g_spawn_async(),
|
||||
* g_spawn_sync() and g_spawn_async_with_pipes(). On POSIX platforms it
|
||||
* is called in the child after GLib has performed all the setup it plans
|
||||
* to perform but before calling exec(). On POSIX actions taken in this
|
||||
* function will thus only affect the child, not the parent.
|
||||
*
|
||||
* Note that POSIX allows only async-signal-safe functions (see signal(7))
|
||||
* to be called in the child between fork() and exec(), which drastically
|
||||
* limits the usefulness of child setup functions.
|
||||
*
|
||||
* Also note that modifying the environment from the child setup function
|
||||
* may not have the intended effect, since it will get overridden by
|
||||
* a non-%NULL @env argument to the <literal>g_spawn...</literal> functions.
|
||||
*
|
||||
* On Windows the function is called in the parent. Its usefulness on
|
||||
* Windows is thus questionable. In many cases executing the child setup
|
||||
* function in the parent can have ill effects, and you should be very
|
||||
* careful when porting software to Windows that uses child setup
|
||||
* functions.
|
||||
*/
|
||||
typedef void (* GSpawnChildSetupFunc) (gpointer user_data);
|
||||
|
||||
/**
|
||||
* GSpawnFlags:
|
||||
* @G_SPAWN_LEAVE_DESCRIPTORS_OPEN: the parent's open file descriptors will be
|
||||
* inherited by the child; otherwise all descriptors except stdin/stdout/stderr
|
||||
* will be closed before calling exec() in the child.
|
||||
* @G_SPAWN_DO_NOT_REAP_CHILD: the child will not be automatically reaped; you
|
||||
* must use g_child_watch_add() yourself (or call waitpid()
|
||||
* or handle <literal>SIGCHLD</literal> yourself), or the child will become a zombie.
|
||||
* @G_SPAWN_SEARCH_PATH: <literal>argv[0]</literal> need not be an absolute path,
|
||||
* it will be looked for in the user's <envar>PATH</envar>.
|
||||
* @G_SPAWN_STDOUT_TO_DEV_NULL: the child's standard output will be discarded,
|
||||
* instead of going to the same location as the parent's standard output.
|
||||
* @G_SPAWN_STDERR_TO_DEV_NULL: the child's standard error will be discarded.
|
||||
* @G_SPAWN_CHILD_INHERITS_STDIN: the child will inherit the parent's standard
|
||||
* input (by default, the child's standard input is attached to
|
||||
* <filename>/dev/null</filename>).
|
||||
* @G_SPAWN_FILE_AND_ARGV_ZERO: the first element of <literal>argv</literal> is
|
||||
* the file to execute, while the remaining elements are the actual argument
|
||||
* vector to pass to the file. Normally g_spawn_async_with_pipes() uses
|
||||
* <literal>argv[0]</literal> as the file to execute, and passes all of
|
||||
* <literal>argv</literal> to the child.
|
||||
*
|
||||
* Flags passed to g_spawn_sync(), g_spawn_async() and g_spawn_async_with_pipes().
|
||||
*/
|
||||
typedef enum
|
||||
{
|
||||
G_SPAWN_LEAVE_DESCRIPTORS_OPEN = 1 << 0,
|
||||
|
||||
@ -40,6 +40,18 @@ G_BEGIN_DECLS
|
||||
typedef struct _GString GString;
|
||||
typedef struct _GStringChunk GStringChunk;
|
||||
|
||||
/**
|
||||
* GString:
|
||||
* @str: points to the character data. It may move as text is added.
|
||||
* The @str field is null-terminated and so
|
||||
* can be used as an ordinary C string.
|
||||
* @len: contains the length of the string, not including the
|
||||
* terminating nul byte.
|
||||
* @allocated_len: the number of bytes that can be stored in the
|
||||
* string before it needs to be reallocated. May be larger than @len.
|
||||
*
|
||||
* The #GString struct contains the public fields of a #GString.
|
||||
*/
|
||||
struct _GString
|
||||
{
|
||||
gchar *str;
|
||||
|
||||
Loading…
Reference in New Issue
Block a user