X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=glib%2Fgspawn.h;h=eb7304bb821ef40383abd8a42df2fb0c7cde494e;hb=13e15733f38a40c6ef6a1baede91cce81c86ebaa;hp=9836b34242a6e8f4d91aa079ee70b249c0c429d9;hpb=45a1c41e8cfdeb4edeb7a671b95e599a49c6c281;p=platform%2Fupstream%2Fglib.git diff --git a/glib/gspawn.h b/glib/gspawn.h index 9836b34..eb7304b 100644 --- a/glib/gspawn.h +++ b/glib/gspawn.h @@ -18,20 +18,55 @@ * Boston, MA 02111-1307, USA. */ -#if defined(G_DISABLE_SINGLE_INCLUDES) && !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION) -#error "Only can be included directly." -#endif - #ifndef __G_SPAWN_H__ #define __G_SPAWN_H__ +#if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION) +#error "Only can be included directly." +#endif + #include 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_TOO_BIG: execv() returned `E2BIG` + * @G_SPAWN_ERROR_2BIG: deprecated alias for %G_SPAWN_ERROR_TOO_BIG + * @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 */ @@ -39,7 +74,10 @@ typedef enum 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_TOO_BIG,/* execv() returned E2BIG */ +#ifndef G_DISABLE_DEPRECATED + G_SPAWN_ERROR_2BIG = G_SPAWN_ERROR_TOO_BIG, +#endif G_SPAWN_ERROR_NOEXEC, /* execv() returned ENOEXEC */ G_SPAWN_ERROR_NAMETOOLONG, /* "" "" ENAMETOOLONG */ G_SPAWN_ERROR_NOENT, /* "" "" ENOENT */ @@ -58,10 +96,82 @@ typedef enum */ } GSpawnError; +/** + * G_SPAWN_EXIT_ERROR: + * + * Error domain used by g_spawn_check_exit_status(). The code + * will be the program exit code. + */ +#define G_SPAWN_EXIT_ERROR g_spawn_exit_error_quark () + +/** + * 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(), which can, in very + * limited ways, be used to affect the child's execution. + * + * On POSIX platforms, the function is called in the child after GLib + * has performed all the setup it plans to perform, but before calling + * exec(). Actions taken in this function will only affect the child, + * not the parent. + * + * 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. + * + * However, even on POSIX, you are extremely limited in what you can + * safely do from a #GSpawnChildSetupFunc, because any mutexes that were + * held by other threads in the parent process at the time of the fork() + * will still be locked in the child process, and they will never be + * unlocked (since the threads that held them don't exist in the child). + * 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. + * + * In particular, it is not safe to call any function which may + * call malloc(), which includes POSIX functions such as setenv(). + * If you need to set up the child environment differently from + * the parent, you should use g_get_environ(), g_environ_setenv(), + * and g_environ_unsetenv(), and then pass the complete environment + * list to the `g_spawn...` function. + */ typedef void (* GSpawnChildSetupFunc) (gpointer user_data); +/** + * GSpawnFlags: + * @G_SPAWN_DEFAULT: no flags, default behaviour + * @G_SPAWN_LEAVE_DESCRIPTORS_OPEN: the parent's open file descriptors will + * be inherited by the child; otherwise all descriptors except stdin, + * stdout and 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. + * @G_SPAWN_SEARCH_PATH_FROM_ENVP: if `argv[0]` is not an abolute path, + * it will be looked for in the `PATH` from the passed child environment. + * Since: 2.34 + * @G_SPAWN_CLOEXEC_PIPES: create all pipes with the `O_CLOEXEC` flag set. + * Since: 2.40 + * + * Flags passed to g_spawn_sync(), g_spawn_async() and g_spawn_async_with_pipes(). + */ typedef enum { + G_SPAWN_DEFAULT = 0, 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() */ @@ -70,19 +180,17 @@ typedef enum 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 + G_SPAWN_FILE_AND_ARGV_ZERO = 1 << 6, + G_SPAWN_SEARCH_PATH_FROM_ENVP = 1 << 7, + G_SPAWN_CLOEXEC_PIPES = 1 << 8 } GSpawnFlags; +GLIB_AVAILABLE_IN_ALL GQuark g_spawn_error_quark (void); +GLIB_AVAILABLE_IN_ALL +GQuark g_spawn_exit_error_quark (void); -#ifdef G_OS_WIN32 -#define g_spawn_async g_spawn_async_utf8 -#define g_spawn_async_with_pipes g_spawn_async_with_pipes_utf8 -#define g_spawn_sync g_spawn_sync_utf8 -#define g_spawn_command_line_sync g_spawn_command_line_sync_utf8 -#define g_spawn_command_line_async g_spawn_command_line_async_utf8 -#endif - +GLIB_AVAILABLE_IN_ALL gboolean g_spawn_async (const gchar *working_directory, gchar **argv, gchar **envp, @@ -96,6 +204,7 @@ gboolean g_spawn_async (const gchar *working_directory, /* Opens pipes for non-NULL standard_output, standard_input, standard_error, * and returns the parent's end of the pipes. */ +GLIB_AVAILABLE_IN_ALL gboolean g_spawn_async_with_pipes (const gchar *working_directory, gchar **argv, gchar **envp, @@ -113,6 +222,7 @@ gboolean g_spawn_async_with_pipes (const gchar *working_directory, * standard output or error of the command will be placed there. */ +GLIB_AVAILABLE_IN_ALL gboolean g_spawn_sync (const gchar *working_directory, gchar **argv, gchar **envp, @@ -124,16 +234,74 @@ gboolean g_spawn_sync (const gchar *working_directory, gint *exit_status, GError **error); +GLIB_AVAILABLE_IN_ALL gboolean g_spawn_command_line_sync (const gchar *command_line, gchar **standard_output, gchar **standard_error, gint *exit_status, GError **error); +GLIB_AVAILABLE_IN_ALL gboolean g_spawn_command_line_async (const gchar *command_line, GError **error); +GLIB_AVAILABLE_IN_2_34 +gboolean g_spawn_check_exit_status (gint exit_status, + GError **error); + +GLIB_AVAILABLE_IN_ALL void g_spawn_close_pid (GPid pid); +#ifdef G_OS_WIN32 +#define g_spawn_async g_spawn_async_utf8 +#define g_spawn_async_with_pipes g_spawn_async_with_pipes_utf8 +#define g_spawn_sync g_spawn_sync_utf8 +#define g_spawn_command_line_sync g_spawn_command_line_sync_utf8 +#define g_spawn_command_line_async g_spawn_command_line_async_utf8 + +GLIB_AVAILABLE_IN_ALL +gboolean g_spawn_async_utf8 (const gchar *working_directory, + gchar **argv, + gchar **envp, + GSpawnFlags flags, + GSpawnChildSetupFunc child_setup, + gpointer user_data, + GPid *child_pid, + GError **error); +GLIB_AVAILABLE_IN_ALL +gboolean g_spawn_async_with_pipes_utf8 (const gchar *working_directory, + gchar **argv, + gchar **envp, + GSpawnFlags flags, + GSpawnChildSetupFunc child_setup, + gpointer user_data, + GPid *child_pid, + gint *standard_input, + gint *standard_output, + gint *standard_error, + GError **error); +GLIB_AVAILABLE_IN_ALL +gboolean g_spawn_sync_utf8 (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); + +GLIB_AVAILABLE_IN_ALL +gboolean g_spawn_command_line_sync_utf8 (const gchar *command_line, + gchar **standard_output, + gchar **standard_error, + gint *exit_status, + GError **error); +GLIB_AVAILABLE_IN_ALL +gboolean g_spawn_command_line_async_utf8 (const gchar *command_line, + GError **error); +#endif + G_END_DECLS #endif /* __G_SPAWN_H__ */