a reference, you'll raise a run-time exception.
The following list is ordered by scalar variables first, then the
-arrays, then the hashes (except $^M was added in the wrong place).
-This is somewhat obscured because %ENV and %SIG are listed as
-$ENV{expr} and $SIG{expr}.
+arrays, then the hashes.
=over 8
=item *
-The default place to put an input record when a C<E<lt>FHE<gt>>
+The default place to put an input record when a C<< <FH> >>
operation's result is tested by itself as the sole criterion of a C<while>
test. Outside a C<while> test, this will not happen.
=over 8
-=item $E<lt>I<digits>E<gt>
+=item $a
+
+=item $b
+
+Special package variables when using sort(), see L<perlfunc/sort>.
+Because of this specialness $a and $b don't need to be declared
+(using local(), use vars, or our()) even when using the strict
+vars pragma. Don't lexicalize them with C<my $a> or C<my $b>
+if you want to be able to use them in the sort() comparison block
+or function.
+
+=back
+
+=over 8
+
+=item $<I<digits>>
Contains the subpattern from the corresponding set of capturing
parentheses from the last pattern match, not counting patterns
=item $+
-The last bracket matched by the last search pattern. This is useful if
-you don't know which one of a set of alternative patterns matched. For
-example:
+The text matched by the last bracket of the last successful search pattern.
+This is useful if you don't know which one of a set of alternative patterns
+matched. For example:
/Version: (.*)|Revision: (.*)/ && ($rev = $+);
(Mnemonic: be positive and forward looking.)
This variable is read-only and dynamically scoped to the current BLOCK.
-=item @+
+=item $^N
-$+[0] is the offset of the end of the last successful match.
-C<$+[>I<n>C<]> is the offset of the end of the substring matched by
-I<n>-th subpattern, or undef if the subpattern did not match.
+The text matched by the used group most-recently closed (i.e. the group
+with the rightmost closing parenthesis) of the last successful search
+pattern. (Mnemonic: the (possibly) Nested parenthesis that most
+recently closed.)
-Thus after a match against $_, $& coincides with C<substr $_, $-[0],
-$+[0] - $-[0]>. Similarly, C<$>I<n> coincides with C<substr $_, $-[>I<n>C<],
-$+[>I<n>C<] - $-[>I<n>C<]> if C<$-[>I<n>C<]> is defined, and $+ coincides with
-C<substr $_, $-[$#-], $+[$#-]>. One can use C<$#+> to find the number
-of subgroups in the last successful match. Contrast with
-C<$#->, the last I<matched> subgroup. Compare with C<@->.
+This is primarly used inside C<(?{...})> blocks for examining text
+recently matched. For example, to effectively capture text to a variable
+(in addition to C<$1>, C<$2>, etc.), replace C<(...)> with
+
+ (?:(...)(?{ $var = $^N }))
+
+By setting and then using C<$var> in this way relieves you from having to
+worry about exactly which numbered set of parentheses they are.
+
+This variable is dynamically scoped to the current BLOCK.
+
+=item @LAST_MATCH_END
+
+=item @+
+
+This array holds the offsets of the ends of the last successful
+submatches in the currently active dynamic scope. C<$+[0]> is
+the offset into the string of the end of the entire match. This
+is the same value as what the C<pos> function returns when called
+on the variable that was matched against. The I<n>th element
+of this array holds the offset of the I<n>th submatch, so
+C<$+[1]> is the offset past where $1 ends, C<$+[2]> the offset
+past where $2 ends, and so on. You can use C<$#+> to determine
+how many subgroups were in the last successful match. See the
+examples given for the C<@-> variable.
=item $MULTILINE_MATCHING
=item $*
-Set to 1 to do multi-line matching within a string, 0 to tell Perl
-that it can assume that strings contain a single line, for the purpose
-of optimizing pattern matches. Pattern matches on strings containing
-multiple newlines can produce confusing results when C<$*> is 0. Default
-is 0. (Mnemonic: * matches multiple things.) This variable
-influences the interpretation of only C<^> and C<$>. A literal newline can
-be searched for even when C<$* == 0>.
+Set to a non-zero integer value to do multi-line matching within a
+string, 0 (or undefined) to tell Perl that it can assume that strings
+contain a single line, for the purpose of optimizing pattern matches.
+Pattern matches on strings containing multiple newlines can produce
+confusing results when C<$*> is 0 or undefined. Default is undefined.
+(Mnemonic: * matches multiple things.) This variable influences the
+interpretation of only C<^> and C<$>. A literal newline can be searched
+for even when C<$* == 0>.
Use of C<$*> is deprecated in modern Perl, supplanted by
the C</s> and C</m> modifiers on pattern matching.
-=item input_line_number HANDLE EXPR
+Assigning a non-numerical value to C<$*> triggers a warning (and makes
+C<$*> act if C<$* == 0>), while assigning a numerical value to C<$*>
+makes that an implicit C<int> is applied on the value.
+
+=item HANDLE->input_line_number(EXPR)
=item $INPUT_LINE_NUMBER
=item $.
-The current input record number for the last file handle from which
-you just read() (or called a C<seek> or C<tell> on). The value
-may be different from the actual physical line number in the file,
-depending on what notion of "line" is in effect--see C<$/> on how
-to change that. An explicit close on a filehandle resets the line
-number. Because C<E<lt>E<gt>> never does an explicit close, line
-numbers increase across ARGV files (but see examples in L<perlfunc/eof>).
-Consider this variable read-only: setting it does not reposition
-the seek pointer; you'll have to do that on your own. Localizing C<$.>
-has the effect of also localizing Perl's notion of "the last read
-filehandle". (Mnemonic: many programs use "." to mean the current line
-number.)
-
-=item input_record_separator HANDLE EXPR
+Current line number for the last filehandle accessed.
+
+Each filehandle in Perl counts the number of lines that have been read
+from it. (Depending on the value of C<$/>, Perl's idea of what
+constitutes a line may not match yours.) When a line is read from a
+filehandle (via readline() or C<< <> >>), or when tell() or seek() is
+called on it, C<$.> becomes an alias to the line counter for that
+filehandle.
+
+You can adjust the counter by assigning to C<$.>, but this will not
+actually move the seek pointer. I<Localizing C<$.> will not localize
+the filehandle's line count>. Instead, it will localize perl's notion
+of which filehandle C<$.> is currently aliased to.
+
+C<$.> is reset when the filehandle is closed, but B<not> when an open
+filehandle is reopened without an intervening close(). For more
+details, see L<perlop/"I/O Operators">. Because C<< <> >> never does
+an explicit close, line numbers increase across ARGV files (but see
+examples in L<perlfunc/eof>).
+
+You can also use C<< HANDLE->input_line_number(EXPR) >> to access the
+line counter for a given filehandle without having to worry about
+which handle you last accessed.
+
+(Mnemonic: many programs use "." to mean the current line number.)
+
+=item IO::Handle->input_record_separator(EXPR)
=item $INPUT_RECORD_SEPARATOR
On VMS, record reads are done with the equivalent of C<sysread>,
so it's best not to mix record and non-record reads on the same
file. (This is unlikely to be a problem, because any file you'd
-want to read in record mode is probably usable in line mode.)
+want to read in record mode is probably unusable in line mode.)
Non-VMS systems do normal I/O, so it's safe to mix record and
non-record reads of a file.
See also L<perlport/"Newlines">. Also see C<$.>.
-=item autoflush HANDLE EXPR
+=item HANDLE->autoflush(EXPR)
=item $OUTPUT_AUTOFLUSH
happening. This has no effect on input buffering. See L<perlfunc/getc>
for that. (Mnemonic: when you want your pipes to be piping hot.)
-=item output_field_separator HANDLE EXPR
+=item IO::Handle->output_field_separator EXPR
=item $OUTPUT_FIELD_SEPARATOR
between fields. (Mnemonic: what is printed when there is a "," in
your print statement.)
-=item output_record_separator HANDLE EXPR
+=item IO::Handle->output_record_separator EXPR
=item $OUTPUT_RECORD_SEPARATOR
Use of C<$#> is deprecated.
-=item format_page_number HANDLE EXPR
+=item HANDLE->format_page_number(EXPR)
=item $FORMAT_PAGE_NUMBER
Used with formats.
(Mnemonic: % is page number in B<nroff>.)
-=item format_lines_per_page HANDLE EXPR
+=item HANDLE->format_lines_per_page(EXPR)
=item $FORMAT_LINES_PER_PAGE
Used with formats.
(Mnemonic: = has horizontal lines.)
-=item format_lines_left HANDLE EXPR
+=item HANDLE->format_lines_left(EXPR)
=item $FORMAT_LINES_LEFT
Used with formats.
(Mnemonic: lines_on_page - lines_printed.)
+=item @LAST_MATCH_START
+
=item @-
$-[0] is the offset of the start of the last successful match.
C<$#+>, the number of subgroups in the regular expression. Compare
with C<@+>.
-=item format_name HANDLE EXPR
+This array holds the offsets of the beginnings of the last
+successful submatches in the currently active dynamic scope.
+C<$-[0]> is the offset into the string of the beginning of the
+entire match. The I<n>th element of this array holds the offset
+of the I<n>th submatch, so C<$-[1]> is the offset where $1
+begins, C<$-[2]> the offset where $2 begins, and so on.
+
+After a match against some variable $var:
+
+=over 5
+
+=item C<$`> is the same as C<substr($var, 0, $-[0])>
+
+=item C<$&> is the same as C<substr($var, $-[0], $+[0] - $-[0])>
+
+=item C<$'> is the same as C<substr($var, $+[0])>
+
+=item C<$1> is the same as C<substr($var, $-[1], $+[1] - $-[1])>
+
+=item C<$2> is the same as C<substr($var, $-[2], $+[2] - $-[2])>
+
+=item C<$3> is the same as C<substr $var, $-[3], $+[3] - $-[3])>
+
+=back
+
+=item HANDLE->format_name(EXPR)
=item $FORMAT_NAME
channel. Default is the name of the filehandle. (Mnemonic: brother to
C<$^>.)
-=item format_top_name HANDLE EXPR
+=item HANDLE->format_top_name(EXPR)
=item $FORMAT_TOP_NAME
output channel. Default is the name of the filehandle with _TOP
appended. (Mnemonic: points to top of page.)
-=item format_line_break_characters HANDLE EXPR
+=item IO::Handle->format_line_break_characters EXPR
=item $FORMAT_LINE_BREAK_CHARACTERS
S<" \n-">, to break on whitespace or hyphens. (Mnemonic: a "colon" in
poetry is a part of a line.)
-=item format_formfeed HANDLE EXPR
+=item IO::Handle->format_formfeed EXPR
=item $FORMAT_FORMFEED
successful call to wait() or waitpid(), or from the system()
operator. This is just the 16-bit status word returned by the
wait() system call (or else is made up to look like it). Thus, the
-exit value of the subprocess is really (C<$? E<gt>E<gt> 8>), and
+exit value of the subprocess is really (C<<< $? >> 8 >>>), and
C<$? & 127> gives which signal, if any, the process died from, and
C<$? & 128> reports whether there was a core dump. (Mnemonic:
similar to B<sh> and B<ksh>.)
Under VMS, the pragma C<use vmsish 'status'> makes C<$?> reflect the
actual VMS exit status, instead of the default emulation of POSIX
-status.
+status; see L<perlvms/$?> for details.
Also see L<Error Indicators>.
=item $@
-The Perl syntax error message from the last eval() operator. If null, the
-last eval() parsed and executed correctly (although the operations you
-invoked may have failed in the normal fashion). (Mnemonic: Where was
-the syntax error "at"?)
+The Perl syntax error message from the last eval() operator.
+If $@ is the null string, the last eval() parsed and executed
+correctly (although the operations you invoked may have failed in the
+normal fashion). (Mnemonic: Where was the syntax error "at"?)
Warning messages are not collected in this variable. You can,
however, set up a routine to process warnings by setting C<$SIG{__WARN__}>
=item $<
The real uid of this process. (Mnemonic: it's the uid you came I<from>,
-if you're running setuid.)
+if you're running setuid.) You can change both the real uid and
+the effective uid at the same time by using POSIX::setuid().
=item $EFFECTIVE_USER_ID
$< = $>; # set real to effective uid
($<,$>) = ($>,$<); # swap real and effective uid
+You can change both the effective uid and the real uid at the same
+time by using POSIX::setuid().
+
(Mnemonic: it's the uid you went I<to>, if you're running setuid.)
-C<$E<lt>> and C<$E<gt>> can be swapped only on machines
+C<< $< >> and C<< $> >> can be swapped only on machines
supporting setreuid().
=item $REAL_GROUP_ID
set the real gid. So the value given by C<$(> should I<not> be assigned
back to C<$(> without being forced numeric, such as by adding zero.
+You can change both the real gid and the effective gid at the same
+time by using POSIX::setgid().
+
(Mnemonic: parentheses are used to I<group> things. The real gid is the
group you I<left>, if you're running setgid.)
to force an effective gid of 5 and an effectively empty setgroups()
list, say C< $) = "5 5" >.
+You can change both the effective gid and the real gid at the same
+time by using POSIX::setgid() (use only a single numeric argument).
+
(Mnemonic: parentheses are used to I<group> things. The effective gid
is the group that's I<right> for you, if you're running setgid.)
-C<$E<lt>>, C<$E<gt>>, C<$(> and C<$)> can be set only on
+C<< $< >>, C<< $> >>, C<$(> and C<$)> can be set only on
machines that support the corresponding I<set[re][ug]id()> routine. C<$(>
and C<$)> can be swapped only on machines supporting setregid().
program state than it is for hiding the program you're running.
(Mnemonic: same as B<sh> and B<ksh>.)
+Note for BSD users: setting C<$0> does not completely remove "perl"
+from the ps(1) output. For example, setting C<$0> to C<"foobar"> will
+result in C<"perl: foobar (perl)">. This is an operating system
+feature.
+
=item $[
The index of the first element in an array, and of the first character
directive, and cannot influence the behavior of any other file.
Its use is highly discouraged.
-=item $PERL_VERSION
-
=item $]
The version + patchlevel / 1000 of the Perl interpreter. This variable
See also the documentation of C<use VERSION> and C<require VERSION>
for a convenient way to fail if the running Perl interpreter is too old.
+The use of this variable is deprecated. The floating point representation
+can sometimes lead to inaccurate numeric comparisons. See C<$^V> for a
+more modern representation of the Perl version that allows accurate string
+comparisons.
+
=item $COMPILING
=item $^C
preserved even if the open() fails. (Ordinary file descriptors are
closed before the open() is attempted.) The close-on-exec
status of a file descriptor will be decided according to the value of
-C<$^F> when the open() or pipe() was called, not the time of the exec().
+C<$^F> when the corresponding file, pipe, or socket was opened, not the
+time of the exec().
=item $^H
-The current set of syntax checks enabled by C<use strict> and other block
-scoped compiler hints. See the documentation of C<strict> for more details.
+WARNING: This variable is strictly for internal use only. Its availability,
+behavior, and contents are subject to change without notice.
+
+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.
+
+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 $^H 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 $^H.
+
+This behavior provides the semantic of lexical scoping, and is used in,
+for instance, the C<use strict> pragma.
+
+The contents should be an integer; different bits of it are used for
+different pragmatic flags. Here's an example:
+
+ sub add_100 { $^H |= 0x100 }
+
+ sub foo {
+ BEGIN { add_100() }
+ bar->baz($boon);
+ }
+
+Consider what happens during execution of the BEGIN block. At this point
+the BEGIN block has already been compiled, but the body of foo() is still
+being compiled. The new value of $^H will therefore be visible only while
+the body of foo() is being compiled.
+
+Substitution of the above BEGIN block with:
+
+ BEGIN { require strict; strict->import('vars') }
+
+demonstrates how C<use strict 'vars'> is implemented. Here's a conditional
+version of the same lexical pragma:
+
+ BEGIN { require strict; strict->import('vars') if $condition }
+
+=item %^H
+
+WARNING: This variable is strictly for internal use only. Its availability,
+behavior, and contents are subject to change without notice.
+
+The %^H hash provides the same scoping semantic as $^H. This makes it
+useful for implementation of lexically scoped pragmas.
=item $INPLACE_EDIT
$^M = 'a' x (1 << 16);
-would allocate a 64K buffer for use when in emergency. See the
+would allocate a 64K buffer for use in an emergency. See the
F<INSTALL> file in the Perl distribution for information on how to
enable this option. To discourage casual use of this advanced
-feature, there is no L<English> long name for this variable.
+feature, there is no L<English|English> long name for this variable.
=item $OSNAME
Start with single-step on.
+=item 0x40
+
+Use subroutine address instead of name when reporting.
+
+=item 0x80
+
+Report C<goto &subroutine> as well.
+
+=item 0x100
+
+Provide informative "file" names for evals based on the place they were compiled.
+
+=item 0x200
+
+Provide informative names to anonymous subroutines based on the place they
+were compiled.
+
=back
Some bits may be relevant at compile-time only, some at
run-time only. This is a new mechanism and the details may change.
+=item $LAST_REGEXP_CODE_RESULT
+
=item $^R
The result of evaluation of the last successful C<(?{ code })>
regular expression assertion (see L<perlre>). May be written to.
+=item $EXCEPTIONS_BEING_CAUGHT
+
=item $^S
Current state of the interpreter. Undefined if parsing of the current
epoch (beginning of 1970). The values returned by the B<-M>, B<-A>,
and B<-C> filetests are based on this value.
+=item $PERL_VERSION
+
+=item $^V
+
+The revision, version, and subversion of the Perl interpreter, represented
+as a string composed of characters with those ordinals. Thus in Perl v5.6.0
+it equals C<chr(5) . chr(6) . chr(0)> and will return true for
+C<$^V eq v5.6.0>. Note that the characters in this string value can
+potentially be in Unicode range.
+
+This can be used to determine whether the Perl interpreter executing a
+script is in the right range of versions. (Mnemonic: use ^V for Version
+Control.) Example:
+
+ warn "No \"our\" declarations!\n" if $^V and $^V lt v5.6.0;
+
+See the documentation of C<use VERSION> and C<require VERSION>
+for a convenient way to fail if the running Perl interpreter is too old.
+
+See also C<$]> for an older representation of the Perl version.
+
=item $WARNING
=item $^W
The current value of the warning switch, initially true if B<-w>
was used, false otherwise, but directly modifiable. (Mnemonic:
-related to the B<-w> switch.) See also L<warning>.
+related to the B<-w> switch.) See also L<warnings>.
+
+=item ${^WARNING_BITS}
+
+The current set of warning checks enabled by the C<use warnings> pragma.
+See the documentation of C<warnings> for more details.
+
+=item ${^WIDE_SYSTEM_CALLS}
+
+Global flag that enables system calls made by Perl to use wide character
+APIs native to the system, if available. This is currently only implemented
+on the Windows platform.
+
+This can also be enabled from the command line using the C<-C> switch.
+
+The initial value is typically C<0> for compatibility with Perl versions
+earlier than 5.6, but may be automatically set to C<1> by Perl if the system
+provides a user-settable default (e.g., C<$ENV{LC_CTYPE}>).
+
+The C<bytes> pragma always overrides the effect of this flag in the current
+lexical scope. See L<bytes>.
=item $EXECUTABLE_NAME
=item $ARGV
-contains the name of the current file when reading from E<lt>E<gt>.
+contains the name of the current file when reading from <>.
=item @ARGV
one, because C<$ARGV[0]> is the first argument, I<not> the program's
command name itself. See C<$0> for the command name.
+=item @F
+
+The array @F contains the fields of each line read in when autosplit
+mode is turned on. See L<perlrun> for the B<-a> switch. This array
+is package-specific, and must be declared or given a full package name
+if not in package main when running under C<strict 'vars'>.
+
=item @INC
The array @INC contains the list of places that the C<do EXPR>,
C<do>, C<require>, or C<use> 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 C<require>
-operator uses this array to determine whether a particular file has
+operator uses this hash to determine whether a particular file has
already been included.
=item %ENV
not available.
See L<perlfunc/die>, L<perlfunc/warn>, L<perlfunc/eval>, and
-L<warning> for additional information.
+L<warnings> for additional information.
=back
(which will interpolate C<$!> and C<$?>!). (See also L<Fatal>,
though.)
-When the eval() expression above is executed, open(), C<<PIPEE<gt>>,
+When the eval() expression above is executed, open(), C<< <PIPE> >>,
and C<close> are translated to calls in the C run-time library and
thence to the operating system kernel. C<$!> is set to the C library's
C<errno> if one of these calls fails.
control-C<W>. This is better than typing a literal control-C<W>
into your program.
-Finally, new in Perl 5.006, Perl variable names may be alphanumeric
+Finally, new in Perl 5.6, Perl variable names may be alphanumeric
strings that begin with control characters (or better yet, a caret).
These variables must be written in the form C<${^Foo}>; the braces
are not optional. C<${^Foo}> denotes the scalar variable whose
in the scope of C<use English>. For that reason, saying C<use
English> in libraries is strongly discouraged. See the
Devel::SawAmpersand module documentation from CPAN
-(http://www.perl.com/CPAN/modules/by-module/Devel/Devel-SawAmpersand-0.10.readme)
+(http://www.perl.com/CPAN/modules/by-module/Devel/)
for more information.
Having to even think about the C<$^S> variable in your exception