• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1<!-- ##### SECTION Title ##### -->
2Spawning Processes
3
4<!-- ##### SECTION Short_Description ##### -->
5process 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>
22Error 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>
48Error domain for spawning processes. Errors in this domain will
49be from the #GSpawnError enumeration. See #GError for information on
50error domains.
51</para>
52
53
54
55<!-- ##### ENUM GSpawnFlags ##### -->
56<para>
57Flags 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>
82Specifies the type of the setup function passed to g_spawn_async(),
83g_spawn_sync() and g_spawn_async_with_pipes(). On POSIX platforms it
84is called in the child after GLib has performed all the setup it plans
85to perform but before calling exec(). On POSIX actions taken in this
86function will thus only affect the child, not the parent.
87</para>
88
89<para>
90Note that POSIX allows only async-signal-safe functions (see signal(7))
91to be called in the child between fork() and exec(), which drastically
92limits the usefulness of child setup functions.
93</para>
94
95<para>
96Also note that modifying the environment from the child setup function
97may not have the intended effect, since it will get overridden by
98a non-%NULL @env argument to the <literal>g_spawn...</literal> functions.
99</para>
100
101<para>
102On Windows the function is called in the parent. Its usefulness on
103Windows is thus questionable. In many cases executing the child setup
104function in the parent can have ill effects, and you should be very
105careful when porting software to Windows that uses child setup
106functions.
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