![]() | ![]() | ![]() | GLib Reference Manual | ![]() |
---|
Spawning Processes — process launching with
#include <glib.h> enum GSpawnError; #define G_SPAWN_ERROR enum GSpawnFlags; void (*GSpawnChildSetupFunc) (gpointer user_data); gboolean g_spawn_async_with_pipes (const gchar *working_directory, gchar **argv, gchar **envp, GSpawnFlags flags, GSpawnChildSetupFunc child_setup, gpointer user_data, gint *child_pid, gint *standard_input, gint *standard_output, gint *standard_error, GError **error); gboolean g_spawn_async (const gchar *working_directory, gchar **argv, gchar **envp, GSpawnFlags flags, GSpawnChildSetupFunc child_setup, gpointer user_data, gint *child_pid, GError **error); gboolean g_spawn_sync (const gchar *working_directory, gchar **argv, gchar **envp, GSpawnFlags flags, GSpawnChildSetupFunc child_setup, gpointer user_data, gchar **standard_output, gchar **standard_error, gint *exit_status, GError **error); gboolean g_spawn_command_line_async (const gchar *command_line, GError **error); gboolean g_spawn_command_line_sync (const gchar *command_line, gchar **standard_output, gchar **standard_error, gint *exit_status, GError **error);
typedef enum { 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 dir 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, /* "" "" ENAMETOOLONG */ G_SPAWN_ERROR_NOENT, /* "" "" ENOENT */ G_SPAWN_ERROR_NOMEM, /* "" "" ENOMEM */ G_SPAWN_ERROR_NOTDIR, /* "" "" ENOTDIR */ G_SPAWN_ERROR_LOOP, /* "" "" ELOOP */ G_SPAWN_ERROR_TXTBUSY, /* "" "" ETXTBUSY */ G_SPAWN_ERROR_IO, /* "" "" EIO */ G_SPAWN_ERROR_NFILE, /* "" "" ENFILE */ G_SPAWN_ERROR_MFILE, /* "" "" EMFLE */ G_SPAWN_ERROR_INVAL, /* "" "" EINVAL */ G_SPAWN_ERROR_ISDIR, /* "" "" EISDIR */ G_SPAWN_ERROR_LIBBAD, /* "" "" ELIBBAD */ G_SPAWN_ERROR_FAILED /* other fatal failure, error->message * should explain */ } GSpawnError;
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 | |
G_SPAWN_ERROR_PERM | |
G_SPAWN_ERROR_2BIG | |
G_SPAWN_ERROR_NOEXEC | |
G_SPAWN_ERROR_NAMETOOLONG | |
G_SPAWN_ERROR_NOENT | |
G_SPAWN_ERROR_NOMEM | |
G_SPAWN_ERROR_NOTDIR | |
G_SPAWN_ERROR_LOOP | |
G_SPAWN_ERROR_TXTBUSY | |
G_SPAWN_ERROR_IO | |
G_SPAWN_ERROR_NFILE | |
G_SPAWN_ERROR_MFILE | |
G_SPAWN_ERROR_INVAL | |
G_SPAWN_ERROR_ISDIR | |
G_SPAWN_ERROR_LIBBAD | |
G_SPAWN_ERROR_FAILED | Some other fatal failure, error->message should explain. |
#define G_SPAWN_ERROR g_spawn_error_quark ()
Error domain for spawning processes. Errors in this domain will be from the GSpawnError enumeration. See GError for information on error domains.
typedef enum { G_SPAWN_LEAVE_DESCRIPTORS_OPEN = 1 << 0, G_SPAWN_DO_NOT_REAP_CHILD = 1 << 1, /* look for argv[0] in the path i.e. use execvp() */ G_SPAWN_SEARCH_PATH = 1 << 2, /* Dump output to /dev/null */ G_SPAWN_STDOUT_TO_DEV_NULL = 1 << 3, G_SPAWN_STDERR_TO_DEV_NULL = 1 << 4, G_SPAWN_CHILD_INHERITS_STDIN = 1 << 5, G_SPAWN_FILE_AND_ARGV_ZERO = 1 << 6 } GSpawnFlags;
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 |
G_SPAWN_DO_NOT_REAP_CHILD | the child will not be automatically reaped; you
must call |
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 standad 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. |
void (*GSpawnChildSetupFunc) (gpointer user_data);
Specifies the type of the setup function passed to g_spawn_async(),
g_spawn_sync() and g_spawn_async_with_pipes(). It is called in the
child after GLib has performed all the setup it plans to perform
but before calling
user_data : | user data to pass to the function. |
gboolean g_spawn_async_with_pipes (const gchar *working_directory, gchar **argv, gchar **envp, GSpawnFlags flags, GSpawnChildSetupFunc child_setup, gpointer user_data, gint *child_pid, gint *standard_input, gint *standard_output, gint *standard_error, GError **error);
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; the PATH shell variable will only be searched if you pass the G_SPAWN_SEARCH_PATH flag.
On Windows, the low-level child process creation API
(
envp is a NULL-terminated array of strings, where each string 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 behavior. On Unix, the G_SPAWN_DO_NOT_REAP_CHILD means
that the child will not be automatically reaped; you must call
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
child_setup and user_data are a function and user data. On POSIX
platforms, the function is called in the child after GLib has
performed all the setup it plans to perform (including creating
pipes, closing file descriptors, etc.) but before calling
If non-NULL, child_pid will on Unix be filled with the child's
process ID. You can use the process ID to send signals to the
child, or to
If non-NULL, the standard_input, standard_output, standard_error locations will be filled with file descriptors for writing to the child's standard input or reading from its standard output or standard error. The caller of g_spawn_async_with_pipes() must close these file descriptors when they are no longer in use. If these parameters are NULL, the corresponding pipe won't be created.
If standard_input is NULL, the child's standard input is attached to /dev/null unless G_SPAWN_CHILD_INHERITS_STDIN is set.
If standard_error is NULL, the child's standard error goes to the same location as the parent's standard error unless G_SPAWN_STDERR_TO_DEV_NULL is set.
If standard_output is NULL, the child's standard output goes to the same location as the parent's standard output unless G_SPAWN_STDOUT_TO_DEV_NULL is set.
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 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.
working_directory : | child's current working directory, or NULL to inherit parent's |
argv : | child's argument vector |
envp : | child's environment, or NULL to inherit parent's |
flags : | flags from GSpawnFlags |
child_setup : | function to run in the child just before |
user_data : | user data for child_setup |
child_pid : | return location for child process ID, or NULL |
standard_input : | return location for file descriptor to write to child's stdin, or NULL |
standard_output : | return location for file descriptor to read child's stdout, or NULL |
standard_error : | return location for file descriptor to read child's stderr, or NULL |
error : | return location for error |
Returns : | TRUE on success, FALSE if an error was set |
gboolean g_spawn_async (const gchar *working_directory, gchar **argv, gchar **envp, GSpawnFlags flags, GSpawnChildSetupFunc child_setup, gpointer user_data, gint *child_pid, GError **error);
See g_spawn_async_with_pipes() for a full description; this function simply calls the g_spawn_async_with_pipes() without any pipes.
working_directory : | child's current working directory, or NULL to inherit parent's |
argv : | child's argument vector |
envp : | child's environment, or NULL to inherit parent's |
flags : | flags from GSpawnFlags |
child_setup : | function to run in the child just before |
user_data : | user data for child_setup |
child_pid : | return location for child process ID, or NULL |
error : | return location for error |
Returns : | TRUE on success, FALSE if error is set |
gboolean g_spawn_sync (const gchar *working_directory, gchar **argv, gchar **envp, GSpawnFlags flags, GSpawnChildSetupFunc child_setup, gpointer user_data, gchar **standard_output, gchar **standard_error, gint *exit_status, GError **error);
Executes a child synchronously (waits for the child to exit before returning).
All output from the child is stored in standard_output and standard_error,
if those parameters are non-NULL. If exit_status is non-NULL, the exit
status of the child is stored there as it would be returned by
This function calls g_spawn_async_with_pipes() internally; see that function for full details on the other parameters.
working_directory : | child's current working directory, or NULL to inherit parent's |
argv : | child's argument vector |
envp : | child's environment, or NULL to inherit parent's |
flags : | flags from GSpawnFlags |
child_setup : | function to run in the child just before |
user_data : | user data for child_setup |
standard_output : | return location for child output |
standard_error : | return location for child error messages |
exit_status : | child exit status, as returned by |
error : | return location for error |
Returns : | TRUE on success, FALSE if an error was set. |
gboolean g_spawn_command_line_async (const gchar *command_line, GError **error);
A simple version of g_spawn_async() that parses a command line with g_shell_parse_argv() and passes it to g_spawn_async(). Runs a command line in the background. Unlike g_spawn_async(), the G_SPAWN_SEARCH_PATH flag is enabled, other flags are not. Note that G_SPAWN_SEARCH_PATH can have security implications, so consider using g_spawn_async() directly if appropriate. Possible errors are those from g_shell_parse_argv() and g_spawn_async().
The same concerns on Windows apply as for g_spawn_command_line_sync().
command_line : | a command line |
error : | return location for errors |
Returns : | TRUE on success, FALSE if error is set. |
gboolean g_spawn_command_line_sync (const gchar *command_line, gchar **standard_output, gchar **standard_error, gint *exit_status, GError **error);
A simple version of g_spawn_sync() with little-used parameters removed, taking a command line instead of an argument vector. See g_spawn_sync() for full details. command_line will be parsed by g_shell_parse_argv(). Unlike g_spawn_sync(), the G_SPAWN_SEARCH_PATH flag is enabled. Note that G_SPAWN_SEARCH_PATH can have security implications, so consider using g_spawn_sync() directly if appropriate. Possible errors are those from g_spawn_sync() and those from g_shell_parse_argv().
On Windows, please note the implications of g_shell_parse_argv() parsing command_line. Space is a separator, and backslashes are special. Thus you cannot simply pass a command_line containing canonical Windows paths, like "c:\\program files\\app\\app.exe", as the backslashes will be eaten, and the space will act as a separator. You need to enclose such paths with single quotes, like "'c:\\program files\\app\\app.exe' 'e:\\folder\\argument.txt'".
command_line : | a command line |
standard_output : | return location for child output |
standard_error : | return location for child errors |
exit_status : | return location for child exit status |
error : | return location for errors |
Returns : | TRUE on success, FALSE if an error was set |
<< Timers | File Utilities >> |