POSIX_SPAWN(3) | 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 <ed@FreeBSD.org>

June 26, 2023 | Debian