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 p1003.1-2001.

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>