posix_spawnp()

Spawn a process (using executable name)

Synopsis:

#include <sys/spawn.h>

/* If using C and gcc version 2.95, use: */

int posix_spawnp(pid_t *_Restrict pid,
        const char *_Restrict file,
        const posix_spawn_file_actions_t *file_actions,
        const posix_spawnattr_t *_Restrict attrp,
        char *const argv[],
        char *const envp[]);

/* If using C++ and gcc higher than version 2.95,
   use: */

int posix_spawnp(pid_t *_Restrict pid,
        const char *_Restrict file,
        const posix_spawn_file_actions_t *file_actions,
        const posix_spawnattr_t *_Restrict attrp,
        char *const argv[_Restrict_arr],
        char *const envp[_Restrict_arr]);

A pointer to an argument vector. The value in argv[0] should represent the filename of the program being loaded, but can be NULL if no arguments are being passed. The last member of argv must be a NULL pointer. The value of argv can't be NULL.

attrp

A pointer to a spawn attributes object. If the value of the attrp pointer is NULL, then the default values are used.

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.

file

The name of the executable file. The file parameter to posix_spawnp() is used to construct a pathname that identifies the new process image file. If the file parameter contains a slash character, the file parameter is used as the pathname for the new process image file. Otherwise, the path prefix for this file is obtained by a search of the directories passed as the environment variable PATH (see the Base Definitions volume of IEEE Std 1003.1-2001, Chapter 8, Environment Variables). If this environment variable isn't defined, the results of the search are implementation-defined.

file_actions

If file_actions is a NULL pointer, then file descriptors open in the calling process will remain open in the child process, except for those whose close-on-exec flag FD_CLOEXEC is set (see fcntl()). For those file descriptors that remain open, all attributes of the corresponding open file descriptions, including file locks (see fcntl()), will remain unchanged. If file_actions is not NULL, then the file descriptors open in the child process will be those open in the calling process as modified by the spawn file actions object pointed to by file_actions and the FD_CLOEXEC flag for each remaining open file descriptor after the spawn file actions have been processed. The effective order of processing the spawn file actions will be:

The set of open file descriptors for the child process will initially be the same set as is open for the calling process. All attributes of the corresponding open file descriptions, including file locks (see fcntl()), will remain unchanged.
The signal mask, signal default actions, and the effective user and group IDs for the child process will be changed as specified in the attributes object referenced by attrp.
The file actions specified by the spawn file actions object are performed in the order in which they were added to the spawn file actions object.
Any file descriptor that has its FD_CLOEXEC flag set (see fcntl()) will be closed. The posix_spawnattr_t spawn attributes object type is defined in <spawn.h>. It will contain at least the attributes defined below.

pid

The process ID.

Library:

libc

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

Description:

The posix_spawnp() function creates a new process (child process) from the specified process image. The new process image is constructed from a regular executable file called the new process image file. This means that the only difference between posix_spawnp() and posix_spawn() is that posix_spawnp() accepts the name of an executable without its full path having been specified. Therefore, all this function needs to do is to locate file and then prefix it with its location (as required). posix_spawn() can then be called to perform the actual work.

For more information, see posix_spawn.

Returns:

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

Errors:

EINVAL: For any invalid parameter. An invalid argument was provided including an improperly initialized posix_spawnattr_t or posix_spawn_file_actions_t object.
EIO: An internal error occurred in the library.
ENOENT: The file argument couldn't be found in any of the PATH environment variable locations.
ENOMEM: The memory required to create the message to send to procnto couldn't be allocated memory to create the new process and its associated data structures couldn't be allocated. For partitions, the partition ID couldn't be added to the attributes object.
EOK: Success.
errno: Any error returned by a stat() on path.
ETXTBSY: The text file that you're trying to execute is busy (e.g. it might be open for writing).

When Adaptive Partitioning modules are also included in the image, the following error codes can be returned:

EACCES

The spawned program does not have permission to associate with the specified partitions.

EEXIST

Either one of the following errors have occur ed:

An attempt to associate with more than one partition of a given memory class. This typically occurs when you create a group name partition with more than one pseudo partition of the same memory clas,s and then an attempt to spawn a process and associate with that group name partition.
An attempt to associate with more than one scheduling partition. This typically occurs when you create a group name partition with more than one scheduler pseudo partition, and then attempt to spawn a process and associate with that group name partition.

ENOMEM

The posix_spawnattr_t object specifies a memory partition that doesn't exist. The new process was unable to associate with one or more memory partitions to be inherited from the parent process.

For EINVAL, posix_spawn() might fail if:

The value specified by file_actions or attrp is invalid. If this error occurs after the calling process successfully returns from the posix_spawn() or posix_spawnp() function, the child process may exit with exit status 127.
If posix_spawn() or posix_spawnp() fail for any of the reasons that would cause fork() or one of the exec() family of functions to fail, an error value will be returned as described by fork() and exec(), respectively (or, if the error occurs after the calling process successfully returns, the child process exits with exit status 127).
If POSIX_SPAWN_SETPGROUP is set in the spawn-flags attribute of the object referenced by attrp, and posix_spawn() or posix_spawnp() fails while changing the child's process group, an error value will be returned as described by setpgid() (or, if the error occurs after the calling process successfully returns, the child process exits with exit status 127).
If POSIX_SPAWN_SETSCHEDPARAM is set and POSIX_SPAWN_SETSCHEDULER isn't set in the spawn-flags attribute of the object referenced by attrp, then if posix_spawn() or posix_spawnp() fails for any of the reasons that would cause sched_setparam() to fail, an error value will be returned as described by sched_setparam() (or, if the error occurs after the calling process successfully returns, the child process exits with exit status 127).
If POSIX_SPAWN_SETSCHEDULER is set in the spawn-flags attribute of the object referenced by attrp, and ifposix_spawn() or posix_spawnp() fails for any of the reasons that would cause sched_setscheduler() to fail, an error value will be returned as described by sched_setscheduler() (or, if the error occurs after the calling process successfully returns, the child process exits with exit status 127).
If the file_actions argument is not NULL, and specifies any close(), dup2(), or open() actions to be performed, and if posix_spawn() or posix_spawnp() fails for any of the reasons that would cause close(), dup2(), or open() to fail, an error value will be returned as described by close(), dup2(), and open(), respectively (or, if the error occurs after the calling process successfully returns, the child process will exit with exit status 127). An open() file action may, by itself, result in any of the errors described by close() or dup2(), in addition to those described by open()).

Classification:

POSIX 1003.1 RTS

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