@node spawn*, process @findex spawnl @findex spawnle @findex spawnlp @findex spawnlpe @findex spawnv @findex spawnve @findex spawnvp @findex spawnvpe @vindex COMSPEC@r{ environment variable, and }spawn* @vindex PATH@r{ environment variable, and }spawn* @vindex CMDLINE@r{ environment variable, and }spawn* @subheading Syntax @smallexample #include int spawnl(int mode, const char *path, const char *argv0, ..., NULL); int spawnle(int mode, const char *path, const char *argv0, ..., NULL /*, const char **envp */); int spawnlp(int mode, const char *path, const char *argv0, ..., NULL); int spawnlpe(int mode, const char *path, const char *argv0, ..., NULL /*, const char **envp */); int spawnv(int mode, const char *path, char *const argv[]); int spawnve(int mode, const char *path, char *const argv[], char *const envp[]); int spawnvp(int mode, const char *path, char *const argv[]); int spawnvpe(int mode, const char *path, char *const argv[], char *const envp[]); @end smallexample @subheading Description These functions run other programs. The @var{path} points to the program to run, and may optionally include its extension. These functions will look for a file @var{path} with the extensions @file{.com}, @file{.exe}, @file{.bat}, and @file{.btm}; if none are found, neither in the current directory nor along the @samp{PATH}, they will look for @var{path} itself. @file{.com} programs are invoked via the usual DOS calls; DJGPP @file{.exe} programs are invoked in a way that allows long command lines to be passed; other @file{.exe} programs are invoked via DOS; @file{.bat} and @file{.btm} programs are invoked via the command processor given by the @samp{COMSPEC} environment variable; @file{.sh}, @file{.ksh} programs and programs with any other extensions that have @code{#!} as their first two characters 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 @samp{/bin/sh}, the @code{spawn} functions will additionally look them up on the @samp{PATH}; this allows to run Unix scripts without editing, if you have a shell installed somewhere along your @samp{PATH}.) Any non-recognizable files will be also invoked via DOS calls. @strong{WARNING!} DOS is rather stupid in invoking programs: if the file doesn't have the telltale ``MZ'' signature of the @file{.exe} style programs, DOS assumes it is a @file{.com} style image and tries to execute it directly. If the file is not really an executable program, your application will almost certainly crash. Applications that need to be robust in such situations should test whether the program file is indeed an executable, e.g. with calls to @code{stat} (@pxref{stat}) or @code{_is_executable} (@pxref{_is_executable}) library functions. Note that built-in commands of the shells can @emph{not} be invoked via these functions; use @code{system} instead, or invoke the appropriate shell with the built-in command as its argument. The programs are invoked with the arguments given. The zeroth argument is normally not used, since MS-DOS cannot pass it separately, but for compatibility it should be the name of the program. There are two ways of passing arguments. The @code{l} functions (like @code{spawnl}) take a list of arguments, with a @code{NULL} at the end of the list. This is useful when you know how many argument there will be ahead of time. The @code{v} functions (like @code{spawnv}) take a pointer to a list of arguments, which also must be @code{NULL}-terminated. This is useful when you need to compute the number of arguments at runtime. In either case, you may also specify @code{e} to indicate that you will be giving an explicit environment, else the current environment is used. You may also specify @code{p} to indicate that you would like @code{spawn*} to search the @code{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 @emph{not} glob the arguments passed to them; other programs also won't glob the arguments if they suppress expansion when given quoted filenames. When the calling program runs on Windows 9X or Windows 2000 and calls the system shell to run the child program, or if the child program is a native Windows program (in @code{PE-COFF} format), or when the system shell is @file{4DOS} or @file{NDOS} and the shell is called to run the command, command lines longer than 126 characters are passed via the environment variable @code{CMDLINE}. @xref{exec*}. @subheading Return Value If successful and @code{mode} is @code{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. @file{COMMAND.COM} is notorious for returning 0 even if it couldn't run the command. If successful and @var{mode} is @code{P_OVERLAY}, these functions will not return. If there is an error (e.g., the program specified as @code{argv[0]} cannot be run, or the command line is too long), these functions return -1 and set @code{errno} to indicate the error. If the child program was interrupted by @key{Ctrl-C} or a Critical Device error, @code{errno} is set to @code{EINTR} (even if the child's exit code is 0), and bits 8-17 of the return value are set to @code{SIGINT} or @code{SIGABRT}, accordingly. Note that you must set the signal handler for @code{SIGINT} to @code{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. @subheading Portability @portability !ansi, !posix @subheading Example @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); @end example @c ----------------------------------------------------------------------- @node __djgpp_spawn, process @findex __djgpp_spawn @subheading Syntax @example #include int __djgpp_spawn(int mode, const char *path, char *const argv[], char *const envp[], unsigned long flags); @end example @subheading Description This function runs other programs like @code{spawnve} (@pxref{spawn*}) except that an additional parameter @var{flags} is passed. @var{flags} can include the following flags to control the details of finding the program to run: @table @code @item SPAWN_EXTENSION_SRCH If an extension is not included in @var{path}, search for a file @var{path} with the extensions @file{.com}, @file{.exe}, @file{.bat}, and @file{.btm}. @item SPAWN_NO_EXTENSION_SRCH Do not perform an extension search. If the file has an extension, it must already be included in @var{path}. @end table @subheading Return Value @xref{spawn*}. @subheading Portability @portability !ansi, !posix @subheading Example @example char *args[] = @{ "gcc.exe", "-v", "hello.c", 0 @}; __djgpp_spawn(P_WAIT, "/dev/env/DJDIR/bin/gcc.exe", args, NULL, SPAWN_NO_EXTENSION_SRCH); @end example @c ----------------------------------------------------------------------- @node __dosexec_find_on_path, process @findex __dosexec_find_on_path @subheading Syntax @example #include #include char *__dosexec_find_on_path(const char *program, char *envp[], char *buf); @end example @subheading Description This function searches for a program using a given path. The program is searched for using a known set of executable extensions, e.g. @file{.exe}. These executable extensions are described for the @code{spawn*()} function (@pxref{spawn*}). Pass the program name in @var{program}, the environment array in @var{envp} and the output buffer in @var{buf}. @var{envp} is an array of pointers to the environment variables; it must be terminated with a @code{NULL} pointer. @var{buf} must be large enough to hold at least @samp{FILENAME_MAX} bytes. @var{envp} controls where @code{__dosexec_find_on_path} looks for the program. If @var{envp} is @code{NULL}, then only the current directory is searched. If @var{envp} contains the @samp{PATH} environment variable whose value lists several directories, then these directories are also searched. The global variable @code{environ} is usually passed for @var{envp}. @subheading Return Value If the function finds the program, with or without one of the known executable extensions, either in the current directory or along the @samp{PATH} as recorded in @var{envp}, it puts the full pathname into @var{buf} and returns a pointer to @var{buf}. Otherwise, it returns @code{NULL}. @subheading Portability @portability !ansi, !posix @subheading Example @smallexample char shellpath[FILENAME_MAX]; extern char * __dosexec_find_on_path (const char *, char *[], char *); extern char **environ; /* See if we can find "/bin/sh.exe", "/bin/sh.com", etc. */ if (__dosexec_find_on_path ("/bin/sh", (char **)0, shellpath) /* If not found, look for "sh" along the PATH. */ || __dosexec_find_on_path ("sh", environ, shellpath)) printf ("/bin/sh found as `%s'\n", shellpath); @end smallexample