From c2dc66ccf2719df9813b0ab97f22af166770f944 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Javier=20Jard=C3=B3n?= Date: Wed, 6 Jul 2011 22:13:05 +0100 Subject: [PATCH] Move documentation to inline comments: spawn --- docs/reference/glib/tmpl/.gitignore | 1 + docs/reference/glib/tmpl/spawn.sgml | 198 ------------------------------------ glib/gspawn.c | 9 ++ glib/gspawn.h | 82 +++++++++++++++ glib/gstring.h | 12 +++ 5 files changed, 104 insertions(+), 198 deletions(-) delete mode 100644 docs/reference/glib/tmpl/spawn.sgml diff --git a/docs/reference/glib/tmpl/.gitignore b/docs/reference/glib/tmpl/.gitignore index 69e1543..2d9b777 100644 --- a/docs/reference/glib/tmpl/.gitignore +++ b/docs/reference/glib/tmpl/.gitignore @@ -34,6 +34,7 @@ random_numbers.sgml relations.sgml sequence.sgml shell.sgml +spawn.sgml string_chunks.sgml thread_pools.sgml threads.sgml diff --git a/docs/reference/glib/tmpl/spawn.sgml b/docs/reference/glib/tmpl/spawn.sgml deleted file mode 100644 index baf085e..0000000 --- a/docs/reference/glib/tmpl/spawn.sgml +++ /dev/null @@ -1,198 +0,0 @@ - -Spawning Processes - - -process launching - - - - - - - - - - - - - - - - - - - -Error codes returned by spawning processes. - - -@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, error->message should explain. - - - -Error domain for spawning processes. Errors in this domain will -be from the #GSpawnError enumeration. See #GError for information on -error domains. - - - - - - -Flags passed to g_spawn_sync(), g_spawn_async() and g_spawn_async_with_pipes(). - - -@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 SIGCHLD yourself), or the child will become a zombie. -@G_SPAWN_SEARCH_PATH: argv[0] need not be an absolute path, - it will be looked for in the user's PATH. -@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 - /dev/null). -@G_SPAWN_FILE_AND_ARGV_ZERO: the first element of argv 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 - argv[0] as the file to execute, and passes all of - argv to the child. - - - -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 g_spawn... 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. - - -@user_data: user data to pass to the function. - - - - - - - -@working_directory: -@argv: -@envp: -@flags: -@child_setup: -@user_data: -@child_pid: -@standard_input: -@standard_output: -@standard_error: -@error: -@Returns: - - - - - - - -@working_directory: -@argv: -@envp: -@flags: -@child_setup: -@user_data: -@child_pid: -@error: -@Returns: - - - - - - - -@working_directory: -@argv: -@envp: -@flags: -@child_setup: -@user_data: -@standard_output: -@standard_error: -@exit_status: -@error: -@Returns: - - - - - - - -@command_line: -@error: -@Returns: - - - - - - - -@command_line: -@standard_output: -@standard_error: -@exit_status: -@error: -@Returns: - - - - - - - -@pid: - - diff --git a/glib/gspawn.c b/glib/gspawn.c index 4eaa33f..7b4f702 100644 --- a/glib/gspawn.c +++ b/glib/gspawn.c @@ -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, diff --git a/glib/gspawn.h b/glib/gspawn.h index fa8bfab..c9da1a8 100644 --- a/glib/gspawn.h +++ b/glib/gspawn.h @@ -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, + * error->message 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 g_spawn... 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 SIGCHLD yourself), or the child will become a zombie. + * @G_SPAWN_SEARCH_PATH: argv[0] need not be an absolute path, + * it will be looked for in the user's PATH. + * @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 + * /dev/null). + * @G_SPAWN_FILE_AND_ARGV_ZERO: the first element of argv 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 + * argv[0] as the file to execute, and passes all of + * argv 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, diff --git a/glib/gstring.h b/glib/gstring.h index 2b1dd6e..404fdeb 100644 --- a/glib/gstring.h +++ b/glib/gstring.h @@ -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; -- 2.7.4