Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 2893 insertions, 0 deletions

diff --git a/upstream/mageia-cauldron/man1/perlvar.1 b/upstream/mageia-cauldron/man1/perlvar.1
new file mode 100644
index 00000000..9b06d42d
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlvar.1
@@ -0,0 +1,2893 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLVAR 1"
+.TH PERLVAR 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH NAME
+perlvar \- Perl predefined variables
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+.SS "The Syntax of Variable Names"
+.IX Subsection "The Syntax of Variable Names"
+Variable names in Perl can have several formats.  Usually, they
+must begin with a letter or underscore, in which case they can be
+arbitrarily long (up to an internal limit of 251 characters) and
+may contain letters, digits, underscores, or the special sequence
+\&\f(CW\*(C`::\*(C'\fR or \f(CW\*(C`\*(Aq\*(C'\fR.  In this case, the part before the last \f(CW\*(C`::\*(C'\fR or
+\&\f(CW\*(C`\*(Aq\*(C'\fR is taken to be a \fIpackage qualifier\fR; see perlmod.
+A Unicode letter that is not ASCII is not considered to be a letter
+unless \f(CW"use\ utf8"\fR is in effect, and somewhat more complicated
+rules apply; see "Identifier parsing" in perldata for details.
+.PP
+Perl variable names may also be a sequence of digits, a single
+punctuation character, or the two-character sequence: \f(CW\*(C`^\*(C'\fR (caret or
+CIRCUMFLEX ACCENT) followed by any one of the characters \f(CW\*(C`[][A\-Z^_?\e]\*(C'\fR.
+These names are all reserved for
+special uses by Perl; for example, the all-digits names are used
+to hold data captured by backreferences after a regular expression
+match.
+.PP
+Since Perl v5.6.0, Perl variable names may also be alphanumeric strings
+preceded by a caret.  These must all be written using the demarcated
+variable form using curly braces such as \f(CW\*(C`${^Foo}\*(C'\fR;
+the braces are \fBnot\fR optional.  \f(CW\*(C`${^Foo}\*(C'\fR denotes the scalar variable
+whose name is considered to be a control\-\f(CW\*(C`F\*(C'\fR followed by two \f(CW\*(C`o\*(C'\fR's.
+(See "Demarcated variable names using braces" in perldata for more
+information on this form of spelling a variable name or specifying
+access to an element of an array or a hash).
+These variables are
+reserved for future special uses by Perl, except for the ones that
+begin with \f(CW\*(C`^_\*(C'\fR (caret-underscore).  No
+name that begins with \f(CW\*(C`^_\*(C'\fR will acquire a special
+meaning in any future version of Perl; such names may therefore be
+used safely in programs.  \f(CW$^_\fR itself, however, \fIis\fR reserved.
+.PP
+Note that you also \fBmust\fR use the demarcated form to access subscripts
+of variables of this type when interpolating, for instance to access the
+first element of the \f(CW\*(C`@{^CAPTURE}\*(C'\fR variable inside of a double quoted
+string you would write \f(CW"${^CAPTURE[0]}"\fR and NOT \f(CW"${^CAPTURE}[0]"\fR
+which would mean to reference a scalar variable named \f(CW\*(C`${^CAPTURE}\*(C'\fR and
+not index 0 of the magic \f(CW\*(C`@{^CAPTURE}\*(C'\fR array which is populated by the
+regex engine.
+.PP
+Perl identifiers that begin with digits or
+punctuation characters are exempt from the effects of the \f(CW\*(C`package\*(C'\fR
+declaration and are always forced to be in package \f(CW\*(C`main\*(C'\fR; they are
+also exempt from \f(CW\*(C`strict \*(Aqvars\*(Aq\*(C'\fR errors.  A few other names are also
+exempt in these ways:
+.PP
+.Vb 5
+\&    ENV      STDIN
+\&    INC      STDOUT
+\&    ARGV     STDERR
+\&    ARGVOUT
+\&    SIG
+.Ve
+.PP
+In particular, the special \f(CW\*(C`${^_XYZ}\*(C'\fR variables are always taken
+to be in package \f(CW\*(C`main\*(C'\fR, regardless of any \f(CW\*(C`package\*(C'\fR declarations
+presently in scope.
+.SH "SPECIAL VARIABLES"
+.IX Header "SPECIAL VARIABLES"
+The following names have special meaning to Perl.  Most punctuation
+names have reasonable mnemonics, or analogs in the shells.
+Nevertheless, if you wish to use long variable names, you need only say:
+.PP
+.Vb 1
+\&    use English;
+.Ve
+.PP
+at the top of your program.  This aliases all the short names to the long
+names in the current package.  Some even have medium names, generally
+borrowed from \fBawk\fR.  For more info, please see English.
+.PP
+Before you continue, note the sort order for variables.  In general, we
+first list the variables in case-insensitive, almost-lexigraphical
+order (ignoring the \f(CW\*(C`{\*(C'\fR or \f(CW\*(C`^\*(C'\fR preceding words, as in \f(CW\*(C`${^UNICODE}\*(C'\fR
+or \f(CW$^T\fR), although \f(CW$_\fR and \f(CW@_\fR move up to the top of the pile.
+For variables with the same identifier, we list it in order of scalar,
+array, hash, and bareword.
+.SS "General Variables"
+.IX Subsection "General Variables"
+.ie n .IP $ARG 8
+.el .IP \f(CW$ARG\fR 8
+.IX Item "$ARG"
+.PD 0
+.ie n .IP $_ 8
+.el .IP \f(CW$_\fR 8
+.IX Xref "$_ $ARG"
+.IX Item "$_"
+.PD
+The default input and pattern-searching space.  The following pairs are
+equivalent:
+.Sp
+.Vb 2
+\&    while (<>) {...}    # equivalent only in while!
+\&    while (defined($_ = <>)) {...}
+\&
+\&    /^Subject:/
+\&    $_ =~ /^Subject:/
+\&
+\&    tr/a\-z/A\-Z/
+\&    $_ =~ tr/a\-z/A\-Z/
+\&
+\&    chomp
+\&    chomp($_)
+.Ve
+.Sp
+Here are the places where Perl will assume \f(CW$_\fR even if you don't use it:
+.RS 8
+.IP \(bu 3
+The following functions use \f(CW$_\fR as a default argument:
+.Sp
+abs, alarm, chomp, chop, chr, chroot,
+cos, defined, eval, evalbytes, exp, fc, glob, hex, int, lc,
+lcfirst, length, log, lstat, mkdir, oct, ord, pos, print, printf,
+quotemeta, readlink, readpipe, ref, require, reverse (in scalar context only),
+rmdir, say, sin, split (for its second
+argument), sqrt, stat, study, uc, ucfirst,
+unlink, unpack.
+.IP \(bu 3
+All file tests (\f(CW\*(C`\-f\*(C'\fR, \f(CW\*(C`\-d\*(C'\fR) except for \f(CW\*(C`\-t\*(C'\fR, which defaults to STDIN.
+See "\-X" in perlfunc
+.IP \(bu 3
+The pattern matching operations \f(CW\*(C`m//\*(C'\fR, \f(CW\*(C`s///\*(C'\fR and \f(CW\*(C`tr///\*(C'\fR (aka \f(CW\*(C`y///\*(C'\fR)
+when used without an \f(CW\*(C`=~\*(C'\fR operator.
+.IP \(bu 3
+The default iterator variable in a \f(CW\*(C`foreach\*(C'\fR loop if no other
+variable is supplied.
+.IP \(bu 3
+The implicit iterator variable in the \f(CWgrep()\fR and \f(CWmap()\fR functions.
+.IP \(bu 3
+The implicit variable of \f(CWgiven()\fR.
+.IP \(bu 3
+The default place to put the next value or input record
+when a \f(CW\*(C`<FH>\*(C'\fR, \f(CW\*(C`readline\*(C'\fR, \f(CW\*(C`readdir\*(C'\fR or \f(CW\*(C`each\*(C'\fR
+operation's result is tested by itself as the sole criterion of a \f(CW\*(C`while\*(C'\fR
+test.  Outside a \f(CW\*(C`while\*(C'\fR test, this will not happen.
+.RE
+.RS 8
+.Sp
+\&\f(CW$_\fR is a global variable.
+.Sp
+However, between perl v5.10.0 and v5.24.0, it could be used lexically by
+writing \f(CW\*(C`my $_\*(C'\fR.  Making \f(CW$_\fR refer to the global \f(CW$_\fR in the same scope
+was then possible with \f(CW\*(C`our $_\*(C'\fR.  This experimental feature was removed and is
+now a fatal error, but you may encounter it in older code.
+.Sp
+Mnemonic: underline is understood in certain operations.
+.RE
+.ie n .IP @ARG 8
+.el .IP \f(CW@ARG\fR 8
+.IX Item "@ARG"
+.PD 0
+.ie n .IP @_ 8
+.el .IP \f(CW@_\fR 8
+.IX Xref "@_ @ARG"
+.IX Item "@_"
+.PD
+Within a subroutine the array \f(CW@_\fR contains the parameters passed to
+that subroutine.  Inside a subroutine, \f(CW@_\fR is the default array for
+the array operators \f(CW\*(C`pop\*(C'\fR and \f(CW\*(C`shift\*(C'\fR.
+.Sp
+See perlsub.
+.ie n .IP $LIST_SEPARATOR 8
+.el .IP \f(CW$LIST_SEPARATOR\fR 8
+.IX Item "$LIST_SEPARATOR"
+.PD 0
+.IP "$""" 8
+.IX Xref "$"" $LIST_SEPARATOR"
+.PD
+When an array or an array slice is interpolated into a double-quoted
+string or a similar context such as \f(CW\*(C`/.../\*(C'\fR, its elements are
+separated by this value.  Default is a space.  For example, this:
+.Sp
+.Vb 1
+\&    print "The array is: @array\en";
+.Ve
+.Sp
+is equivalent to this:
+.Sp
+.Vb 1
+\&    print "The array is: " . join($", @array) . "\en";
+.Ve
+.Sp
+Mnemonic: works in double-quoted context.
+.ie n .IP $PROCESS_ID 8
+.el .IP \f(CW$PROCESS_ID\fR 8
+.IX Item "$PROCESS_ID"
+.PD 0
+.ie n .IP $PID 8
+.el .IP \f(CW$PID\fR 8
+.IX Item "$PID"
+.IP $$ 8
+.IX Xref "$$ $PID $PROCESS_ID"
+.PD
+The process number of the Perl running this script.  Though you \fIcan\fR set
+this variable, doing so is generally discouraged, although it can be
+invaluable for some testing purposes.  It will be reset automatically
+across \f(CWfork()\fR calls.
+.Sp
+Note for Linux and Debian GNU/kFreeBSD users: Before Perl v5.16.0 perl
+would emulate POSIX semantics on Linux systems using LinuxThreads, a
+partial implementation of POSIX Threads that has since been superseded
+by the Native POSIX Thread Library (NPTL).
+.Sp
+LinuxThreads is now obsolete on Linux, and caching \f(CWgetpid()\fR
+like this made embedding perl unnecessarily complex (since you'd have
+to manually update the value of $$), so now \f(CW$$\fR and \f(CWgetppid()\fR
+will always return the same values as the underlying C library.
+.Sp
+Debian GNU/kFreeBSD systems also used LinuxThreads up until and
+including the 6.0 release, but after that moved to FreeBSD thread
+semantics, which are POSIX-like.
+.Sp
+To see if your system is affected by this discrepancy check if
+\&\f(CW\*(C`getconf GNU_LIBPTHREAD_VERSION | grep \-q NPTL\*(C'\fR returns a false
+value.  NTPL threads preserve the POSIX semantics.
+.Sp
+Mnemonic: same as shells.
+.ie n .IP $PROGRAM_NAME 8
+.el .IP \f(CW$PROGRAM_NAME\fR 8
+.IX Item "$PROGRAM_NAME"
+.PD 0
+.ie n .IP $0 8
+.el .IP \f(CW$0\fR 8
+.IX Xref "$0 $PROGRAM_NAME"
+.IX Item "$0"
+.PD
+Contains the name of the program being executed.
+.Sp
+On some (but not all) operating systems assigning to \f(CW$0\fR modifies
+the argument area that the \f(CW\*(C`ps\*(C'\fR program sees.  On some platforms you
+may have to use special \f(CW\*(C`ps\*(C'\fR options or a different \f(CW\*(C`ps\*(C'\fR to see the
+changes.  Modifying the \f(CW$0\fR is more useful as a way of indicating the
+current program state than it is for hiding the program you're
+running.
+.Sp
+Note that there are platform-specific limitations on the maximum
+length of \f(CW$0\fR.  In the most extreme case it may be limited to the
+space occupied by the original \f(CW$0\fR.
+.Sp
+In some platforms there may be arbitrary amount of padding, for
+example space characters, after the modified name as shown by \f(CW\*(C`ps\*(C'\fR.
+In some platforms this padding may extend all the way to the original
+length of the argument area, no matter what you do (this is the case
+for example with Linux 2.2).
+.Sp
+Note for BSD users: setting \f(CW$0\fR does not completely remove "perl"
+from the \fBps\fR\|(1) output.  For example, setting \f(CW$0\fR to \f(CW"foobar"\fR may
+result in \f(CW"perl: foobar (perl)"\fR (whether both the \f(CW"perl: "\fR prefix
+and the " (perl)" suffix are shown depends on your exact BSD variant
+and version).  This is an operating system feature, Perl cannot help it.
+.Sp
+In multithreaded scripts Perl coordinates the threads so that any
+thread may modify its copy of the \f(CW$0\fR and the change becomes visible
+to \fBps\fR\|(1) (assuming the operating system plays along).  Note that
+the view of \f(CW$0\fR the other threads have will not change since they
+have their own copies of it.
+.Sp
+If the program has been given to perl via the switches \f(CW\*(C`\-e\*(C'\fR or \f(CW\*(C`\-E\*(C'\fR,
+\&\f(CW$0\fR will contain the string \f(CW"\-e"\fR.
+.Sp
+On Linux as of perl v5.14.0 the legacy process name will be set with
+\&\f(CWprctl(2)\fR, in addition to altering the POSIX name via \f(CW\*(C`argv[0]\*(C'\fR as
+perl has done since version 4.000.  Now system utilities that read the
+legacy process name such as ps, top and killall will recognize the
+name you set when assigning to \f(CW$0\fR.  The string you supply will be
+cut off at 16 bytes, this is a limitation imposed by Linux.
+.Sp
+Wide characters are invalid in \f(CW$0\fR values. For historical reasons,
+though, Perl accepts them and encodes them to UTF\-8. When this
+happens a wide-character warning is triggered.
+.Sp
+Mnemonic: same as \fBsh\fR and \fBksh\fR.
+.ie n .IP $REAL_GROUP_ID 8
+.el .IP \f(CW$REAL_GROUP_ID\fR 8
+.IX Item "$REAL_GROUP_ID"
+.PD 0
+.ie n .IP $GID 8
+.el .IP \f(CW$GID\fR 8
+.IX Item "$GID"
+.IP $( 8
+.IX Xref "$( $GID $REAL_GROUP_ID"
+.PD
+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
+\&\f(CWgetgid()\fR, and the subsequent ones by \f(CWgetgroups()\fR, one of which may be
+the same as the first number.
+.Sp
+However, a value assigned to \f(CW$(\fR must be a single number used to
+set the real gid.  So the value given by \f(CW$(\fR should \fInot\fR be assigned
+back to \f(CW$(\fR without being forced numeric, such as by adding zero.  Note
+that this is different to the effective gid (\f(CW$)\fR) which does take a
+list.
+.Sp
+You can change both the real gid and the effective gid at the same
+time by using \f(CWPOSIX::setgid()\fR.  Changes
+to \f(CW$(\fR require a check to \f(CW$!\fR
+to detect any possible errors after an attempted change.
+.Sp
+Mnemonic: parentheses are used to \fIgroup\fR things.  The real gid is the
+group you \fIleft\fR, if you're running setgid.
+.ie n .IP $EFFECTIVE_GROUP_ID 8
+.el .IP \f(CW$EFFECTIVE_GROUP_ID\fR 8
+.IX Item "$EFFECTIVE_GROUP_ID"
+.PD 0
+.ie n .IP $EGID 8
+.el .IP \f(CW$EGID\fR 8
+.IX Item "$EGID"
+.IP $) 8
+.IX Xref "$) $EGID $EFFECTIVE_GROUP_ID"
+.PD
+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 \f(CWgetegid()\fR, and the subsequent ones by \f(CWgetgroups()\fR,
+one of which may be the same as the first number.
+.Sp
+Similarly, a value assigned to \f(CW$)\fR must also be a space-separated
+list of numbers.  The first number sets the effective gid, and
+the rest (if any) are passed to \f(CWsetgroups()\fR.  To get the effect of an
+empty list for \f(CWsetgroups()\fR, just repeat the new effective gid; that is,
+to force an effective gid of 5 and an effectively empty \f(CWsetgroups()\fR
+list, say \f(CW\*(C` $) = "5 5" \*(C'\fR.
+.Sp
+You can change both the effective gid and the real gid at the same
+time by using \f(CWPOSIX::setgid()\fR (use only a single numeric argument).
+Changes to \f(CW$)\fR require a check to \f(CW$!\fR to detect any possible errors
+after an attempted change.
+.Sp
+\&\f(CW$<\fR, \f(CW$>\fR, \f(CW$(\fR and \f(CW$)\fR can be set only on
+machines that support the corresponding \fIset[re][ug]\fR\f(BIid()\fR routine.  \f(CW$(\fR
+and \f(CW$)\fR can be swapped only on machines supporting \f(CWsetregid()\fR.
+.Sp
+Mnemonic: parentheses are used to \fIgroup\fR things.  The effective gid
+is the group that's \fIright\fR for you, if you're running setgid.
+.ie n .IP $REAL_USER_ID 8
+.el .IP \f(CW$REAL_USER_ID\fR 8
+.IX Item "$REAL_USER_ID"
+.PD 0
+.ie n .IP $UID 8
+.el .IP \f(CW$UID\fR 8
+.IX Item "$UID"
+.IP $< 8
+.IX Xref "$< $UID $REAL_USER_ID"
+.PD
+The real uid of this process.  You can change both the real uid and the
+effective uid at the same time by using \f(CWPOSIX::setuid()\fR.  Since
+changes to \f(CW$<\fR require a system call, check \f(CW$!\fR after a change
+attempt to detect any possible errors.
+.Sp
+Mnemonic: it's the uid you came \fIfrom\fR, if you're running setuid.
+.ie n .IP $EFFECTIVE_USER_ID 8
+.el .IP \f(CW$EFFECTIVE_USER_ID\fR 8
+.IX Item "$EFFECTIVE_USER_ID"
+.PD 0
+.ie n .IP $EUID 8
+.el .IP \f(CW$EUID\fR 8
+.IX Item "$EUID"
+.IP $> 8
+.IX Xref "$> $EUID $EFFECTIVE_USER_ID"
+.PD
+The effective uid of this process.  For example:
+.Sp
+.Vb 2
+\&    $< = $>;            # set real to effective uid
+\&    ($<,$>) = ($>,$<);  # swap real and effective uids
+.Ve
+.Sp
+You can change both the effective uid and the real uid at the same
+time by using \f(CWPOSIX::setuid()\fR.  Changes to \f(CW$>\fR require a check
+to \f(CW$!\fR to detect any possible errors after an attempted change.
+.Sp
+\&\f(CW$<\fR and \f(CW$>\fR can be swapped only on machines
+supporting \f(CWsetreuid()\fR.
+.Sp
+Mnemonic: it's the uid you went \fIto\fR, if you're running setuid.
+.ie n .IP $SUBSCRIPT_SEPARATOR 8
+.el .IP \f(CW$SUBSCRIPT_SEPARATOR\fR 8
+.IX Item "$SUBSCRIPT_SEPARATOR"
+.PD 0
+.ie n .IP $SUBSEP 8
+.el .IP \f(CW$SUBSEP\fR 8
+.IX Item "$SUBSEP"
+.IP $; 8
+.IX Xref "$; $SUBSEP SUBSCRIPT_SEPARATOR"
+.PD
+The subscript separator for multidimensional array emulation.  If you
+refer to a hash element as
+.Sp
+.Vb 1
+\&    $foo{$x,$y,$z}
+.Ve
+.Sp
+it really means
+.Sp
+.Vb 1
+\&    $foo{join($;, $x, $y, $z)}
+.Ve
+.Sp
+But don't put
+.Sp
+.Vb 1
+\&    @foo{$x,$y,$z}     # a slice\-\-note the @
+.Ve
+.Sp
+which means
+.Sp
+.Vb 1
+\&    ($foo{$x},$foo{$y},$foo{$z})
+.Ve
+.Sp
+Default is "\e034", the same as SUBSEP in \fBawk\fR.  If your keys contain
+binary data there might not be any safe value for \f(CW$;\fR.
+.Sp
+Consider using "real" multidimensional arrays as described
+in perllol.
+.Sp
+Mnemonic: comma (the syntactic subscript separator) is a semi-semicolon.
+.ie n .IP $a 8
+.el .IP \f(CW$a\fR 8
+.IX Item "$a"
+.PD 0
+.ie n .IP $b 8
+.el .IP \f(CW$b\fR 8
+.IX Xref "$a $b"
+.IX Item "$b"
+.PD
+Special package variables when using \f(CWsort()\fR, see "sort" in perlfunc.
+Because of this specialness \f(CW$a\fR and \f(CW$b\fR don't need to be declared
+(using \f(CW\*(C`use vars\*(C'\fR, or \f(CWour()\fR) even when using the \f(CW\*(C`strict \*(Aqvars\*(Aq\*(C'\fR
+pragma.  Don't lexicalize them with \f(CW\*(C`my $a\*(C'\fR or \f(CW\*(C`my $b\*(C'\fR if you want to
+be able to use them in the \f(CWsort()\fR comparison block or function.
+.ie n .IP %ENV 8
+.el .IP \f(CW%ENV\fR 8
+.IX Xref "%ENV"
+.IX Item "%ENV"
+The hash \f(CW%ENV\fR contains your current environment.  Setting a
+value in \f(CW\*(C`ENV\*(C'\fR changes the environment for any child processes
+you subsequently \f(CWfork()\fR off.
+.Sp
+As of v5.18.0, both keys and values stored in \f(CW%ENV\fR are stringified.
+.Sp
+.Vb 7
+\&    my $foo = 1;
+\&    $ENV{\*(Aqbar\*(Aq} = \e$foo;
+\&    if( ref $ENV{\*(Aqbar\*(Aq} ) {
+\&        say "Pre 5.18.0 Behaviour";
+\&    } else {
+\&        say "Post 5.18.0 Behaviour";
+\&    }
+.Ve
+.Sp
+Previously, only child processes received stringified values:
+.Sp
+.Vb 2
+\&    my $foo = 1;
+\&    $ENV{\*(Aqbar\*(Aq} = \e$foo;
+\&
+\&    # Always printed \*(Aqnon ref\*(Aq
+\&    system($^X, \*(Aq\-e\*(Aq,
+\&           q/print ( ref $ENV{\*(Aqbar\*(Aq}  ? \*(Aqref\*(Aq : \*(Aqnon ref\*(Aq ) /);
+.Ve
+.Sp
+This happens because you can't really share arbitrary data structures with
+foreign processes.
+.ie n .IP $OLD_PERL_VERSION 8
+.el .IP \f(CW$OLD_PERL_VERSION\fR 8
+.IX Item "$OLD_PERL_VERSION"
+.PD 0
+.IP $] 8
+.IX Xref "$] $OLD_PERL_VERSION"
+.PD
+The revision, version, and subversion of the Perl interpreter, represented
+as a decimal of the form 5.XXXYYY, where XXX is the version / 1e3 and YYY
+is the subversion / 1e6.  For example, Perl v5.10.1 would be "5.010001".
+.Sp
+This variable can be used to determine whether the Perl interpreter
+executing a script is in the right range of versions:
+.Sp
+.Vb 1
+\&    warn "No PerlIO!\en" if "$]" < 5.008;
+.Ve
+.Sp
+When comparing \f(CW$]\fR, numeric comparison operators should be used, but the
+variable should be stringified first to avoid issues where its original
+numeric value is inaccurate.
+.Sp
+See also the documentation of \f(CW\*(C`use VERSION\*(C'\fR and
+\&\f(CW\*(C`require VERSION\*(C'\fR for a convenient way to fail if the running Perl
+interpreter is too old.
+.Sp
+See "$^V" for a representation of the Perl version as a version
+object, which allows more flexible string comparisons.
+.Sp
+The main advantage of \f(CW$]\fR over \f(CW$^V\fR is that it works the same on any
+version of Perl.  The disadvantages are that it can't easily be compared
+to versions in other formats (e.g. literal v\-strings, "v1.2.3" or
+version objects) and numeric comparisons are subject to the binary
+floating point representation; it's good for numeric literal version
+checks and bad for comparing to a variable that hasn't been
+sanity-checked.
+.Sp
+The \f(CW$OLD_PERL_VERSION\fR form was added in Perl v5.20.0 for historical
+reasons but its use is discouraged. (If your reason to use \f(CW$]\fR is to
+run code on old perls then referring to it as \f(CW$OLD_PERL_VERSION\fR would
+be self-defeating.)
+.Sp
+Mnemonic: Is this version of perl in the right bracket?
+.ie n .IP $SYSTEM_FD_MAX 8
+.el .IP \f(CW$SYSTEM_FD_MAX\fR 8
+.IX Item "$SYSTEM_FD_MAX"
+.PD 0
+.IP $^F 8
+.IX Xref "$^F $SYSTEM_FD_MAX"
+.IX Item "$^F"
+.PD
+The maximum system file descriptor, ordinarily 2.  System file
+descriptors are passed to \f(CWexec()\fRed processes, while higher file
+descriptors are not.  Also, during an
+\&\f(CWopen()\fR, system file descriptors are
+preserved even if the \f(CWopen()\fR fails (ordinary file descriptors are
+closed before the \f(CWopen()\fR is attempted).  The close-on-exec
+status of a file descriptor will be decided according to the value of
+\&\f(CW$^F\fR when the corresponding file, pipe, or socket was opened, not the
+time of the \f(CWexec()\fR.
+.ie n .IP @F 8
+.el .IP \f(CW@F\fR 8
+.IX Xref "@F"
+.IX Item "@F"
+The array \f(CW@F\fR contains the fields of each line read in when autosplit
+mode is turned on.  See perlrun for the \fB\-a\fR switch.  This
+array is package-specific, and must be declared or given a full package
+name if not in package main when running under \f(CW\*(C`strict \*(Aqvars\*(Aq\*(C'\fR.
+.ie n .IP @INC 8
+.el .IP \f(CW@INC\fR 8
+.IX Xref "@INC"
+.IX Item "@INC"
+The array \f(CW@INC\fR contains the list of places that the \f(CW\*(C`do EXPR\*(C'\fR,
+\&\f(CW\*(C`require\*(C'\fR, or \f(CW\*(C`use\*(C'\fR constructs look for their library files.  It
+initially consists of the arguments to any \fB\-I\fR command-line
+switches, followed by the default Perl library, probably
+\&\fI/usr/local/lib/perl\fR.
+Prior to Perl 5.26, \f(CW\*(C`.\*(C'\fR \-which represents the current directory, was included
+in \f(CW@INC\fR; it has been removed. This change in behavior is documented
+in \f(CW\*(C`PERL_USE_UNSAFE_INC\*(C'\fR and it is
+not recommended that \f(CW\*(C`.\*(C'\fR be re-added to \f(CW@INC\fR.
+If you need to modify \f(CW@INC\fR at runtime, you should use the \f(CW\*(C`use lib\*(C'\fR pragma
+to get the machine-dependent library properly loaded as well:
+.Sp
+.Vb 2
+\&    use lib \*(Aq/mypath/libdir/\*(Aq;
+\&    use SomeMod;
+.Ve
+.Sp
+You can also insert hooks into the file inclusion system by putting Perl
+code directly into \f(CW@INC\fR.  Those hooks may be subroutine references,
+array references or blessed objects.  See "require" in perlfunc for details.
+.ie n .IP %INC 8
+.el .IP \f(CW%INC\fR 8
+.IX Xref "%INC"
+.IX Item "%INC"
+The hash \f(CW%INC\fR contains entries for each filename included via the
+\&\f(CW\*(C`do\*(C'\fR, \f(CW\*(C`require\*(C'\fR, or \f(CW\*(C`use\*(C'\fR operators.  The key is the filename
+you specified (with module names converted to pathnames), and the
+value is the location of the file found.  The \f(CW\*(C`require\*(C'\fR
+operator uses this hash to determine whether a particular file has
+already been included.
+.Sp
+If the file was loaded via a hook (e.g. a subroutine reference, see
+"require" in perlfunc for a description of these hooks), this hook is
+by default inserted into \f(CW%INC\fR in place of a filename.  Note, however,
+that the hook may have set the \f(CW%INC\fR entry by itself to provide some more
+specific info.
+.ie n .IP $INC 8
+.el .IP \f(CW$INC\fR 8
+.IX Xref "$INC"
+.IX Item "$INC"
+As of 5.37.7 when an \f(CW@INC\fR hook is executed the index of the \f(CW@INC\fR
+array that holds the hook will be localized into the \f(CW$INC\fR variable.
+When the hook returns the integer successor of its value will be used to
+determine the next index in \f(CW@INC\fR that will be checked, thus if it is
+set to \-1 (or \f(CW\*(C`undef\*(C'\fR) the traversal over the \f(CW@INC\fR array will be
+restarted from its beginning.
+.Sp
+Normally traversal through the \f(CW@INC\fR array is from beginning to end
+(\f(CW\*(C`0 .. $#INC\*(C'\fR), and if the \f(CW@INC\fR array is modified by the hook the
+iterator may be left in a state where newly added entries are skipped.
+Changing this value allows an \f(CW@INC\fR hook to rewrite the \f(CW@INC\fR array
+and tell Perl where to continue afterwards. See "require" in perlfunc for
+details on \f(CW@INC\fR hooks.
+.ie n .IP $INPLACE_EDIT 8
+.el .IP \f(CW$INPLACE_EDIT\fR 8
+.IX Item "$INPLACE_EDIT"
+.PD 0
+.IP $^I 8
+.IX Xref "$^I $INPLACE_EDIT"
+.IX Item "$^I"
+.PD
+The current value of the inplace-edit extension.  Use \f(CW\*(C`undef\*(C'\fR to disable
+inplace editing.
+.Sp
+Mnemonic: value of \fB\-i\fR switch.
+.ie n .IP @ISA 8
+.el .IP \f(CW@ISA\fR 8
+.IX Xref "@ISA"
+.IX Item "@ISA"
+Each package contains a special array called \f(CW@ISA\fR which contains a list
+of that class's parent classes, if any. This array is simply a list of
+scalars, each of which is a string that corresponds to a package name. The
+array is examined when Perl does method resolution, which is covered in
+perlobj.
+.Sp
+To load packages while adding them to \f(CW@ISA\fR, see the parent pragma. The
+discouraged base pragma does this as well, but should not be used except
+when compatibility with the discouraged fields pragma is required.
+.IP $^M 8
+.IX Xref "$^M"
+.IX Item "$^M"
+By default, running out of memory is an untrappable, fatal error.
+However, if suitably built, Perl can use the contents of \f(CW$^M\fR
+as an emergency memory pool after \f(CWdie()\fRing.  Suppose that your Perl
+were compiled with \f(CW\*(C`\-DPERL_EMERGENCY_SBRK\*(C'\fR and used Perl's malloc.
+Then
+.Sp
+.Vb 1
+\&    $^M = \*(Aqa\*(Aq x (1 << 16);
+.Ve
+.Sp
+would allocate a 64K buffer for use in an emergency.  See the
+INSTALL file in the Perl distribution for information on how to
+add custom C compilation flags when compiling perl.  To discourage casual
+use of this advanced feature, there is no English long name for
+this variable.
+.Sp
+This variable was added in Perl 5.004.
+.IP ${^MAX_NESTED_EVAL_BEGIN_BLOCKS} 8
+.IX Item "${^MAX_NESTED_EVAL_BEGIN_BLOCKS}"
+This variable determines the maximum number \f(CW\*(C`eval EXPR\*(C'\fR/\f(CW\*(C`BEGIN\*(C'\fR or
+\&\f(CW\*(C`require\*(C'\fR/\f(CW\*(C`BEGIN\*(C'\fR block nesting that is allowed. This means it also
+controls the maximum nesting of \f(CW\*(C`use\*(C'\fR statements as well.
+.Sp
+The default of 1000 should be sufficiently large for normal working
+purposes, and if you must raise it then you should be conservative
+with your choice or you may encounter segfaults from exhaustion of
+the C stack. It seems unlikely that real code has a use depth above
+1000, but we have left this configurable just in case.
+.Sp
+When set to \f(CW0\fR then \f(CW\*(C`BEGIN\*(C'\fR blocks inside of \f(CW\*(C`eval EXPR\*(C'\fR or
+\&\f(CW\*(C`require EXPR\*(C'\fR are forbidden entirely and will trigger an exception
+which will terminate the compilation and in the case of \f(CW\*(C`require\*(C'\fR
+will throw an exception, or in the case of \f(CW\*(C`eval\*(C'\fR return the error in
+\&\f(CW$@\fR as usual.
+.Sp
+Consider the code
+.Sp
+.Vb 1
+\& perl \-le\*(Aqsub f { eval "BEGIN { f() }"; } f()\*(Aq
+.Ve
+.Sp
+each invocation of \f(CWf()\fR will consume considerable C stack, and this
+variable is used to cause code like this to die instead of exhausting
+the C stack and triggering a segfault. Needless to say code like this is
+unusual, it is unlikely you will actually need to raise the setting.
+However it may be useful to set it to 0 for a limited time period to
+prevent BEGIN{} blocks from being executed during an \f(CW\*(C`eval EXPR\*(C'\fR.
+.Sp
+Note that setting this to 1 would NOT affect code like this:
+.Sp
+.Vb 1
+\&    BEGIN { $n += 1; BEGIN { $n += 2; BEGIN { $n += 4 } } }
+.Ve
+.Sp
+The reason is that BEGIN blocks are executed immediately after they are
+completed, thus the innermost will execute before the ones which contain
+it have even finished compiling, and the depth will not go above 1. In
+fact the above code is equivalent to
+.Sp
+.Vb 3
+\&    BEGIN { $n+=4 }
+\&    BEGIN { $n+=2 }
+\&    BEGIN { $n+=1 }
+.Ve
+.Sp
+which makes it obvious why a ${^MAX_EVAL_BEGIN_DEPTH} of 1 would not
+block this code.
+.Sp
+Only \f(CW\*(C`BEGIN\*(C'\fR's executed inside of an \f(CW\*(C`eval\*(C'\fR or \f(CW\*(C`require\*(C'\fR (possibly via
+\&\f(CW\*(C`use\*(C'\fR) are affected.
+.ie n .IP $OSNAME 8
+.el .IP \f(CW$OSNAME\fR 8
+.IX Item "$OSNAME"
+.PD 0
+.IP $^O 8
+.IX Xref "$^O $OSNAME"
+.IX Item "$^O"
+.PD
+The name of the operating system under which this copy of Perl was
+built, as determined during the configuration process.  For examples
+see "PLATFORMS" in perlport.
+.Sp
+The value is identical to \f(CW$Config{\*(Aqosname\*(Aq}\fR.  See also Config
+and the \fB\-V\fR command-line switch documented in perlrun.
+.Sp
+In Windows platforms, \f(CW$^O\fR is not very helpful: since it is always
+\&\f(CW\*(C`MSWin32\*(C'\fR, it doesn't tell the difference between
+95/98/ME/NT/2000/XP/CE/.NET.  Use \f(CWWin32::GetOSName()\fR or
+\&\fBWin32::GetOSVersion()\fR (see Win32 and perlport) to distinguish
+between the variants.
+.Sp
+This variable was added in Perl 5.003.
+.ie n .IP %SIG 8
+.el .IP \f(CW%SIG\fR 8
+.IX Xref "%SIG"
+.IX Item "%SIG"
+The hash \f(CW%SIG\fR contains signal handlers for signals.  For example:
+.Sp
+.Vb 6
+\&    sub handler {   # 1st argument is signal name
+\&        my($sig) = @_;
+\&        print "Caught a SIG$sig\-\-shutting down\en";
+\&        close(LOG);
+\&        exit(0);
+\&    }
+\&
+\&    $SIG{\*(AqINT\*(Aq}  = \e&handler;
+\&    $SIG{\*(AqQUIT\*(Aq} = \e&handler;
+\&    ...
+\&    $SIG{\*(AqINT\*(Aq}  = \*(AqDEFAULT\*(Aq;   # restore default action
+\&    $SIG{\*(AqQUIT\*(Aq} = \*(AqIGNORE\*(Aq;    # ignore SIGQUIT
+.Ve
+.Sp
+Using a value of \f(CW\*(AqIGNORE\*(Aq\fR usually has the effect of ignoring the
+signal, except for the \f(CW\*(C`CHLD\*(C'\fR signal.  See perlipc for more about
+this special case.  Using an empty string or \f(CW\*(C`undef\*(C'\fR as the value has
+the same effect as \f(CW\*(AqDEFAULT\*(Aq\fR.
+.Sp
+Here are some other examples:
+.Sp
+.Vb 7
+\&    $SIG{"PIPE"} = "Plumber";   # assumes main::Plumber (not
+\&                                # recommended)
+\&    $SIG{"PIPE"} = \e&Plumber;   # just fine; assume current
+\&                                # Plumber
+\&    $SIG{"PIPE"} = *Plumber;    # somewhat esoteric
+\&    $SIG{"PIPE"} = Plumber();   # oops, what did Plumber()
+\&                                # return??
+.Ve
+.Sp
+Be sure not to use a bareword as the name of a signal handler,
+lest you inadvertently call it.
+.Sp
+Using a string that doesn't correspond to any existing function or a
+glob that doesn't contain a code slot is equivalent to \f(CW\*(AqIGNORE\*(Aq\fR,
+but a warning is emitted when the handler is being called (the warning
+is not emitted for the internal hooks described below).
+.Sp
+If your system has the \f(CWsigaction()\fR function then signal handlers
+are installed using it.  This means you get reliable signal handling.
+.Sp
+The default delivery policy of signals changed in Perl v5.8.0 from
+immediate (also known as "unsafe") to deferred, also known as "safe
+signals".  See perlipc for more information.
+.Sp
+Certain internal hooks can be also set using the \f(CW%SIG\fR hash.  The
+routine indicated by \f(CW$SIG{_\|_WARN_\|_}\fR is called when a warning
+message is about to be printed.  The warning message is passed as the
+first argument.  The presence of a \f(CW\*(C`_\|_WARN_\|_\*(C'\fR hook causes the
+ordinary printing of warnings to \f(CW\*(C`STDERR\*(C'\fR to be suppressed.  You can
+use this to save warnings in a variable, or turn warnings into fatal
+errors, like this:
+.Sp
+.Vb 2
+\&    local $SIG{_\|_WARN_\|_} = sub { die $_[0] };
+\&    eval $proggie;
+.Ve
+.Sp
+As the \f(CW\*(AqIGNORE\*(Aq\fR hook is not supported by \f(CW\*(C`_\|_WARN_\|_\*(C'\fR, its effect is
+the same as using \f(CW\*(AqDEFAULT\*(Aq\fR.  You can disable warnings using the
+empty subroutine:
+.Sp
+.Vb 1
+\&    local $SIG{_\|_WARN_\|_} = sub {};
+.Ve
+.Sp
+The routine indicated by \f(CW$SIG{_\|_DIE_\|_}\fR is called when a fatal
+exception is about to be thrown.  The error message is passed as the
+first argument.  When a \f(CW\*(C`_\|_DIE_\|_\*(C'\fR 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 \f(CW\*(C`goto &sub\*(C'\fR, a loop exit,
+or a \f(CWdie()\fR.  The \f(CW\*(C`_\|_DIE_\|_\*(C'\fR handler is explicitly disabled during
+the call, so that you can die from a \f(CW\*(C`_\|_DIE_\|_\*(C'\fR handler.  Similarly
+for \f(CW\*(C`_\|_WARN_\|_\*(C'\fR.
+.Sp
+The \f(CW$SIG{_\|_DIE_\|_}\fR hook is called even inside an \f(CWeval()\fR. It was
+never intended to happen this way, but an implementation glitch made
+this possible. This used to be deprecated, as it allowed strange action
+at a distance like rewriting a pending exception in \f(CW$@\fR. Plans to
+rectify this have been scrapped, as users found that rewriting a
+pending exception is actually a useful feature, and not a bug.
+.Sp
+The \f(CW$SIG{_\|_DIE_\|_}\fR doesn't support \f(CW\*(AqIGNORE\*(Aq\fR; it has the same
+effect as \f(CW\*(AqDEFAULT\*(Aq\fR.
+.Sp
+\&\f(CW\*(C`_\|_DIE_\|_\*(C'\fR/\f(CW\*(C`_\|_WARN_\|_\*(C'\fR 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 warnings or errors that result from parsing
+Perl should be used with extreme caution, like this:
+.Sp
+.Vb 5
+\&    require Carp if defined $^S;
+\&    Carp::confess("Something wrong") if defined &Carp::confess;
+\&    die "Something wrong, but could not load Carp to give "
+\&      . "backtrace...\en\et"
+\&      . "To see backtrace try starting Perl with \-MCarp switch";
+.Ve
+.Sp
+Here the first line will load \f(CW\*(C`Carp\*(C'\fR \fIunless\fR it is the parser who
+called the handler.  The second line will print backtrace and die if
+\&\f(CW\*(C`Carp\*(C'\fR was available.  The third line will be executed only if \f(CW\*(C`Carp\*(C'\fR was
+not available.
+.Sp
+Having to even think about the \f(CW$^S\fR variable in your exception
+handlers is simply wrong.  \f(CW$SIG{_\|_DIE_\|_}\fR as currently implemented
+invites grievous and difficult to track down errors.  Avoid it
+and use an \f(CW\*(C`END{}\*(C'\fR or CORE::GLOBAL::die override instead.
+.Sp
+See "die" in perlfunc, "warn" in perlfunc, "eval" in perlfunc, and
+warnings for additional information.
+.IP %{^HOOK} 8
+.IX Xref "%{^HOOK}"
+.IX Item "%{^HOOK}"
+This hash contains coderefs which are called when various perl keywords
+which are hard or impossible to wrap are called. The keys of this hash
+are named after the keyword that is being hooked, followed by two
+underbars and then a phase term; either "before" or "after".
+.Sp
+Perl will throw an error if you attempt modify a key which is not
+documented to exist, or if you attempt to store anything other than a
+code reference or undef in the hash.  If you wish to use an object to
+implement a hook you can use currying to embed the object into an
+anonymous code reference.
+.Sp
+Currently there is only one keyword which can be hooked, \f(CW\*(C`require\*(C'\fR, but
+it is expected that in future releases there will be additional keywords
+with hook support.
+.RS 8
+.IP require_\|_before 4
+.IX Item "require__before"
+The routine indicated by \f(CW\*(C`${^HOOK}{require_\|_before}\*(C'\fR is called by
+\&\f(CW\*(C`require\*(C'\fR \fBbefore\fR it checks \f(CW%INC\fR, looks up \f(CW@INC\fR, calls INC
+hooks, or compiles any code.  It is called with a single argument, the
+filename for the item being required (package names are converted to
+paths).  It may alter this filename to change what file is loaded.  If
+the hook dies during execution then it will block the require from executing.
+.Sp
+In order to make it easy to perform an action with shared state both
+before and after the require keyword was executed the \f(CW\*(C`require_\|_before\*(C'\fR
+hook may return a "post-action" coderef which will in turn be executed when
+the \f(CW\*(C`require\*(C'\fR completes.  This coderef will be executed regardless as to
+whether the require completed succesfully or threw an exception.  It will
+be called with the filename that was required.  You can check \f(CW%INC\fR to
+determine if the require was successful.  Any other return from the
+\&\f(CW\*(C`require_\|_before\*(C'\fR hook will be silently ignored.
+.Sp
+\&\f(CW\*(C`require_\|_before\*(C'\fR hooks are called in FIFO order, and if the hook
+returns a code reference those code references will be called in FILO
+order.  In other words if A requires B requires C, then
+\&\f(CW\*(C`require_\|_before\*(C'\fR will be called first for A, then B and then C, and
+the post-action code reference will executed first for C, then B and
+then finally A.
+.Sp
+Well behaved code should ensure that when setting up a
+\&\f(CW\*(C`require_\|_before\*(C'\fR hook that any prior installed hook will be called,
+and that their return value, if a code reference, will be called as
+well.  See "require" in perlfunc for an example implementation.
+.IP require_\|_after 4
+.IX Item "require__after"
+The routine indicated by \f(CW\*(C`${^HOOK}{require_\|_after}\*(C'\fR is called by
+\&\f(CW\*(C`require\*(C'\fR \fBafter\fR the require completes.  It is called with a single
+argument, the filename for the item being required (package names are
+converted to paths).  It is executed when the \f(CW\*(C`require\*(C'\fR completes,
+either via exception or via completion of the require statement, and you
+can check \f(CW%INC\fR to determine if the require was successful.
+.Sp
+The \f(CW\*(C`require_\|_after\*(C'\fR hook is called for each required file in FILO
+order. In other words if A requires B requires C, then \f(CW\*(C`require_\|_after\*(C'\fR
+will be called first for C, then B and then A.
+.RE
+.RS 8
+.RE
+.ie n .IP $BASETIME 8
+.el .IP \f(CW$BASETIME\fR 8
+.IX Item "$BASETIME"
+.PD 0
+.IP $^T 8
+.IX Xref "$^T $BASETIME"
+.IX Item "$^T"
+.PD
+The time at which the program began running, in seconds since the
+epoch (beginning of 1970).  The values returned by the \fB\-M\fR, \fB\-A\fR,
+and \fB\-C\fR filetests are based on this value.
+.ie n .IP $PERL_VERSION 8
+.el .IP \f(CW$PERL_VERSION\fR 8
+.IX Item "$PERL_VERSION"
+.PD 0
+.IP $^V 8
+.IX Xref "$^V $PERL_VERSION"
+.IX Item "$^V"
+.PD
+The revision, version, and subversion of the Perl interpreter,
+represented as a version object.
+.Sp
+This variable first appeared in perl v5.6.0; earlier versions of perl
+will see an undefined value.  Before perl v5.10.0 \f(CW$^V\fR was represented
+as a v\-string rather than a version object.
+.Sp
+\&\f(CW$^V\fR can be used to determine whether the Perl interpreter executing
+a script is in the right range of versions.  For example:
+.Sp
+.Vb 1
+\&    warn "Hashes not randomized!\en" if !$^V or $^V lt v5.8.1
+.Ve
+.Sp
+While version objects overload stringification, to portably convert
+\&\f(CW$^V\fR into its string representation, use \f(CWsprintf()\fR's \f(CW"%vd"\fR
+conversion, which works for both v\-strings or version objects:
+.Sp
+.Vb 1
+\&    printf "version is v%vd\en", $^V;  # Perl\*(Aqs version
+.Ve
+.Sp
+See the documentation of \f(CW\*(C`use VERSION\*(C'\fR and \f(CW\*(C`require VERSION\*(C'\fR
+for a convenient way to fail if the running Perl interpreter is too old.
+.Sp
+See also \f(CW"$]"\fR for a decimal representation of the Perl version.
+.Sp
+The main advantage of \f(CW$^V\fR over \f(CW$]\fR is that, for Perl v5.10.0 or
+later, it overloads operators, allowing easy comparison against other
+version representations (e.g. decimal, literal v\-string, "v1.2.3", or
+objects).  The disadvantage is that prior to v5.10.0, it was only a
+literal v\-string, which can't be easily printed or compared, whereas
+the behavior of \f(CW$]\fR is unchanged on all versions of Perl.
+.Sp
+Mnemonic: use ^V for a version object.
+.ie n .IP $EXECUTABLE_NAME 8
+.el .IP \f(CW$EXECUTABLE_NAME\fR 8
+.IX Item "$EXECUTABLE_NAME"
+.PD 0
+.IP $^X 8
+.IX Xref "$^X $EXECUTABLE_NAME"
+.IX Item "$^X"
+.PD
+The name used to execute the current copy of Perl, from C's
+\&\f(CW\*(C`argv[0]\*(C'\fR or (where supported) \fI/proc/self/exe\fR.
+.Sp
+Depending on the host operating system, the value of \f(CW$^X\fR may be
+a relative or absolute pathname of the perl program file, or may
+be the string used to invoke perl but not the pathname of the
+perl program file.  Also, most operating systems permit invoking
+programs that are not in the PATH environment variable, so there
+is no guarantee that the value of \f(CW$^X\fR is in PATH.  For VMS, the
+value may or may not include a version number.
+.Sp
+You usually can use the value of \f(CW$^X\fR to re-invoke an independent
+copy of the same perl that is currently running, e.g.,
+.Sp
+.Vb 1
+\&    @first_run = \`$^X \-le "print int rand 100 for 1..100"\`;
+.Ve
+.Sp
+But recall that not all operating systems support forking or
+capturing of the output of commands, so this complex statement
+may not be portable.
+.Sp
+It is not safe to use the value of \f(CW$^X\fR as a path name of a file,
+as some operating systems that have a mandatory suffix on
+executable files do not require use of the suffix when invoking
+a command.  To convert the value of \f(CW$^X\fR to a path name, use the
+following statements:
+.Sp
+.Vb 7
+\&    # Build up a set of file names (not command names).
+\&    use Config;
+\&    my $this_perl = $^X;
+\&    if ($^O ne \*(AqVMS\*(Aq) {
+\&        $this_perl .= $Config{_exe}
+\&        unless $this_perl =~ m/$Config{_exe}$/i;
+\&    }
+.Ve
+.Sp
+Because many operating systems permit anyone with read access to
+the Perl program file to make a copy of it, patch the copy, and
+then execute the copy, the security-conscious Perl programmer
+should take care to invoke the installed copy of perl, not the
+copy referenced by \f(CW$^X\fR.  The following statements accomplish
+this goal, and produce a pathname that can be invoked as a
+command or referenced as a file.
+.Sp
+.Vb 6
+\&    use Config;
+\&    my $secure_perl_path = $Config{perlpath};
+\&    if ($^O ne \*(AqVMS\*(Aq) {
+\&        $secure_perl_path .= $Config{_exe}
+\&        unless $secure_perl_path =~ m/$Config{_exe}$/i;
+\&    }
+.Ve
+.SS "Variables related to regular expressions"
+.IX Subsection "Variables related to regular expressions"
+Most of the special variables related to regular expressions are side
+effects. Perl sets these variables when it has completed a match
+successfully, so you should check the match result before using them.
+For instance:
+.PP
+.Vb 3
+\&    if( /P(A)TT(ER)N/ ) {
+\&        print "I found $1 and $2\en";
+\&    }
+.Ve
+.PP
+These variables are read-only and behave similarly to a dynamically
+scoped variable, with only a few exceptions which are explicitly
+documented as behaving otherwise.  See the following section for more
+details.
+.PP
+\fIScoping Rules of Regex Variables\fR
+.IX Subsection "Scoping Rules of Regex Variables"
+.PP
+Regular expression variables allow the programmer to access the state of
+the most recent \fIsuccessful\fR regex match in the current dynamic scope.
+.PP
+The variables themselves are global and unscoped, but the data they
+access is scoped similarly to dynamically scoped variables, in that
+every successful match behaves as though it localizes a global state
+object to the current block or file scope.
+(See "Compound Statements" in perlsyn for more details on dynamic
+scoping and the \f(CW\*(C`local\*(C'\fR keyword.)
+.PP
+A \fIsuccessful match\fR includes any successful match performed by the
+search and replace operator \f(CW\*(C`s///\*(C'\fR as well as those performed by the
+\&\f(CW\*(C`m//\*(C'\fR operator.
+.PP
+Consider the following code:
+.PP
+.Vb 7
+\&    my @state;
+\&    sub matchit {
+\&        push @state, $1;            # pushes "baz"
+\&        my $str = shift;
+\&        $str =~ /(zat)/;            # matches "zat"
+\&        push @state, $1;            # pushes "zat"
+\&    }
+\&
+\&    {
+\&        $str = "foo bar baz blorp zat";
+\&        $str =~ /(foo)/;            # matches "foo"
+\&        push @state, $1;            # pushes "foo"
+\&        {
+\&            $str =~ /(pizza)/;      # does NOT match
+\&            push @state, $1;        # pushes "foo"
+\&            $str =~ /(bar)/;        # matches "bar"
+\&            push @state, $1;        # pushes "bar"
+\&            $str =~ /(baz)/;        # matches "baz"
+\&            matchit($str);          # see above
+\&            push @state, $1;        # pushes "baz"
+\&        }
+\&        $str =~ s/noodles/rice/;    # does NOT match
+\&        push @state, $1;            # pushes "foo"
+\&        $str =~ s/(blorp)/zwoop/;   # matches "blorp"
+\&        push @state, $1;            # pushes "blorp"
+\&    }
+\&    # the following prints "foo, foo, bar, baz, zat, baz, foo, blorp"
+\&    print join ",", @state;
+.Ve
+.PP
+Notice that each successful match in the exact same scope overrides the
+match context of the previous successful match, but that unsuccessful
+matches do not. Also note that in an inner nested scope the previous
+state from an outer dynamic scope persists until it has been overriden
+by another successful match, but that when the inner nested scope exits
+whatever match context was in effect before the inner successful match
+is restored when the scope concludes.
+.PP
+It is a known issue that \f(CW\*(C`goto LABEL\*(C'\fR may interact poorly with the
+dynamically scoped match context. This may not be fixable, and is
+considered to be one of many good reasons to avoid \f(CW\*(C`goto LABEL\*(C'\fR.
+.PP
+\fIPerformance issues\fR
+.IX Subsection "Performance issues"
+.PP
+Traditionally in Perl, any use of any of the three variables  \f(CW\*(C`$\`\*(C'\fR, \f(CW$&\fR
+or \f(CW\*(C`$\*(Aq\*(C'\fR (or their \f(CW\*(C`use English\*(C'\fR equivalents) anywhere in the code, caused
+all subsequent successful pattern matches to make a copy of the matched
+string, in case the code might subsequently access one of those variables.
+This imposed a considerable performance penalty across the whole program,
+so generally the use of these variables has been discouraged.
+.PP
+In Perl 5.6.0 the \f(CW\*(C`@\-\*(C'\fR and \f(CW\*(C`@+\*(C'\fR dynamic arrays were introduced that
+supply the indices of successful matches. So you could for example do
+this:
+.PP
+.Vb 1
+\&    $str =~ /pattern/;
+\&
+\&    print $\`, $&, $\*(Aq; # bad: performance hit
+\&
+\&    print             # good: no performance hit
+\&    substr($str, 0,     $\-[0]),
+\&    substr($str, $\-[0], $+[0]\-$\-[0]),
+\&    substr($str, $+[0]);
+.Ve
+.PP
+In Perl 5.10.0 the \f(CW\*(C`/p\*(C'\fR match operator flag and the \f(CW\*(C`${^PREMATCH}\*(C'\fR,
+\&\f(CW\*(C`${^MATCH}\*(C'\fR, and \f(CW\*(C`${^POSTMATCH}\*(C'\fR variables were introduced, that allowed
+you to suffer the penalties only on patterns marked with \f(CW\*(C`/p\*(C'\fR.
+.PP
+In Perl 5.18.0 onwards, perl started noting the presence of each of the
+three variables separately, and only copied that part of the string
+required; so in
+.PP
+.Vb 1
+\&    $\`; $&; "abcdefgh" =~ /d/
+.Ve
+.PP
+perl would only copy the "abcd" part of the string. That could make a big
+difference in something like
+.PP
+.Vb 3
+\&    $str = \*(Aqx\*(Aq x 1_000_000;
+\&    $&; # whoops
+\&    $str =~ /x/g # one char copied a million times, not a million chars
+.Ve
+.PP
+In Perl 5.20.0 a new copy-on-write system was enabled by default, which
+finally fixes most of the performance issues with these three variables, and
+makes them safe to use anywhere.
+.PP
+The \f(CW\*(C`Devel::NYTProf\*(C'\fR and \f(CW\*(C`Devel::FindAmpersand\*(C'\fR modules can help you
+find uses of these problematic match variables in your code.
+.ie n .IP "$<\fIdigits\fR> ($1, $2, ...)" 8
+.el .IP "$<\fIdigits\fR> ($1, \f(CW$2\fR, ...)" 8
+.IX Xref "$1 $2 $3 $\\f(ISdigits\\f(IE"
+.IX Item "$<digits> ($1, $2, ...)"
+Contains the subpattern from the corresponding set of capturing
+parentheses from the last successful pattern match in the current
+dynamic scope. (See "Scoping Rules of Regex Variables".)
+.Sp
+Note there is a distinction between a capture buffer which matches
+the empty string a capture buffer which is optional. Eg, \f(CW\*(C`(x?)\*(C'\fR and
+\&\f(CW\*(C`(x)?\*(C'\fR The latter may be undef, the former not.
+.Sp
+These variables are read-only.
+.Sp
+Mnemonic: like \edigits.
+.IP @{^CAPTURE} 8
+.IX Xref "@{^CAPTURE} @^CAPTURE"
+.IX Item "@{^CAPTURE}"
+An array which exposes the contents of the capture buffers, if any, of
+the last successful pattern match, not counting patterns matched
+in nested blocks that have been exited already.
+.Sp
+Note that the 0 index of @{^CAPTURE} is equivalent to \f(CW$1\fR, the 1 index
+is equivalent to \f(CW$2\fR, etc.
+.Sp
+.Vb 3
+\&    if ("foal"=~/(.)(.)(.)(.)/) {
+\&        print join "\-", @{^CAPTURE};
+\&    }
+.Ve
+.Sp
+should output "f\-o-a-l".
+.Sp
+See also "$<\fIdigits\fR> ($1, \f(CW$2\fR, ...)", "%{^CAPTURE}" and
+"%{^CAPTURE_ALL}".
+.Sp
+Note that unlike most other regex magic variables there is no single
+letter equivalent to \f(CW\*(C`@{^CAPTURE}\*(C'\fR. Also be aware that when
+interpolating subscripts of this array you \fBmust\fR use the demarcated
+variable form, for instance
+.Sp
+.Vb 1
+\&    print "${^CAPTURE[0]}"
+.Ve
+.Sp
+see "Demarcated variable names using braces" in perldata for more
+information on this form and its uses.
+.Sp
+This variable was added in 5.25.7
+.ie n .IP $MATCH 8
+.el .IP \f(CW$MATCH\fR 8
+.IX Item "$MATCH"
+.PD 0
+.IP $& 8
+.IX Xref "$& $MATCH"
+.PD
+The string matched by the last successful pattern match.
+(See "Scoping Rules of Regex Variables".)
+.Sp
+See "Performance issues" above for the serious performance implications
+of using this variable (even once) in your code.
+.Sp
+This variable is read-only, and its value is dynamically scoped.
+.Sp
+Mnemonic: like \f(CW\*(C`&\*(C'\fR in some editors.
+.IP ${^MATCH} 8
+.IX Xref "${^MATCH}"
+.IX Item "${^MATCH}"
+It is only guaranteed to return a defined value when the pattern was
+compiled or executed with the \f(CW\*(C`/p\*(C'\fR modifier.
+.Sp
+This is similar to \f(CW$&\fR (\f(CW$MATCH\fR) except that to use it you must
+use the \f(CW\*(C`/p\*(C'\fR modifier when executing the pattern, and it does not incur
+and performance penalty associated with that variable.
+.Sp
+See "Performance issues" above.
+.Sp
+This variable was added in Perl v5.10.0.
+.Sp
+This variable is read-only, and its value is dynamically scoped.
+.ie n .IP $PREMATCH 8
+.el .IP \f(CW$PREMATCH\fR 8
+.IX Item "$PREMATCH"
+.PD 0
+.IP $` 8
+.IX Xref "$` $PREMATCH"
+.PD
+The string preceding whatever was matched by the last successful
+pattern match. (See "Scoping Rules of Regex Variables").
+.Sp
+See "Performance issues" above for the serious performance implications
+of using this variable (even once) in your code.
+.Sp
+This variable is read-only, and its value is dynamically scoped.
+.Sp
+Mnemonic: \f(CW\*(C`\`\*(C'\fR often precedes a quoted string.
+.IP ${^PREMATCH} 8
+.IX Xref "${^PREMATCH}"
+.IX Item "${^PREMATCH}"
+It is only guaranteed to return a defined value when the pattern was
+executed with the \f(CW\*(C`/p\*(C'\fR modifier.
+.Sp
+This is similar to \f(CW\*(C`$\`\*(C'\fR ($PREMATCH) except that to use it you must
+use the \f(CW\*(C`/p\*(C'\fR modifier when executing the pattern, and it does not incur
+and performance penalty associated with that variable.
+.Sp
+See "Performance issues" above.
+.Sp
+This variable was added in Perl v5.10.0.
+.Sp
+This variable is read-only, and its value is dynamically scoped.
+.ie n .IP $POSTMATCH 8
+.el .IP \f(CW$POSTMATCH\fR 8
+.IX Item "$POSTMATCH"
+.PD 0
+.IP $' 8
+.IX Xref "$' $POSTMATCH @-"
+.PD
+The string following whatever was matched by the last successful
+pattern match. (See "Scoping Rules of Regex Variables"). Example:
+.Sp
+.Vb 3
+\&    local $_ = \*(Aqabcdefghi\*(Aq;
+\&    /def/;
+\&    print "$\`:$&:$\*(Aq\en";       # prints abc:def:ghi
+.Ve
+.Sp
+See "Performance issues" above for the serious performance implications
+of using this variable (even once) in your code.
+.Sp
+This variable is read-only, and its value is dynamically scoped.
+.Sp
+Mnemonic: \f(CW\*(C`\*(Aq\*(C'\fR often follows a quoted string.
+.IP ${^POSTMATCH} 8
+.IX Xref "${^POSTMATCH}"
+.IX Item "${^POSTMATCH}"
+It is only guaranteed to return a defined value when the pattern was
+compiled or executed with the \f(CW\*(C`/p\*(C'\fR modifier.
+.Sp
+This is similar to \f(CW\*(C`$\*(Aq\*(C'\fR (\f(CW$POSTMATCH\fR) except that to use it you must
+use the \f(CW\*(C`/p\*(C'\fR modifier when executing the pattern, and it does not incur
+and performance penalty associated with that variable.
+.Sp
+See "Performance issues" above.
+.Sp
+This variable was added in Perl v5.10.0.
+.Sp
+This variable is read-only, and its value is dynamically scoped.
+.ie n .IP $LAST_PAREN_MATCH 8
+.el .IP \f(CW$LAST_PAREN_MATCH\fR 8
+.IX Item "$LAST_PAREN_MATCH"
+.PD 0
+.IP $+ 8
+.IX Xref "$+ $LAST_PAREN_MATCH"
+.PD
+The text matched by the highest used capture group of the last
+successful search pattern. (See "Scoping Rules of Regex Variables").
+It is logically equivalent to the highest
+numbered capture variable (\f(CW$1\fR, \f(CW$2\fR, ...) which has a defined value.
+.Sp
+This is useful if you don't know which one of a set of alternative patterns
+matched.  For example:
+.Sp
+.Vb 1
+\&    /Version: (.*)|Revision: (.*)/ && ($rev = $+);
+.Ve
+.Sp
+This variable is read-only, and its value is dynamically scoped.
+.Sp
+Mnemonic: be positive and forward looking.
+.ie n .IP $LAST_SUBMATCH_RESULT 8
+.el .IP \f(CW$LAST_SUBMATCH_RESULT\fR 8
+.IX Item "$LAST_SUBMATCH_RESULT"
+.PD 0
+.IP $^N 8
+.IX Xref "$^N $LAST_SUBMATCH_RESULT"
+.IX Item "$^N"
+.PD
+The text matched by the used group most-recently closed (i.e. the group
+with the rightmost closing parenthesis) of the last successful match.
+(See "Scoping Rules of Regex Variables").
+.Sp
+This is subtly different from \f(CW$+\fR. For example in
+.Sp
+.Vb 1
+\&    "ab" =~ /^((.)(.))$/
+.Ve
+.Sp
+we have
+.Sp
+.Vb 3
+\&    $1,$^N   have the value "ab"
+\&    $2       has  the value "a"
+\&    $3,$+    have the value "b"
+.Ve
+.Sp
+This is primarily used inside \f(CW\*(C`(?{...})\*(C'\fR blocks for examining text
+recently matched.  For example, to effectively capture text to a variable
+(in addition to \f(CW$1\fR, \f(CW$2\fR, etc.), replace \f(CW\*(C`(...)\*(C'\fR with
+.Sp
+.Vb 1
+\&    (?:(...)(?{ $var = $^N }))
+.Ve
+.Sp
+By setting and then using \f(CW$var\fR in this way relieves you from having to
+worry about exactly which numbered set of parentheses they are.
+.Sp
+This variable is read-only, and its value is dynamically scoped.
+.Sp
+This variable was added in Perl v5.8.0.
+.Sp
+Mnemonic: the (possibly) Nested parenthesis that most recently closed.
+.ie n .IP @LAST_MATCH_END 8
+.el .IP \f(CW@LAST_MATCH_END\fR 8
+.IX Item "@LAST_MATCH_END"
+.PD 0
+.IP @+ 8
+.IX Xref "@+ @LAST_MATCH_END"
+.PD
+This array holds the offsets of the ends of the last successful
+match and any matching capture buffers that the pattern contains.
+(See "Scoping Rules of Regex Variables")
+.Sp
+The number of elements it contains will be one more than the number
+of capture buffers in the pattern, regardless of which capture buffers
+actually matched. You can use this to determine how many capture
+buffers there are in the pattern. (As opposed to \f(CW\*(C`@\-\*(C'\fR which may
+have fewer elements.)
+.Sp
+\&\f(CW$+[0]\fR is the offset into the string of the end of the entire match.
+This is the same value as what the \f(CW\*(C`pos\*(C'\fR function returns when called
+on the variable that was matched against. The \fIn\fRth element of this
+array holds the offset of the \fIn\fRth submatch, so \f(CW$+[1]\fR is the offset
+past where \f(CW$1\fR ends, \f(CW$+[2]\fR the offset past where \f(CW$2\fR ends, and so
+on. You can use \f(CW$#+\fR to determine how many subgroups were in the last
+successful match. See the examples given for the \f(CW\*(C`@\-\*(C'\fR variable.
+.Sp
+This variable is read-only, and its value is dynamically scoped.
+.Sp
+This variable was added in Perl v5.6.0.
+.IP %{^CAPTURE} 8
+.IX Item "%{^CAPTURE}"
+.PD 0
+.ie n .IP %LAST_PAREN_MATCH 8
+.el .IP \f(CW%LAST_PAREN_MATCH\fR 8
+.IX Item "%LAST_PAREN_MATCH"
+.IP %+ 8
+.IX Xref "%+ %LAST_PAREN_MATCH %{^CAPTURE}"
+.PD
+Similar to \f(CW\*(C`@+\*(C'\fR, the \f(CW\*(C`%+\*(C'\fR hash allows access to the named capture
+buffers, should they exist, in the last successful match in the
+currently active dynamic scope. (See "Scoping Rules of Regex Variables").
+.Sp
+For example, \f(CW$+{foo}\fR is equivalent to \f(CW$1\fR after the following match:
+.Sp
+.Vb 1
+\&    \*(Aqfoo\*(Aq =~ /(?<foo>foo)/;
+.Ve
+.Sp
+The keys of the \f(CW\*(C`%+\*(C'\fR hash list only the names of buffers that have
+captured (and that are thus associated to defined values).
+.Sp
+If multiple distinct capture groups have the same name, then
+\&\f(CW$+{NAME}\fR will refer to the leftmost defined group in the match.
+.Sp
+The underlying behaviour of \f(CW\*(C`%+\*(C'\fR is provided by the
+Tie::Hash::NamedCapture module.
+.Sp
+\&\fBNote:\fR \f(CW\*(C`%\-\*(C'\fR and \f(CW\*(C`%+\*(C'\fR are tied views into a common internal hash
+associated with the last successful regular expression.  Therefore mixing
+iterative access to them via \f(CW\*(C`each\*(C'\fR may have unpredictable results.
+Likewise, if the last successful match changes, then the results may be
+surprising.
+.Sp
+This variable was added in Perl v5.10.0. The \f(CW\*(C`%{^CAPTURE}\*(C'\fR alias was
+added in 5.25.7.
+.Sp
+This variable is read-only, and its value is dynamically scoped.
+.ie n .IP @LAST_MATCH_START 8
+.el .IP \f(CW@LAST_MATCH_START\fR 8
+.IX Item "@LAST_MATCH_START"
+.PD 0
+.IP @\- 8
+.IX Xref "@- @LAST_MATCH_START"
+.PD
+This array holds the offsets of the beginnings of the last successful
+match and any capture buffers it contains.
+(See "Scoping Rules of Regex Variables").
+.Sp
+The number of elements it contains will be one more than the number of
+the highest capture buffers (also called a subgroup) that actually
+matched something. (As opposed to \f(CW\*(C`@+\*(C'\fR which may have fewer elements.)
+.Sp
+\&\f(CW\*(C`$\-[0]\*(C'\fR is the offset of the start of the last successful match.
+\&\f(CW\*(C`$\-[\fR\f(CIn\fR\f(CW]\*(C'\fR is the offset of the start of the substring matched by
+\&\fIn\fR\-th subpattern, or undef if the subpattern did not match.
+.Sp
+Thus, after a match against \f(CW$_\fR, \f(CW$&\fR coincides with
+\&\f(CW\*(C`substr $_, $\-[0], $+[0] \- $\-[0]\*(C'\fR.  Similarly, \f(CW\*(C`$\fR\f(CIn\fR\f(CW\*(C'\fR coincides
+with \f(CW\*(C`substr $_, $\-[n], $+[n] \- $\-[n]\*(C'\fR if \f(CW\*(C`$\-[n]\*(C'\fR is defined, and
+\&\f(CW$+\fR coincides with \f(CW\*(C`substr $_, $\-[$#\-], $+[$#\-] \- $\-[$#\-]\*(C'\fR.
+One can use \f(CW\*(C`$#\-\*(C'\fR to find the last matched subgroup in the last
+successful match.  Contrast with \f(CW$#+\fR, the number of subgroups
+in the regular expression.
+.Sp
+\&\f(CW\*(C`$\-[0]\*(C'\fR is the offset into the string of the beginning of the
+entire match.  The \fIn\fRth element of this array holds the offset
+of the \fIn\fRth submatch, so \f(CW\*(C`$\-[1]\*(C'\fR is the offset where \f(CW$1\fR
+begins, \f(CW\*(C`$\-[2]\*(C'\fR the offset where \f(CW$2\fR begins, and so on.
+.Sp
+After a match against some variable \f(CW$var\fR:
+.RS 8
+.ie n .IP """$\`"" is the same as ""substr($var, 0, $\-[0])""" 5
+.el .IP "\f(CW$\`\fR is the same as \f(CWsubstr($var, 0, $\-[0])\fR" 5
+.IX Item "$ is the same as substr($var, 0, $-[0])"
+.PD 0
+.ie n .IP "$& is the same as ""substr($var, $\-[0], $+[0] \- $\-[0])""" 5
+.el .IP "\f(CW$&\fR is the same as \f(CWsubstr($var, $\-[0], $+[0] \- $\-[0])\fR" 5
+.IX Item "$& is the same as substr($var, $-[0], $+[0] - $-[0])"
+.ie n .IP """$\*(Aq"" is the same as ""substr($var, $+[0])""" 5
+.el .IP "\f(CW$\*(Aq\fR is the same as \f(CWsubstr($var, $+[0])\fR" 5
+.IX Item "$ is the same as substr($var, $+[0])"
+.ie n .IP "$1 is the same as ""substr($var, $\-[1], $+[1] \- $\-[1])""" 5
+.el .IP "\f(CW$1\fR is the same as \f(CWsubstr($var, $\-[1], $+[1] \- $\-[1])\fR" 5
+.IX Item "$1 is the same as substr($var, $-[1], $+[1] - $-[1])"
+.ie n .IP "$2 is the same as ""substr($var, $\-[2], $+[2] \- $\-[2])""" 5
+.el .IP "\f(CW$2\fR is the same as \f(CWsubstr($var, $\-[2], $+[2] \- $\-[2])\fR" 5
+.IX Item "$2 is the same as substr($var, $-[2], $+[2] - $-[2])"
+.ie n .IP "$3 is the same as ""substr($var, $\-[3], $+[3] \- $\-[3])""" 5
+.el .IP "\f(CW$3\fR is the same as \f(CWsubstr($var, $\-[3], $+[3] \- $\-[3])\fR" 5
+.IX Item "$3 is the same as substr($var, $-[3], $+[3] - $-[3])"
+.RE
+.RS 8
+.PD
+.Sp
+This variable is read-only, and its value is dynamically scoped.
+.Sp
+This variable was added in Perl v5.6.0.
+.RE
+.IP %{^CAPTURE_ALL} 8
+.IX Xref "%{^CAPTURE_ALL}"
+.IX Item "%{^CAPTURE_ALL}"
+.PD 0
+.IP %\- 8
+.IX Xref "%-"
+.PD
+Similar to \f(CW\*(C`%+\*(C'\fR, this variable allows access to the named capture
+groups in the last successful match in the currently active dynamic
+scope. (See "Scoping Rules of Regex Variables"). To each capture group
+name found in the regular expression, it associates a reference to an
+array containing the list of values captured by all buffers with that
+name (should there be several of them), in the order where they appear.
+.Sp
+Here's an example:
+.Sp
+.Vb 12
+\&    if (\*(Aq1234\*(Aq =~ /(?<A>1)(?<B>2)(?<A>3)(?<B>4)/) {
+\&        foreach my $bufname (sort keys %\-) {
+\&            my $ary = $\-{$bufname};
+\&            foreach my $idx (0..$#$ary) {
+\&                print "\e$\-{$bufname}[$idx] : ",
+\&                      (defined($ary\->[$idx])
+\&                          ? "\*(Aq$ary\->[$idx]\*(Aq"
+\&                          : "undef"),
+\&                      "\en";
+\&            }
+\&        }
+\&    }
+.Ve
+.Sp
+would print out:
+.Sp
+.Vb 4
+\&    $\-{A}[0] : \*(Aq1\*(Aq
+\&    $\-{A}[1] : \*(Aq3\*(Aq
+\&    $\-{B}[0] : \*(Aq2\*(Aq
+\&    $\-{B}[1] : \*(Aq4\*(Aq
+.Ve
+.Sp
+The keys of the \f(CW\*(C`%\-\*(C'\fR hash correspond to all buffer names found in
+the regular expression.
+.Sp
+The behaviour of \f(CW\*(C`%\-\*(C'\fR is implemented via the
+Tie::Hash::NamedCapture module.
+.Sp
+\&\fBNote:\fR \f(CW\*(C`%\-\*(C'\fR and \f(CW\*(C`%+\*(C'\fR are tied views into a common internal hash
+associated with the last successful regular expression.  Therefore mixing
+iterative access to them via \f(CW\*(C`each\*(C'\fR may have unpredictable results.
+Likewise, if the last successful match changes, then the results may be
+surprising. See "Scoping Rules of Regex Variables".
+.Sp
+This variable was added in Perl v5.10.0. The \f(CW\*(C`%{^CAPTURE_ALL}\*(C'\fR alias was
+added in 5.25.7.
+.Sp
+This variable is read-only, and its value is dynamically scoped.
+.IP ${^LAST_SUCCESSFUL_PATTERN} 8
+.IX Item "${^LAST_SUCCESSFUL_PATTERN}"
+The last successful pattern that matched in the current scope.  The empty
+pattern defaults to matching to this. For instance:
+.Sp
+.Vb 3
+\&    if (m/foo/ || m/bar/) {
+\&        s//BLAH/;
+\&    }
+.Ve
+.Sp
+and
+.Sp
+.Vb 3
+\&    if (m/foo/ || m/bar/) {
+\&        s/${^LAST_SUCCESSFUL_PATTERN}/BLAH/;
+\&    }
+.Ve
+.Sp
+are equivalent.
+.Sp
+You can use this to debug which pattern matched last, or to match with it again.
+.Sp
+Added in Perl 5.37.10.
+.ie n .IP $LAST_REGEXP_CODE_RESULT 8
+.el .IP \f(CW$LAST_REGEXP_CODE_RESULT\fR 8
+.IX Item "$LAST_REGEXP_CODE_RESULT"
+.PD 0
+.IP $^R 8
+.IX Xref "$^R $LAST_REGEXP_CODE_RESULT"
+.IX Item "$^R"
+.PD
+The result of evaluation of the last successful \f(CW\*(C`(?{ code })\*(C'\fR
+regular expression assertion (see perlre).
+.Sp
+This variable may be written to, and its value is scoped normally,
+unlike most other regex variables.
+.Sp
+This variable was added in Perl 5.005.
+.IP ${^RE_COMPILE_RECURSION_LIMIT} 8
+.IX Xref "${^RE_COMPILE_RECURSION_LIMIT}"
+.IX Item "${^RE_COMPILE_RECURSION_LIMIT}"
+The current value giving the maximum number of open but unclosed
+parenthetical groups there may be at any point during a regular
+expression compilation.  The default is currently 1000 nested groups.
+You may adjust it depending on your needs and the amount of memory
+available.
+.Sp
+This variable was added in Perl v5.30.0.
+.IP ${^RE_DEBUG_FLAGS} 8
+.IX Xref "${^RE_DEBUG_FLAGS}"
+.IX Item "${^RE_DEBUG_FLAGS}"
+The current value of the regex debugging flags.  Set to 0 for no debug output
+even when the \f(CW\*(C`re \*(Aqdebug\*(Aq\*(C'\fR module is loaded.  See re for details.
+.Sp
+This variable was added in Perl v5.10.0.
+.IP ${^RE_TRIE_MAXBUF} 8
+.IX Xref "${^RE_TRIE_MAXBUF}"
+.IX Item "${^RE_TRIE_MAXBUF}"
+Controls how certain regex optimisations are applied and how much memory they
+utilize.  This value by default is 65536 which corresponds to a 512kB
+temporary cache.  Set this to a higher value to trade
+memory for speed when matching large alternations.  Set
+it to a lower value if you want the optimisations to
+be as conservative of memory as possible but still occur, and set it to a
+negative value to prevent the optimisation and conserve the most memory.
+Under normal situations this variable should be of no interest to you.
+.Sp
+This variable was added in Perl v5.10.0.
+.SS "Variables related to filehandles"
+.IX Subsection "Variables related to filehandles"
+Variables that depend on the currently selected filehandle may be set
+by calling an appropriate object method on the \f(CW\*(C`IO::Handle\*(C'\fR object,
+although this is less efficient than using the regular built-in
+variables.  (Summary lines below for this contain the word HANDLE.)
+First you must say
+.PP
+.Vb 1
+\&    use IO::Handle;
+.Ve
+.PP
+after which you may use either
+.PP
+.Vb 1
+\&    method HANDLE EXPR
+.Ve
+.PP
+or more safely,
+.PP
+.Vb 1
+\&    HANDLE\->method(EXPR)
+.Ve
+.PP
+Each method returns the old value of the \f(CW\*(C`IO::Handle\*(C'\fR attribute.  The
+methods each take an optional EXPR, which, if supplied, specifies the
+new value for the \f(CW\*(C`IO::Handle\*(C'\fR attribute in question.  If not
+supplied, most methods do nothing to the current value\-\-except for
+\&\f(CWautoflush()\fR, which will assume a 1 for you, just to be different.
+.PP
+Because loading in the \f(CW\*(C`IO::Handle\*(C'\fR class is an expensive operation,
+you should learn how to use the regular built-in variables.
+.PP
+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.
+.PP
+You should be very careful when modifying the default values of most
+special variables described in this document.  In most cases you want
+to localize these variables before changing them, since if you don't,
+the change may affect other modules which rely on the default values
+of the special variables that you have changed.  This is one of the
+correct ways to read the whole file at once:
+.PP
+.Vb 4
+\&    open my $fh, "<", "foo" or die $!;
+\&    local $/; # enable localized slurp mode
+\&    my $content = <$fh>;
+\&    close $fh;
+.Ve
+.PP
+But the following code is quite bad:
+.PP
+.Vb 4
+\&    open my $fh, "<", "foo" or die $!;
+\&    undef $/; # enable slurp mode
+\&    my $content = <$fh>;
+\&    close $fh;
+.Ve
+.PP
+since some other module, may want to read data from some file in the
+default "line mode", so if the code we have just presented has been
+executed, the global value of \f(CW$/\fR is now changed for any other code
+running inside the same Perl interpreter.
+.PP
+Usually when a variable is localized you want to make sure that this
+change affects the shortest scope possible.  So unless you are already
+inside some short \f(CW\*(C`{}\*(C'\fR block, you should create one yourself.  For
+example:
+.PP
+.Vb 7
+\&    my $content = \*(Aq\*(Aq;
+\&    open my $fh, "<", "foo" or die $!;
+\&    {
+\&        local $/;
+\&        $content = <$fh>;
+\&    }
+\&    close $fh;
+.Ve
+.PP
+Here is an example of how your own code can go broken:
+.PP
+.Vb 5
+\&    for ( 1..3 ){
+\&        $\e = "\er\en";
+\&        nasty_break();
+\&        print "$_";
+\&    }
+\&
+\&    sub nasty_break {
+\&        $\e = "\ef";
+\&        # do something with $_
+\&    }
+.Ve
+.PP
+You probably expect this code to print the equivalent of
+.PP
+.Vb 1
+\&    "1\er\en2\er\en3\er\en"
+.Ve
+.PP
+but instead you get:
+.PP
+.Vb 1
+\&    "1\ef2\ef3\ef"
+.Ve
+.PP
+Why? Because \f(CWnasty_break()\fR modifies \f(CW\*(C`$\e\*(C'\fR without localizing it
+first.  The value you set in  \f(CWnasty_break()\fR is still there when you
+return.  The fix is to add \f(CWlocal()\fR so the value doesn't leak out of
+\&\f(CWnasty_break()\fR:
+.PP
+.Vb 1
+\&    local $\e = "\ef";
+.Ve
+.PP
+It's easy to notice the problem in such a short example, but in more
+complicated code you are looking for trouble if you don't localize
+changes to the special variables.
+.ie n .IP $ARGV 8
+.el .IP \f(CW$ARGV\fR 8
+.IX Xref "$ARGV"
+.IX Item "$ARGV"
+Contains the name of the current file when reading from \f(CW\*(C`<>\*(C'\fR.
+.ie n .IP @ARGV 8
+.el .IP \f(CW@ARGV\fR 8
+.IX Xref "@ARGV"
+.IX Item "@ARGV"
+The array \f(CW@ARGV\fR contains the command-line arguments intended for
+the script.  \f(CW$#ARGV\fR is generally the number of arguments minus
+one, because \f(CW$ARGV[0]\fR is the first argument, \fInot\fR the program's
+command name itself.  See "$0" for the command name.
+.IP ARGV 8
+.IX Xref "ARGV"
+.IX Item "ARGV"
+The special filehandle that iterates over command-line filenames in
+\&\f(CW@ARGV\fR.  Usually written as the null filehandle in the angle operator
+\&\f(CW\*(C`<>\*(C'\fR.  Note that currently \f(CW\*(C`ARGV\*(C'\fR only has its magical effect
+within the \f(CW\*(C`<>\*(C'\fR operator; elsewhere it is just a plain filehandle
+corresponding to the last file opened by \f(CW\*(C`<>\*(C'\fR.  In particular,
+passing \f(CW\*(C`\e*ARGV\*(C'\fR as a parameter to a function that expects a filehandle
+may not cause your function to automatically read the contents of all the
+files in \f(CW@ARGV\fR.
+.IP ARGVOUT 8
+.IX Xref "ARGVOUT"
+.IX Item "ARGVOUT"
+The special filehandle that points to the currently open output file
+when doing edit-in-place processing with \fB\-i\fR.  Useful when you have
+to do a lot of inserting and don't want to keep modifying \f(CW$_\fR.  See
+perlrun for the \fB\-i\fR switch.
+.IP "IO::Handle\->output_field_separator( EXPR )" 8
+.IX Item "IO::Handle->output_field_separator( EXPR )"
+.PD 0
+.ie n .IP $OUTPUT_FIELD_SEPARATOR 8
+.el .IP \f(CW$OUTPUT_FIELD_SEPARATOR\fR 8
+.IX Item "$OUTPUT_FIELD_SEPARATOR"
+.ie n .IP $OFS 8
+.el .IP \f(CW$OFS\fR 8
+.IX Item "$OFS"
+.IP $, 8
+.IX Xref "$, $OFS $OUTPUT_FIELD_SEPARATOR"
+.PD
+The output field separator for the print operator.  If defined, this
+value is printed between each of print's arguments.  Default is \f(CW\*(C`undef\*(C'\fR.
+.Sp
+You cannot call \f(CWoutput_field_separator()\fR on a handle, only as a
+static method.  See IO::Handle.
+.Sp
+Mnemonic: what is printed when there is a "," in your print statement.
+.IP "HANDLE\->input_line_number( EXPR )" 8
+.IX Item "HANDLE->input_line_number( EXPR )"
+.PD 0
+.ie n .IP $INPUT_LINE_NUMBER 8
+.el .IP \f(CW$INPUT_LINE_NUMBER\fR 8
+.IX Item "$INPUT_LINE_NUMBER"
+.ie n .IP $NR 8
+.el .IP \f(CW$NR\fR 8
+.IX Item "$NR"
+.IP $. 8
+.IX Xref "$. $NR $INPUT_LINE_NUMBER line number"
+.PD
+Current line number for the last filehandle accessed.
+.Sp
+Each filehandle in Perl counts the number of lines that have been read
+from it.  (Depending on the value of \f(CW$/\fR, Perl's idea of what
+constitutes a line may not match yours.)  When a line is read from a
+filehandle (via \f(CWreadline()\fR or \f(CW\*(C`<>\*(C'\fR), or when \f(CWtell()\fR or
+\&\f(CWseek()\fR is called on it, \f(CW$.\fR becomes an alias to the line counter
+for that filehandle.
+.Sp
+You can adjust the counter by assigning to \f(CW$.\fR, but this will not
+actually move the seek pointer.  \fILocalizing \fR\f(CI$.\fR\fI will not localize
+the filehandle's line count\fR.  Instead, it will localize perl's notion
+of which filehandle \f(CW$.\fR is currently aliased to.
+.Sp
+\&\f(CW$.\fR is reset when the filehandle is closed, but \fBnot\fR when an open
+filehandle is reopened without an intervening \f(CWclose()\fR.  For more
+details, see "I/O Operators" in perlop.  Because \f(CW\*(C`<>\*(C'\fR never does
+an explicit close, line numbers increase across \f(CW\*(C`ARGV\*(C'\fR files (but see
+examples in "eof" in perlfunc).
+.Sp
+You can also use \f(CW\*(C`HANDLE\->input_line_number(EXPR)\*(C'\fR to access the
+line counter for a given filehandle without having to worry about
+which handle you last accessed.
+.Sp
+Mnemonic: many programs use "." to mean the current line number.
+.IP "IO::Handle\->input_record_separator( EXPR )" 8
+.IX Item "IO::Handle->input_record_separator( EXPR )"
+.PD 0
+.ie n .IP $INPUT_RECORD_SEPARATOR 8
+.el .IP \f(CW$INPUT_RECORD_SEPARATOR\fR 8
+.IX Item "$INPUT_RECORD_SEPARATOR"
+.ie n .IP $RS 8
+.el .IP \f(CW$RS\fR 8
+.IX Item "$RS"
+.IP $/ 8
+.IX Xref "$ $RS $INPUT_RECORD_SEPARATOR"
+.PD
+The input record separator, newline by default.  This influences Perl's
+idea of what a "line" is.  Works like \fBawk\fR's RS variable, including
+treating empty lines as a terminator if set to the null string (an
+empty line cannot contain any spaces or tabs).  You may set it to a
+multi-character string to match a multi-character terminator, or to
+\&\f(CW\*(C`undef\*(C'\fR to read through the end of file.  Setting it to \f(CW"\en\en"\fR
+means something slightly different than setting to \f(CW""\fR, if the file
+contains consecutive empty lines.  Setting to \f(CW""\fR will treat two or
+more consecutive empty lines as a single empty line.  Setting to
+\&\f(CW"\en\en"\fR will blindly assume that the next input character belongs to
+the next paragraph, even if it's a newline.
+.Sp
+.Vb 3
+\&    local $/;           # enable "slurp" mode
+\&    local $_ = <FH>;    # whole file now here
+\&    s/\en[ \et]+/ /g;
+.Ve
+.Sp
+Remember: the value of \f(CW$/\fR is a string, not a regex.  \fBawk\fR has to
+be better for something. :\-)
+.Sp
+Setting \f(CW$/\fR to an empty string \-\- the so-called \fIparagraph mode\fR \-\- merits
+special attention.  When \f(CW$/\fR is set to \f(CW""\fR and the entire file is read in
+with that setting, any sequence of one or more consecutive newlines at the
+beginning of the file is discarded.  With the exception of the final record in
+the file, each sequence of characters ending in two or more newlines is
+treated as one record and is read in to end in exactly two newlines.  If the
+last record in the file ends in zero or one consecutive newlines, that record
+is read in with that number of newlines.  If the last record ends in two or
+more consecutive newlines, it is read in with two newlines like all preceding
+records.
+.Sp
+Suppose we wrote the following string to a file:
+.Sp
+.Vb 4
+\&    my $string = "\en\en\en";
+\&    $string .= "alpha beta\engamma delta\en\en\en";
+\&    $string .= "epsilon zeta eta\en\en";
+\&    $string .= "theta\en";
+\&
+\&    my $file = \*(Aqsimple_file.txt\*(Aq;
+\&    open my $OUT, \*(Aq>\*(Aq, $file or die;
+\&    print $OUT $string;
+\&    close $OUT or die;
+.Ve
+.Sp
+Now we read that file in paragraph mode:
+.Sp
+.Vb 4
+\&    local $/ = ""; # paragraph mode
+\&    open my $IN, \*(Aq<\*(Aq, $file or die;
+\&    my @records = <$IN>;
+\&    close $IN or die;
+.Ve
+.Sp
+\&\f(CW@records\fR will consist of these 3 strings:
+.Sp
+.Vb 5
+\&    (
+\&      "alpha beta\engamma delta\en\en",
+\&      "epsilon zeta eta\en\en",
+\&      "theta\en",
+\&    )
+.Ve
+.Sp
+Setting \f(CW$/\fR to a reference to an integer, scalar containing an
+integer, or scalar that's convertible to an integer will attempt to
+read records instead of lines, with the maximum record size being the
+referenced integer number of characters.  So this:
+.Sp
+.Vb 3
+\&    local $/ = \e32768; # or \e"32768", or \e$var_containing_32768
+\&    open my $fh, "<", $myfile or die $!;
+\&    local $_ = <$fh>;
+.Ve
+.Sp
+will read a record of no more than 32768 characters from \f(CW$fh\fR.  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.  Trying to set the record
+size to zero or less is deprecated and will cause $/ to have the value
+of "undef", which will cause reading in the (rest of the) whole file.
+.Sp
+As of 5.19.9 setting \f(CW$/\fR to any other form of reference will throw a
+fatal exception. This is in preparation for supporting new ways to set
+\&\f(CW$/\fR in the future.
+.Sp
+On VMS only, record reads bypass PerlIO layers and any associated
+buffering, so you must not mix record and non-record reads on the
+same filehandle.  Record mode mixes with line mode only when the
+same buffering layer is in use for both modes.
+.Sp
+You cannot call \f(CWinput_record_separator()\fR on a handle, only as a
+static method.  See IO::Handle.
+.Sp
+See also "Newlines" in perlport.  Also see "$.".
+.Sp
+Mnemonic: / delimits line boundaries when quoting poetry.
+.IP "IO::Handle\->output_record_separator( EXPR )" 8
+.IX Item "IO::Handle->output_record_separator( EXPR )"
+.PD 0
+.ie n .IP $OUTPUT_RECORD_SEPARATOR 8
+.el .IP \f(CW$OUTPUT_RECORD_SEPARATOR\fR 8
+.IX Item "$OUTPUT_RECORD_SEPARATOR"
+.ie n .IP $ORS 8
+.el .IP \f(CW$ORS\fR 8
+.IX Item "$ORS"
+.IP $\e 8
+.IX Xref "$\\ $ORS $OUTPUT_RECORD_SEPARATOR"
+.IX Item "$"
+.PD
+The output record separator for the print operator.  If defined, this
+value is printed after the last of print's arguments.  Default is \f(CW\*(C`undef\*(C'\fR.
+.Sp
+You cannot call \f(CWoutput_record_separator()\fR on a handle, only as a
+static method.  See IO::Handle.
+.Sp
+Mnemonic: you set \f(CW\*(C`$\e\*(C'\fR instead of adding "\en" at the end of the print.
+Also, it's just like \f(CW$/\fR, but it's what you get "back" from Perl.
+.IP "HANDLE\->autoflush( EXPR )" 8
+.IX Item "HANDLE->autoflush( EXPR )"
+.PD 0
+.ie n .IP $OUTPUT_AUTOFLUSH 8
+.el .IP \f(CW$OUTPUT_AUTOFLUSH\fR 8
+.IX Item "$OUTPUT_AUTOFLUSH"
+.IP $| 8
+.IX Xref "$| autoflush flush $OUTPUT_AUTOFLUSH"
+.PD
+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 really buffered by the system or
+not; \f(CW$|\fR tells you only whether you've asked Perl explicitly to
+flush after each write).  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 or
+socket, such as when you are running a Perl program under \fBrsh\fR and
+want to see the output as it's happening.  This has no effect on input
+buffering.  See "getc" in perlfunc for that.  See "select" in perlfunc on
+how to select the output channel.  See also IO::Handle.
+.Sp
+Mnemonic: when you want your pipes to be piping hot.
+.IP ${^LAST_FH} 8
+.IX Xref "${^LAST_FH}"
+.IX Item "${^LAST_FH}"
+This read-only variable contains a reference to the last-read filehandle.
+This is set by \f(CW\*(C`<HANDLE>\*(C'\fR, \f(CW\*(C`readline\*(C'\fR, \f(CW\*(C`tell\*(C'\fR, \f(CW\*(C`eof\*(C'\fR and \f(CW\*(C`seek\*(C'\fR.
+This is the same handle that \f(CW$.\fR and \f(CW\*(C`tell\*(C'\fR and \f(CW\*(C`eof\*(C'\fR without arguments
+use.  It is also the handle used when Perl appends ", <STDIN> line 1" to
+an error or warning message.
+.Sp
+This variable was added in Perl v5.18.0.
+.PP
+\fIVariables related to formats\fR
+.IX Subsection "Variables related to formats"
+.PP
+The special variables for formats are a subset of those for
+filehandles.  See perlform for more information about Perl's
+formats.
+.ie n .IP $ACCUMULATOR 8
+.el .IP \f(CW$ACCUMULATOR\fR 8
+.IX Item "$ACCUMULATOR"
+.PD 0
+.IP $^A 8
+.IX Xref "$^A $ACCUMULATOR"
+.IX Item "$^A"
+.PD
+The current value of the \f(CWwrite()\fR accumulator for \f(CWformat()\fR lines.
+A format contains \f(CWformline()\fR calls that put their result into
+\&\f(CW$^A\fR.  After calling its format, \f(CWwrite()\fR prints out the contents
+of \f(CW$^A\fR and empties.  So you never really see the contents of \f(CW$^A\fR
+unless you call \f(CWformline()\fR yourself and then look at it.  See
+perlform and "formline PICTURE,LIST" in perlfunc.
+.IP IO::Handle\->format_formfeed(EXPR) 8
+.IX Item "IO::Handle->format_formfeed(EXPR)"
+.PD 0
+.ie n .IP $FORMAT_FORMFEED 8
+.el .IP \f(CW$FORMAT_FORMFEED\fR 8
+.IX Item "$FORMAT_FORMFEED"
+.IP $^L 8
+.IX Xref "$^L $FORMAT_FORMFEED"
+.IX Item "$^L"
+.PD
+What formats output as a form feed.  The default is \f(CW\*(C`\ef\*(C'\fR.
+.Sp
+You cannot call \f(CWformat_formfeed()\fR on a handle, only as a static
+method.  See IO::Handle.
+.IP HANDLE\->format_page_number(EXPR) 8
+.IX Item "HANDLE->format_page_number(EXPR)"
+.PD 0
+.ie n .IP $FORMAT_PAGE_NUMBER 8
+.el .IP \f(CW$FORMAT_PAGE_NUMBER\fR 8
+.IX Item "$FORMAT_PAGE_NUMBER"
+.IP $% 8
+.IX Xref "$% $FORMAT_PAGE_NUMBER"
+.PD
+The current page number of the currently selected output channel.
+.Sp
+Mnemonic: \f(CW\*(C`%\*(C'\fR is page number in \fBnroff\fR.
+.IP HANDLE\->format_lines_left(EXPR) 8
+.IX Item "HANDLE->format_lines_left(EXPR)"
+.PD 0
+.ie n .IP $FORMAT_LINES_LEFT 8
+.el .IP \f(CW$FORMAT_LINES_LEFT\fR 8
+.IX Item "$FORMAT_LINES_LEFT"
+.IP $\- 8
+.IX Xref "$- $FORMAT_LINES_LEFT"
+.PD
+The number of lines left on the page of the currently selected output
+channel.
+.Sp
+Mnemonic: lines_on_page \- lines_printed.
+.IP "IO::Handle\->format_line_break_characters EXPR" 8
+.IX Item "IO::Handle->format_line_break_characters EXPR"
+.PD 0
+.ie n .IP $FORMAT_LINE_BREAK_CHARACTERS 8
+.el .IP \f(CW$FORMAT_LINE_BREAK_CHARACTERS\fR 8
+.IX Item "$FORMAT_LINE_BREAK_CHARACTERS"
+.ie n .IP $: 8
+.el .IP \f(CW$:\fR 8
+.IX Xref "$: FORMAT_LINE_BREAK_CHARACTERS"
+.IX Item "$:"
+.PD
+The current set of characters after which a string may be broken to
+fill continuation fields (starting with \f(CW\*(C`^\*(C'\fR) in a format.  The default is
+"\ \en\-", to break on a space, newline, or a hyphen.
+.Sp
+You cannot call \f(CWformat_line_break_characters()\fR on a handle, only as
+a static method.  See IO::Handle.
+.Sp
+Mnemonic: a "colon" in poetry is a part of a line.
+.IP HANDLE\->format_lines_per_page(EXPR) 8
+.IX Item "HANDLE->format_lines_per_page(EXPR)"
+.PD 0
+.ie n .IP $FORMAT_LINES_PER_PAGE 8
+.el .IP \f(CW$FORMAT_LINES_PER_PAGE\fR 8
+.IX Item "$FORMAT_LINES_PER_PAGE"
+.IP $= 8
+.IX Xref "$= $FORMAT_LINES_PER_PAGE"
+.PD
+The current page length (printable lines) of the currently selected
+output channel.  The default is 60.
+.Sp
+Mnemonic: = has horizontal lines.
+.IP HANDLE\->format_top_name(EXPR) 8
+.IX Item "HANDLE->format_top_name(EXPR)"
+.PD 0
+.ie n .IP $FORMAT_TOP_NAME 8
+.el .IP \f(CW$FORMAT_TOP_NAME\fR 8
+.IX Item "$FORMAT_TOP_NAME"
+.IP $^ 8
+.IX Xref "$^ $FORMAT_TOP_NAME"
+.PD
+The name of the current top-of-page format for the currently selected
+output channel.  The default is the name of the filehandle with \f(CW\*(C`_TOP\*(C'\fR
+appended.  For example, the default format top name for the \f(CW\*(C`STDOUT\*(C'\fR
+filehandle is \f(CW\*(C`STDOUT_TOP\*(C'\fR.
+.Sp
+Mnemonic: points to top of page.
+.IP HANDLE\->format_name(EXPR) 8
+.IX Item "HANDLE->format_name(EXPR)"
+.PD 0
+.ie n .IP $FORMAT_NAME 8
+.el .IP \f(CW$FORMAT_NAME\fR 8
+.IX Item "$FORMAT_NAME"
+.IP $~ 8
+.IX Xref "$~ $FORMAT_NAME"
+.PD
+The name of the current report format for the currently selected
+output channel.  The default format name is the same as the filehandle
+name.  For example, the default format name for the \f(CW\*(C`STDOUT\*(C'\fR
+filehandle is just \f(CW\*(C`STDOUT\*(C'\fR.
+.Sp
+Mnemonic: brother to \f(CW$^\fR.
+.SS "Error Variables"
+.IX Xref "error exception"
+.IX Subsection "Error Variables"
+The variables \f(CW$@\fR, \f(CW$!\fR, \f(CW$^E\fR, and \f(CW$?\fR contain information
+about different types of error conditions that may appear during
+execution of a Perl program.  The variables are shown ordered by
+the "distance" between the subsystem which reported the error and
+the Perl process.  They correspond to errors detected by the Perl
+interpreter, C library, operating system, or an external program,
+respectively.
+.PP
+To illustrate the differences between these variables, consider the
+following Perl expression, which uses a single-quoted string.  After
+execution of this statement, perl may have set all four special error
+variables:
+.PP
+.Vb 5
+\&    eval q{
+\&        open my $pipe, "/cdrom/install |" or die $!;
+\&        my @res = <$pipe>;
+\&        close $pipe or die "bad pipe: $?, $!";
+\&    };
+.Ve
+.PP
+When perl executes the \f(CWeval()\fR expression, it translates the
+\&\f(CWopen()\fR, \f(CW\*(C`<PIPE>\*(C'\fR, and \f(CW\*(C`close\*(C'\fR calls in the C run-time library
+and thence to the operating system kernel.  perl sets \f(CW$!\fR to
+the C library's \f(CW\*(C`errno\*(C'\fR if one of these calls fails.
+.PP
+\&\f(CW$@\fR is set if the string to be \f(CW\*(C`eval\*(C'\fR\-ed did not compile (this may
+happen if \f(CW\*(C`open\*(C'\fR or \f(CW\*(C`close\*(C'\fR were imported with bad prototypes), or
+if Perl code executed during evaluation \f(CWdie()\fRd.  In these cases the
+value of \f(CW$@\fR is the compile error, or the argument to \f(CW\*(C`die\*(C'\fR (which
+will interpolate \f(CW$!\fR and \f(CW$?\fR).  (See also Fatal, though.)
+.PP
+Under a few operating systems, \f(CW$^E\fR may contain a more verbose error
+indicator, such as in this case, "CDROM tray not closed."  Systems that
+do not support extended error messages leave \f(CW$^E\fR the same as \f(CW$!\fR.
+.PP
+Finally, \f(CW$?\fR may be set to a non\-0 value if the external program
+\&\fI/cdrom/install\fR fails.  The upper eight bits reflect specific error
+conditions encountered by the program (the program's \f(CWexit()\fR value).
+The lower eight bits reflect mode of failure, like signal death and
+core dump information.  See \fBwait\fR\|(2) for details.  In contrast to
+\&\f(CW$!\fR and \f(CW$^E\fR, which are set only if an error condition is detected,
+the variable \f(CW$?\fR is set on each \f(CW\*(C`wait\*(C'\fR or pipe \f(CW\*(C`close\*(C'\fR,
+overwriting the old value.  This is more like \f(CW$@\fR, which on every
+\&\f(CWeval()\fR is always set on failure and cleared on success.
+.PP
+For more details, see the individual descriptions at \f(CW$@\fR, \f(CW$!\fR,
+\&\f(CW$^E\fR, and \f(CW$?\fR.
+.IP ${^CHILD_ERROR_NATIVE} 8
+.IX Xref "$^CHILD_ERROR_NATIVE"
+.IX Item "${^CHILD_ERROR_NATIVE}"
+The native status returned by the last pipe close, backtick (\f(CW\`\`\fR)
+command, successful call to \f(CWwait()\fR or \f(CWwaitpid()\fR, or from the
+\&\f(CWsystem()\fR operator.  On POSIX-like systems this value can be decoded
+with the WIFEXITED, WEXITSTATUS, WIFSIGNALED, WTERMSIG, WIFSTOPPED, and
+WSTOPSIG functions provided by the POSIX module.
+.Sp
+Under VMS this reflects the actual VMS exit status; i.e. it is the
+same as \f(CW$?\fR when the pragma \f(CW\*(C`use vmsish \*(Aqstatus\*(Aq\*(C'\fR is in effect.
+.Sp
+This variable was added in Perl v5.10.0.
+.ie n .IP $EXTENDED_OS_ERROR 8
+.el .IP \f(CW$EXTENDED_OS_ERROR\fR 8
+.IX Item "$EXTENDED_OS_ERROR"
+.PD 0
+.IP $^E 8
+.IX Xref "$^E $EXTENDED_OS_ERROR"
+.IX Item "$^E"
+.PD
+Error information specific to the current operating system.  At the
+moment, this differs from \f(CW"$!"\fR under only VMS, OS/2, and Win32 (and
+for MacPerl).  On all other platforms, \f(CW$^E\fR is always just the same
+as \f(CW$!\fR.
+.Sp
+Under VMS, \f(CW$^E\fR provides the VMS status value from the last system
+error.  This is more specific information about the last system error
+than that provided by \f(CW$!\fR.  This is particularly important when \f(CW$!\fR
+is set to \fBEVMSERR\fR.
+.Sp
+Under OS/2, \f(CW$^E\fR is set to the error code of the last call to OS/2
+API either via CRT, or directly from perl.
+.Sp
+Under Win32, \f(CW$^E\fR always returns the last error information reported
+by the Win32 call \f(CWGetLastError()\fR which describes the last error
+from within the Win32 API.  Most Win32\-specific code will report errors
+via \f(CW$^E\fR.  ANSI C and Unix-like calls set \f(CW\*(C`errno\*(C'\fR and so most
+portable Perl code will report errors via \f(CW$!\fR.
+.Sp
+Caveats mentioned in the description of \f(CW"$!"\fR generally apply to
+\&\f(CW$^E\fR, also.
+.Sp
+This variable was added in Perl 5.003.
+.Sp
+Mnemonic: Extra error explanation.
+.ie n .IP $EXCEPTIONS_BEING_CAUGHT 8
+.el .IP \f(CW$EXCEPTIONS_BEING_CAUGHT\fR 8
+.IX Item "$EXCEPTIONS_BEING_CAUGHT"
+.PD 0
+.IP $^S 8
+.IX Xref "$^S $EXCEPTIONS_BEING_CAUGHT"
+.IX Item "$^S"
+.PD
+Current state of the interpreter.
+.Sp
+.Vb 5
+\&    $^S         State
+\&    \-\-\-\-\-\-\-\-\-   \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\&    undef       Parsing module, eval, or main program
+\&    true (1)    Executing an eval or try block
+\&    false (0)   Otherwise
+.Ve
+.Sp
+The first state may happen in \f(CW$SIG{_\|_DIE_\|_}\fR and \f(CW$SIG{_\|_WARN_\|_}\fR
+handlers.
+.Sp
+The English name \f(CW$EXCEPTIONS_BEING_CAUGHT\fR is slightly misleading, because
+the \f(CW\*(C`undef\*(C'\fR value does not indicate whether exceptions are being caught,
+since compilation of the main program does not catch exceptions.
+.Sp
+This variable was added in Perl 5.004.
+.ie n .IP $WARNING 8
+.el .IP \f(CW$WARNING\fR 8
+.IX Item "$WARNING"
+.PD 0
+.IP $^W 8
+.IX Xref "$^W $WARNING"
+.IX Item "$^W"
+.PD
+The current value of the warning switch, initially true if \fB\-w\fR was
+used, false otherwise, but directly modifiable.
+.Sp
+See also warnings.
+.Sp
+Mnemonic: related to the \fB\-w\fR switch.
+.IP ${^WARNING_BITS} 8
+.IX Xref "${^WARNING_BITS}"
+.IX Item "${^WARNING_BITS}"
+The current set of warning checks enabled by the \f(CW\*(C`use warnings\*(C'\fR pragma.
+It has the same scoping as the \f(CW$^H\fR and \f(CW\*(C`%^H\*(C'\fR variables.  The exact
+values are considered internal to the warnings pragma and may change
+between versions of Perl.
+.Sp
+Each time a statement completes being compiled, the current value of
+\&\f(CW\*(C`${^WARNING_BITS}\*(C'\fR is stored with that statement, and can later be
+retrieved via \f(CW\*(C`(caller($level))[9]\*(C'\fR.
+.Sp
+This variable was added in Perl v5.6.0.
+.ie n .IP $OS_ERROR 8
+.el .IP \f(CW$OS_ERROR\fR 8
+.IX Item "$OS_ERROR"
+.PD 0
+.ie n .IP $ERRNO 8
+.el .IP \f(CW$ERRNO\fR 8
+.IX Item "$ERRNO"
+.IP $! 8
+.IX Xref "$! $ERRNO $OS_ERROR"
+.PD
+When referenced, \f(CW$!\fR retrieves the current value
+of the C \f(CW\*(C`errno\*(C'\fR integer variable.
+If \f(CW$!\fR is assigned a numerical value, that value is stored in \f(CW\*(C`errno\*(C'\fR.
+When referenced as a string, \f(CW$!\fR yields the system error string
+corresponding to \f(CW\*(C`errno\*(C'\fR.
+.Sp
+Many system or library calls set \f(CW\*(C`errno\*(C'\fR if they fail,
+to indicate the cause of failure.  They usually do \fBnot\fR
+set \f(CW\*(C`errno\*(C'\fR to zero if they succeed and may set \f(CW\*(C`errno\*(C'\fR to a
+non-zero value on success.  This means \f(CW\*(C`errno\*(C'\fR, hence \f(CW$!\fR, is
+meaningful only \fIimmediately\fR after a \fBfailure\fR:
+.Sp
+.Vb 11
+\&    if (open my $fh, "<", $filename) {
+\&        # Here $! is meaningless.
+\&        ...
+\&    }
+\&    else {
+\&        # ONLY here is $! meaningful.
+\&        ...
+\&        # Already here $! might be meaningless.
+\&    }
+\&    # Since here we might have either success or failure,
+\&    # $! is meaningless.
+.Ve
+.Sp
+Here, \fImeaningless\fR means that \f(CW$!\fR may be unrelated to the outcome
+of the \f(CWopen()\fR operator.  Assignment to \f(CW$!\fR is similarly ephemeral.
+It can be used immediately before invoking the \f(CWdie()\fR operator,
+to set the exit value, or to inspect the system error string
+corresponding to error \fIn\fR, or to restore \f(CW$!\fR to a meaningful state.
+.Sp
+Perl itself may set \f(CW\*(C`errno\*(C'\fR to a non-zero on failure even if no
+system call is performed.
+.Sp
+Mnemonic: What just went bang?
+.ie n .IP %OS_ERROR 8
+.el .IP \f(CW%OS_ERROR\fR 8
+.IX Item "%OS_ERROR"
+.PD 0
+.ie n .IP %ERRNO 8
+.el .IP \f(CW%ERRNO\fR 8
+.IX Item "%ERRNO"
+.IP %! 8
+.IX Xref "%! %OS_ERROR %ERRNO"
+.PD
+Each element of \f(CW\*(C`%!\*(C'\fR has a true value only if \f(CW$!\fR is set to that
+value.  For example, \f(CW$!{ENOENT}\fR is true if and only if the current
+value of \f(CW$!\fR is \f(CW\*(C`ENOENT\*(C'\fR; that is, if the most recent error was "No
+such file or directory" (or its moral equivalent: not all operating
+systems give that exact error, and certainly not all languages).  The
+specific true value is not guaranteed, but in the past has generally
+been the numeric value of \f(CW$!\fR.  To check if a particular key is
+meaningful on your system, use \f(CW\*(C`exists $!{the_key}\*(C'\fR; for a list of legal
+keys, use \f(CW\*(C`keys %!\*(C'\fR.  See Errno for more information, and also see
+"$!".
+.Sp
+This variable was added in Perl 5.005.
+.ie n .IP $CHILD_ERROR 8
+.el .IP \f(CW$CHILD_ERROR\fR 8
+.IX Item "$CHILD_ERROR"
+.PD 0
+.IP $? 8
+.IX Xref "$? $CHILD_ERROR"
+.PD
+The status returned by the last pipe close, backtick (\f(CW\`\`\fR) command,
+successful call to \f(CWwait()\fR or \f(CWwaitpid()\fR, or from the \f(CWsystem()\fR
+operator.  This is just the 16\-bit status word returned by the
+traditional Unix \f(CWwait()\fR system call (or else is made up to look
+like it).  Thus, the exit value of the subprocess is really (\f(CW$? >>
+8\fR), and \f(CW\*(C`$? & 127\*(C'\fR gives which signal, if any, the process died
+from, and \f(CW\*(C`$? & 128\*(C'\fR reports whether there was a core dump.
+.Sp
+Additionally, if the \f(CW\*(C`h_errno\*(C'\fR variable is supported in C, its value
+is returned via \f(CW$?\fR if any \f(CW\*(C`gethost*()\*(C'\fR function fails.
+.Sp
+If you have installed a signal handler for \f(CW\*(C`SIGCHLD\*(C'\fR, the
+value of \f(CW$?\fR will usually be wrong outside that handler.
+.Sp
+Inside an \f(CW\*(C`END\*(C'\fR subroutine \f(CW$?\fR contains the value that is going to be
+given to \f(CWexit()\fR.  You can modify \f(CW$?\fR in an \f(CW\*(C`END\*(C'\fR subroutine to
+change the exit status of your program.  For example:
+.Sp
+.Vb 3
+\&    END {
+\&        $? = 1 if $? == 255;  # die would make it 255
+\&    }
+.Ve
+.Sp
+Under VMS, the pragma \f(CW\*(C`use vmsish \*(Aqstatus\*(Aq\*(C'\fR makes \f(CW$?\fR reflect the
+actual VMS exit status, instead of the default emulation of POSIX
+status; see "$?" in perlvms for details.
+.Sp
+Mnemonic: similar to \fBsh\fR and \fBksh\fR.
+.ie n .IP $EVAL_ERROR 8
+.el .IP \f(CW$EVAL_ERROR\fR 8
+.IX Item "$EVAL_ERROR"
+.PD 0
+.IP $@ 8
+.IX Xref "$@ $EVAL_ERROR"
+.PD
+The Perl error from the last \f(CW\*(C`eval\*(C'\fR operator, i.e. the last exception that
+was caught.  For \f(CW\*(C`eval BLOCK\*(C'\fR, this is either a runtime error message or the
+string or reference \f(CW\*(C`die\*(C'\fR was called with.  The \f(CW\*(C`eval STRING\*(C'\fR form also
+catches syntax errors and other compile time exceptions.
+.Sp
+If no error occurs, \f(CW\*(C`eval\*(C'\fR sets \f(CW$@\fR to the empty string.
+.Sp
+Warning messages are not collected in this variable.  You can, however,
+set up a routine to process warnings by setting \f(CW$SIG{_\|_WARN_\|_}\fR as
+described in "%SIG".
+.Sp
+Mnemonic: Where was the error "at"?
+.SS "Variables related to the interpreter state"
+.IX Subsection "Variables related to the interpreter state"
+These variables provide information about the current interpreter state.
+.ie n .IP $COMPILING 8
+.el .IP \f(CW$COMPILING\fR 8
+.IX Item "$COMPILING"
+.PD 0
+.IP $^C 8
+.IX Xref "$^C $COMPILING"
+.IX Item "$^C"
+.PD
+The current value of the flag associated with the \fB\-c\fR switch.
+Mainly of use with \fB\-MO=...\fR to allow code to alter its behavior
+when being compiled, such as for example to \f(CW\*(C`AUTOLOAD\*(C'\fR at compile
+time rather than normal, deferred loading.  Setting
+\&\f(CW\*(C`$^C = 1\*(C'\fR is similar to calling \f(CW\*(C`B::minus_c\*(C'\fR.
+.Sp
+This variable was added in Perl v5.6.0.
+.ie n .IP $DEBUGGING 8
+.el .IP \f(CW$DEBUGGING\fR 8
+.IX Item "$DEBUGGING"
+.PD 0
+.IP $^D 8
+.IX Xref "$^D $DEBUGGING"
+.IX Item "$^D"
+.PD
+The current value of the debugging flags.  May be read or set.  Like its
+command-line equivalent, you can use numeric
+or symbolic values, e.g. \f(CW\*(C`$^D = 10\*(C'\fR or \f(CW\*(C`$^D = "st"\*(C'\fR.  See
+"\fB\-D\fR\fInumber\fR" in perlrun.  The contents of this variable also affects the
+debugger operation.  See "Debugger Internals" in perldebguts.
+.Sp
+Mnemonic: value of \fB\-D\fR switch.
+.IP ${^GLOBAL_PHASE} 8
+.IX Xref "${^GLOBAL_PHASE}"
+.IX Item "${^GLOBAL_PHASE}"
+The current phase of the perl interpreter.
+.Sp
+Possible values are:
+.RS 8
+.IP CONSTRUCT 8
+.IX Item "CONSTRUCT"
+The \f(CW\*(C`PerlInterpreter*\*(C'\fR is being constructed via \f(CW\*(C`perl_construct\*(C'\fR.  This
+value is mostly there for completeness and for use via the
+underlying C variable \f(CW\*(C`PL_phase\*(C'\fR.  It's not really possible for Perl
+code to be executed unless construction of the interpreter is
+finished.
+.IP START 8
+.IX Item "START"
+This is the global compile-time.  That includes, basically, every
+\&\f(CW\*(C`BEGIN\*(C'\fR block executed directly or indirectly from during the
+compile-time of the top-level program.
+.Sp
+This phase is not called "BEGIN" to avoid confusion with
+\&\f(CW\*(C`BEGIN\*(C'\fR\-blocks, as those are executed during compile-time of any
+compilation unit, not just the top-level program.  A new, localised
+compile-time entered at run-time, for example by constructs as
+\&\f(CW\*(C`eval "use SomeModule"\*(C'\fR are not global interpreter phases, and
+therefore aren't reflected by \f(CW\*(C`${^GLOBAL_PHASE}\*(C'\fR.
+.IP CHECK 8
+.IX Item "CHECK"
+Execution of any \f(CW\*(C`CHECK\*(C'\fR blocks.
+.IP INIT 8
+.IX Item "INIT"
+Similar to "CHECK", but for \f(CW\*(C`INIT\*(C'\fR\-blocks, not \f(CW\*(C`CHECK\*(C'\fR blocks.
+.IP RUN 8
+.IX Item "RUN"
+The main run-time, i.e. the execution of \f(CW\*(C`PL_main_root\*(C'\fR.
+.IP END 8
+.IX Item "END"
+Execution of any \f(CW\*(C`END\*(C'\fR blocks.
+.IP DESTRUCT 8
+.IX Item "DESTRUCT"
+Global destruction.
+.RE
+.RS 8
+.Sp
+Also note that there's no value for UNITCHECK-blocks.  That's because
+those are run for each compilation unit individually, and therefore is
+not a global interpreter phase.
+.Sp
+Not every program has to go through each of the possible phases, but
+transition from one phase to another can only happen in the order
+described in the above list.
+.Sp
+An example of all of the phases Perl code can see:
+.Sp
+.Vb 1
+\&    BEGIN { print "compile\-time: ${^GLOBAL_PHASE}\en" }
+\&
+\&    INIT  { print "init\-time: ${^GLOBAL_PHASE}\en" }
+\&
+\&    CHECK { print "check\-time: ${^GLOBAL_PHASE}\en" }
+\&
+\&    {
+\&        package Print::Phase;
+\&
+\&        sub new {
+\&            my ($class, $time) = @_;
+\&            return bless \e$time, $class;
+\&        }
+\&
+\&        sub DESTROY {
+\&            my $self = shift;
+\&            print "$$self: ${^GLOBAL_PHASE}\en";
+\&        }
+\&    }
+\&
+\&    print "run\-time: ${^GLOBAL_PHASE}\en";
+\&
+\&    my $runtime = Print::Phase\->new(
+\&        "lexical variables are garbage collected before END"
+\&    );
+\&
+\&    END   { print "end\-time: ${^GLOBAL_PHASE}\en" }
+\&
+\&    our $destruct = Print::Phase\->new(
+\&        "package variables are garbage collected after END"
+\&    );
+.Ve
+.Sp
+This will print out
+.Sp
+.Vb 7
+\&    compile\-time: START
+\&    check\-time: CHECK
+\&    init\-time: INIT
+\&    run\-time: RUN
+\&    lexical variables are garbage collected before END: RUN
+\&    end\-time: END
+\&    package variables are garbage collected after END: DESTRUCT
+.Ve
+.Sp
+This variable was added in Perl 5.14.0.
+.RE
+.IP $^H 8
+.IX Xref "$^H"
+.IX Item "$^H"
+WARNING: This variable is strictly for
+internal use only.  Its availability,
+behavior, and contents are subject to change without notice.
+.Sp
+This variable contains compile-time hints for the Perl interpreter.  At the
+end of compilation of a BLOCK the value of this variable is restored to the
+value when the interpreter started to compile the BLOCK.
+.Sp
+Each time a statement completes being compiled, the current value of
+\&\f(CW$^H\fR is stored with that statement, and can later be retrieved via
+\&\f(CW\*(C`(caller($level))[8]\*(C'\fR.  See "caller EXPR" in perlfunc.
+.Sp
+When perl begins to parse any block construct that provides a lexical scope
+(e.g., eval body, required file, subroutine body, loop body, or conditional
+block), the existing value of \f(CW$^H\fR is saved, but its value is left unchanged.
+When the compilation of the block is completed, it regains the saved value.
+Between the points where its value is saved and restored, code that
+executes within BEGIN blocks is free to change the value of \f(CW$^H\fR.
+.Sp
+This behavior provides the semantic of lexical scoping, and is used in,
+for instance, the \f(CW\*(C`use strict\*(C'\fR pragma.
+.Sp
+The contents should be an integer; different bits of it are used for
+different pragmatic flags.  Here's an example:
+.Sp
+.Vb 1
+\&    sub add_100 { $^H |= 0x100 }
+\&
+\&    sub foo {
+\&        BEGIN { add_100() }
+\&        bar\->baz($boon);
+\&    }
+.Ve
+.Sp
+Consider what happens during execution of the BEGIN block.  At this point
+the BEGIN block has already been compiled, but the body of \f(CWfoo()\fR is still
+being compiled.  The new value of \f(CW$^H\fR
+will therefore be visible only while
+the body of \f(CWfoo()\fR is being compiled.
+.Sp
+Substitution of \f(CW\*(C`BEGIN { add_100() }\*(C'\fR block with:
+.Sp
+.Vb 1
+\&    BEGIN { require strict; strict\->import(\*(Aqvars\*(Aq) }
+.Ve
+.Sp
+demonstrates how \f(CW\*(C`use strict \*(Aqvars\*(Aq\*(C'\fR is implemented.  Here's a conditional
+version of the same lexical pragma:
+.Sp
+.Vb 3
+\&    BEGIN {
+\&        require strict; strict\->import(\*(Aqvars\*(Aq) if $condition
+\&    }
+.Ve
+.Sp
+This variable was added in Perl 5.003.
+.IP %^H 8
+.IX Xref "%^H"
+.IX Item "%^H"
+The \f(CW\*(C`%^H\*(C'\fR hash provides the same scoping semantics as \f(CW$^H\fR.  This
+makes it useful for implementing lexically scoped pragmas.  See perlpragma.
+All the entries are stringified when accessed at runtime, so only simple values
+can be accommodated.  This means no references to objects, for example.
+.Sp
+Each time a statement completes being compiled, the current value of
+\&\f(CW\*(C`%^H\*(C'\fR is stored with that statement, and can later be retrieved via
+\&\f(CW\*(C`(caller($level))[10]\*(C'\fR.  See "caller EXPR" in perlfunc.
+.Sp
+When putting items into \f(CW\*(C`%^H\*(C'\fR, in order to avoid conflicting with other
+users of the hash there is a convention regarding which keys to use.
+A module should use only keys that begin with the module's name (the
+name of its main package) and a "/" character.  For example, a module
+\&\f(CW\*(C`Foo::Bar\*(C'\fR should use keys such as \f(CW\*(C`Foo::Bar/baz\*(C'\fR.
+.Sp
+This variable was added in Perl v5.6.0.
+.IP ${^OPEN} 8
+.IX Xref "${^OPEN}"
+.IX Item "${^OPEN}"
+An internal variable used by PerlIO.  A string in two parts, separated
+by a \f(CW\*(C`\e0\*(C'\fR byte, the first part describes the input layers, the second
+part describes the output layers.
+.Sp
+This is the mechanism that applies the lexical effects of the open
+pragma, and the main program scope effects of the \f(CW\*(C`io\*(C'\fR or \f(CW\*(C`D\*(C'\fR options
+for the \-C command-line switch and
+PERL_UNICODE environment variable.
+.Sp
+The functions \f(CWaccept()\fR, \f(CWopen()\fR, \f(CWpipe()\fR, \f(CWreadpipe()\fR (as well
+as the related \f(CW\*(C`qx\*(C'\fR and \f(CW\`STRING\`\fR operators), \f(CWsocket()\fR,
+\&\f(CWsocketpair()\fR, and \f(CWsysopen()\fR are affected by the lexical value of
+this variable.  The implicit "ARGV" handle opened by \f(CWreadline()\fR (or
+the related \f(CW\*(C`<>\*(C'\fR and \f(CW\*(C`<<>>\*(C'\fR operators) on passed filenames is
+also affected (but not if it opens \f(CW\*(C`STDIN\*(C'\fR).  If this variable is not
+set, these functions will set the default layers as described in
+"Defaults and how to override them" in PerlIO.
+.Sp
+\&\f(CWopen()\fR ignores this variable (and the default layers) when called with
+3 arguments and explicit layers are specified.  Indirect calls to these
+functions via modules like IO::Handle are not affected as they occur
+in a different lexical scope.  Directory handles such as opened by
+\&\f(CWopendir()\fR are not currently affected.
+.Sp
+This variable was added in Perl v5.8.0.
+.ie n .IP $PERLDB 8
+.el .IP \f(CW$PERLDB\fR 8
+.IX Item "$PERLDB"
+.PD 0
+.IP $^P 8
+.IX Xref "$^P $PERLDB"
+.IX Item "$^P"
+.PD
+The internal variable for debugging support.  The meanings of the
+various bits are subject to change, but currently indicate:
+.RS 8
+.IP 0x01 6
+.IX Item "0x01"
+Debug subroutine enter/exit.
+.IP 0x02 6
+.IX Item "0x02"
+Line-by-line debugging.  Causes \f(CWDB::DB()\fR subroutine to be called for
+each statement executed.  Also causes saving source code lines (like
+0x400).
+.IP 0x04 6
+.IX Item "0x04"
+Switch off optimizations.
+.IP 0x08 6
+.IX Item "0x08"
+Preserve more data for future interactive inspections.
+.IP 0x10 6
+.IX Item "0x10"
+Keep info about source lines on which a subroutine is defined.
+.IP 0x20 6
+.IX Item "0x20"
+Start with single-step on.
+.IP 0x40 6
+.IX Item "0x40"
+Use subroutine address instead of name when reporting.
+.IP 0x80 6
+.IX Item "0x80"
+Report \f(CW\*(C`goto &subroutine\*(C'\fR as well.
+.IP 0x100 6
+.IX Item "0x100"
+Provide informative "file" names for evals based on the place they were compiled.
+.IP 0x200 6
+.IX Item "0x200"
+Provide informative names to anonymous subroutines based on the place they
+were compiled.
+.IP 0x400 6
+.IX Item "0x400"
+Save source code lines into \f(CW\*(C`@{"_<$filename"}\*(C'\fR.
+.IP 0x800 6
+.IX Item "0x800"
+When saving source, include evals that generate no subroutines.
+.IP 0x1000 6
+.IX Item "0x1000"
+When saving source, include source that did not compile.
+.RE
+.RS 8
+.Sp
+Some bits may be relevant at compile-time only, some at
+run-time only.  This is a new mechanism and the details may change.
+See also perldebguts.
+.RE
+.IP ${^TAINT} 8
+.IX Xref "${^TAINT}"
+.IX Item "${^TAINT}"
+Reflects if taint mode is on or off.  1 for on (the program was run with
+\&\fB\-T\fR), 0 for off, \-1 when only taint warnings are enabled (i.e. with
+\&\fB\-t\fR or \fB\-TU\fR).
+.Sp
+Note: if your perl was built without taint support (see perlsec),
+then \f(CW\*(C`${^TAINT}\*(C'\fR will always be 0, even if the program was run with \fB\-T\fR).
+.Sp
+This variable is read-only.
+.Sp
+This variable was added in Perl v5.8.0.
+.IP ${^SAFE_LOCALES} 8
+.IX Xref "${^SAFE_LOCALES}"
+.IX Item "${^SAFE_LOCALES}"
+Reflects if safe locale operations are available to this perl (when the
+value is 1) or not (the value is 0).  This variable is always 1 if the
+perl has been compiled without threads.  It is also 1 if this perl is
+using thread-safe locale operations.  Note that an individual thread may
+choose to use the global locale (generally unsafe) by calling
+"switch_to_global_locale" in perlapi.  This variable currently is still
+set to 1 in such threads.
+.Sp
+This variable is read-only.
+.Sp
+This variable was added in Perl v5.28.0.
+.IP ${^UNICODE} 8
+.IX Xref "${^UNICODE}"
+.IX Item "${^UNICODE}"
+Reflects certain Unicode settings of Perl.  See
+perlrun documentation for the \f(CW\*(C`\-C\*(C'\fR
+switch for more information about the possible values.
+.Sp
+This variable is set during Perl startup and is thereafter read-only.
+.Sp
+This variable was added in Perl v5.8.2.
+.IP ${^UTF8CACHE} 8
+.IX Xref "${^UTF8CACHE}"
+.IX Item "${^UTF8CACHE}"
+This variable controls the state of the internal UTF\-8 offset caching code.
+1 for on (the default), 0 for off, \-1 to debug the caching code by checking
+all its results against linear scans, and panicking on any discrepancy.
+.Sp
+This variable was added in Perl v5.8.9.  It is subject to change or
+removal without notice, but is currently used to avoid recalculating the
+boundaries of multi-byte UTF\-8\-encoded characters.
+.IP ${^UTF8LOCALE} 8
+.IX Xref "${^UTF8LOCALE}"
+.IX Item "${^UTF8LOCALE}"
+This variable indicates whether a UTF\-8 locale was detected by perl at
+startup.  This information is used by perl when it's in
+adjust\-utf8ness\-to\-locale mode (as when run with the \f(CW\*(C`\-CL\*(C'\fR command-line
+switch); see perlrun for more info on
+this.
+.Sp
+This variable was added in Perl v5.8.8.
+.SS "Deprecated and removed variables"
+.IX Subsection "Deprecated and removed variables"
+Deprecating a variable announces the intent of the perl maintainers to
+eventually remove the variable from the language.  It may still be
+available despite its status.  Using a deprecated variable triggers
+a warning.
+.PP
+Once a variable is removed, its use triggers an error telling you
+the variable is unsupported.
+.PP
+See perldiag for details about error messages.
+.IP $# 8
+.IX Xref "$#"
+\&\f(CW$#\fR was a variable that could be used to format printed numbers.
+After a deprecation cycle, its magic was removed in Perl v5.10.0 and
+using it now triggers a warning: \f(CW\*(C`$# is no longer supported\*(C'\fR.
+.Sp
+This is not the sigil you use in front of an array name to get the
+last index, like \f(CW$#array\fR.  That's still how you get the last index
+of an array in Perl.  The two have nothing to do with each other.
+.Sp
+Deprecated in Perl 5.
+.Sp
+Removed in Perl v5.10.0.
+.IP $* 8
+.IX Xref "$*"
+\&\f(CW$*\fR was a variable that you could use to enable multiline matching.
+After a deprecation cycle, its magic was removed in Perl v5.10.0.
+Using it now triggers a warning: \f(CW\*(C`$* is no longer supported\*(C'\fR.
+You should use the \f(CW\*(C`/s\*(C'\fR and \f(CW\*(C`/m\*(C'\fR regexp modifiers instead.
+.Sp
+Deprecated in Perl 5.
+.Sp
+Removed in Perl v5.10.0.
+.IP $[ 8
+.IX Xref "$["
+This variable stores the index of the first element in an array, and
+of the first character in a substring.  The default is 0, but you could
+theoretically set it to 1 to make Perl behave more like \fBawk\fR (or Fortran)
+when subscripting and when evaluating the \fBindex()\fR and \fBsubstr()\fR functions.
+.Sp
+As of release 5 of Perl, assignment to \f(CW$[\fR is treated as a compiler
+directive, and cannot influence the behavior of any other file.
+(That's why you can only assign compile-time constants to it.)
+Its use is highly discouraged.
+.Sp
+Prior to Perl v5.10.0, assignment to \f(CW$[\fR could be seen from outer lexical
+scopes in the same file, unlike other compile-time directives (such as
+strict).  Using \fBlocal()\fR on it would bind its value strictly to a lexical
+block.  Now it is always lexically scoped.
+.Sp
+As of Perl v5.16.0, it is implemented by the arybase module.
+.Sp
+As of Perl v5.30.0, or under \f(CW\*(C`use v5.16\*(C'\fR, or \f(CW\*(C`no feature "array_base"\*(C'\fR,
+\&\f(CW$[\fR no longer has any effect, and always contains 0.
+Assigning 0 to it is permitted, but any other value will produce an error.
+.Sp
+Mnemonic: [ begins subscripts.
+.Sp
+Deprecated in Perl v5.12.0.
+.IP ${^ENCODING} 8
+.IX Xref "${^ENCODING}"
+.IX Item "${^ENCODING}"
+This variable is no longer supported.
+.Sp
+It used to hold the \fIobject reference\fR to the \f(CW\*(C`Encode\*(C'\fR object that was
+used to convert the source code to Unicode.
+.Sp
+Its purpose was to allow your non-ASCII Perl
+scripts not to have to be written in UTF\-8; this was
+useful before editors that worked on UTF\-8 encoded text were common, but
+that was long ago.  It caused problems, such as affecting the operation
+of other modules that weren't expecting it, causing general mayhem.
+.Sp
+If you need something like this functionality, it is recommended that use
+you a simple source filter, such as Filter::Encoding.
+.Sp
+If you are coming here because code of yours is being adversely affected
+by someone's use of this variable, you can usually work around it by
+doing this:
+.Sp
+.Vb 1
+\& local ${^ENCODING};
+.Ve
+.Sp
+near the beginning of the functions that are getting broken.  This
+undefines the variable during the scope of execution of the including
+function.
+.Sp
+This variable was added in Perl 5.8.2 and removed in 5.26.0.
+Setting it to anything other than \f(CW\*(C`undef\*(C'\fR was made fatal in Perl 5.28.0.
+.IP ${^WIN32_SLOPPY_STAT} 8
+.IX Xref "${^WIN32_SLOPPY_STAT} sitecustomize sitecustomize.pl"
+.IX Item "${^WIN32_SLOPPY_STAT}"
+This variable no longer has any function.
+.Sp
+This variable was added in Perl v5.10.0 and removed in Perl v5.34.0.