Start a new process.
The posix_spawn
API replaces the fork
and exec
method that is common in
UNIX systems, for systems that lack the necessary hardware for an efficient
fork
implementation.
The file actions and spawn attributes help emulating the typical fork
and
exec
scenario. Normally, fork
is used to duplicate the running process
including its open resources. The return value of the call tell if the code
is now executing in the child or parent process. It is then possible to do
various setup work before calling exec
in the child process, which replaces
the running binary.
The file actions makes it possible to specify a set of actions to perform on
the programs file descriptor after what is normally the fork
stage.
Available options are open
and dup2
. The file actions structure must be
initialized using posix_spawn_file_actions_init
and de-initialized using
posix_spawn_file_actions_destroy
after use with posix_spawn
.
The spawn attributes makes it possible to add miscellaneous operations that are commonly done when starting a program. These are setting the spawn attribute flag and the process group.
For a complete example of how to use this API, consider checking the program
bin/sh
.
Syntax
#include <spawn.h>
int posix_spawn (pid_t *pid, const char *path,
const posix_spawn_file_actions_t *factions,
const posix_spawnattr_t *sattr,
char **argv, char **env);
Attribute helper functions:
int posix_spawnattr_init (posix_spawnattr_t *attr);
int posix_spawnattr_setflags (posix_spawnattr_t *attr, int flags);
int posix_spawnattr_setpgroup (posix_spawnattr_t *attr, int pgroup);
int posix_spawnattr_destroy (posix_spawnattr_t *attr);
File actions helper functions:
int posix_spawn_file_actions_init (posix_spawn_file_actions_t *factions);
int posix_spawn_file_actions_addopen (posix_spawn_file_actions_t *factions,
int fildes, char *path, int oflag, int mode);
int posix_spawn_file_actions_adddup2 (posix_spawn_file_actions_t *factions,
int fildes, int newfildes);
int posix_spawn_file_actions_destroy (posix_spawn_file_actions_t *factions);
Parameters
-
pid
A pointer to a
pid_t
that will receive the process ID (PID) of the started process. -
path
Full path to the program executable.
-
factions
Pointer to an optional file actions structure. If unused, set to null.
-
sattr
Pointer to an optional spawn attributes structure. If unused, set to null.
-
argv
List of strings that will be supplied as the program arguments (appears as
argv
in itsmain
function). The first argument is usually expected to be the program name. Note that this is a pointer to a pointer array, which must be terminated by a null pointer and not a null string. -
env
Same as
argv
, except for the environment variables. To inherit the environment of the caller, pass the global variableenviron
as this argument.
Return Value
The return value is null if successful. Otherwise, the return value is negative and errno is set:
-
ENOMEM
Out of memory.
-
ENOEXEC
Executable file format error. The file may be corrupted, compiled for the wrong architecture or contain unknown relocation types.
Remarks
Errors raised by processing the file actions and/or spawn attributes are ignored.