perl 5.004_04

1 files changed, 250 insertions, 113 deletions

diff --git a/gnu/usr.bin/perl/pod/perlvar.pod b/gnu/usr.bin/perl/pod/perlvar.pod
index 3d1c195007b..75f4e6d5c2b 100644
--- a/gnu/usr.bin/perl/pod/perlvar.pod
+++ b/gnu/usr.bin/perl/pod/perlvar.pod
@@ -7,7 +7,7 @@ perlvar - Perl predefined variables
 =head2 Predefined Names
 
 The following names have special meaning to Perl.  Most of the
-punctuational names have reasonable mnemonics, or analogues in one of
+punctuation names have reasonable mnemonics, or analogues in one of
 the shells.  Nevertheless, if you wish to use the long variable names,
 you just need to say
 
@@ -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
@@ -51,8 +57,8 @@ a reference, you'll raise a run-time exception.
 The default input and pattern-searching space.  The following pairs are
 equivalent:
 
-    while (<>) {...}	# only equivalent in while!
-    while ($_ = <>) {...}
+    while (<>) {...}	# equivalent in only while!
+    while (defined($_ = <>)) {...}
 
     /^Subject:/
     $_ =~ /^Subject:/
@@ -63,7 +69,7 @@ equivalent:
     chop
     chop($_)
 
-Here are the places where Perl will assume $_ even if you 
+Here are the places where Perl will assume $_ even if you
 don't use it:
 
 =over 3
@@ -83,16 +89,16 @@ Various list functions like print() and unlink().
 The pattern matching operations C<m//>, C<s///>, and C<tr///> when used
 without an C<=~> operator.
 
-=item * 
+=item *
 
 The default iterator variable in a C<foreach> loop if no other
 variable is supplied.
 
-=item * 
+=item *
 
 The implicit iterator variable in the grep() and map() functions.
 
-=item * 
+=item *
 
 The default place to put an input record when a C<E<lt>FHE<gt>>
 operation's result is tested by itself as the sole criterion of a C<while>
@@ -102,7 +108,11 @@ test.  Note that outside of a C<while> test, this will not happen.
 
 (Mnemonic: underline is understood in certain operations.)
 
-=item $<I<digit>>
+=back
+
+=over 8
+
+=item $E<lt>I<digit>E<gt>
 
 Contains the subpattern from the corresponding set of parentheses in
 the last pattern matched, not counting patterns matched in nested
@@ -123,7 +133,7 @@ BLOCK).  (Mnemonic: like & in some editors.)  This variable is read-only.
 
 The string preceding whatever was matched by the last successful
 pattern match (not counting any matches hidden within a BLOCK or eval
-enclosed by the current BLOCK).  (Mnemonic: ` often precedes a quoted
+enclosed by the current BLOCK).  (Mnemonic: C<`> often precedes a quoted
 string.)  This variable is read-only.
 
 =item $POSTMATCH
@@ -132,7 +142,7 @@ string.)  This variable is read-only.
 
 The string following whatever was matched by the last successful
 pattern match (not counting any matches hidden within a BLOCK or eval()
-enclosed by the current BLOCK).  (Mnemonic: ' often follows a quoted
+enclosed by the current BLOCK).  (Mnemonic: C<'> often follows a quoted
 string.)  Example:
 
     $_ = 'abcdefghi';
@@ -158,15 +168,15 @@ This variable is read-only.
 
 =item $*
 
-Set to 1 to do multiline matching within a string, 0 to tell Perl
+Set to 1 to do multi-line matching within a string, 0 to tell Perl
 that it can assume that strings contain a single line, for the purpose
 of optimizing pattern matches.  Pattern matches on strings containing
 multiple newlines can produce confusing results when "C<$*>" is 0.  Default
 is 0.  (Mnemonic: * matches multiple things.)  Note that this variable
-only influences the interpretation of "C<^>" and "C<$>".  A literal newline can
+influences the interpretation of only "C<^>" and "C<$>".  A literal newline can
 be searched for even when C<$* == 0>.
 
