OpenBSD manual page server

Manual Page Search Parameters

POSIX_SPAWN(3) Library Functions Manual POSIX_SPAWN(3)

posix_spawn, posix_spawnplaunch external command

#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]);

The () function forks a new process and starts an external program from pathname path.

The () 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.

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.

execve(2), fork(2), posix_spawn_file_actions_addclose(3), posix_spawn_file_actions_init(3), posix_spawnattr_init(3), posix_spawnattr_setflags(3)

Both functions conform to IEEE Std 1003.1-2001 (“POSIX.1”).

The handling of NULL envp is an extension to that standard.

These functions were ported from FreeBSD to OpenBSD 5.2.

Ed Schouten <ed@FreeBSD.org>

June 26, 2023 OpenBSD-current