PageRenderTime 25ms CodeModel.GetById 10ms app.highlight 8ms RepoModel.GetById 1ms app.codeStats 0ms

/src/wrappers/glib/library/utilities/glib_spawning_processes.e

http://github.com/tybor/Liberty
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