man3/posix_spawn.3

   1 .\" Copyright (c) 2009 Bill O. Gallmeister (bgallmeister@gmail.com)
   2 .\" and Copyright 2010 Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .\" References consulted:
   7 .\"     Linux glibc source code
   8 .\"     POSIX 1003.1-2004 documentation
   9 .\"     (http://www.opengroup.org/onlinepubs/009695399)
  10 .\"
  11 .TH POSIX_SPAWN 3 2021-03-22 "Linux man-pages (unreleased)"
  12 .SH NAME
  13 posix_spawn, posix_spawnp \- spawn a process
  14 .SH LIBRARY
  15 Standard C library
  16 .RI ( libc ", " \-lc )
  17 .SH SYNOPSIS
  18 .nf
  19 .B #include <spawn.h>
  20 .PP
  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]);
  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]);
  31 .fi
  32 .SH DESCRIPTION
  33 The
  34 .BR posix_spawn ()
  35 and
  36 .BR posix_spawnp ()
  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
  41 to support the
  42 .BR fork (2)
  43 system call.
  44 These machines are generally small, embedded systems lacking MMU support.
  45 .PP
  46 The
  47 .BR posix_spawn ()
  48 and
  49 .BR posix_spawnp ()
  50 functions provide the functionality of a combined
  51 .BR fork (2)
  52 and
  53 .BR exec (3),
  54 with some optional housekeeping steps in the child process before the
  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.
  63 .PP
  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
  78 .B PATH
  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
  84 .BR posix_spawnp ()
  85 differs only on the point just described.
  86 .PP
  87 The remaining arguments to these two functions are as follows:
  88 .IP * 3
  89 The
  90 .I pid
  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.
 111 .IP *
 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
 134 .BR fork ()
 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
 142 Since glibc 2.24, the
 143 .BR posix_spawn ()
 144 function commences by calling
 145 .BR clone (2)
 146 with
 147 .B CLONE_VM
 148 and
 149 .B CLONE_VFORK
 150 flags.
 151 Older implementations use
 152 .BR fork (2),
 153 or possibly
 154 .BR vfork (2)
 155 (see below).
 156 .PP
 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.
 162 .PP
 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.
 169 .PP
 170 Before glibc 2.24, the child process is created using
 171 .BR vfork (2)
 172 instead of
 173 .BR fork (2)
 174 when either of the following is true:
 175 .IP * 3
 176 the
 177 .I spawn-flags
 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
 183 .IP *
 184 .I file_actions
 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 .
 197 .PP
 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
 203 the requested file.
 204 .SS pre-exec() step: housekeeping
 205 In between the
 206 .B fork()
 207 and the
 208 .B exec()
 209 steps, a child process may need to perform a set of housekeeping actions.
 210 The
 211 .BR posix_spawn ()
 212 and
 213 .BR posix_spawnp ()
 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
 217 .I attrp
 218 and the file actions object pointed to by
 219 .IR file_actions .
 220 In the child, processing is done in the following sequence:
 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.
 228 File actions, as specified in the
 229 .I file_actions
 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.
 238 .PP
 239 All process attributes in the child,
 240 other than those affected by attributes specified in the
 241 object pointed to by
 242 .I attrp
 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).
 249 .PP
 250 The process attributes actions are defined by the attributes object
 251 pointed to by
 252 .IR attrp .
 253 The
 254 .I spawn-flags
 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.
 260 .PP
 261 The effects of the flags that may be specified in
 262 .I spawn-flags
 263 are as follows:
 264 .TP
 265 .B POSIX_SPAWN_SETSIGMASK
 266 Set the signal mask to the signal set specified in the
 267 .I spawn-sigmask
 268 attribute
 269 .\" FIXME .
 270 .\" (see
 271 .\" .BR posix_spawnattr_setsigmask (3))
 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
 280 .I spawn-sigdefault
 281 attribute
 282 .\" FIXME .
 283 .\" (see
 284 .\" .BR posix_spawnattr_setsigdefault (3))
 285 of the object pointed to by
 286 .I attrp
 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
 300 to the parameters specified in the
 301 .I spawn-schedparam
 302 attribute
 303 .\" FIXME .
 304 .\" (see
 305 .\" .BR posix_spawnattr_setschedparam (3))
 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
 315 .I spawn-schedpolicy
 316 attribute
 317 .\" FIXME .
 318 .\" (see
 319 .\" .BR posix_spawnattr_setpolicy (3))
 320 of the object pointed to by
 321 .IR attrp .
 322 .IP *
 323 The scheduling parameters are set to the value specified in the
 324 .I spawn-schedparam
 325 attribute
 326 .\" FIXME .
 327 .\" (see
 328 .\" .BR posix_spawnattr_setschedparam (3))
 329 of the object pointed to by
 330 .I attrp
 331 (but see BUGS).
 332 .PP
 333 If the
 334 .B POSIX_SPAWN_SETSCHEDPARAM
 335 and
 336 .B POSIX_SPAWN_SETSCHEDPOLICY
 337 flags are not specified,
 338 the child inherits the corresponding scheduling attributes from the parent.
 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
 355 attribute
 356 .\" FIXME .
 357 .\" (see
 358 .\" .BR posix_spawnattr_setpgroup (3))
 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.
 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
 372 .B fork()
 373 step to use
 374 .BR vfork (2)
 375 instead of
 376 .BR fork (2).
 377 The
 378 .B _GNU_SOURCE
 379 feature test macro must be defined to obtain the definition of this constant.
 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
 389 feature test macro must be defined to obtain the definition of this constant.
 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
 394 .PP
 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.
 405 .PP
 406 The
 407 .I file_actions
 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).
 412 If
 413 .I file_actions
 414 is NULL, then no special action is taken, and standard
 415 .BR exec (3)
 416 semantics apply\(emfile descriptors open before the exec
 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.
 422 .PP
 423 If
 424 .I file_actions
 425 is not NULL, then it contains an ordered set of requests to
 426 .BR open (2),
 427 .BR close (2),
 428 and
 429 .BR dup2 (2)
 430 files.
 431 These requests are added to the
 432 .I file_actions
 433 by
 434 .BR posix_spawn_file_actions_addopen (3),
 435 .BR posix_spawn_file_actions_addclose (3),
 436 and
 437 .BR posix_spawn_file_actions_adddup2 (3).
 438 The requested operations are performed in the order they were added to
 439 .IR file_actions .
 440 .\" FIXME . I think the following is best placed in the
 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 .
 451 .PP
 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,
 460 the child runs the requested executable.
 461 .PP
 462 The child process takes its environment from the
 463 .I envp
 464 argument, which is interpreted as if it had been passed to
 465 .BR execve (2).
 466 The arguments to the created process come from the
 467 .I argv
 468 argument, which is processed as for
 469 .BR execve (2).
 470 .SH RETURN VALUE
 471 Upon successful completion,
 472 .BR posix_spawn ()
 473 and
 474 .BR posix_spawnp ()
 475 place the PID of the child process in
 476 .IR pid ,
 477 and return 0.
 478 If there is an error during the
 479 .B fork()
 480 step,
 481 then no child is created,
 482 the contents of
 483 .I *pid
 484 are unspecified,
 485 and these functions return an error number as described below.
 486 .PP
 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.
 494 .SH ERRORS
 495 The
 496 .BR posix_spawn ()
 497 and
 498 .BR posix_spawnp ()
 499 functions fail only in the case where the underlying
 500 .BR fork (2),
 501 .BR vfork (2),
 502 or
 503 .BR clone (2)
 504 call fails;  in these cases, these functions return an error number,
 505 which will be one of the errors described for
 506 .BR fork (2),
 507 .BR vfork (2),
 508 or
 509 .BR clone (2).
 510 .PP
 511 In addition, these functions fail if:
 512 .TP
 513 .B ENOSYS
 514 Function not supported on this system.
 515 .SH VERSIONS
 516 The
 517 .BR posix_spawn ()
 518 and
 519 .BR posix_spawnp ()
 520 functions are available since glibc 2.2.
 521 .SH STANDARDS
 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.
 530 .SH NOTES
 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
 537 .I posix_spawnattr_t
 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.)
 547 .PP
 548 According to POSIX, it is unspecified whether fork handlers established with
 549 .BR pthread_atfork (3)
 550 are called when
 551 .BR posix_spawn ()
 552 is invoked.
 553 Since glibc 2.24, the fork handlers are not executed in any case.
 554 .\" Tested on glibc 2.12
 555 On older implementations,
 556 fork handlers are called only if the child is created using
 557 .BR fork (2).
 558 .PP
 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
 568 .I /proc/self/fd
 569 directory.
 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
 582 .B POSIX_SPAWN_SETSCHEDULER
 583 was specified without also specifying
 584 .BR POSIX_SPAWN_SETSCHEDPARAM .
 585 .SH EXAMPLES
 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.
 592 .PP
 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.
 598 .PP
 599 .in +4n
 600 .EX
 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
 605 .EE
 606 .in
 607 .PP
 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.
 615 .PP
 616 .in +4n
 617 .EX
 618 $ \fB./a.out \-c date\fP
 619 PID of child: 7636
 620 date: write error: Bad file descriptor
 621 Child status: exited, status=1
 622 .EE
 623 .in
 624 .PP
 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,
 635 .B SIGKILL
 636 is necessary
 637 .RB ( SIGKILL
 638 can't be blocked).
 639 .PP
 640 .in +4n
 641 .EX
 642 $ \fB./a.out \-s sleep 60 &\fP
 643 [1] 7637
 644 $ PID of child: 7638
 645
 646 $ \fBkill 7638\fP
 647 $ \fBkill \-KILL 7638\fP
 648 $ Child status: killed by signal 9
 649 [1]+  Done                    ./a.out \-s sleep 60
 650 .EE
 651 .in
 652 .PP
 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.
 656 .PP
 657 .in +4n
 658 .EX
 659 $ \fB./a.out xxxxx
 660 PID of child: 10190
 661 Child status: exited, status=127
 662 .EE
 663 .in
 664 .SS Program source
 665 \&
 666 .EX
 667 #include <spawn.h>
 668 #include <stdint.h>
 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
 676 #define errExit(msg)    do { perror(msg); \e
 677                              exit(EXIT_FAILURE); } while (0)
 678
 679 #define errExitEN(en, msg) \e
 680                         do { errno = en; perror(msg); \e
 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"
 707                action to it. */
 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"
 724                action to it. */
 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
 753     /* Destroy any objects that we created earlier. */
 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
 767     printf("PID of child: %jd\en", (intmax_t) child_pid);
 768
 769     /* Monitor status of the child until it terminates. */
 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)) {
 778             printf("exited, status=%d\en", WEXITSTATUS(status));
 779         } else if (WIFSIGNALED(status)) {
 780             printf("killed by signal %d\en", WTERMSIG(status));
 781         } else if (WIFSTOPPED(status)) {
 782             printf("stopped by signal %d\en", WSTOPSIG(status));
 783         } else if (WIFCONTINUED(status)) {
 784             printf("continued\en");
 785         }
 786     } while (!WIFEXITED(status) && !WIFSIGNALED(status));
 787
 788     exit(EXIT_SUCCESS);
 789 }
 790 .EE
 791 .SH SEE ALSO
 792 .nh \" Disable hyphenation
 793 .ad l
 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),
 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),
 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),
 825 .BR pthread_atfork (3),
 826 .IR <spawn.h> ,
 827 Base Definitions volume of POSIX.1-2001,
 828 .I http://www.opengroup.org/unix/online.html