-S flag fixes for DOSISH platforms

This patch supercedes the one posted here by Ilya
(Message-Id: <199707191651.MAA04897@monk.mps.ohio-state.edu>).

There are no changes for Unix platforms over Ilya's
version.  On DOSISH platforms, the initial check in
the current directory (or the actual path to the script,
if supplied) includes searching for valid extensions.

The fact that -S does not do a PATH search if the supplied
filename contains directory separators (on all platforms) is
documented.  This behavior is similar to Unix and DOS shells.

Note -S *does* have an effect on DOSISH platforms even if no
PATH search happens: valid extensions will be checked for if
the file name is not found.

p5p-msgid: 199707250043.UAA02385@aatma.engin.umich.edu

2 files changed, 33 insertions, 4 deletions

diff --git a/pod/perldiag.pod b/pod/perldiag.pod
index ab40fd122d..409aa21ec0 100644
--- a/pod/perldiag.pod
+++ b/pod/perldiag.pod
@@ -549,8 +549,19 @@ mention "perl" on the #! line somewhere.
 
 =item Can't execute %s
 
+(F) You used the B<-S> switch, but the copies of the script to execute found
+in the PATH did not have correct permissions.
+
+=item Can't find %s on PATH, '.' not in PATH
+
+(F) You used the B<-S> switch, but the script to execute could not be found
+in the PATH, or at least not with the correct permissions.  The script
+exists in the current directory, but PATH prohibits running it.
+
+=item Can't find %s on PATH
+
 (F) You used the B<-S> switch, but the script to execute could not be found
-in the PATH, or at least not with the correct permissions.
+in the PATH.
 
 =item Can't find label %s
 
diff --git a/pod/perlrun.pod b/pod/perlrun.pod
index 61e40f88a0..19aa0a2a9e 100644
--- a/pod/perlrun.pod
+++ b/pod/perlrun.pod
@@ -431,9 +431,27 @@ prints "true" if and only if the script is invoked with a B<-xyz> switch.
 =item B<-S>
 
 makes Perl use the PATH environment variable to search for the
-script (unless the name of the script starts with a slash).  Typically
-this is used to emulate #! startup on machines that don't support #!,
-in the following manner:
+script (unless the name of the script contains directory separators).
+On some platforms, this also makes Perl append suffixes to the
+filename while searching for it.  For example, on Win32 platforms,
+the ".bat" and ".cmd" suffixes are appended if a lookup for the
+original name fails, and if the name does not already end in one
+of those suffixes.  If your Perl was compiled with DEBUGGING turned
+on, using the -Dp switch to Perl shows how the search progresses.
+
+If the file supplied contains directory separators (i.e. it is an
+absolute or relative pathname), and if the file is not found,
+platforms that append file extensions will do so and try to look
+for the file with those extensions added, one by one.
+
+On DOS-like platforms, if the script does not contain directory
+separators, it will first be searched for in the current directory
+before being searched for on the PATH.  On Unix platforms, the
+script will be searched for strictly on the PATH.
+
+Typically this is used to emulate #! startup on platforms that
+don't support #!.  This example works on many platforms that
+have a shell compatible with Bourne shell:
 
     #!/usr/bin/perl
     eval 'exec /usr/bin/perl -S $0 ${1+"$@"}'