diff options
Diffstat (limited to 'man/man3/posix_spawn.3')
| -rw-r--r-- | man/man3/posix_spawn.3 | 823 |
1 files changed, 823 insertions, 0 deletions
diff --git a/man/man3/posix_spawn.3 b/man/man3/posix_spawn.3 new file mode 100644 index 000000000..7eb96429f --- /dev/null +++ b/man/man3/posix_spawn.3 @@ -0,0 +1,823 @@ +.\" Copyright (c) 2009 Bill O. Gallmeister (bgallmeister@gmail.com) +.\" and Copyright 2010 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux glibc source code +.\" POSIX 1003.1-2004 documentation +.\" (http://www.opengroup.org/onlinepubs/009695399) +.\" +.TH posix_spawn 3 (date) "Linux man-pages (unreleased)" +.SH NAME +posix_spawn, posix_spawnp \- spawn a process +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <spawn.h> +.P +.BI "int posix_spawn(pid_t *restrict " pid ", const char *restrict " path , +.BI " const posix_spawn_file_actions_t *restrict " file_actions , +.BI " const posix_spawnattr_t *restrict " attrp , +.BI " char *const " argv [restrict], +.BI " char *const " envp [restrict]); +.BI "int posix_spawnp(pid_t *restrict " pid ", const char *restrict " file , +.BI " const posix_spawn_file_actions_t *restrict " file_actions , +.BI " const posix_spawnattr_t *restrict " attrp , +.BI " char *const " argv [restrict], +.BI " char *const " envp [restrict]); +.fi +.SH DESCRIPTION +The +.BR posix_spawn () +and +.BR 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 +.BR fork (2) +system call. +These machines are generally small, embedded systems lacking MMU support. +.P +The +.BR posix_spawn () +and +.BR posix_spawnp () +functions provide the functionality of a combined +.BR fork (2) +and +.BR exec (3), +with some optional housekeeping steps in the child process before the +.BR exec (3). +These functions are not meant to replace the +.BR fork (2) +and +.BR execve (2) +system calls. +In fact, they provide only a subset of the functionality +that can be achieved by using the system calls. +.P +The only difference between +.BR posix_spawn () +and +.BR posix_spawnp () +is the manner in which they specify the file to be executed by +the child process. +With +.BR posix_spawn (), +the executable file is specified as a pathname +(which can be absolute or relative). +With +.BR posix_spawnp (), +the executable file is specified as a simple filename; +the system searches for this file in the list of directories specified by +.B PATH +(in the same way as for +.BR execvp (3)). +For the remainder of this page, the discussion is phrased in terms of +.BR posix_spawn (), +with the understanding that +.BR posix_spawnp () +differs only on the point just described. +.P +The remaining arguments to these two functions are as follows: +.TP +.I pid +points to a buffer that is used to return the process ID +of the new child process. +.TP +.I file_actions +points to a +.I "spawn file actions object" +that specifies file-related actions to be performed in the child +between the +.BR fork (2) +and +.BR exec (3) +steps. +This object is initialized and populated before the +.BR posix_spawn () +call using +.BR posix_spawn_file_actions_init (3) +and the +.BR posix_spawn_file_actions_* () +functions. +.TP +.I attrp +points to an +.I attributes objects +that specifies various attributes of the created child process. +This object is initialized and populated before the +.BR posix_spawn () +call using +.BR posix_spawnattr_init (3) +and the +.BR posix_spawnattr_* () +functions. +.TP +.I argv +.TQ +.I envp +specify the argument list and environment for the program +that is executed in the child process, as for +.BR execve (2). +.P +Below, the functions are described in terms of a three-step process: the +.BR fork () +step, the +.RB pre- exec () +step (executed in the child), +and the +.BR exec () +step (executed in the child). +.SS fork() step +Since glibc 2.24, the +.BR posix_spawn () +function commences by calling +.BR clone (2) +with +.B CLONE_VM +and +.B CLONE_VFORK +flags. +Older implementations use +.BR fork (2), +or possibly +.BR vfork (2) +(see below). +.P +The PID of the new child process is placed in +.IR *pid . +The +.BR posix_spawn () +function then returns control to the parent process. +.P +Subsequently, the parent can use one of the system calls described in +.BR 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. +.P +Before glibc 2.24, the child process is created using +.BR vfork (2) +instead of +.BR fork (2) +when either of the following is true: +.IP \[bu] 3 +the +.I spawn-flags +element of the attributes object pointed to by +.I attrp +contains the GNU-specific flag +.BR POSIX_SPAWN_USEVFORK ; +or +.IP \[bu] +.I file_actions +is NULL and the +.I spawn-flags +element of the attributes object pointed to by +.I attrp +does \fInot\fP contain +.BR POSIX_SPAWN_SETSIGMASK , +.BR POSIX_SPAWN_SETSIGDEF , +.BR POSIX_SPAWN_SETSCHEDPARAM , +.BR POSIX_SPAWN_SETSCHEDULER , +.BR POSIX_SPAWN_SETPGROUP , +or +.BR POSIX_SPAWN_RESETIDS . +.P +In other words, +.BR vfork (2) +is used if the caller requests it, +or if there is no cleanup expected in the child before it +.BR exec (3)s +the requested file. +.SS pre-exec() step: housekeeping +In between the +.B fork() +and the +.B exec() +steps, a child process may need to perform a set of housekeeping actions. +The +.BR posix_spawn () +and +.BR posix_spawnp () +functions support a small, well-defined set of system tasks that the child +process can accomplish before it executes the executable file. +These operations are controlled by the attributes object pointed to by +.I attrp +and the file actions object pointed to by +.IR file_actions . +In the child, processing is done in the following sequence: +.IP (1) 5 +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 +.IR attrp . +.IP (2) +File actions, as specified in the +.I file_actions +argument, +are performed in the order that they were specified using calls to the +.BR posix_spawn_file_actions_add* () +functions. +.IP (3) +File descriptors with the +.B FD_CLOEXEC +flag set are closed. +.P +All process attributes in the child, +other than those affected by attributes specified in the +object pointed to by +.I attrp +and the file actions in the object pointed to by +.IR file_actions , +will be affected as though the child was created with +.BR fork (2) +and it executed the program with +.BR execve (2). +.P +The process attributes actions are defined by the attributes object +pointed to by +.IR attrp . +The +.I spawn-flags +attribute (set using +.BR posix_spawnattr_setflags (3)) +controls the general actions that occur, +and other attributes in the object specify values +to be used during those actions. +.P +The effects of the flags that may be specified in +.I spawn-flags +are as follows: +.TP +.B POSIX_SPAWN_SETSIGMASK +Set the signal mask to the signal set specified in the +.I spawn-sigmask +attribute +.\" FIXME . +.\" (see +.\" .BR posix_spawnattr_setsigmask (3)) +of the object pointed to by +.IR attrp . +If the +.B POSIX_SPAWN_SETSIGMASK +flag is not set, then the child inherits the parent's signal mask. +.TP +.B POSIX_SPAWN_SETSIGDEF +Reset the disposition of all signals in the set specified in the +.I spawn-sigdefault +attribute +.\" FIXME . +.\" (see +.\" .BR posix_spawnattr_setsigdefault (3)) +of the object pointed to by +.I attrp +to the default. +For the treatment of the dispositions of signals not specified in the +.I spawn-sigdefault +attribute, or the treatment when +.B POSIX_SPAWN_SETSIGDEF +is not specified, see +.BR execve (2). +.TP +.B POSIX_SPAWN_SETSCHEDPARAM +.\" (POSIX_PRIORITY_SCHEDULING only) +If this flag is set, and the +.B POSIX_SPAWN_SETSCHEDULER +flag is not set, then set the scheduling parameters +to the parameters specified in the +.I spawn-schedparam +attribute +.\" FIXME . +.\" (see +.\" .BR posix_spawnattr_setschedparam (3)) +of the object pointed to by +.IR attrp . +.TP +.B POSIX_SPAWN_SETSCHEDULER +Set the scheduling policy algorithm and parameters of the child, +as follows: +.RS +.IP \[bu] 3 +The scheduling policy is set to the value specified in the +.I spawn-schedpolicy +attribute +.\" FIXME . +.\" (see +.\" .BR posix_spawnattr_setpolicy (3)) +of the object pointed to by +.IR attrp . +.IP \[bu] +The scheduling parameters are set to the value specified in the +.I spawn-schedparam +attribute +.\" FIXME . +.\" (see +.\" .BR posix_spawnattr_setschedparam (3)) +of the object pointed to by +.I attrp +(but see BUGS). +.P +If the +.B POSIX_SPAWN_SETSCHEDPARAM +and +.B POSIX_SPAWN_SETSCHEDPOLICY +flags are not specified, +the child inherits the corresponding scheduling attributes from the parent. +.RE +.TP +.B 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 +.BR execve (2)). +.TP +.B POSIX_SPAWN_SETPGROUP +Set the process group to the value specified in the +.I spawn-pgroup +attribute +.\" FIXME . +.\" (see +.\" .BR posix_spawnattr_setpgroup (3)) +of the object pointed to by +.IR attrp . +If the +.I spawn-pgroup +attribute has the value 0, +the child's process group ID is made the same as its process ID. +If the +.B POSIX_SPAWN_SETPGROUP +flag is not set, the child inherits the parent's process group ID. +.TP +.B POSIX_SPAWN_USEVFORK +Since glibc 2.24, this flag has no effect. +On older implementations, setting this flag forces the +.B fork() +step to use +.BR vfork (2) +instead of +.BR fork (2). +The +.B _GNU_SOURCE +feature test macro must be defined to obtain the definition of this constant. +.TP +.BR POSIX_SPAWN_SETSID " (since glibc 2.26)" +If this flag is set, +the child process shall create a new session and become the session leader. +The child process shall also become the process group leader of the new process +group in the session (see +.BR setsid (2)). +The +.B _GNU_SOURCE +feature test macro must be defined to obtain the definition of this constant. +.\" This flag has been accepted in POSIX, see: +.\" http://austingroupbugs.net/view.php?id=1044 +.\" and has been implemented since glibc 2.26 +.\" commit daeb1fa2e1b33323e719015f5f546988bd4cc73b +.P +If +.I attrp +is NULL, then the default behaviors described above for each flag apply. +.\" mtk: I think we probably don't want to say the following, since it +.\" could lead people to do the wrong thing +.\" The POSIX standard tells you to call +.\" this function to de-initialize the attributes object pointed to by +.\" .I attrp +.\" when you are done with it; +.\" however, on Linux systems this operation is a no-op. +.P +The +.I 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 +.BR exec (3). +If +.I file_actions +is NULL, then no special action is taken, and standard +.BR exec (3) +semantics apply\[em]file descriptors open before the exec +remain open in the new process, +except those for which the +.B FD_CLOEXEC +flag has been set. +File locks remain in place. +.P +If +.I file_actions +is not NULL, then it contains an ordered set of requests to +.BR open (2), +.BR close (2), +and +.BR dup2 (2) +files. +These requests are added to the +.I file_actions +by +.BR posix_spawn_file_actions_addopen (3), +.BR posix_spawn_file_actions_addclose (3), +and +.BR posix_spawn_file_actions_adddup2 (3). +The requested operations are performed in the order they were added to +.IR file_actions . +.\" FIXME . I think the following is best placed in the +.\" posix_spawn_file_actions_adddup2(3) page, and a similar statement is +.\" also needed in posix_spawn_file_actions_addclose(3) +.\" Note that you can specify file descriptors in +.\" .I posix_spawn_file_actions_adddup2 (3) +.\" which would not be usable if you called +.\" .BR dup2 (2) +.\" at that time--i.e., file descriptors that are opened or +.\" closed by the earlier operations +.\" added to +.\" .I file_actions . +.P +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. +.SS exec() step +Once the child has successfully forked and performed +all requested pre-exec steps, +the child runs the requested executable. +.P +The child process takes its environment from the +.I envp +argument, which is interpreted as if it had been passed to +.BR execve (2). +The arguments to the created process come from the +.I argv +argument, which is processed as for +.BR execve (2). +.SH RETURN VALUE +Upon successful completion, +.BR posix_spawn () +and +.BR posix_spawnp () +place the PID of the child process in +.IR pid , +and return 0. +If there is an error during the +.B fork() +step, +then no child is created, +the contents of +.I *pid +are unspecified, +and these functions return an error number as described below. +.P +Even when these functions return a success status, +the child process may still fail for a plethora of reasons related to its +pre-\fBexec\fR() initialization. +In addition, the +.BR exec (3) +may fail. +In all of these cases, the child process will exit with the exit value of 127. +.SH ERRORS +The +.BR posix_spawn () +and +.BR posix_spawnp () +functions fail only in the case where the underlying +.BR fork (2), +.BR vfork (2), +or +.BR clone (2) +call fails; in these cases, these functions return an error number, +which will be one of the errors described for +.BR fork (2), +.BR vfork (2), +or +.BR clone (2). +.P +In addition, these functions fail if: +.TP +.B ENOSYS +Function not supported on this system. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.2. +POSIX.1-2001. +.\" FIXME . This piece belongs in spawnattr_setflags(3) +.\" The +.\" .B POSIX_SPAWN_USEVFORK +.\" flag is a GNU extension; the +.\" .B _GNU_SOURCE +.\" feature test macro must be defined (before including any header files) +.\" to obtain the definition of this constant. +.SH NOTES +The housekeeping activities in the child are controlled by +the objects pointed to by +.I attrp +(for non-file actions) and +.I file_actions +In POSIX parlance, the +.I posix_spawnattr_t +and +.I 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.) +.P +According to POSIX, it is unspecified whether fork handlers established with +.BR pthread_atfork (3) +are called when +.BR posix_spawn () +is invoked. +Since glibc 2.24, the fork handlers are not executed in any case. +.\" Tested on glibc 2.12 +On older implementations, +fork handlers are called only if the child is created using +.BR fork (2). +.P +There is no "posix_fspawn" function (i.e., a function that is to +.BR posix_spawn () +as +.BR fexecve (3) +is to +.BR execve (2)). +However, this functionality can be obtained by specifying the +.I path +argument as one of the files in the caller's +.I /proc/self/fd +directory. +.SH BUGS +POSIX.1 says that when +.B POSIX_SPAWN_SETSCHEDULER +is specified in +.IR spawn-flags , +then the +.B POSIX_SPAWN_SETSCHEDPARAM +(if present) is ignored. +However, before glibc 2.14, calls to +.BR posix_spawn () +failed with an error if +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=12052 +.B POSIX_SPAWN_SETSCHEDULER +was specified without also specifying +.BR POSIX_SPAWN_SETSCHEDPARAM . +.SH EXAMPLES +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. +.P +In the first run, the +.BR date (1) +command is executed in the child, and the +.BR posix_spawn () +call employs no file actions or attributes objects. +.P +.in +4n +.EX +$ \fB./a.out date\fP +PID of child: 7634 +Tue Feb 1 19:47:50 CEST 2011 +Child status: exited, status=0 +.EE +.in +.P +In the next run, the +.I \-c +command-line option is used to create a file actions object that closes +standard output in the child. +Consequently, +.BR date (1) +fails when trying to perform output and exits with a status of 1. +.P +.in +4n +.EX +$ \fB./a.out \-c date\fP +PID of child: 7636 +date: write error: Bad file descriptor +Child status: exited, status=1 +.EE +.in +.P +In the next run, the +.I \-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 +.BR kill (1) +(i.e., +.BR SIGTERM ) +fails, because that signal is blocked. +Therefore, to kill the child, +.B SIGKILL +is necessary +.RB ( SIGKILL +can't be blocked). +.P +.in +4n +.EX +$ \fB./a.out \-s sleep 60 &\fP +[1] 7637 +$ PID of child: 7638 +.P +$ \fBkill 7638\fP +$ \fBkill \-KILL 7638\fP +$ Child status: killed by signal 9 +[1]+ Done ./a.out \-s sleep 60 +.EE +.in +.P +When we try to execute a nonexistent command in the child, the +.BR exec (3) +fails and the child exits with a status of 127. +.P +.in +4n +.EX +$ \fB./a.out xxxxx +PID of child: 10190 +Child status: exited, status=127 +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (posix_spawn.c) +.EX +#include <errno.h> +#include <spawn.h> +#include <stdint.h> +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +#include <unistd.h> +#include <wait.h> +\& +#define errExit(msg) do { perror(msg); \e + exit(EXIT_FAILURE); } while (0) +\& +#define errExitEN(en, msg) \e + do { errno = en; perror(msg); \e + 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 \[aq]c\[aq]: /* \-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 \[aq]s\[aq]: /* \-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_SETSIGMASK); + 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\[aq]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: %jd\en", (intmax_t) 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\en", WEXITSTATUS(status)); + } else if (WIFSIGNALED(status)) { + printf("killed by signal %d\en", WTERMSIG(status)); + } else if (WIFSTOPPED(status)) { + printf("stopped by signal %d\en", WSTOPSIG(status)); + } else if (WIFCONTINUED(status)) { + printf("continued\en"); + } + } while (!WIFEXITED(status) && !WIFSIGNALED(status)); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.nh \" Disable hyphenation +.ad l +.BR close (2), +.BR dup2 (2), +.BR execl (2), +.BR execlp (2), +.BR fork (2), +.BR open (2), +.BR sched_setparam (2), +.BR sched_setscheduler (2), +.BR setpgid (2), +.BR setuid (2), +.BR sigaction (2), +.BR sigprocmask (2), +.BR posix_spawn_file_actions_addclose (3), +.BR posix_spawn_file_actions_adddup2 (3), +.BR posix_spawn_file_actions_addopen (3), +.BR posix_spawn_file_actions_destroy (3), +.BR posix_spawn_file_actions_init (3), +.BR posix_spawnattr_destroy (3), +.BR posix_spawnattr_getflags (3), +.BR posix_spawnattr_getpgroup (3), +.BR posix_spawnattr_getschedparam (3), +.BR posix_spawnattr_getschedpolicy (3), +.BR posix_spawnattr_getsigdefault (3), +.BR posix_spawnattr_getsigmask (3), +.BR posix_spawnattr_init (3), +.BR posix_spawnattr_setflags (3), +.BR posix_spawnattr_setpgroup (3), +.BR posix_spawnattr_setschedparam (3), +.BR posix_spawnattr_setschedpolicy (3), +.BR posix_spawnattr_setsigdefault (3), +.BR posix_spawnattr_setsigmask (3), +.BR pthread_atfork (3), +.IR <spawn.h> , +Base Definitions volume of POSIX.1-2001, +.I http://www.opengroup.org/unix/online.html |