posix_spawn(), posix_spawnp()

Arguments:

pid

NULL, or a pointer to a location where the function can store the process ID of the child process.

path

(posix_spawn() only) A path to the executable.

file

(posix_spawnp() only) The name of the executable file, which is used to construct a pathname that identifies the new process image file:

• If file contains a slash, the argument 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 PATH environment variable. In QNX Neutrino, if PATH isn't defined, the function searches for the executable in the current working directory.

file_actions

NULL, or a pointer to an opaque spawn file actions object that specifies the actions you want to perform on the file descriptors in the child process. For more information, see “File actions,” below.

attrp

NULL, or a pointer to an opaque spawn attributes object that describes attributes to be applied during the spawn. If attrp is NULL, then the default attribute values are used. For more information, see the “Attributes” section, below.

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

As a QNX Neutrino extension, the value of argv can be NULL. In this case, the behavior is exactly as if argv were a pointer to the two-element array:

• {path, NULL} for posix_spawn()
• {file, NULL} for posix_spawnp()

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.

If a variable appears more than once in the envp array, the behavior is undefined.

Library:

libc

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

Description:

A running process has two sets of credentials of importance during its execution: the real user and group IDs (ruid and rgid respectively) and the effective user and group IDs (euid and egid respectively). Typically, when a new process (a child process) is spawned, both sets of credentials (real and effective) are taken from the spawning (parent) process. The exception to this is if the executable file being spawned has either its setuid and/or setgid mode bits set, in which case the euid is set to the uid of the executable, and/or the egid is set to the gid of the executable. POSIX doesn't define a way to directly specify the ruid and rgid of a spawned process. If you want to do this, call posix_spawnattr_setcred() —a QNX Neutrino extension—before spawning the child process.

When a C program is executed as the result of calling posix_spawn() or posix_spawnp(), it's entered as a C-language function call as follows:

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

where argc is the argument count and argv is an array of character pointers to the arguments themselves.

In addition, the global environ variable is initialized as a pointer to an array of character pointers to the environment strings. The argument argv is an array of character pointers to NULL-terminated strings. The last member of this array is a NULL pointer and isn't counted in argc. These strings constitute the argument list available to the new process image. The value in argv[0] should point to a filename that's associated with the process image that you're starting.

The number of bytes available for the child process's combined argument and environment lists is {ARG_MAX}.

On successful completion, posix_spawn() and posix_spawnp() store the process ID of the child process in the variable pointed to by a non-NULL pid argument, and return zero as the function return value. Otherwise, no child process is created, the value stored in the variable pointed to by a non-NULL pid is undefined, and the functions return an error number. If the pid argument is NULL, the process ID of the child isn't returned to the caller.

If you're using adaptive partitioning, the child runs in the same partition as the parent; you can use SchedCtl() to control that after the child has been spawned.

File actions

The spawn file actions let you control which files are open in the spawned process. These actions are defined in an opaque posix_spawn_file_actions_t object.

If file_actions is NULL, then the file descriptors that are open in the calling process remain open in the child process, except for those whose close-on-exec flag, FD_CLOEXEC, is set. For those file descriptors that remain open, all attributes of the corresponding open file descriptions, including file locks, remain unchanged. For more information about FD_CLOEXEC and file locks, see fcntl().

To destroy the file actions object, call posix_spawn_file_actions_destroy().

Attributes

The spawn attributes are defined in an opaque posix_spawnattr_t object. Use posix_spawnattr_init() to initialize the object, and posix_spawnattr_destroy() to destroy it.

You can do the following by using the attributes defined by POSIX. You can get and set the POSIX flags by calling the POSIX posix_spawnattr_getflags() and posix_spawnattr_setflags() routines, or the QNX Neutrino posix_spawnattr_getxflags() and posix_spawnattr_setxflags() routines.

You can do the following by using the attributes defined as extensions by QNX Neutrino. You can get and set the QNX Neutrino and POSIX flags by calling posix_spawnattr_getxflags() and posix_spawnattr_setxflags(). Both of these routines are QNX Neutrino extensions.

