diff options
Diffstat (limited to 'man3/posix_spawn.3')
| -rw-r--r-- | man3/posix_spawn.3 | 170 |
1 files changed, 85 insertions, 85 deletions
diff --git a/man3/posix_spawn.3 b/man3/posix_spawn.3 index 7eb96429f..9bd6ce129 100644 --- a/man3/posix_spawn.3 +++ b/man3/posix_spawn.3 @@ -39,7 +39,7 @@ 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) +.MR fork 2 system call. These machines are generally small, embedded systems lacking MMU support. .P @@ -48,15 +48,15 @@ The and .BR posix_spawnp () functions provide the functionality of a combined -.BR fork (2) +.MR fork 2 and -.BR exec (3), +.MR exec 3 , with some optional housekeeping steps in the child process before the -.BR exec (3). +.MR exec 3 . These functions are not meant to replace the -.BR fork (2) +.MR fork 2 and -.BR execve (2) +.MR execve 2 system calls. In fact, they provide only a subset of the functionality that can be achieved by using the system calls. @@ -77,7 +77,7 @@ 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)). +.MR execvp 3 ). For the remainder of this page, the discussion is phrased in terms of .BR posix_spawn (), with the understanding that @@ -95,14 +95,14 @@ points to a .I "spawn file actions object" that specifies file-related actions to be performed in the child between the -.BR fork (2) +.MR fork 2 and -.BR exec (3) +.MR exec 3 steps. This object is initialized and populated before the .BR posix_spawn () call using -.BR posix_spawn_file_actions_init (3) +.MR posix_spawn_file_actions_init 3 and the .BR posix_spawn_file_actions_* () functions. @@ -114,7 +114,7 @@ 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) +.MR posix_spawnattr_init 3 and the .BR posix_spawnattr_* () functions. @@ -124,7 +124,7 @@ functions. .I envp specify the argument list and environment for the program that is executed in the child process, as for -.BR execve (2). +.MR execve 2 . .P Below, the functions are described in terms of a three-step process: the .BR fork () @@ -138,16 +138,16 @@ step (executed in the child). Since glibc 2.24, the .BR posix_spawn () function commences by calling -.BR clone (2) +.MR clone 2 with .B CLONE_VM and .B CLONE_VFORK flags. Older implementations use -.BR fork (2), +.MR fork 2 , or possibly -.BR vfork (2) +.MR vfork 2 (see below). .P The PID of the new child process is placed in @@ -157,16 +157,16 @@ The function then returns control to the parent process. .P Subsequently, the parent can use one of the system calls described in -.BR wait (2) +.MR 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) +.MR vfork 2 instead of -.BR fork (2) +.MR fork 2 when either of the following is true: .IP \[bu] 3 the @@ -192,10 +192,10 @@ or .BR POSIX_SPAWN_RESETIDS . .P In other words, -.BR vfork (2) +.MR 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 +.MR exec 3 s the requested file. .SS pre-exec() step: housekeeping In between the @@ -239,9 +239,9 @@ object pointed to by 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) +.MR fork 2 and it executed the program with -.BR execve (2). +.MR execve 2 . .P The process attributes actions are defined by the attributes object pointed to by @@ -249,7 +249,7 @@ pointed to by The .I spawn-flags attribute (set using -.BR posix_spawnattr_setflags (3)) +.MR posix_spawnattr_setflags 3 ) controls the general actions that occur, and other attributes in the object specify values to be used during those actions. @@ -286,7 +286,7 @@ For the treatment of the dispositions of signals not specified in the attribute, or the treatment when .B POSIX_SPAWN_SETSIGDEF is not specified, see -.BR execve (2). +.MR execve 2 . .TP .B POSIX_SPAWN_SETSCHEDPARAM .\" (POSIX_PRIORITY_SCHEDULING only) @@ -343,7 +343,7 @@ 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)). +.MR execve 2 ). .TP .B POSIX_SPAWN_SETPGROUP Set the process group to the value specified in the @@ -367,9 +367,9 @@ 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) +.MR vfork 2 instead of -.BR fork (2). +.MR fork 2 . The .B _GNU_SOURCE feature test macro must be defined to obtain the definition of this constant. @@ -379,7 +379,7 @@ 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)). +.MR setsid 2 ). The .B _GNU_SOURCE feature test macro must be defined to obtain the definition of this constant. @@ -404,11 +404,11 @@ The 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). +.MR exec 3 . If .I file_actions is NULL, then no special action is taken, and standard -.BR exec (3) +.MR exec 3 semantics apply\[em]file descriptors open before the exec remain open in the new process, except those for which the @@ -419,18 +419,18 @@ File locks remain in place. If .I file_actions is not NULL, then it contains an ordered set of requests to -.BR open (2), -.BR close (2), +.MR open 2 , +.MR close 2 , and -.BR dup2 (2) +.MR 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), +.MR posix_spawn_file_actions_addopen 3 , +.MR posix_spawn_file_actions_addclose 3 , and -.BR posix_spawn_file_actions_adddup2 (3). +.MR 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 @@ -458,11 +458,11 @@ the child runs the requested executable. The child process takes its environment from the .I envp argument, which is interpreted as if it had been passed to -.BR execve (2). +.MR execve 2 . The arguments to the created process come from the .I argv argument, which is processed as for -.BR execve (2). +.MR execve 2 . .SH RETURN VALUE Upon successful completion, .BR posix_spawn () @@ -484,7 +484,7 @@ 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) +.MR exec 3 may fail. In all of these cases, the child process will exit with the exit value of 127. .SH ERRORS @@ -493,16 +493,16 @@ The and .BR posix_spawnp () functions fail only in the case where the underlying -.BR fork (2), -.BR vfork (2), +.MR fork 2 , +.MR vfork 2 , or -.BR clone (2) +.MR 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), +.MR fork 2 , +.MR vfork 2 , or -.BR clone (2). +.MR clone 2 . .P In addition, these functions fail if: .TP @@ -539,7 +539,7 @@ 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) +.MR pthread_atfork 3 are called when .BR posix_spawn () is invoked. @@ -547,14 +547,14 @@ 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). +.MR fork 2 . .P There is no "posix_fspawn" function (i.e., a function that is to .BR posix_spawn () as -.BR fexecve (3) +.MR fexecve 3 is to -.BR execve (2)). +.MR execve 2 ). However, this functionality can be obtained by specifying the .I path argument as one of the files in the caller's @@ -584,7 +584,7 @@ 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) +.MR date 1 command is executed in the child, and the .BR posix_spawn () call employs no file actions or attributes objects. @@ -603,7 +603,7 @@ In the next run, the command-line option is used to create a file actions object that closes standard output in the child. Consequently, -.BR date (1) +.MR date 1 fails when trying to perform output and exits with a status of 1. .P .in +4n @@ -620,7 +620,7 @@ In the next run, the 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) +.MR kill 1 (i.e., .BR SIGTERM ) fails, because that signal is blocked. @@ -644,7 +644,7 @@ $ Child status: killed by signal 9 .in .P When we try to execute a nonexistent command in the child, the -.BR exec (3) +.MR exec 3 fails and the child exits with a status of 127. .P .in +4n @@ -786,38 +786,38 @@ main(int argc, char *argv[]) .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), +.MR close 2 , +.MR dup2 2 , +.MR execl 2 , +.MR execlp 2 , +.MR fork 2 , +.MR open 2 , +.MR sched_setparam 2 , +.MR sched_setscheduler 2 , +.MR setpgid 2 , +.MR setuid 2 , +.MR sigaction 2 , +.MR sigprocmask 2 , +.MR posix_spawn_file_actions_addclose 3 , +.MR posix_spawn_file_actions_adddup2 3 , +.MR posix_spawn_file_actions_addopen 3 , +.MR posix_spawn_file_actions_destroy 3 , +.MR posix_spawn_file_actions_init 3 , +.MR posix_spawnattr_destroy 3 , +.MR posix_spawnattr_getflags 3 , +.MR posix_spawnattr_getpgroup 3 , +.MR posix_spawnattr_getschedparam 3 , +.MR posix_spawnattr_getschedpolicy 3 , +.MR posix_spawnattr_getsigdefault 3 , +.MR posix_spawnattr_getsigmask 3 , +.MR posix_spawnattr_init 3 , +.MR posix_spawnattr_setflags 3 , +.MR posix_spawnattr_setpgroup 3 , +.MR posix_spawnattr_setschedparam 3 , +.MR posix_spawnattr_setschedpolicy 3 , +.MR posix_spawnattr_setsigdefault 3 , +.MR posix_spawnattr_setsigmask 3 , +.MR pthread_atfork 3 , .IR <spawn.h> , Base Definitions volume of POSIX.1-2001, .I http://www.opengroup.org/unix/online.html |