-Use of "C<$*>" is deprecated in Perl 5.
+Use of "C<$*>" is deprecated in modern perls.
 
 =item input_line_number HANDLE EXPR
 
@@ -176,8 +186,9 @@ Use of "C<$*>" is deprecated in Perl 5.
 
 =item $.
 
-The current input line number of the last filehandle that was read.  An
-explicit close on the filehandle resets the line number.  Since
+The current input line number for the last file handle from
+which you read (or performed a C<seek> or C<tell> on).  An
+explicit close on a filehandle resets the line number.  Because
 "C<E<lt>E<gt>>" never does an explicit close, line numbers increase
 across ARGV files (but see examples under eof()).  Localizing C<$.> has
 the effect of also localizing Perl's notion of "the last read
@@ -193,33 +204,39 @@ number.)
 =item $/
 
 The input record separator, newline by default.  Works like B<awk>'s RS
-variable, including treating blank lines as delimiters if set to the
-null string.  You may set it to a multicharacter string to match a
-multi-character delimiter.  Note that setting it to C<"\n\n"> means
-something slightly different than setting it to C<"">, if the file
-contains consecutive blank lines.  Setting it to C<""> will treat two or
-more consecutive blank lines as a single blank line.  Setting it to
-C<"\n\n"> will blindly assume that the next input character belongs to the
-next paragraph, even if it's a newline.  (Mnemonic: / is used to
-delimit line boundaries when quoting poetry.)
+variable, including treating empty lines as delimiters if set to the
+null string.  (Note: An empty line cannot contain any spaces or tabs.)
+You may set it to a multi-character string to match a multi-character
+delimiter, or to C<undef> to read to end of file.  Note that setting it
+to C<"\n\n"> means something slightly different than setting it to
+C<"">, if the file contains consecutive empty lines.  Setting it to
+C<""> will treat two or more consecutive empty lines as a single empty
+line.  Setting it to C<"\n\n"> will blindly assume that the next input
+character belongs to the next paragraph, even if it's a newline.
+(Mnemonic: / is used to delimit line boundaries when quoting poetry.)
 
     undef $/;
     $_ = <FH>; 		# whole file now here
     s/\n[ \t]+/ /g;
 
+Remember: the value of $/ is a string, not a regexp.  AWK has to be
+better for something :-)
+
 =item autoflush HANDLE EXPR
 
 =item $OUTPUT_AUTOFLUSH
 
 =item $|
 
-If set to nonzero, forces a flush after every write or print on the
-currently selected output channel.  Default is 0.  Note that STDOUT
-will typically be line buffered if output is to the terminal and block
-buffered otherwise.  Setting this variable is useful primarily when you
-are outputting to a pipe, such as when you are running a Perl script
-under rsh and want to see the output as it's happening.  This has no
-effect on input buffering.  
+If set to nonzero, forces a flush right away and after every write or print on the
+currently selected output channel.  Default is 0 (regardless of whether
+the channel is actually buffered by the system or not; C<$|> tells you
+only whether you've asked Perl explicitly to flush after each write).
+Note that STDOUT will typically be line buffered if output is to the
+terminal and block buffered otherwise.  Setting this variable is useful
+primarily when you are outputting to a pipe, such as when you are running
+a Perl script under rsh and want to see the output as it's happening.  This
+has no effect on input buffering.
 (Mnemonic: when you want your pipes to be piping hot.)
 
 =item output_field_separator HANDLE EXPR
@@ -231,8 +248,8 @@ effect on input buffering.
 =item $,
 
 The output field separator for the print operator.  Ordinarily the
-print operator simply prints out the comma separated fields you
-specify.  In order to get behavior more like B<awk>, set this variable
+print operator simply prints out the comma-separated fields you
+specify.  To get behavior more like B<awk>, set this variable
 as you would set B<awk>'s OFS variable to specify what is printed
 between fields.  (Mnemonic: what is printed when there is a , in your
 print statement.)
@@ -246,12 +263,12 @@ print statement.)
 =item $\
 
 The output record separator for the print operator.  Ordinarily the
