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]);

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 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:
  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 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:
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:

Classification:

POSIX 1003.1 RTS

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

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()