GENWiki

Premier IT Outsourcing and Support Services within the UK

User Tools

Site Tools


man:posix_spawnp

POSIX_SPAWN(3) Linux Programmer's Manual POSIX_SPAWN(3)

NAME

     posix_spawn, posix_spawnp - spawn a process

SYNOPSIS

     #include <spawn.h>
     int posix_spawn(pid_t *pid, const char *path,
                     const posix_spawn_file_actions_t *file_actions,
                     const posix_spawnattr_t *attrp,
                     char *const argv[], char *const envp[]);
     int posix_spawnp(pid_t *pid, const char *file,
                     const posix_spawn_file_actions_t *file_actions,
                     const posix_spawnattr_t *attrp,
                     char *const argv[], char *const envp[]);

DESCRIPTION

     The posix_spawn() and posix_spawnp() functions are used to create a new
     child process that executes a specified  file.   These  functions  were
     specified  by  POSIX  to  provide a standardized method of creating new
     processes on machines that lack the capability to support  the  fork(2)
     system  call.   These  machines  are  generally small, embedded systems
     lacking MMU support.
     The posix_spawn() and posix_spawnp() functions provide the  functional-
     ity  of a combined fork(2) and exec(3), with some optional housekeeping
     steps in the child process before the exec(3).  These functions are not
     meant to replace the fork(2) and execve(2) system calls.  In fact, they
     provide only a subset of the functionality  that  can  be  achieved  by
     using the system calls.
     The  only  difference  between  posix_spawn() and posix_spawnp() is the
     manner in which they specify the file  to  be  executed  by  the  child
     process.   With  posix_spawn(),  the  executable file is specified as a
     pathname (which can be absolute or relative).  With posix_spawnp(), the
     executable  file is specified as a simple filename; the system searches
     for this file in the list of directories specified by PATH (in the same
     way  as for execvp(3)).  For the remainder of this page, the discussion
     is phrased in terms  of  posix_spawn(),  with  the  understanding  that
     posix_spawnp() differs only on the point just described.
     The remaining arguments to these two functions are as follows:
  • The pid argument points to a buffer that is used to return the

process ID of the new child process.

  • The file_actions argument points to a spawn file actions object that

specifies file-related actions to be performed in the child between

        the fork(2) and exec(3) steps.  This object is initialized and popu-
        lated       before       the      posix_spawn()      call      using
        posix_spawn_file_actions_init(3)               and               the
        posix_spawn_file_actions_*() functions.
  • The attrp argument points to an attributes objects that specifies

various attributes of the created child process. This object is

        initialized  and  populated  before  the  posix_spawn()  call  using
        posix_spawnattr_init(3) and the posix_spawnattr_*() functions.
  • The argv and envp arguments specify the argument list and environ-

ment for the program that is executed in the child process, as for

        execve(2).
     Below, the functions are described in terms of  a  three-step  process:
     the  fork()  step, the pre-exec() step (executed in the child), and the
     exec() step (executed in the child).
 fork() step
     The posix_spawn() function commences by calling  fork(2),  or  possibly
     vfork(2) (see below).
     The  PID of the new child process is placed in *pid.  The posix_spawn()
     function then returns control to the parent process.
     Subsequently, the parent can use one of the system calls  described  in
     wait(2)  to  check the status of the child process.  If the child fails
     in any of the housekeeping steps described below, or fails  to  execute
     the desired file, it exits with a status of 127.
     The  child  process  is  created using vfork(2) instead of fork(2) when
     either of the following is true:
  • the spawn-flags element of the attributes object pointed to by attrp

contains the GNU-specific flag POSIX_SPAWN_USEVFORK; or

  • file_actions is NULL and the spawn-flags element of the attributes

