_NutForkExecl(), _NutForkExecle(), _NutForkExeclp(), _NutForkExeclpe(), _NutForkExecv(), _NutForkExecve(), _NutForkExecvp(), _NutForkExecvpe() -- combination of fork() and exec() functions

SYNOPSIS

#include <nutc.h>

extern char **environ;

int _NutForkExecl(const char *path, const char *arg0, ..., const char *argn, (char *)0);

int _NutForkExecle(const char *path, const char *arg0, ..., const char *argn, (char *)0, char *const envp[]);

int _NutForkExeclp(const char *file, const char *arg0, ..., const char *argn, (char *)0);

int _NutForkExeclpe(const char *file, const char *arg0, ..., const char *argn, (char *)0, char *const envp[]);

int _NutForkExecv(const char *path, char *const argv[]);

int _NutForkExecve(const char *path, char *const argv[], char *const envp[]);

int _NutForkExecvp(const char *file, char *const argv[]);

int _NutForkExecvpe(const char *file, char *const argv[], char *const envp[]);

The _NutForkExec() family of functions combines the fork() function and the corresponding member of the exec() family of functions to create a new process. This function should be used whenever you need to create a new process, and do not need to manipulate process state (for example, closing file descriptors) in the child prior to calling an exec() function. All resources (for example, files, shared memory segments, memory mapped segments) and properties (for example, parent process ID, controlling terminals) are inherited by to the new child as if fork() had been called, followed by the corresponding exec() function. For forms of _NutForkExec() that do not take an envp argument, the environment for the new process image is taken from the external variable environ in the calling process. Otherwise, the envp argument specifies the environment for the new process image. The environment for the new process image is taken from the external variable environ in the calling process.

Handlers registered with pthread_atfork() are not invoked when a _NutForkExec() function is called, because no child process is actually created.

PARAMETERS

path: Specifies the path name of the new process image file.
file: Is used to construct a path name that identifies the new process image file. If file contains a slash character, the argument is used as the path name for this file; otherwise, the path prefix for this file is obtained by a search of the directories in the environment variable PATH. If PATH is not set, the current directory is searched.
arg0, ..., argn: Are pointers to null-terminated character strings. These strings constitute the argument list for the new process image. The list is terminated by a NULL pointer. The argument arg0 should point to a file name that is associated with the process being started by the _NutForkExec() function.
argv: Contains the argument list for the new process image. This is an array of pointers to character strings and should be terminated by a NULL pointer. The value in argv[0] should point to a file name that is associated with the process being started by the _NutForkExec() function.
envp: Contains the environment for the new process image. This is an array of pointers to character strings and should be terminated by a NULL pointer.

RETURN VALUES

If successful, the _NutForkExec() functions return the process ID of the newly created process. On failure, they returns -1 and set errno to one of the following values:

E2BIG: The number of bytes used by the new process image's argument list and environment list is greater than ARG_MAX bytes.
EACCES: Search permission is denied for a directory listed in the new process image file's path prefix, or the new process image file denies execution permission, or the new process image file is not a regular file.
ENAMETOOLONG: The length of path or file (or an element of $PATH prefixed to file) exceeds PATH_MAX, or a path name component is longer than NAME_MAX.
ENOENT: A component of path or file does not name an existing file, or path or file is an empty string.
ENOEXEC: The new process image file has the appropriate access permissions, but is not in the proper format.
ENOMEM: The new process image requires more memory than is allowed by the hardware or system-imposed memory management constraints.
ENOTDIR: A component of the new process image file's path prefix is not a directory.

CONFORMANCE

PTC MKS Toolkit UNIX APIs extensions.

MULTITHREAD SAFETY LEVEL

_NutForkExecl(), _NutForkExeclp(), _NutForkExeclpe(): MT-Safe, with exceptions.

_NutForkExecv(), _NutForkExecvp(), _NutForkExecvpe(): MT-Safe, with exceptions.

_NutForkExecle(), _NutForkExecve(): Async-signal-safe.

Except for _NutForkExecle() and _NutForkExecve(), these functions are MT-Safe as long as the environment is not being modified. If the environment is being modified when these functions are called, behavior is unspecified. _NutForkExecle() and _NutForkExecve() are Async-signal-safe.

PORTING ISSUES

The _NutForkExec() family of functions provides the most efficient mechanism to create a new process. Refer to Process Management in the Windows Concepts chapter of the PTC MKS Toolkit UNIX to Windows Porting Guide for a detailed discussion of the process model.

You must ensure that any path name arguments you pass to non-NuTCRACKER Platform applications are in Win32 format, as only NuTCRACKER Platform applications recognize the NuTCRACKER Platform format. Refer to Path Names in the Windows Concepts chapter of 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

_NutForkExecl(), _NutForkExecle(), _NutForkExeclp(), _NutForkExeclpe(), _NutForkExecv(), _NutForkExecve(), _NutForkExecvp(), _NutForkExecvpe()
combination of fork() and exec() functions

Function