Name
spawnl, spawnle, spawnlp, spawnlpe, spawnv, spawnve,
spawnvp, spawnvpe - Create and execute a child process.
Syntax
#include <stdio.h>
#include <process.h>
int spawnl(modeflag, pathname, arg0, arg1..., argn,NULL)
int spawnle(modeflag, pathname, arg0, arg1..., argn,NULL,
envp)
int spawnlp(modeflag, pathname, arg0, arg1..., argn,NULL)
int spawnlpe(modeflag, pathname, arg0, arg1..., argn, NULL,
envp)
int spawnv(modeflag, pathname, argv)
int spawnve(modeflag, pathname, argv, envp)
int spawnvp(modeflag, pathname, argv)
int spawnvpe(modeflag, pathname, argv, envp)
int modeflag;
char *pathname;
char *arg0,*arg1,...,*argn;
char *argv[ ];
char *envp[ ];
Description
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 modeflag argument
determines the action taken by the parent process before and
during spawn.
The following values for modeflag are defined in process.h.
Value Meaning
P_WAIT Suspends parent process until
execution of child process is
complete (synchronous spawn)
P_NOWAIT Continues to execute parent process
concurrently with child process
(asynchronous spawn, valid only in
protected mode)
P_NOWAITO Continues to execute parent process
and ignores wait and cwait calls
against child process (asynchronous
spawn, valid only in protected
mode)
P_OVERLAY Overlays parent process with child,
destroying the parent (same effect
as exec calls)
Notes
The spawn functions, with a modeflag of P_OVERLAY, will not
work in OS/2 DOS-compatibility mode in programs which are
bound with FAPI for dual-mode execution.
Programs linked as DOS mode .EXE files will work, and
protected-mode programs will work. The restriction applies
only to bound programs in real mode.
In order to ensure proper overlay initialization and
termination, do not use the setjmp or longjmp functions to
enter or leave an overlay routine.
The pathname argument specifies the file which will be
executed 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 does not end with a period
(.), the command interpreter searches for the file; if
unsuccessful, the extension .COM is attempted first,
followed by .EXE. If pathname has an extension, only that
extension is used. If pathname ends with a period, the spawn
calls search for pathname with no extension. The spawnlp,
spawnlpe, spawnvp, and spawnvpe routines search for pathname
(using the same procedures) in the directories specified by
the PATH environment variable.
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
pathname. 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 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.
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 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 (_C_FILE_INFO in protected mode). The C start-up
code normally processes this entry and then deletes it from
the environment. However, if a spawn function spawns a non-C
process (such as CMD.EXE), 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.
Return Value
The return value from a synchronous spawn (P_WAIT specified
for modeflag) is the exit status of the child process.
The return value from an asynchronous spawn (P_NOWAIT or
P_NOWAITO specified for modeflag) is the process ID. To
obtain the exit code for a process spawned with P_NOWAIT,
you must call the wait or cwait function and specify the
process ID. The exit code cannot be obtained for a process
spawned with P_NOWAITO.
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:
Value Meaning
E2BIG In DOS, the argument list exceeds 128
bytes, or the space required for the
environment information exceeds 32K.
In OS/2, the argument list and the
space required for environment
information combined exceed 32K.
EINVAL The modeflag argument is invalid.
ENOENT The file or path name is not found.
ENOEXEC The specified file is not executable
or has an invalid executable-file
format.
ENOMEM Not enough memory is available to
execute the child process.
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.
See Also
abort(DOS), atexit(DOS), exec(DOS), exit(DOS), _exit(DOS),
system(DOS)
Example
#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
};
main (argc, argv) 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;
/* Based on first letter of argument: */
switch (argv[1][0])
{
case '1':
spawnl(P_WAIT, "child.exe","child ",
"spawnl","two",NULL);
break;
case '2':
spawnle (P_WAIT, "child.exe","child",
"spawnle","two",NULL,my_env);
break;
case '3':
spawnlp (P_WAIT, "child.exe","child",
"spawnlp","two",NULL);
break;
case '4':
spawnlpe (P_WAIT, "child.exe","child",
"spawnlpe","two",NULL, my_env);
break;
Page 6 (printed 6/18/89)
SPAWN(DOS) UNIX System V SPAWN(DOS)
case '5':
spawnv (P_OVERLAY, "child.exe",args);
break;
case '6':
spawnve (P_OVERLAY,
"child.exe",args,my_env);
break;
case '7':
spawnvp (P_OVERLAY, "child.exe",args);
break;
case '8':
spawnvpe(P_OVERLAY,
"child.exe",args,my_env);
break;
default:
printf("Enter a number from 1 to 8 ");
printf("as a command line parameter.\n");
exit();
}
printf("\n\nReturned from SPAWN!\n");
}
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.
Page 7 (printed 6/18/89)