1 /* gspawn.h - Process launching 2 * 3 * Copyright 2000 Red Hat, Inc. 4 * 5 * This library is free software; you can redistribute it and/or 6 * modify it under the terms of the GNU Lesser General Public 7 * License as published by the Free Software Foundation; either 8 * version 2.1 of the License, or (at your option) any later version. 9 * 10 * This library is distributed in the hope that it will be useful, 11 * but WITHOUT ANY WARRANTY; without even the implied warranty of 12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 13 * Lesser General Public License for more details. 14 * 15 * You should have received a copy of the GNU Lesser General Public License 16 * along with this library; if not, see <http://www.gnu.org/licenses/>. 17 */ 18 19 #ifndef __G_SPAWN_H__ 20 #define __G_SPAWN_H__ 21 22 #if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION) 23 #error "Only <glib.h> can be included directly." 24 #endif 25 26 #include <glib/gerror.h> 27 28 G_BEGIN_DECLS 29 30 31 /* I'm not sure I remember our proposed naming convention here. */ 32 /** 33 * G_SPAWN_ERROR: 34 * 35 * Error domain for spawning processes. Errors in this domain will 36 * be from the #GSpawnError enumeration. See #GError for information on 37 * error domains. 38 */ 39 #define G_SPAWN_ERROR g_spawn_error_quark () 40 41 /** 42 * GSpawnError: 43 * @G_SPAWN_ERROR_FORK: Fork failed due to lack of memory. 44 * @G_SPAWN_ERROR_READ: Read or select on pipes failed. 45 * @G_SPAWN_ERROR_CHDIR: Changing to working directory failed. 46 * @G_SPAWN_ERROR_ACCES: execv() returned `EACCES` 47 * @G_SPAWN_ERROR_PERM: execv() returned `EPERM` 48 * @G_SPAWN_ERROR_TOO_BIG: execv() returned `E2BIG` 49 * @G_SPAWN_ERROR_2BIG: deprecated alias for %G_SPAWN_ERROR_TOO_BIG (deprecated since GLib 2.32) 50 * @G_SPAWN_ERROR_NOEXEC: execv() returned `ENOEXEC` 51 * @G_SPAWN_ERROR_NAMETOOLONG: execv() returned `ENAMETOOLONG` 52 * @G_SPAWN_ERROR_NOENT: execv() returned `ENOENT` 53 * @G_SPAWN_ERROR_NOMEM: execv() returned `ENOMEM` 54 * @G_SPAWN_ERROR_NOTDIR: execv() returned `ENOTDIR` 55 * @G_SPAWN_ERROR_LOOP: execv() returned `ELOOP` 56 * @G_SPAWN_ERROR_TXTBUSY: execv() returned `ETXTBUSY` 57 * @G_SPAWN_ERROR_IO: execv() returned `EIO` 58 * @G_SPAWN_ERROR_NFILE: execv() returned `ENFILE` 59 * @G_SPAWN_ERROR_MFILE: execv() returned `EMFILE` 60 * @G_SPAWN_ERROR_INVAL: execv() returned `EINVAL` 61 * @G_SPAWN_ERROR_ISDIR: execv() returned `EISDIR` 62 * @G_SPAWN_ERROR_LIBBAD: execv() returned `ELIBBAD` 63 * @G_SPAWN_ERROR_FAILED: Some other fatal failure, 64 * `error->message` should explain. 65 * 66 * Error codes returned by spawning processes. 67 */ 68 typedef enum 69 { 70 G_SPAWN_ERROR_FORK, /* fork failed due to lack of memory */ 71 G_SPAWN_ERROR_READ, /* read or select on pipes failed */ 72 G_SPAWN_ERROR_CHDIR, /* changing to working dir failed */ 73 G_SPAWN_ERROR_ACCES, /* execv() returned EACCES */ 74 G_SPAWN_ERROR_PERM, /* execv() returned EPERM */ 75 G_SPAWN_ERROR_TOO_BIG,/* execv() returned E2BIG */ 76 G_SPAWN_ERROR_2BIG GLIB_DEPRECATED_ENUMERATOR_IN_2_32_FOR(G_SPAWN_ERROR_TOO_BIG) = G_SPAWN_ERROR_TOO_BIG, 77 G_SPAWN_ERROR_NOEXEC, /* execv() returned ENOEXEC */ 78 G_SPAWN_ERROR_NAMETOOLONG, /* "" "" ENAMETOOLONG */ 79 G_SPAWN_ERROR_NOENT, /* "" "" ENOENT */ 80 G_SPAWN_ERROR_NOMEM, /* "" "" ENOMEM */ 81 G_SPAWN_ERROR_NOTDIR, /* "" "" ENOTDIR */ 82 G_SPAWN_ERROR_LOOP, /* "" "" ELOOP */ 83 G_SPAWN_ERROR_TXTBUSY, /* "" "" ETXTBUSY */ 84 G_SPAWN_ERROR_IO, /* "" "" EIO */ 85 G_SPAWN_ERROR_NFILE, /* "" "" ENFILE */ 86 G_SPAWN_ERROR_MFILE, /* "" "" EMFLE */ 87 G_SPAWN_ERROR_INVAL, /* "" "" EINVAL */ 88 G_SPAWN_ERROR_ISDIR, /* "" "" EISDIR */ 89 G_SPAWN_ERROR_LIBBAD, /* "" "" ELIBBAD */ 90 G_SPAWN_ERROR_FAILED /* other fatal failure, error->message 91 * should explain 92 */ 93 } GSpawnError; 94 95 /** 96 * G_SPAWN_EXIT_ERROR: 97 * 98 * Error domain used by g_spawn_check_exit_status(). The code 99 * will be the program exit code. 100 */ 101 #define G_SPAWN_EXIT_ERROR g_spawn_exit_error_quark () 102 103 /** 104 * GSpawnChildSetupFunc: 105 * @user_data: (closure): user data to pass to the function. 106 * 107 * Specifies the type of the setup function passed to g_spawn_async(), 108 * g_spawn_sync() and g_spawn_async_with_pipes(), which can, in very 109 * limited ways, be used to affect the child's execution. 110 * 111 * On POSIX platforms, the function is called in the child after GLib 112 * has performed all the setup it plans to perform, but before calling 113 * exec(). Actions taken in this function will only affect the child, 114 * not the parent. 115 * 116 * On Windows, the function is called in the parent. Its usefulness on 117 * Windows is thus questionable. In many cases executing the child setup 118 * function in the parent can have ill effects, and you should be very 119 * careful when porting software to Windows that uses child setup 120 * functions. 121 * 122 * However, even on POSIX, you are extremely limited in what you can 123 * safely do from a #GSpawnChildSetupFunc, because any mutexes that were 124 * held by other threads in the parent process at the time of the fork() 125 * will still be locked in the child process, and they will never be 126 * unlocked (since the threads that held them don't exist in the child). 127 * POSIX allows only async-signal-safe functions (see signal(7)) to be 128 * called in the child between fork() and exec(), which drastically limits 129 * the usefulness of child setup functions. 130 * 131 * In particular, it is not safe to call any function which may 132 * call malloc(), which includes POSIX functions such as setenv(). 133 * If you need to set up the child environment differently from 134 * the parent, you should use g_get_environ(), g_environ_setenv(), 135 * and g_environ_unsetenv(), and then pass the complete environment 136 * list to the `g_spawn...` function. 137 */ 138 typedef void (* GSpawnChildSetupFunc) (gpointer user_data); 139 140 /** 141 * GSpawnFlags: 142 * @G_SPAWN_DEFAULT: no flags, default behaviour 143 * @G_SPAWN_LEAVE_DESCRIPTORS_OPEN: the parent's open file descriptors will 144 * be inherited by the child; otherwise all descriptors except stdin, 145 * stdout and stderr will be closed before calling exec() in the child. 146 * @G_SPAWN_DO_NOT_REAP_CHILD: the child will not be automatically reaped; 147 * you must use g_child_watch_add() yourself (or call waitpid() or handle 148 * `SIGCHLD` yourself), or the child will become a zombie. 149 * @G_SPAWN_SEARCH_PATH: `argv[0]` need not be an absolute path, it will be 150 * looked for in the user's `PATH`. 151 * @G_SPAWN_STDOUT_TO_DEV_NULL: the child's standard output will be discarded, 152 * instead of going to the same location as the parent's standard output. 153 * @G_SPAWN_STDERR_TO_DEV_NULL: the child's standard error will be discarded. 154 * @G_SPAWN_CHILD_INHERITS_STDIN: the child will inherit the parent's standard 155 * input (by default, the child's standard input is attached to `/dev/null`). 156 * @G_SPAWN_FILE_AND_ARGV_ZERO: the first element of `argv` is the file to 157 * execute, while the remaining elements are the actual argument vector 158 * to pass to the file. Normally g_spawn_async_with_pipes() uses `argv[0]` 159 * as the file to execute, and passes all of `argv` to the child. 160 * @G_SPAWN_SEARCH_PATH_FROM_ENVP: if `argv[0]` is not an absolute path, 161 * it will be looked for in the `PATH` from the passed child environment. 162 * Since: 2.34 163 * @G_SPAWN_CLOEXEC_PIPES: create all pipes with the `O_CLOEXEC` flag set. 164 * Since: 2.40 165 * 166 * Flags passed to g_spawn_sync(), g_spawn_async() and g_spawn_async_with_pipes(). 167 */ 168 typedef enum 169 { 170 G_SPAWN_DEFAULT = 0, 171 G_SPAWN_LEAVE_DESCRIPTORS_OPEN = 1 << 0, 172 G_SPAWN_DO_NOT_REAP_CHILD = 1 << 1, 173 /* look for argv[0] in the path i.e. use execvp() */ 174 G_SPAWN_SEARCH_PATH = 1 << 2, 175 /* Dump output to /dev/null */ 176 G_SPAWN_STDOUT_TO_DEV_NULL = 1 << 3, 177 G_SPAWN_STDERR_TO_DEV_NULL = 1 << 4, 178 G_SPAWN_CHILD_INHERITS_STDIN = 1 << 5, 179 G_SPAWN_FILE_AND_ARGV_ZERO = 1 << 6, 180 G_SPAWN_SEARCH_PATH_FROM_ENVP = 1 << 7, 181 G_SPAWN_CLOEXEC_PIPES = 1 << 8 182 } GSpawnFlags; 183 184 GLIB_AVAILABLE_IN_ALL 185 GQuark g_spawn_error_quark (void); 186 GLIB_AVAILABLE_IN_ALL 187 GQuark g_spawn_exit_error_quark (void); 188 189 GLIB_AVAILABLE_IN_ALL 190 gboolean g_spawn_async (const gchar *working_directory, 191 gchar **argv, 192 gchar **envp, 193 GSpawnFlags flags, 194 GSpawnChildSetupFunc child_setup, 195 gpointer user_data, 196 GPid *child_pid, 197 GError **error); 198 199 200 /* Opens pipes for non-NULL standard_output, standard_input, standard_error, 201 * and returns the parent's end of the pipes. 202 */ 203 GLIB_AVAILABLE_IN_ALL 204 gboolean g_spawn_async_with_pipes (const gchar *working_directory, 205 gchar **argv, 206 gchar **envp, 207 GSpawnFlags flags, 208 GSpawnChildSetupFunc child_setup, 209 gpointer user_data, 210 GPid *child_pid, 211 gint *standard_input, 212 gint *standard_output, 213 gint *standard_error, 214 GError **error); 215 216 GLIB_AVAILABLE_IN_2_68 217 gboolean g_spawn_async_with_pipes_and_fds (const gchar *working_directory, 218 const gchar * const *argv, 219 const gchar * const *envp, 220 GSpawnFlags flags, 221 GSpawnChildSetupFunc child_setup, 222 gpointer user_data, 223 gint stdin_fd, 224 gint stdout_fd, 225 gint stderr_fd, 226 const gint *source_fds, 227 const gint *target_fds, 228 gsize n_fds, 229 GPid *child_pid_out, 230 gint *stdin_pipe_out, 231 gint *stdout_pipe_out, 232 gint *stderr_pipe_out, 233 GError **error); 234 235 /* Lets you provide fds for stdin/stdout/stderr */ 236 GLIB_AVAILABLE_IN_2_58 237 gboolean g_spawn_async_with_fds (const gchar *working_directory, 238 gchar **argv, 239 gchar **envp, 240 GSpawnFlags flags, 241 GSpawnChildSetupFunc child_setup, 242 gpointer user_data, 243 GPid *child_pid, 244 gint stdin_fd, 245 gint stdout_fd, 246 gint stderr_fd, 247 GError **error); 248 249 /* If standard_output or standard_error are non-NULL, the full 250 * standard output or error of the command will be placed there. 251 */ 252 253 GLIB_AVAILABLE_IN_ALL 254 gboolean g_spawn_sync (const gchar *working_directory, 255 gchar **argv, 256 gchar **envp, 257 GSpawnFlags flags, 258 GSpawnChildSetupFunc child_setup, 259 gpointer user_data, 260 gchar **standard_output, 261 gchar **standard_error, 262 gint *exit_status, 263 GError **error); 264 265 GLIB_AVAILABLE_IN_ALL 266 gboolean g_spawn_command_line_sync (const gchar *command_line, 267 gchar **standard_output, 268 gchar **standard_error, 269 gint *exit_status, 270 GError **error); 271 GLIB_AVAILABLE_IN_ALL 272 gboolean g_spawn_command_line_async (const gchar *command_line, 273 GError **error); 274 275 GLIB_AVAILABLE_IN_2_34 276 gboolean g_spawn_check_exit_status (gint exit_status, 277 GError **error); 278 279 GLIB_AVAILABLE_IN_ALL 280 void g_spawn_close_pid (GPid pid); 281 282 G_END_DECLS 283 284 #endif /* __G_SPAWN_H__ */ 285