_spawnl - _spawnvpe -- Start and Run Child Processes

Format

#include <process.h>
int _spawnl(int modeflag, char *pathname, char *arg0, char *arg1, ...,
              char *argn, NULL);
int _spawnlp(int modeflag, char *pathname, char *arg0, char *arg1, ...,
              char *argn, NULL);
int _spawnle(int modeflag, char *pathname, char *arg0, char *arg1, ...,
              char *argn, NULL, char *envp[ ]);
int _spawnlpe(int modeflag, char *pathname, char *arg0, char *arg1, ...,
              char *argn, NULL, char *envp[ ]);
int _spawnv(int modeflag, char *pathname, char *argv[ ]);
int _spawnvp(int modeflag, char *pathname, char *argv[ ]);
int _spawnve(int modeflag, char *pathname, char *argv[ ], char *envp[ ]);
int _spawnvpe(int modeflag, char *pathname, char *argv[ ], char *envp[ ])

Language Level: Extension
Each of the _spawn functions creates and runs a new child process. Enough storage must be available for loading and running the child process. All of the _spawn functions are versions of the same routine; the letters at the end determine the specific variation:

Letter Variation
p Uses PATH environment variable to find the file to be run
l Lists command-line arguments separately
v Passes to the child process an array of pointers to command-line arguments
e Passes to the child process an array of pointers to environment strings.

The modeflag argument determines the action taken by the parent process before and during the _spawn. The values for modeflag are defined in <process.h>:

Value Meaning
P_WAIT Suspend the parent process until the child process is complete.
P_NOWAIT Continue to run the parent process concurrently.
P_OVERLAY Start the child process, and then, if successful, end the parent process. (This has the same effect as exec calls.)

The pathname argument specifies the file to run as the child process. The pathname can specify a full path (from the root), a partial path (from the current working directory), or just a file name. If pathname does not have a file-name extension or end with a period, the _spawn functions add the extension .EXE and search for the file. If pathname has an extension, only that extension is used. If pathname ends with a period, the _spawn functions search for pathname with no extension. The _spawnlp, _spawnlpe, _spawnvp, and _spawnvpe functions search for pathname (using the same procedures) in the directories specified by the PATH environment variable.

You pass arguments to the child process by giving one or more pointers to character strings as arguments in the _spawn routine. These character strings form the argument list for the child process.

The argument pointers can be passed as separate arguments (_spawnl, _spawnle, _spawnlp, and _spawnlpe) or as an array of pointers (_spawnv, _spawnve, _spawnvp, and _spawnvpe). At least one argument, either arg0 or argv[0], must be passed to the child process. By convention, this argument is a copy of the pathname argument. However, a different value will not produce an error.

Use the _spawnl, _spawnle, _spawnlp, and _spawnlpe functions where you know the number of arguments. The arg0 is usually a pointer to pathname. The arg1 through argn arguments are pointers to the character strings forming the new argument list. Following argn, a NULL pointer must mark the end of the argument list.

The _spawnv, _spawnve, _spawnvp, and _spawnvpe functions are useful when the number of arguments to the child process is variable. Pointers to the arguments are passed as an array, argv. The argv[0] argument is usually a pointer to the pathname. The argv[1] through argv[n] arguments are pointers to the character strings forming the new argument list. The argv[n+1] argument must be a NULL pointer to mark the end of the argument list.

Files that are open when a _spawn call is made remain open in the child process. In the _spawnl, _spawnlp, _spawnv, and _spawnvp calls, the child process inherits the environment of the parent. The _spawnle, _spawnlpe, _spawnve, and _spawnvpe functions let you alter the environment for the child process by passing a list of environment settings through the envp argument. The envp argument is an array of character pointers, each element of which points to a null-terminated string, that defines an environment variable. Such a string has the form:

NAME=value

where NAME is the name of an environment variable, and value is the string value to which that variable is set. (Notice that value is not enclosed in double quotation marks.) The final element of the envp array should be NULL. When envp itself is NULL, the child process inherits the environment settings of the parent process.

Note: Signal settings are not preserved in child processes created by calls to _spawn functions. The signal settings are reset to the default in the child process.

Return Value
The return from a spawn function has one of two different meanings. The return value of a synchronous spawn is the exit status of the child process. The return value of an asynchronous spawn is the process identification of the child process. You can use wait or _cwait to get the child process exit code if an asynchronous spawn was done.

A return value of -1 indicates an error (the child process is not started), and errno is set to one of the following values:

Value Meaning
EAGAIN The limit of the number of processes that the operating system permits has been reached.
EINVAL The modeflag argument is incorrect.
ENOENT The file or path name was not found or was not specified correctly.
ENOEXEC The specified file is not executable or has an incorrect executable file format.
ENOMEM Not enough storage is available to run the child process.

Example


_cwait -- Wait for Child Process
execl - _execvpe -- Load and Run Child Process
exit -- End Program
_exit -- End Program
wait -- Wait for Child Process
<process.h>