-print operator simply prints out the comma separated fields you
-specify, with no trailing newline or record separator assumed.  In
-order to get behavior more like B<awk>, set this variable as you would
+print operator simply prints out the comma-separated fields you
+specify, with no trailing newline or record separator assumed.
+To get behavior more like B<awk>, set this variable as you would
 set B<awk>'s ORS variable to specify what is printed at the end of the
 print.  (Mnemonic: you set "C<$\>" instead of adding \n at the end of the
-print.  Also, it's just like /, but it's what you get "back" from
+print.  Also, it's just like C<$/>, but it's what you get "back" from
 Perl.)
 
 =item $LIST_SEPARATOR
@@ -268,7 +285,7 @@ is a space.  (Mnemonic: obvious, I think.)
 
 =item $;
 
-The subscript separator for multi-dimensional array emulation.  If you
+The subscript separator for multidimensional array emulation.  If you
 refer to a hash element as
 
     $foo{$a,$b,$c}
@@ -291,7 +308,7 @@ keys contain binary data there might not be any safe value for "C<$;>".
 semi-semicolon.  Yeah, I know, it's pretty lame, but "C<$,>" is already
 taken for something more important.)
 
-Consider using "real" multi-dimensional arrays in Perl 5.
+Consider using "real" multidimensional arrays.
 
 =item $OFMT
 
@@ -300,11 +317,12 @@ Consider using "real" multi-dimensional arrays in Perl 5.
 The output format for printed numbers.  This variable is a half-hearted
 attempt to emulate B<awk>'s OFMT variable.  There are times, however,
 when B<awk> and Perl have differing notions of what is in fact
-numeric.  Also, the initial value is %.20g rather than %.6g, so you
-need to set "C<$#>" explicitly to get B<awk>'s value.  (Mnemonic: # is the
-number sign.)
+numeric.  The initial value is %.I<n>g, where I<n> is the value
+of the macro DBL_DIG from your system's F<float.h>.  This is different from
+B<awk>'s default OFMT setting of %.6g, so you need to set "C<$#>"
+explicitly to get B<awk>'s value.  (Mnemonic: # is the number sign.)
 
-Use of "C<$#>" is deprecated in Perl 5.
+Use of "C<$#>" is deprecated.
 
 =item format_page_number HANDLE EXPR
 
@@ -360,7 +378,7 @@ appended.  (Mnemonic: points to top of page.)
 =item $:
 
 The current set of characters after which a string may be broken to
-fill continuation fields (starting with ^) in a format.  Default is 
+fill continuation fields (starting with ^) in a format.  Default is
 S<" \n-">, to break on whitespace or hyphens.  (Mnemonic: a "colon" in
 poetry is a part of a line.)
 
@@ -370,7 +388,7 @@ poetry is a part of a line.)
 
 =item $^L
 
-What formats output to perform a formfeed.  Default is \f.
+What formats output to perform a form feed.  Default is \f.
 
 =item $ACCUMULATOR
 
@@ -389,10 +407,22 @@ L<perlfunc/formline()>.
 
 The status returned by the last pipe close, backtick (C<``>) command,
 or system() operator.  Note that this is the status word returned by
-the wait() system call, so the exit value of the subprocess is actually
-(C<$? E<gt>E<gt> 8>).  Thus on many systems, C<$? & 255> gives which signal,
-if any, the process died from, and whether there was a core dump.
-(Mnemonic: similar to B<sh> and B<ksh>.)
+the wait() system call (or else is made up to look like it).  Thus,
+the exit value of the subprocess is actually (C<$? E<gt>E<gt> 8>), and
+C<$? & 255> gives which signal, if any, the process died from, and
+whether there was a core dump.  (Mnemonic: similar to B<sh> and
+B<ksh>.)
+
+Note that if you have installed a signal handler for C<SIGCHLD>, the
+value of C<$?> will usually be wrong outside that handler.
+
+Inside an C<END> subroutine C<$?> contains the value that is going to be
+given to C<exit()>.  You can modify C<$?> in an C<END> subroutine to
+change the exit status of the script.
+
+Under VMS, the pragma C<use vmsish 'status'> makes C<$?> reflect the
+actual VMS exit status, instead of the default emulation of POSIX
+status.
 
 =item $OS_ERROR
 
