]>
Commit | Line | Data |
---|---|---|
a5458d49 | 1 | .\" Copyright (c) 2009 Bill O. Gallmeister (bgallmeister@gmail.com) |
10069ed0 | 2 | .\" and Copyright 2010 Michael Kerrisk <mtk.manpages@gmail.com> |
a5458d49 | 3 | .\" |
5fbde956 | 4 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
a5458d49 BG |
5 | .\" |
6 | .\" References consulted: | |
7 | .\" Linux glibc source code | |
10069ed0 MK |
8 | .\" POSIX 1003.1-2004 documentation |
9 | .\" (http://www.opengroup.org/onlinepubs/009695399) | |
a5458d49 | 10 | .\" |
4c1c5274 | 11 | .TH posix_spawn 3 (date) "Linux man-pages (unreleased)" |
a5458d49 BG |
12 | .SH NAME |
13 | posix_spawn, posix_spawnp \- spawn a process | |
97677bb2 AC |
14 | .SH LIBRARY |
15 | Standard C library | |
8fc3b2cf | 16 | .RI ( libc ", " \-lc ) |
a5458d49 BG |
17 | .SH SYNOPSIS |
18 | .nf | |
19 | .B #include <spawn.h> | |
f90f031e | 20 | .PP |
a2471dc6 AC |
21 | .BI "int posix_spawn(pid_t *restrict " pid ", const char *restrict " path , |
22 | .BI " const posix_spawn_file_actions_t *restrict " file_actions , | |
23 | .BI " const posix_spawnattr_t *restrict " attrp , | |
24 | .BI " char *const " argv [restrict], | |
25 | .BI " char *const " envp [restrict]); | |
0864c240 AC |
26 | .BI "int posix_spawnp(pid_t *restrict " pid ", const char *restrict " file , |
27 | .BI " const posix_spawn_file_actions_t *restrict " file_actions , | |
28 | .BI " const posix_spawnattr_t *restrict " attrp , | |
29 | .BI " char *const " argv [restrict], | |
30 | .BI " char *const " envp [restrict]); | |
a5458d49 | 31 | .fi |
a5458d49 | 32 | .SH DESCRIPTION |
10069ed0 MK |
33 | The |
34 | .BR posix_spawn () | |
a5458d49 BG |
35 | and |
36 | .BR posix_spawnp () | |
10069ed0 MK |
37 | functions are used to create a new child process that executes |
38 | a specified file. | |
39 | These functions were specified by POSIX to provide a standardized method | |
40 | of creating new processes on machines that lack the capability | |
a5458d49 | 41 | to support the |
10069ed0 | 42 | .BR fork (2) |
a5458d49 BG |
43 | system call. |
44 | These machines are generally small, embedded systems lacking MMU support. | |
847e0d88 | 45 | .PP |
10069ed0 MK |
46 | The |
47 | .BR posix_spawn () | |
a5458d49 BG |
48 | and |
49 | .BR posix_spawnp () | |
10069ed0 MK |
50 | functions provide the functionality of a combined |
51 | .BR fork (2) | |
a5458d49 | 52 | and |
10069ed0 | 53 | .BR exec (3), |
a5458d49 | 54 | with some optional housekeeping steps in the child process before the |
10069ed0 MK |
55 | .BR exec (3). |
56 | These functions are not meant to replace the | |
57 | .BR fork (2) | |
58 | and | |
59 | .BR execve (2) | |
60 | system calls. | |
61 | In fact, they provide only a subset of the functionality | |
62 | that can be achieved by using the system calls. | |
847e0d88 | 63 | .PP |
10069ed0 MK |
64 | The only difference between |
65 | .BR posix_spawn () | |
66 | and | |
67 | .BR posix_spawnp () | |
68 | is the manner in which they specify the file to be executed by | |
69 | the child process. | |
70 | With | |
71 | .BR posix_spawn (), | |
72 | the executable file is specified as a pathname | |
73 | (which can be absolute or relative). | |
74 | With | |
75 | .BR posix_spawnp (), | |
76 | the executable file is specified as a simple filename; | |
77 | the system searches for this file in the list of directories specified by | |
1ae6b2c7 | 78 | .B PATH |
10069ed0 MK |
79 | (in the same way as for |
80 | .BR execvp (3)). | |
81 | For the remainder of this page, the discussion is phrased in terms of | |
82 | .BR posix_spawn (), | |
83 | with the understanding that | |
cf3ecd87 | 84 | .BR posix_spawnp () |
10069ed0 | 85 | differs only on the point just described. |
847e0d88 | 86 | .PP |
10069ed0 | 87 | The remaining arguments to these two functions are as follows: |
4279e42d | 88 | .TP |
a5458d49 | 89 | .I pid |
4279e42d | 90 | points to a buffer that is used to return the process ID |
10069ed0 | 91 | of the new child process. |
4279e42d | 92 | .TP |
10069ed0 | 93 | .I file_actions |
4279e42d | 94 | points to a |
10069ed0 MK |
95 | .I "spawn file actions object" |
96 | that specifies file-related actions to be performed in the child | |
97 | between the | |
98 | .BR fork (2) | |
99 | and | |
100 | .BR exec (3) | |
101 | steps. | |
102 | This object is initialized and populated before the | |
103 | .BR posix_spawn () | |
104 | call using | |
105 | .BR posix_spawn_file_actions_init (3) | |
106 | and the | |
107 | .BR posix_spawn_file_actions_* () | |
108 | functions. | |
4279e42d | 109 | .TP |
10069ed0 | 110 | .I attrp |
4279e42d | 111 | points to an |
10069ed0 MK |
112 | .I attributes objects |
113 | that specifies various attributes of the created child process. | |
114 | This object is initialized and populated before the | |
115 | .BR posix_spawn () | |
116 | call using | |
117 | .BR posix_spawnattr_init (3) | |
118 | and the | |
119 | .BR posix_spawnattr_* () | |
120 | functions. | |
4279e42d | 121 | .TP |
10069ed0 | 122 | .I argv |
4279e42d | 123 | .TQ |
10069ed0 | 124 | .I envp |
4279e42d | 125 | specify the argument list and environment for the program |
10069ed0 MK |
126 | that is executed in the child process, as for |
127 | .BR execve (2). | |
128 | .PP | |
129 | Below, the functions are described in terms of a three-step process: the | |
6614e292 | 130 | .BR fork () |
10069ed0 MK |
131 | step, the |
132 | .RB pre- exec () | |
133 | step (executed in the child), | |
134 | and the | |
135 | .BR exec () | |
136 | step (executed in the child). | |
137 | .SS fork() step | |
0c76bb72 | 138 | Since glibc 2.24, the |
10069ed0 MK |
139 | .BR posix_spawn () |
140 | function commences by calling | |
0c76bb72 OG |
141 | .BR clone (2) |
142 | with | |
1ae6b2c7 | 143 | .B CLONE_VM |
0c76bb72 | 144 | and |
1ae6b2c7 | 145 | .B CLONE_VFORK |
0c76bb72 OG |
146 | flags. |
147 | Older implementations use | |
10069ed0 MK |
148 | .BR fork (2), |
149 | or possibly | |
150 | .BR vfork (2) | |
151 | (see below). | |
847e0d88 | 152 | .PP |
10069ed0 MK |
153 | The PID of the new child process is placed in |
154 | .IR *pid . | |
155 | The | |
156 | .BR posix_spawn () | |
157 | function then returns control to the parent process. | |
847e0d88 | 158 | .PP |
10069ed0 MK |
159 | Subsequently, the parent can use one of the system calls described in |
160 | .BR wait (2) | |
161 | to check the status of the child process. | |
162 | If the child fails in any of the housekeeping steps described below, | |
163 | or fails to execute the desired file, | |
164 | it exits with a status of 127. | |
847e0d88 | 165 | .PP |
0c76bb72 | 166 | Before glibc 2.24, the child process is created using |
10069ed0 MK |
167 | .BR vfork (2) |
168 | instead of | |
169 | .BR fork (2) | |
170 | when either of the following is true: | |
22356d97 | 171 | .IP \(bu 3 |
a5458d49 BG |
172 | the |
173 | .I spawn-flags | |
10069ed0 MK |
174 | element of the attributes object pointed to by |
175 | .I attrp | |
176 | contains the GNU-specific flag | |
177 | .BR POSIX_SPAWN_USEVFORK ; | |
178 | or | |
22356d97 | 179 | .IP \(bu |
a5458d49 | 180 | .I file_actions |
10069ed0 MK |
181 | is NULL and the |
182 | .I spawn-flags | |
183 | element of the attributes object pointed to by | |
184 | .I attrp | |
185 | does \fInot\fP contain | |
186 | .BR POSIX_SPAWN_SETSIGMASK , | |
187 | .BR POSIX_SPAWN_SETSIGDEF , | |
188 | .BR POSIX_SPAWN_SETSCHEDPARAM , | |
189 | .BR POSIX_SPAWN_SETSCHEDULER , | |
190 | .BR POSIX_SPAWN_SETPGROUP , | |
191 | or | |
192 | .BR POSIX_SPAWN_RESETIDS . | |
dd3568a1 | 193 | .PP |
10069ed0 MK |
194 | In other words, |
195 | .BR vfork (2) | |
196 | is used if the caller requests it, | |
197 | or if there is no cleanup expected in the child before it | |
198 | .BR exec (3)s | |
a5458d49 | 199 | the requested file. |
10069ed0 | 200 | .SS pre-exec() step: housekeeping |
a5458d49 | 201 | In between the |
1ae6b2c7 | 202 | .B fork() |
a5458d49 | 203 | and the |
1ae6b2c7 | 204 | .B exec() |
0b78e0f5 | 205 | steps, a child process may need to perform a set of housekeeping actions. |
10069ed0 MK |
206 | The |
207 | .BR posix_spawn () | |
a5458d49 BG |
208 | and |
209 | .BR posix_spawnp () | |
10069ed0 MK |
210 | functions support a small, well-defined set of system tasks that the child |
211 | process can accomplish before it executes the executable file. | |
212 | These operations are controlled by the attributes object pointed to by | |
1ae6b2c7 | 213 | .I attrp |
10069ed0 | 214 | and the file actions object pointed to by |
82b43a76 | 215 | .IR file_actions . |
a5458d49 | 216 | In the child, processing is done in the following sequence: |
22356d97 | 217 | .IP (1) 5 |
10069ed0 MK |
218 | Process attribute actions: signal mask, signal default handlers, |
219 | scheduling algorithm and parameters, | |
220 | process group, and effective user and group IDs | |
221 | are changed as specified by the attributes object pointed to by | |
222 | .IR attrp . | |
22356d97 | 223 | .IP (2) |
a5458d49 BG |
224 | File actions, as specified in the |
225 | .I file_actions | |
10069ed0 MK |
226 | argument, |
227 | are performed in the order that they were specified using calls to the | |
228 | .BR posix_spawn_file_actions_add* () | |
229 | functions. | |
22356d97 | 230 | .IP (3) |
10069ed0 MK |
231 | File descriptors with the |
232 | .B FD_CLOEXEC | |
233 | flag set are closed. | |
dd3568a1 | 234 | .PP |
10069ed0 MK |
235 | All process attributes in the child, |
236 | other than those affected by attributes specified in the | |
237 | object pointed to by | |
1ae6b2c7 | 238 | .I attrp |
10069ed0 MK |
239 | and the file actions in the object pointed to by |
240 | .IR file_actions , | |
241 | will be affected as though the child was created with | |
242 | .BR fork (2) | |
243 | and it executed the program with | |
244 | .BR execve (2). | |
847e0d88 | 245 | .PP |
10069ed0 MK |
246 | The process attributes actions are defined by the attributes object |
247 | pointed to by | |
248 | .IR attrp . | |
249 | The | |
a5458d49 | 250 | .I spawn-flags |
10069ed0 MK |
251 | attribute (set using |
252 | .BR posix_spawnattr_setflags (3)) | |
253 | controls the general actions that occur, | |
254 | and other attributes in the object specify values | |
255 | to be used during those actions. | |
dd3568a1 | 256 | .PP |
10069ed0 | 257 | The effects of the flags that may be specified in |
1ae6b2c7 | 258 | .I spawn-flags |
10069ed0 | 259 | are as follows: |
0019177e | 260 | .TP |
10069ed0 MK |
261 | .B POSIX_SPAWN_SETSIGMASK |
262 | Set the signal mask to the signal set specified in the | |
a5458d49 | 263 | .I spawn-sigmask |
82b43a76 MK |
264 | attribute |
265 | .\" FIXME . | |
266 | .\" (see | |
267 | .\" .BR posix_spawnattr_setsigmask (3)) | |
10069ed0 MK |
268 | of the object pointed to by |
269 | .IR attrp . | |
270 | If the | |
271 | .B POSIX_SPAWN_SETSIGMASK | |
272 | flag is not set, then the child inherits the parent's signal mask. | |
273 | .TP | |
274 | .B POSIX_SPAWN_SETSIGDEF | |
275 | Reset the disposition of all signals in the set specified in the | |
a5458d49 | 276 | .I spawn-sigdefault |
82b43a76 MK |
277 | attribute |
278 | .\" FIXME . | |
279 | .\" (see | |
280 | .\" .BR posix_spawnattr_setsigdefault (3)) | |
10069ed0 | 281 | of the object pointed to by |
1ae6b2c7 | 282 | .I attrp |
10069ed0 MK |
283 | to the default. |
284 | For the treatment of the dispositions of signals not specified in the | |
285 | .I spawn-sigdefault | |
286 | attribute, or the treatment when | |
287 | .B POSIX_SPAWN_SETSIGDEF | |
288 | is not specified, see | |
289 | .BR execve (2). | |
290 | .TP | |
291 | .B POSIX_SPAWN_SETSCHEDPARAM | |
292 | .\" (POSIX_PRIORITY_SCHEDULING only) | |
293 | If this flag is set, and the | |
294 | .B POSIX_SPAWN_SETSCHEDULER | |
295 | flag is not set, then set the scheduling parameters | |
a5458d49 BG |
296 | to the parameters specified in the |
297 | .I spawn-schedparam | |
82b43a76 MK |
298 | attribute |
299 | .\" FIXME . | |
300 | .\" (see | |
301 | .\" .BR posix_spawnattr_setschedparam (3)) | |
10069ed0 MK |
302 | of the object pointed to by |
303 | .IR attrp . | |
304 | .TP | |
305 | .B POSIX_SPAWN_SETSCHEDULER | |
306 | Set the scheduling policy algorithm and parameters of the child, | |
307 | as follows: | |
308 | .RS | |
22356d97 | 309 | .IP \(bu 3 |
10069ed0 | 310 | The scheduling policy is set to the value specified in the |
a5458d49 | 311 | .I spawn-schedpolicy |
82b43a76 MK |
312 | attribute |
313 | .\" FIXME . | |
314 | .\" (see | |
315 | .\" .BR posix_spawnattr_setpolicy (3)) | |
10069ed0 MK |
316 | of the object pointed to by |
317 | .IR attrp . | |
22356d97 | 318 | .IP \(bu |
82b43a76 | 319 | The scheduling parameters are set to the value specified in the |
10069ed0 | 320 | .I spawn-schedparam |
82b43a76 MK |
321 | attribute |
322 | .\" FIXME . | |
323 | .\" (see | |
324 | .\" .BR posix_spawnattr_setschedparam (3)) | |
10069ed0 | 325 | of the object pointed to by |
1ae6b2c7 | 326 | .I attrp |
82b43a76 | 327 | (but see BUGS). |
dd3568a1 | 328 | .PP |
10069ed0 MK |
329 | If the |
330 | .B POSIX_SPAWN_SETSCHEDPARAM | |
a5458d49 | 331 | and |
10069ed0 MK |
332 | .B POSIX_SPAWN_SETSCHEDPOLICY |
333 | flags are not specified, | |
334 | the child inherits the corresponding scheduling attributes from the parent. | |
10069ed0 MK |
335 | .RE |
336 | .TP | |
337 | .B POSIX_SPAWN_RESETIDS | |
338 | If this flag is set, | |
339 | reset the effective UID and GID to the | |
340 | real UID and GID of the parent process. | |
341 | If this flag is not set, | |
342 | then the child retains the effective UID and GID of the parent. | |
343 | In either case, if the set-user-ID and set-group-ID permission | |
344 | bits are enabled on the executable file, their effect will override | |
345 | the setting of the effective UID and GID (se | |
346 | .BR execve (2)). | |
347 | .TP | |
348 | .B POSIX_SPAWN_SETPGROUP | |
349 | Set the process group to the value specified in the | |
350 | .I spawn-pgroup | |
82b43a76 MK |
351 | attribute |
352 | .\" FIXME . | |
353 | .\" (see | |
354 | .\" .BR posix_spawnattr_setpgroup (3)) | |
10069ed0 MK |
355 | of the object pointed to by |
356 | .IR attrp . | |
357 | If the | |
358 | .I spawn-pgroup | |
359 | attribute has the value 0, | |
360 | the child's process group ID is made the same as its process ID. | |
361 | If the | |
362 | .B POSIX_SPAWN_SETPGROUP | |
363 | flag is not set, the child inherits the parent's process group ID. | |
8b5b47e9 OG |
364 | .TP |
365 | .B POSIX_SPAWN_USEVFORK | |
366 | Since glibc 2.24, this flag has no effect. | |
367 | On older implementations, setting this flag forces the | |
1ae6b2c7 | 368 | .B fork() |
8b5b47e9 OG |
369 | step to use |
370 | .BR vfork (2) | |
371 | instead of | |
372 | .BR fork (2). | |
373 | The | |
374 | .B _GNU_SOURCE | |
90d83c61 | 375 | feature test macro must be defined to obtain the definition of this constant. |
fa0d6e64 OG |
376 | .TP |
377 | .BR POSIX_SPAWN_SETSID " (since glibc 2.26)" | |
378 | If this flag is set, | |
379 | the child process shall create a new session and become the session leader. | |
380 | The child process shall also become the process group leader of the new process | |
381 | group in the session (see | |
382 | .BR setsid (2)). | |
383 | The | |
384 | .B _GNU_SOURCE | |
90d83c61 | 385 | feature test macro must be defined to obtain the definition of this constant. |
fa0d6e64 OG |
386 | .\" This flag has been accepted in POSIX, see: |
387 | .\" http://austingroupbugs.net/view.php?id=1044 | |
388 | .\" and has been implemented in glibc since version 2.26 | |
389 | .\" commit daeb1fa2e1b33323e719015f5f546988bd4cc73b | |
dd3568a1 | 390 | .PP |
10069ed0 MK |
391 | If |
392 | .I attrp | |
393 | is NULL, then the default behaviors described above for each flag apply. | |
394 | .\" mtk: I think we probably don't want to say the following, since it | |
395 | .\" could lead people to do the wrong thing | |
396 | .\" The POSIX standard tells you to call | |
397 | .\" this function to de-initialize the attributes object pointed to by | |
398 | .\" .I attrp | |
399 | .\" when you are done with it; | |
400 | .\" however, on Linux systems this operation is a no-op. | |
847e0d88 | 401 | .PP |
10069ed0 | 402 | The |
a5458d49 | 403 | .I file_actions |
10069ed0 MK |
404 | argument specifies a sequence of file operations |
405 | that are performed in the child process after | |
406 | the general processing described above, and before it performs the | |
407 | .BR exec (3). | |
a5458d49 BG |
408 | If |
409 | .I file_actions | |
410 | is NULL, then no special action is taken, and standard | |
10069ed0 | 411 | .BR exec (3) |
6b469e24 | 412 | semantics apply\(emfile descriptors open before the exec |
10069ed0 MK |
413 | remain open in the new process, |
414 | except those for which the | |
415 | .B FD_CLOEXEC | |
416 | flag has been set. | |
417 | File locks remain in place. | |
dd3568a1 | 418 | .PP |
a5458d49 BG |
419 | If |
420 | .I file_actions | |
10069ed0 MK |
421 | is not NULL, then it contains an ordered set of requests to |
422 | .BR open (2), | |
423 | .BR close (2), | |
a5458d49 | 424 | and |
10069ed0 | 425 | .BR dup2 (2) |
a5458d49 BG |
426 | files. |
427 | These requests are added to the | |
428 | .I file_actions | |
429 | by | |
10069ed0 MK |
430 | .BR posix_spawn_file_actions_addopen (3), |
431 | .BR posix_spawn_file_actions_addclose (3), | |
a5458d49 | 432 | and |
10069ed0 | 433 | .BR posix_spawn_file_actions_adddup2 (3). |
a5458d49 | 434 | The requested operations are performed in the order they were added to |
10069ed0 | 435 | .IR file_actions . |
82b43a76 | 436 | .\" FIXME . I think the following is best placed in the |
10069ed0 MK |
437 | .\" posix_spawn_file_actions_adddup2(3) page, and a similar statement is |
438 | .\" also needed in posix_spawn_file_actions_addclose(3) | |
439 | .\" Note that you can specify file descriptors in | |
440 | .\" .I posix_spawn_file_actions_adddup2 (3) | |
441 | .\" which would not be usable if you called | |
442 | .\" .BR dup2 (2) | |
443 | .\" at that time--i.e., file descriptors that are opened or | |
444 | .\" closed by the earlier operations | |
445 | .\" added to | |
446 | .\" .I file_actions . | |
847e0d88 | 447 | .PP |
10069ed0 MK |
448 | If any of the housekeeping actions fails |
449 | (due to bogus values being passed or other reasons why signal handling, | |
450 | process scheduling, process group ID functions, | |
451 | and file descriptor operations might fail), | |
452 | the child process exits with exit value 127. | |
453 | .SS exec() step | |
454 | Once the child has successfully forked and performed | |
455 | all requested pre-exec steps, | |
a5458d49 | 456 | the child runs the requested executable. |
dd3568a1 | 457 | .PP |
a5458d49 BG |
458 | The child process takes its environment from the |
459 | .I envp | |
10069ed0 MK |
460 | argument, which is interpreted as if it had been passed to |
461 | .BR execve (2). | |
a5458d49 BG |
462 | The arguments to the created process come from the |
463 | .I argv | |
10069ed0 MK |
464 | argument, which is processed as for |
465 | .BR execve (2). | |
a5458d49 | 466 | .SH RETURN VALUE |
a5458d49 BG |
467 | Upon successful completion, |
468 | .BR posix_spawn () | |
469 | and | |
470 | .BR posix_spawnp () | |
10069ed0 MK |
471 | place the PID of the child process in |
472 | .IR pid , | |
a5458d49 | 473 | and return 0. |
0b78e0f5 | 474 | If there is an error during the |
1ae6b2c7 | 475 | .B fork() |
157d398b | 476 | step, |
10069ed0 MK |
477 | then no child is created, |
478 | the contents of | |
1ae6b2c7 | 479 | .I *pid |
10069ed0 MK |
480 | are unspecified, |
481 | and these functions return an error number as described below. | |
847e0d88 | 482 | .PP |
10069ed0 MK |
483 | Even when these functions return a success status, |
484 | the child process may still fail for a plethora of reasons related to its | |
485 | pre-\fBexec\fR() initialization. | |
486 | In addition, the | |
487 | .BR exec (3) | |
488 | may fail. | |
489 | In all of these cases, the child process will exit with the exit value of 127. | |
a5458d49 | 490 | .SH ERRORS |
10069ed0 | 491 | The |
a5458d49 BG |
492 | .BR posix_spawn () |
493 | and | |
494 | .BR posix_spawnp () | |
10069ed0 | 495 | functions fail only in the case where the underlying |
0c76bb72 | 496 | .BR fork (2), |
aa0da2b9 | 497 | .BR vfork (2), |
0c76bb72 OG |
498 | or |
499 | .BR clone (2) | |
10069ed0 MK |
500 | call fails; in these cases, these functions return an error number, |
501 | which will be one of the errors described for | |
0c76bb72 | 502 | .BR fork (2), |
aa0da2b9 | 503 | .BR vfork (2), |
a5458d49 | 504 | or |
0c76bb72 | 505 | .BR clone (2). |
dd3568a1 | 506 | .PP |
10069ed0 | 507 | In addition, these functions fail if: |
a5458d49 BG |
508 | .TP |
509 | .B ENOSYS | |
510 | Function not supported on this system. | |
9c78ec5b MK |
511 | .SH VERSIONS |
512 | The | |
513 | .BR posix_spawn () | |
514 | and | |
515 | .BR posix_spawnp () | |
516 | functions are available since glibc 2.2. | |
3113c7f3 | 517 | .SH STANDARDS |
9c78ec5b MK |
518 | POSIX.1-2001, POSIX.1-2008. |
519 | .\" FIXME . This piece belongs in spawnattr_setflags(3) | |
520 | .\" The | |
521 | .\" .B POSIX_SPAWN_USEVFORK | |
522 | .\" flag is a GNU extension; the | |
523 | .\" .B _GNU_SOURCE | |
524 | .\" feature test macro must be defined (before including any header files) | |
525 | .\" to obtain the definition of this constant. | |
a5458d49 | 526 | .SH NOTES |
10069ed0 MK |
527 | The housekeeping activities in the child are controlled by |
528 | the objects pointed to by | |
529 | .I attrp | |
530 | (for non-file actions) and | |
531 | .I file_actions | |
532 | In POSIX parlance, the | |
a5458d49 | 533 | .I posix_spawnattr_t |
10069ed0 MK |
534 | and |
535 | .I posix_spawn_file_actions_t | |
536 | data types are referred to as objects, | |
537 | and their elements are not specified by name. | |
538 | Portable programs should initialize these objects using | |
539 | only the POSIX-specified functions. | |
540 | (In other words, | |
541 | although these objects may be implemented as structures containing fields, | |
542 | portable programs must avoid dependence on such implementation details.) | |
847e0d88 | 543 | .PP |
0c76bb72 | 544 | According to POSIX, it is unspecified whether fork handlers established with |
10069ed0 MK |
545 | .BR pthread_atfork (3) |
546 | are called when | |
547 | .BR posix_spawn () | |
548 | is invoked. | |
0c76bb72 | 549 | Since glibc 2.24, the fork handlers are not executed in any case. |
10069ed0 | 550 | .\" Tested on glibc 2.12 |
0c76bb72 | 551 | On older implementations, |
10069ed0 MK |
552 | fork handlers are called only if the child is created using |
553 | .BR fork (2). | |
847e0d88 | 554 | .PP |
53562047 MK |
555 | There is no "posix_fspawn" function (i.e., a function that is to |
556 | .BR posix_spawn () | |
557 | as | |
558 | .BR fexecve (3) | |
559 | is to | |
560 | .BR execve (2)). | |
561 | However, this functionality can be obtained by specifying the | |
562 | .I path | |
563 | argument as one of the files in the caller's | |
1ae6b2c7 | 564 | .I /proc/self/fd |
53562047 | 565 | directory. |
82b43a76 MK |
566 | .SH BUGS |
567 | POSIX.1 says that when | |
568 | .B POSIX_SPAWN_SETSCHEDULER | |
569 | is specified in | |
570 | .IR spawn-flags , | |
571 | then the | |
572 | .B POSIX_SPAWN_SETSCHEDPARAM | |
573 | (if present) is ignored. | |
574 | However, before glibc 2.14, calls to | |
575 | .BR posix_spawn () | |
576 | failed with an error if | |
577 | .\" http://sourceware.org/bugzilla/show_bug.cgi?id=12052 | |
1ae6b2c7 | 578 | .B POSIX_SPAWN_SETSCHEDULER |
82b43a76 MK |
579 | was specified without also specifying |
580 | .BR POSIX_SPAWN_SETSCHEDPARAM . | |
a14af333 | 581 | .SH EXAMPLES |
10069ed0 MK |
582 | The program below demonstrates the use of various functions in the |
583 | POSIX spawn API. | |
584 | The program accepts command-line attributes that can be used | |
585 | to create file actions and attributes objects. | |
586 | The remaining command-line arguments are used as the executable name | |
587 | and command-line arguments of the program that is executed in the child. | |
847e0d88 | 588 | .PP |
10069ed0 MK |
589 | In the first run, the |
590 | .BR date (1) | |
591 | command is executed in the child, and the | |
592 | .BR posix_spawn () | |
593 | call employs no file actions or attributes objects. | |
bdd915e2 | 594 | .PP |
161b8eda | 595 | .in +4n |
bdd915e2 | 596 | .EX |
10069ed0 MK |
597 | $ \fB./a.out date\fP |
598 | PID of child: 7634 | |
599 | Tue Feb 1 19:47:50 CEST 2011 | |
600 | Child status: exited, status=0 | |
bdd915e2 | 601 | .EE |
10069ed0 | 602 | .in |
bdd915e2 | 603 | .PP |
10069ed0 MK |
604 | In the next run, the |
605 | .I \-c | |
606 | command-line option is used to create a file actions object that closes | |
607 | standard output in the child. | |
608 | Consequently, | |
609 | .BR date (1) | |
610 | fails when trying to perform output and exits with a status of 1. | |
bdd915e2 | 611 | .PP |
161b8eda | 612 | .in +4n |
bdd915e2 | 613 | .EX |
86d93b3e | 614 | $ \fB./a.out \-c date\fP |
10069ed0 MK |
615 | PID of child: 7636 |
616 | date: write error: Bad file descriptor | |
617 | Child status: exited, status=1 | |
bdd915e2 | 618 | .EE |
10069ed0 | 619 | .in |
bdd915e2 | 620 | .PP |
10069ed0 MK |
621 | In the next run, the |
622 | .I \-s | |
623 | command-line option is used to create an attributes object that | |
624 | specifies that all (blockable) signals in the child should be blocked. | |
625 | Consequently, trying to kill child with the default signal sent by | |
626 | .BR kill (1) | |
627 | (i.e., | |
628 | .BR SIGTERM ) | |
629 | fails, because that signal is blocked. | |
630 | Therefore, to kill the child, | |
1ae6b2c7 | 631 | .B SIGKILL |
10069ed0 MK |
632 | is necessary |
633 | .RB ( SIGKILL | |
634 | can't be blocked). | |
bdd915e2 | 635 | .PP |
161b8eda | 636 | .in +4n |
bdd915e2 | 637 | .EX |
86d93b3e | 638 | $ \fB./a.out \-s sleep 60 &\fP |
10069ed0 MK |
639 | [1] 7637 |
640 | $ PID of child: 7638 | |
641 | ||
642 | $ \fBkill 7638\fP | |
86d93b3e | 643 | $ \fBkill \-KILL 7638\fP |
10069ed0 | 644 | $ Child status: killed by signal 9 |
86d93b3e | 645 | [1]+ Done ./a.out \-s sleep 60 |
bdd915e2 | 646 | .EE |
10069ed0 | 647 | .in |
bdd915e2 | 648 | .PP |
10069ed0 MK |
649 | When we try to execute a nonexistent command in the child, the |
650 | .BR exec (3) | |
651 | fails and the child exits with a status of 127. | |
bdd915e2 | 652 | .PP |
161b8eda | 653 | .in +4n |
bdd915e2 | 654 | .EX |
10069ed0 MK |
655 | $ \fB./a.out xxxxx |
656 | PID of child: 10190 | |
657 | Child status: exited, status=127 | |
bdd915e2 | 658 | .EE |
10069ed0 | 659 | .in |
7b5e3ad5 | 660 | .SS Program source |
c7885256 | 661 | \& |
b0b6ab4e | 662 | .\" SRC BEGIN (posix_spawn.c) |
e7d0bb47 | 663 | .EX |
ad3868f0 | 664 | #include <errno.h> |
10069ed0 | 665 | #include <spawn.h> |
8eb90116 | 666 | #include <stdint.h> |
10069ed0 | 667 | #include <stdio.h> |
10069ed0 MK |
668 | #include <stdlib.h> |
669 | #include <string.h> | |
ad3868f0 | 670 | #include <unistd.h> |
10069ed0 | 671 | #include <wait.h> |
10069ed0 | 672 | |
d1a71985 | 673 | #define errExit(msg) do { perror(msg); \e |
10069ed0 MK |
674 | exit(EXIT_FAILURE); } while (0) |
675 | ||
d1a71985 MK |
676 | #define errExitEN(en, msg) \e |
677 | do { errno = en; perror(msg); \e | |
10069ed0 MK |
678 | exit(EXIT_FAILURE); } while (0) |
679 | ||
680 | char **environ; | |
681 | ||
682 | int | |
683 | main(int argc, char *argv[]) | |
684 | { | |
685 | pid_t child_pid; | |
686 | int s, opt, status; | |
687 | sigset_t mask; | |
688 | posix_spawnattr_t attr; | |
689 | posix_spawnattr_t *attrp; | |
690 | posix_spawn_file_actions_t file_actions; | |
691 | posix_spawn_file_actions_t *file_actionsp; | |
692 | ||
693 | /* Parse command\-line options, which can be used to specify an | |
694 | attributes object and file actions object for the child. */ | |
695 | ||
696 | attrp = NULL; | |
697 | file_actionsp = NULL; | |
698 | ||
699 | while ((opt = getopt(argc, argv, "sc")) != \-1) { | |
700 | switch (opt) { | |
701 | case \(aqc\(aq: /* \-c: close standard output in child */ | |
702 | ||
703 | /* Create a file actions object and add a "close" | |
c6beb8a1 | 704 | action to it. */ |
10069ed0 MK |
705 | |
706 | s = posix_spawn_file_actions_init(&file_actions); | |
707 | if (s != 0) | |
708 | errExitEN(s, "posix_spawn_file_actions_init"); | |
709 | ||
710 | s = posix_spawn_file_actions_addclose(&file_actions, | |
711 | STDOUT_FILENO); | |
712 | if (s != 0) | |
713 | errExitEN(s, "posix_spawn_file_actions_addclose"); | |
714 | ||
715 | file_actionsp = &file_actions; | |
716 | break; | |
717 | ||
718 | case \(aqs\(aq: /* \-s: block all signals in child */ | |
719 | ||
720 | /* Create an attributes object and add a "set signal mask" | |
c6beb8a1 | 721 | action to it. */ |
10069ed0 MK |
722 | |
723 | s = posix_spawnattr_init(&attr); | |
724 | if (s != 0) | |
725 | errExitEN(s, "posix_spawnattr_init"); | |
726 | s = posix_spawnattr_setflags(&attr, POSIX_SPAWN_SETSIGMASK); | |
727 | if (s != 0) | |
728 | errExitEN(s, "posix_spawnattr_setflags"); | |
729 | ||
730 | sigfillset(&mask); | |
731 | s = posix_spawnattr_setsigmask(&attr, &mask); | |
732 | if (s != 0) | |
733 | errExitEN(s, "posix_spawnattr_setsigmask"); | |
734 | ||
735 | attrp = &attr; | |
736 | break; | |
737 | } | |
738 | } | |
739 | ||
740 | /* Spawn the child. The name of the program to execute and the | |
741 | command\-line arguments are taken from the command\-line arguments | |
742 | of this program. The environment of the program execed in the | |
743 | child is made the same as the parent\(aqs environment. */ | |
744 | ||
745 | s = posix_spawnp(&child_pid, argv[optind], file_actionsp, attrp, | |
746 | &argv[optind], environ); | |
747 | if (s != 0) | |
748 | errExitEN(s, "posix_spawn"); | |
749 | ||
c6beb8a1 | 750 | /* Destroy any objects that we created earlier. */ |
10069ed0 MK |
751 | |
752 | if (attrp != NULL) { | |
753 | s = posix_spawnattr_destroy(attrp); | |
754 | if (s != 0) | |
755 | errExitEN(s, "posix_spawnattr_destroy"); | |
756 | } | |
757 | ||
758 | if (file_actionsp != NULL) { | |
759 | s = posix_spawn_file_actions_destroy(file_actionsp); | |
760 | if (s != 0) | |
761 | errExitEN(s, "posix_spawn_file_actions_destroy"); | |
762 | } | |
763 | ||
8eb90116 | 764 | printf("PID of child: %jd\en", (intmax_t) child_pid); |
10069ed0 | 765 | |
c6beb8a1 | 766 | /* Monitor status of the child until it terminates. */ |
10069ed0 MK |
767 | |
768 | do { | |
769 | s = waitpid(child_pid, &status, WUNTRACED | WCONTINUED); | |
770 | if (s == \-1) | |
771 | errExit("waitpid"); | |
772 | ||
773 | printf("Child status: "); | |
774 | if (WIFEXITED(status)) { | |
d1a71985 | 775 | printf("exited, status=%d\en", WEXITSTATUS(status)); |
10069ed0 | 776 | } else if (WIFSIGNALED(status)) { |
d1a71985 | 777 | printf("killed by signal %d\en", WTERMSIG(status)); |
10069ed0 | 778 | } else if (WIFSTOPPED(status)) { |
d1a71985 | 779 | printf("stopped by signal %d\en", WSTOPSIG(status)); |
10069ed0 | 780 | } else if (WIFCONTINUED(status)) { |
d1a71985 | 781 | printf("continued\en"); |
10069ed0 MK |
782 | } |
783 | } while (!WIFEXITED(status) && !WIFSIGNALED(status)); | |
784 | ||
785 | exit(EXIT_SUCCESS); | |
786 | } | |
e7d0bb47 | 787 | .EE |
b0b6ab4e | 788 | .\" SRC END |
a5458d49 | 789 | .SH SEE ALSO |
10069ed0 MK |
790 | .nh \" Disable hyphenation |
791 | .ad l | |
a5458d49 BG |
792 | .BR close (2), |
793 | .BR dup2 (2), | |
794 | .BR execl (2), | |
795 | .BR execlp (2), | |
796 | .BR fork (2), | |
797 | .BR open (2), | |
798 | .BR sched_setparam (2), | |
799 | .BR sched_setscheduler (2), | |
800 | .BR setpgid (2), | |
801 | .BR setuid (2), | |
802 | .BR sigaction (2), | |
10069ed0 MK |
803 | .BR sigprocmask (2), |
804 | .BR posix_spawn_file_actions_addclose (3), | |
805 | .BR posix_spawn_file_actions_adddup2 (3), | |
806 | .BR posix_spawn_file_actions_addopen (3), | |
807 | .BR posix_spawn_file_actions_destroy (3), | |
808 | .BR posix_spawn_file_actions_init (3), | |
a5458d49 BG |
809 | .BR posix_spawnattr_destroy (3), |
810 | .BR posix_spawnattr_getflags (3), | |
811 | .BR posix_spawnattr_getpgroup (3), | |
812 | .BR posix_spawnattr_getschedparam (3), | |
813 | .BR posix_spawnattr_getschedpolicy (3), | |
814 | .BR posix_spawnattr_getsigdefault (3), | |
815 | .BR posix_spawnattr_getsigmask (3), | |
816 | .BR posix_spawnattr_init (3), | |
817 | .BR posix_spawnattr_setflags (3), | |
818 | .BR posix_spawnattr_setpgroup (3), | |
819 | .BR posix_spawnattr_setschedparam (3), | |
820 | .BR posix_spawnattr_setschedpolicy (3), | |
821 | .BR posix_spawnattr_setsigdefault (3), | |
822 | .BR posix_spawnattr_setsigmask (3), | |
a5458d49 | 823 | .BR pthread_atfork (3), |
d8012462 | 824 | .IR <spawn.h> , |
10069ed0 | 825 | Base Definitions volume of POSIX.1-2001, |
a5458d49 | 826 | .I http://www.opengroup.org/unix/online.html |