posix_spawn(), posix_spawnp() -- spawn a process

SYNOPSIS

#include <spawn.h>

int posix_spawn(pid_t *restrict pid, const char *restrict path, const posix_spawn_file_actions_t *file_actions, const posix_spawnattr_t *restrict attrp, char *const argv, char *const envp);

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

Using a specified image, the functions posix_spawn() and posix_spawnp() create a new child process. These functions also construct a new process image from a regular executable called the new process image file.

When you use this call to run a C program, that program is entered as the following C function call:

int main(int argc, char *argv[]);

where argc is the argument count and argv is an array of character pointers to the actual arguments. Additionally, the variable:

extern char **environ;

points to an array of character pointers to the environment strings.

The argument and environment lists for the child process can take up a maximum of {ARG_MAX} bytes.

By default, the process attributes of the new image process are the same as would occur if fork() was called to create a child process and then that child process called a member of the exec() family of functions to execute the new process impage. However, the attrp and file_actions attributes may modify these attributes as described in the PARAMETERS section.

PARAMETERS

argv

Specifies an array of character pointers to the parameter list that is to be made available as the parameter list for the new process image. Each member of this array points to a null-terminated string, except the last member which is a null pointer. This last member is not included in the argument count passed as argc when calling a C language program. The argv[0] member points to the file name associated with the process image started by posix_spawn() or posix_spawnp().

attrp

Points to a spawn attributes object of the type posix_spawnattr_t. It modifies the signal mask, signal default actions, and the effective user and groups ID of the calling process to create the corresponding attributes of the child process.

When the value of the attrp pointer is NULL, no modifications are made. Otherwise, modifications are made based on the values of various attributes in the object pointed to by attrp.

When the POSIX_SPAWN_SETPGROUP flag is set in the spawn-flags attribute and the spawn-pgroup attribute is non-zero, the child's process group is set to the value of that spawn-pgroup attribute. When the POSIX_SPACWN_SETPGROUPflag is set and the spawn-pgroup attribute is zero, the child process is created in a new process group with a process group ID equal to its process ID.

When the POSIX_SPAWN_SETGROUP flag is not set in the spawn-flags attribute, the new child process inherits the process group of the parent.

When the POSIX_SPAWN_SETSCHEDPARAM flag is set in the spawn-flags attribute and the POSIX_SPAWN_SETSCHEDULER flag is not set, the new process image is initially given the scheduling policy of the calling process with the scheduling parameters specified in the spawn-schedparam attribute.

When the POSIX_SPAWN_SETSCHEDULER flag is set in the spawn-flags attribute (regardless of how the POSIX_SPAWN_SETSCHEDPARAM flag is set), the new process image is initially set to the scheduling policy given by the spawn-schedpolicy attribute and the scheduling parameters given by the spawn-schedparam attribute.

The POSIX_SPAWN_RESETIDS flag in the spawn-flags attribute determines the effective user ID of the child process. When this flag is not set, the child process inherits the effective user ID of the parent process. When this flag is set, the effective user ID of the child process is reset to the real user ID of the parent. In either case, when the set-user-ID mode bit of the new process image file is set, the effective user ID of the child process becomes that file's owner ID before the new process image begins execution.

The POSIX_SPAWN_RESETIDS flag in the spawn-flags attribute also governs the effective group ID of the child process. When this flag is not set, the child process inherits the effective group ID of the parent process. When this flag is set, the effective group ID of the child process is reset to the real group ID of the parent. In either case, when the set-group-ID mode bit of the new process image file is set, the effective group ID of the child process becomes that file's group ID before the new process image begins execution.

When the POSIX_SPAWN_SETSIGMASK flag is set in the spawn-flags attribute, the child process is initially assigned the signal mask specified in the spawn-sigmask attribute.

When the POSIX_SPAWN_SETSIGDEF flag is set in the spawn-flags attribute, the signals specified in the spawn-sigdefault attribute are set to their default actions in the child process. Signals set to the default action in the parent process are set to the default action in the child process.

Signals set to be caught by the calling process are set to the default action in the child process.

With the exception of SIGCHLD, any signals that are set for the calling process to ignore are normally also set for the child process to ignore. However, a set POSIX_SPAWN_SETSIGDEF flag in the spawn-flags attribute of the attrp object and the signals indicated in the spawn-sigdefault attribute of the attrp object can specify otherwise.

When SIGCHLD is set for the calling process to ignore, it is unspecified whether SIGCHLD is set for the child process to ignore or to the child process' default action, unless a set POSIX_SPAWN_SETSIGDEF flag in the spawn_flags attribute of the attrp object and the SIGCHLD signal being indicated in the spawn-sigdefault attribute of the attrp object.