Returns:

EOK

The child was successfully spawned.

EBADF

A problem occurred when posix_spawn() was duplicating a file descriptor. For example, another thread might have opened or closed a file descriptor while the posix_spawn() was occurring. You can add synchronization around the operations that involve file descriptors, or try calling posix_spawn() again.

EINVAL

An argument was invalid; the spawn attributes or file actions object is invalid, or the name of the process image file is NULL or an empty string.

If you specify an invalid value in the file actions or spawn attributes, posix_spawn() or posix_spawnp() might fail; if the value causes an error to occur after the child has been successfully spawned, the child process may exit with a status of 127.

EIO

An internal error occurred in the library.

ENAMETOOLONG

• The length of the path argument is greater than PATH_MAX.
• An action set with posix_spawn_file_actions_addopen() has a path that's longer than PATH_MAX.

In both cases the length of the path used for comparing against PATH_MAX includes the terminating NUL.

ENOENT

• For posix_spawn(), the executable specified by the path argument couldn't be found.
• For posix_spawnp(), the executable specified by 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.

ENOTSUP

No security policy has been loaded. (To use this function, you must load a security policy.)

EPERM

The calling process doesn't have the required permission (see procmgr_ability()), or an underlying call to mmap() failed because it attempted to set PROT_EXEC for a region of memory covered by an untrusted memory-mapped file. This error may also indicate that the process lacks the PROCMGR_AID_SETTYPEID ability or does not have a subrange that includes typeid.

ESECTYPEINVAL

The type identifier either does not exist or has no abilities associated with it. A type must be the source type in at least one allow, allow_attach or allow_link rule for a process to have its type identifier set to it. (These rules are defined in the security policy.)

ETXTBSY

The text file that you're trying to execute is busy (e.g., it might be open for writing).

If posix_spawn() or posix_spawnp() fails for any of the reasons that would cause fork() or one of the exec*() family of functions to fail, an error value is returned as described for those functions (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 is returned as described for 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 is returned as described for 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 if posix_spawn() or posix_spawnp() fails for any of the reasons that would cause sched_setscheduler() to fail, an error value is returned as described for 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 isn't 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 is returned as described for those functions (or, if the error occurs after the calling process successfully returns, the child process exits with exit status 127). For example, if the parent process closes a file descriptor while it's being duplicated, you'll get an error of EBADF. 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().

The posix_spawn() and posix_spawnp() functions can also return any error returned by a stat() on path. See also the errors for ConnectAttach() and MsgSendvnc().

Examples:

Specify an absolute path, using posix_spawn():

pid_t child_pid;
int ret;

ret = posix_spawn (&child_pid, "/home/dpr/hello", NULL, NULL, NULL, NULL);
if (ret != EOK)
{
    printf("posix_spawn() failed: %s\n", strerror(ret) );
    return EXIT_FAILURE;
}

printf ("Child pid: %d\n\n", child_pid);

To specify a relative path, use posix_spawnp():

ret = posix_spawnp (&child_pid, "./hello", NULL, NULL, NULL, NULL);

If the path doesn't include a slash, search the PATH for the executable:

ret = posix_spawnp (&child_pid, "hello", NULL, NULL, NULL, NULL);

Use the spawn attributes and flags to lower the child process's priority (with error checking omitted, in the interest of brevity):

pid_t child_pid;
posix_spawnattr_t attr;
int policy;
struct sched_param param;

/* Get the parent's scheduling policy and parameters. */
pthread_getschedparam (pthread_self(), &policy, &param);

/* Initialize the spawn attributes structure. */
posix_spawnattr_init (&attr);

/* Set the child's priority to be two levels lower. */
param.sched_priority -= 2;
posix_spawnattr_setschedparam (&attr, &param);

/* Set the appropriate flag to make the changes take effect. */
posix_spawnattr_setflags (&attr, POSIX_SPAWN_SETSCHEDPARAM);
  
/* Spawn the child process. */
posix_spawnp (&child_pid, "./hello", NULL, &attr, NULL, NULL);

Classification:

POSIX 1003.1 SPN