@@ -405,7 +435,7 @@ all the usual caveats.  (This means that you shouldn't depend on the
 value of "C<$!>" to be anything in particular unless you've gotten a
 specific error return indicating a system error.)  If used in a string
 context, yields the corresponding system error string.  You can assign
-to "C<$!>" in order to set I<errno> if, for instance, you want "C<$!>" to return the
+to "C<$!>" to set I<errno> if, for instance, you want "C<$!>" to return the
 string for error I<n>, or you want to set the exit value for the die()
 operator.  (Mnemonic: What just went bang?)
 
@@ -413,14 +443,14 @@ 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.)
-At the moment, this differs from C<$!> only under VMS, where it
-provides the VMS status value from the last system error.  The
+More specific information about the last system error than that provided by
+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 either via CRT, or directly from perl.  The
 caveats mentioned in the description of C<$!> apply here, too.
 (Mnemonic: Extra error explanation.)
 
-
 =item $EVAL_ERROR
 
 =item $@
@@ -431,7 +461,8 @@ invoked may have failed in the normal fashion).  (Mnemonic: Where was
 the syntax error "at"?)
 
 Note that warning messages are not collected in this variable.  You can,
-however, set up a routine to process warnings by setting $SIG{__WARN__} below.
+however, set up a routine to process warnings by setting C<$SIG{__WARN__}>
+as described below.
 
 =item $PROCESS_ID
 
@@ -462,8 +493,9 @@ The effective uid of this process.  Example:
     $< = $>;		# set real to effective uid
     ($<,$>) = ($>,$<);	# swap real and effective uid
 
-(Mnemonic: it's the uid you went I<TO>, if you're running setuid.)  Note:
-"C<$E<lt>>" and "C<$E<gt>>" can only be swapped on machines supporting setreuid().
+(Mnemonic: it's the uid you went I<TO>, if you're running setuid.)
+Note: "C<$E<lt>>" and "C<$E<gt>>" can be swapped only on machines
+supporting setreuid().
 
 =item $REAL_GROUP_ID
 
@@ -475,8 +507,14 @@ The real gid of this process.  If you are on a machine that supports
 membership in multiple groups simultaneously, gives a space separated
 list of groups you are in.  The first number is the one returned by
 getgid(), and the subsequent ones by getgroups(), one of which may be