envp

Is an array of character pointers to null-terminated strings. These strings make up the environment for the new process image. The end of this array is indicated with a null pointer.

file

Indicates the name for the new process image file created by the created by the posix_spawnp() function. When this file name include a slash character (/, posix_spawnp() uses it as the full path name. Otherwise, posix_spawnp() determines the full path name of file by searching the directories indicated by the PATH environment variable.

file_actions

Indicates the actions that are taken on the calling process' open file descriptors to create the child process' open file descriptors.

When file_actions is a null pointer, the child process has the same open file descriptors (with unchanged attributes) as the calling process, with the exception of those descriptors with a set FD_CLOEXEC (close-on-exec) flag (see fcntl()).

A non-NULL file_action points to a spawn file actions object. The following steps are taken to determine the open file descriptors of the child process:

Initially, the child process' open file descriptors (and their attributes) are set to be the same as the calling process' descriptors.

The attrp attributes object is used to modify the signal mask, signal default actions, and the effective user and groups ID of the calling process to generate the child process' corresponding attributes.

File actions indicated by the spawn file actions object are performed (in the order they were added to the object) on the attributes of the calling process to generate the corresponding attributes of the child process.

Close all file descriptors with the FD_CLOSEC flag set (see fcntl()).

path

Indicates the path name of the new process image file for the posix_spawn() to execute.

pid

Points to the variable used to return the process ID of the child process created. When pid is a null pointer, the child process' process ID is not returned.

RETURN VALUES

When posix_spawn() and posix_spawnp() complete successfully, they return 0 and the child process' process id is returned to the parent process using the variable pointed to by a non-null pid. Otherwise, no child process is created and the functions return one of the following error numbers:

EINVAL: file_actions or attrp specifies an invalid value.

When 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.

When posix_spawn() or posix_spawnp() fail for a reason that would cause the failure of fork() or one of the exec() family of functions, an error value is 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).

When POSIX_SPAWN_SETPGROUP is set in the spawn-flags attribute of the attrp object, and posix_spawn() or posix_spawnp() fails while changing the child's process group, an error value is returned as described by setpgid() (or, if the error occurs after the calling process successfully returns, the child process exits with exit status 127).

When POSIX_SPAWN_SETSCHEDPARAM is set and POSIX_SPAWN_SETSCHEDULERis not set in the spawn-flags attribute of the attrp object, and posix_spawn() or posix_spawnp() fails for a reason that would cause sched_setparam() to fail, an error value is 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).

When POSIX_SPAWN_SETSCHEDULERis set in the spawn-flags attribute of the attrp object, and posix_spawn() or posix_spawnp() fail for a reason that would cause sched_setscheduler() to fail, an error value is 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).

When file_actions is non-NULL, and specifies any close, dup2, or open actions to be performed, and posix_spawn() or posix_spawnp() fails for a reason that would cause close(), dup2(), or open() to fail, an error value is returned as described by close(), dup2(), and open(), respectively (or, if the error occurs after the calling process successfully returns, the child process exits 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().

CONFORMANCE

UNIX 03.

MULTITHREAD SAFETY LEVEL

MT-Safe.

PORTING ISSUES

The setting of scheduling policy or scheduling parameters is not supported.

The full semantics of setuid(), setgid(), seteuid(), and setegid() cannot be implemented on Windows systems, and thus the POSIX_SPAWN_RESETIDS functionality is not fully implemented. See the PTC MKS Toolkit UNIX to Windows Porting Guide for more information.

Executable paths are treated as multibyte sequences and are converted to Unicode (UTF-16) before passing to Win32. The conversion is either performed based on the current thread locale, set using uselocale() or the process locale as set by a call to setlocale(), and overridden by _NutConf() _NC_SET_ANSI_LOCALE and _NC_SET_UTF8_LOCALE options. Under all other conditions, the multibyte sequences are considered to be from the ANSI code page for the current windows system locale.

Environment variables are sonsidered to be multibyte sequences and converted to Unicode (UTF-16) only when _NutConf() is called to set _NC_SET_UTF8_LOCALE. Environment variables are converted from OEM in the Windows system locale to Unicode (UTF-16) only when _NutConf() is called to set _NC_SET_OEM_ENVIRONMENT. Otherwise environment variables are considered to be ANSI strings in the current system locale.

The argument arrays are sonsidered to be multibyte sequences and converted to Unicode (UTF-16) only when _NutConf() is called to set _NC_SET_UTF8_LOCALE. Otherwise argument arrays are considered to be ANSI strings in the current system locale.

AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition

posix_spawn(), posix_spawnp()
spawn a process

Advanced Realtime Function