luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-08-23 17:38:54 +02:00
Code Issues Packages Projects Releases Wiki Activity

Move documentation to inline comments: spawn

Browse Source
This commit is contained in:
Javier Jardón
2011-07-06 22:13:05 +01:00
parent 0e27a71899
commit c2dc66ccf2
5 changed files with 104 additions and 198 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
docs/reference/glib/tmpl/.gitignore vendored
View File

@@ -34,6 +34,7 @@ random_numbers.sgml
relations.sgml relations.sgml
sequence.sgml sequence.sgml
shell.sgml shell.sgml
spawn.sgml
string_chunks.sgml string_chunks.sgml
thread_pools.sgml thread_pools.sgml
threads.sgml threads.sgml

198
docs/reference/glib/tmpl/spawn.sgml
View File

@@ -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-&gt;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:

9
glib/gspawn.c
View File

@@ -51,6 +51,15 @@
#include "gutils.h" #include "gutils.h"
#include "glibintl.h" #include "glibintl.h"
/**
* SECTION:spawn
* @Short_description: process launching
* @Title: Spawning Processes
*/
static gint g_execute (const gchar *file, static gint g_execute (const gchar *file,
gchar **argv, gchar **argv,
gchar **envp, gchar **envp,

82
glib/gspawn.h
View File

@@ -29,9 +29,43 @@
G_BEGIN_DECLS G_BEGIN_DECLS
/* I'm not sure I remember our proposed naming convention here. */ /* 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 () #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-&gt;message</literal> should explain.
*
* Error codes returned by spawning processes.
*/
typedef enum typedef enum
{ {
G_SPAWN_ERROR_FORK, /* fork failed due to lack of memory */ G_SPAWN_ERROR_FORK, /* fork failed due to lack of memory */
@@ -58,8 +92,56 @@ typedef enum
*/ */
} GSpawnError; } 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); 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 typedef enum
{ {
G_SPAWN_LEAVE_DESCRIPTORS_OPEN = 1 << 0, G_SPAWN_LEAVE_DESCRIPTORS_OPEN = 1 << 0,

12
glib/gstring.h
View File

@@ -40,6 +40,18 @@ G_BEGIN_DECLS
typedef struct _GString GString; typedef struct _GString GString;
typedef struct _GStringChunk GStringChunk; 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 struct _GString
{ {
gchar *str; gchar *str;