Syntax
int posix_spawn(pid_t *restrict pid, const char *restrict path,
const posix_spawn_file_actions_t *file_actions,
const posix_spawnattr_t *restrict attrp,
char *const argv[restrict], char *const envp[restrict]);
int posix_spawnp(pid_t *restrict pid, const char *restrict file,
const posix_spawn_file_actions_t *file_actions,
const posix_spawnattr_t *restrict attrp,
char *const argv[restrict], char * const envp[restrict]);
Description
The posix_spawn and posix_spawnp subroutines
create a new process (child process) from the specified process image.
The new process image is constructed from a regular executable file
called the new process image file.
When
a C program is executed as the result of this call, the program is
entered as a C-language function call as follows:
int main(int argc, char *argv[]);
where
argc is
the argument count and
argv is an array
of character pointers to the arguments themselves. In addition, the
following variable:
extern char **environ;
is initialized as a pointer to an array of character
pointers to the environment strings.
The argv parameter
is an array of character pointers to null-terminated strings. The
last member of this array is a null pointer and is not counted in argc.
These strings constitute the argument list available to the new process
image. The value in argv[0] should point
to a file name that is associated with the process image being started
by the posix_spawn or posix_spawnp function.
The
argument envp is an array of character pointers
to null-terminated strings. These strings constitute the environment
for the new process image. The environment array is terminated by
a null pointer.
The number of bytes available for the child
process' combined argument and environment lists is {ARG_MAX}.
The implementation specifies in the system documentation whether any
list overhead, such as length words, null terminators, pointers, or
alignment bytes, is included in this total.
The path argument
to posix_spawn is a path name that identifies
the new process image file to execute.
The file parameter
to posix_spawnp is used to construct a path
name that identifies the new process image file. If the file parameter
contains a slash character (/), the file parameter
is used as the path name for the new process image file. Otherwise,
the path prefix for this file is obtained by a search of the directories
passed as the environment variable PATH.
If this environment variable is not defined, the results of the search
are implementation-defined.
If file_actions is
a null pointer, file descriptors that are open in the calling process
remain open in the child process, except for those whose FD_CLOEXEC flag
is set (see fcntl, dup, or dup2 Subroutine). For those file
descriptors that remain open, all attributes of the corresponding
open file descriptions, including file locks, remain unchanged.
If
file_actions is
not a null pointer, the file descriptors open in the child process
are those open in the calling process as modified by the spawn file
actions object pointed to by
file_actions and
the
FD_CLOEXEC flag of each remaining open
file descriptor after the spawn file actions have been processed.
The effective order of processing the spawn file actions is as follows:
- The set of open file descriptors for the child process is initially
the same set as is open for the calling process. All attributes of
the corresponding open file descriptions, including file locks (see fcntl, dup, or dup2 Subroutine), remain unchanged.
- The signal mask, signal default actions, and the effective user
and group IDs for the child process are changed as specified in the
attributes object referenced by attrp.
- The file actions specified by the spawn file actions object are
performed in the order in which they were added to the spawn file
actions object.
- Any file descriptor that has its FD_CLOEXEC flag
set is closed.
The
posix_spawnattr_t spawn attributes
object type is defined in the
spawn.h header
file. Its attributes are defined as follows:
- If the POSIX_SPAWN_SETPGROUP flag is
set in the spawn-flags attribute of the
object referenced by attrp, and the spawn-pgroup attribute
of the same object is non-zero, the child's process group is as specified
in the spawn-pgroup attribute of the object
referenced by attrp.
- As a special case, if the POSIX_SPAWN_SETPGROUP flag
is set in the spawn-flags attribute of the
object referenced by attrp, and the spawn-pgroup attribute
of the same object is set to 0, then the child is
in a new process group with a process group ID equal to its process
ID.
- If the POSIX_SPAWN_SETPGROUP flag is
not set in the spawn-flags attribute of
the object referenced by attrp, the new
child process inherits the parent's process group.
- If the POSIX_SPAWN_SETSCHEDPARAM flag
is set in the spawn-flags attribute of the object referenced by attrp,
but POSIX_SPAWN_SETSCHEDULER is not set,
the new process image initially has the scheduling policy of the calling
process with the scheduling parameters specified in the spawn-schedparam attribute
of the object referenced by attrp.
- If the POSIX_SPAWN_SETSCHEDULER flag
is set in the spawn-flags attribute of the
object referenced by attrp (regardless of
the setting of the POSIX_SPAWN_SETSCHEDPARAM flag),
the new process image initially has the scheduling policy specified
in the spawn-schedpolicy attribute of the
object referenced by attrp and the scheduling
parameters specified in the spawn-schedparam attribute
of the same object.
- The POSIX_SPAWN_RESETIDS flag in the spawn-flags attribute
of the object referenced by attrp governs
the effective user ID of the child process. If this flag is not set,
the child process inherits the parent process' effective user ID.
If this flag is set, the child process' effective user ID is reset
to the parent's real user ID. In either case, if the set-user-ID mode
bit of the new process image file is set, the effective user ID of
the child process becomes that file's owner ID before the new process
image begins execution.
- The POSIX_SPAWN_RESETIDS flag in the spawn-flags attribute
of the object referenced by attrp also governs
the effective group ID of the child process. If this flag is not set,
the child process inherits the parent process' effective group ID.
If this flag is set, the child process' effective group ID is reset
to the parent's real group ID. In either case, if the set-group-ID
mode bit of the new process image file is set, the effective group
ID of the child process becomes that file's group ID before the new
process image begins execution.
- If the POSIX_SPAWN_SETSIGMASK flag is
set in the spawn-flags attribute of the
object referenced by attrp, the child process
initially has the signal mask specified in the spawn-sigmask attribute
of the object referenced by attrp.
- If the POSIX_SPAWN_SETSIGDEF flag is
set in the spawn-flags attribute of the
object referenced by attrp, the signals
specified in the spawn-sigdefault attribute
of the same object is set to their default actions in the child process.
Signals set to the default action in the parent process are set to
the default action in the child process. Signals set to be caught
by the calling process are set to the default action in the child
process.
- Except for SIGCHLD, signals set to be
ignored by the calling process image are set to be ignored by the
child process, unless otherwise specified by the POSIX_SPAWN_SETSIGDEF flag
being set in the spawn-flags attribute of
the object referenced by attrp and the signals
being indicated in the spawn-sigdefault attribute
of the object referenced by attrp.
- If the SIGCHLD signal is set to be ignored
by the calling process, it is unspecified whether the SIGCHLD signal
is set to be ignored or set to the default action in the child process.
This is true unless otherwise specified by the POSIX_SPAWN_SETSIGDEF flag
being set in the spawn_flags attribute of
the object referenced by attrp and the SIGCHLD signal
being indicated in the spawn_sigdefault attribute
of the object referenced by attrp.
- If the value of the attrp pointer is
NULL, then the default values are used.
All process attributes, other than those influenced by the attributes
set in the object referenced by
attrp in
the preceding list or by the file descriptor manipulations specified
in
file_actions, are displayed in the new
process image as though
fork had been called
to create a child process and then a member of the
exec family
of functions had been called by the child process to execute the new
process image.
By default, fork handlers are not run in posix_spawn or posix_spawnp routines.
To enable fork handlers, set the POSIX_SPAWN_FORK_HANDLERS flag
in the attribute.
Return Values
Upon
successful completion, posix_spawn and posix_spawnp return
the process ID of the child process to the parent process, in the
variable pointed to by a non-NULL pid argument,
and return 0 as the function return value. Otherwise,
no child process is created, the value stored into the variable pointed
to by a non-NULL pid is unspecified, and
an error number is returned as the function return value to indicate
the error. If the pid argument is a null
pointer, the process ID of the child is not returned to the caller.