1POSIX_SPAWN(3)             Linux Programmer's Manual            POSIX_SPAWN(3)
2
3
4

NAME

6       posix_spawn, posix_spawnp - spawn a process
7

SYNOPSIS

9       #include <spawn.h>
10
11       int posix_spawn(pid_t *pid, const char *path,
12                       const posix_spawn_file_actions_t *file_actions,
13                       const posix_spawnattr_t *attrp,
14                       char *const argv[], char *const envp[]);
15
16       int posix_spawnp(pid_t *pid, const char *file,
17                        const posix_spawn_file_actions_t *file_actions,
18                        const posix_spawnattr_t *attrp,
19                        char *const argv[], char *const envp[]);
20

DESCRIPTION

22       The posix_spawn() and posix_spawnp() functions are used to create a new
23       child process that executes a specified  file.   These  functions  were
24       specified  by  POSIX  to  provide a standardized method of creating new
25       processes on machines that lack the capability to support  the  fork(2)
26       system  call.   These  machines  are  generally small, embedded systems
27       lacking MMU support.
28
29       The posix_spawn() and posix_spawnp() functions provide the  functional‐
30       ity  of a combined fork(2) and exec(3), with some optional housekeeping
31       steps in the child process before the exec(3).  These functions are not
32       meant to replace the fork(2) and execve(2) system calls.  In fact, they
33       provide only a subset of the functionality that can be achieved by  us‐
34       ing the system calls.
35
36       The  only  difference  between  posix_spawn() and posix_spawnp() is the
37       manner in which they specify the file  to  be  executed  by  the  child
38       process.   With  posix_spawn(),  the  executable file is specified as a
39       pathname (which can be absolute or relative).  With posix_spawnp(), the
40       executable  file is specified as a simple filename; the system searches
41       for this file in the list of directories specified by PATH (in the same
42       way  as for execvp(3)).  For the remainder of this page, the discussion
43       is phrased in terms  of  posix_spawn(),  with  the  understanding  that
44       posix_spawnp() differs only on the point just described.
45
46       The remaining arguments to these two functions are as follows:
47
48       *  The  pid  argument  points  to  a  buffer that is used to return the
49          process ID of the new child process.
50
51       *  The file_actions argument points to a spawn file actions object that
52          specifies  file-related actions to be performed in the child between
53          the fork(2) and exec(3) steps.  This object is initialized and popu‐
54          lated  before  the  posix_spawn()  call  using  posix_spawn_file_ac‐
55          tions_init(3) and the posix_spawn_file_actions_*() functions.
56
57       *  The attrp argument points to an attributes  objects  that  specifies
58          various  attributes  of  the  created child process.  This object is
59          initialized  and  populated  before  the  posix_spawn()  call  using
60          posix_spawnattr_init(3) and the posix_spawnattr_*() functions.
61
62       *  The  argv  and envp arguments specify the argument list and environ‐
63          ment for the program that is executed in the child process,  as  for
64          execve(2).
65
66       Below,  the  functions  are described in terms of a three-step process:
67       the fork() step, the pre-exec() step (executed in the child),  and  the
68       exec() step (executed in the child).
69
70   fork() step
71       Since  glibc  2.24,  the  posix_spawn()  function  commences by calling
72       clone(2) with CLONE_VM and CLONE_VFORK  flags.   Older  implementations
73       use fork(2), or possibly vfork(2) (see below).
74
75       The  PID of the new child process is placed in *pid.  The posix_spawn()
76       function then returns control to the parent process.
77
78       Subsequently, the parent can use one of the system calls  described  in
79       wait(2)  to  check the status of the child process.  If the child fails
80       in any of the housekeeping steps described below, or fails  to  execute
81       the desired file, it exits with a status of 127.
82
83       Before  glibc 2.24, the child process is created using vfork(2) instead
84       of fork(2) when either of the following is true:
85
86       *  the spawn-flags element of the attributes object pointed to by attrp
87          contains the GNU-specific flag POSIX_SPAWN_USEVFORK; or
88
89       *  file_actions  is  NULL and the spawn-flags element of the attributes
90          object pointed to by attrp does not contain  POSIX_SPAWN_SETSIGMASK,
91          POSIX_SPAWN_SETSIGDEF,                    POSIX_SPAWN_SETSCHEDPARAM,
92          POSIX_SPAWN_SETSCHEDULER, POSIX_SPAWN_SETPGROUP, or  POSIX_SPAWN_RE‐
93          SETIDS.
94
95       In other words, vfork(2) is used if the caller requests it, or if there
96       is no cleanup expected in the child before it  exec(3)s  the  requested
97       file.
98
99   pre-exec() step: housekeeping
100       In between the fork() and the exec() steps, a child process may need to
101       perform  a  set  of  housekeeping  actions.   The   posix_spawn()   and
102       posix_spawnp()  functions  support  a small, well-defined set of system
103       tasks that the child process can accomplish before it executes the exe‐
104       cutable file.  These operations are controlled by the attributes object
105       pointed to by attrp and the file actions object pointed to by  file_ac‐
106       tions.  In the child, processing is done in the following sequence:
107
108       1. Process  attribute  actions:  signal  mask, signal default handlers,
109          scheduling algorithm and parameters, process  group,  and  effective
110          user and group IDs are changed as specified by the attributes object
111          pointed to by attrp.
112
113       2. File actions, as specified in the file_actions  argument,  are  per‐
114          formed  in  the  order  that  they were specified using calls to the
115          posix_spawn_file_actions_add*() functions.
116
117       3. File descriptors with the FD_CLOEXEC flag set are closed.
118
119       All process attributes in the child, other than those affected  by  at‐
120       tributes  specified  in the object pointed to by attrp and the file ac‐
121       tions in the object pointed to by file_actions,  will  be  affected  as
122       though  the  child was created with fork(2) and it executed the program
123       with execve(2).
124
125       The process attributes actions are defined  by  the  attributes  object
126       pointed  to by attrp.  The spawn-flags attribute (set using posix_spaw‐
127       nattr_setflags(3)) controls the general actions that occur,  and  other
128       attributes  in  the  object  specify values to be used during those ac‐
129       tions.
130
131       The effects of the flags that may be specified in  spawn-flags  are  as
132       follows:
133
134       POSIX_SPAWN_SETSIGMASK
135              Set  the  signal  mask to the signal set specified in the spawn-
136              sigmask attribute of the object pointed to  by  attrp.   If  the
137              POSIX_SPAWN_SETSIGMASK  flag is not set, then the child inherits
138              the parent's signal mask.
139
140       POSIX_SPAWN_SETSIGDEF
141              Reset the disposition of all signals in the set specified in the
142              spawn-sigdefault  attribute of the object pointed to by attrp to
143              the default.  For the treatment of the dispositions  of  signals
144              not  specified  in the spawn-sigdefault attribute, or the treat‐
145              ment when POSIX_SPAWN_SETSIGDEF is not specified, see execve(2).
146
147       POSIX_SPAWN_SETSCHEDPARAM
148              If this flag is set, and the  POSIX_SPAWN_SETSCHEDULER  flag  is
149              not  set,  then  set the scheduling parameters to the parameters
150              specified  in  the  spawn-schedparam  attribute  of  the  object
151              pointed to by attrp.
152
153       POSIX_SPAWN_SETSCHEDULER
154              Set the scheduling policy algorithm and parameters of the child,
155              as follows:
156
157              *  The scheduling policy is set to the value  specified  in  the
158                 spawn-schedpolicy  attribute  of the object pointed to by at‐
159                 trp.
160
161              *  The scheduling parameters are set to the value  specified  in
162                 the  spawn-schedparam  attribute  of the object pointed to by
163                 attrp (but see BUGS).
164
165              If the POSIX_SPAWN_SETSCHEDPARAM and  POSIX_SPAWN_SETSCHEDPOLICY
166              flags  are  not  specified, the child inherits the corresponding
167              scheduling attributes from the parent.
168
169       POSIX_SPAWN_RESETIDS
170              If this flag is set, reset the effective UID and GID to the real
171              UID  and  GID  of  the parent process.  If this flag is not set,
172              then the child retains the effective UID and GID of the  parent.
173              In  either  case, if the set-user-ID and set-group-ID permission
174              bits are enabled on the executable file, their effect will over‐
175              ride the setting of the effective UID and GID (se execve(2)).
176
177       POSIX_SPAWN_SETPGROUP
178              Set the process group to the value specified in the spawn-pgroup
179              attribute of the object pointed to  by  attrp.   If  the  spawn-
180              pgroup  attribute  has the value 0, the child's process group ID
181              is made the same as its process ID.   If  the  POSIX_SPAWN_SETP‐
182              GROUP  flag  is not set, the child inherits the parent's process
183              group ID.
184
185       POSIX_SPAWN_USEVFORK
186              Since glibc 2.24, this flag has no effect.  On older implementa‐
187              tions,  setting this flag forces the fork() step to use vfork(2)
188              instead of fork(2).  The _GNU_SOURCE feature test macro must  be
189              defined to obtain the definition of this constant.
190
191       POSIX_SPAWN_SETSID (since glibc 2.26)
192              If  this  flag is set, the child process shall create a new ses‐
193              sion and become the session leader.   The  child  process  shall
194              also become the process group leader of the new process group in
195              the session (see setsid(2)).  The _GNU_SOURCE feature test macro
196              must be defined to obtain the definition of this constant.
197
198       If  attrp  is NULL, then the default behaviors described above for each
199       flag apply.
200
201       The file_actions argument specifies a sequence of file operations  that
202       are  performed  in  the  child process after the general processing de‐
203       scribed above, and before it performs the exec(3).  If file_actions  is
204       NULL,  then  no special action is taken, and standard exec(3) semantics
205       apply—file descriptors open before the exec  remain  open  in  the  new
206       process, except those for which the FD_CLOEXEC flag has been set.  File
207       locks remain in place.
208
209       If file_actions is not NULL, then it contains an  ordered  set  of  re‐
210       quests  to  open(2),  close(2),  and dup2(2) files.  These requests are
211       added  to  the  file_actions  by   posix_spawn_file_actions_addopen(3),
212       posix_spawn_file_actions_addclose(3),  and posix_spawn_file_actions_ad‐
213       ddup2(3).  The requested operations are performed  in  the  order  they
214       were added to file_actions.
215
216       If  any  of  the  housekeeping actions fails (due to bogus values being
217       passed or  other  reasons  why  signal  handling,  process  scheduling,
218       process group ID functions, and file descriptor operations might fail),
219       the child process exits with exit value 127.
220
221   exec() step
222       Once the child has successfully forked and performed all requested pre-
223       exec steps, the child runs the requested executable.
224
225       The  child  process takes its environment from the envp argument, which
226       is interpreted as if it had been passed to execve(2).  The arguments to
227       the  created process come from the argv argument, which is processed as
228       for execve(2).
229

