_spawn Functions

Description

Create and execute a new child process for DOS.

#include <stdio.h>

#include <process.h>

int _spawnl( int mode, char *cmdname, char *arg0, char *arg1, ... char *argn, NULL );

int _spawnle( int mode, char *cmdname, char *arg0, char *arg1, ... char *argn, NULL, char **envp);

int _spawnlp( int mode, char *cmdname, char *arg0, char *arg1, ... char *argn, NULL );

int _spawnlpe( int mode, char *cmdname, char *arg0,
char *arg1, ... char *argn, NULL, char **envp);

int _spawnv( int mode, char *cmdname, char **argv);

int _spawnve( int mode, char *cmdname, char **argv, char **envp);

int _spawnvp( int mode, char *cmdname, char **argv);

int _spawnvpe( int mode, char *cmdname, char **argv, char **envp);

Remarks

The _spawn family of functions creates and executes a new child process. Enough memory must be available for loading and executing the child process. The mode argument determines the action taken by the parent process before and during _spawn. The following values for mode are defined in PROCESS.H:

The cmdname argument specifies the file which will be executed as the child process, and can specify a full path (from the root), a partial path (from the current working directory), or just a filename. If cmdname does not have a filename extension or does not end with a period (.), the _spawn function first tries the .COM extension, then the .EXE extension, and finally the .BAT extension. This ability to spawn batch files is new beginning with Microsoft C version 6.0.

If cmdname has an extension, only that extension is used. If cmdname ends with a period, the _spawn calls search for cmdname with no extension. The _spawnlp, _spawnlpe, _spawnvp, and _spawnvpe routines search for cmdname (using the same procedures) in the directories specified by the PATH environment variable.

If cmdname contains a drive specifier or any slashes (i.e., if it is a relative path name), the _spawn call searches only for the specified file and no path searching is done.

Arguments for the Child Process

Arguments are passed to the child process by giving one or more pointers to character strings as arguments in the _spawn call. These character strings form the argument list for the child process. The combined length of the strings forming the argument list for the child process must not exceed 128 bytes in real mode. The terminating null character ('\0') for each string is not included in the count, but space characters (automatically inserted to separate arguments) are included.

The argument pointers may 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, arg0 or argv[0], must be passed to the child process. By convention, this argument is the name of the program as it might be typed on the command line by the user. (A different value will not produce an error.) In real mode, the argv[0] value is supplied by the operating system and is the fully qualified path name of the executing program. In protected mode, it is usually the program name as it would be typed on the command line.

The _spawnl, _spawnle, _spawnlp, and _spawnlpe calls are typically used in cases where the number of arguments is known in advance. The arg0 argument is usually a pointer to cmdname. The arguments arg1 through argn are pointers to the character strings forming the new argument list. Following argn, there must be a NULL pointer to mark the end of the argument list.

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

Environment of the Child Process

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 calls allow the user to alter the environment for the child process by passing a list of environment settings through the envp argument. The argument envp is an array of character pointers, each element of which (except for the final element) points to a null-terminated string defining an environment variable. Such a string usually 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. (Note 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.

The _spawn functions can pass the child process all information about open files, including the translation mode, through the C_FILE_INFO entry in the environment that is passed in real mode.

The startup code normally processes this entry and then deletes it from the environment. However, if a _spawn function spawns a non-C process, this entry remains in the environment. Printing the environment shows graphics characters in the definition string for this entry, since the environment information is passed in binary form in real mode. It should not have any other effect on normal operations. In protected mode, the environment information is passed in text form and therefore contains no graphics characters.

You must explicitly flush (using fflush or _flushall) or close any stream prior to the _spawn function call.

Starting with Microsoft C version 6.0, you can control whether or not the open file information of a process will be passed to its child processes. The external variable _fileinfo (declared in STDLIB.H) controls the passing of C_FILE_INFO information. If _fileinfo is 0, the C_FILE_INFO information is not passed to the child processes. If _fileinfo is not 0, C_FILE_INFO is passed to child processes.

By default, _fileinfo is 0 and thus the C_FILE_INFO information is not passed to child processes. There are two ways to modify the default value of _fileinfo:

Link the supplied object file FILEINFO.OBJ into your program. Use the /NOE option to avoid multiple symbol definitions.

Set the _fileinfo variable to a nonzero value directly within your C program.

Return Value

The return value from a synchronous _spawn (_P_WAIT specified for mode) is the exit status of the child process.

The exit status is 0 if the process terminated normally. The exit status can be set to a nonzero value if the child process specifically calls the exit routine with a nonzero argument. If the child process did not explicitly set a positive exit status, a positive exit status indicates an abnormal exit with an abort or an interrupt. A return value of –1 indicates an error (the child process is not started). In this case, errno is set to one of the following values:

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

Compatibility

Standards:None

16-Bit:DOS

32-Bit:DOS32X

To ensure proper overlay initialization and termination, do not use the setjmp or longjmp function to enter or leave an overlay routine.

See Also

abort, atexit, _exec functions, exit, _exit, _onexit, system

Example

/* SPAWN.C: This program accepts a number in the range 1 - 8 from the

* command line. Based on the number it receives, it executes one of the

* eight different procedures that spawn the process named child. For

* some of these procedures, the CHILD.EXE file must be in the

* same directory; for others, it only has to be in the same path.

*/

#include <stdio.h>

#include <process.h>

char *my_env[] =

{

"THIS=environment will be",

"PASSED=to child.exe by the",

"_SPAWNLE=and",

"_SPAWNLPE=and",

"_SPAWNVE=and",

"_SPAWNVPE=functions",

NULL

};

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

{

char *args[4];

int result;

/* Set up parameters to be sent: */

args[0] = "child";

args[1] = "spawn??";

args[2] = "two";

args[3] = NULL;

switch (argv[1][0]) /* Based on first letter of argument */

{

case '1':

_spawnl( _P_WAIT, argv[2], argv[2], "_spawnl", "two", NULL );

break;

case '2':

_spawnle( _P_WAIT, argv[2], argv[2], "_spawnle", "two",

NULL, my_env );

break;

case '3':

_spawnlp( _P_WAIT, argv[2], argv[2], "_spawnlp", "two", NULL );

break;

case '4':

_spawnlpe( _P_WAIT, argv[2], argv[2], "_spawnlpe", "two",

NULL, my_env );

break;

case '5':

_spawnv( _P_OVERLAY, argv[2], args );

break;

case '6':

_spawnve( _P_OVERLAY, argv[2], args, my_env );

break;

case '7':

_spawnvp( _P_OVERLAY, argv[2], args );

break;

case '8':

_spawnvpe( _P_OVERLAY, argv[2], args, my_env );

break;

default:

printf( "SYNTAX: SPAWN <1-8> <childprogram>\n" );

exit( 1 );

}

printf( "\n\nReturned from SPAWN!\n" );

}