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