Contains the name of the program being executed.
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
+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
+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.
($foo{$a},$foo{$b},$foo{$c})
-Default is "\034", the same as SUBSEP in B<awk>. If your keys contain
+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
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
+time rather than normal, deferred loading. Setting
C<$^C = 1> is similar to calling C<B::minus_c>.
This variable was added in Perl 5.6.
Mnemonic: value of B<-D> switch.
=item ${^ENCODING}
-X<$^ENCODING>
+X<${^ENCODING}>
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
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
+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 ${^GLOBAL_PHASE}
+X<${^GLOBAL_PHASE}>
+
+The current phase of the perl interpreter.
+
+Possible values are:
+
+=over 8
+
+=item CONSTRUCT
+
+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.
+
+=item START
+
+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.
+
+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 CHECK
+
+Execution of any C<CHECK> blocks.
+
+=item INIT
+
+Similar to "CHECK", but for C<INIT>-blocks, not C<CHECK> blocks.
+
+=item RUN
+
+The main run-time, i.e. the execution of C<PL_main_root>.
+
+=item END
+
+Execution of any C<END> blocks.
+
+=item DESTRUCT
+
+Global destruction.
+
+=back
+
+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.
+
+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.
+
+An example of all of the phases Perl code can see:
+
+ BEGIN { print "compile-time: ${^GLOBAL_PHASE}\n" }
+
+ INIT { print "init-time: ${^GLOBAL_PHASE}\n" }
+
+ CHECK { print "check-time: ${^GLOBAL_PHASE}\n" }
+
+ {
+ package Print::Phase;
+
+ sub new {
+ my ($class, $time) = @_;
+ return bless \$time, $class;
+ }
+
+ sub DESTROY {
+ my $self = shift;
+ print "$$self: ${^GLOBAL_PHASE}\n";
+ }
+ }
+
+ print "run-time: ${^GLOBAL_PHASE}\n";
+
+ my $runtime = Print::Phase->new(
+ "lexical variables are garbage collected before END"
+ );
+
+ END { print "end-time: ${^GLOBAL_PHASE}\n" }
+
+ our $destruct = Print::Phase->new(
+ "package variables are garbage collected after END"
+ );
+
+This will print out
+
+ 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
+
+This variable was added in Perl 5.14.0.
+
=item $^H
+X<$^H>
WARNING: This variable is strictly for internal use only. Its availability,
behavior, and contents are subject to change without notice.
being compiled. The new value of C<$^H> will therefore be visible only while
the body of C<foo()> is being compiled.
-Substitution of the above BEGIN block with:
+Substitution of C<BEGIN { add_100() }> block with:
BEGIN { require strict; strict->import('vars') }
-demonstrates how C<use strict 'vars'> is implemented. Here's a conditional
+demonstrates how C<use strict 'vars'> is implemented. Here's a conditional
version of the same lexical pragma:
BEGIN { require strict; strict->import('vars') if $condition }
This variable was added in Perl 5.003.
=item %^H
+X<%^H>
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>.
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
+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,
+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:
This variable was added in Perl 5.003.
=item ${^OPEN}
+X<${^OPEN}>
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
=back
Some bits may be relevant at compile-time only, some at
-run-time only. This is a new mechanism and the details may change.
+run-time only. This is a new mechanism and the details may change.
See also L<perldebguts>.
=item %SIG
-
-=item $SIG{expr}
X<%SIG>
The hash C<%SIG> contains signal handlers for signals. For example:
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.
+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
+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:
not available.
Having to even think about the C<$^S> variable in your exception
-handlers is simply wrong. C<$SIG{__DIE__}> as currently implemented
+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.
and B<-C> filetests are based on this value.
=item ${^TAINT}
+X<${^TAINT}>
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
This variable was added in Perl 5.8.
=item ${^UNICODE}
+X<${^UNICODE}>
-Reflects certain Unicode settings of Perl.
See L<perlrun>
+Reflects certain Unicode settings of Perl. See L<perlrun>
documentation for the C<-C> switch for more information about
the possible values.
This variable was added in Perl 5.8.2.
=item ${^UTF8CACHE}
+X<${^UTF8CACHE}>
This variable controls the state of the internal UTF-8 offset caching code.
1 for on (the default), 0 for off, -1 to debug the caching code by checking
This variable was added in Perl 5.8.9.
=item ${^UTF8LOCALE}
+X<${^UTF8LOCALE}>
This variable indicates whether a UTF-8 locale was detected by perl at
startup. This information is used by perl when it's in
Mnemonic: use ^V for Version Control.
=item ${^WIN32_SLOPPY_STAT}
-X<sitecustomize> X<sitecustomize.pl>
+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
=item $PREMATCH
=item $`
-X<$`> X<$PREMATCH>
+X<$`> X<$PREMATCH> X<${^PREMATCH}>
The string preceding whatever was matched by the last successful
pattern match, not counting any matches hidden within a BLOCK or C<eval>
Mnemonic: C<`> often precedes a quoted string.
=item ${^PREMATCH}
-X<${^PREMATCH}>
+X<$`> X<${^PREMATCH}>
This is similar to C<$`> ($PREMATCH) except that it does not incur the
performance penalty associated with that variable, and is only guaranteed
=item $POSTMATCH
=item $'
-X<$'> X<$POSTMATCH>
+X<$'> X<$POSTMATCH> X<${^POSTMATCH}> X<@->
The string following whatever was matched by the last successful
pattern match (not counting any matches hidden within a BLOCK or C<eval()>
Mnemonic: C<'> often follows a quoted string.
=item ${^POSTMATCH}
-X<${^POSTMATCH}>
+X<${^POSTMATCH}> X<$'> X<$POSTMATCH>
This is similar to C<$'> (C<$POSTMATCH>) except that it does not incur the
performance penalty associated with that variable, and is only guaranteed
=item $LAST_SUBMATCH_RESULT
=item $^N
-X<$^N>
+X<$^N> X<$LAST_SUBMATCH_RESULT>
The text matched by the used group most-recently closed (i.e. the group
with the rightmost closing parenthesis) of the last successful search
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
+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 %LAST_PAREN_MATCH
=item %+
-X<%+>
+X<%+> X<%LAST_PAREN_MATCH>
Similar to C<@+>, the C<%+> hash allows access to the named capture
buffers, should they exist, in the last successful match in the
This array holds the offsets of the beginnings of the last
successful submatches in the currently active dynamic scope.
C<$-[0]> is the offset into the string of the beginning of the
-entire match. The I<n>th element of this array holds the offset
+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 C<$1>
begins, C<$-[2]> the offset where C<$2> begins, and so on.
This variable was added in Perl 5.6.
+=item %LAST_MATCH_START
+
=item %-
-X<%->
+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
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 5.10.
=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
=item $ARGV
X<$ARGV>
-contains the name of the current file when reading from <>.
+Contains the name of the current file when reading from C<< <> >>.
=item @ARGV
X<@ARGV>
-The array @ARGV contains the command-line arguments intended for
+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 C<$0> for the command name.
to do a lot of inserting and don't want to keep modifying C<$_>. See
L<perlrun> for the B<-i> switch.
-=item Handle->output_field_separator EXPR
+=item Handle->output_field_separator( EXPR )
=item $OUTPUT_FIELD_SEPARATOR
Mnemonic: what is printed when there is a "," in your print statement.
-=item HANDLE->input_line_number(EXPR)
+=item HANDLE->input_line_number( EXPR )
=item $INPUT_LINE_NUMBER
Current line number for the last filehandle accessed.
Each filehandle in Perl counts the number of lines that have been read
-from it. (Depending on the value of C<$/>, Perl's idea of what
+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
Mnemonic: many programs use "." to mean the current line number.
-=item HANDLE->input_record_separator(EXPR)
+=item HANDLE->input_record_separator( EXPR )
=item $INPUT_RECORD_SEPARATOR
X<$/> X<$RS> X<$INPUT_RECORD_SEPARATOR>
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
+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
local $_ = <FH>; # whole file now here
s/\n[ \t]+/ /g;
-Remember: the value of C<$/> is a string, not a regex.
B<awk> has to
+Remember: the value of C<$/> is a string, not a regex. B<awk> has to
be better for something. :-)
Setting C<$/> to a reference to an integer, scalar containing an
open my $fh, "<", $myfile or die $!;
local $_ = <$fh>;
-will read a record of no more than 32768 bytes from FILE. If you're
+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
+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.
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
+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.
-See also L<perlport/"Newlines">. Also see C<$.>.
+See also L<perlport/"Newlines">. Also see C<$.>.
Mnemonic: / delimits line boundaries when quoting poetry.
-=item HANDLE->autoflush(EXPR)
-
-=item $OUTPUT_AUTOFLUSH
-
-=item Handle->output_record_separator EXPR
+=item Handle->output_record_separator( EXPR )
=item $OUTPUT_RECORD_SEPARATOR
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.
+=item HANDLE->autoflush( EXPR )
+
+=item $OUTPUT_AUTOFLUSH
+
=item $|
X<$|> X<autoflush> X<flush> X<$OUTPUT_AUTOFLUSH>
If set to nonzero, forces a flush right away and after every write or
-print on the currently selected output channel. Default is 0
+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
+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
+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>.
Mnemonic: when you want your pipes to be piping hot.
=head3 Variables related to formats
The special variables for formats are a subset of those for
-filehandles so they have
-
-See L<perlform> for more information about Perl's formats.
+filehandles. See L<perlform> for more information about Perl's
+formats.
=over 8
-=item HANDLE->format_formfeed(EXPR)
-
-=item $FORMAT_FORMFEED
-
=item $ACCUMULATOR
=item $^A
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
+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()>.
+=item HANDLE->format_formfeed(EXPR)
+
+=item $FORMAT_FORMFEED
+
=item $^L
X<$^L> X<$FORMAT_FORMFEED>
respectively.
To illustrate the differences between these variables, consider the
-following Perl expression, which uses a single-quoted string:
+following Perl expression, which uses a single-quoted string. After
+execution of this statement, perl may have set all four special error
+variables:
- eval q{
- open my $pipe, "/cdrom/install |" or die $!;
- my @res = <$pipe>;
- close $pipe or die "bad pipe: $?, $!";
- };
+ eval q{
+ open my $pipe, "/cdrom/install |" or die $!;
+ my @res = <$pipe>;
+ close $pipe or die "bad pipe: $?, $!";
+ };
-After execution of this statement all 4 variables may have been set.
+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.
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
+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.)
-When the C<eval()> expression above is executed, C<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.
-
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<$!>.
=over 8
-=item $EXTENDED_OS_ERROR
-
=item ${^CHILD_ERROR_NATIVE}
X<$^CHILD_ERROR_NATIVE>
This variable was added in Perl 5.8.9.
+=item $EXTENDED_OS_ERROR
+
=item $^E
X<$^E> X<$EXTENDED_OS_ERROR>
Current state of the interpreter.
- $^S State
- --------- -------------------
- undef Parsing module/eval
- true (1) Executing an eval
- false (0) Otherwise
+ $^S State
+ --------- -------------------
+ undef Parsing module/eval
+ true (1) Executing an eval
+ false (0) Otherwise
The first state may happen in C<$SIG{__DIE__}> and C<$SIG{__WARN__}>
handlers.
Mnemonic: related to the B<-w> switch.
=item ${^WARNING_BITS}
+X<${^WARNING_BITS}>
The current set of warning checks enabled by the C<use warnings> pragma.
See the documentation of C<warnings> for more details.
sets this variable. This means that the value of C<$!> is meaningful
only I<immediately> after a B<failure>:
- if (open my $fh, "<", $filename) {
- # Here $! is meaningless.
- ...
- } else {
- # ONLY here is $! meaningful.
- ...
- # Already here $! might be meaningless.
+ 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.
-In the above I<meaningless> stands for anything: zero, non-zero,
+The I<meaningless> stands for anything: zero, non-zero,
C<undef>. A successful system or library call does B<not> set the
variable to zero.
=item %ERRNO
=item %!
-X<%!>
+X<%!> X<%OS_ERROR> X<%ERRNO>
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
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<$!>.
+for more information, and also see L</$!>.
This variable was added in Perl 5.005.
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.
+described in L</%SIG>.
Mnemonic: Where was the syntax error "at"?
=over 8
+=item $OFMT
+
=item $#
-X<$#>
+X<$#> X<$OFMT>
C<$#> was a variable that you could be use to format printed numbers.
After a deprecation cycle, its magic was removed in Perl 5.10 and
Removed in Perl 5.10.
+=item $ARRAY_BASE
+
=item $[
-X<$[>
+X<$[> X<$ARRAY_BASE>
This variable stores the index of the first element in an array, and
-of the first character in a substring. You use to be able to assign to
+of the first character in a substring. You used to be able to assign to
this variable, but you can't do that anymore. It's now always 0, like
it should be.
Deprecated in Perl 5.12.
+=item $OLD_PERL_VERSION
+
=item $]
-X<$]>
+X<$]> X<$OLD_PERL_VERSION>
+
+See C<$^V> for a more modern representation of the Perl version that allows
+accurate string comparisons.
The version + patchlevel / 1000 of the Perl interpreter. This variable
can be used to determine whether the Perl interpreter executing a
warn "No checksumming!\n" if $] < 3.019;
+The floating point representation can sometimes lead to inaccurate
+numeric comparisons.
+
See also the documentation of C<use VERSION> and C<require VERSION>
for a convenient way to fail if the running Perl interpreter is too old.
-The 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.
-
Mnemonic: Is this version of perl in the right bracket?
Deprecated in Perl 5.6.
https://perl5.git.perl.org / perl5.git / blobdiff