-the same as the first number.  (Mnemonic: parentheses are used to I<GROUP>
-things.  The real gid is the group you I<LEFT>, if you're running setgid.)
+the same as the first number.
+
+However, a value assigned to "C<$(>" must be a single number used to
+set the real gid.  So the value given by "C<$(>" should I<not> be assigned
+back to "C<$(>" without being forced numeric, such as by adding zero.
+
+(Mnemonic: parentheses are used to I<GROUP> things.  The real gid is the
+group you I<LEFT>, if you're running setgid.)
 
 =item $EFFECTIVE_GROUP_ID
 
@@ -488,21 +526,29 @@ The effective gid of this process.  If you are on a machine that
 supports membership in multiple groups simultaneously, gives a space
 separated list of groups you are in.  The first number is the one
 returned by getegid(), and the subsequent ones by getgroups(), one of
-which may be the same as the first number.  (Mnemonic: parentheses are
-used to I<GROUP> things.  The effective gid is the group that's I<RIGHT> for
-you, if you're running setgid.)
+which may be the same as the first number.
+
+Similarly, a value assigned to "C<$)>" must also be a space-separated
+list of numbers.  The first number is used to set the effective gid, and
+the rest (if any) are passed to setgroups().  To get the effect of an
+empty list for setgroups(), just repeat the new effective gid; that is,
+to force an effective gid of 5 and an effectively empty setgroups()
+list, say C< $) = "5 5" >.
 
-Note: "C<$E<lt>>", "C<$E<gt>>", "C<$(>" and "C<$)>" can only be set on machines
-that support the corresponding I<set[re][ug]id()> routine.  "C<$(>" and "C<$)>" 
-can only be swapped on machines supporting setregid().   Because Perl doesn't
-currently use initgroups(), you can't set your group vector to multiple groups.
+(Mnemonic: parentheses are used to I<GROUP> things.  The effective gid
+is the group that's I<RIGHT> for you, if you're running setgid.)
+
+Note: "C<$E<lt>>", "C<$E<gt>>", "C<$(>" and "C<$)>" can be set only on
+machines that support the corresponding I<set[re][ug]id()> routine.  "C<$(>"
+and "C<$)>" can be swapped only on machines supporting setregid().
 
 =item $PROGRAM_NAME
 
 =item $0
 
 Contains the name of the file containing the Perl script being
-executed.  Assigning to "C<$0>" modifies the argument area that the ps(1)
+executed.  On some operating systems
+assigning to "C<$0>" modifies the argument area that the ps(1)
 program sees.  This is more useful as a way of indicating the
 current program state than it is for hiding the program you're running.
 (Mnemonic: same as B<sh> and B<ksh>.)
@@ -523,24 +569,15 @@ discouraged.
 
 =item $]
 
-The string printed out when you say C<perl -v>.
-(This is currently I<BROKEN>).
-It can be used to
-determine at the beginning of a script whether the perl interpreter
-executing the script is in the right range of versions.  If used in a
-numeric context, returns the version + patchlevel / 1000.  Example:
-
-    # see if getc is available
-    ($version,$patchlevel) =
-	     $] =~ /(\d+\.\d+).*\nPatch level: (\d+)/;
-    print STDERR "(No filename completion available.)\n"
-	     if $version * 1000 + $patchlevel < 2016;
-
-or, used numerically,
+The version + patchlevel / 1000 of the Perl interpreter.  This variable
+can be used to determine whether the Perl interpreter executing a
+script is in the right range of versions.  (Mnemonic: Is this version
+of perl in the right bracket?)  Example:
 
     warn "No checksumming!\n" if $] < 3.019;
 
-(Mnemonic: Is this version of perl in the right bracket?)
+See also the documentation of C<use VERSION> and C<require VERSION>
+for a convenient way to fail if the Perl interpreter is too old.
 
 =item $DEBUGGING
 
@@ -561,6 +598,11 @@ closed before the open() is attempted.)  Note that the close-on-exec
 status of a file descriptor will be decided according to the value of
 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> and other block
+scoped compiler hints.  See the documentation of C<strict> for more details.
+
 =item $INPLACE_EDIT
 
 =item $^I
@@ -568,7 +610,22 @@ C<$^F> at the time of the open, not the time of the exec.
 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
 
 The name of the operating system under which this copy of Perl was
@@ -579,16 +636,52 @@ is identical to C<$Config{'osname'}>.
 
 =item $^P
 
-The internal flag that the debugger clears so that it doesn't debug
-itself.  You could conceivably disable debugging yourself by clearing
-it.
+The internal variable for debugging support.  Different bits mean the
+following (subject to change): 
+
+=over 6
+
+=item 0x01
+
+Debug subroutine enter/exit.
+
+=item 0x02
+
+Line-by-line debugging.
+
+=item 0x04
+
+Switch off optimizations.
+
+=item 0x08
+
+Preserve more data for future interactive inspections.
+
+=item 0x10
+
+Keep info about source lines on which a subroutine is defined.
+
+=item 0x20
+
+Start with single-step on.
+
+=back
+
+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
 
 The time at which the script began running, in seconds since the
-epoch (beginning of 1970).  The values returned by the B<-M>, B<-A> 
+epoch (beginning of 1970).  The values returned by the B<-M>, B<-A>,
 and B<-C> filetests are
 based on this value.
 
