EIC code displayed by LXR |
|
|
|
|||
File indexing completed on 2026-05-06 08:41:18
0001 /* gspawn.h - Process launching 0002 * 0003 * Copyright 2000 Red Hat, Inc. 0004 * 0005 * SPDX-License-Identifier: LGPL-2.1-or-later 0006 * 0007 * This library is free software; you can redistribute it and/or 0008 * modify it under the terms of the GNU Lesser General Public 0009 * License as published by the Free Software Foundation; either 0010 * version 2.1 of the License, or (at your option) any later version. 0011 * 0012 * This library is distributed in the hope that it will be useful, 0013 * but WITHOUT ANY WARRANTY; without even the implied warranty of 0014 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 0015 * Lesser General Public License for more details. 0016 * 0017 * You should have received a copy of the GNU Lesser General Public License 0018 * along with this library; if not, see <http://www.gnu.org/licenses/>. 0019 */ 0020 0021 #ifndef __G_SPAWN_H__ 0022 #define __G_SPAWN_H__ 0023 0024 #if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION) 0025 #error "Only <glib.h> can be included directly." 0026 #endif 0027 0028 #include <glib/gerror.h> 0029 0030 G_BEGIN_DECLS 0031 0032 0033 /* I'm not sure I remember our proposed naming convention here. */ 0034 /** 0035 * G_SPAWN_ERROR: 0036 * 0037 * Error domain for spawning processes. Errors in this domain will 0038 * be from the #GSpawnError enumeration. See #GError for information on 0039 * error domains. 0040 */ 0041 #define G_SPAWN_ERROR g_spawn_error_quark () 0042 0043 /** 0044 * GSpawnError: 0045 * @G_SPAWN_ERROR_FORK: Fork failed due to lack of memory. 0046 * @G_SPAWN_ERROR_READ: Read or select on pipes failed. 0047 * @G_SPAWN_ERROR_CHDIR: Changing to working directory failed. 0048 * @G_SPAWN_ERROR_ACCES: execv() returned `EACCES` 0049 * @G_SPAWN_ERROR_PERM: execv() returned `EPERM` 0050 * @G_SPAWN_ERROR_TOO_BIG: execv() returned `E2BIG` 0051 * @G_SPAWN_ERROR_2BIG: deprecated alias for %G_SPAWN_ERROR_TOO_BIG (deprecated since GLib 2.32) 0052 * @G_SPAWN_ERROR_NOEXEC: execv() returned `ENOEXEC` 0053 * @G_SPAWN_ERROR_NAMETOOLONG: execv() returned `ENAMETOOLONG` 0054 * @G_SPAWN_ERROR_NOENT: execv() returned `ENOENT` 0055 * @G_SPAWN_ERROR_NOMEM: execv() returned `ENOMEM` 0056 * @G_SPAWN_ERROR_NOTDIR: execv() returned `ENOTDIR` 0057 * @G_SPAWN_ERROR_LOOP: execv() returned `ELOOP` 0058 * @G_SPAWN_ERROR_TXTBUSY: execv() returned `ETXTBUSY` 0059 * @G_SPAWN_ERROR_IO: execv() returned `EIO` 0060 * @G_SPAWN_ERROR_NFILE: execv() returned `ENFILE` 0061 * @G_SPAWN_ERROR_MFILE: execv() returned `EMFILE` 0062 * @G_SPAWN_ERROR_INVAL: execv() returned `EINVAL` 0063 * @G_SPAWN_ERROR_ISDIR: execv() returned `EISDIR` 0064 * @G_SPAWN_ERROR_LIBBAD: execv() returned `ELIBBAD` 0065 * @G_SPAWN_ERROR_FAILED: Some other fatal failure, 0066 * `error->message` should explain. 0067 * 0068 * Error codes returned by spawning processes. 0069 */ 0070 typedef enum 0071 { 0072 G_SPAWN_ERROR_FORK, /* fork failed due to lack of memory */ 0073 G_SPAWN_ERROR_READ, /* read or select on pipes failed */ 0074 G_SPAWN_ERROR_CHDIR, /* changing to working dir failed */ 0075 G_SPAWN_ERROR_ACCES, /* execv() returned EACCES */ 0076 G_SPAWN_ERROR_PERM, /* execv() returned EPERM */ 0077 G_SPAWN_ERROR_TOO_BIG,/* execv() returned E2BIG */ 0078 G_SPAWN_ERROR_2BIG GLIB_DEPRECATED_ENUMERATOR_IN_2_32_FOR(G_SPAWN_ERROR_TOO_BIG) = G_SPAWN_ERROR_TOO_BIG, 0079 G_SPAWN_ERROR_NOEXEC, /* execv() returned ENOEXEC */ 0080 G_SPAWN_ERROR_NAMETOOLONG, /* "" "" ENAMETOOLONG */ 0081 G_SPAWN_ERROR_NOENT, /* "" "" ENOENT */ 0082 G_SPAWN_ERROR_NOMEM, /* "" "" ENOMEM */ 0083 G_SPAWN_ERROR_NOTDIR, /* "" "" ENOTDIR */ 0084 G_SPAWN_ERROR_LOOP, /* "" "" ELOOP */ 0085 G_SPAWN_ERROR_TXTBUSY, /* "" "" ETXTBUSY */ 0086 G_SPAWN_ERROR_IO, /* "" "" EIO */ 0087 G_SPAWN_ERROR_NFILE, /* "" "" ENFILE */ 0088 G_SPAWN_ERROR_MFILE, /* "" "" EMFLE */ 0089 G_SPAWN_ERROR_INVAL, /* "" "" EINVAL */ 0090 G_SPAWN_ERROR_ISDIR, /* "" "" EISDIR */ 0091 G_SPAWN_ERROR_LIBBAD, /* "" "" ELIBBAD */ 0092 G_SPAWN_ERROR_FAILED /* other fatal failure, error->message 0093 * should explain 0094 */ 0095 } GSpawnError; 0096 0097 /** 0098 * G_SPAWN_EXIT_ERROR: 0099 * 0100 * Error domain used by g_spawn_check_wait_status(). The code 0101 * will be the program exit code. 0102 */ 0103 #define G_SPAWN_EXIT_ERROR g_spawn_exit_error_quark () 0104 0105 /** 0106 * GSpawnChildSetupFunc: 0107 * @data: user data passed to the function. 0108 * 0109 * Specifies the type of the setup function passed to g_spawn_async(), 0110 * g_spawn_sync() and g_spawn_async_with_pipes(), which can, in very 0111 * limited ways, be used to affect the child's execution. 0112 * 0113 * On POSIX platforms, the function is called in the child after GLib 0114 * has performed all the setup it plans to perform, but before calling 0115 * exec(). Actions taken in this function will only affect the child, 0116 * not the parent. 0117 * 0118 * On Windows, the function is called in the parent. Its usefulness on 0119 * Windows is thus questionable. In many cases executing the child setup 0120 * function in the parent can have ill effects, and you should be very 0121 * careful when porting software to Windows that uses child setup 0122 * functions. 0123 * 0124 * However, even on POSIX, you are extremely limited in what you can 0125 * safely do from a #GSpawnChildSetupFunc, because any mutexes that were 0126 * held by other threads in the parent process at the time of the fork() 0127 * will still be locked in the child process, and they will never be 0128 * unlocked (since the threads that held them don't exist in the child). 0129 * POSIX allows only async-signal-safe functions (see signal(7)) to be 0130 * called in the child between fork() and exec(), which drastically limits 0131 * the usefulness of child setup functions. 0132 * 0133 * In particular, it is not safe to call any function which may 0134 * call malloc(), which includes POSIX functions such as setenv(). 0135 * If you need to set up the child environment differently from 0136 * the parent, you should use g_get_environ(), g_environ_setenv(), 0137 * and g_environ_unsetenv(), and then pass the complete environment 0138 * list to the `g_spawn...` function. 0139 */ 0140 typedef void (* GSpawnChildSetupFunc) (gpointer data); 0141 0142 /** 0143 * GSpawnFlags: 0144 * @G_SPAWN_DEFAULT: no flags, default behaviour 0145 * @G_SPAWN_LEAVE_DESCRIPTORS_OPEN: the parent's open file descriptors will 0146 * be inherited by the child; otherwise all descriptors except stdin, 0147 * stdout and stderr will be closed before calling exec() in the child. 0148 * @G_SPAWN_DO_NOT_REAP_CHILD: the child will not be automatically reaped; 0149 * you must use g_child_watch_add() yourself (or call waitpid() or handle 0150 * `SIGCHLD` yourself), or the child will become a zombie. 0151 * @G_SPAWN_SEARCH_PATH: `argv[0]` need not be an absolute path, it will be 0152 * looked for in the user's `PATH`. 0153 * @G_SPAWN_STDOUT_TO_DEV_NULL: the child's standard output will be discarded, 0154 * instead of going to the same location as the parent's standard output. 0155 * @G_SPAWN_STDERR_TO_DEV_NULL: the child's standard error will be discarded. 0156 * @G_SPAWN_CHILD_INHERITS_STDIN: the child will inherit the parent's standard 0157 * input (by default, the child's standard input is attached to `/dev/null`). 0158 * @G_SPAWN_FILE_AND_ARGV_ZERO: the first element of `argv` is the file to 0159 * execute, while the remaining elements are the actual argument vector 0160 * to pass to the file. Normally g_spawn_async_with_pipes() uses `argv[0]` 0161 * as the file to execute, and passes all of `argv` to the child. 0162 * @G_SPAWN_SEARCH_PATH_FROM_ENVP: if `argv[0]` is not an absolute path, 0163 * it will be looked for in the `PATH` from the passed child environment. 0164 * Since: 2.34 0165 * @G_SPAWN_CLOEXEC_PIPES: create all pipes with the `O_CLOEXEC` flag set. 0166 * Since: 2.40 0167 * @G_SPAWN_CHILD_INHERITS_STDOUT: the child will inherit the parent's standard output. 0168 * Since: 2.74 0169 * @G_SPAWN_CHILD_INHERITS_STDERR: the child will inherit the parent's standard error. 0170 * Since: 2.74 0171 * @G_SPAWN_STDIN_FROM_DEV_NULL: the child's standard input is attached to `/dev/null`. 0172 * Since: 2.74 0173 * 0174 * Flags passed to g_spawn_sync(), g_spawn_async() and g_spawn_async_with_pipes(). 0175 */ 0176 typedef enum 0177 { 0178 G_SPAWN_DEFAULT = 0, 0179 G_SPAWN_LEAVE_DESCRIPTORS_OPEN = 1 << 0, 0180 G_SPAWN_DO_NOT_REAP_CHILD = 1 << 1, 0181 /* look for argv[0] in the path i.e. use execvp() */ 0182 G_SPAWN_SEARCH_PATH = 1 << 2, 0183 /* Dump output to /dev/null */ 0184 G_SPAWN_STDOUT_TO_DEV_NULL = 1 << 3, 0185 G_SPAWN_STDERR_TO_DEV_NULL = 1 << 4, 0186 G_SPAWN_CHILD_INHERITS_STDIN = 1 << 5, 0187 G_SPAWN_FILE_AND_ARGV_ZERO = 1 << 6, 0188 G_SPAWN_SEARCH_PATH_FROM_ENVP = 1 << 7, 0189 G_SPAWN_CLOEXEC_PIPES = 1 << 8, 0190 0191 /** 0192 * G_SPAWN_CHILD_INHERITS_STDOUT: 0193 * 0194 * The child will inherit the parent's standard output. 0195 * 0196 * Since: 2.74 0197 */ 0198 G_SPAWN_CHILD_INHERITS_STDOUT = 1 << 9, 0199 0200 /** 0201 * G_SPAWN_CHILD_INHERITS_STDERR: 0202 * 0203 * The child will inherit the parent's standard error. 0204 * 0205 * Since: 2.74 0206 */ 0207 G_SPAWN_CHILD_INHERITS_STDERR = 1 << 10, 0208 0209 /** 0210 * G_SPAWN_STDIN_FROM_DEV_NULL: 0211 * 0212 * The child's standard input is attached to `/dev/null`. 0213 * 0214 * Since: 2.74 0215 */ 0216 G_SPAWN_STDIN_FROM_DEV_NULL = 1 << 11 0217 } GSpawnFlags; 0218 0219 GLIB_AVAILABLE_IN_ALL 0220 GQuark g_spawn_error_quark (void); 0221 GLIB_AVAILABLE_IN_ALL 0222 GQuark g_spawn_exit_error_quark (void); 0223 0224 GLIB_AVAILABLE_IN_ALL 0225 gboolean g_spawn_async (const gchar *working_directory, 0226 gchar **argv, 0227 gchar **envp, 0228 GSpawnFlags flags, 0229 GSpawnChildSetupFunc child_setup, 0230 gpointer user_data, 0231 GPid *child_pid, 0232 GError **error); 0233 0234 0235 /* Opens pipes for non-NULL standard_output, standard_input, standard_error, 0236 * and returns the parent's end of the pipes. 0237 */ 0238 GLIB_AVAILABLE_IN_ALL 0239 gboolean g_spawn_async_with_pipes (const gchar *working_directory, 0240 gchar **argv, 0241 gchar **envp, 0242 GSpawnFlags flags, 0243 GSpawnChildSetupFunc child_setup, 0244 gpointer user_data, 0245 GPid *child_pid, 0246 gint *standard_input, 0247 gint *standard_output, 0248 gint *standard_error, 0249 GError **error); 0250 0251 GLIB_AVAILABLE_IN_2_68 0252 gboolean g_spawn_async_with_pipes_and_fds (const gchar *working_directory, 0253 const gchar * const *argv, 0254 const gchar * const *envp, 0255 GSpawnFlags flags, 0256 GSpawnChildSetupFunc child_setup, 0257 gpointer user_data, 0258 gint stdin_fd, 0259 gint stdout_fd, 0260 gint stderr_fd, 0261 const gint *source_fds, 0262 const gint *target_fds, 0263 gsize n_fds, 0264 GPid *child_pid_out, 0265 gint *stdin_pipe_out, 0266 gint *stdout_pipe_out, 0267 gint *stderr_pipe_out, 0268 GError **error); 0269 0270 /* Lets you provide fds for stdin/stdout/stderr */ 0271 GLIB_AVAILABLE_IN_2_58 0272 gboolean g_spawn_async_with_fds (const gchar *working_directory, 0273 gchar **argv, 0274 gchar **envp, 0275 GSpawnFlags flags, 0276 GSpawnChildSetupFunc child_setup, 0277 gpointer user_data, 0278 GPid *child_pid, 0279 gint stdin_fd, 0280 gint stdout_fd, 0281 gint stderr_fd, 0282 GError **error); 0283 0284 /* If standard_output or standard_error are non-NULL, the full 0285 * standard output or error of the command will be placed there. 0286 */ 0287 0288 GLIB_AVAILABLE_IN_ALL 0289 gboolean g_spawn_sync (const gchar *working_directory, 0290 gchar **argv, 0291 gchar **envp, 0292 GSpawnFlags flags, 0293 GSpawnChildSetupFunc child_setup, 0294 gpointer user_data, 0295 gchar **standard_output, 0296 gchar **standard_error, 0297 gint *wait_status, 0298 GError **error); 0299 0300 GLIB_AVAILABLE_IN_ALL 0301 gboolean g_spawn_command_line_sync (const gchar *command_line, 0302 gchar **standard_output, 0303 gchar **standard_error, 0304 gint *wait_status, 0305 GError **error); 0306 GLIB_AVAILABLE_IN_ALL 0307 gboolean g_spawn_command_line_async (const gchar *command_line, 0308 GError **error); 0309 0310 GLIB_AVAILABLE_IN_2_70 0311 gboolean g_spawn_check_wait_status (gint wait_status, 0312 GError **error); 0313 0314 GLIB_DEPRECATED_IN_2_70_FOR(g_spawn_check_wait_status) 0315 gboolean g_spawn_check_exit_status (gint wait_status, 0316 GError **error); 0317 0318 GLIB_AVAILABLE_IN_ALL 0319 void g_spawn_close_pid (GPid pid); 0320 0321 G_END_DECLS 0322 0323 #endif /* __G_SPAWN_H__ */
| [ Source navigation ] | [ Diff markup ] | [ Identifier search ] | [ general search ] |
|
This page was automatically generated by the 2.3.7 LXR engine. The LXR team |
|