object pointed to by attrp does not contain POSIX_SPAWN_SETSIGMASK,

        POSIX_SPAWN_SETSIGDEF,                    POSIX_SPAWN_SETSCHEDPARAM,
        POSIX_SPAWN_SETSCHEDULER,         POSIX_SPAWN_SETPGROUP,          or
        POSIX_SPAWN_RESETIDS.
     In other words, vfork(2) is used if the caller requests it, or if there
     is no cleanup expected in the child before it  exec(3)s  the  requested
     file.
 pre-exec() step: housekeeping
     In  between  the  fork(2)  and the exec(3), a child process may need to
     perform  a  set  of  housekeeping  actions.   The   posix_spawn()   and
     posix_spawnp()  functions  support  a small, well-defined set of system
     tasks that the child process can accomplish before it executes the exe-
     cutable file.  These operations are controlled by the attributes object
     pointed to  by  attrp  and  the  file  actions  object  pointed  to  by
     file_actions.   In  the  child,  processing  is  done  in the following
     sequence:
     1. Process attribute actions: signal  mask,  signal  default  handlers,
        scheduling  algorithm  and  parameters, process group, and effective
        user and group IDs are changed as specified by the attributes object
        pointed to by attrp.
     2. File  actions,  as  specified in the file_actions argument, are per-
        formed in the order that they were  specified  using  calls  to  the
        posix_spawn_file_actions_add*() functions.
     3. File descriptors with the FD_CLOEXEC flag set are closed.
     All  process  attributes  in  the  child,  other than those affected by
     attributes specified in the object pointed to by  attrp  and  the  file
     actions  in  the object pointed to by file_actions, will be affected as
     though the child was created with fork(2) and it executed  the  program
     with execve(2).
     The  process  attributes  actions  are defined by the attributes object
     pointed to by attrp.  The spawn-flags attribute (set using  posix_spaw-
     nattr_setflags(3))  controls  the general actions that occur, and other
     attributes in the  object  specify  values  to  be  used  during  those
     actions.
     The  effects  of  the flags that may be specified in spawn-flags are as
     follows:
     POSIX_SPAWN_SETSIGMASK
             Set the signal mask to the signal set specified in  the  spawn-
             sigmask  attribute  of  the object pointed to by attrp.  If the
             POSIX_SPAWN_SETSIGMASK flag is not set, then the child inherits
             the parent's signal mask.
     POSIX_SPAWN_SETSIGDEF
             Reset  the  disposition  of all signals in the set specified in
             the spawn-sigdefault attribute of  the  object  pointed  to  by
             attrp to the default.  For the treatment of the dispositions of
             signals not specified in the spawn-sigdefault attribute, or the
             treatment  when  POSIX_SPAWN_SETSIGDEF  is  not  specified, see
             execve(2).
     POSIX_SPAWN_SETSCHEDPARAM
             If this flag is set, and the POSIX_SPAWN_SETSCHEDULER  flag  is
             not  set,  then set the scheduling parameters to the parameters
             specified in  the  spawn-schedparam  attribute  of  the  object
             pointed to by attrp.
     POSIX_SPAWN_SETSCHEDULER
             Set  the  scheduling  policy  algorithm  and  parameters of the
             child, as follows:
  • The scheduling policy is set to the value specified in the

spawn-schedpolicy attribute of the object pointed to by

                attrp.
  • The scheduling parameters are set to the value specified in

the spawn-schedparam attribute of the object pointed to by

                attrp (but see BUGS).
             If the POSIX_SPAWN_SETSCHEDPARAM and POSIX_SPAWN_SETSCHEDPOLICY
             flags  are  not specified, the child inherits the corresponding
             scheduling attributes from the parent.
     POSIX_SPAWN_RESETIDS
             If this flag is set, reset the effective UID  and  GID  to  the
             real  UID  and  GID of the parent process.  If this flag is not
             set, then the child retains the effective UID and  GID  of  the
             parent.   In  either  case, if the set-user-ID and set-group-ID
             permission bits are  enabled  on  the  executable  file,  their
             effect  will  override the setting of the effective UID and GID
             (se execve(2)).
     POSIX_SPAWN_SETPGROUP
             Set the process group to the  value  specified  in  the  spawn-
             pgroup  attribute  of  the  object pointed to by attrp.  If the
             spawn-pgroup attribute has the value  0,  the  child's  process
             group  ID  is  made  the  same  as  its  process  ID.   If  the
             POSIX_SPAWN_SETPGROUP flag is not set, the child  inherits  the
             parent's process group ID.
     If  attrp  is NULL, then the default behaviors described above for each
     flag apply.
     The file_actions argument specifies a sequence of file operations  that
     are  performed  in  the  child  process  after  the  general processing
     described above, and before it performs the exec(3).   If  file_actions
     is  NULL,  then no special action is taken, and standard exec(3) seman-
     tics apply--file descriptors open before the exec remain  open  in  the
     new  process,  except those for which the FD_CLOEXEC flag has been set.
     File locks remain in place.
     If file_actions is not  NULL,  then  it  contains  an  ordered  set  of
     requests  to  open(2), close(2), and dup2(2) files.  These requests are
     added  to  the  file_actions  by   posix_spawn_file_actions_addopen(3),
     posix_spawn_file_actions_addclose(3),                               and
     posix_spawn_file_actions_adddup2(3).  The requested operations are per-
     formed in the order they were added to file_actions.
     If  any  of  the  housekeeping actions fails (due to bogus values being
     passed or  other  reasons  why  signal  handling,  process  scheduling,
     process group ID functions, and file descriptor operations might fail),
     the child process exits with exit value 127.
 exec() step
     Once the child has successfully forked and performed all requested pre-
     exec steps, the child runs the requested executable.
     The  child  process takes its environment from the envp argument, which
     is interpreted as if it had been passed to execve(2).  The arguments to
     the  created process come from the argv argument, which is processed as
     for execve(2).

