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->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 196
