POSIX_SPAWN(3) FreeBSD Library Functions Manual POSIX_SPAWN(3)
NAME
posix_spawn, posix_spawnp - launch external command
SYNOPSIS
#include <spawn.h>
int
posix_spawn(pid_t *restrict pidp, 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 pidp, 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() function forks a new process and starts an external
program from pathname path.
The posix_spawnp() function is similar, except it constructs the pathname
from file following the usual PATH handling rules: if file contains a
slash, then it is directly used as a path. Otherwise, posix_spawnp()
searches every directory mentioned in PATH until it finds an executable.
If PATH is not set, the default is "/usr/bin:/bin".
Arguments to the new process are passed to execve(2) as argv and envp.
If envp is NULL, the environment is passed unchanged from the parent
process.
If file_actions is a null pointer, file descriptors open in the parent
process follow the usual rules: they remain open in the child process
unless they've been marked FD_CLOEXEC with fcntl(2).
Otherwise, file descriptors in the child process are altered according to
posix_spawn_file_actions_init(3), posix_spawn_file_actions_addclose(3),
posix_spawn_file_actions_adddup2(3), and
posix_spawn_file_actions_addopen(3).
The attrp argument can be used to control signal, UID and GID handling in
the child process.
If attrp is NULL, default values are used: caught signals in the parent
process are set to the default value in the child process, and ignored
signals stay ignored.
See posix_spawnattr_setflags(3) for attribute details.
RETURN VALUES
Upon successful completion, both functions return 0. If pidp is not a
NULL pointer, *pidp gets set to the PID of the newly created child
process.
In case of an error, both functions may return fork() or exec() return
values and set errno accordingly.
Note, however, that after the new process is started, the child process
has no way to return an error value. In case of a problem, the child
process will instead exit with exit status 127.
SEE ALSO
execve(2), fork(2), posix_spawn_file_actions_addclose(3),
posix_spawn_file_actions_init(3), posix_spawnattr_init(3),
posix_spawnattr_setflags(3)
STANDARDS
Both functions conform to IEEE Std 1003.1-2001 ("POSIX.1").
The handling of NULL envp is an extension to that standard.
HISTORY
These functions were ported from FreeBSD to OpenBSD 5.2.
AUTHORS
Ed Schouten <
[email protected]>
FreeBSD 14.1-RELEASE-p8 June 26, 2023 FreeBSD 14.1-RELEASE-p8