RETURN VALUE

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

ERRORS

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

VERSIONS

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

CONFORMING TO

     POSIX.1-2001, POSIX.1-2008.

NOTES

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

BUGS

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

EXAMPLE

     The program below demonstrates the use  of  various  functions  in  the
     POSIX  spawn API.  The program accepts command-line attributes that can
     be used to create file actions and attributes objects.   The  remaining
     command-line arguments are used as the executable name and command-line
     arguments of the program that is executed in the child.
     In the first run, the date(1) command is executed in the child, and the
     posix_spawn() call employs no file actions or attributes objects.
         $  ./a.out  date  PID  of child: 7634 Tue Feb  1 19:47:50 CEST 2011
         Child status: exited, status=0
     In the next run, the -c command-line option is used to  create  a  file
     actions object that closes standard output in the child.  Consequently,
     date(1) fails when trying to perform output and exits with a status  of
     1.
         $  ./a.out  -c  date PID of child: 7636 date: write error: Bad file
         descriptor Child status: exited, status=1
     In the next run, the -s  command-line  option  is  used  to  create  an
     attributes  object  that  specifies that all (blockable) signals in the
     child should be blocked.  Consequently, trying to kill child  with  the
     default signal sent by kill(1) (i.e., SIGTERM) fails, because that sig-
     nal is blocked.  Therefore, to kill the  child,  SIGKILL  is  necessary
     (SIGKILL can't be blocked).
         $ ./a.out -s sleep 60 & [1] 7637 $ PID of child: 7638
         $  kill  7638  $ kill -KILL 7638 $ Child status: killed by signal 9
         [1]+  Done                    ./a.out -s sleep 60
     When we try to execute a nonexistent command in the child, the  exec(3)
     fails and the child exits with a status of 127.
         $  ./a.out  xxxxx  PID  of  child: 10190 Child status: exited, sta-
         tus=127
 Program source
      #include <spawn.h> #include  <stdio.h>  #include  <unistd.h>  #include
     <stdlib.h> #include <string.h> #include <wait.h> #include <errno.h>
     #define errExit(msg)    do { perror(msg); \
                                  exit(EXIT_FAILURE); } while (0)
     #define errExitEN(en, msg) \
                             do { errno = en; perror(msg); \
                                  exit(EXIT_FAILURE); } while (0)
     char **environ;
     int main(int argc, char *argv[]) {
         pid_t child_pid;
         int s, opt, status;
         sigset_t mask;
         posix_spawnattr_t attr;
         posix_spawnattr_t *attrp;
         posix_spawn_file_actions_t file_actions;
         posix_spawn_file_actions_t *file_actionsp;
         /* Parse command-line options, which can be used to specify an
            attributes object and file actions object for the child. */
         attrp = NULL;
         file_actionsp = NULL;
         while ((opt = getopt(argc, argv, "sc")) != -1) {
             switch (opt) {
             case 'c':       /* -c: close standard output in child */
                 /* Create a file actions object and add a "close"
                    action to it */
                 s = posix_spawn_file_actions_init(&file_actions);
                 if (s != 0)
                     errExitEN(s, "posix_spawn_file_actions_init");
                 s = posix_spawn_file_actions_addclose(&file_actions,
                                                       STDOUT_FILENO);
                 if (s != 0)
                     errExitEN(s, "posix_spawn_file_actions_addclose");
                 file_actionsp = &file_actions;
                 break;
             case 's':       /* -s: block all signals in child */
                 /* Create an attributes object and add a "set signal mask"
                    action to it */
                 s = posix_spawnattr_init(&attr);
                 if (s != 0)
                     errExitEN(s, "posix_spawnattr_init");
                 s   =  posix_spawnattr_setflags(&attr,  POSIX_SPAWN_SETSIG-
     MASK);
                 if (s != 0)
                     errExitEN(s, "posix_spawnattr_setflags");
                 sigfillset(&mask);
                 s = posix_spawnattr_setsigmask(&attr, &mask);
                 if (s != 0)
                     errExitEN(s, "posix_spawnattr_setsigmask");
                 attrp = &attr;
                 break;
             }
         }
         /* Spawn the child. The name of the program to execute and the
            command-line arguments are taken from the command-line arguments
            of this program. The environment of the program execed in the
            child is made the same as the parent's environment. */
         s = posix_spawnp(&child_pid, argv[optind], file_actionsp, attrp,
                          &argv[optind], environ);
         if (s != 0)
             errExitEN(s, "posix_spawn");
         /* Destroy any objects that we created earlier */
         if (attrp != NULL) {
             s = posix_spawnattr_destroy(attrp);
             if (s != 0)
                 errExitEN(s, "posix_spawnattr_destroy");
         }
         if (file_actionsp != NULL) {
             s = posix_spawn_file_actions_destroy(file_actionsp);
             if (s != 0)
                 errExitEN(s, "posix_spawn_file_actions_destroy");
         }
         printf("PID of child: %ld\n", (long) child_pid);
         /* Monitor status of the child until it terminates */
         do {
             s = waitpid(child_pid, &status, WUNTRACED | WCONTINUED);
             if (s == -1)
                 errExit("waitpid");
             printf("Child status: ");
             if (WIFEXITED(status)) {
                 printf("exited, status=%d\n", WEXITSTATUS(status));
             } else if (WIFSIGNALED(status)) {
                 printf("killed by signal %d\n", WTERMSIG(status));
             } else if (WIFSTOPPED(status)) {
                 printf("stopped by signal %d\n", WSTOPSIG(status));
             } else if (WIFCONTINUED(status)) {
                 printf("continued\n");
             }
         } while (!WIFEXITED(status) && !WIFSIGNALED(status));
         exit(EXIT_SUCCESS); }

