posix_spawnp()

Spawn a process (using executable name)

Synopsis:

#include <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],
        char *const envp[_Restrict]);

Arguments:

argv

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 spawn attribute object.

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 is not 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()), shall 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 of each remaining open file descriptor after the spawn file actions have been processed. The effective order of processing the spawn file actions will be:

1. 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.
2. 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.
3. 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.
4. 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 could not be found in any of the PATH environment variable locations.

ENOMEM

The memory required to create the message to send to procnto could not be allocated memory to create the new process and its associated data structures could not 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.

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 class 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 an attempt to spawn a process and associate with that group name partition.

ENOMEM

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

Classification:

POSIX 1003.1 RTS

See also:

posix_spawn(), posix_spawn_file_actions_addclose(), posix_spawn_file_actions_adddup2(), posix_spawn_file_actions_addopen(), posix_spawn_file_actions_destroy(), posix_spawn_file_actions_init(), posix_spawnattr_addpartid(), posix_spawnattr_addpartition(), posix_spawnattr_destroy(), posix_spawnattr_getcred(), posix_spawnattr_getflags(), posix_spawnattr_getnode(), posix_spawnattr_getpartid(), posix_spawnattr_getpgroup(), posix_spawnattr_getrunmask(), posix_spawnattr_getschedparam(), posix_spawnattr_getschedpolicy(), posix_spawnattr_getsigdefault(), posix_spawnattr_getsigignore(), posix_spawnattr_getsigmask(), posix_spawnattr_getstackmax(), posix_spawnattr_getxflags(), posix_spawnattr_init(), posix_spawnattr_setcred(), posix_spawnattr_setflags(), posix_spawnattr_setnode(), posix_spawnattr_setpgroup(), posix_spawnattr_setschedparam(), posix_spawnattr_setrunmask(), posix_spawnattr_setschedpolicy(), posix_spawnattr_setsigdefault(), posix_spawnattr_setsigignore(), posix_spawnattr_setstackmax(), posix_spawnattr_setstackmax(), posix_spawnattr_setxflags()