/src/wrappers/glib/library/utilities/glib_spawning_processes.e
Specman e | 468 lines | 2 code | 77 blank | 389 comment | 0 complexity | ff28df323f17a93a52f3208b2b8a294b MD5 | raw file
1class GLIB_SPAWNING_PROCESSES 2-- Spawning Processes 3 4-- Spawning Processes -- process launching with fork()/exec(). 5 6-- Synopsis 7 8 9-- #include <glib.h> 10 11 12-- enum GSpawnError; 13-- #define G_SPAWN_ERROR 14-- enum GSpawnFlags; 15-- void (*GSpawnChildSetupFunc) (gpointer user_data); 16-- gboolean g_spawn_async_with_pipes (const gchar *working_directory, 17-- gchar **argv, 18-- gchar **envp, 19-- GSpawnFlags flags, 20-- GSpawnChildSetupFunc child_setup, 21-- gpointer user_data, 22-- GPid *child_pid, 23-- gint *standard_input, 24-- gint *standard_output, 25-- gint *standard_error, 26-- GError **error); 27-- gboolean g_spawn_async (const gchar *working_directory, 28-- gchar **argv, 29-- gchar **envp, 30-- GSpawnFlags flags, 31-- GSpawnChildSetupFunc child_setup, 32-- gpointer user_data, 33-- GPid *child_pid, 34-- GError **error); 35-- gboolean g_spawn_sync (const gchar *working_directory, 36-- gchar **argv, 37-- gchar **envp, 38-- GSpawnFlags flags, 39-- GSpawnChildSetupFunc child_setup, 40-- gpointer user_data, 41-- gchar **standard_output, 42-- gchar **standard_error, 43-- gint *exit_status, 44-- GError **error); 45-- gboolean g_spawn_command_line_async (const gchar *command_line, 46-- GError **error); 47-- gboolean g_spawn_command_line_sync (const gchar *command_line, 48-- gchar **standard_output, 49-- gchar **standard_error, 50-- gint *exit_status, 51-- GError **error); 52-- void g_spawn_close_pid (GPid pid); 53 54 55-- Description 56 57-- Details 58 59-- enum GSpawnError 60 61-- typedef enum 62-- { 63-- G_SPAWN_ERROR_FORK, /* fork failed due to lack of memory */ 64-- G_SPAWN_ERROR_READ, /* read or select on pipes failed */ 65-- G_SPAWN_ERROR_CHDIR, /* changing to working dir failed */ 66-- G_SPAWN_ERROR_ACCES, /* execv() returned EACCES */ 67-- G_SPAWN_ERROR_PERM, /* execv() returned EPERM */ 68-- G_SPAWN_ERROR_2BIG, /* execv() returned E2BIG */ 69-- G_SPAWN_ERROR_NOEXEC, /* execv() returned ENOEXEC */ 70-- G_SPAWN_ERROR_NAMETOOLONG, /* "" "" ENAMETOOLONG */ 71-- G_SPAWN_ERROR_NOENT, /* "" "" ENOENT */ 72-- G_SPAWN_ERROR_NOMEM, /* "" "" ENOMEM */ 73-- G_SPAWN_ERROR_NOTDIR, /* "" "" ENOTDIR */ 74-- G_SPAWN_ERROR_LOOP, /* "" "" ELOOP */ 75-- G_SPAWN_ERROR_TXTBUSY, /* "" "" ETXTBUSY */ 76-- G_SPAWN_ERROR_IO, /* "" "" EIO */ 77-- G_SPAWN_ERROR_NFILE, /* "" "" ENFILE */ 78-- G_SPAWN_ERROR_MFILE, /* "" "" EMFLE */ 79-- G_SPAWN_ERROR_INVAL, /* "" "" EINVAL */ 80-- G_SPAWN_ERROR_ISDIR, /* "" "" EISDIR */ 81-- G_SPAWN_ERROR_LIBBAD, /* "" "" ELIBBAD */ 82-- G_SPAWN_ERROR_FAILED /* other fatal failure, error->message 83-- * should explain 84-- */ 85-- } GSpawnError; 86 87-- Error codes returned by spawning processes. 88 89-- G_SPAWN_ERROR_FORK Fork failed due to lack of memory. 90-- G_SPAWN_ERROR_READ Read or select on pipes failed. 91-- G_SPAWN_ERROR_CHDIR Changing to working directory failed. 92-- G_SPAWN_ERROR_ACCES execv() returned EACCES. 93-- G_SPAWN_ERROR_PERM execv() returned EPERM. 94-- G_SPAWN_ERROR_2BIG execv() returned E2BIG. 95-- G_SPAWN_ERROR_NOEXEC execv() returned ENOEXEC. 96-- G_SPAWN_ERROR_NAMETOOLONG execv() returned ENAMETOOLONG. 97-- G_SPAWN_ERROR_NOENT execv() returned ENOENT. 98-- G_SPAWN_ERROR_NOMEM execv() returned ENOMEM. 99-- G_SPAWN_ERROR_NOTDIR execv() returned ENOTDIR. 100-- G_SPAWN_ERROR_LOOP execv() returned ELOOP. 101-- G_SPAWN_ERROR_TXTBUSY execv() returned ETXTBUSY. 102-- G_SPAWN_ERROR_IO execv() returned EIO. 103-- G_SPAWN_ERROR_NFILE execv() returned ENFILE. 104-- G_SPAWN_ERROR_MFILE execv() returned EMFILE. 105-- G_SPAWN_ERROR_INVAL execv() returned EINVAL. 106-- G_SPAWN_ERROR_ISDIR execv() returned EISDIR. 107-- G_SPAWN_ERROR_LIBBAD execv() returned ELIBBAD. 108-- G_SPAWN_ERROR_FAILED Some other fatal failure, error->message should 109-- explain. 110 111-- --------------------------------------------------------------------------------- 112 113-- G_SPAWN_ERROR 114 115-- #define G_SPAWN_ERROR g_spawn_error_quark () 116 117-- Error domain for spawning processes. Errors in this domain will be from the 118-- GSpawnError enumeration. See GError for information on error domains. 119 120-- --------------------------------------------------------------------------------- 121 122-- enum GSpawnFlags 123 124-- typedef enum 125-- { 126-- G_SPAWN_LEAVE_DESCRIPTORS_OPEN = 1 << 0, 127-- G_SPAWN_DO_NOT_REAP_CHILD = 1 << 1, 128-- /* look for argv[0] in the path i.e. use execvp() */ 129-- G_SPAWN_SEARCH_PATH = 1 << 2, 130-- /* Dump output to /dev/null */ 131-- G_SPAWN_STDOUT_TO_DEV_NULL = 1 << 3, 132-- G_SPAWN_STDERR_TO_DEV_NULL = 1 << 4, 133-- G_SPAWN_CHILD_INHERITS_STDIN = 1 << 5, 134-- G_SPAWN_FILE_AND_ARGV_ZERO = 1 << 6 135-- } GSpawnFlags; 136 137-- Flags passed to g_spawn_sync(), g_spawn_async() and g_spawn_async_with_pipes(). 138 139-- G_SPAWN_LEAVE_DESCRIPTORS_OPEN the parent's open file descriptors will be 140-- inherited by the child; otherwise all descriptors 141-- except stdin/stdout/stderr will be closed before 142-- calling exec() in the child. 143-- G_SPAWN_DO_NOT_REAP_CHILD the child will not be automatically reaped; you 144-- must call waitpid() or handle SIGCHLD yourself, or 145-- the child will become a zombie. 146-- G_SPAWN_SEARCH_PATH argv[0] need not be an absolute path, it will be 147-- looked for in the user's PATH. 148-- G_SPAWN_STDOUT_TO_DEV_NULL the child's standad output will be discarded, 149-- instead of going to the same location as the 150-- parent's standard output. 151-- G_SPAWN_STDERR_TO_DEV_NULL the child's standard error will be discarded. 152-- G_SPAWN_CHILD_INHERITS_STDIN the child will inherit the parent's standard input 153-- (by default, the child's standard input is 154-- attached to /dev/null). 155-- G_SPAWN_FILE_AND_ARGV_ZERO the first element of argv is the file to execute, 156-- while the remaining elements are the actual 157-- argument vector to pass to the file. Normally 158-- g_spawn_async_with_pipes() uses argv[0] as the 159-- file to execute, and passes all of argv to the 160-- child. 161 162-- --------------------------------------------------------------------------------- 163 164-- GSpawnChildSetupFunc () 165 166-- void (*GSpawnChildSetupFunc) (gpointer user_data); 167 168-- Specifies the type of the setup function passed to g_spawn_async(), 169-- g_spawn_sync() and g_spawn_async_with_pipes(). On POSIX platforms it is called in 170-- the child after GLib has performed all the setup it plans to perform but before 171-- calling exec(). On POSIX actions taken in this function will thus only affect the 172-- child, not the parent. 173 174-- On Windows the function is called in the parent. Its usefulness on Windows is 175-- thus questionable. In many cases executing the child setup function in the parent 176-- can have ill effects, and you should be very careful when porting software to 177-- Windows that uses child setup functions. 178 179-- user_data : user data to pass to the function. 180 181-- --------------------------------------------------------------------------------- 182 183-- g_spawn_async_with_pipes () 184 185-- gboolean g_spawn_async_with_pipes (const gchar *working_directory, 186-- gchar **argv, 187-- gchar **envp, 188-- GSpawnFlags flags, 189-- GSpawnChildSetupFunc child_setup, 190-- gpointer user_data, 191-- GPid *child_pid, 192-- gint *standard_input, 193-- gint *standard_output, 194-- gint *standard_error, 195-- GError **error); 196 197-- Executes a child program asynchronously (your program will not block waiting for 198-- the child to exit). The child program is specified by the only argument that must 199-- be provided, argv. argv should be a NULL-terminated array of strings, to be 200-- passed as the argument vector for the child. The first string in argv is of 201-- course the name of the program to execute. By default, the name of the program 202-- must be a full path; the PATH shell variable will only be searched if you pass 203-- the G_SPAWN_SEARCH_PATH flag. 204 205-- On Windows, note that all the string or string vector arguments to this function 206-- and the other g_spawn*() functions are in UTF-8, the GLib file name encoding. 207-- Unicode characters that are not part of the system codepage passed in argument 208-- vectors will be correctly available in the spawned program only if it uses wide 209-- character API to retrieve its command line. For C programs built with Microsoft's 210-- tools it is enough to make the program have a wmain() instead of main(). wmain() 211-- has a wide character argument vector as parameter. 212 213-- At least currently, mingw doesn't support wmain(), so if you use mingw to develop 214-- the spawned program, it will have to call the undocumented function 215-- __wgetmainargs() to get the wide character argument vector and environment. See 216-- gspawn-win32-helper.c in the GLib sources or init.c in the mingw runtime sources 217-- for a prototype for that function. Alternatively, you can retrieve the Win32 218-- system level wide character command line passed to the spawned program using the 219-- GetCommandLineW() function. 220 221-- On Windows the low-level child process creation API CreateProcess() doesn't use 222-- argument vectors, but a command line. The C runtime library's spawn*() family of 223-- functions (which g_spawn_async_with_pipes() eventually calls) paste the argument 224-- vector elements together into a command line, and the C runtime startup code does 225-- a corresponding reconstruction of an argument vector from the command line, to be 226-- passed to main(). Complications arise when you have argument vector elements that 227-- contain spaces of double quotes. The spawn*() functions don't do any quoting or 228-- escaping, but on the other hand the startup code does do unquoting and unescaping 229-- in order to enable receiving arguments with embedded spaces or double quotes. To 230-- work around this asymmetry, g_spawn_async_with_pipes() will do quoting and 231-- escaping on argument vector elements that need it before calling the C runtime 232-- spawn() function. 233 234-- envp is a NULL-terminated array of strings, where each string has the form 235-- KEY=VALUE. This will become the child's environment. If envp is NULL, the child 236-- inherits its parent's environment. 237 238-- flags should be the bitwise OR of any flags you want to affect the function's 239-- behaviour. The G_SPAWN_DO_NOT_REAP_CHILD means that the child will not 240-- automatically be reaped; you must use a GChildWatch source to be notified about 241-- the death of the child process. Eventually you must call g_spawn_close_pid() on 242-- the child_pid, in order to free resources which may be associated with the child 243-- process. (On Unix, using a GChildWatch source is equivalent to calling waitpid() 244-- or handling the SIGCHLD signal manually. On Windows, calling g_spawn_close_pid() 245-- is equivalent to calling CloseHandle() on the process handle returned in 246-- child_pid). 247 248-- G_SPAWN_LEAVE_DESCRIPTORS_OPEN means that the parent's open file descriptors will 249-- be inherited by the child; otherwise all descriptors except stdin/stdout/stderr 250-- will be closed before calling exec() in the child. G_SPAWN_SEARCH_PATH means that 251-- argv[0] need not be an absolute path, it will be looked for in the user's PATH. 252-- G_SPAWN_STDOUT_TO_DEV_NULL means that the child's standard output will be 253-- discarded, instead of going to the same location as the parent's standard output. 254-- If you use this flag, standard_output must be NULL. G_SPAWN_STDERR_TO_DEV_NULL 255-- means that the child's standard error will be discarded, instead of going to the 256-- same location as the parent's standard error. If you use this flag, 257-- standard_error must be NULL. G_SPAWN_CHILD_INHERITS_STDIN means that the child 258-- will inherit the parent's standard input (by default, the child's standard input 259-- is attached to /dev/null). If you use this flag, standard_input must be NULL. 260-- G_SPAWN_FILE_AND_ARGV_ZERO means that the first element of argv is the file to 261-- execute, while the remaining elements are the actual argument vector to pass to 262-- the file. Normally g_spawn_async_with_pipes() uses argv[0] as the file to 263-- execute, and passes all of argv to the child. 264 265-- child_setup and user_data are a function and user data. On POSIX platforms, the 266-- function is called in the child after GLib has performed all the setup it plans 267-- to perform (including creating pipes, closing file descriptors, etc.) but before 268-- calling exec(). That is, child_setup is called just before calling exec() in the 269-- child. Obviously actions taken in this function will only affect the child, not 270-- the parent. On Windows, there is no separate fork() and exec() functionality. 271-- Child processes are created and run with a single API call, CreateProcess(). 272-- child_setup is called in the parent process just before creating the child 273-- process. You should carefully consider what you do in child_setup if you intend 274-- your software to be portable to Windows. 275 276-- If non-NULL, child_pid will on Unix be filled with the child's process ID. You 277-- can use the process ID to send signals to the child, or to waitpid() if you 278-- specified the G_SPAWN_DO_NOT_REAP_CHILD flag. On Windows, child_pid will be 279-- filled with a handle to the child process only if you specified the 280-- G_SPAWN_DO_NOT_REAP_CHILD flag. You can then access the child process using the 281-- Win32 API, for example wait for its termination with the WaitFor*() functions, or 282-- examine its exit code with GetExitCodeProcess(). You should close the handle with 283-- CloseHandle() or g_spawn_close_pid() when you no longer need it. 284 285-- If non-NULL, the standard_input, standard_output, standard_error locations will 286-- be filled with file descriptors for writing to the child's standard input or 287-- reading from its standard output or standard error. The caller of 288-- g_spawn_async_with_pipes() must close these file descriptors when they are no 289-- longer in use. If these parameters are NULL, the corresponding pipe won't be 290-- created. 291 292-- If standard_input is NULL, the child's standard input is attached to /dev/null 293-- unless G_SPAWN_CHILD_INHERITS_STDIN is set. 294 295-- If standard_error is NULL, the child's standard error goes to the same location 296-- as the parent's standard error unless G_SPAWN_STDERR_TO_DEV_NULL is set. 297 298-- If standard_output is NULL, the child's standard output goes to the same location 299-- as the parent's standard output unless G_SPAWN_STDOUT_TO_DEV_NULL is set. 300 301-- error can be NULL to ignore errors, or non-NULL to report errors. If an error is 302-- set, the function returns FALSE. Errors are reported even if they occur in the 303-- child (for example if the executable in argv[0] is not found). Typically the 304-- message field of returned errors should be displayed to users. Possible errors 305-- are those from the G_SPAWN_ERROR domain. 306 307-- If an error occurs, child_pid, standard_input, standard_output, and 308-- standard_error will not be filled with valid values. 309 310-- If child_pid is not NULL and an error does not occur then the returned pid must 311-- be closed using g_spawn_close_pid(). 312 313-- working_directory : child's current working directory, or NULL to inherit 314-- parent's, in the GLib file name encoding 315-- argv : child's argument vector, in the GLib file name encoding 316-- envp : child's environment, or NULL to inherit parent's, in the GLib 317-- file name encoding 318-- flags : flags from GSpawnFlags 319-- child_setup : function to run in the child just before exec() 320-- user_data : user data for child_setup 321-- child_pid : return location for child process ID, or NULL 322-- standard_input : return location for file descriptor to write to child's 323-- stdin, or NULL 324-- standard_output : return location for file descriptor to read child's stdout, 325-- or NULL 326-- standard_error : return location for file descriptor to read child's stderr, 327-- or NULL 328-- error : return location for error 329-- Returns : TRUE on success, FALSE if an error was set 330 331-- --------------------------------------------------------------------------------- 332 333-- g_spawn_async () 334 335-- gboolean g_spawn_async (const gchar *working_directory, 336-- gchar **argv, 337-- gchar **envp, 338-- GSpawnFlags flags, 339-- GSpawnChildSetupFunc child_setup, 340-- gpointer user_data, 341-- GPid *child_pid, 342-- GError **error); 343 344-- See g_spawn_async_with_pipes() for a full description; this function simply calls 345-- the g_spawn_async_with_pipes() without any pipes. 346 347-- working_directory : child's current working directory, or NULL to inherit 348-- parent's 349-- argv : child's argument vector 350-- envp : child's environment, or NULL to inherit parent's 351-- flags : flags from GSpawnFlags 352-- child_setup : function to run in the child just before exec() 353-- user_data : user data for child_setup 354-- child_pid : return location for child process ID, or NULL 355-- error : return location for error 356-- Returns : TRUE on success, FALSE if error is set 357 358-- --------------------------------------------------------------------------------- 359 360-- g_spawn_sync () 361 362-- gboolean g_spawn_sync (const gchar *working_directory, 363-- gchar **argv, 364-- gchar **envp, 365-- GSpawnFlags flags, 366-- GSpawnChildSetupFunc child_setup, 367-- gpointer user_data, 368-- gchar **standard_output, 369-- gchar **standard_error, 370-- gint *exit_status, 371-- GError **error); 372 373-- Executes a child synchronously (waits for the child to exit before returning). 374-- All output from the child is stored in standard_output and standard_error, if 375-- those parameters are non-NULL. If exit_status is non-NULL, the exit status of the 376-- child is stored there as it would be returned by waitpid(); standard UNIX macros 377-- such as WIFEXITED() and WEXITSTATUS() must be used to evaluate the exit status. 378-- If an error occurs, no data is returned in standard_output, standard_error, or 379-- exit_status. 380 381-- This function calls g_spawn_async_with_pipes() internally; see that function for 382-- full details on the other parameters and details on how these functions work on 383-- Windows. 384 385-- working_directory : child's current working directory, or NULL to inherit 386-- parent's 387-- argv : child's argument vector 388-- envp : child's environment, or NULL to inherit parent's 389-- flags : flags from GSpawnFlags 390-- child_setup : function to run in the child just before exec() 391-- user_data : user data for child_setup 392-- standard_output : return location for child output 393-- standard_error : return location for child error messages 394-- exit_status : return location for child exit status, as returned by 395-- waitpid() 396-- error : return location for error 397-- Returns : TRUE on success, FALSE if an error was set. 398 399-- --------------------------------------------------------------------------------- 400 401-- g_spawn_command_line_async () 402 403-- gboolean g_spawn_command_line_async (const gchar *command_line, 404-- GError **error); 405 406-- A simple version of g_spawn_async() that parses a command line with 407-- g_shell_parse_argv() and passes it to g_spawn_async(). Runs a command line in the 408-- background. Unlike g_spawn_async(), the G_SPAWN_SEARCH_PATH flag is enabled, 409-- other flags are not. Note that G_SPAWN_SEARCH_PATH can have security 410-- implications, so consider using g_spawn_async() directly if appropriate. Possible 411-- errors are those from g_shell_parse_argv() and g_spawn_async(). 412 413-- The same concerns on Windows apply as for g_spawn_command_line_sync(). 414 415-- command_line : a command line 416-- error : return location for errors 417-- Returns : TRUE on success, FALSE if error is set. 418 419-- --------------------------------------------------------------------------------- 420 421-- g_spawn_command_line_sync () 422 423-- gboolean g_spawn_command_line_sync (const gchar *command_line, 424-- gchar **standard_output, 425-- gchar **standard_error, 426-- gint *exit_status, 427-- GError **error); 428 429-- A simple version of g_spawn_sync() with little-used parameters removed, taking a 430-- command line instead of an argument vector. See g_spawn_sync() for full details. 431-- command_line will be parsed by g_shell_parse_argv(). Unlike g_spawn_sync(), the 432-- G_SPAWN_SEARCH_PATH flag is enabled. Note that G_SPAWN_SEARCH_PATH can have 433-- security implications, so consider using g_spawn_sync() directly if appropriate. 434-- Possible errors are those from g_spawn_sync() and those from 435-- g_shell_parse_argv(). 436 437-- If exit_status is non-NULL, the exit status of the child is stored there as it 438-- would be returned by waitpid(); standard UNIX macros such as WIFEXITED() and 439-- WEXITSTATUS() must be used to evaluate the exit status. 440 441-- On Windows, please note the implications of g_shell_parse_argv() parsing 442-- command_line. Parsing is done according to Unix shell rules, not Windows command 443-- interpreter rules. Space is a separator, and backslashes are special. Thus you 444-- cannot simply pass a command_line containing canonical Windows paths, like 445-- "c:\\program files\\app\\app.exe", as the backslashes will be eaten, and the 446-- space will act as a separator. You need to enclose such paths with single quotes, 447-- like "'c:\\program files\\app\\app.exe' 'e:\\folder\\argument.txt'". 448 449-- command_line : a command line 450-- standard_output : return location for child output 451-- standard_error : return location for child errors 452-- exit_status : return location for child exit status, as returned by waitpid() 453-- error : return location for errors 454-- Returns : TRUE on success, FALSE if an error was set 455 456-- --------------------------------------------------------------------------------- 457 458-- g_spawn_close_pid () 459 460-- void g_spawn_close_pid (GPid pid); 461 462-- On some platforms, notably WIN32, the GPid type represents a resource which must 463-- be closed to prevent resource leaking. g_spawn_close_pid() is provided for this 464-- purpose. It should be used on all platforms, even though it doesn't do anything 465-- under UNIX. 466 467-- pid : The process identifier to close 468end -- class GLIB_SPAWNING_PROCESSES