docs/reference/glib/tmpl/spawn.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Spawning Processes
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 process launching
   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: execv() returned %EACCES.
  29 @G_SPAWN_ERROR_PERM: execv() returned %EPERM.
  30 @G_SPAWN_ERROR_2BIG: execv() returned %E2BIG.
  31 @G_SPAWN_ERROR_NOEXEC: execv() returned %ENOEXEC.
  32 @G_SPAWN_ERROR_NAMETOOLONG: execv() returned %ENAMETOOLONG.
  33 @G_SPAWN_ERROR_NOENT: execv() returned %ENOENT.
  34 @G_SPAWN_ERROR_NOMEM: execv() returned %ENOMEM.
  35 @G_SPAWN_ERROR_NOTDIR: execv() returned %ENOTDIR.
  36 @G_SPAWN_ERROR_LOOP: execv() returned %ELOOP.
  37 @G_SPAWN_ERROR_TXTBUSY: execv() returned %ETXTBUSY.
  38 @G_SPAWN_ERROR_IO: execv() returned %EIO.
  39 @G_SPAWN_ERROR_NFILE: execv() returned %ENFILE.
  40 @G_SPAWN_ERROR_MFILE: execv() returned %EMFILE.
  41 @G_SPAWN_ERROR_INVAL: execv() returned %EINVAL.
  42 @G_SPAWN_ERROR_ISDIR: execv() returned %EISDIR.
  43 @G_SPAWN_ERROR_LIBBAD: execv() 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 exec() in the child.
  63 @G_SPAWN_DO_NOT_REAP_CHILD: the child will not be automatically reaped; you
  64   must use g_child_watch_add() yourself (or call waitpid()
  65   or handle <literal>SIGCHLD</literal> 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 standard 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 exec(). On POSIX actions taken in this
  86 function will thus only affect the child, not the parent.
  87 </para>
  88
  89 <para>
  90 Note that POSIX allows only async-signal-safe functions (see signal(7))
  91 to be called in the child between fork() and exec(), which drastically
  92 limits the usefulness of child setup functions.
  93 </para>
  94
  95 <para>
  96 Also note that modifying the environment from the child setup function
  97 may not have the intended effect, since it will get overridden by
  98 a non-%NULL @env argument to the <literal>g_spawn...</literal> functions.
  99 </para>
 100
 101 <para>
 102 On Windows the function is called in the parent. Its usefulness on
 103 Windows is thus questionable. In many cases executing the child setup
 104 function in the parent can have ill effects, and you should be very
 105 careful when porting software to Windows that uses child setup
 106 functions.
 107 </para>
 108
 109 @user_data: user data to pass to the function.
 110
 111
 112 <!-- ##### FUNCTION g_spawn_async_with_pipes ##### -->
 113 <para>
 114
 115 </para>
 116
 117 @working_directory:
 118 @argv:
 119 @envp:
 120 @flags:
 121 @child_setup:
 122 @user_data:
 123 @child_pid:
 124 @standard_input:
 125 @standard_output:
 126 @standard_error:
 127 @error:
 128 @Returns:
 129
 130
 131 <!-- ##### FUNCTION g_spawn_async ##### -->
 132 <para>
 133
 134 </para>
 135
 136 @working_directory:
 137 @argv:
 138 @envp:
 139 @flags:
 140 @child_setup:
 141 @user_data:
 142 @child_pid:
 143 @error:
 144 @Returns:
 145
 146
 147 <!-- ##### FUNCTION g_spawn_sync ##### -->
 148 <para>
 149
 150 </para>
 151
 152 @working_directory:
 153 @argv:
 154 @envp:
 155 @flags:
 156 @child_setup:
 157 @user_data:
 158 @standard_output:
 159 @standard_error:
 160 @exit_status:
 161 @error:
 162 @Returns:
 163
 164
 165 <!-- ##### FUNCTION g_spawn_command_line_async ##### -->
 166 <para>
 167
 168 </para>
 169
 170 @command_line:
 171 @error:
 172 @Returns:
 173
 174
 175 <!-- ##### FUNCTION g_spawn_command_line_sync ##### -->
 176 <para>
 177
 178 </para>
 179
 180 @command_line:
 181 @standard_output:
 182 @standard_error:
 183 @exit_status:
 184 @error:
 185 @Returns:
 186
 187
 188 <!-- ##### FUNCTION g_spawn_close_pid ##### -->
 189 <para>
 190
 191 </para>
 192
 193 @pid:
 194
 195