Click above to get retro games delivered to your door ever month!

spawn*
======

Syntax
------

     #include <process.h>
     
     int spawnl(int mode, const char *path, const char *argv0, ...);
     int spawnle(int mode, const char *path, const char *argv0, ... /*, const char **envp */);
     int spawnlp(int mode, const char *path, const char *argv0, ...);
     int spawnlpe(int mode, const char *path, const char *argv0, ... /*, const char **envp */);
     
     int spawnv(int mode, const char *path, const char **argv);
     int spawnve(int mode, const char *path, const char **argv, const char **envp);
     int spawnvp(int mode, const char *path, const char **argv);
     int spawnvpe(int mode, const char *path, const char **argv, const char **envp);

Description
-----------

These functions run other programs.  The PATH points to the program to
run.  The extension is optional--if not given, and PATH is not found
neither in the current directly nor along the `PATH', the extensions
`.com', `.exe', `.bat', `.btm', `.sh', and `.ksh' are checked.  `.com'
programs are invoked via the usual DOS calls; DJGPP `.exe' programs are
invoked in a way that allows long command lines to be passed; other
`.exe' programs are invoked via DOS; `.bat' and `.btm' programs are
invoked via the command processor given by the `COMSPEC' environment
variable; `.sh', `.ksh' programs and programs with any other extensions
that have `#!' as their first two caharacters are assumed to be
Unix-style scripts and are invoked by calling a program whose pathname
immediately follows the first two characters.  (If the name of that
program is a Unix-style pathname, without a drive letter and without an
extension, like `/bin/sh', the `spawn' functions will additionally look
them up on the `PATH'; this allows to run Unix scripts without editing,
if you have a shell installed somewhere along your `PATH'.)

Note that built-in commands of the shells can *not* be invoked via
these functions; use `system' instead.

The programs are invoked with the arguments given.  The zeroth argument
is normally not used, since MS-DOS cannot pass it separately.  There are
two ways of passing arguments.  The `l' functions (like `spawnl') take
a list of arguments, with a zero at the end of the list.  This is
useful when you know how many argument there will be ahead of time.
The `v' functions (like `spawnv') take a pointer to a list of
arguments.  This is useful when you need to compute the number of
arguments at runtime.

In either case, you may also specify `e' to indicate that you will be
giving an explicit environment, else the current environment is used.
You may also specify `p' to indicate that you would like `spawn*' to
search the PATH (in either the environment you pass or the current
environment) for the executable, else it will only check the explicit
path given.

Note that these function understand about other DJGPP programs, and will
call them directly, so that you can pass command lines longer than 126
characters to them without any special code.  DJGPP programs called by
these functions will *not* glob the arguments passed to them; other
programs also won't glob the arguments if they suppress expansion when
given quoted filenames.

exec*:.   

Return Value
------------

If successful and `mode' is `P_WAIT', these functions return the exit
code of the child process in the lower 8 bits of the return value.
Note that if the program is run by a command processor (e.g., if it's a
batch file), the exit code of that command processor will be returned.
`COMMAND.COM' is notorious for returning 0 even if it couldn't run the
command.

If successful and MODE is `P_OVERLAY', these functions will not return.

If there is an error (e.g., the program specified as `argv[0]' cannot
be run, or the command line is too long), these functions return -1 and
set `errno' to indicate the error.  If the child program was
interrupted by <Ctrl-C> or a Critical Device error, `errno' is set to
`EINTR' (even if the child's exit code is 0), and bits 8-17 of the
return value are set to `SIGINT' or `SIGABRT', accordingly.  Note that
you must set the signal handler for `SIGINT' to `SIG_IGN', or arrange
for the handler to return, or else your program will be aborted before
it will get chance to set the value of the return code.

Example
-------


     char *environ[] = {
       "PATH=c:\\dos;c:\\djgpp;c:\\usr\\local\\bin",
       "DJGPP=c:/djgpp",
       0
     };
     
     char *args[] = {
       "gcc",
       "-v",
       "hello.c",
       0
     };
     
     spawnvpe(P_WAIT, "gcc", args, environ);