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
34       using 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
55          posix_spawn_file_actions_init(3)               and               the
56          posix_spawn_file_actions_*() functions.
57
58       *  The  attrp  argument  points to an attributes objects that specifies
59          various attributes of the created child  process.   This  object  is
60          initialized  and  populated  before  the  posix_spawn()  call  using
61          posix_spawnattr_init(3) and the posix_spawnattr_*() functions.
62
63       *  The argv and envp arguments specify the argument list  and  environ‐
64          ment  for  the program that is executed in the child process, as for
65          execve(2).
66
67       Below, the functions are described in terms of  a  three-step  process:
68       the  fork()  step, the pre-exec() step (executed in the child), and the
69       exec() step (executed in the child).
70
71   fork() step
72       The posix_spawn() function commences by calling  fork(2),  or  possibly
73       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       The  child  process  is  created using vfork(2) instead of fork(2) when
84       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
93          POSIX_SPAWN_RESETIDS.
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(2)  and the exec(3), 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
106       file_actions.   In  the  child,  processing  is  done  in the following
107       sequence:
108
109       1. Process attribute actions: signal  mask,  signal  default  handlers,
110          scheduling  algorithm  and  parameters, process group, and effective
111          user and group IDs are changed as specified by the attributes object
112          pointed to by attrp.
113
114       2. File  actions,  as  specified in the file_actions argument, are per‐
115          formed in the order that they were  specified  using  calls  to  the
116          posix_spawn_file_actions_add*() functions.
117
118       3. File descriptors with the FD_CLOEXEC flag set are closed.
119
120       All  process  attributes  in  the  child,  other than those affected by
121       attributes specified in the object pointed to by  attrp  and  the  file
122       actions  in  the object pointed to by file_actions, will be affected as
123       though the child was created with fork(2) and it executed  the  program
124       with execve(2).
125
126       The  process  attributes  actions  are defined by the attributes object
127       pointed to by attrp.  The spawn-flags attribute (set using  posix_spaw‐
128       nattr_setflags(3))  controls  the general actions that occur, and other
129       attributes in the  object  specify  values  to  be  used  during  those
130       actions.
131
132       The  effects  of  the flags that may be specified in spawn-flags are as
133       follows:
134
135       POSIX_SPAWN_SETSIGMASK
136               Set the signal mask to the signal set specified in  the  spawn-
137               sigmask  attribute  of  the object pointed to by attrp.  If the
138               POSIX_SPAWN_SETSIGMASK flag is not set, then the child inherits
139               the parent's signal mask.
140
141       POSIX_SPAWN_SETSIGDEF
142               Reset  the  disposition  of all signals in the set specified in
143               the spawn-sigdefault attribute of  the  object  pointed  to  by
144               attrp to the default.  For the treatment of the dispositions of
145               signals not specified in the spawn-sigdefault attribute, or the
146               treatment  when  POSIX_SPAWN_SETSIGDEF  is  not  specified, see
147               execve(2).
148
149       POSIX_SPAWN_SETSCHEDPARAM
150               If this flag is set, and the POSIX_SPAWN_SETSCHEDULER  flag  is
151               not  set,  then set the scheduling parameters to the parameters
152               specified in  the  spawn-schedparam  attribute  of  the  object
153               pointed to by attrp.
154
155       POSIX_SPAWN_SETSCHEDULER
156               Set  the  scheduling  policy  algorithm  and  parameters of the
157               child, as follows:
158
159               *  The scheduling policy is set to the value specified  in  the
160                  spawn-schedpolicy  attribute  of  the  object  pointed to by
161                  attrp.
162
163               *  The scheduling parameters are set to the value specified  in
164                  the  spawn-schedparam  attribute of the object pointed to by
165                  attrp (but see BUGS).
166
167               If the POSIX_SPAWN_SETSCHEDPARAM and POSIX_SPAWN_SETSCHEDPOLICY
168               flags  are  not specified, the child inherits the corresponding
169               scheduling attributes from the parent.
170
171       POSIX_SPAWN_RESETIDS
172               If this flag is set, reset the effective UID  and  GID  to  the
173               real  UID  and  GID of the parent process.  If this flag is not
174               set, then the child retains the effective UID and  GID  of  the
175               parent.   In  either  case, if the set-user-ID and set-group-ID
176               permission bits are  enabled  on  the  executable  file,  their
177               effect  will  override the setting of the effective UID and GID
178               (se execve(2)).
179
180       POSIX_SPAWN_SETPGROUP
181               Set the process group to the  value  specified  in  the  spawn-
182               pgroup  attribute  of  the  object pointed to by attrp.  If the
183               spawn-pgroup attribute has the value  0,  the  child's  process
184               group  ID  is  made  the  same  as  its  process  ID.   If  the
185               POSIX_SPAWN_SETPGROUP flag is not set, the child  inherits  the
186               parent's process group ID.
187
188       If  attrp  is NULL, then the default behaviors described above for each
189       flag apply.
190
191       The file_actions argument specifies a sequence of file operations  that
192       are  performed  in  the  child  process  after  the  general processing
193       described above, and before it performs the exec(3).   If  file_actions
194       is  NULL,  then no special action is taken, and standard exec(3) seman‐
195       tics apply--file descriptors open before the exec remain  open  in  the
196       new  process,  except those for which the FD_CLOEXEC flag has been set.
197       File locks remain in place.
198
199       If file_actions is not  NULL,  then  it  contains  an  ordered  set  of
200       requests  to  open(2), close(2), and dup2(2) files.  These requests are
201       added  to  the  file_actions  by   posix_spawn_file_actions_addopen(3),
202       posix_spawn_file_actions_addclose(3),                               and
203       posix_spawn_file_actions_adddup2(3).  The requested operations are per‐
204       formed in the order they were added to file_actions.
205
206       If  any  of  the  housekeeping actions fails (due to bogus values being
207       passed or  other  reasons  why  signal  handling,  process  scheduling,
208       process group ID functions, and file descriptor operations might fail),
209       the child process exits with exit value 127.
210
211   exec() step
212       Once the child has successfully forked and performed all requested pre-
213       exec steps, the child runs the requested executable.
214
215       The  child  process takes its environment from the envp argument, which
216       is interpreted as if it had been passed to execve(2).  The arguments to
217       the  created process come from the argv argument, which is processed as
218       for execve(2).
219

