docs/reference/glib/tmpl/spawn.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Spawning Processes
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 process launching with <function>fork()</function>/<function>exec()</function>.
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9
  10 </para>
  11
  12 <!-- ##### SECTION See_Also ##### -->
  13 <para>
  14
  15 </para>
  16
  17 <!-- ##### SECTION Stability_Level ##### -->
  18
  19
  20 <!-- ##### ENUM GSpawnError ##### -->
  21 <para>
  22 Error codes returned by spawning processes.
  23 </para>
  24
  25 @G_SPAWN_ERROR_FORK: Fork failed due to lack of memory.
  26 @G_SPAWN_ERROR_READ: Read or select on pipes failed.
  27 @G_SPAWN_ERROR_CHDIR: Changing to working directory failed.
  28 @G_SPAWN_ERROR_ACCES: <function>execv()</function> returned %EACCES.
  29 @G_SPAWN_ERROR_PERM: <function>execv()</function> returned %EPERM.
  30 @G_SPAWN_ERROR_2BIG: <function>execv()</function> returned %E2BIG.
  31 @G_SPAWN_ERROR_NOEXEC: <function>execv()</function> returned %ENOEXEC.
  32 @G_SPAWN_ERROR_NAMETOOLONG: <function>execv()</function> returned %ENAMETOOLONG.
  33 @G_SPAWN_ERROR_NOENT: <function>execv()</function> returned %ENOENT.
  34 @G_SPAWN_ERROR_NOMEM: <function>execv()</function> returned %ENOMEM.
  35 @G_SPAWN_ERROR_NOTDIR: <function>execv()</function> returned %ENOTDIR.
  36 @G_SPAWN_ERROR_LOOP: <function>execv()</function> returned %ELOOP.
  37 @G_SPAWN_ERROR_TXTBUSY: <function>execv()</function> returned %ETXTBUSY.
  38 @G_SPAWN_ERROR_IO: <function>execv()</function> returned %EIO.
  39 @G_SPAWN_ERROR_NFILE: <function>execv()</function> returned %ENFILE.
  40 @G_SPAWN_ERROR_MFILE: <function>execv()</function> returned %EMFILE.
  41 @G_SPAWN_ERROR_INVAL: <function>execv()</function> returned %EINVAL.
  42 @G_SPAWN_ERROR_ISDIR: <function>execv()</function> returned %EISDIR.
  43 @G_SPAWN_ERROR_LIBBAD: <function>execv()</function> returned %ELIBBAD.
  44 @G_SPAWN_ERROR_FAILED: Some other fatal failure, <literal>error-&gt;message</literal> should explain.
  45
  46 <!-- ##### MACRO G_SPAWN_ERROR ##### -->
  47 <para>
  48 Error domain for spawning processes. Errors in this domain will
  49 be from the #GSpawnError enumeration. See #GError for information on
  50 error domains.
  51 </para>
  52
  53
  54
  55 <!-- ##### ENUM GSpawnFlags ##### -->
  56 <para>
  57 Flags passed to g_spawn_sync(), g_spawn_async() and g_spawn_async_with_pipes().
  58 </para>
  59
  60 @G_SPAWN_LEAVE_DESCRIPTORS_OPEN: the parent's open file descriptors will be
  61  inherited by the child; otherwise all descriptors except stdin/stdout/stderr
  62  will be closed before calling <function>exec()</function> in the child.
  63 @G_SPAWN_DO_NOT_REAP_CHILD: the child will not be automatically reaped; you
  64   must call <function>waitpid()</function> or handle <literal>SIGCHLD</literal>
  65   yourself, or the child will become a zombie.
  66 @G_SPAWN_SEARCH_PATH: <literal>argv[0]</literal> need not be an absolute path,
  67   it will be looked for in the user's <envar>PATH</envar>.
  68 @G_SPAWN_STDOUT_TO_DEV_NULL: the child's standad output will be discarded,
  69   instead of going to the same location as the parent's standard output.
  70 @G_SPAWN_STDERR_TO_DEV_NULL: the child's standard error will be discarded.
  71 @G_SPAWN_CHILD_INHERITS_STDIN: the child will inherit the parent's standard
  72   input (by default, the child's standard input is attached to
  73   <filename>/dev/null</filename>).
  74 @G_SPAWN_FILE_AND_ARGV_ZERO: the first element of <literal>argv</literal> is
  75   the file to execute, while the remaining elements are the actual argument
  76   vector to pass to the file. Normally g_spawn_async_with_pipes() uses
  77   <literal>argv[0]</literal> as the file to execute, and passes all of
  78   <literal>argv</literal> to the child.
  79
  80 <!-- ##### USER_FUNCTION GSpawnChildSetupFunc ##### -->
  81 <para>
  82 Specifies the type of the setup function passed to g_spawn_async(),
  83 g_spawn_sync() and g_spawn_async_with_pipes(). On POSIX platforms it
  84 is called in the child after GLib has performed all the setup it plans
  85 to perform but before calling <function>exec()</function>. On POSIX
  86 actions taken in this function will thus only affect the child, not
  87 the parent.
  88 </para>
  89
  90 <para>
  91 On Windows the function is called in the parent. Its usefulness on
  92 Windows is thus questionable. In many cases executing the child setup
  93 function in the parent can have ill effects, and you should be very
  94 careful when porting software to Windows that uses child setup
  95 functions.
  96 </para>
  97
  98 @user_data: user data to pass to the function.
  99
 100
 101 <!-- ##### FUNCTION g_spawn_async_with_pipes ##### -->
 102 <para>
 103
 104 </para>
 105
 106 @working_directory:
 107 @argv:
 108 @envp:
 109 @flags:
 110 @child_setup:
 111 @user_data:
 112 @child_pid:
 113 @standard_input:
 114 @standard_output:
 115 @standard_error:
 116 @error:
 117 @Returns:
 118
 119
 120 <!-- ##### FUNCTION g_spawn_async ##### -->
 121 <para>
 122
 123 </para>
 124
 125 @working_directory:
 126 @argv:
 127 @envp:
 128 @flags:
 129 @child_setup:
 130 @user_data:
 131 @child_pid:
 132 @error:
 133 @Returns:
 134
 135
 136 <!-- ##### FUNCTION g_spawn_sync ##### -->
 137 <para>
 138
 139 </para>
 140
 141 @working_directory:
 142 @argv:
 143 @envp:
 144 @flags:
 145 @child_setup:
 146 @user_data:
 147 @standard_output:
 148 @standard_error:
 149 @exit_status:
 150 @error:
 151 @Returns:
 152
 153
 154 <!-- ##### FUNCTION g_spawn_command_line_async ##### -->
 155 <para>
 156
 157 </para>
 158
 159 @command_line:
 160 @error:
 161 @Returns:
 162
 163
 164 <!-- ##### FUNCTION g_spawn_command_line_sync ##### -->
 165 <para>
 166
 167 </para>
 168
 169 @command_line:
 170 @standard_output:
 171 @standard_error:
 172 @exit_status:
 173 @error:
 174 @Returns:
 175
 176
 177 <!-- ##### FUNCTION g_spawn_close_pid ##### -->
 178 <para>
 179
 180 </para>
 181
 182 @pid:
 183
 184