spawn()

Create and execute a new child process

Synopsis:

#include <spawn.h>

pid_t spawn( const char * path,
             int fd_count, 
             const int fd_map[ ], 
             const struct inheritance * inherit, 
             char * const argv[ ], 
             char * const envp[ ] );

Arguments:

path
The full path name of the executable.
fd_count
The number of entries in the fd_map array. If fd_count is 0, fd_map is ignored, and the child process inherits all file descriptors (except for the ones modified with fcntl()'s FD_CLOEXEC flag).
fd_map
An array of file descriptors that you want the child process to inherit. If fd_count isn't 0, fd_map must contain at least fd_count file descriptors, up to a maximum of OPEN_MAX. The first three entries (if specified) become the child process's standard input, standard output, and standard error (stdin, stdout, and stderr).

If you set fdmap[X] to SPAWN_FDCLOSED instead of to a valid file descriptor, the file descriptor X is closed in the child process.

For more information, see Mapping file descriptors,” below.

inherit
A structure, of type struct inheritance, that indicates what you want the child process to inherit from the parent. For more information, see inheritance structure,” below.
argv
A pointer to an argument vector. The value in argv[0] can't be NULL, and should represent the filename of the program being loaded. The last member of argv must be a NULL pointer. The value of argv can't be NULL.
envp
A pointer to an array of character pointers, each pointing to a string defining an environment variable. The array is terminated with a NULL pointer. Each pointer points to a character string of the form:
variable=value
  

that's used to define an environment variable. If the value of envp is NULL, then the child process inherits the environment of the parent process.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The spawn() function creates and executes a new child process, named in path.


Note: If the new child process is a shell script, the first line must start with #!, followed by the path of the program to run to interpret the script, optionally followed by one argument. The script must also be marked as executable. For more information, see The first line in the Writing Shell Scripts chapter of the Neutrino User's Guide.

The spawn() function is a QNX Neutrino function (based on the POSIX 1003.1d draft standard). The C library also includes several specialized spawn*() functions. Their names consist of spawn followed by several letters:

This suffix: Indicates the function takes these arguments:
e An array of environment variables.
l A NULL-terminated list of arguments to the program.
p A relative path. If the path doesn't contain a slash, the PATH environment variable is searched for the program. This suffix also lets the #! construction work; see SPAWN_CHECK_SCRIPT, below.
v A vector of arguments to the program.

As shown below, these functions eventually call spawn(), which in turn sends a message to the process manager.

spawn spawnve spawnl spawnv spawnle spawnp spawnvpe spawnlpe spawnvp spawnlp

To view the documentation for a function, click its name in this diagram:


How the spawn functions are related


Most of the spawn*() functions do a lot of work before a message is sent to procnto.

The child process inherits the following attributes of the parent process:

The child process has several differences from the parent process:

The child process also has these differences from the parent process if you haven't set the SPAWN_EXEC flag:

If the child process is spawned on a remote node, the process group ID and the session membership aren't set; the child process is put into a new session and a new process group.

The child process can access its environment by using the environ global variable (found in <unistd.h>).

If the path is on a filesystem mounted with the ST_NOSUID flag set, the effective user ID, effective group ID, saved set-user ID and saved set-group ID are unchanged for the child process. Otherwise, if the set-user ID mode bit is set, the effective user ID of the child process is set to the owner ID of path. Similarly, if the set-group ID mode bit is set, the effective group ID of the child process is set to the group ID of path.

The real user ID, real group ID and supplementary group IDs of the child process remain the same as those of the parent process. The effective user ID and effective group ID of the child process are saved as the saved set-user ID and the saved set-group ID used by the setuid().


Note: A parent/child relationship doesn't imply that the child process dies when the parent process dies.

Mapping file descriptors

As described above, you can use the fd_count and fd_map arguments to specify which file descriptors you want the child process to inherit.

The number used for a file descriptor in the child process depends on its position in fd_map, not on the actual file descriptor in the parent. For example, suppose the parent has file descriptors valued 1, 3, and 5 that you want to have in the child process. If you specify:

int fd_map = { 1, 3, 5 };

then the mapping is as follows:

In the child, this fd: Is the same as this fd in the parent:
0 1
1 3
2 5

If 1, 3, and 5 are the only file descriptors open in the parent, and you specify an fd_count of 0, the function duplicates all the file descriptors:

In the child, this fd: Is the same as this fd in the parent:
1 1
3 3
5 5

and file descriptors 0, 2, 4, and 6 (and higher) are closed.

If you're using an explicit fd_map, then in order to get numerically matching file descriptors in the child and the parent, you must fill the holes in the map with SPAWN_FDCLOSE:

int fd_map = { SPAWN_FDCLOSE, 1, SPAWN_FDCLOSE, 3, SPAWN_FDCLOSE, 5 };

Note: Be careful if you use SPAWN_FDCLOSE for file descriptors 0, 1, and 2. If the child process calls open(), the function assigns the lowest numbered unused file descriptor. If, for example, you set stdout or 1 to SPAWN_FDCLOSED, the next open() in the spawned application is assigned file descriptor 1. In this case, printf() would write to whatever resource was opened, which may or may not be what you intended.

It's safer to set 0, 1 and 2 to be the file descriptor from an open() of a known resource (such as /dev/null) in the parent, and then pass those file descriptors to the child.


inheritance structure

The inheritance structure contains at least these members:

unsigned long flags
Zero or more of the following bits:

The <spawn.h> file also defines SPAWN_ALIGN_MASK. It's a mask for the alignment flags listed above.

pid_t pgroup
The child process's group if you specify SPAWN_SETGROUP in the flags member.

If SPAWN_SETGROUP is set in inherit.flags and inherit.pgroup is set to SPAWN_NEWPGROUP, the child process starts a new process group with the process group ID set to its process ID.

int runmask
(QNX Neutrino Core OS 6.3.2 or later) If you specify SPAWN_EXPLICIT_CPU in the flags member, the child process's runmask and inherit mask are set to the value of this member. For more information, see the Multicore Processing User's Guide.
sigset_t sigmask
The child process's signal mask if you specify SPAWN_SETSIGMASK in the flags member.
sigset_t sigdefault
The child process's set of defaulted signals if you specify SPAWN_SETSIGDEF in the flags member.
sigset_t sigignore
The child process's set of ignored signals if you specify SPAWN_SETSIGIGN in the flags member.
unsigned long stack_max
The maximum stack size for the child process, if you set SPAWN_SETSTACKMAX in the flags member.
int policy
The scheduling policy for the child process, if you set SPAWN_EXPLICIT_SCHED in the flags member. The policy must be one of the following:
uint32_t nd
The node descriptor of the remote node on which to spawn the child process. This member is used only if you set SPAWN_SETND in the flags member.

Note: If you want to spawn() remotely, set the nd member to the node descriptor. See the netmgr_strtond() function.

struct sched_param param
Scheduling parameters for the child process, if you set SPAWN_EXPLICIT_SCHED in the flags member. For more information, see the documentation for sched_param.

Returns:

The process ID of the child process, or -1 if an error occurs (errno is set).


Note: If you set SPAWN_EXEC in the flags member of the inheritence structure, spawn() doesn't return, unless an error occurred.

Errors:

E2BIG
The number of bytes used by the argument list and environment list of the new child process is greater than ARG_MAX bytes.
EACCESS
Search permission is denied for a directory listed in the path prefix of the new child process or the child process's file doesn't have the execute bit set or path's filesystem was mounted with the ST_NOEXEC flag.
EAGAIN
Insufficient resources available to create the child process.
EBADF
An entry in fd_map refers to an invalid file descriptor, or an error occurred duplicating open file descriptors to the new process.
EFAULT
One of the buffers specified in the function call is invalid.
EINTR
The function was interrupted by a signal.
EINVAL
An argument is invalid (e.g. argv[0] is NULL).
ELOOP
Too many levels of symbolic links or prefixes.
EMFILE
Insufficient resources available to load the new executable image or to remap file descriptors in the child process.
ENAMETOOLONG
The length of path exceeds PATH_MAX or a pathname component is longer than NAME_MAX.
ENOENT
The file identified by the path argument is empty, or one or more components of the pathname of the child process don't exist.
ENOEXEC
The child process's file has the correct permissions, but isn't in the correct format for an executable. (This error doesn't occur if SPAWN_CHECK_SCRIPT is set in the flags member of the inheritance structure.)
ENOMEM
Insufficient memory available to create the child process.
ENOSYS
The spawn() function isn't implemented for the filesystem specified in path.
ENOTDIR
A component of the path prefix of the child process isn't a directory.
ETXTBSY
The text file that you're trying to execute is busy (e.g. it might be open for writing).

Classification:

QNX Neutrino

Safety:
Cancellation point No
Interrupt handler No
Signal handler Yes
Thread Yes

See also:

execl(), execle(), execlp(), execlpe(), execv(), execve(), execvp(), execvpe(), getenv(), netmgr_strtond(), posix_spawn(), posix_spawnp(), putenv(), sched_param, setenv(), sigaddset(), sigdelset(), sigemptyset(), sigfillset(), spawnl(), spawnle(), spawnlp(), spawnlpe(), spawnp(), spawnv(), spawnve(), spawnvp(), spawnvpe(), wait(), waitpid()

Processes and Threads chapter of Getting Started with QNX Neutrino