SPAWNL(DOS) XENIX System V SPAWNL(DOS)
Name
spawnl, spawnvp - Creates a new 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 spawnv (modeflag, pathname, argv);
int spawnve (modeflag, pathname, argv, envp);
int spawnvp (modeflag, pathname, argv);
int modeflag;
char *pathname;
char *arg0,*arg1...*argn;
char *argv [ ];
char *envp [ ];
Description
The spawn functions create and execute a new child process.
There must be enough memory available for loading and
executing the child process. The modeflag argument
determines the action taken by the parent process before and
during the spawn. The following values for modeflag are
defined in process.h:
Value Meaning
P_WAIT Suspend parent process until
execution of child process is
complete
P_NOWAIT Continue to execute parent process
concurrently with child process
P_OVERLAY Overlay parent process with child,
destroying the parent (same effect
as exec calls)
Only the P_WAIT and P_OVERLAY modeflag values may currently
be used. The P_NOWAIT value is reserved for possible future
implementation. An error value is returned if P_NOWAIT is
used.
The pathname argument specifies the file to be executed as
Page 1 (printed 8/7/87)
SPAWNL(DOS) XENIX System V SPAWNL(DOS)
the child process. The pathname can specify a full path
(from the root), a partial path (from the current working
directory), or just a filename. If pathname does not have a
filename extension or end with a period (.), the spawn calls
first append the extension .COM and search for the file; if
unsuccessful, the extension .EXE is attempted. 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 and spawnvp 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. 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, and spawnlp) or as an array of pointers
(spawnv, spawnve, and spawnvp). At least one argument, arg0
or argv[0], must be passed to the child process. By
convention, this argument is a copy of the pathname
argument. (A different value will not produce an error.)
Under versions of MS-DOS earlier than 3.0, the passed value
of arg0 or arg[0] is not available for use in the child
process. However, under MS-DOS 3.0 and later, the pathname
is available as arg0 or arg[0].
The spawnl, spawnle and spawnlp calls are typically used in
cases where the number of arguments is known in advance.
arg0 is usually a pointer to pathname. 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.
spawnv, spawnve, and spawnvp are useful when the number of
arguments to the child process is variable. Pointers to the
arguments are passed as an array, argv. argv[0] is usually
a pointer to the pathname. argv[1] through argv[n] are
pointers to the character strings forming the new argument
list. 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. spawnle and spawnve allow the user to alter the
Page 2 (printed 8/7/87)
SPAWNL(DOS) XENIX System V SPAWNL(DOS)
environment for the child process by passing a list of
environment settings through the envp argument. envp is an
array of character pointers, each element of which points to
a null-terminated string defining 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 quotes.) When envp is NULL, the child
process inherits the environment settings of the parent
process.
Return Value
The return value is the exit status of the child process.
The exit status is 0 if the process terminated normally.
The exit status can also be set to a nonzero value if the
child process specifically calls the exit routine with a
nonzero argument. If not set, a positive exit status
indicates an abnormal exit via an abort or an interrupt.
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
E2BIG The argument list exceeds 128 bytes
or the space required for the
environment information exceeds 32K
bytes.
EINVAL Invalid modeflag argument.
ENOENT File or pathname 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.
See Also
abort(S), exec(S), exit(DOS)
Page 3 (printed 8/7/87)
SPAWNL(DOS) XENIX System V SPAWNL(DOS)
Example
#include <stdio.h> #include <process.h>
extern char **environ;
char *args[4]; int result;
args[0] = "child"; args[1] = "one"; args[2] = "two"; args[3]
= NULL; . . . /* All of the
following statements attempt to spawn a ** process called
"child.exe" and pass it 3 arguments. ** The first 3 suspend
the parent, and the last 3 ** overlay the parent with the
child. */
result = spawnl (P_WAIT,"child.exe","child","one","two",
NULL); result = spawnle
(P_WAIT,"child.exe","child","one",
"two",NULL,environ); result = spawnlp
(P_WAIT,"child.exe","child","one", "two",NULL);
result = spawnv (P_OVERLAY,"child.exe",args); result =
spawnve (P_OVERLAY,"child.exe",args,environ); result =
spawnvp (P_OVERLAY,"child.exe",args);
Notes
The spawn calls do not preserve the translation modes of
open files. If the child process must use files inherited
from the parent, the setmode routine should be used to set
the translation mode of these files to the desired mode.
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.
These calls must be compiled with the -dos flag.
Page 4 (printed 8/7/87)