Date:	Tue, 25 Nov 1997 19:02:56 +0200 (IST)
From:	Eli Zaretskii <eliz AT is DOT elta DOT co DOT il>
To:	DJ Delorie <dj AT delorie DOT com>
cc:	djgpp-workers AT delorie DOT com
Subject:	Docs changes for dosexec
Message-ID:	<Pine.SUN.3.91.971125190015.29142D-100000@is>
MIME-Version:	1.0

These changes describe the new behavior (see my other mail about 
dosexec.c) and also warn about problems when the file is not a DOS or 
DJGPP executable (e.g., a text file), as Nate asked a long time ago.

*** src/libc/dos/process/dosexec.t~0	Mon Sep  9 00:55:00 1996
--- src/libc/dos/process/dosexec.txh	Sat Nov 22 19:19:32 1997
***************
*** 18,43 ****
  @subheading Description
  
  These functions run other programs.  The @var{path} points to the
! program to run.  The extension is optional---if not given, and
! @var{path} is not found neither in the current directly nor along the
! @samp{PATH}, the extensions @file{.com}, @file{.exe}, @file{.bat},
! @file{.btm}, @file{.sh}, and @file{.ksh} are checked.  @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 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
  @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}.)
  
  Note that built-in commands of the shells can @emph{not} be invoked via
! these functions; use @code{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
--- 18,58 ----
  @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}, @file{.btm}, @file{.sh},
! @file{.ksh}, @file{.pl} and @file{.sed}; if none is found, neither in
! the current directly 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.  There are
***************
*** 51,59 ****
  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 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
--- 66,74 ----
  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

- Raw text -