SEE ALSO

     close(2), dup2(2), execl(2), execlp(2), fork(2), open(2),
     sched_setparam(2), sched_setscheduler(2), setpgid(2), setuid(2),
     sigaction(2), sigprocmask(2), posix_spawn_file_actions_addclose(3),
     posix_spawn_file_actions_adddup2(3),
     posix_spawn_file_actions_addopen(3),
     posix_spawn_file_actions_destroy(3), posix_spawn_file_actions_init(3),
     posix_spawnattr_destroy(3), posix_spawnattr_getflags(3),
     posix_spawnattr_getpgroup(3), posix_spawnattr_getschedparam(3),
     posix_spawnattr_getschedpolicy(3), posix_spawnattr_getsigdefault(3),
     posix_spawnattr_getsigmask(3), posix_spawnattr_init(3),
     posix_spawnattr_setflags(3), posix_spawnattr_setpgroup(3),
     posix_spawnattr_setschedparam(3), posix_spawnattr_setschedpolicy(3),
     posix_spawnattr_setsigdefault(3), posix_spawnattr_setsigmask(3),
     pthread_atfork(3), <spawn.h>, Base Definitions volume of POSIX.1-2001,
     http://www.opengroup.org/unix/online.html

COLOPHON

     This page is part of release 4.16 of the Linux man-pages project.  A
     description of the project, information about reporting bugs, and the
     latest version of this page, can be found at
     https://www.kernel.org/doc/man-pages/.

GNU 2017-09-15 POSIX_SPAWN(3)

/data/webs/external/dokuwiki/data/pages/man/posix_spawnp.txt · Last modified: 2019/05/17 09:32 by 127.0.0.1

Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki