66 lines
2.6 KiB
Markdown
66 lines
2.6 KiB
Markdown
## Name
|
|
|
|
posix\_spawn - launch a new process
|
|
|
|
## Synopsis
|
|
|
|
```**c++
|
|
#include <spawn.h>
|
|
|
|
int posix_spawn(pid_t* pid, const char* executable_path, const posix_spawn_file_actions_t*, const posix_spawnattr_t*, char* const argv[], char* const envp[]);
|
|
int posix_spawnp(pid_t* pid, const char* executable_path, const posix_spawn_file_actions_t*, const posix_spawnattr_t*, char* const argv[], char* const envp[]);
|
|
```
|
|
|
|
## Description
|
|
|
|
Spawn a new process reading the binary `executable_path`, passing `argv` as arguments to `main()` and setting `envp` as argument.
|
|
|
|
Places the process ID of the new process in `pid`.
|
|
|
|
If `executable_path` passed to `posix_spawn` is a relative path, it is resolved relative to the current working directory.
|
|
|
|
If `executable_path` passed to `posix_spawnp` is a relative path, it is resolved by searching through directories specified in the `PATH` environment variable.
|
|
|
|
The `posix_spawn_file_actions_t` and `posix_spawnattr_t` arguments may be `nullptr`. If they aren't, see [`posix_spawn_file_actions`(2)](posix_spawn_file_actions_init.md) and [`posix_spawnattr`(2)](posix_spawnattr_init.md) for what they do.
|
|
|
|
The last entry in `argv` and `envp` has to be `nullptr`.
|
|
|
|
The new process is started as if the following steps are executed in this order:
|
|
|
|
1. A new process is started as if `fork()` was called.
|
|
2. If the `posix_spawnattr_t` parameter is non-nullptr, it [takes effect](posix_spawnattr_init.md).
|
|
3. If the `posix_spawn_file_actions_t` parameter is non-nullptr, it [takes effect](posix_spawn_file_actions_init.md).
|
|
4. `executable_path` is loaded and starts running, as if `execve` or `execvpe` was called.
|
|
|
|
## Return value
|
|
|
|
If the process is successfully forked, returns 0.
|
|
Otherwise, returns an error number. This function does *not* return -1 on error and does *not* set `errno` like most other functions, it instead returns what other functions set `errno` to as result.
|
|
|
|
If the process forks successfully but spawnattr or file action processing or exec fail, `posix_spawn` returns 0 and the child exits with exit code `127`.
|
|
|
|
## Example
|
|
|
|
This simple example launches `/bin/Calculator`.
|
|
|
|
To make the child process use the parent's environment, it passes `environ` from `unistd.h`.
|
|
|
|
```**c++
|
|
#include <errno.h>
|
|
#include <unistd.h>
|
|
#include <stdio.h>
|
|
#include <spawn.h>
|
|
|
|
int main()
|
|
{
|
|
const char* argv[] = { "Calculator", nullptr };
|
|
pid_t child_pid;
|
|
if ((errno = posix_spawn(&child_pid, "/bin/Calculator", nullptr, nullptr, const_cast<char**>(argv), environ)))
|
|
perror("posix_spawn");
|
|
}
|
|
```
|
|
|
|
## See also
|
|
|
|
* [`posix_spawnattr`(2)](posix_spawnattr_init.md)
|
|
* [`posix_spawn_file_actions`(2)](posix_spawn_file_actions_init.md)
|