=head2 Predefined Names
-The following names have special meaning to Perl. Most of the
-punctuational names have reasonable mnemonics, or analogues in one of
-the shells. Nevertheless, if you wish to use the long variable names,
+The following names have special meaning to Perl. Most
+punctuation names have reasonable mnemonics, or analogues in one of
+the shells. Nevertheless, if you wish to use long variable names,
you just need to say
use English;
at the top of your program. This will alias all the short names to the
-long names in the current package. Some of them even have medium names,
+long names in the current package. Some 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;
method HANDLE EXPR
-or
+or more safely,
HANDLE->method(EXPR)
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
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:/
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
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>
(Mnemonic: underline is understood in certain operations.)
-=item $<I<digit>>
+=back
+
+=over 8
+
+=item $E<lt>I<digits>E<gt>
Contains the subpattern from the corresponding set of parentheses in
the last pattern matched, not counting patterns matched in nested
-blocks that have been exited already. (Mnemonic: like \digit.)
+blocks that have been exited already. (Mnemonic: like \digits.)
These variables are all read-only.
=item $MATCH
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
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';
=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, supplanted by
+the C</s> and C</m> modifiers on pattern matching.
=item input_line_number HANDLE EXPR
=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
=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 :-)
+
+Setting $/ to a reference to an integer, scalar containing an integer, or
+scalar that's convertable to an integer will attempt to read records
+instead of lines, with the maximum record size being the referenced
+integer. So this:
+
+ $/ = \32768; # or \"32768", or \$var_containing_32768
+ open(FILE, $myfile);
+ $_ = <FILE>;
+
+will read a record of no more than 32768 bytes from FILE. If you're not
+reading from a record-oriented file (or your OS doesn't have
+record-oriented files), then you'll likely get a full chunk of data with
+every read. If a record is larger than the record size you've set, you'll
+get the record back in pieces.
+
+On VMS, record reads are done with the equivalent of C<sysread>, so it's
+best not to mix record and non-record reads on the same file. (This is
+likely not a problem, as any file you'd want to read in record mode is
+proably usable in line mode) Non-VMS systems perform normal I/O, so
+it's safe to mix record and non-record reads of a file.
+
=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
=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.)
=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
=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}
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
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
=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.)
=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
=item $?
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>.)
+or system() operator. Note that this is the status word returned by 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<$? & 127>
+gives which signal, if any, the process died from, and C<$? & 128> reports
+whether there was a core dump. (Mnemonic: similar to B<sh> and B<ksh>.)
+
+Additionally, if the C<h_errno> variable is supported in C, its value
+is returned via $? if any of the C<gethost*()> functions fail.
+
+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
If used in a numeric context, yields the current value of errno, with
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
+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?)
+=item $EXTENDED_OS_ERROR
+
+=item $^E
+
+Error information specific to the current operating system. At
+the moment, this differs from C<$!> under only VMS, OS/2, and Win32
+(and for MacPerl). On all other platforms, C<$^E> is always just
+the same as C<$!>.
+
+Under VMS, C<$^E> provides the VMS status value from the last
+system error. This is more specific information about the last
+system error than that provided by C<$!>. This is particularly
+important when C<$!> is set to B<EVMSERR>.
+
+Under OS/2, C<$^E> is set to the error code of the last call to
+OS/2 API either via CRT, or directly from perl.
+
+Under Win32, C<$^E> always returns the last error information
+reported by the Win32 call C<GetLastError()> which describes
+the last error from within the Win32 API. Most Win32-specific
+code will report errors via C<$^E>. ANSI C and UNIX-like calls
+set C<errno> and so most portable Perl code will report errors
+via C<$!>.
+
+Caveats mentioned in the description of C<$!> generally apply to
+C<$^E>, also. (Mnemonic: Extra error explanation.)
+
=item $EVAL_ERROR
=item $@
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
$< = $>; # 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
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
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.
-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.
+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" >.
+
+(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>.)
=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
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
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
+built, as determined during the configuration process. The value
+is identical to C<$Config{'osname'}>.
+
=item $PERLDB
=item $^P
-The internal flag that the debugger clears so that it doesn't debug
-itself. You could conceivable 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, otherwise 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.
=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
=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
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
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
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> and 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