=head1 DESCRIPTION
-=head2 Predefined Names
+=head2 The Syntax of Variable Names
-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
-
- use English;
-
-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 B<awk>. In general, it's best to use the
-
- use English '-no_match_vars';
-
-invocation if you don't need $PREMATCH, $MATCH, or $POSTMATCH, as it avoids
-a certain performance hit with the use of regular expressions. See
-L<English>.
-
-Variables that depend on the currently selected filehandle may be set by
-calling an appropriate object method on the IO::Handle 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
-
- use IO::Handle;
-
-after which you may use either
-
- method HANDLE EXPR
-
-or more safely,
-
- HANDLE->method(EXPR)
-
-Each method returns the old value of the IO::Handle attribute.
-The methods each take an optional EXPR, which, if supplied, specifies the
-new value for the IO::Handle attribute in question. If not supplied,
-most methods do nothing to the current value--except for
-autoflush(), which will assume a 1 for you, just to be different.
-
-Because loading in the IO::Handle class is an expensive operation, you should
-learn how to use the regular built-in variables.
-
-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.
-
-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:
-
- open my $fh, "<", "foo" or die $!;
- local $/; # enable localized slurp mode
- my $content = <$fh>;
- close $fh;
-
-But the following code is quite bad:
-
- open my $fh, "<", "foo" or die $!;
- undef $/; # enable slurp mode
- my $content = <$fh>;
- close $fh;
-
-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 C<$/> is now changed for any other code
-running inside the same Perl interpreter.
+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
+C<::> or C<'>. In this case, the part before the last C<::> or
+C<'> is taken to be a I<package qualifier>; see L<perlmod>.
-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 C<{}> block, you should create one yourself. For
-example:
+Perl variable names may also be a sequence of digits or a single
+punctuation or control character. 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. Perl has a special syntax for the single-control-character
+names: It understands C<^X> (caret C<X>) to mean the control-C<X>
+character. For example, the notation C<$^W> (dollar-sign caret
+C<W>) is the scalar variable whose name is the single character
+control-C<W>. This is better than typing a literal control-C<W>
+into your program.
- my $content = '';
- open my $fh, "<", "foo" or die $!;
- {
- local $/;
- $content = <$fh>;
- }
- close $fh;
+Since Perl v5.6.0, 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
+name is a control-C<F> followed by two C<o>'s. These variables are
+reserved for future special uses by Perl, except for the ones that
+begin with C<^_> (control-underscore or caret-underscore). No
+control-character name that begins with C<^_> will acquire a special
+meaning in any future version of Perl; such names may therefore be
+used safely in programs. C<$^_> itself, however, I<is> reserved.
-Here is an example of how your own code can go broken:
+Perl identifiers that begin with digits, control characters, or
+punctuation characters are exempt from the effects of the C<package>
+declaration and are always forced to be in package C<main>; they are
+also exempt from C<strict 'vars'> errors. A few other names are also
+exempt in these ways:
- for (1..5){
- nasty_break();
- print "$_ ";
- }
- sub nasty_break {
- $_ = 5;
- # do something with $_
- }
+ ENV STDIN
+ INC STDOUT
+ ARGV STDERR
+ ARGVOUT
+ SIG
-You probably expect this code to print:
+In particular, the special C<${^_XYZ}> variables are always taken
+to be in package C<main>, regardless of any C<package> declarations
+presently in scope.
- 1 2 3 4 5
+=head1 SPECIAL VARIABLES
-but instead you get:
+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:
- 5 5 5 5 5
+ use English;
-Why? Because nasty_break() modifies C<$_> without localizing it
-first. The fix is to add local():
+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 B<awk>. To avoid a performance hit, if you don't need the
+C<$PREMATCH>, C<$MATCH>, or C<$POSTMATCH> it's best to use the C<English>
+module without them:
- local $_ = 5;
+ use English '-no_match_vars';
-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.
+Before you continue, note the sort order for variables. In general, we
+first list the variables in case-insensitive, almost-lexigraphical
+order (ignoring the C<{> or C<^> preceding words, as in C<${^UNICODE}>
+or C<$^T>), although C<$_> and C<@_> 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.
-The following list is ordered by scalar variables first, then the
-arrays, then the hashes.
+=head2 General Variables
=over 8
The default input and pattern-searching space. The following pairs are
equivalent:
- while (<>) {...} # equivalent only in while!
+ while (<>) {...} # equivalent only in while!
while (defined($_ = <>)) {...}
/^Subject:/
chomp
chomp($_)
-Here are the places where Perl will assume $_ even if you
-don't use it:
+Here are the places where Perl will assume C<$_> even if you don't use it:
=over 3
=item *
-The following functions:
+The following functions use C<$_> as a default argument:
-abs, alarm, chomp, chop, chr, chroot, cos, defined, eval, exp, glob,
-hex, int, lc, lcfirst, length, log, lstat, mkdir, oct, ord, pos, print,
+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, sin, split (on its second argument), sqrt, stat, study, uc, ucfirst,
+rmdir, say, sin, split (for its second
+argument), sqrt, stat, study, uc, ucfirst,
unlink, unpack.
=item *
All file tests (C<-f>, C<-d>) except for C<-t>, which defaults to STDIN.
See L<perlfunc/-X>
-
=item *
The pattern matching operations C<m//>, C<s///> and C<tr///> (aka C<y///>)
=item *
-The implicit iterator variable in the grep() and map() functions.
+The implicit iterator variable in the C<grep()> and C<map()> functions.
=item *
-The implicit variable of given().
+The implicit variable of C<given()>.
=item *
-The default place to put an input record when a C<< <FH> >>
+The default place to put the next value or input record
+when a C<< <FH> >>, C<readline>, C<readdir> or C<each>
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.
=back
-As C<$_> is a global variable, this may lead in some cases to unwanted
-side-effects. As of perl 5.9.1, you can now use a lexical version of
+C<$_> is by default a global variable. However, as
+of perl v5.10.0, you can use a lexical version of
C<$_> by declaring it in a file or in a block with C<my>. Moreover,
-declaring C<our $_> restores the global C<$_> in the current scope.
+declaring C<our $_> restores the global C<$_> in the current scope. Though
+this seemed like a good idea at the time it was introduced, lexical C<$_>
+actually causes more problems than it solves. If you call a function that
+expects to be passed information via C<$_>, it may or may not work,
+depending on how the function is written, there not being any easy way to
+solve this. Just avoid lexical C<$_>, unless you are feeling particularly
+masochistic. For this reason lexical C<$_> is still experimental and will
+produce a warning unless warnings have been disabled. As with other
+experimental features, the behavior of lexical C<$_> is subject to change
+without notice, including change into a fatal error.
+
+Mnemonic: underline is understood in certain operations.
-(Mnemonic: underline is understood in certain operations.)
+=item @ARG
-=back
+=item @_
+X<@_> X<@ARG>
-=over 8
+Within a subroutine the array C<@_> contains the parameters passed to
+that subroutine. Inside a subroutine, C<@_> is the default array for
+the array operators C<push>, C<pop>, C<shift>, and C<unshift>.
-=item $a
+See L<perlsub>.
-=item $b
-X<$a> X<$b>
+=item $LIST_SEPARATOR
-Special package variables when using sort(), see L<perlfunc/sort>.
-Because of this specialness $a and $b don't need to be declared
-(using use vars, or our()) even when using the C<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.
+=item $"
+X<$"> X<$LIST_SEPARATOR>
-=back
+When an array or an array slice is interpolated into a double-quoted
+string or a similar context such as C</.../>, its elements are
+separated by this value. Default is a space. For example, this:
-=over 8
+ print "The array is: @array\n";
-=item $<I<digits>> ($1, $2, ...)
-X<$1> X<$2> X<$3>
+is equivalent to this:
-Contains the subpattern from the corresponding set of capturing
-parentheses from the last successful pattern match, not counting patterns
-matched in nested blocks that have been exited already. (Mnemonic:
-like \digits.) These variables are all read-only and dynamically
-scoped to the current BLOCK.
+ print "The array is: " . join($", @array) . "\n";
-=item $MATCH
+Mnemonic: works in double-quoted context.
-=item $&
-X<$&> X<$MATCH>
+=item $PROCESS_ID
-The string matched by the last successful pattern match (not counting
-any matches hidden within a BLOCK or eval() enclosed by the current
-BLOCK). (Mnemonic: like & in some editors.) This variable is read-only
-and dynamically scoped to the current BLOCK.
+=item $PID
-The use of this variable anywhere in a program imposes a considerable
-performance penalty on all regular expression matches. See L</BUGS>.
+=item $$
+X<$$> X<$PID> X<$PROCESS_ID>
-See L</@-> for a replacement.
+The process number of the Perl running this script. Though you I<can> set
+this variable, doing so is generally discouraged, although it can be
+invaluable for some testing purposes. It will be reset automatically
+across C<fork()> calls.
-=item ${^MATCH}
-X<${^MATCH}>
+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).
-This is similar to C<$&> (C<$MATCH>) except that it does not incur the
-performance penalty associated with that variable, and is only guaranteed
-to return a defined value when the pattern was compiled or executed with
-the C</p> modifier.
+LinuxThreads is now obsolete on Linux, and caching C<getpid()>
+like this made embedding perl unnecessarily complex (since you'd have
+to manually update the value of $$), so now C<$$> and C<getppid()>
+will always return the same values as the underlying C library.
-=item $PREMATCH
+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.
-=item $`
-X<$`> X<$PREMATCH>
+To see if your system is affected by this discrepancy check if
+C<getconf GNU_LIBPTHREAD_VERSION | grep -q NPTL> returns a false
+value. NTPL threads preserve the POSIX semantics.
-The string preceding whatever was matched by the last successful
-pattern match (not counting any matches hidden within a BLOCK or eval
-enclosed by the current BLOCK). (Mnemonic: C<`> often precedes a quoted
-string.) This variable is read-only.
+Mnemonic: same as shells.
-The use of this variable anywhere in a program imposes a considerable
-performance penalty on all regular expression matches. See L</BUGS>.
+=item $PROGRAM_NAME
-See L</@-> for a replacement.
+=item $0
+X<$0> X<$PROGRAM_NAME>
-=item ${^PREMATCH}
-X<${^PREMATCH}>
+Contains the name of the program being executed.
-This is similar to C<$`> ($PREMATCH) except that it does not incur the
-performance penalty associated with that variable, and is only guaranteed
-to return a defined value when the pattern was compiled or executed with
-the C</p> modifier.
+On some (but not all) operating systems assigning to C<$0> modifies
+the argument area that the C<ps> program sees. On some platforms you
+may have to use special C<ps> options or a different C<ps> to see the
+changes. Modifying the C<$0> is more useful as a way of indicating the
+current program state than it is for hiding the program you're
+running.
-=item $POSTMATCH
+Note that there are platform-specific limitations on the maximum
+length of C<$0>. In the most extreme case it may be limited to the
+space occupied by the original C<$0>.
-=item $'
-X<$'> X<$POSTMATCH>
+In some platforms there may be arbitrary amount of padding, for
+example space characters, after the modified name as shown by C<ps>.
+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).
-The string following whatever was matched by the last successful
-pattern match (not counting any matches hidden within a BLOCK or eval()
-enclosed by the current BLOCK). (Mnemonic: C<'> often follows a quoted
-string.) Example:
+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"> may
+result in C<"perl: foobar (perl)"> (whether both the C<"perl: "> 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.
- local $_ = 'abcdefghi';
- /def/;
- print "$`:$&:$'\n"; # prints abc:def:ghi
+In multithreaded scripts Perl coordinates the threads so that any
+thread may modify its copy of the C<$0> and the change becomes visible
+to ps(1) (assuming the operating system plays along). Note that
+the view of C<$0> the other threads have will not change since they
+have their own copies of it.
-This variable is read-only and dynamically scoped to the current BLOCK.
+If the program has been given to perl via the switches C<-e> or C<-E>,
+C<$0> will contain the string C<"-e">.
-The use of this variable anywhere in a program imposes a considerable
-performance penalty on all regular expression matches. See L</BUGS>.
+On Linux as of perl v5.14.0 the legacy process name will be set with
+C<prctl(2)>, in addition to altering the POSIX name via C<argv[0]> 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 C<$0>. The string you supply will be
+cut off at 16 bytes, this is a limitation imposed by Linux.
-See L</@-> for a replacement.
+Mnemonic: same as B<sh> and B<ksh>.
-=item ${^POSTMATCH}
-X<${^POSTMATCH}>
+=item $REAL_GROUP_ID
-This is similar to C<$'> (C<$POSTMATCH>) except that it does not incur the
-performance penalty associated with that variable, and is only guaranteed
-to return a defined value when the pattern was compiled or executed with
-the C</p> modifier.
+=item $GID
-=item $LAST_PAREN_MATCH
+=item $(
+X<$(> X<$GID> X<$REAL_GROUP_ID>
-=item $+
-X<$+> X<$LAST_PAREN_MATCH>
+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
+C<getgid()>, and the subsequent ones by C<getgroups()>, one of which may be
+the same as the first number.
-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:
+However, a value assigned to C<$(> must be a single number used to
+set the real gid. So the value given by C<$(> should I<not> be assigned
+back to C<$(> without being forced numeric, such as by adding zero. Note
+that this is different to the effective gid (C<$)>) which does take a
+list.
- /Version: (.*)|Revision: (.*)/ && ($rev = $+);
+You can change both the real gid and the effective gid at the same
+time by using C<POSIX::setgid()>. Changes
+to C<$(> require a check to C<$!>
+to detect any possible errors after an attempted change.
-(Mnemonic: be positive and forward looking.)
-This variable is read-only and dynamically scoped to the current BLOCK.
+Mnemonic: parentheses are used to I<group> things. The real gid is the
+group you I<left>, if you're running setgid.
-=item $LAST_SUBMATCH_RESULT
+=item $EFFECTIVE_GROUP_ID
-=item $^N
-X<$^N>
+=item $EGID
-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.)
+=item $)
+X<$)> X<$EGID> X<$EFFECTIVE_GROUP_ID>
-This is primarily 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
+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 C<getegid()>, and the subsequent ones by C<getgroups()>,
+one of which may be the same as the first number.
- (?:(...)(?{ $var = $^N }))
+Similarly, a value assigned to C<$)> must also be a space-separated
+list of numbers. The first number sets the effective gid, and
+the rest (if any) are passed to C<setgroups()>. To get the effect of an
+empty list for C<setgroups()>, just repeat the new effective gid; that is,
+to force an effective gid of 5 and an effectively empty C<setgroups()>
+list, say C< $) = "5 5" >.
-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.
+You can change both the effective gid and the real gid at the same
+time by using C<POSIX::setgid()> (use only a single numeric argument).
+Changes to C<$)> require a check to C<$!> to detect any possible errors
+after an attempted change.
-This variable is dynamically scoped to the current BLOCK.
+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 C<setregid()>.
-=item @LAST_MATCH_END
+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.
-=item @+
-X<@+> X<@LAST_MATCH_END>
+=item $REAL_USER_ID
-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 $UID
-=item %LAST_PAREN_MATCH
+=item $<
+X<< $< >> X<$UID> X<$REAL_USER_ID>
-=item %+
-X<%+>
+The real uid of this process. You can change both the real uid and the
+effective uid at the same time by using C<POSIX::setuid()>. Since
+changes to C<< $< >> require a system call, check C<$!> after a change
+attempt to detect any possible errors.
-Similar to C<@+>, the C<%+> hash allows access to the named capture
-buffers, should they exist, in the last successful match in the
-currently active dynamic scope.
+Mnemonic: it's the uid you came I<from>, if you're running setuid.
-For example, C<$+{foo}> is equivalent to C<$1> after the following match:
+=item $EFFECTIVE_USER_ID
- 'foo' =~ /(?<foo>foo)/;
+=item $EUID
-The keys of the C<%+> hash list only the names of buffers that have
-captured (and that are thus associated to defined values).
+=item $>
+X<< $> >> X<$EUID> X<$EFFECTIVE_USER_ID>
-The underlying behaviour of C<%+> is provided by the
-L<Tie::Hash::NamedCapture> module.
+The effective uid of this process. For example:
-B<Note:> C<%-> and C<%+> are tied views into a common internal hash
-associated with the last successful regular expression. Therefore mixing
-iterative access to them via C<each> may have unpredictable results.
-Likewise, if the last successful match changes, then the results may be
-surprising.
+ $< = $>; # set real to effective uid
+ ($<,$>) = ($>,$<); # swap real and effective uids
-=item HANDLE->input_line_number(EXPR)
+You can change both the effective uid and the real uid at the same
+time by using C<POSIX::setuid()>. Changes to C<< $> >> require a check
+to C<$!> to detect any possible errors after an attempted change.
-=item $INPUT_LINE_NUMBER
+C<< $< >> and C<< $> >> can be swapped only on machines
+supporting C<setreuid()>.
-=item $NR
+Mnemonic: it's the uid you went I<to>, if you're running setuid.
-=item $.
-X<$.> X<$NR> X<$INPUT_LINE_NUMBER> X<line number>
+=item $SUBSCRIPT_SEPARATOR
-Current line number for the last filehandle accessed.
+=item $SUBSEP
-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.
+=item $;
+X<$;> X<$SUBSEP> X<SUBSCRIPT_SEPARATOR>
-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.
+The subscript separator for multidimensional array emulation. If you
+refer to a hash element as
+
+ $foo{$a,$b,$c}
+
+it really means
+
+ $foo{join($;, $a, $b, $c)}
+
+But don't put
+
+ @foo{$a,$b,$c} # a slice--note the @
+
+which means
+
+ ($foo{$a},$foo{$b},$foo{$c})
+
+Default is "\034", the same as SUBSEP in B<awk>. If your keys contain
+binary data there might not be any safe value for C<$;>.
+
+Consider using "real" multidimensional arrays as described
+in L<perllol>.
+
+Mnemonic: comma (the syntactic subscript separator) is a semi-semicolon.
+
+=item $a
+
+=item $b
+X<$a> X<$b>
+
+Special package variables when using C<sort()>, see L<perlfunc/sort>.
+Because of this specialness C<$a> and C<$b> don't need to be declared
+(using C<use vars>, or C<our()>) even when using the C<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 C<sort()> comparison block or function.
+
+=item %ENV
+X<%ENV>
+
+The hash C<%ENV> contains your current environment. Setting a
+value in C<ENV> changes the environment for any child processes
+you subsequently C<fork()> off.
+
+=item $SYSTEM_FD_MAX
+
+=item $^F
+X<$^F> X<$SYSTEM_FD_MAX>
+
+The maximum system file descriptor, ordinarily 2. System file
+descriptors are passed to C<exec()>ed processes, while higher file
+descriptors are not. Also, during an
+C<open()>, system file descriptors are
+preserved even if the C<open()> fails (ordinary file descriptors are
+closed before the C<open()> is attempted). The close-on-exec
+status of a file descriptor will be decided according to the value of
+C<$^F> when the corresponding file, pipe, or socket was opened, not the
+time of the C<exec()>.
+
+=item @F
+X<@F>
+
+The array C<@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
+X<@INC>
+
+The array C<@INC> contains the list of places that the C<do EXPR>,
+C<require>, or C<use> constructs look for their library files. It
+initially consists of the arguments to any B<-I> command-line
+switches, followed by the default Perl library, probably
+F</usr/local/lib/perl>, followed by ".", to represent the current
+directory. ("." will not be appended if taint checks are enabled,
+either by C<-T> or by C<-t>.) If you need to modify this at runtime,
+you should use the C<use lib> pragma to get the machine-dependent
+library properly loaded also:
+
+ use lib '/mypath/libdir/';
+ use SomeMod;
+
+You can also insert hooks into the file inclusion system by putting Perl
+code directly into C<@INC>. Those hooks may be subroutine references,
+array references or blessed objects. See L<perlfunc/require> for details.
+
+=item %INC
+X<%INC>
+
+The hash C<%INC> contains entries for each filename included via the
+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 hash to determine whether a particular file has
+already been included.
+
+If the file was loaded via a hook (e.g. a subroutine reference, see
+L<perlfunc/require> for a description of these hooks), this hook is
+by default inserted into C<%INC> in place of a filename. Note, however,
+that the hook may have set the C<%INC> entry by itself to provide some more
+specific info.
+
+=item $INPLACE_EDIT
+
+=item $^I
+X<$^I> X<$INPLACE_EDIT>
+
+The current value of the inplace-edit extension. Use C<undef> to disable
+inplace editing.
+
+Mnemonic: value of B<-i> switch.
+
+=item $^M
+X<$^M>
+
+By default, running out of memory is an untrappable, fatal error.
+However, if suitably built, Perl can use the contents of C<$^M>
+as an emergency memory pool after C<die()>ing. Suppose that your Perl
+were compiled with C<-DPERL_EMERGENCY_SBRK> and used Perl's malloc.
+Then
+
+ $^M = 'a' x (1 << 16);
+
+would allocate a 64K buffer for use in an emergency. See the
+F<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 L<English|English> long name for
+this variable.
+
+This variable was added in Perl 5.004.
+
+=item $OSNAME
+
+=item $^O
+X<$^O> X<$OSNAME>
+
+The name of the operating system under which this copy of Perl was
+built, as determined during the configuration process. For examples
+see L<perlport/PLATFORMS>.
+
+The value is identical to C<$Config{'osname'}>. See also L<Config>
+and the B<-V> command-line switch documented in L<perlrun>.
+
+In Windows platforms, C<$^O> is not very helpful: since it is always
+C<MSWin32>, it doesn't tell the difference between
+95/98/ME/NT/2000/XP/CE/.NET. Use C<Win32::GetOSName()> or
+Win32::GetOSVersion() (see L<Win32> and L<perlport>) to distinguish
+between the variants.
+
+This variable was added in Perl 5.003.
+
+=item %SIG
+X<%SIG>
+
+The hash C<%SIG> contains signal handlers for signals. For example:
+
+ sub handler { # 1st argument is signal name
+ my($sig) = @_;
+ print "Caught a SIG$sig--shutting down\n";
+ close(LOG);
+ exit(0);
+ }
+
+ $SIG{'INT'} = \&handler;
+ $SIG{'QUIT'} = \&handler;
+ ...
+ $SIG{'INT'} = 'DEFAULT'; # restore default action
+ $SIG{'QUIT'} = 'IGNORE'; # ignore SIGQUIT
+
+Using a value of C<'IGNORE'> usually has the effect of ignoring the
+signal, except for the C<CHLD> signal. See L<perlipc> for more about
+this special case.
+
+Here are some other examples:
+
+ $SIG{"PIPE"} = "Plumber"; # assumes main::Plumber (not
+ # recommended)
+ $SIG{"PIPE"} = \&Plumber; # just fine; assume current
+ # Plumber
+ $SIG{"PIPE"} = *Plumber; # somewhat esoteric
+ $SIG{"PIPE"} = Plumber(); # oops, what did Plumber()
+ # return??
+
+Be sure not to use a bareword as the name of a signal handler,
+lest you inadvertently call it.
+
+If your system has the C<sigaction()> function then signal handlers
+are installed using it. This means you get reliable signal handling.
+
+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 L<perlipc> for more information.
+
+Certain internal hooks can be also set using the C<%SIG> hash. The
+routine indicated by C<$SIG{__WARN__}> is called when a warning
+message is about to be printed. The warning message is passed as the
+first argument. The presence of a C<__WARN__> hook causes the
+ordinary printing of warnings to C<STDERR> to be suppressed. You can
+use this to save warnings in a variable, or turn warnings into fatal
+errors, like this:
+
+ local $SIG{__WARN__} = sub { die $_[0] };
+ eval $proggie;
+
+As the C<'IGNORE'> hook is not supported by C<__WARN__>, you can
+disable warnings using the empty subroutine:
+
+ local $SIG{__WARN__} = sub {};
+
+The routine indicated by C<$SIG{__DIE__}> is called when a fatal
+exception is about to be thrown. The error message is passed as the
+first argument. When a C<__DIE__> hook routine returns, the exception
+processing continues as it would have in the absence of the hook,
+unless the hook routine itself exits via a C<goto &sub>, a loop exit,
+or a C<die()>. The C<__DIE__> handler is explicitly disabled during
+the call, so that you can die from a C<__DIE__> handler. Similarly
+for C<__WARN__>.
+
+Due to an implementation glitch, the C<$SIG{__DIE__}> hook is called
+even inside an C<eval()>. Do not use this to rewrite a pending
+exception in C<$@>, or as a bizarre substitute for overriding
+C<CORE::GLOBAL::die()>. This strange action at a distance may be fixed
+in a future release so that C<$SIG{__DIE__}> is only called if your
+program is about to exit, as was the original intent. Any other use is
+deprecated.
+
+C<__DIE__>/C<__WARN__> handlers are very special in one respect: they
+may be called to report (probable) errors found by the parser. In such
+a case the parser may be in inconsistent state, so any attempt to
+evaluate Perl code from such a handler will probably result in a
+segfault. This means that warnings or errors that result from parsing
+Perl should be used with extreme caution, like this:
+
+ require Carp if defined $^S;
+ Carp::confess("Something wrong") if defined &Carp::confess;
+ die "Something wrong, but could not load Carp to give "
+ . "backtrace...\n\t"
+ . "To see backtrace try starting Perl with -MCarp switch";
+
+Here the first line will load C<Carp> I<unless> it is the parser who
+called the handler. The second line will print backtrace and die if
+C<Carp> was available. The third line will be executed only if C<Carp> was
+not available.
+
+Having to even think about the C<$^S> variable in your exception
+handlers is simply wrong. C<$SIG{__DIE__}> as currently implemented
+invites grievous and difficult to track down errors. Avoid it
+and use an C<END{}> or CORE::GLOBAL::die override instead.
+
+See L<perlfunc/die>, L<perlfunc/warn>, L<perlfunc/eval>, and
+L<warnings> for additional information.
+
+=item $BASETIME
+
+=item $^T
+X<$^T> X<$BASETIME>
+
+The time at which the program began running, in seconds since the
+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
+X<$^V> X<$PERL_VERSION>
+
+The revision, version, and subversion of the Perl interpreter,
+represented as a C<version> object.
+
+This variable first appeared in perl v5.6.0; earlier versions of perl
+will see an undefined value. Before perl v5.10.0 C<$^V> was represented
+as a v-string.
+
+C<$^V> can be used to determine whether the Perl interpreter executing
+a script is in the right range of versions. For example:
+
+ warn "Hashes not randomized!\n" if !$^V or $^V lt v5.8.1
+
+To convert C<$^V> into its string representation use C<sprintf()>'s
+C<"%vd"> conversion:
+
+ printf "version is v%vd\n", $^V; # Perl's version
+
+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.
+
+This variable was added in Perl v5.6.0.
+
+Mnemonic: use ^V for Version Control.
+
+=item ${^WIN32_SLOPPY_STAT}
+X<${^WIN32_SLOPPY_STAT}> X<sitecustomize> X<sitecustomize.pl>
+
+If this variable is set to a true value, then C<stat()> on Windows will
+not try to open the file. This means that the link count cannot be
+determined and file attributes may be out of date if additional
+hardlinks to the file exist. On the other hand, not opening the file
+is considerably faster, especially for files on network drives.
+
+This variable could be set in the F<sitecustomize.pl> file to
+configure the local Perl installation to use "sloppy" C<stat()> by
+default. See the documentation for B<-f> in
+L<perlrun|perlrun/"Command Switches"> for more information about site
+customization.
+
+This variable was added in Perl v5.10.0.
+
+=item $EXECUTABLE_NAME
+
+=item $^X
+X<$^X> X<$EXECUTABLE_NAME>
+
+The name used to execute the current copy of Perl, from C's
+C<argv[0]> or (where supported) F</proc/self/exe>.
+
+Depending on the host operating system, the value of C<$^X> 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 C<$^X> is in PATH. For VMS, the
+value may or may not include a version number.
+
+You usually can use the value of C<$^X> to re-invoke an independent
+copy of the same perl that is currently running, e.g.,
+
+ @first_run = `$^X -le "print int rand 100 for 1..100"`;
+
+But recall that not all operating systems support forking or
+capturing of the output of commands, so this complex statement
+may not be portable.
+
+It is not safe to use the value of C<$^X> 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 C<$^X> to a path name, use the
+following statements:
+
+ # Build up a set of file names (not command names).
+ use Config;
+ my $this_perl = $^X;
+ if ($^O ne 'VMS') {
+ $this_perl .= $Config{_exe}
+ unless $this_perl =~ m/$Config{_exe}$/i;
+ }
+
+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 C<$^X>. The following statements accomplish
+this goal, and produce a pathname that can be invoked as a
+command or referenced as a file.
+
+ use Config;
+ my $secure_perl_path = $Config{perlpath};
+ if ($^O ne 'VMS') {
+ $secure_perl_path .= $Config{_exe}
+ unless $secure_perl_path =~ m/$Config{_exe}$/i;
+ }
+
+=back
+
+=head2 Variables related to regular expressions
+
+Most of the special variables related to regular expressions are side
+effects. Perl sets these variables when it has a successful match, so
+you should check the match result before using them. For instance:
+
+ if( /P(A)TT(ER)N/ ) {
+ print "I found $1 and $2\n";
+ }
+
+These variables are read-only and dynamically-scoped, unless we note
+otherwise.
+
+The dynamic nature of the regular expression variables means that
+their value is limited to the block that they are in, as demonstrated
+by this bit of code:
+
+ my $outer = 'Wallace and Grommit';
+ my $inner = 'Mutt and Jeff';
+
+ my $pattern = qr/(\S+) and (\S+)/;
+
+ sub show_n { print "\$1 is $1; \$2 is $2\n" }
+
+ {
+ OUTER:
+ show_n() if $outer =~ m/$pattern/;
+
+ INNER: {
+ show_n() if $inner =~ m/$pattern/;
+ }
+
+ show_n();
+ }
+
+The output shows that while in the C<OUTER> block, the values of C<$1>
+and C<$2> are from the match against C<$outer>. Inside the C<INNER>
+block, the values of C<$1> and C<$2> are from the match against
+C<$inner>, but only until the end of the block (i.e. the dynamic
+scope). After the C<INNER> block completes, the values of C<$1> and
+C<$2> return to the values for the match against C<$outer> even though
+we have not made another match:
+
+ $1 is Wallace; $2 is Grommit
+ $1 is Mutt; $2 is Jeff
+ $1 is Wallace; $2 is Grommit
+
+If you are using Perl v5.18 or earlier, note that C<use
+English> imposes a considerable performance penalty on all regular
+expression matches in a program because it uses the C<$`>, C<$&>, and
+C<$'>, regardless of whether they occur in the scope of C<use
+English>. For that reason, saying C<use English> in libraries is
+strongly discouraged unless you import it without the match variables:
+
+ use English '-no_match_vars'
+
+The C<Devel::NYTProf> and C<Devel::FindAmpersand>
+modules can help you find uses of these
+problematic match variables in your code.
+
+Since Perl v5.10.0, you can use the C</p> match operator flag and the
+C<${^PREMATCH}>, C<${^MATCH}>, and C<${^POSTMATCH}> variables instead
+so you only suffer the performance penalties.
+
+If you are using Perl v5.20.0 or higher, you do not need to worry about
+this, as the three naughty variables are no longer naughty.
+
+=over 8
+
+=item $<I<digits>> ($1, $2, ...)
+X<$1> X<$2> X<$3>
+
+Contains the subpattern from the corresponding set of capturing
+parentheses from the last successful pattern match, not counting patterns
+matched in nested blocks that have been exited already.
+
+These variables are read-only and dynamically-scoped.
+
+Mnemonic: like \digits.
+
+=item $MATCH
+
+=item $&
+X<$&> X<$MATCH>
-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/"IE<sol>O Operators">. Because C<< <> >> never does
-an explicit close, line numbers increase across ARGV files (but see
-examples in L<perlfunc/eof>).
+The string matched by the last successful pattern match (not counting
+any matches hidden within a BLOCK or C<eval()> enclosed by the current
+BLOCK).
-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.
+In Perl v5.18 and earlier, the use of this variable
+anywhere in a program imposes a considerable
+performance penalty on all regular expression matches. To avoid this
+penalty, you can extract the same substring by using L</@->. Starting
+with Perl v5.10.0, you can use the C</p> match flag and the C<${^MATCH}>
+variable to do the same thing for particular match operations.
-(Mnemonic: many programs use "." to mean the current line number.)
+This variable is read-only and dynamically-scoped.
-=item IO::Handle->input_record_separator(EXPR)
+Mnemonic: like C<&> in some editors.
-=item $INPUT_RECORD_SEPARATOR
+=item ${^MATCH}
+X<${^MATCH}>
-=item $RS
+This is similar to C<$&> (C<$MATCH>) except that it does not incur the
+performance penalty associated with that variable.
+In Perl v5.18 and earlier, it is only guaranteed
+to return a defined value when the pattern was compiled or executed with
+the C</p> modifier. In Perl v5.20, the C</p> modifier does nothing, so
+C<${^MATCH}> does the same thing as C<$MATCH>.
-=item $/
-X<$/> X<$RS> X<$INPUT_RECORD_SEPARATOR>
+This variable was added in Perl v5.10.0.
-The input record separator, newline by default. This
-influences Perl's idea of what a "line" is. Works like B<awk>'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 C<undef> to read through the end
-of file. Setting it to C<"\n\n"> means something slightly
-different than setting to C<"">, if the file contains consecutive
-empty lines. Setting to C<""> will treat two or more consecutive
-empty lines as a single empty line. Setting to C<"\n\n"> will
-blindly assume that the next input character belongs to the next
-paragraph, even if it's a newline. (Mnemonic: / delimits
-line boundaries when quoting poetry.)
+This variable is read-only and dynamically-scoped.
- local $/; # enable "slurp" mode
- local $_ = <FH>; # whole file now here
- s/\n[ \t]+/ /g;
+=item $PREMATCH
-Remember: the value of C<$/> is a string, not a regex. B<awk> has to be
-better for something. :-)
+=item $`
+X<$`> X<$PREMATCH> X<${^PREMATCH}>
-Setting C<$/> 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. So this:
+The string preceding whatever was matched by the last successful
+pattern match, not counting any matches hidden within a BLOCK or C<eval>
+enclosed by the current BLOCK.
- local $/ = \32768; # or \"32768", or \$var_containing_32768
- open my $fh, "<", $myfile or die $!;
- local $_ = <$fh>;
+In Perl v5.18 and earlier, the use of this variable
+anywhere in a program imposes a considerable
+performance penalty on all regular expression matches. To avoid this
+penalty, you can extract the same substring by using L</@->. Starting
+with Perl v5.10.0, you can use the C</p> match flag and the
+C<${^PREMATCH}> variable to do the same thing for particular match
+operations.
-will read a record of no more than 32768 bytes from FILE. If you're
-not reading from a record-oriented file (or your OS doesn't have
-record-oriented files), then you'll likely get a full chunk of data
-with every read. If a record is larger than the record size you've
-set, you'll get the record back in pieces. Trying to set the record
-size to zero or less will cause reading in the (rest of the) whole file.
+This variable is read-only and dynamically-scoped.
-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 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.
+Mnemonic: C<`> often precedes a quoted string.
-See also L<perlport/"Newlines">. Also see C<$.>.
+=item ${^PREMATCH}
+X<$`> X<${^PREMATCH}>
-=item HANDLE->autoflush(EXPR)
+This is similar to C<$`> ($PREMATCH) except that it does not incur the
+performance penalty associated with that variable.
+In Perl v5.18 and earlier, it is only guaranteed
+to return a defined value when the pattern was compiled or executed with
+the C</p> modifier. In Perl v5.20, the C</p> modifier does nothing, so
+C<${^PREMATCH}> does the same thing as C<$PREMATCH>.
-=item $OUTPUT_AUTOFLUSH
+This variable was added in Perl v5.10.0
-=item $|
-X<$|> X<autoflush> X<flush> X<$OUTPUT_AUTOFLUSH>
+This variable is read-only and dynamically-scoped.
-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; C<$|> 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 B<rsh> and want to see the output as it's
-happening. This has no effect on input buffering. See L<perlfunc/getc>
-for that. See L<perldoc/select> on how to select the output channel.
-See also L<IO::Handle>. (Mnemonic: when you want your pipes to be piping hot.)
-
-=item IO::Handle->output_field_separator EXPR
+=item $POSTMATCH
-=item $OUTPUT_FIELD_SEPARATOR
+=item $'
+X<$'> X<$POSTMATCH> X<${^POSTMATCH}> X<@->
-=item $OFS
+The string following whatever was matched by the last successful
+pattern match (not counting any matches hidden within a BLOCK or C<eval()>
+enclosed by the current BLOCK). Example:
-=item $,
-X<$,> X<$OFS> X<$OUTPUT_FIELD_SEPARATOR>
+ local $_ = 'abcdefghi';
+ /def/;
+ print "$`:$&:$'\n"; # prints abc:def:ghi
-The output field separator for the print operator. If defined, this
-value is printed between each of print's arguments. Default is C<undef>.
-(Mnemonic: what is printed when there is a "," in your print statement.)
+In Perl v5.18 and earlier, the use of this variable
+anywhere in a program imposes a considerable
+performance penalty on all regular expression matches.
+To avoid this penalty, you can extract the same substring by
+using L</@->. Starting with Perl v5.10.0, you can use the C</p> match flag
+and the C<${^POSTMATCH}> variable to do the same thing for particular
+match operations.
-=item IO::Handle->output_record_separator EXPR
+This variable is read-only and dynamically-scoped.
-=item $OUTPUT_RECORD_SEPARATOR
+Mnemonic: C<'> often follows a quoted string.
-=item $ORS
+=item ${^POSTMATCH}
+X<${^POSTMATCH}> X<$'> X<$POSTMATCH>
-=item $\
-X<$\> X<$ORS> X<$OUTPUT_RECORD_SEPARATOR>
+This is similar to C<$'> (C<$POSTMATCH>) except that it does not incur the
+performance penalty associated with that variable.
+In Perl v5.18 and earlier, it is only guaranteed
+to return a defined value when the pattern was compiled or executed with
+the C</p> modifier. In Perl v5.20, the C</p> modifier does nothing, so
+C<${^POSTMATCH}> does the same thing as C<$POSTMATCH>.
-The output record separator for the print operator. If defined, this
-value is printed after the last of print's arguments. Default is C<undef>.
-(Mnemonic: you set C<$\> instead of adding "\n" at the end of the print.
-Also, it's just like C<$/>, but it's what you get "back" from Perl.)
+This variable was added in Perl v5.10.0.
-=item $LIST_SEPARATOR
+This variable is read-only and dynamically-scoped.
-=item $"
-X<$"> X<$LIST_SEPARATOR>
+=item $LAST_PAREN_MATCH
-This is like C<$,> except that it applies to array and slice values
-interpolated into a double-quoted string (or similar interpreted
-string). Default is a space. (Mnemonic: obvious, I think.)
+=item $+
+X<$+> X<$LAST_PAREN_MATCH>
-=item $SUBSCRIPT_SEPARATOR
+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:
-=item $SUBSEP
+ /Version: (.*)|Revision: (.*)/ && ($rev = $+);
-=item $;
-X<$;> X<$SUBSEP> X<SUBSCRIPT_SEPARATOR>
+This variable is read-only and dynamically-scoped.
-The subscript separator for multidimensional array emulation. If you
-refer to a hash element as
+Mnemonic: be positive and forward looking.
- $foo{$a,$b,$c}
+=item $LAST_SUBMATCH_RESULT
-it really means
+=item $^N
+X<$^N> X<$LAST_SUBMATCH_RESULT>
- $foo{join($;, $a, $b, $c)}
+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.
-But don't put
+This is primarily 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
- @foo{$a,$b,$c} # a slice--note the @
+ (?:(...)(?{ $var = $^N }))
-which means
+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.
- ($foo{$a},$foo{$b},$foo{$c})
+This variable was added in Perl v5.8.0.
-Default is "\034", the same as SUBSEP in B<awk>. If your
-keys contain binary data there might not be any safe value for C<$;>.
-(Mnemonic: comma (the syntactic subscript separator) is a
-semi-semicolon. Yeah, I know, it's pretty lame, but C<$,> is already
-taken for something more important.)
+Mnemonic: the (possibly) Nested parenthesis that most recently closed.
-Consider using "real" multidimensional arrays as described
-in L<perllol>.
+=item @LAST_MATCH_END
-=item HANDLE->format_page_number(EXPR)
+=item @+
+X<@+> X<@LAST_MATCH_END>
-=item $FORMAT_PAGE_NUMBER
+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 C<$1> ends, C<$+[2]> the offset
+past where C<$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 $%
-X<$%> X<$FORMAT_PAGE_NUMBER>
+This variable was added in Perl v5.6.0.
-The current page number of the currently selected output channel.
-Used with formats.
-(Mnemonic: % is page number in B<nroff>.)
+=item %LAST_PAREN_MATCH
-=item HANDLE->format_lines_per_page(EXPR)
+=item %+
+X<%+> X<%LAST_PAREN_MATCH>
-=item $FORMAT_LINES_PER_PAGE
+Similar to C<@+>, the C<%+> hash allows access to the named capture
+buffers, should they exist, in the last successful match in the
+currently active dynamic scope.
-=item $=
-X<$=> X<$FORMAT_LINES_PER_PAGE>
+For example, C<$+{foo}> is equivalent to C<$1> after the following match:
-The current page length (printable lines) of the currently selected
-output channel. Default is 60.
-Used with formats.
-(Mnemonic: = has horizontal lines.)
+ 'foo' =~ /(?<foo>foo)/;
-=item HANDLE->format_lines_left(EXPR)
+The keys of the C<%+> hash list only the names of buffers that have
+captured (and that are thus associated to defined values).
-=item $FORMAT_LINES_LEFT
+The underlying behaviour of C<%+> is provided by the
+L<Tie::Hash::NamedCapture> module.
-=item $-
-X<$-> X<$FORMAT_LINES_LEFT>
+B<Note:> C<%-> and C<%+> are tied views into a common internal hash
+associated with the last successful regular expression. Therefore mixing
+iterative access to them via C<each> may have unpredictable results.
+Likewise, if the last successful match changes, then the results may be
+surprising.
-The number of lines left on the page of the currently selected output
-channel.
-Used with formats.
-(Mnemonic: lines_on_page - lines_printed.)
+This variable was added in Perl v5.10.0.
+
+This variable is read-only and dynamically-scoped.
=item @LAST_MATCH_START
=item @-
X<@-> X<@LAST_MATCH_START>
-$-[0] is the offset of the start of the last successful match.
+C<$-[0]> is the offset of the start of the last successful match.
C<$-[>I<n>C<]> is the offset of the start of the substring matched by
I<n>-th subpattern, or undef if the subpattern did not match.
-Thus after a match against $_, $& coincides with C<substr $_, $-[0],
+Thus, after a match against C<$_>, C<$&> coincides with C<substr $_, $-[0],
$+[0] - $-[0]>. Similarly, $I<n> coincides with C<substr $_, $-[n],
$+[n] - $-[n]> if C<$-[n]> is defined, and $+ coincides with
-C<substr $_, $-[$#-], $+[$#-] - $-[$#-]>. One can use C<$#-> to find the last
-matched subgroup in the last successful match. Contrast with
+C<substr $_, $-[$#-], $+[$#-] - $-[$#-]>. One can use C<$#-> to find the
+last matched subgroup in the last successful match. Contrast with
C<$#+>, the number of subgroups in the regular expression. Compare
with C<@+>.
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.
+of the I<n>th submatch, so C<$-[1]> is the offset where C<$1>
+begins, C<$-[2]> the offset where C<$2> begins, and so on.
-After a match against some variable $var:
+After a match against some variable C<$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], $+[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
+
+This variable was added in Perl v5.6.0.
+
+=item %LAST_MATCH_START
+
+=item %-
+X<%-> X<%LAST_MATCH_START>
+
+Similar to C<%+>, this variable allows access to the named capture groups
+in the last successful match in the currently active dynamic scope. 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.
+
+Here's an example:
+
+ if ('1234' =~ /(?<A>1)(?<B>2)(?<A>3)(?<B>4)/) {
+ foreach my $bufname (sort keys %-) {
+ my $ary = $-{$bufname};
+ foreach my $idx (0..$#$ary) {
+ print "\$-{$bufname}[$idx] : ",
+ (defined($ary->[$idx])
+ ? "'$ary->[$idx]'"
+ : "undef"),
+ "\n";
+ }
+ }
+ }
+
+would print out:
+
+ $-{A}[0] : '1'
+ $-{A}[1] : '3'
+ $-{B}[0] : '2'
+ $-{B}[1] : '4'
+
+The keys of the C<%-> hash correspond to all buffer names found in
+the regular expression.
+
+The behaviour of C<%-> is implemented via the
+L<Tie::Hash::NamedCapture> module.
+
+B<Note:> C<%-> and C<%+> are tied views into a common internal hash
+associated with the last successful regular expression. Therefore mixing
+iterative access to them via C<each> may have unpredictable results.
+Likewise, if the last successful match changes, then the results may be
+surprising.
+
+This variable was added in Perl v5.10.0.
+
+This variable is read-only and dynamically-scoped.
+
+=item $LAST_REGEXP_CODE_RESULT
+
+=item $^R
+X<$^R> X<$LAST_REGEXP_CODE_RESULT>
+
+The result of evaluation of the last successful C<(?{ code })>
+regular expression assertion (see L<perlre>). May be written to.
+
+This variable was added in Perl 5.005.
+
+=item ${^RE_DEBUG_FLAGS}
+X<${^RE_DEBUG_FLAGS}>
+
+The current value of the regex debugging flags. Set to 0 for no debug output
+even when the C<re 'debug'> module is loaded. See L<re> for details.
+
+This variable was added in Perl v5.10.0.
+
+=item ${^RE_TRIE_MAXBUF}
+X<${^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.
+
+This variable was added in Perl v5.10.0.
+
+=back
+
+=head2 Variables related to filehandles
+
+Variables that depend on the currently selected filehandle may be set
+by calling an appropriate object method on the C<IO::Handle> 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
+
+ use IO::Handle;
+
+after which you may use either
+
+ method HANDLE EXPR
+
+or more safely,
+
+ HANDLE->method(EXPR)
+
+Each method returns the old value of the C<IO::Handle> attribute. The
+methods each take an optional EXPR, which, if supplied, specifies the
+new value for the C<IO::Handle> attribute in question. If not
+supplied, most methods do nothing to the current value--except for
+C<autoflush()>, which will assume a 1 for you, just to be different.
+
+Because loading in the C<IO::Handle> class is an expensive operation,
+you should learn how to use the regular built-in variables.
+
+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.
+
+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:
+
+ open my $fh, "<", "foo" or die $!;
+ local $/; # enable localized slurp mode
+ my $content = <$fh>;
+ close $fh;
+
+But the following code is quite bad:
+
+ open my $fh, "<", "foo" or die $!;
+ undef $/; # enable slurp mode
+ my $content = <$fh>;
+ close $fh;
+
+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 C<$/> is now changed for any other code
+running inside the same Perl interpreter.
+
+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 C<{}> block, you should create one yourself. For
+example:
+
+ my $content = '';
+ open my $fh, "<", "foo" or die $!;
+ {
+ local $/;
+ $content = <$fh>;
+ }
+ close $fh;
+
+Here is an example of how your own code can go broken:
+
+ for ( 1..3 ){
+ $\ = "\r\n";
+ nasty_break();
+ print "$_";
+ }
+
+ sub nasty_break {
+ $\ = "\f";
+ # do something with $_
+ }
+
+You probably expect this code to print the equivalent of
-=item C<$'> is the same as C<substr($var, $+[0])>
+ "1\r\n2\r\n3\r\n"
-=item C<$1> is the same as C<substr($var, $-[1], $+[1] - $-[1])>
+but instead you get:
-=item C<$2> is the same as C<substr($var, $-[2], $+[2] - $-[2])>
+ "1\f2\f3\f"
-=item C<$3> is the same as C<substr($var, $-[3], $+[3] - $-[3])>
+Why? Because C<nasty_break()> modifies C<$\> without localizing it
+first. The value you set in C<nasty_break()> is still there when you
+return. The fix is to add C<local()> so the value doesn't leak out of
+C<nasty_break()>:
-=back
+ local $\ = "\f";
-=item %-
-X<%->
+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.
-Similar to C<%+>, this variable allows access to the named capture buffers
-in the last successful match in the currently active dynamic scope. To
-each capture buffer 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.
+=over 8
-Here's an example:
+=item $ARGV
+X<$ARGV>
- if ('1234' =~ /(?<A>1)(?<B>2)(?<A>3)(?<B>4)/) {
- foreach my $bufname (sort keys %-) {
- my $ary = $-{$bufname};
- foreach my $idx (0..$#$ary) {
- print "\$-{$bufname}[$idx] : ",
- (defined($ary->[$idx]) ? "'$ary->[$idx]'" : "undef"),
- "\n";
- }
- }
- }
+Contains the name of the current file when reading from C<< <> >>.
-would print out:
+=item @ARGV
+X<@ARGV>
- $-{A}[0] : '1'
- $-{A}[1] : '3'
- $-{B}[0] : '2'
- $-{B}[1] : '4'
+The array C<@ARGV> contains the command-line arguments intended for
+the script. C<$#ARGV> is generally the number of arguments minus
+one, because C<$ARGV[0]> is the first argument, I<not> the program's
+command name itself. See L</$0> for the command name.
-The keys of the C<%-> hash correspond to all buffer names found in
-the regular expression.
+=item ARGV
+X<ARGV>
-The behaviour of C<%-> is implemented via the
-L<Tie::Hash::NamedCapture> module.
+The special filehandle that iterates over command-line filenames in
+C<@ARGV>. Usually written as the null filehandle in the angle operator
+C<< <> >>. Note that currently C<ARGV> only has its magical effect
+within the C<< <> >> operator; elsewhere it is just a plain filehandle
+corresponding to the last file opened by C<< <> >>. In particular,
+passing C<\*ARGV> 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 C<@ARGV>.
-B<Note:> C<%-> and C<%+> are tied views into a common internal hash
-associated with the last successful regular expression. Therefore mixing
-iterative access to them via C<each> may have unpredictable results.
-Likewise, if the last successful match changes, then the results may be
-surprising.
+=item ARGVOUT
+X<ARGVOUT>
-=item HANDLE->format_name(EXPR)
+The special filehandle that points to the currently open output file
+when doing edit-in-place processing with B<-i>. Useful when you have
+to do a lot of inserting and don't want to keep modifying C<$_>. See
+L<perlrun> for the B<-i> switch.
-=item $FORMAT_NAME
+=item IO::Handle->output_field_separator( EXPR )
-=item $~
-X<$~> X<$FORMAT_NAME>
+=item $OUTPUT_FIELD_SEPARATOR
-The name of the current report format for the currently selected output
-channel. Default is the name of the filehandle. (Mnemonic: brother to
-C<$^>.)
+=item $OFS
-=item HANDLE->format_top_name(EXPR)
+=item $,
+X<$,> X<$OFS> X<$OUTPUT_FIELD_SEPARATOR>
-=item $FORMAT_TOP_NAME
+The output field separator for the print operator. If defined, this
+value is printed between each of print's arguments. Default is C<undef>.
-=item $^
-X<$^> X<$FORMAT_TOP_NAME>
+You cannot call C<output_field_separator()> on a handle, only as a
+static method. See L<IO::Handle|IO::Handle>.
-The name of the current top-of-page format for the currently selected
-output channel. Default is the name of the filehandle with _TOP
-appended. (Mnemonic: points to top of page.)
+Mnemonic: what is printed when there is a "," in your print statement.
-=item IO::Handle->format_line_break_characters EXPR
+=item HANDLE->input_line_number( EXPR )
-=item $FORMAT_LINE_BREAK_CHARACTERS
+=item $INPUT_LINE_NUMBER
-=item $:
-X<$:> X<FORMAT_LINE_BREAK_CHARACTERS>
+=item $NR
-The current set of characters after which a string may be broken to
-fill continuation fields (starting with ^) in a format. Default is
-S<" \n-">, to break on whitespace or hyphens. (Mnemonic: a "colon" in
-poetry is a part of a line.)
+=item $.
+X<$.> X<$NR> X<$INPUT_LINE_NUMBER> X<line number>
-=item IO::Handle->format_formfeed EXPR
+Current line number for the last filehandle accessed.
-=item $FORMAT_FORMFEED
+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 C<readline()> or C<< <> >>), or when C<tell()> or
+C<seek()> is called on it, C<$.> becomes an alias to the line counter
+for that filehandle.
-=item $^L
-X<$^L> X<$FORMAT_FORMFEED>
+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.
-What formats output as a form feed. Default is \f.
+C<$.> is reset when the filehandle is closed, but B<not> when an open
+filehandle is reopened without an intervening C<close()>. For more
+details, see L<perlop/"IE<sol>O Operators">. Because C<< <> >> never does
+an explicit close, line numbers increase across C<ARGV> files (but see
+examples in L<perlfunc/eof>).
-=item $ACCUMULATOR
+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.
-=item $^A
-X<$^A> X<$ACCUMULATOR>
+Mnemonic: many programs use "." to mean the current line number.
-The current value of the write() accumulator for format() lines. A format
-contains formline() calls that put their result into C<$^A>. After
-calling its format, write() prints out the contents of C<$^A> and empties.
-So you never really see the contents of C<$^A> unless you call
-formline() yourself and then look at it. See L<perlform> and
-L<perlfunc/formline()>.
+=item IO::Handle->input_record_separator( EXPR )
-=item $CHILD_ERROR
+=item $INPUT_RECORD_SEPARATOR
-=item $?
-X<$?> X<$CHILD_ERROR>
+=item $RS
-The status returned by the last pipe close, backtick (C<``>) command,
-successful call to wait() or waitpid(), or from the system()
-operator. This is just the 16-bit status word returned by the
-traditional Unix wait() system call (or else is made up to look like it). Thus, the
-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>.)
+=item $/
+X<$/> X<$RS> X<$INPUT_RECORD_SEPARATOR>
-Additionally, if the C<h_errno> variable is supported in C, its value
-is returned via $? if any C<gethost*()> function fails.
+The input record separator, newline by default. This influences Perl's
+idea of what a "line" is. Works like B<awk>'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
+C<undef> to read through the end of file. Setting it to C<"\n\n">
+means something slightly different than setting to C<"">, if the file
+contains consecutive empty lines. Setting to C<""> will treat two or
+more consecutive empty lines as a single empty line. Setting to
+C<"\n\n"> will blindly assume that the next input character belongs to
+the next paragraph, even if it's a newline.
-If you have installed a signal handler for C<SIGCHLD>, the
-value of C<$?> will usually be wrong outside that handler.
+ local $/; # enable "slurp" mode
+ local $_ = <FH>; # whole file now here
+ s/\n[ \t]+/ /g;
-Inside an C<END> subroutine C<$?> contains the value that is going to be
-given to C<exit()>. You can modify C<$?> in an C<END> subroutine to
-change the exit status of your program. For example:
+Remember: the value of C<$/> is a string, not a regex. B<awk> has to
+be better for something. :-)
- END {
- $? = 1 if $? == 255; # die would make it 255
- }
+Setting C<$/> 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:
-Under VMS, the pragma C<use vmsish 'status'> makes C<$?> reflect the
-actual VMS exit status, instead of the default emulation of POSIX
-status; see L<perlvms/$?> for details.
+ local $/ = \32768; # or \"32768", or \$var_containing_32768
+ open my $fh, "<", $myfile or die $!;
+ local $_ = <$fh>;
-Also see L<Error Indicators>.
+will read a record of no more than 32768 characters from $fh. 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 will cause reading in the (rest of the) whole file.
-=item ${^CHILD_ERROR_NATIVE}
-X<$^CHILD_ERROR_NATIVE>
+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.
-The native status returned by the last pipe close, backtick (C<``>)
-command, successful call to wait() or waitpid(), or from the system()
-operator. On POSIX-like systems this value can be decoded with the
-WIFEXITED, WEXITSTATUS, WIFSIGNALED, WTERMSIG, WIFSTOPPED, WSTOPSIG
-and WIFCONTINUED functions provided by the L<POSIX> module.
+You cannot call C<input_record_separator()> on a handle, only as a
+static method. See L<IO::Handle|IO::Handle>.
-Under VMS this reflects the actual VMS exit status; i.e. it is the same
-as $? when the pragma C<use vmsish 'status'> is in effect.
+See also L<perlport/"Newlines">. Also see L</$.>.
-=item ${^ENCODING}
-X<$^ENCODING>
+Mnemonic: / delimits line boundaries when quoting poetry.
-The I<object reference> to the Encode object that is used to convert
-the source code to Unicode. Thanks to this variable your perl script
-does not have to be written in UTF-8. Default is I<undef>. The direct
-manipulation of this variable is highly discouraged.
+=item IO::Handle->output_record_separator( EXPR )
-=item $OS_ERROR
+=item $OUTPUT_RECORD_SEPARATOR
-=item $ERRNO
+=item $ORS
-=item $!
-X<$!> X<$ERRNO> X<$OS_ERROR>
+=item $\
+X<$\> X<$ORS> X<$OUTPUT_RECORD_SEPARATOR>
-If used numerically, yields the current value of the C C<errno>
-variable, or in other words, if a system or library call fails, it
-sets this variable. This means that the value of C<$!> is meaningful
-only I<immediately> after a B<failure>:
+The output record separator for the print operator. If defined, this
+value is printed after the last of print's arguments. Default is C<undef>.
- 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,
- # here $! is meaningless.
+You cannot call C<output_record_separator()> on a handle, only as a
+static method. See L<IO::Handle|IO::Handle>.
-In the above I<meaningless> stands for anything: zero, non-zero,
-C<undef>. A successful system or library call does B<not> set
-the variable to zero.
+Mnemonic: you set C<$\> instead of adding "\n" at the end of the print.
+Also, it's just like C<$/>, but it's what you get "back" from Perl.
-If used as a string, yields the corresponding system error string.
-You can assign a number to C<$!> to set I<errno> if, for instance,
-you want C<"$!"> to return the string for error I<n>, or you want
-to set the exit value for the die() operator. (Mnemonic: What just
-went bang?)
+=item HANDLE->autoflush( EXPR )
-Also see L<Error Indicators>.
+=item $OUTPUT_AUTOFLUSH
-=item %OS_ERROR
+=item $|
+X<$|> X<autoflush> X<flush> X<$OUTPUT_AUTOFLUSH>
-=item %ERRNO
+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; C<$|> 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 B<rsh> and
+want to see the output as it's happening. This has no effect on input
+buffering. See L<perlfunc/getc> for that. See L<perlfunc/select> on
+how to select the output channel. See also L<IO::Handle>.
-=item %!
-X<%!>
+Mnemonic: when you want your pipes to be piping hot.
-Each element of C<%!> has a true value only if C<$!> is set to that
-value. For example, C<$!{ENOENT}> is true if and only if the current
-value of C<$!> is C<ENOENT>; 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).
-To check if a particular key is meaningful on your system, use
-C<exists $!{the_key}>; for a list of legal keys, use C<keys %!>.
-See L<Errno> for more information, and also see above for the
-validity of C<$!>.
+=item ${^LAST_FH}
+X<${^LAST_FH}>
-=item $EXTENDED_OS_ERROR
+This read-only variable contains a reference to the last-read filehandle.
+This is set by C<< <HANDLE> >>, C<readline>, C<tell>, C<eof> and C<seek>.
+This is the same handle that C<$.> and C<tell> and C<eof> without arguments
+use. It is also the handle used when Perl appends ", <STDIN> line 1" to
+an error or warning message.
-=item $^E
-X<$^E> X<$EXTENDED_OS_ERROR>
+This variable was added in Perl v5.18.0.
-Error information specific to the current operating system. At
-the moment, this differs from C<$!> under only VMS, OS/2, and Win32
-(and for MacPerl). On all other platforms, C<$^E> is always just
-the same as C<$!>.
+=back
-Under VMS, C<$^E> provides the VMS status value from the last
-system error. This is more specific information about the last
-system error than that provided by C<$!>. This is particularly
-important when C<$!> is set to B<EVMSERR>.
+=head3 Variables related to formats
-Under OS/2, C<$^E> is set to the error code of the last call to
-OS/2 API either via CRT, or directly from perl.
+The special variables for formats are a subset of those for
+filehandles. See L<perlform> for more information about Perl's
+formats.
-Under Win32, C<$^E> always returns the last error information
-reported by the Win32 call C<GetLastError()> which describes
-the last error from within the Win32 API. Most Win32-specific
-code will report errors via C<$^E>. ANSI C and Unix-like calls
-set C<errno> and so most portable Perl code will report errors
-via C<$!>.
+=over 8
-Caveats mentioned in the description of C<$!> generally apply to
-C<$^E>, also. (Mnemonic: Extra error explanation.)
+=item $ACCUMULATOR
-Also see L<Error Indicators>.
+=item $^A
+X<$^A> X<$ACCUMULATOR>
-=item $EVAL_ERROR
+The current value of the C<write()> accumulator for C<format()> lines.
+A format contains C<formline()> calls that put their result into
+C<$^A>. After calling its format, C<write()> prints out the contents
+of C<$^A> and empties. So you never really see the contents of C<$^A>
+unless you call C<formline()> yourself and then look at it. See
+L<perlform> and L<perlfunc/"formline PICTURE,LIST">.
-=item $@
-X<$@> X<$EVAL_ERROR>
+=item IO::Handle->format_formfeed(EXPR)
-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"?)
+=item $FORMAT_FORMFEED
-Warning messages are not collected in this variable. You can,
-however, set up a routine to process warnings by setting C<$SIG{__WARN__}>
-as described below.
+=item $^L
+X<$^L> X<$FORMAT_FORMFEED>
-Also see L<Error Indicators>.
+What formats output as a form feed. The default is C<\f>.
-=item $PROCESS_ID
+You cannot call C<format_formfeed()> on a handle, only as a static
+method. See L<IO::Handle|IO::Handle>.
-=item $PID
+=item HANDLE->format_page_number(EXPR)
-=item $$
-X<$$> X<$PID> X<$PROCESS_ID>
+=item $FORMAT_PAGE_NUMBER
-The process number of the Perl running this script. You should
-consider this variable read-only, although it will be altered
-across fork() calls. (Mnemonic: same as shells.)
+=item $%
+X<$%> X<$FORMAT_PAGE_NUMBER>
-Note for Linux users: on Linux, the C functions C<getpid()> and
-C<getppid()> return different values from different threads. In order to
-be portable, this behavior is not reflected by C<$$>, whose value remains
-consistent across threads. If you want to call the underlying C<getpid()>,
-you may use the CPAN module C<Linux::Pid>.
+The current page number of the currently selected output channel.
-=item $REAL_USER_ID
+Mnemonic: C<%> is page number in B<nroff>.
-=item $UID
+=item HANDLE->format_lines_left(EXPR)
-=item $<
-X<< $< >> X<$UID> X<$REAL_USER_ID>
+=item $FORMAT_LINES_LEFT
-The real uid of this process. (Mnemonic: it's the uid you came I<from>,
-if you're running setuid.) You can change both the real uid and
-the effective uid at the same time by using POSIX::setuid(). Since
-changes to $< require a system call, check $! after a change attempt to
-detect any possible errors.
+=item $-
+X<$-> X<$FORMAT_LINES_LEFT>
-=item $EFFECTIVE_USER_ID
+The number of lines left on the page of the currently selected output
+channel.
-=item $EUID
+Mnemonic: lines_on_page - lines_printed.
-=item $>
-X<< $> >> X<$EUID> X<$EFFECTIVE_USER_ID>
+=item IO::Handle->format_line_break_characters EXPR
-The effective uid of this process. Example:
+=item $FORMAT_LINE_BREAK_CHARACTERS
- $< = $>; # set real to effective uid
- ($<,$>) = ($>,$<); # swap real and effective uid
+=item $:
+X<$:> X<FORMAT_LINE_BREAK_CHARACTERS>
-You can change both the effective uid and the real uid at the same
-time by using POSIX::setuid(). Changes to $> require a check to $!
-to detect any possible errors after an attempted change.
+The current set of characters after which a string may be broken to
+fill continuation fields (starting with C<^>) in a format. The default is
+S<" \n-">, to break on a space, newline, or a hyphen.
-(Mnemonic: it's the uid you went I<to>, if you're running setuid.)
-C<< $< >> and C<< $> >> can be swapped only on machines
-supporting setreuid().
+You cannot call C<format_line_break_characters()> on a handle, only as
+a static method. See L<IO::Handle|IO::Handle>.
-=item $REAL_GROUP_ID
+Mnemonic: a "colon" in poetry is a part of a line.
-=item $GID
+=item HANDLE->format_lines_per_page(EXPR)
-=item $(
-X<$(> X<$GID> X<$REAL_GROUP_ID>
+=item $FORMAT_LINES_PER_PAGE
-The real gid of this process. If you are on a machine that supports
-membership in multiple groups simultaneously, gives a space separated
-list of groups you are in. The first number is the one returned by
-getgid(), and the subsequent ones by getgroups(), one of which may be
-the same as the first number.
+=item $=
+X<$=> X<$FORMAT_LINES_PER_PAGE>
-However, a value assigned to C<$(> must be a single number used to
-set the real gid. So the value given by C<$(> should I<not> be assigned
-back to C<$(> without being forced numeric, such as by adding zero. Note
-that this is different to the effective gid (C<$)>) which does take a
-list.
+The current page length (printable lines) of the currently selected
+output channel. The default is 60.
-You can change both the real gid and the effective gid at the same
-time by using POSIX::setgid(). Changes to $( require a check to $!
-to detect any possible errors after an attempted change.
+Mnemonic: = has horizontal lines.
-(Mnemonic: parentheses are used to I<group> things. The real gid is the
-group you I<left>, if you're running setgid.)
+=item HANDLE->format_top_name(EXPR)
-=item $EFFECTIVE_GROUP_ID
+=item $FORMAT_TOP_NAME
-=item $EGID
+=item $^
+X<$^> X<$FORMAT_TOP_NAME>
-=item $)
-X<$)> X<$EGID> X<$EFFECTIVE_GROUP_ID>
+The name of the current top-of-page format for the currently selected
+output channel. The default is the name of the filehandle with C<_TOP>
+appended. For example, the default format top name for the C<STDOUT>
+filehandle is C<STDOUT_TOP>.
-The effective gid of this process. If you are on a machine that
-supports membership in multiple groups simultaneously, gives a space
-separated list of groups you are in. The first number is the one
-returned by getegid(), and the subsequent ones by getgroups(), one of
-which may be the same as the first number.
+Mnemonic: points to top of page.
-Similarly, a value assigned to C<$)> must also be a space-separated
-list of numbers. The first number sets the effective gid, and
-the rest (if any) are passed to setgroups(). To get the effect of an
-empty list for setgroups(), just repeat the new effective gid; that is,
-to force an effective gid of 5 and an effectively empty setgroups()
-list, say C< $) = "5 5" >.
+=item HANDLE->format_name(EXPR)
-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).
-Changes to $) require a check to $! to detect any possible errors
-after an attempted change.
+=item $FORMAT_NAME
-(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.)
+=item $~
+X<$~> X<$FORMAT_NAME>
-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().
+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 C<STDOUT>
+filehandle is just C<STDOUT>.
-=item $PROGRAM_NAME
+Mnemonic: brother to C<$^>.
-=item $0
-X<$0> X<$PROGRAM_NAME>
+=back
-Contains the name of the program being executed.
+=head2 Error Variables
+X<error> X<exception>
-On some (read: not all) operating systems assigning to C<$0> modifies
-the argument area that the C<ps> program sees. On some platforms you
-may have to use special C<ps> options or a different C<ps> to see the
-changes. Modifying the $0 is more useful as a way of indicating the
-current program state than it is for hiding the program you're
-running. (Mnemonic: same as B<sh> and B<ksh>.)
+The variables C<$@>, C<$!>, C<$^E>, and C<$?> 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.
-Note that there are platform specific limitations on the maximum
-length of C<$0>. In the most extreme case it may be limited to the
-space occupied by the original C<$0>.
+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:
-In some platforms there may be arbitrary amount of padding, for
-example space characters, after the modified name as shown by C<ps>.
-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).
+ eval q{
+ open my $pipe, "/cdrom/install |" or die $!;
+ my @res = <$pipe>;
+ close $pipe or die "bad pipe: $?, $!";
+ };
-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"> may
-result in C<"perl: foobar (perl)"> (whether both the C<"perl: "> 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.
+When perl executes the C<eval()> expression, it translates the
+C<open()>, C<< <PIPE> >>, and C<close> calls in the C run-time library
+and thence to the operating system kernel. perl sets C<$!> to
+the C library's C<errno> if one of these calls fails.
-In multithreaded scripts Perl coordinates the threads so that any
-thread may modify its copy of the C<$0> and the change becomes visible
-to ps(1) (assuming the operating system plays along). Note that
-the view of C<$0> the other threads have will not change since they
-have their own copies of it.
+C<$@> is set if the string to be C<eval>-ed did not compile (this may
+happen if C<open> or C<close> were imported with bad prototypes), or
+if Perl code executed during evaluation C<die()>d. In these cases the
+value of C<$@> is the compile error, or the argument to C<die> (which
+will interpolate C<$!> and C<$?>). (See also L<Fatal>, though.)
-If the program has been given to perl via the switches C<-e> or C<-E>,
-C<$0> will contain the string C<"-e">.
+Under a few operating systems, C<$^E> 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 C<$^E> the same as C<$!>.
-On Linux as of perl 5.14 the legacy process name will be set with
-L<prctl(2)>, in addition to altering the POSIX name via C<argv[0]> 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 C<$0>. The string you supply will be
-cut off at 16 bytes, this is a limitation imposed by Linux.
+Finally, C<$?> may be set to non-0 value if the external program
+F</cdrom/install> fails. The upper eight bits reflect specific error
+conditions encountered by the program (the program's C<exit()> value).
+The lower eight bits reflect mode of failure, like signal death and
+core dump information. See L<wait(2)> for details. In contrast to
+C<$!> and C<$^E>, which are set only if error condition is detected,
+the variable C<$?> is set on each C<wait> or pipe C<close>,
+overwriting the old value. This is more like C<$@>, which on every
+C<eval()> is always set on failure and cleared on success.
+
+For more details, see the individual descriptions at C<$@>, C<$!>,
+C<$^E>, and C<$?>.
-=item $[
-X<$[>
+=over 8
-The index of the first element in an array, and of the first character
-in a substring. Default is 0, but you could theoretically set it
-to 1 to make Perl behave more like B<awk> (or Fortran) when
-subscripting and when evaluating the index() and substr() functions.
-(Mnemonic: [ begins subscripts.)
+=item ${^CHILD_ERROR_NATIVE}
+X<$^CHILD_ERROR_NATIVE>
-As of release 5 of Perl, assignment to C<$[> 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 deprecated, and by default will trigger a warning.
+The native status returned by the last pipe close, backtick (C<``>)
+command, successful call to C<wait()> or C<waitpid()>, or from the
+C<system()> operator. On POSIX-like systems this value can be decoded
+with the WIFEXITED, WEXITSTATUS, WIFSIGNALED, WTERMSIG, WIFSTOPPED,
+WSTOPSIG and WIFCONTINUED functions provided by the L<POSIX> module.
-Note that, unlike other compile-time directives (such as L<strict>),
-assignment to C<$[> can be seen from outer lexical scopes in the same file.
-However, you can use local() on it to strictly bind its value to a
-lexical block.
+Under VMS this reflects the actual VMS exit status; i.e. it is the
+same as C<$?> when the pragma C<use vmsish 'status'> is in effect.
-=item $]
-X<$]>
+This variable was added in Perl v5.10.0.
-The version + patchlevel / 1000 of the Perl interpreter. This variable
-can be used to determine whether the Perl interpreter executing a
-script is in the right range of versions. (Mnemonic: Is this version
-of perl in the right bracket?) Example:
+=item $EXTENDED_OS_ERROR
- warn "No checksumming!\n" if $] < 3.019;
+=item $^E
+X<$^E> X<$EXTENDED_OS_ERROR>
-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.
+Error information specific to the current operating system. At the
+moment, this differs from C<$!> under only VMS, OS/2, and Win32 (and
+for MacPerl). On all other platforms, C<$^E> is always just the same
+as C<$!>.
-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.
+Under VMS, C<$^E> provides the VMS status value from the last system
+error. This is more specific information about the last system error
+than that provided by C<$!>. This is particularly important when C<$!>
+is set to B<EVMSERR>.
-=item $COMPILING
+Under OS/2, C<$^E> is set to the error code of the last call to OS/2
+API either via CRT, or directly from perl.
-=item $^C
-X<$^C> X<$COMPILING>
+Under Win32, C<$^E> always returns the last error information reported
+by the Win32 call C<GetLastError()> which describes the last error
+from within the Win32 API. Most Win32-specific code will report errors
+via C<$^E>. ANSI C and Unix-like calls set C<errno> and so most
+portable Perl code will report errors via C<$!>.
-The current value of the flag associated with the B<-c> switch.
-Mainly of use with B<-MO=...> to allow code to alter its behavior
-when being compiled, such as for example to AUTOLOAD at compile
-time rather than normal, deferred loading. Setting
-C<$^C = 1> is similar to calling C<B::minus_c>.
+Caveats mentioned in the description of C<$!> generally apply to
+C<$^E>, also.
-=item $DEBUGGING
+This variable was added in Perl 5.003.
-=item $^D
-X<$^D> X<$DEBUGGING>
+Mnemonic: Extra error explanation.
-The current value of the debugging flags. (Mnemonic: value of B<-D>
-switch.) May be read or set. Like its command-line equivalent, you can use
-numeric or symbolic values, eg C<$^D = 10> or C<$^D = "st">.
+=item $EXCEPTIONS_BEING_CAUGHT
-=item ${^RE_DEBUG_FLAGS}
+=item $^S
+X<$^S> X<$EXCEPTIONS_BEING_CAUGHT>
-The current value of the regex debugging flags. Set to 0 for no debug output
-even when the re 'debug' module is loaded. See L<re> for details.
+Current state of the interpreter.
-=item ${^RE_TRIE_MAXBUF}
+ $^S State
+ --------- -------------------------------------
+ undef Parsing module, eval, or main program
+ true (1) Executing an eval
+ false (0) Otherwise
-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.
+The first state may happen in C<$SIG{__DIE__}> and C<$SIG{__WARN__}>
+handlers.
-=item $SYSTEM_FD_MAX
+The English name $EXCEPTIONS_BEING_CAUGHT is slightly misleading, because
+the C<undef> value does not indicate whether exceptions are being caught,
+since compilation of the main program does not catch exceptions.
-=item $^F
-X<$^F> X<$SYSTEM_FD_MAX>
+This variable was added in Perl 5.004.
-The maximum system file descriptor, ordinarily 2. System file
-descriptors are passed to exec()ed processes, while higher file
-descriptors are not. Also, during an open(), system file descriptors are
-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 corresponding file, pipe, or socket was opened, not the
-time of the exec().
+=item $WARNING
-=item $^H
+=item $^W
+X<$^W> X<$WARNING>
-WARNING: This variable is strictly for internal use only. Its availability,
-behavior, and contents are subject to change without notice.
+The current value of the warning switch, initially true if B<-w> was
+used, false otherwise, but directly modifiable.
-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.
+See also L<warnings>.
-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.
+Mnemonic: related to the B<-w> switch.
-This behavior provides the semantic of lexical scoping, and is used in,
-for instance, the C<use strict> pragma.
+=item ${^WARNING_BITS}
+X<${^WARNING_BITS}>
-The contents should be an integer; different bits of it are used for
-different pragmatic flags. Here's an example:
+The current set of warning checks enabled by the C<use warnings> pragma.
+It has the same scoping as the C<$^H> and C<%^H> variables. The exact
+values are considered internal to the L<warnings> pragma and may change
+between versions of Perl.
- sub add_100 { $^H |= 0x100 }
+This variable was added in Perl v5.6.0.
- sub foo {
- BEGIN { add_100() }
- bar->baz($boon);
- }
+=item $OS_ERROR
-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.
+=item $ERRNO
-Substitution of the above BEGIN block with:
+=item $!
+X<$!> X<$ERRNO> X<$OS_ERROR>
- BEGIN { require strict; strict->import('vars') }
+When referenced, C<$!> retrieves the current value
+of the C C<errno> integer variable.
+If C<$!> is assigned a numerical value, that value is stored in C<errno>.
+When referenced as a string, C<$!> yields the system error string
+corresponding to C<errno>.
-demonstrates how C<use strict 'vars'> is implemented. Here's a conditional
-version of the same lexical pragma:
+Many system or library calls set C<errno> if they fail,
+to indicate the cause of failure. They usually do B<not>
+set C<errno> to zero if they succeed. This means C<errno>,
+hence C<$!>, is meaningful only I<immediately> after a B<failure>:
- BEGIN { require strict; strict->import('vars') if $condition }
+ 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.
-=item %^H
+Here, I<meaningless> means that C<$!> may be unrelated to the outcome
+of the C<open()> operator. Assignment to C<$!> is similarly ephemeral.
+It can be used immediately before invoking the C<die()> operator,
+to set the exit value, or to inspect the system error string
+corresponding to error I<n>, or to restore C<$!> to a meaningful state.
-The %^H hash provides the same scoping semantic as $^H. This makes it
-useful for implementation of lexically scoped pragmas. See L<perlpragma>.
+Mnemonic: What just went bang?
-=item $INPLACE_EDIT
+=item %OS_ERROR
-=item $^I
-X<$^I> X<$INPLACE_EDIT>
+=item %ERRNO
-The current value of the inplace-edit extension. Use C<undef> to disable
-inplace editing. (Mnemonic: value of B<-i> switch.)
+=item %!
+X<%!> X<%OS_ERROR> X<%ERRNO>
-=item $^M
-X<$^M>
+Each element of C<%!> has a true value only if C<$!> is set to that
+value. For example, C<$!{ENOENT}> is true if and only if the current
+value of C<$!> is C<ENOENT>; 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). To
+check if a particular key is meaningful on your system, use C<exists
+$!{the_key}>; for a list of legal keys, use C<keys %!>. See L<Errno>
+for more information, and also see L</$!>.
-By default, running out of memory is an untrappable, fatal error.
-However, if suitably built, Perl can use the contents of C<$^M>
-as an emergency memory pool after die()ing. Suppose that your Perl
-were compiled with C<-DPERL_EMERGENCY_SBRK> and used Perl's malloc.
-Then
+This variable was added in Perl 5.005.
- $^M = 'a' x (1 << 16);
+=item $CHILD_ERROR
-would allocate a 64K buffer for use in an emergency. See the
-F<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 L<English|English> long name for
-this variable.
+=item $?
+X<$?> X<$CHILD_ERROR>
-=item $OSNAME
+The status returned by the last pipe close, backtick (C<``>) command,
+successful call to C<wait()> or C<waitpid()>, or from the C<system()>
+operator. This is just the 16-bit status word returned by the
+traditional Unix C<wait()> system call (or else is made up to look
+like it). Thus, the 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.
-=item $^O
-X<$^O> X<$OSNAME>
+Additionally, if the C<h_errno> variable is supported in C, its value
+is returned via C<$?> if any C<gethost*()> function fails.
-The name of the operating system under which this copy of Perl was
-built, as determined during the configuration process. For examples
-see L<perlport/PLATFORMS>.
+If you have installed a signal handler for C<SIGCHLD>, the
+value of C<$?> will usually be wrong outside that handler.
-The value is identical to C<$Config{'osname'}>. See also L<Config>
-and the B<-V> command-line switch documented in L<perlrun>.
+Inside an C<END> subroutine C<$?> contains the value that is going to be
+given to C<exit()>. You can modify C<$?> in an C<END> subroutine to
+change the exit status of your program. For example:
-In Windows platforms, $^O is not very helpful: since it is always
-C<MSWin32>, it doesn't tell the difference between
-95/98/ME/NT/2000/XP/CE/.NET. Use Win32::GetOSName() or
-Win32::GetOSVersion() (see L<Win32> and L<perlport>) to distinguish
-between the variants.
+ END {
+ $? = 1 if $? == 255; # die would make it 255
+ }
-=item ${^OPEN}
+Under VMS, the pragma C<use vmsish 'status'> makes C<$?> reflect the
+actual VMS exit status, instead of the default emulation of POSIX
+status; see L<perlvms/$?> for details.
-An internal variable used by PerlIO. A string in two parts, separated
-by a C<\0> byte, the first part describes the input layers, the second
-part describes the output layers.
+Mnemonic: similar to B<sh> and B<ksh>.
-=item $PERLDB
+=item $EVAL_ERROR
-=item $^P
-X<$^P> X<$PERLDB>
+=item $@
+X<$@> X<$EVAL_ERROR>
-The internal variable for debugging support. The meanings of the
-various bits are subject to change, but currently indicate:
+The Perl syntax error message from the
+last C<eval()> operator. If C<$@> is
+the null string, the last C<eval()> parsed and executed correctly
+(although the operations you invoked may have failed in the normal
+fashion).
-=over 6
+Warning messages are not collected in this variable. You can, however,
+set up a routine to process warnings by setting C<$SIG{__WARN__}> as
+described in L</%SIG>.
-=item 0x01
+Mnemonic: Where was the syntax error "at"?
-Debug subroutine enter/exit.
+=back
-=item 0x02
+=head2 Variables related to the interpreter state
-Line-by-line debugging. Causes DB::DB() subroutine to be called for each
-statement executed. Also causes saving source code lines (like 0x400).
+These variables provide information about the current interpreter state.
-=item 0x04
+=over 8
-Switch off optimizations.
+=item $COMPILING
-=item 0x08
+=item $^C
+X<$^C> X<$COMPILING>
-Preserve more data for future interactive inspections.
+The current value of the flag associated with the B<-c> switch.
+Mainly of use with B<-MO=...> to allow code to alter its behavior
+when being compiled, such as for example to C<AUTOLOAD> at compile
+time rather than normal, deferred loading. Setting
+C<$^C = 1> is similar to calling C<B::minus_c>.
-=item 0x10
+This variable was added in Perl v5.6.0.
-Keep info about source lines on which a subroutine is defined.
+=item $DEBUGGING
-=item 0x20
+=item $^D
+X<$^D> X<$DEBUGGING>
-Start with single-step on.
+The current value of the debugging flags. May be read or set. Like its
+command-line equivalent, you can use numeric or symbolic values, eg
+C<$^D = 10> or C<$^D = "st">.
-=item 0x40
+Mnemonic: value of B<-D> switch.
-Use subroutine address instead of name when reporting.
+=item ${^ENCODING}
+X<${^ENCODING}>
-=item 0x80
+The I<object reference> to the C<Encode> object that is used to convert
+the source code to Unicode. Thanks to this variable your Perl script
+does not have to be written in UTF-8. Default is I<undef>. The direct
+manipulation of this variable is highly discouraged.
-Report C<goto &subroutine> as well.
+This variable was added in Perl 5.8.2.
-=item 0x100
+=item ${^GLOBAL_PHASE}
+X<${^GLOBAL_PHASE}>
-Provide informative "file" names for evals based on the place they were compiled.
+The current phase of the perl interpreter.
-=item 0x200
+Possible values are:
-Provide informative names to anonymous subroutines based on the place they
-were compiled.
+=over 8
-=item 0x400
+=item CONSTRUCT
-Save source code lines into C<@{"_<$filename"}>.
+The C<PerlInterpreter*> is being constructed via C<perl_construct>. This
+value is mostly there for completeness and for use via the
+underlying C variable C<PL_phase>. It's not really possible for Perl
+code to be executed unless construction of the interpreter is
+finished.
-=back
+=item START
-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 L<perldebguts>.
+This is the global compile-time. That includes, basically, every
+C<BEGIN> block executed directly or indirectly from during the
+compile-time of the top-level program.
-=item $LAST_REGEXP_CODE_RESULT
+This phase is not called "BEGIN" to avoid confusion with
+C<BEGIN>-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
+C<eval "use SomeModule"> are not global interpreter phases, and
+therefore aren't reflected by C<${^GLOBAL_PHASE}>.
-=item $^R
-X<$^R> X<$LAST_REGEXP_CODE_RESULT>
+=item CHECK
-The result of evaluation of the last successful C<(?{ code })>
-regular expression assertion (see L<perlre>). May be written to.
+Execution of any C<CHECK> blocks.
-=item $EXCEPTIONS_BEING_CAUGHT
+=item INIT
-=item $^S
-X<$^S> X<$EXCEPTIONS_BEING_CAUGHT>
+Similar to "CHECK", but for C<INIT>-blocks, not C<CHECK> blocks.
-Current state of the interpreter.
+=item RUN
- $^S State
- --------- -------------------
- undef Parsing module/eval
- true (1) Executing an eval
- false (0) Otherwise
+The main run-time, i.e. the execution of C<PL_main_root>.
-The first state may happen in $SIG{__DIE__} and $SIG{__WARN__} handlers.
+=item END
-=item $BASETIME
+Execution of any C<END> blocks.
-=item $^T
-X<$^T> X<$BASETIME>
+=item DESTRUCT
-The time at which the program began running, in seconds since the
-epoch (beginning of 1970). The values returned by the B<-M>, B<-A>,
-and B<-C> filetests are based on this value.
+Global destruction.
-=item ${^TAINT}
+=back
-Reflects if taint mode is on or off. 1 for on (the program was run with
-B<-T>), 0 for off, -1 when only taint warnings are enabled (i.e. with
-B<-t> or B<-TU>). This variable is read-only.
+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.
-=item ${^UNICODE}
+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.
-Reflects certain Unicode settings of Perl. See L<perlrun>
-documentation for the C<-C> switch for more information about
-the possible values. This variable is set during Perl startup
-and is thereafter read-only.
+An example of all of the phases Perl code can see:
-=item ${^UTF8CACHE}
+ BEGIN { print "compile-time: ${^GLOBAL_PHASE}\n" }
-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.
+ INIT { print "init-time: ${^GLOBAL_PHASE}\n" }
-=item ${^UTF8LOCALE}
+ CHECK { print "check-time: ${^GLOBAL_PHASE}\n" }
-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 C<-CL> command-line
-switch); see L<perlrun> for more info on this.
+ {
+ package Print::Phase;
-=item $PERL_VERSION
+ sub new {
+ my ($class, $time) = @_;
+ return bless \$time, $class;
+ }
-=item $^V
-X<$^V> X<$PERL_VERSION>
+ sub DESTROY {
+ my $self = shift;
+ print "$$self: ${^GLOBAL_PHASE}\n";
+ }
+ }
-The revision, version, and subversion of the Perl interpreter, represented
-as a C<version> object.
+ print "run-time: ${^GLOBAL_PHASE}\n";
-This variable first appeared in perl 5.6.0; earlier versions of perl will
-see an undefined value. Before perl 5.10.0 $^V was represented as a v-string.
+ my $runtime = Print::Phase->new(
+ "lexical variables are garbage collected before END"
+ );
-$^V 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:
+ END { print "end-time: ${^GLOBAL_PHASE}\n" }
- warn "Hashes not randomized!\n" if !$^V or $^V lt v5.8.1
+ our $destruct = Print::Phase->new(
+ "package variables are garbage collected after END"
+ );
-To convert C<$^V> into its string representation use sprintf()'s
-C<"%vd"> conversion:
+This will print out
- printf "version is v%vd\n", $^V; # Perl's version
+ 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
-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.
+This variable was added in Perl 5.14.0.
-See also C<$]> for an older representation of the Perl version.
+=item $^H
+X<$^H>
-=item $WARNING
+WARNING: This variable is strictly for
+internal use only. Its availability,
+behavior, and contents are subject to change without notice.
-=item $^W
-X<$^W> X<$WARNING>
+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.
-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<warnings>.
+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 C<$^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 C<$^H>.
-=item ${^WARNING_BITS}
+This behavior provides the semantic of lexical scoping, and is used in,
+for instance, the C<use strict> pragma.
-The current set of warning checks enabled by the C<use warnings> pragma.
-See the documentation of C<warnings> for more details.
+The contents should be an integer; different bits of it are used for
+different pragmatic flags. Here's an example:
-=item ${^WIN32_SLOPPY_STAT}
-X<sitecustomize> X<sitecustomize.pl>
+ sub add_100 { $^H |= 0x100 }
-If this variable is set to a true value, then stat() on Windows will
-not try to open the file. This means that the link count cannot be
-determined and file attributes may be out of date if additional
-hardlinks to the file exist. On the other hand, not opening the file
-is considerably faster, especially for files on network drives.
+ sub foo {
+ BEGIN { add_100() }
+ bar->baz($boon);
+ }
-This variable could be set in the F<sitecustomize.pl> file to
-configure the local Perl installation to use "sloppy" stat() by
-default. See the documentation for B<-f> in
-L<perlrun|perlrun/"Command Switches"> for more information about site
-customization.
+Consider what happens during execution of the BEGIN block. At this point
+the BEGIN block has already been compiled, but the body of C<foo()> is still
+being compiled. The new value of C<$^H>
+will therefore be visible only while
+the body of C<foo()> is being compiled.
-=item $EXECUTABLE_NAME
+Substitution of C<BEGIN { add_100() }> block with:
-=item $^X
-X<$^X> X<$EXECUTABLE_NAME>
+ BEGIN { require strict; strict->import('vars') }
-The name used to execute the current copy of Perl, from C's
-C<argv[0]> or (where supported) F</proc/self/exe>.
+demonstrates how C<use strict 'vars'> is implemented. Here's a conditional
+version of the same lexical pragma:
-Depending on the host operating system, the value of $^X 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 $^X is in PATH. For VMS, the
-value may or may not include a version number.
+ BEGIN {
+ require strict; strict->import('vars') if $condition
+ }
-You usually can use the value of $^X to re-invoke an independent
-copy of the same perl that is currently running, e.g.,
+This variable was added in Perl 5.003.
- @first_run = `$^X -le "print int rand 100 for 1..100"`;
+=item %^H
+X<%^H>
-But recall that not all operating systems support forking or
-capturing of the output of commands, so this complex statement
-may not be portable.
+The C<%^H> hash provides the same scoping semantic as C<$^H>. This makes
+it useful for implementation of lexically scoped pragmas. See
+L<perlpragma>.
-It is not safe to use the value of $^X 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 $^X to a path name, use the
-following statements:
+When putting items into C<%^H>, 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
+C<Foo::Bar> should use keys such as C<Foo::Bar/baz>.
- # Build up a set of file names (not command names).
- use Config;
- $this_perl = $^X;
- if ($^O ne 'VMS')
- {$this_perl .= $Config{_exe}
- unless $this_perl =~ m/$Config{_exe}$/i;}
+This variable was added in Perl v5.6.0.
-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 $^X. The following statements accomplish
-this goal, and produce a pathname that can be invoked as a
-command or referenced as a file.
+=item ${^OPEN}
+X<${^OPEN}>
- use Config;
- $secure_perl_path = $Config{perlpath};
- if ($^O ne 'VMS')
- {$secure_perl_path .= $Config{_exe}
- unless $secure_perl_path =~ m/$Config{_exe}$/i;}
+An internal variable used by PerlIO. A string in two parts, separated
+by a C<\0> byte, the first part describes the input layers, the second
+part describes the output layers.
-=item ARGV
-X<ARGV>
+This variable was added in Perl v5.8.0.
-The special filehandle that iterates over command-line filenames in
-C<@ARGV>. Usually written as the null filehandle in the angle operator
-C<< <> >>. Note that currently C<ARGV> only has its magical effect
-within the C<< <> >> operator; elsewhere it is just a plain filehandle
-corresponding to the last file opened by C<< <> >>. In particular,
-passing C<\*ARGV> 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 C<@ARGV>.
+=item $PERLDB
-=item $ARGV
-X<$ARGV>
+=item $^P
+X<$^P> X<$PERLDB>
-contains the name of the current file when reading from <>.
+The internal variable for debugging support. The meanings of the
+various bits are subject to change, but currently indicate:
-=item @ARGV
-X<@ARGV>
+=over 6
-The array @ARGV contains the command-line arguments intended for
-the script. C<$#ARGV> is generally the number of arguments minus
-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 0x01
-=item ARGVOUT
-X<ARGVOUT>
+Debug subroutine enter/exit.
-The special filehandle that points to the currently open output file
-when doing edit-in-place processing with B<-i>. Useful when you have
-to do a lot of inserting and don't want to keep modifying $_. See
-L<perlrun> for the B<-i> switch.
+=item 0x02
-=item @F
-X<@F>
+Line-by-line debugging. Causes C<DB::DB()> subroutine to be called for
+each statement executed. Also causes saving source code lines (like
+0x400).
-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 0x04
-=item @INC
-X<@INC>
+Switch off optimizations.
-The array @INC contains the list of places that the C<do EXPR>,
-C<require>, or C<use> constructs look for their library files. It
-initially consists of the arguments to any B<-I> command-line
-switches, followed by the default Perl library, probably
-F</usr/local/lib/perl>, followed by ".", to represent the current
-directory. ("." will not be appended if taint checks are enabled, either by
-C<-T> or by C<-t>.) If you need to modify this at runtime, you should use
-the C<use lib> pragma to get the machine-dependent library properly
-loaded also:
+=item 0x08
- use lib '/mypath/libdir/';
- use SomeMod;
+Preserve more data for future interactive inspections.
-You can also insert hooks into the file inclusion system by putting Perl
-code directly into @INC. Those hooks may be subroutine references, array
-references or blessed objects. See L<perlfunc/require> for details.
+=item 0x10
-=item @ARG
+Keep info about source lines on which a subroutine is defined.
-=item @_
-X<@_> X<@ARG>
+=item 0x20
-Within a subroutine the array @_ contains the parameters passed to that
-subroutine. See L<perlsub>.
+Start with single-step on.
-=item %INC
-X<%INC>
+=item 0x40
-The hash %INC contains entries for each filename included via the
-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 hash to determine whether a particular file has
-already been included.
+Use subroutine address instead of name when reporting.
-If the file was loaded via a hook (e.g. a subroutine reference, see
-L<perlfunc/require> for a description of these hooks), this hook is
-by default inserted into %INC in place of a filename. Note, however,
-that the hook may have set the %INC entry by itself to provide some more
-specific info.
+=item 0x80
-=item %ENV
+Report C<goto &subroutine> as well.
-=item $ENV{expr}
-X<%ENV>
+=item 0x100
-The hash %ENV contains your current environment. Setting a
-value in C<ENV> changes the environment for any child processes
-you subsequently fork() off.
+Provide informative "file" names for evals based on the place they were compiled.
-=item %SIG
+=item 0x200
-=item $SIG{expr}
-X<%SIG>
+Provide informative names to anonymous subroutines based on the place they
+were compiled.
-The hash C<%SIG> contains signal handlers for signals. For example:
+=item 0x400
- sub handler { # 1st argument is signal name
- my($sig) = @_;
- print "Caught a SIG$sig--shutting down\n";
- close(LOG);
- exit(0);
- }
+Save source code lines into C<@{"_<$filename"}>.
- $SIG{'INT'} = \&handler;
- $SIG{'QUIT'} = \&handler;
- ...
- $SIG{'INT'} = 'DEFAULT'; # restore default action
- $SIG{'QUIT'} = 'IGNORE'; # ignore SIGQUIT
+=back
-Using a value of C<'IGNORE'> usually has the effect of ignoring the
-signal, except for the C<CHLD> signal. See L<perlipc> for more about
-this special case.
+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 L<perldebguts>.
-Here are some other examples:
+=item ${^TAINT}
+X<${^TAINT}>
- $SIG{"PIPE"} = "Plumber"; # assumes main::Plumber (not recommended)
- $SIG{"PIPE"} = \&Plumber; # just fine; assume current Plumber
- $SIG{"PIPE"} = *Plumber; # somewhat esoteric
- $SIG{"PIPE"} = Plumber(); # oops, what did Plumber() return??
+Reflects if taint mode is on or off. 1 for on (the program was run with
+B<-T>), 0 for off, -1 when only taint warnings are enabled (i.e. with
+B<-t> or B<-TU>).
-Be sure not to use a bareword as the name of a signal handler,
-lest you inadvertently call it.
+This variable is read-only.
-If your system has the sigaction() function then signal handlers are
-installed using it. This means you get reliable signal handling.
+This variable was added in Perl v5.8.0.
-The default delivery policy of signals changed in Perl 5.8.0 from
-immediate (also known as "unsafe") to deferred, also known as
-"safe signals". See L<perlipc> for more information.
+=item ${^UNICODE}
+X<${^UNICODE}>
-Certain internal hooks can be also set using the %SIG hash. The
-routine indicated by C<$SIG{__WARN__}> is called when a warning message is
-about to be printed. The warning message is passed as the first
-argument. The presence of a C<__WARN__> hook causes the ordinary printing
-of warnings to C<STDERR> to be suppressed. You can use this to save warnings
-in a variable, or turn warnings into fatal errors, like this:
+Reflects certain Unicode settings of Perl. See L<perlrun>
+documentation for the C<-C> switch for more information about
+the possible values.
- local $SIG{__WARN__} = sub { die $_[0] };
- eval $proggie;
+This variable is set during Perl startup and is thereafter read-only.
-As the C<'IGNORE'> hook is not supported by C<__WARN__>, you can
-disable warnings using the empty subroutine:
+This variable was added in Perl v5.8.2.
- local $SIG{__WARN__} = sub {};
+=item ${^UTF8CACHE}
+X<${^UTF8CACHE}>
-The routine indicated by C<$SIG{__DIE__}> is called when a fatal exception
-is about to be thrown. The error message is passed as the first
-argument. When a C<__DIE__> hook routine returns, the exception
-processing continues as it would have in the absence of the hook,
-unless the hook routine itself exits via a C<goto>, a loop exit, or a C<die()>.
-The C<__DIE__> handler is explicitly disabled during the call, so that you
-can die from a C<__DIE__> handler. Similarly for C<__WARN__>.
+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.
-Due to an implementation glitch, the C<$SIG{__DIE__}> hook is called
-even inside an eval(). Do not use this to rewrite a pending exception
-in C<$@>, or as a bizarre substitute for overriding C<CORE::GLOBAL::die()>.
-This strange action at a distance may be fixed in a future release
-so that C<$SIG{__DIE__}> is only called if your program is about
-to exit, as was the original intent. Any other use is deprecated.
-
-C<__DIE__>/C<__WARN__> handlers are very special in one respect:
-they may be called to report (probable) errors found by the parser.
-In such a case the parser may be in inconsistent state, so any
-attempt to evaluate Perl code from such a handler will probably
-result in a segfault. This means that warnings or errors that
-result from parsing Perl should be used with extreme caution, like
-this:
+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.
- require Carp if defined $^S;
- Carp::confess("Something wrong") if defined &Carp::confess;
- die "Something wrong, but could not load Carp to give backtrace...
- To see backtrace try starting Perl with -MCarp switch";
+=item ${^UTF8LOCALE}
+X<${^UTF8LOCALE}>
-Here the first line will load Carp I<unless> it is the parser who
-called the handler. The second line will print backtrace and die if
-Carp was available. The third line will be executed only if Carp was
-not available.
+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 C<-CL> command-line
+switch); see L<perlrun> for more info on this.
-See L<perlfunc/die>, L<perlfunc/warn>, L<perlfunc/eval>, and
-L<warnings> for additional information.
+This variable was added in Perl v5.8.8.
=back
-=head2 Names that are no longer special
+=head2 Deprecated and removed variables
-These variables had special meaning in prior versions of Perl but now
-have no effect and will cause warnings if used. They are included
-here for historical reference.
+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.
+
+Once a variable is removed, its use triggers an error telling you
+the variable is unsupported.
+
+See L<perldiag> for details about error messages.
=over 8
-=item $#
-X<$#>
+=item $OFMT
-C<$#> used to be a variable that could be used to format printed numbers.
-After a deprecation cycle, its magic was removed in Perl 5.10 and using it
-now triggers a warning: C<$# is no longer supported>.
+=item $#
+X<$#> X<$OFMT>
-C<$#> is also used as sigil, which, when prepended on the name of an
-array, gives the index of the last element in that array.
+C<$#> 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: C<$# is no longer supported>.
- my @array = ("a", "b", "c");
- my $last_index = $#array; # $last_index is 2
+This is not the sigil you use in front of an array name to get the
+last index, like C<$#array>. That's still how you get the last index
+of an array in Perl. The two have nothing to do with each other.
- for my $i (0 .. $#array) {
- print "The value of index $i is $array[$i]\n";
- }
+Deprecated in Perl 5.
-Also see L<perldata>.
+Removed in Perl v5.10.0.
=item $*
X<$*>
-C<$*> used to be a variable that enabled multiline matching.
-After a deprecation cycle, its magic was removed in Perl 5.10.
+C<$*> 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: C<$* is no longer supported>.
-Use the C</s> and C</m> regexp modifiers instead.
-
-Also see L<perlre>.
+You should use the C</s> and C</m> regexp modifiers instead.
-=back
+Deprecated in Perl 5.
-=head2 Error Indicators
-X<error> X<exception>
+Removed in Perl v5.10.0.
-The variables C<$@>, C<$!>, C<$^E>, and C<$?> 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.
+=item $ARRAY_BASE
-To illustrate the differences between these variables, consider the
-following Perl expression, which uses a single-quoted string:
+=item $[
+X<$[> X<$ARRAY_BASE>
- eval q{
- open my $pipe, "/cdrom/install |" or die $!;
- my @res = <$pipe>;
- close $pipe or die "bad pipe: $?, $!";
- };
+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 B<awk> (or Fortran)
+when subscripting and when evaluating the index() and substr() functions.
-After execution of this statement all 4 variables may have been set.
+As of release 5 of Perl, assignment to C<$[> 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.
-C<$@> is set if the string to be C<eval>-ed did not compile (this
-may happen if C<open> or C<close> were imported with bad prototypes),
-or if Perl code executed during evaluation die()d . In these cases
-the value of $@ is the compile error, or the argument to C<die>
-(which will interpolate C<$!> and C<$?>). (See also L<Fatal>,
-though.)
+Prior to Perl v5.10.0, assignment to C<$[> could be seen from outer lexical
+scopes in the same file, unlike other compile-time directives (such as
+L<strict>). Using local() on it would bind its value strictly to a lexical
+block. Now it is always lexically scoped.
-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.
+As of Perl v5.16.0, it is implemented by the L<arybase> module. See
+L<arybase> for more details on its behaviour.
-Under a few operating systems, C<$^E> 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 C<$^E>
-the same as C<$!>.
+Under C<use v5.16>, or C<no feature "array_base">, C<$[> no longer has any
+effect, and always contains 0. Assigning 0 to it is permitted, but any
+other value will produce an error.
-Finally, C<$?> may be set to non-0 value if the external program
-F</cdrom/install> fails. The upper eight bits reflect specific
-error conditions encountered by the program (the program's exit()
-value). The lower eight bits reflect mode of failure, like signal
-death and core dump information See wait(2) for details. In
-contrast to C<$!> and C<$^E>, which are set only if error condition
-is detected, the variable C<$?> is set on each C<wait> or pipe
-C<close>, overwriting the old value. This is more like C<$@>, which
-on every eval() is always set on failure and cleared on success.
+Mnemonic: [ begins subscripts.
-For more details, see the individual descriptions at C<$@>, C<$!>, C<$^E>,
-and C<$?>.
+Deprecated in Perl v5.12.0.
-=head2 Technical Note on the Syntax of Variable Names
+=item $OLD_PERL_VERSION
-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
-C<::> or C<'>. In this case, the part before the last C<::> or
-C<'> is taken to be a I<package qualifier>; see L<perlmod>.
+=item $]
+X<$]> X<$OLD_PERL_VERSION>
-Perl variable names may also be a sequence of digits or a single
-punctuation or control character. 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. Perl has a special syntax for the single-control-character
-names: It understands C<^X> (caret C<X>) to mean the control-C<X>
-character. For example, the notation C<$^W> (dollar-sign caret
-C<W>) is the scalar variable whose name is the single character
-control-C<W>. This is better than typing a literal control-C<W>
-into your program.
+See L</$^V> for a more modern representation of the Perl version that allows
+accurate string comparisons.
-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
-name is a control-C<F> followed by two C<o>'s. These variables are
-reserved for future special uses by Perl, except for the ones that
-begin with C<^_> (control-underscore or caret-underscore). No
-control-character name that begins with C<^_> will acquire a special
-meaning in any future version of Perl; such names may therefore be
-used safely in programs. C<$^_> itself, however, I<is> reserved.
+The version + patchlevel / 1000 of the Perl interpreter. This variable
+can be used to determine whether the Perl interpreter executing a
+script is in the right range of versions:
-Perl identifiers that begin with digits, control characters, or
-punctuation characters are exempt from the effects of the C<package>
-declaration and are always forced to be in package C<main>; they are
-also exempt from C<strict 'vars'> errors. A few other names are also
-exempt in these ways:
+ warn "No checksumming!\n" if $] < 3.019;
- ENV STDIN
- INC STDOUT
- ARGV STDERR
- ARGVOUT _
- SIG
+The floating point representation can sometimes lead to inaccurate
+numeric comparisons.
-In particular, the new special C<${^_XYZ}> variables are always taken
-to be in package C<main>, regardless of any C<package> declarations
-presently in scope.
+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.
-=head1 BUGS
+Mnemonic: Is this version of perl in the right bracket?
-Due to an unfortunate accident of Perl's implementation, C<use
-English> imposes a considerable performance penalty on all regular
-expression matches in a program, regardless of whether they occur
-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.cpan.org/modules/by-module/Devel/ )
-for more information. Writing C<use English '-no_match_vars';>
-avoids the performance penalty.
+=back
-Having to even think about the C<$^S> variable in your exception
-handlers is simply wrong. C<$SIG{__DIE__}> as currently implemented
-invites grievous and difficult to track down errors. Avoid it
-and use an C<END{}> or CORE::GLOBAL::die override instead.
+=cut
https://perl5.git.perl.org / perl5.git / blobdiff