* 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.
*/
* process and not its identifier. Process handles and process identifiers
* are different concepts on Windows.
*
- * Return value: %TRUE on success, %FALSE if error is set
+ * Returns: %TRUE on success, %FALSE if error is set
**/
gboolean
g_spawn_async (const gchar *working_directory,
* function for full details on the other parameters and details on
* how these functions work on Windows.
*
- * Return value: %TRUE on success, %FALSE if an error was set
+ * Returns: %TRUE on success, %FALSE if an error was set
*/
gboolean
g_spawn_sync (const gchar *working_directory,
*
* Executes a child program asynchronously (your program will not
* block waiting for the child to exit). The child program is
- * specified by the only argument that must be provided, @argv. @argv
- * should be a %NULL-terminated array of strings, to be passed as the
- * argument vector for the child. The first string in @argv is of
- * course the name of the program to execute. By default, the name of
- * the program must be a full path. If @flags contains the
- * %G_SPAWN_SEARCH_PATH flag, the <envar>PATH</envar> environment variable
- * is used to search for the executable. If @flags contains the
- * %G_SPAWN_SEARCH_PATH_FROM_ENVP flag, the <envar>PATH</envar> variable from
- * @envp is used to search for the executable.
- * If both the %G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP
- * flags are set, the <envar>PATH</envar> variable from @envp takes precedence
- * over the environment variable.
+ * specified by the only argument that must be provided, @argv.
+ * @argv should be a %NULL-terminated array of strings, to be passed
+ * as the argument vector for the child. The first string in @argv
+ * is of course the name of the program to execute. By default, the
+ * name of the program must be a full path. If @flags contains the
+ * %G_SPAWN_SEARCH_PATH flag, the `PATH` environment variable is
+ * used to search for the executable. If @flags contains the
+ * %G_SPAWN_SEARCH_PATH_FROM_ENVP flag, the `PATH` variable from
+ * @envp is used to search for the executable. If both the
+ * %G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP flags
+ * are set, the `PATH` variable from @envp takes precedence over
+ * the environment variable.
*
* If the program name is not a full path and %G_SPAWN_SEARCH_PATH flag is not
* used, then the program will be run from the current directory (or
* identifiers are different concepts on Windows.
*
* @envp is a %NULL-terminated array of strings, where each string
- * has the form <literal>KEY=VALUE</literal>. This will become
- * the child's environment. If @envp is %NULL, the child inherits its
- * parent's environment.
+ * has the form `KEY=VALUE`. This will become the child's environment.
+ * If @envp is %NULL, the child inherits its parent's environment.
*
* @flags should be the bitwise OR of any flags you want to affect the
* function's behaviour. The %G_SPAWN_DO_NOT_REAP_CHILD means that the
*
* %G_SPAWN_LEAVE_DESCRIPTORS_OPEN means that 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_SEARCH_PATH means that @argv[0] need not be an absolute
- * path, it will be looked for in the <envar>PATH</envar> environment
- * variable. %G_SPAWN_SEARCH_PATH_FROM_ENVP means need not be an absolute
- * path, it will be looked for in the <envar>PATH</envar> variable from
+ * except stdin/stdout/stderr will be closed before calling exec() in
+ * the child. %G_SPAWN_SEARCH_PATH means that @argv[0] need not be an
+ * absolute path, it will be looked for in the `PATH` environment
+ * variable. %G_SPAWN_SEARCH_PATH_FROM_ENVP means need not be an
+ * absolute path, it will be looked for in the `PATH` variable from
* @envp. If both %G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP
* are used, the value from @envp takes precedence over the environment.
- * %G_SPAWN_STDOUT_TO_DEV_NULL means that the child's standard output will
- * be discarded, instead of going to the same location as the parent's
+ * %G_SPAWN_STDOUT_TO_DEV_NULL means that the child's standard output
+ * will be discarded, instead of going to the same location as the parent's
* standard output. If you use this flag, @standard_output must be %NULL.
* %G_SPAWN_STDERR_TO_DEV_NULL means that the child's standard error
* will be discarded, instead of going to the same location as the parent's
* @error can be %NULL to ignore errors, or non-%NULL to report errors.
* If an error is set, the function returns %FALSE. Errors are reported
* even if they occur in the child (for example if the executable in
- * @argv[0] is not found). Typically the <literal>message</literal> field
- * of returned errors should be displayed to users. Possible errors are
- * those from the #G_SPAWN_ERROR domain.
+ * @argv[0] is not found). Typically the `message` field of returned
+ * errors should be displayed to users. Possible errors are those from
+ * the #G_SPAWN_ERROR domain.
*
* If an error occurs, @child_pid, @standard_input, @standard_output,
* and @standard_error will not be filled with valid values.
* want to use gdk_spawn_on_screen_with_pipes() instead to ensure that
* the spawned program opens its windows on the right screen.
*
- * Return value: %TRUE on success, %FALSE if an error was set
+ * Returns: %TRUE on success, %FALSE if an error was set
*/
gboolean
g_spawn_async_with_pipes (const gchar *working_directory,
* separator. You need to enclose such paths with single quotes, like
* "'c:\\program files\\app\\app.exe' 'e:\\folder\\argument.txt'".
*
- * Return value: %TRUE on success, %FALSE if an error was set
+ * Returns: %TRUE on success, %FALSE if an error was set
**/
gboolean
g_spawn_command_line_sync (const gchar *command_line,
*
* The same concerns on Windows apply as for g_spawn_command_line_sync().
*
- * Return value: %TRUE on success, %FALSE if error is set
+ * Returns: %TRUE on success, %FALSE if error is set
**/
gboolean
g_spawn_command_line_async (const gchar *command_line,
projects / platform / upstream / glib.git / blobdiff