RETURN VALUE

231       Upon successful completion, posix_spawn() and posix_spawnp() place  the
232       PID  of  the  child process in pid, and return 0.  If there is an error
233       during the fork() step, then no child is created, the contents of  *pid
234       are  unspecified,  and  these  functions  return an error number as de‐
235       scribed below.
236
237       Even when these functions return a success status,  the  child  process
238       may still fail for a plethora of reasons related to its pre-exec() ini‐
239       tialization.  In addition, the exec(3)  may  fail.   In  all  of  these
240       cases, the child process will exit with the exit value of 127.
241

ERRORS

243       The  posix_spawn()  and  posix_spawnp() functions fail only in the case
244       where the underlying fork(2), vfork(2)  or  clone(2)  call  fails;   in
245       these  cases, these functions return an error number, which will be one
246       of the errors described for fork(2), vfork(2) or clone(2).
247
248       In addition, these functions fail if:
249
250       ENOSYS Function not supported on this system.
251

VERSIONS

253       The posix_spawn() and  posix_spawnp()  functions  are  available  since
254       glibc 2.2.
255

CONFORMING TO

257       POSIX.1-2001, POSIX.1-2008.
258

NOTES

260       The  housekeeping activities in the child are controlled by the objects
261       pointed to by attrp (for non-file actions) and  file_actions  In  POSIX
262       parlance,  the  posix_spawnattr_t  and  posix_spawn_file_actions_t data
263       types are referred to as objects, and their elements are not  specified
264       by  name.  Portable programs should initialize these objects using only
265       the POSIX-specified functions.  (In other words, although these objects
266       may  be  implemented as structures containing fields, portable programs
267       must avoid dependence on such implementation details.)
268
269       According to POSIX, it is unspecified whether fork handlers established
270       with pthread_atfork(3) are called when posix_spawn() is invoked.  Since
271       glibc 2.24, the fork handlers are not executed in any case.   On  older
272       implementations,  fork handlers are called only if the child is created
273       using fork(2).
274
275       There is no "posix_fspawn"  function  (i.e.,  a  function  that  is  to
276       posix_spawn()  as fexecve(3) is to execve(2)).  However, this function‐
277       ality can be obtained by specifying the path argument  as  one  of  the
278       files in the caller's /proc/self/fd directory.
279

