Header File 

process.h  

Category 

Process Control Routines 

Prototype 

int spawnl(int mode, char *path, char *arg0, arg1, ..., argn, NULL); 

int _wspawnl(int mode, wchar_t *path, wchar_t *arg0, arg1, ..., argn, NULL); 

int spawnle(int mode, char *path, char *arg0, arg1, ..., argn, NULL, char *envp[]); 

int _wspawnle(int mode, wchar_t *path, wchar_t *arg0, arg1, ..., argn, NULL, wchar_t *envp[]); 

int spawnlp(int mode, char *path, char *arg0, arg1, ..., argn, NULL); 

int _wspawnlp(int mode, wchar_t *path, wchar_t *arg0, arg1, ..., argn, NULL); 

int spawnlpe(int mode, char *path, char *arg0, arg1, ..., argn, NULL, char *envp[]); 

int _wspawnlpe(int mode, wchar_t *path, wchar_t *arg0, arg1, ..., argn, NULL, wchar_t *envp[]); 

int spawnv(int mode, char *path, char *argv[]); 

int _wspawnv(int mode, wchar_t *path, wchar_t *argv[]); 

int spawnve(int mode, char *path, char *argv[], char *envp[]); 

int _wspawnve(int mode, wchar_t *path, wchar_t *argv[], wchar_t *envp[]); 

int spawnvp(int mode, char *path, char *argv[]); 

int _wspawnvp(int mode, wchar_t *path, wchar_t *argv[]); 

int spawnvpe(int mode, char *path, char *argv[], char *envp[]); 

int _wspawnvpe(int mode, wchar_t *path, wchar_t *argv[], wchar_t *envp[]);

The functions in the spawn... family create and run (execute) other files, known as child processes. There must be sufficient memory available for loading and executing a child process. 

The value of mode determines what action the calling function (the parent process) takes after the spawn... call. The possible values of mode are

path is the file name of the called child process. The spawn... function calls search for path using the standard operating system search algorithm:

• If there is no extension or no period, they search for an exact file name. If the file is not found, they search for files first with the extension EXE, then COM, and finally BAT.
• If an extension is given, they search only for the exact file name.
• If only a period is given, they search only for the file name with no extension.
• If path does not contain an explicit directory, spawn... functions that have the p suffix search the current directory, then the directories set with the operating system PATH environment variable.

Each function in the spawn... family must have one of the two argument-specifying suffixes (either l or v). The path search and environment inheritance suffixes (p and e) are optional. 

For example:

• spawnl takes separate arguments, searches only the current directory for the child, and passes on the parent's environment to the child.
• spawnvpe takes an array of argument pointers, incorporates PATH in its search for the child process, and accepts the envp argument for altering the child's environment.

When the l suffix is used, arg0 usually points to path, and arg1, ...., argn point to character strings that form the new list of arguments. A mandatory null following argn marks the end of the list. 

When the e suffix is used, you pass a list of new environment settings through the argument envp. This environment argument is an array of character pointers. Each element points to a null-terminated character string of the form 

envvar = value 

where envvar is the name of an environment variable, and value is the string value to which envvar is set. The last element in envp[] is null. When envp is null, the child inherits the parents' environment settings. 

The combined length of arg0 + arg1 + ... + argn (or of argv[0] + argv[1] + ... + argv[n]), including space characters that separate the arguments, must be less than 260 bytes for Windows (128 for DOS). Null-terminators are not counted. 

When a spawn... function call is made, any open files remain open in the child process. 

Return Value 

When successful, the spawn... functions, where mode is P_WAIT, return the child process' exit status (0 for a normal termination). If the child specifically calls exit with a nonzero argument, its exit status can be set to a nonzero value. 

If mode is P_NOWAIT or P_NOWAITO, the spawn functions return the process ID of the child process. The ID obtained when using P_NOWAIT can be passed to cwait. 

On error, the spawn... functions return -1, and the global variable errno is set to one of the following values:

Example

#include <process.h>
#include <stdio.h>
void spawnl_example(void)
{
   int result;
   result = spawnl(P_WAIT, "bcc32.exe", "bcc32.exe", NULL);
   if (result == -1)
   {
      perror("Error from spawnl");
      exit(1);
   }
}
int main(void)
{
  spawnl_example();
  return 0;
}