RETURN VALUE

221       Upon successful completion, posix_spawn() and posix_spawnp() place  the
222       PID  of  the  child process in pid, and return 0.  If there is an error
223       before or during the fork(2), then no child is created, the contents of
224       *pid  are  unspecified,  and  these functions return an error number as
225       described below.
226
227       Even when these functions return a success status,  the  child  process
228       may still fail for a plethora of reasons related to its pre-exec() ini‐
229       tialization.  In addition, the exec(3)  may  fail.   In  all  of  these
230       cases, the child process will exit with the exit value of 127.
231

ERRORS

233       The  posix_spawn()  and  posix_spawnp() functions fail only in the case
234       where the underlying fork(2) or vfork(2) call fails;  in  these  cases,
235       these functions return an error number, which will be one of the errors
236       described for fork(2) or vfork(2).
237
238       In addition, these functions fail if:
239
240       ENOSYS Function not supported on this system.
241

VERSIONS

243       The posix_spawn() and  posix_spawnp()  functions  are  available  since
244       glibc 2.2.
245

CONFORMING TO

247       POSIX.1-2001, POSIX.1-2008.
248

NOTES

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

BUGS

270       POSIX.1 says that when POSIX_SPAWN_SETSCHEDULER is specified in  spawn-
271       flags,  then  the  POSIX_SPAWN_SETSCHEDPARAM  (if  present) is ignored.
272       However, before glibc 2.14, calls to posix_spawn() failed with an error
273       if  POSIX_SPAWN_SETSCHEDULER  was  specified  without  also  specifying
274       POSIX_SPAWN_SETSCHEDPARAM.
275

EXAMPLE

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

SEE ALSO

450       close(2), dup2(2), execl(2), execlp(2), fork(2), open(2),
451       sched_setparam(2), sched_setscheduler(2), setpgid(2), setuid(2),
452       sigaction(2), sigprocmask(2), posix_spawn_file_actions_addclose(3),
453       posix_spawn_file_actions_adddup2(3),
454       posix_spawn_file_actions_addopen(3),
455       posix_spawn_file_actions_destroy(3), posix_spawn_file_actions_init(3),
456       posix_spawnattr_destroy(3), posix_spawnattr_getflags(3),
457       posix_spawnattr_getpgroup(3), posix_spawnattr_getschedparam(3),
458       posix_spawnattr_getschedpolicy(3), posix_spawnattr_getsigdefault(3),
459       posix_spawnattr_getsigmask(3), posix_spawnattr_init(3),
460       posix_spawnattr_setflags(3), posix_spawnattr_setpgroup(3),
461       posix_spawnattr_setschedparam(3), posix_spawnattr_setschedpolicy(3),
462       posix_spawnattr_setsigdefault(3), posix_spawnattr_setsigmask(3),
463       pthread_atfork(3), <spawn.h>, Base Definitions volume of POSIX.1-2001,
464       http://www.opengroup.org/unix/online.html
465

COLOPHON

467       This page is part of release 4.15 of the Linux man-pages project.  A
468       description of the project, information about reporting bugs, and the
469       latest version of this page, can be found at
470       https://www.kernel.org/doc/man-pages/.
471
472
473
474GNU                               2017-09-15                    POSIX_SPAWN(3)
Impressum