BUGS

281       POSIX.1  says that when POSIX_SPAWN_SETSCHEDULER is specified in spawn-
282       flags, then the  POSIX_SPAWN_SETSCHEDPARAM  (if  present)  is  ignored.
283       However, before glibc 2.14, calls to posix_spawn() failed with an error
284       if  POSIX_SPAWN_SETSCHEDULER  was  specified  without  also  specifying
285       POSIX_SPAWN_SETSCHEDPARAM.
286

EXAMPLES

288       The  program  below  demonstrates  the  use of various functions in the
289       POSIX spawn API.  The program accepts command-line attributes that  can
290       be  used  to create file actions and attributes objects.  The remaining
291       command-line arguments are used as the executable name and command-line
292       arguments of the program that is executed in the child.
293
294       In the first run, the date(1) command is executed in the child, and the
295       posix_spawn() call employs no file actions or attributes objects.
296
297           $ ./a.out date
298           PID of child: 7634
299           Tue Feb  1 19:47:50 CEST 2011
300           Child status: exited, status=0
301
302       In the next run, the -c command-line option is used to  create  a  file
303       actions object that closes standard output in the child.  Consequently,
304       date(1) fails when trying to perform output and exits with a status  of
305       1.
306
307           $ ./a.out -c date
308           PID of child: 7636
309           date: write error: Bad file descriptor
310           Child status: exited, status=1
311
312       In  the  next  run, the -s command-line option is used to create an at‐
313       tributes object that specifies that  all  (blockable)  signals  in  the
314       child  should  be blocked.  Consequently, trying to kill child with the
315       default signal sent by kill(1) (i.e., SIGTERM) fails, because that sig‐
316       nal  is  blocked.   Therefore,  to kill the child, SIGKILL is necessary
317       (SIGKILL can't be blocked).
318
319           $ ./a.out -s sleep 60 &
320           [1] 7637
321           $ PID of child: 7638
322
323           $ kill 7638
324           $ kill -KILL 7638
325           $ Child status: killed by signal 9
326           [1]+  Done                    ./a.out -s sleep 60
327
328       When we try to execute a nonexistent command in the child, the  exec(3)
329       fails and the child exits with a status of 127.
330
331           $ ./a.out xxxxx
332           PID of child: 10190
333           Child status: exited, status=127
334
335   Program source
336
337       #include <spawn.h>
338       #include <stdint.h>
339       #include <stdio.h>
340       #include <unistd.h>
341       #include <stdlib.h>
342       #include <string.h>
343       #include <wait.h>
344       #include <errno.h>
345
346       #define errExit(msg)    do { perror(msg); \
347                                    exit(EXIT_FAILURE); } while (0)
348
349       #define errExitEN(en, msg) \
350                               do { errno = en; perror(msg); \
351                                    exit(EXIT_FAILURE); } while (0)
352
353       char **environ;
354
355       int
356       main(int argc, char *argv[])
357       {
358           pid_t child_pid;
359           int s, opt, status;
360           sigset_t mask;
361           posix_spawnattr_t attr;
362           posix_spawnattr_t *attrp;
363           posix_spawn_file_actions_t file_actions;
364           posix_spawn_file_actions_t *file_actionsp;
365
366           /* Parse command-line options, which can be used to specify an
367              attributes object and file actions object for the child. */
368
369           attrp = NULL;
370           file_actionsp = NULL;
371
372           while ((opt = getopt(argc, argv, "sc")) != -1) {
373               switch (opt) {
374               case 'c':       /* -c: close standard output in child */
375
376                   /* Create a file actions object and add a "close"
377                      action to it */
378
379                   s = posix_spawn_file_actions_init(&file_actions);
380                   if (s != 0)
381                       errExitEN(s, "posix_spawn_file_actions_init");
382
383                   s = posix_spawn_file_actions_addclose(&file_actions,
384                                                         STDOUT_FILENO);
385                   if (s != 0)
386                       errExitEN(s, "posix_spawn_file_actions_addclose");
387
388                   file_actionsp = &file_actions;
389                   break;
390
391               case 's':       /* -s: block all signals in child */
392
393                   /* Create an attributes object and add a "set signal mask"
394                      action to it */
395
396                   s = posix_spawnattr_init(&attr);
397                   if (s != 0)
398                       errExitEN(s, "posix_spawnattr_init");
399                   s = posix_spawnattr_setflags(&attr, POSIX_SPAWN_SETSIGMASK);
400                   if (s != 0)
401                       errExitEN(s, "posix_spawnattr_setflags");
402
403                   sigfillset(&mask);
404                   s = posix_spawnattr_setsigmask(&attr, &mask);
405                   if (s != 0)
406                       errExitEN(s, "posix_spawnattr_setsigmask");
407
408                   attrp = &attr;
409                   break;
410               }
411           }
412
413           /* Spawn the child. The name of the program to execute and the
414              command-line arguments are taken from the command-line arguments
415              of this program. The environment of the program execed in the
416              child is made the same as the parent's environment. */
417
418           s = posix_spawnp(&child_pid, argv[optind], file_actionsp, attrp,
419                            &argv[optind], environ);
420           if (s != 0)
421               errExitEN(s, "posix_spawn");
422
423           /* Destroy any objects that we created earlier */
424
425           if (attrp != NULL) {
426               s = posix_spawnattr_destroy(attrp);
427               if (s != 0)
428                   errExitEN(s, "posix_spawnattr_destroy");
429           }
430
431           if (file_actionsp != NULL) {
432               s = posix_spawn_file_actions_destroy(file_actionsp);
433               if (s != 0)
434                   errExitEN(s, "posix_spawn_file_actions_destroy");
435           }
436
437           printf("PID of child: %jd\n", (intmax_t) child_pid);
438
439           /* Monitor status of the child until it terminates */
440
441           do {
442               s = waitpid(child_pid, &status, WUNTRACED | WCONTINUED);
443               if (s == -1)
444                   errExit("waitpid");
445
446               printf("Child status: ");
447               if (WIFEXITED(status)) {
448                   printf("exited, status=%d\n", WEXITSTATUS(status));
449               } else if (WIFSIGNALED(status)) {
450                   printf("killed by signal %d\n", WTERMSIG(status));
451               } else if (WIFSTOPPED(status)) {
452                   printf("stopped by signal %d\n", WSTOPSIG(status));
453               } else if (WIFCONTINUED(status)) {
454                   printf("continued\n");
455               }
456           } while (!WIFEXITED(status) && !WIFSIGNALED(status));
457
458           exit(EXIT_SUCCESS);
459       }
460

