[inseparable changes from patch to perl 5.004_04]perl-5.004_04

[editor's note: this one imported like a charm!]

 TESTS  -

Subject: Improve pragma/locale test 102 - and don't fail, just warn
From: Jarkko Hietaniemi <jhi@anna.in-berlin.de>
Files: t/pragma/locale.t

Subject: Invalid test output in t/op/taint.t in trial 1
From: Dan Sugalski <sugalsd@lbcc.cc.or.us>
Files: t/op/taint.t

    t/op/taint.t prints out invalid ok messages for tests it skips.
    Rather than printing "ok 136" it prints "136 ok".
    
    p5p-msgid: 3.0.3.32.19970919160918.00857a50@stargate.lbcc.cc.or.us

 UTILITIES  -

Subject: Perldoc tiny patch to avoid $0
From: Ilya Zakharevich <ilya@math.ohio-state.edu>
Files: utils/perldoc.PL
Msg-ID: 199709122141.RAA16846@monk.mps.ohio-state.edu

    (applied based on p5p patch as commit 0b166b6635cf199f072db516b2a523ee659394d5)

Subject: h2ph broken in 5.004_02
From: David Mazieres <dm@reeducation-labor.lcs.mit.edu>
Files: utils/h2ph.PL
Msg-ID: 199708201700.KAA02621@www.chapin.edu

    (applied based on p5p patch as commit 4a8e146e38ec2045f1f817a7cb578e1b1f80f39f)

Subject: add key_t caddr_t to h2ph
From: Tony Sanders <sanders@bsdi.com>
Files: eg/sysvipc/ipcsem utils/h2ph.PL
Msg-ID: 199708272301.RAA12803@austin.bsdi.com

    (applied based on p5p patch as commit 0806a92ffc3a74ca70aa81051cdf2a306cd0a8af)

Subject: perldoc search ., lib and blib/* if -f 'Makefile.PL'
From: Tim Bunce <Tim.Bunce@ig.co.uk>
Files: utils/perldoc.PL

    Subject: perldoc finds wrong pod2man
    
    (from perldoc source)
    
        # We must look both in @INC for library modules and in PATH
        # for executables, like h2xs or perldoc itself.
    
    Unfortunately, searching PATH for installed perl executables like
    pod2man is INCORRECT.  perldoc should start by searching the
    directory it was executed from, which might not be in the PATH
    at all.
    
    Credited: Joseph "Moof-in'" Hall <joseph@cscaper.com>
    
    p5p-msgid: 199708251732.KAA19299@gadget.cscaper.com

Subject: 5.004m4t1: perlbug: NIS domainname gets into wrong places
From: Andreas J. Koenig <koenig@anna.mind.de>
Files: utils/perlbug.PL
Msg-ID: sfcg1qy38as.fsf@anna.in-berlin.de

    (applied based on p5p patch as commit 41f926b844140b7f7eaa9302113e45df3a9f9ff4)

Subject: add better local patch info to perlbug
From: Tim Bunce <Tim.Bunce@ig.co.uk>
Files: utils/perlbug.PL

Subject: perldoc - suggest modules if requested module not found
From: Anthony David <adavid@netinfo.com.au>
Files: utils/perldoc.PL

    private-msgid: 3439CD83.6969@netinfo.com.au

Subject: perldoc mail::foo tries to read binary /usr/ucb/mail
From: Tim Bunce <Tim.Bunce@ig.co.uk>
Files: utils/perldoc.PL

    Subject: perldoc weirdness
    
    perldoc mail::imap yields:
    
    {joseph}:79% perldoc mail::foo
    can't open /usr/ucb/mail: Permission denied at ./pod2man line 362.
    
    Credited: Joseph "Moof-in'" Hall <joseph@cscaper.com>
    
    p5p-msgid: 199710082014.NAA00808@gadget.cscaper.com

Subject: perldoc -f setpwent (for example) returns no descriptive text
From: Tim Bunce <Tim.Bunce@ig.co.uk>
Files: utils/perldoc.PL

Subject: perldoc diffs: don't search auto - much faster
From: "Joseph N. Hall" <joseph@5sigma.com>
Files: utils/perldoc.PL
Msg-ID: MailDrop1.2d7dPPC.971012211957@screechy.cscaper.com

    (applied based on p5p patch as commit 62b753c6ae4ab9bf22fbb6ec7ceac820bcef8fe4)

1 files changed, 70 insertions, 33 deletions

diff --git a/pod/perlvar.pod b/pod/perlvar.pod
index 6487fdda36..75f4e6d5c2 100644
--- a/pod/perlvar.pod
+++ b/pod/perlvar.pod
@@ -18,9 +18,9 @@ long names in the current package.  Some of them even have medium names,
 generally borrowed from B<awk>.
 
 To go a step further, those variables that depend on the currently
-selected filehandle may instead be set by calling an object method on
-the FileHandle object.  (Summary lines below for this contain the word
-HANDLE.)  First you must say
+selected filehandle may instead (and preferably) be set by calling an
+object method on the FileHandle object.  (Summary lines below for this
+contain the word HANDLE.)  First you must say
 
     use FileHandle;
 
@@ -42,6 +42,12 @@ A few of these variables are considered "read-only".  This means that if
 you try to assign to this variable, either directly or indirectly through
 a reference, you'll raise a run-time exception.
 
+The following list is ordered by scalar variables first, then the
+arrays, then the hashes (except $^M was added in the wrong place).
+This is somewhat obscured by the fact that %ENV and %SIG are listed as
+$ENV{expr} and $SIG{expr}.
+
+
 =over 8
 
 =item $ARG
@@ -438,16 +444,13 @@ operator.  (Mnemonic: What just went bang?)
 =item $^E
 
 More specific information about the last system error than that provided by
-C<$!>, if available.  (If not, it's just C<$!> again, except under OS/2.)
+C<$!>, if available.  (If not, it's just C<$!> again.)
 At the moment, this differs from C<$!> under only VMS and OS/2, where it
 provides the VMS status value from the last system error, and OS/2 error
-code of the last call to OS/2 API which was not directed via CRT.  The
+code of the last call to OS/2 API either via CRT, or directly from perl.  The
 caveats mentioned in the description of C<$!> apply here, too.
 (Mnemonic: Extra error explanation.)
 
-Note that under OS/2 C<$!> and C<$^E> do not track each other, so if an
-OS/2-specific call is performed, you may need to check both.
-
 =item $EVAL_ERROR
 
 =item $@
@@ -597,8 +600,8 @@ C<$^F> at the time of the open, not the time of the exec.
 
 =item $^H
 
-The current set of syntax checks enabled by C<use strict>.  See the
-documentation of C<strict> for more details.
+The current set of syntax checks enabled by C<use strict> and other block
+scoped compiler hints.  See the documentation of C<strict> for more details.
 
 =item $INPLACE_EDIT
 
@@ -607,6 +610,20 @@ documentation of C<strict> for more details.
 The current value of the inplace-edit extension.  Use C<undef> to disable
 inplace editing.  (Mnemonic: value of B<-i> switch.)
 
+=item $^M
+
+By default, running out of memory it is not trappable.  However, if
+compiled for this, Perl may use the contents of C<$^M> as an emergency
+pool after die()ing with this message.  Suppose that your Perl were
+compiled with -DPERL_EMERGENCY_SBRK and used Perl's malloc.  Then
+
+    $^M = 'a' x (1<<16);
+
+would allocate a 64K buffer for use when in emergency.  See the F<INSTALL>
+file for information on how to enable this option.  As a disincentive to
+casual use of this advanced feature, there is no L<English> long name for
+this variable.
+
 =item $OSNAME
 
 =item $^O
@@ -653,6 +670,12 @@ Start with single-step on.
 Note that some bits may be relevent at compile-time only, some at
 run-time only. This is a new mechanism and the details may change.
 
+=item $^S
+
+Current state of the interpreter.  Undefined if parsing of the current
+module/eval is not finished (may happen in $SIG{__DIE__} and
+$SIG{__WARN__} handlers).  True if inside an eval, othewise false.
+
 =item $BASETIME
 
 =item $^T
@@ -699,6 +722,11 @@ to get the machine-dependent library properly loaded also:
     use lib '/mypath/libdir/';
     use SomeMod;
 
+=item @_
+
+Within a subroutine the array @_ contains the parameters passed to that
+subroutine. See L<perlsub>.
+
 =item %INC
 
 The hash %INC contains entries for each filename that has
@@ -707,25 +735,25 @@ specified, and the value is the location of the file actually found.
 The C<require> command uses this array to determine whether a given file
 has already been included.
 
-=item $ENV{expr}
+=item %ENV  $ENV{expr}
 
 The hash %ENV contains your current environment.  Setting a
 value in C<ENV> changes the environment for child processes.
 
-=item $SIG{expr}
+=item %SIG  $SIG{expr}
 
 The hash %SIG is used to set signal handlers for various
 signals.  Example:
 
     sub handler {	# 1st argument is signal name
-	local($sig) = @_;
+	my($sig) = @_;
 	print "Caught a SIG$sig--shutting down\n";
 	close(LOG);
 	exit(0);
     }
 
-    $SIG{'INT'} = 'handler';
-    $SIG{'QUIT'} = 'handler';
+    $SIG{'INT'}  = \&handler;
+    $SIG{'QUIT'} = \&handler;
     ...
     $SIG{'INT'} = 'DEFAULT';	# restore default action
     $SIG{'QUIT'} = 'IGNORE';	# ignore SIGQUIT
@@ -733,8 +761,8 @@ signals.  Example:
 The %SIG array contains values for only the signals actually set within
 the Perl script.  Here are some other examples:
 
-    $SIG{PIPE} = Plumber;       # SCARY!!
-    $SIG{"PIPE"} = "Plumber";   # just fine, assumes main::Plumber
+    $SIG{"PIPE"} = Plumber;     # SCARY!!
+    $SIG{"PIPE"} = "Plumber";   # assumes main::Plumber (not recommended)
     $SIG{"PIPE"} = \&Plumber;   # just fine; assume current Plumber
     $SIG{"PIPE"} = Plumber();   # oops, what did Plumber() return??
 
@@ -775,21 +803,30 @@ argument.  When a __DIE__ hook routine returns, the exception
 processing continues as it would have in the absence of the hook,
 unless the hook routine itself exits via a C<goto>, a loop exit, or a die().
 The C<__DIE__> handler is explicitly disabled during the call, so that you
-can die from a C<__DIE__> handler.  Similarly for C<__WARN__>.  See
-L<perlfunc/die>, L<perlfunc/warn> and L<perlfunc/eval>.
-
-=item $^M
-
-By default, running out of memory it is not trappable.  However, if
-compiled for this, Perl may use the contents of C<$^M> as an emergency
-pool after die()ing with this message.  Suppose that your Perl were
-compiled with -DPERL_EMERGENCY_SBRK and used Perl's malloc.  Then
-
-    $^M = 'a' x (1<<16);
-
-would allocate a 64K buffer for use when in emergency.  See the F<INSTALL>
-file for information on how to enable this option.  As a disincentive to
-casual use of this advanced feature, there is no L<English> long name for
-this variable.
+can die from a C<__DIE__> handler.  Similarly for C<__WARN__>.
+
+Note that the C<$SIG{__DIE__}> hook is called even inside eval()ed
+blocks/strings.  See L<perlfunc/die>, L<perlvar/$^S> for how to
+circumvent this.
+
+Note that C<__DIE__>/C<__WARN__> handlers are very special in one
+respect: they may be called to report (probable) errors found by the
+parser.  In such a case the parser may be in inconsistent state, so
+any attempt to evaluate Perl code from such a handler will probably
+result in a segfault.  This means that calls which result/may-result
+in parsing Perl should be used with extreme causion, like this:
+
+    require Carp if defined $^S;
+    Carp::confess("Something wrong") if defined &Carp::confess;
+    die "Something wrong, but could not load Carp to give backtrace...
+         To see backtrace try starting Perl with -MCarp switch";
+
+Here the first line will load Carp I<unless> it is the parser who
+called the handler.  The second line will print backtrace and die if
+Carp was available.  The third line will be executed only if Carp was
+not available.
+
+See L<perlfunc/die>, L<perlfunc/warn> and L<perlfunc/eval> for
+additional info.
 
 =back