@@ -596,8 +689,8 @@ based on this value.
 
 =item $^W
 
-The current value of the warning switch, either TRUE or FALSE.  (Mnemonic: related to the
-B<-w> switch.)
+The current value of the warning switch, either TRUE or FALSE.
+(Mnemonic: related to the B<-w> switch.)
 
 =item $EXECUTABLE_NAME
 
@@ -607,13 +700,13 @@ The name that the Perl binary itself was executed as, from C's C<argv[0]>.
 
 =item $ARGV
 
-contains the name of the current file when reading from <>.
+contains the name of the current file when reading from E<lt>E<gt>.
 
 =item @ARGV
 
 The array @ARGV contains the command line arguments intended for the
 script.  Note that C<$#ARGV> is the generally number of arguments minus
-one, since C<$ARGV[0]> is the first argument, I<NOT> the command name.  See
+one, because C<$ARGV[0]> is the first argument, I<NOT> the command name.  See
 "C<$0>" for the command name.
 
 =item @INC
@@ -621,14 +714,19 @@ one, since C<$ARGV[0]> is the first argument, I<NOT> the command name.  See
 The array @INC contains the list of places to look for Perl scripts to
 be evaluated by the C<do EXPR>, C<require>, or C<use> constructs.  It
 initially consists of the arguments to any B<-I> command line switches,
-followed by the default Perl library, probably "/usr/local/lib/perl",
+followed by the default Perl library, probably F</usr/local/lib/perl>,
 followed by ".", to represent the current directory.  If you need to
-modify this at runtime, you should use the C<use lib> pragma in order
-to also get the machine-dependent library properly loaded:
+modify this at runtime, you should use the C<use lib> pragma
+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
@@ -637,44 +735,60 @@ 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
 
-The %SIG array only contains values for the signals actually set within
+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??
 
 The one marked scary is problematic because it's a bareword, which means
-sometimes it's a string representing the function, and sometimes it's 
+sometimes it's a string representing the function, and sometimes it's
 going to call the subroutine call right then and there!  Best to be sure
-and quote it or take a reference to it.  *Plumber works too.  See L<perlsubs>.
+and quote it or take a reference to it.  *Plumber works too.  See L<perlsub>.
+
+If your system has the sigaction() function then signal handlers are
+installed using it.  This means you get reliable signal handling.  If
+your system has the SA_RESTART flag it is used when signals handlers are
+installed.  This means that system calls for which it is supported
+continue rather than returning when a signal arrives.  If you want your
+system calls to be interrupted by signal delivery then do something like
+this:
+
+    use POSIX ':signal_h';
+
+    my $alarm = 0;
+    sigaction SIGALRM, new POSIX::SigAction sub { $alarm = 1 }
+    	or die "Error setting SIGALRM handler: $!\n";
+
+See L<POSIX>.
 
 Certain internal hooks can be also set using the %SIG hash.  The
-routine indicated by $SIG{__WARN__} is called when a warning message is
+routine indicated by C<$SIG{__WARN__}> is called when a warning message is
 about to be printed.  The warning message is passed as the first
 argument.  The presence of a __WARN__ hook causes the ordinary printing
 of warnings to STDERR to be suppressed.  You can use this to save warnings
@@ -683,13 +797,36 @@ in a variable, or turn warnings into fatal errors, like this:
     local $SIG{__WARN__} = sub { die $_[0] };
     eval $proggie;
 
-The routine indicated by $SIG{__DIE__} is called when a fatal exception
+The routine indicated by C<$SIG{__DIE__}> is called when a fatal exception
 is about to be thrown.  The error message is passed as the first
 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 __DIE__ handler is explicitly disabled during the call, so that you
-can die from a __DIE__ handler.  Similarly for __WARN__.
+The C<__DIE__> handler is explicitly disabled during the call, so that you
+can die from a C<__DIE__> handler.  Similarly for C<__WARN__>.
 
-=back
+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