SEE ALSO

462       close(2), dup2(2), execl(2), execlp(2), fork(2), open(2),
463       sched_setparam(2), sched_setscheduler(2), setpgid(2), setuid(2),
464       sigaction(2), sigprocmask(2), posix_spawn_file_actions_addclose(3),
465       posix_spawn_file_actions_adddup2(3),
466       posix_spawn_file_actions_addopen(3),
467       posix_spawn_file_actions_destroy(3), posix_spawn_file_actions_init(3),
468       posix_spawnattr_destroy(3), posix_spawnattr_getflags(3),
469       posix_spawnattr_getpgroup(3), posix_spawnattr_getschedparam(3),
470       posix_spawnattr_getschedpolicy(3), posix_spawnattr_getsigdefault(3),
471       posix_spawnattr_getsigmask(3), posix_spawnattr_init(3),
472       posix_spawnattr_setflags(3), posix_spawnattr_setpgroup(3),
473       posix_spawnattr_setschedparam(3), posix_spawnattr_setschedpolicy(3),
474       posix_spawnattr_setsigdefault(3), posix_spawnattr_setsigmask(3),
475       pthread_atfork(3), <spawn.h>, Base Definitions volume of POSIX.1-2001,
476       http://www.opengroup.org/unix/online.html
477

COLOPHON

479       This page is part of release 5.10 of the Linux man-pages project.  A
480       description of the project, information about reporting bugs, and the
481       latest version of this page, can be found at
482       https://www.kernel.org/doc/man-pages/.
483
484
485
486GNU                               2020-11-01                    POSIX_SPAWN(3)
Impressum