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 $!;
+ 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 $!;
+ open my $fh, "<", "foo" or die $!;
undef $/; # enable slurp mode
my $content = <$fh>;
close $fh;
example:
my $content = '';
- open my $fh, "foo" or die $!;
+ open my $fh, "<", "foo" or die $!;
{
local $/;
$content = <$fh>;
=item $ARG
=item $_
+X<$_> X<$ARG>
The default input and pattern-searching space. The following pairs are
equivalent:
=item *
-Various unary functions, including functions like ord() and int(), as well
-as the all file tests (C<-f>, C<-d>) except for C<-t>, which defaults to
-STDIN.
+The following functions:
+
+abs, alarm, chomp, chop, chr, chroot, cos, defined, eval, exp, glob,
+hex, int, lc, lcfirst, length, log, lstat, mkdir, oct, ord, pos, print,
+quotemeta, readlink, readpipe, ref, require, reverse (in scalar context only),
+rmdir, sin, split (on its second argument), sqrt, stat, study, uc, ucfirst,
+unlink, unpack.
=item *
-Various list functions like print() and unlink().
+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///> when used
-without an C<=~> operator.
+The pattern matching operations C<m//>, C<s///> and C<tr///> (aka C<y///>)
+when used without an C<=~> operator.
=item *
=item *
+The implicit variable of given().
+
+=item *
+
The default place to put an input record when a C<< <FH> >>
operation's result is tested by itself as the sole criterion of a C<while>
test. Outside a C<while> test, this will not happen.
=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<$_> 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.
+
(Mnemonic: underline is understood in certain operations.)
=back
=item $a
=item $b
+X<$a> X<$b>
Special package variables when using sort(), see L<perlfunc/sort>.
Because of this specialness $a and $b don't need to be declared
-(using local(), use vars, or our()) even when using the strict
-vars pragma. Don't lexicalize them with C<my $a> or C<my $b>
-if you want to be able to use them in the sort() comparison block
-or function.
+(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.
=back
=over 8
=item $<I<digits>>
+X<$1> X<$2> X<$3>
Contains the subpattern from the corresponding set of capturing
parentheses from the last pattern match, not counting patterns
=item $MATCH
=item $&
+X<$&> X<$MATCH>
The string matched by the last successful pattern match (not counting
any matches hidden within a BLOCK or eval() enclosed by the current
The use of this variable anywhere in a program imposes a considerable
performance penalty on all regular expression matches. See L</BUGS>.
+See L</@-> for a replacement.
+
+=item ${^MATCH}
+X<${^MATCH}>
+
+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 $PREMATCH
=item $`
+X<$`> X<$PREMATCH>
The string preceding whatever was matched by the last successful
pattern match (not counting any matches hidden within a BLOCK or eval
The use of this variable anywhere in a program imposes a considerable
performance penalty on all regular expression matches. See L</BUGS>.
+See L</@-> for a replacement.
+
+=item ${^PREMATCH}
+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
+to return a defined value when the pattern was compiled or executed with
+the C</p> modifier.
+
=item $POSTMATCH
=item $'
+X<$'> X<$POSTMATCH>
The string following whatever was matched by the last successful
pattern match (not counting any matches hidden within a BLOCK or eval()
The use of this variable anywhere in a program imposes a considerable
performance penalty on all regular expression matches. See L</BUGS>.
+See L</@-> for a replacement.
+
+=item ${^POSTMATCH}
+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
+to return a defined value when the pattern was compiled or executed with
+the C</p> modifier.
+
=item $LAST_PAREN_MATCH
=item $+
+X<$+> X<$LAST_PAREN_MATCH>
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
(Mnemonic: be positive and forward looking.)
This variable is read-only and dynamically scoped to the current BLOCK.
+=item $LAST_SUBMATCH_RESULT
+
=item $^N
+X<$^N>
The text matched by the used group most-recently closed (i.e. the group
with the rightmost closing parenthesis) of the last successful search
=item @LAST_MATCH_END
=item @+
+X<@+> X<@LAST_MATCH_END>
This array holds the offsets of the ends of the last successful
submatches in the currently active dynamic scope. C<$+[0]> is
how many subgroups were in the last successful match. See the
examples given for the C<@-> variable.
-=item $MULTILINE_MATCHING
+=item %+
+X<%+>
-=item $*
+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.
-Set to a non-zero integer value to do multi-line matching within a
-string, 0 (or undefined) to tell Perl that it can assume that strings
-contain a single line, for the purpose of optimizing pattern matches.
-Pattern matches on strings containing multiple newlines can produce
-confusing results when C<$*> is 0 or undefined. Default is undefined.
-(Mnemonic: * matches multiple things.) This variable influences the
-interpretation of only C<^> and C<$>. A literal newline can be searched
-for even when C<$* == 0>.
+For example, C<$+{foo}> is equivalent to C<$1> after the following match:
-Use of C<$*> is deprecated in modern Perl, supplanted by
-the C</s> and C</m> modifiers on pattern matching.
+ 'foo' =~ /(?<foo>foo)/;
-Assigning a non-numerical value to C<$*> triggers a warning (and makes
-C<$*> act if C<$* == 0>), while assigning a numerical value to C<$*>
-makes that an implicit C<int> is applied on the value.
+The keys of the C<%+> hash list only the names of buffers that have
+captured (and that are thus associated to defined values).
+
+The underlying behaviour of C<%+> is provided by 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.
=item HANDLE->input_line_number(EXPR)
=item $NR
=item $.
+X<$.> X<$NR> X<$INPUT_LINE_NUMBER> X<line number>
-Current line number for the last filehandle accessed.
+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
=item $RS
=item $/
+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
integer. So this:
local $/ = \32768; # or \"32768", or \$var_containing_32768
- open my $fh, $myfile or die $!;
+ open my $fh, "<", $myfile or die $!;
local $_ = <$fh>;
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.
+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
=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
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. (Mnemonic: when you want your pipes to be piping hot.)
+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 $OFS
=item $,
+X<$,> X<$OFS> X<$OUTPUT_FIELD_SEPARATOR>
-The output field separator for the print operator. Ordinarily the
-print operator simply prints out its arguments without further
-adornment. To get behavior more like B<awk>, set this variable as
-you would set B<awk>'s OFS variable to specify what is printed
-between fields. (Mnemonic: what is printed when there is a "," in
-your print statement.)
+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.)
=item IO::Handle->output_record_separator EXPR
=item $ORS
=item $\
+X<$\> X<$ORS> X<$OUTPUT_RECORD_SEPARATOR>
-The output record separator for the print operator. Ordinarily the
-print operator simply prints out its arguments as is, with no
-trailing newline or other end-of-record string added. To get
-behavior more like B<awk>, set this variable as you would set
-B<awk>'s ORS variable to specify what is printed at the end of the
-print. (Mnemonic: you set C<$\> instead of adding "\n" at the
-end of the print. Also, it's just like C<$/>, but it's what you
-get "back" from Perl.)
+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.)
=item $LIST_SEPARATOR
=item $"
+X<$"> X<$LIST_SEPARATOR>
This is like C<$,> except that it applies to array and slice values
interpolated into a double-quoted string (or similar interpreted
=item $SUBSEP
=item $;
+X<$;> X<$SUBSEP> X<SUBSCRIPT_SEPARATOR>
The subscript separator for multidimensional array emulation. If you
refer to a hash element as
Consider using "real" multidimensional arrays as described
in L<perllol>.
-=item $OFMT
-
-=item $#
-
-The output format for printed numbers. This variable is a half-hearted
-attempt to emulate B<awk>'s OFMT variable. There are times, however,
-when B<awk> and Perl have differing notions of what counts as
-numeric. The initial value is "%.I<n>g", where I<n> is the value
-of the macro DBL_DIG from your system's F<float.h>. This is different from
-B<awk>'s default OFMT setting of "%.6g", so you need to set C<$#>
-explicitly to get B<awk>'s value. (Mnemonic: # is the number sign.)
-
-Use of C<$#> is deprecated.
-
=item HANDLE->format_page_number(EXPR)
=item $FORMAT_PAGE_NUMBER
=item $%
+X<$%> X<$FORMAT_PAGE_NUMBER>
The current page number of the currently selected output channel.
Used with formats.
=item $FORMAT_LINES_PER_PAGE
=item $=
+X<$=> X<$FORMAT_LINES_PER_PAGE>
The current page length (printable lines) of the currently selected
output channel. Default is 60.
=item $FORMAT_LINES_LEFT
=item $-
+X<$-> X<$FORMAT_LINES_LEFT>
The number of lines left on the page of the currently selected output
channel.
=item @LAST_MATCH_START
=item @-
+X<@-> X<@LAST_MATCH_START>
$-[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],
-$+[0] - $-[0]>. Similarly, C<$>I<n> coincides with C<substr $_, $-[>I<n>C<],
-$+[>I<n>C<] - $-[>I<n>C<]> if C<$-[>I<n>C<]> is defined, and $+ coincides with
-C<substr $_, $-[$#-], $+[$#-]>. One can use C<$#-> to find the last
+$+[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<$#+>, the number of subgroups in the regular expression. Compare
with C<@+>.
=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])>
+=item C<$3> is the same as C<substr($var, $-[3], $+[3] - $-[3])>
=back
+=item %-
+X<%->
+
+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.
+
+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.
+
=item HANDLE->format_name(EXPR)
=item $FORMAT_NAME
=item $~
+X<$~> X<$FORMAT_NAME>
The name of the current report format for the currently selected output
channel. Default is the name of the filehandle. (Mnemonic: brother to
=item $FORMAT_TOP_NAME
=item $^
+X<$^> X<$FORMAT_TOP_NAME>
The name of the current top-of-page format for the currently selected
output channel. Default is the name of the filehandle with _TOP
=item $FORMAT_LINE_BREAK_CHARACTERS
=item $:
+X<$:> X<FORMAT_LINE_BREAK_CHARACTERS>
The current set of characters after which a string may be broken to
fill continuation fields (starting with ^) in a format. Default is
=item $FORMAT_FORMFEED
=item $^L
+X<$^L> X<$FORMAT_FORMFEED>
What formats output as a form feed. Default is \f.
=item $ACCUMULATOR
=item $^A
+X<$^A> X<$ACCUMULATOR>
The current value of the write() accumulator for format() lines. A format
contains formline() calls that put their result into C<$^A>. After
=item $CHILD_ERROR
=item $?
+X<$?> X<$CHILD_ERROR>
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
-wait() system call (or else is made up to look like it). Thus, 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:
Also see L<Error Indicators>.
+=item ${^CHILD_ERROR_NATIVE}
+X<$^CHILD_ERROR_NATIVE>
+
+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.
+
+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.
+
=item ${^ENCODING}
+X<$^ENCODING>
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. See L<encoding>
-for more details.
+manipulation of this variable is highly discouraged.
=item $OS_ERROR
=item $ERRNO
=item $!
+X<$!> X<$ERRNO> X<$OS_ERROR>
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>:
- if (open(FH, $filename)) {
+ if (open my $fh, "<", $filename) {
# Here $! is meaningless.
...
} else {
C<undef>. A successful system or library call does B<not> set
the variable to zero.
-If used an a string, yields the corresponding system error string.
+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
Also see L<Error Indicators>.
+=item %OS_ERROR
+
+=item %ERRNO
+
=item %!
+X<%!>
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
=item $EXTENDED_OS_ERROR
=item $^E
+X<$^E> X<$EXTENDED_OS_ERROR>
Error information specific to the current operating system. At
the moment, this differs from C<$!> under only VMS, OS/2, and Win32
=item $EVAL_ERROR
=item $@
+X<$@> X<$EVAL_ERROR>
The Perl syntax error message from the last eval() operator.
If $@ is the null string, the last eval() parsed and executed
=item $PID
=item $$
+X<$$> X<$PID> X<$PROCESS_ID>
The process number of the Perl running this script. You should
consider this variable read-only, although it will be altered
=item $UID
=item $<
+X<< $< >> X<$UID> X<$REAL_USER_ID>
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().
+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 $EFFECTIVE_USER_ID
=item $EUID
=item $>
+X<< $> >> X<$EUID> X<$EFFECTIVE_USER_ID>
The effective uid of this process. Example:
($<,$>) = ($>,$<); # swap real and effective uid
You can change both the effective uid and the real uid at the same
-time by using POSIX::setuid().
+time by using POSIX::setuid(). Changes to $> require a check to $!
+to detect any possible errors after an attempted change.
(Mnemonic: it's the uid you went I<to>, if you're running setuid.)
C<< $< >> and C<< $> >> can be swapped only on machines
=item $GID
=item $(
+X<$(> X<$GID> X<$REAL_GROUP_ID>
The real gid of this process. If you are on a machine that supports
membership in multiple groups simultaneously, gives a space separated
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.
+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.
You can change both the real gid and the effective gid at the same
-time by using POSIX::setgid().
+time by using POSIX::setgid(). Changes to $( require a check to $!
+to detect any possible errors after an attempted change.
(Mnemonic: parentheses are used to I<group> things. The real gid is the
group you I<left>, if you're running setgid.)
=item $EGID
=item $)
+X<$)> X<$EGID> X<$EFFECTIVE_GROUP_ID>
The effective gid of this process. If you are on a machine that
supports membership in multiple groups simultaneously, gives a space
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.
(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 $PROGRAM_NAME
=item $0
+X<$0> X<$PROGRAM_NAME>
+
+Contains the name of the program being executed.
+
+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>.)
-Contains the name of the program being executed. On some operating
-systems assigning to C<$0> modifies the argument area that the B<ps>
-program sees. This is more useful as a way of indicating the current
-program state than it is for hiding the program you're running.
-(Mnemonic: same as B<sh> and B<ksh>.)
+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>.
+
+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).
Note for BSD users: setting C<$0> does not completely remove "perl"
-from the ps(1) output. For example, setting C<$0> to C<"foobar"> will
-result in C<"perl: foobar (perl)">. This is an operating system
-feature.
+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.
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).
+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.
=item $[
+X<$[>
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
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.
+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.
+
=item $]
+X<$]>
The version + patchlevel / 1000 of the Perl interpreter. This variable
can be used to determine whether the Perl interpreter executing a
=item $COMPILING
=item $^C
+X<$^C> X<$COMPILING>
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. See L<perlcc>. Setting
+time rather than normal, deferred loading. Setting
C<$^C = 1> is similar to calling C<B::minus_c>.
=item $DEBUGGING
=item $^D
+X<$^D> X<$DEBUGGING>
The current value of the debugging flags. (Mnemonic: value of B<-D>
-switch.)
+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 ${^RE_DEBUG_FLAGS}
+
+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.
+
+=item ${^RE_TRIE_MAXBUF}
+
+Controls how certain regex optimisations are applied and how much memory they
+utilize. This value by default is 65536 which corresponds to a 512kB temporary
+cache. Set this to a higher value to trade memory for speed when matching
+large alternations. Set it to a lower value if you want the optimisations to
+be as conservative of memory as possible but still occur, and set it to a
+negative value to prevent the optimisation and conserve the most memory.
+Under normal situations this variable should be of no interest to you.
=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 exec()ed processes, while higher file
=item %^H
-WARNING: This variable is strictly for internal use only. Its availability,
-behavior, and contents are subject to change without notice.
-
The %^H hash provides the same scoping semantic as $^H. This makes it
-useful for implementation of lexically scoped pragmas.
+useful for implementation of lexically scoped pragmas. See L<perlpragma>.
=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 die()ing. Suppose that your Perl
-were compiled with -DPERL_EMERGENCY_SBRK and used Perl's malloc.
+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
-enable this option. To discourage casual use of this advanced
-feature, there is no L<English|English> long name for this variable.
+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 $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. The value
=item $PERLDB
=item $^P
+X<$^P> X<$PERLDB>
The internal variable for debugging support. The meanings of the
various bits are subject to change, but currently indicate:
Provide informative names to anonymous subroutines based on the place they
were compiled.
+=item 0x400
+
+Debug assertion subroutines enter/exit.
+
=back
Some bits may be relevant at compile-time only, some at
=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.
=item $EXCEPTIONS_BEING_CAUGHT
=item $^S
+X<$^S> X<$EXCEPTIONS_BEING_CAUGHT>
+
+Current state of the interpreter.
-Current state of the interpreter. Undefined if parsing of the current
-module/eval is not finished (may happen in $SIG{__DIE__} and
-$SIG{__WARN__} handlers). True if inside an eval(), otherwise false.
+ $^S State
+ --------- -------------------
+ undef Parsing module/eval
+ true (1) Executing an eval
+ false (0) Otherwise
+
+The first state may happen in $SIG{__DIE__} and $SIG{__WARN__} handlers.
=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>,
=item ${^TAINT}
-Reflects if taint mode is on or off (i.e. if the program was run with
-B<-T> or not). True for on, false for off.
+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.
+
+=item ${^UNICODE}
+
+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.
+
+=item ${^UTF8CACHE}
+
+This variable controls the state of the internal UTF-8 offset caching code.
+1 for on (the default), 0 for off, -1 to debug the caching code by checking
+all its results against linear scans, and panicking on any discrepancy.
+
+=item ${^UTF8LOCALE}
+
+This variable indicates whether an 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.
=item $PERL_VERSION
=item $^V
+X<$^V> X<$PERL_VERSION>
The revision, version, and subversion of the Perl interpreter, represented
-as a string composed of characters with those ordinals. Thus in Perl v5.6.0
-it equals C<chr(5) . chr(6) . chr(0)> and will return true for
-C<$^V eq v5.6.0>. Note that the characters in this string value can
-potentially be in Unicode range.
+as a C<version> object.
+
+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.
-This can be used to determine whether the Perl interpreter executing a
+$^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:
- warn "No \"our\" declarations!\n" if $^V and $^V lt v5.6.0;
+ warn "Hashes not randomized!\n" if !$^V or $^V lt v5.8.1
To convert C<$^V> into its string representation use sprintf()'s
C<"%vd"> conversion:
=item $WARNING
=item $^W
+X<$^W> X<$WARNING>
The current value of the warning switch, initially true if B<-w>
was used, false otherwise, but directly modifiable. (Mnemonic:
The current set of warning checks enabled by the C<use warnings> pragma.
See the documentation of C<warnings> for more details.
-=item ${^WIDE_SYSTEM_CALLS}
+=item ${^WIN32_SLOPPY_STAT}
-Global flag that enables system calls made by Perl to use wide character
-APIs native to the system, if available. This is currently only implemented
-on the Windows platform.
+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.
-This can also be enabled from the command line using the C<-C> switch.
-
-The initial value is typically C<0> for compatibility with Perl versions
-earlier than 5.6, but may be automatically set to C<1> by Perl if the system
-provides a user-settable default (e.g., C<$ENV{LC_CTYPE}>).
-
-The C<bytes> pragma always overrides the effect of this flag in the current
-lexical scope. See L<bytes>.
+This variable could be set in the F<sitecustomize.pl> file to
+configure the local Perl installation to use "sloppy" stat() by
+default. See L<perlrun> for more information about site
+customization.
=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]>.
+C<argv[0]> or (where supported) F</proc/self/exe>.
Depending on the host operating system, the value of $^X may be
a relative or absolute pathname of the perl program file, or may
a command. To convert the value of $^X to a path name, use the
following statements:
-# Build up a set of file names (not command names).
+ # Build up a set of file names (not command names).
use Config;
$this_perl = $^X;
if ($^O ne 'VMS')
unless $secure_perl_path =~ m/$Config{_exe}$/i;}
=item ARGV
+X<ARGV>
The special filehandle that iterates over command-line filenames in
C<@ARGV>. Usually written as the null filehandle in the angle operator
files in C<@ARGV>.
=item $ARGV
+X<$ARGV>
contains the name of the current file when reading from <>.
=item @ARGV
+X<@ARGV>
The array @ARGV contains the command-line arguments intended for
the script. C<$#ARGV> is generally the number of arguments minus
command name itself. See C<$0> for the command name.
=item ARGVOUT
+X<ARGVOUT>
The special filehandle that points to the currently open output file
when doing edit-in-place processing with B<-i>. Useful when you have
L<perlrun> for the B<-i> switch.
=item @F
+X<@F>
The array @F contains the fields of each line read in when autosplit
mode is turned on. See L<perlrun> for the B<-a> switch. This array
if not in package main when running under C<strict 'vars'>.
=item @INC
+X<@INC>
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
code directly into @INC. Those hooks may be subroutine references, array
references or blessed objects. See L<perlfunc/require> for details.
+=item @ARG
+
=item @_
+X<@_> X<@ARG>
Within a subroutine the array @_ contains the parameters passed to that
subroutine. See L<perlsub>.
=item %INC
+X<%INC>
The hash %INC contains entries for each filename included via the
C<do>, C<require>, or C<use> operators. The key is the filename
=item %ENV
=item $ENV{expr}
+X<%ENV>
The hash %ENV contains your current environment. Setting a
value in C<ENV> changes the environment for any child processes
=item %SIG
=item $SIG{expr}
+X<%SIG>
-The hash %SIG contains signal handlers for signals. For example:
+The hash C<%SIG> contains signal handlers for signals. For example:
sub handler { # 1st argument is signal name
my($sig) = @_;
lest you inadvertently call it.
If your system has the sigaction() function then signal handlers are
-installed using it. This means you get reliable signal handling. If
-your system has the SA_RESTART flag it is used when signals handlers are
-installed. This means that system calls for which restarting is supported
-continue rather than returning when a signal arrives. If you want your
-system calls to be interrupted by signal delivery then do something like
-this:
+installed using it. This means you get reliable signal handling.
- use POSIX ':signal_h';
-
- my $alarm = 0;
- sigaction SIGALRM, new POSIX::SigAction sub { $alarm = 1 }
- or die "Error setting SIGALRM handler: $!\n";
-
-See L<POSIX>.
+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.
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 __WARN__ hook causes the ordinary printing
-of warnings to STDERR to be suppressed. You can use this to save warnings
+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 __DIE__ hook routine returns, the exception
+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 die().
+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__>.
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 CORE::GLOBAL::die().
+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.
=back
=head2 Error Indicators
+X<error> X<exception>
The variables C<$@>, C<$!>, C<$^E>, and C<$?> contain information
about different types of error conditions that may appear during
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>,
+(which will interpolate C<$!> and C<$?>). (See also L<Fatal>,
though.)
When the eval() expression above is executed, open(), C<< <PIPE> >>,
ENV STDIN
INC STDOUT
ARGV STDERR
- ARGVOUT
+ ARGVOUT _
SIG
In particular, the new special C<${^_XYZ}> variables are always taken
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.
+for more information. Writing C<use English '-no_match_vars';>
+avoids the performance penalty.
Having to even think about the C<$^S> variable in your exception
handlers is simply wrong. C<$SIG{__DIE__}> as currently implemented
https://perl5.git.perl.org / perl5.git / blobdiff