1=head1 NAME 2 3perlvar - Perl predefined variables 4 5=head1 DESCRIPTION 6 7=head2 The Syntax of Variable Names 8 9Variable names in Perl can have several formats. Usually, they 10must begin with a letter or underscore, in which case they can be 11arbitrarily long (up to an internal limit of 251 characters) and 12may contain letters, digits, underscores, or the special sequence 13C<::> or C<'>. In this case, the part before the last C<::> or 14C<'> is taken to be a I<package qualifier>; see L<perlmod>. 15A Unicode letter that is not ASCII is not considered to be a letter 16unless S<C<"use utf8">> is in effect, and somewhat more complicated 17rules apply; see L<perldata/Identifier parsing> for details. 18 19Perl variable names may also be a sequence of digits, a single 20punctuation character, or the two-character sequence: C<^> (caret or 21CIRCUMFLEX ACCENT) followed by any one of the characters C<[][A-Z^_?\]>. 22These names are all reserved for 23special uses by Perl; for example, the all-digits names are used 24to hold data captured by backreferences after a regular expression 25match. 26 27Since Perl v5.6.0, Perl variable names may also be alphanumeric strings 28preceded by a caret. These must all be written in the form C<${^Foo}>; 29the braces are not optional. C<${^Foo}> denotes the scalar variable 30whose name is considered to be a control-C<F> followed by two C<o>'s. 31These variables are 32reserved for future special uses by Perl, except for the ones that 33begin with C<^_> (caret-underscore). No 34name that begins with C<^_> will acquire a special 35meaning in any future version of Perl; such names may therefore be 36used safely in programs. C<$^_> itself, however, I<is> reserved. 37 38Perl identifiers that begin with digits or 39punctuation characters are exempt from the effects of the C<package> 40declaration and are always forced to be in package C<main>; they are 41also exempt from C<strict 'vars'> errors. A few other names are also 42exempt in these ways: 43 44 ENV STDIN 45 INC STDOUT 46 ARGV STDERR 47 ARGVOUT 48 SIG 49 50In particular, the special C<${^_XYZ}> variables are always taken 51to be in package C<main>, regardless of any C<package> declarations 52presently in scope. 53 54=head1 SPECIAL VARIABLES 55 56The following names have special meaning to Perl. Most punctuation 57names have reasonable mnemonics, or analogs in the shells. 58Nevertheless, if you wish to use long variable names, you need only say: 59 60 use English; 61 62at the top of your program. This aliases all the short names to the long 63names in the current package. Some even have medium names, generally 64borrowed from B<awk>. For more info, please see L<English>. 65 66Before you continue, note the sort order for variables. In general, we 67first list the variables in case-insensitive, almost-lexigraphical 68order (ignoring the C<{> or C<^> preceding words, as in C<${^UNICODE}> 69or C<$^T>), although C<$_> and C<@_> move up to the top of the pile. 70For variables with the same identifier, we list it in order of scalar, 71array, hash, and bareword. 72 73=head2 General Variables 74 75=over 8 76 77=item $ARG 78 79=item $_ 80X<$_> X<$ARG> 81 82The default input and pattern-searching space. The following pairs are 83equivalent: 84 85 while (<>) {...} # equivalent only in while! 86 while (defined($_ = <>)) {...} 87 88 /^Subject:/ 89 $_ =~ /^Subject:/ 90 91 tr/a-z/A-Z/ 92 $_ =~ tr/a-z/A-Z/ 93 94 chomp 95 chomp($_) 96 97Here are the places where Perl will assume C<$_> even if you don't use it: 98 99=over 3 100 101=item * 102 103The following functions use C<$_> as a default argument: 104 105abs, alarm, chomp, chop, chr, chroot, 106cos, defined, eval, evalbytes, exp, fc, glob, hex, int, lc, 107lcfirst, length, log, lstat, mkdir, oct, ord, pos, print, printf, 108quotemeta, readlink, readpipe, ref, require, reverse (in scalar context only), 109rmdir, say, sin, split (for its second 110argument), sqrt, stat, study, uc, ucfirst, 111unlink, unpack. 112 113=item * 114 115All file tests (C<-f>, C<-d>) except for C<-t>, which defaults to STDIN. 116See L<perlfunc/-X> 117 118=item * 119 120The pattern matching operations C<m//>, C<s///> and C<tr///> (aka C<y///>) 121when used without an C<=~> operator. 122 123=item * 124 125The default iterator variable in a C<foreach> loop if no other 126variable is supplied. 127 128=item * 129 130The implicit iterator variable in the C<grep()> and C<map()> functions. 131 132=item * 133 134The implicit variable of C<given()>. 135 136=item * 137 138The default place to put the next value or input record 139when a C<< <FH> >>, C<readline>, C<readdir> or C<each> 140operation's result is tested by itself as the sole criterion of a C<while> 141test. Outside a C<while> test, this will not happen. 142 143=back 144 145C<$_> is a global variable. 146 147However, between perl v5.10.0 and v5.24.0, it could be used lexically by 148writing C<my $_>. Making C<$_> refer to the global C<$_> in the same scope 149was then possible with C<our $_>. This experimental feature was removed and is 150now a fatal error, but you may encounter it in older code. 151 152Mnemonic: underline is understood in certain operations. 153 154=item @ARG 155 156=item @_ 157X<@_> X<@ARG> 158 159Within a subroutine the array C<@_> contains the parameters passed to 160that subroutine. Inside a subroutine, C<@_> is the default array for 161the array operators C<pop> and C<shift>. 162 163See L<perlsub>. 164 165=item $LIST_SEPARATOR 166 167=item $" 168X<$"> X<$LIST_SEPARATOR> 169 170When an array or an array slice is interpolated into a double-quoted 171string or a similar context such as C</.../>, its elements are 172separated by this value. Default is a space. For example, this: 173 174 print "The array is: @array\n"; 175 176is equivalent to this: 177 178 print "The array is: " . join($", @array) . "\n"; 179 180Mnemonic: works in double-quoted context. 181 182=item $PROCESS_ID 183 184=item $PID 185 186=item $$ 187X<$$> X<$PID> X<$PROCESS_ID> 188 189The process number of the Perl running this script. Though you I<can> set 190this variable, doing so is generally discouraged, although it can be 191invaluable for some testing purposes. It will be reset automatically 192across C<fork()> calls. 193 194Note for Linux and Debian GNU/kFreeBSD users: Before Perl v5.16.0 perl 195would emulate POSIX semantics on Linux systems using LinuxThreads, a 196partial implementation of POSIX Threads that has since been superseded 197by the Native POSIX Thread Library (NPTL). 198 199LinuxThreads is now obsolete on Linux, and caching C<getpid()> 200like this made embedding perl unnecessarily complex (since you'd have 201to manually update the value of $$), so now C<$$> and C<getppid()> 202will always return the same values as the underlying C library. 203 204Debian GNU/kFreeBSD systems also used LinuxThreads up until and 205including the 6.0 release, but after that moved to FreeBSD thread 206semantics, which are POSIX-like. 207 208To see if your system is affected by this discrepancy check if 209C<getconf GNU_LIBPTHREAD_VERSION | grep -q NPTL> returns a false 210value. NTPL threads preserve the POSIX semantics. 211 212Mnemonic: same as shells. 213 214=item $PROGRAM_NAME 215 216=item $0 217X<$0> X<$PROGRAM_NAME> 218 219Contains the name of the program being executed. 220 221On some (but not all) operating systems assigning to C<$0> modifies 222the argument area that the C<ps> program sees. On some platforms you 223may have to use special C<ps> options or a different C<ps> to see the 224changes. Modifying the C<$0> is more useful as a way of indicating the 225current program state than it is for hiding the program you're 226running. 227 228Note that there are platform-specific limitations on the maximum 229length of C<$0>. In the most extreme case it may be limited to the 230space occupied by the original C<$0>. 231 232In some platforms there may be arbitrary amount of padding, for 233example space characters, after the modified name as shown by C<ps>. 234In some platforms this padding may extend all the way to the original 235length of the argument area, no matter what you do (this is the case 236for example with Linux 2.2). 237 238Note for BSD users: setting C<$0> does not completely remove "perl" 239from the ps(1) output. For example, setting C<$0> to C<"foobar"> may 240result in C<"perl: foobar (perl)"> (whether both the C<"perl: "> prefix 241and the " (perl)" suffix are shown depends on your exact BSD variant 242and version). This is an operating system feature, Perl cannot help it. 243 244In multithreaded scripts Perl coordinates the threads so that any 245thread may modify its copy of the C<$0> and the change becomes visible 246to ps(1) (assuming the operating system plays along). Note that 247the view of C<$0> the other threads have will not change since they 248have their own copies of it. 249 250If the program has been given to perl via the switches C<-e> or C<-E>, 251C<$0> will contain the string C<"-e">. 252 253On Linux as of perl v5.14.0 the legacy process name will be set with 254C<prctl(2)>, in addition to altering the POSIX name via C<argv[0]> as 255perl has done since version 4.000. Now system utilities that read the 256legacy process name such as ps, top and killall will recognize the 257name you set when assigning to C<$0>. The string you supply will be 258cut off at 16 bytes, this is a limitation imposed by Linux. 259 260Mnemonic: same as B<sh> and B<ksh>. 261 262=item $REAL_GROUP_ID 263 264=item $GID 265 266=item $( 267X<$(> X<$GID> X<$REAL_GROUP_ID> 268 269The real gid of this process. If you are on a machine that supports 270membership in multiple groups simultaneously, gives a space separated 271list of groups you are in. The first number is the one returned by 272C<getgid()>, and the subsequent ones by C<getgroups()>, one of which may be 273the same as the first number. 274 275However, a value assigned to C<$(> must be a single number used to 276set the real gid. So the value given by C<$(> should I<not> be assigned 277back to C<$(> without being forced numeric, such as by adding zero. Note 278that this is different to the effective gid (C<$)>) which does take a 279list. 280 281You can change both the real gid and the effective gid at the same 282time by using C<POSIX::setgid()>. Changes 283to C<$(> require a check to C<$!> 284to detect any possible errors after an attempted change. 285 286Mnemonic: parentheses are used to I<group> things. The real gid is the 287group you I<left>, if you're running setgid. 288 289=item $EFFECTIVE_GROUP_ID 290 291=item $EGID 292 293=item $) 294X<$)> X<$EGID> X<$EFFECTIVE_GROUP_ID> 295 296The effective gid of this process. If you are on a machine that 297supports membership in multiple groups simultaneously, gives a space 298separated list of groups you are in. The first number is the one 299returned by C<getegid()>, and the subsequent ones by C<getgroups()>, 300one of which may be the same as the first number. 301 302Similarly, a value assigned to C<$)> must also be a space-separated 303list of numbers. The first number sets the effective gid, and 304the rest (if any) are passed to C<setgroups()>. To get the effect of an 305empty list for C<setgroups()>, just repeat the new effective gid; that is, 306to force an effective gid of 5 and an effectively empty C<setgroups()> 307list, say C< $) = "5 5" >. 308 309You can change both the effective gid and the real gid at the same 310time by using C<POSIX::setgid()> (use only a single numeric argument). 311Changes to C<$)> require a check to C<$!> to detect any possible errors 312after an attempted change. 313 314C<< $< >>, C<< $> >>, C<$(> and C<$)> can be set only on 315machines that support the corresponding I<set[re][ug]id()> routine. C<$(> 316and C<$)> can be swapped only on machines supporting C<setregid()>. 317 318Mnemonic: parentheses are used to I<group> things. The effective gid 319is the group that's I<right> for you, if you're running setgid. 320 321=item $REAL_USER_ID 322 323=item $UID 324 325=item $< 326X<< $< >> X<$UID> X<$REAL_USER_ID> 327 328The real uid of this process. You can change both the real uid and the 329effective uid at the same time by using C<POSIX::setuid()>. Since 330changes to C<< $< >> require a system call, check C<$!> after a change 331attempt to detect any possible errors. 332 333Mnemonic: it's the uid you came I<from>, if you're running setuid. 334 335=item $EFFECTIVE_USER_ID 336 337=item $EUID 338 339=item $> 340X<< $> >> X<$EUID> X<$EFFECTIVE_USER_ID> 341 342The effective uid of this process. For example: 343 344 $< = $>; # set real to effective uid 345 ($<,$>) = ($>,$<); # swap real and effective uids 346 347You can change both the effective uid and the real uid at the same 348time by using C<POSIX::setuid()>. Changes to C<< $> >> require a check 349to C<$!> to detect any possible errors after an attempted change. 350 351C<< $< >> and C<< $> >> can be swapped only on machines 352supporting C<setreuid()>. 353 354Mnemonic: it's the uid you went I<to>, if you're running setuid. 355 356=item $SUBSCRIPT_SEPARATOR 357 358=item $SUBSEP 359 360=item $; 361X<$;> X<$SUBSEP> X<SUBSCRIPT_SEPARATOR> 362 363The subscript separator for multidimensional array emulation. If you 364refer to a hash element as 365 366 $foo{$x,$y,$z} 367 368it really means 369 370 $foo{join($;, $x, $y, $z)} 371 372But don't put 373 374 @foo{$x,$y,$z} # a slice--note the @ 375 376which means 377 378 ($foo{$x},$foo{$y},$foo{$z}) 379 380Default is "\034", the same as SUBSEP in B<awk>. If your keys contain 381binary data there might not be any safe value for C<$;>. 382 383Consider using "real" multidimensional arrays as described 384in L<perllol>. 385 386Mnemonic: comma (the syntactic subscript separator) is a semi-semicolon. 387 388=item $a 389 390=item $b 391X<$a> X<$b> 392 393Special package variables when using C<sort()>, see L<perlfunc/sort>. 394Because of this specialness C<$a> and C<$b> don't need to be declared 395(using C<use vars>, or C<our()>) even when using the C<strict 'vars'> 396pragma. Don't lexicalize them with C<my $a> or C<my $b> if you want to 397be able to use them in the C<sort()> comparison block or function. 398 399=item %ENV 400X<%ENV> 401 402The hash C<%ENV> contains your current environment. Setting a 403value in C<ENV> changes the environment for any child processes 404you subsequently C<fork()> off. 405 406As of v5.18.0, both keys and values stored in C<%ENV> are stringified. 407 408 my $foo = 1; 409 $ENV{'bar'} = \$foo; 410 if( ref $ENV{'bar'} ) { 411 say "Pre 5.18.0 Behaviour"; 412 } else { 413 say "Post 5.18.0 Behaviour"; 414 } 415 416Previously, only child processes received stringified values: 417 418 my $foo = 1; 419 $ENV{'bar'} = \$foo; 420 421 # Always printed 'non ref' 422 system($^X, '-e', 423 q/print ( ref $ENV{'bar'} ? 'ref' : 'non ref' ) /); 424 425This happens because you can't really share arbitrary data structures with 426foreign processes. 427 428=item $OLD_PERL_VERSION 429 430=item $] 431X<$]> X<$OLD_PERL_VERSION> 432 433The revision, version, and subversion of the Perl interpreter, represented 434as a decimal of the form 5.XXXYYY, where XXX is the version / 1e3 and YYY 435is the subversion / 1e6. For example, Perl v5.10.1 would be "5.010001". 436 437This variable can be used to determine whether the Perl interpreter 438executing a script is in the right range of versions: 439 440 warn "No PerlIO!\n" if $] lt '5.008'; 441 442When comparing C<$]>, string comparison operators are B<highly 443recommended>. The inherent limitations of binary floating point 444representation can sometimes lead to incorrect comparisons for some 445numbers on some architectures. 446 447See also the documentation of C<use VERSION> and C<require VERSION> 448for a convenient way to fail if the running Perl interpreter is too old. 449 450See L</$^V> for a representation of the Perl version as a L<version> 451object, which allows more flexible string comparisons. 452 453The main advantage of C<$]> over C<$^V> is that it works the same on any 454version of Perl. The disadvantages are that it can't easily be compared 455to versions in other formats (e.g. literal v-strings, "v1.2.3" or 456version objects) and numeric comparisons can occasionally fail; it's good 457for string literal version checks and bad for comparing to a variable 458that hasn't been sanity-checked. 459 460The C<$OLD_PERL_VERSION> form was added in Perl v5.20.0 for historical 461reasons but its use is discouraged. (If your reason to use C<$]> is to 462run code on old perls then referring to it as C<$OLD_PERL_VERSION> would 463be self-defeating.) 464 465Mnemonic: Is this version of perl in the right bracket? 466 467=item $SYSTEM_FD_MAX 468 469=item $^F 470X<$^F> X<$SYSTEM_FD_MAX> 471 472The maximum system file descriptor, ordinarily 2. System file 473descriptors are passed to C<exec()>ed processes, while higher file 474descriptors are not. Also, during an 475C<open()>, system file descriptors are 476preserved even if the C<open()> fails (ordinary file descriptors are 477closed before the C<open()> is attempted). The close-on-exec 478status of a file descriptor will be decided according to the value of 479C<$^F> when the corresponding file, pipe, or socket was opened, not the 480time of the C<exec()>. 481 482=item @F 483X<@F> 484 485The array C<@F> contains the fields of each line read in when autosplit 486mode is turned on. See L<perlrun> for the B<-a> switch. This array 487is package-specific, and must be declared or given a full package name 488if not in package main when running under C<strict 'vars'>. 489 490=item @INC 491X<@INC> 492 493The array C<@INC> contains the list of places that the C<do EXPR>, 494C<require>, or C<use> constructs look for their library files. It 495initially consists of the arguments to any B<-I> command-line 496switches, followed by the default Perl library, probably 497F</usr/local/lib/perl>. 498Prior to Perl 5.26, C<.> -which represents the current directory, was included 499in C<@INC>; it has been removed. This change in behavior is documented 500in L<C<PERL_USE_UNSAFE_INC>|perlrun/PERL_USE_UNSAFE_INC> and it is 501not recommended that C<.> be re-added to C<@INC>. 502If you need to modify C<@INC> at runtime, you should use the C<use lib> pragma 503to get the machine-dependent library properly loaded as well: 504 505 use lib '/mypath/libdir/'; 506 use SomeMod; 507 508You can also insert hooks into the file inclusion system by putting Perl 509code directly into C<@INC>. Those hooks may be subroutine references, 510array references or blessed objects. See L<perlfunc/require> for details. 511 512=item %INC 513X<%INC> 514 515The hash C<%INC> contains entries for each filename included via the 516C<do>, C<require>, or C<use> operators. The key is the filename 517you specified (with module names converted to pathnames), and the 518value is the location of the file found. The C<require> 519operator uses this hash to determine whether a particular file has 520already been included. 521 522If the file was loaded via a hook (e.g. a subroutine reference, see 523L<perlfunc/require> for a description of these hooks), this hook is 524by default inserted into C<%INC> in place of a filename. Note, however, 525that the hook may have set the C<%INC> entry by itself to provide some more 526specific info. 527 528=item $INPLACE_EDIT 529 530=item $^I 531X<$^I> X<$INPLACE_EDIT> 532 533The current value of the inplace-edit extension. Use C<undef> to disable 534inplace editing. 535 536Mnemonic: value of B<-i> switch. 537 538=item @ISA 539X<@ISA> 540 541Each package contains a special array called C<@ISA> which contains a list 542of that class's parent classes, if any. This array is simply a list of 543scalars, each of which is a string that corresponds to a package name. The 544array is examined when Perl does method resolution, which is covered in 545L<perlobj>. 546 547To load packages while adding them to C<@ISA>, see the L<parent> pragma. The 548discouraged L<base> pragma does this as well, but should not be used except 549when compatibility with the discouraged L<fields> pragma is required. 550 551=item $^M 552X<$^M> 553 554By default, running out of memory is an untrappable, fatal error. 555However, if suitably built, Perl can use the contents of C<$^M> 556as an emergency memory pool after C<die()>ing. Suppose that your Perl 557were compiled with C<-DPERL_EMERGENCY_SBRK> and used Perl's malloc. 558Then 559 560 $^M = 'a' x (1 << 16); 561 562would allocate a 64K buffer for use in an emergency. See the 563F<INSTALL> file in the Perl distribution for information on how to 564add custom C compilation flags when compiling perl. To discourage casual 565use of this advanced feature, there is no L<English|English> long name for 566this variable. 567 568This variable was added in Perl 5.004. 569 570=item $OSNAME 571 572=item $^O 573X<$^O> X<$OSNAME> 574 575The name of the operating system under which this copy of Perl was 576built, as determined during the configuration process. For examples 577see L<perlport/PLATFORMS>. 578 579The value is identical to C<$Config{'osname'}>. See also L<Config> 580and the B<-V> command-line switch documented in L<perlrun>. 581 582In Windows platforms, C<$^O> is not very helpful: since it is always 583C<MSWin32>, it doesn't tell the difference between 58495/98/ME/NT/2000/XP/CE/.NET. Use C<Win32::GetOSName()> or 585Win32::GetOSVersion() (see L<Win32> and L<perlport>) to distinguish 586between the variants. 587 588This variable was added in Perl 5.003. 589 590=item %SIG 591X<%SIG> 592 593The hash C<%SIG> contains signal handlers for signals. For example: 594 595 sub handler { # 1st argument is signal name 596 my($sig) = @_; 597 print "Caught a SIG$sig--shutting down\n"; 598 close(LOG); 599 exit(0); 600 } 601 602 $SIG{'INT'} = \&handler; 603 $SIG{'QUIT'} = \&handler; 604 ... 605 $SIG{'INT'} = 'DEFAULT'; # restore default action 606 $SIG{'QUIT'} = 'IGNORE'; # ignore SIGQUIT 607 608Using a value of C<'IGNORE'> usually has the effect of ignoring the 609signal, except for the C<CHLD> signal. See L<perlipc> for more about 610this special case. 611 612Here are some other examples: 613 614 $SIG{"PIPE"} = "Plumber"; # assumes main::Plumber (not 615 # recommended) 616 $SIG{"PIPE"} = \&Plumber; # just fine; assume current 617 # Plumber 618 $SIG{"PIPE"} = *Plumber; # somewhat esoteric 619 $SIG{"PIPE"} = Plumber(); # oops, what did Plumber() 620 # return?? 621 622Be sure not to use a bareword as the name of a signal handler, 623lest you inadvertently call it. 624 625If your system has the C<sigaction()> function then signal handlers 626are installed using it. This means you get reliable signal handling. 627 628The default delivery policy of signals changed in Perl v5.8.0 from 629immediate (also known as "unsafe") to deferred, also known as "safe 630signals". See L<perlipc> for more information. 631 632Certain internal hooks can be also set using the C<%SIG> hash. The 633routine indicated by C<$SIG{__WARN__}> is called when a warning 634message is about to be printed. The warning message is passed as the 635first argument. The presence of a C<__WARN__> hook causes the 636ordinary printing of warnings to C<STDERR> to be suppressed. You can 637use this to save warnings in a variable, or turn warnings into fatal 638errors, like this: 639 640 local $SIG{__WARN__} = sub { die $_[0] }; 641 eval $proggie; 642 643As the C<'IGNORE'> hook is not supported by C<__WARN__>, you can 644disable warnings using the empty subroutine: 645 646 local $SIG{__WARN__} = sub {}; 647 648The routine indicated by C<$SIG{__DIE__}> is called when a fatal 649exception is about to be thrown. The error message is passed as the 650first argument. When a C<__DIE__> hook routine returns, the exception 651processing continues as it would have in the absence of the hook, 652unless the hook routine itself exits via a C<goto &sub>, a loop exit, 653or a C<die()>. The C<__DIE__> handler is explicitly disabled during 654the call, so that you can die from a C<__DIE__> handler. Similarly 655for C<__WARN__>. 656 657The C<$SIG{__DIE__}> hook is called even inside an C<eval()>. It was 658never intended to happen this way, but an implementation glitch made 659this possible. This used to be deprecated, as it allowed strange action 660at a distance like rewriting a pending exception in C<$@>. Plans to 661rectify this have been scrapped, as users found that rewriting a 662pending exception is actually a useful feature, and not a bug. 663 664C<__DIE__>/C<__WARN__> handlers are very special in one respect: they 665may be called to report (probable) errors found by the parser. In such 666a case the parser may be in inconsistent state, so any attempt to 667evaluate Perl code from such a handler will probably result in a 668segfault. This means that warnings or errors that result from parsing 669Perl should be used with extreme caution, like this: 670 671 require Carp if defined $^S; 672 Carp::confess("Something wrong") if defined &Carp::confess; 673 die "Something wrong, but could not load Carp to give " 674 . "backtrace...\n\t" 675 . "To see backtrace try starting Perl with -MCarp switch"; 676 677Here the first line will load C<Carp> I<unless> it is the parser who 678called the handler. The second line will print backtrace and die if 679C<Carp> was available. The third line will be executed only if C<Carp> was 680not available. 681 682Having to even think about the C<$^S> variable in your exception 683handlers is simply wrong. C<$SIG{__DIE__}> as currently implemented 684invites grievous and difficult to track down errors. Avoid it 685and use an C<END{}> or CORE::GLOBAL::die override instead. 686 687See L<perlfunc/die>, L<perlfunc/warn>, L<perlfunc/eval>, and 688L<warnings> for additional information. 689 690=item $BASETIME 691 692=item $^T 693X<$^T> X<$BASETIME> 694 695The time at which the program began running, in seconds since the 696epoch (beginning of 1970). The values returned by the B<-M>, B<-A>, 697and B<-C> filetests are based on this value. 698 699=item $PERL_VERSION 700 701=item $^V 702X<$^V> X<$PERL_VERSION> 703 704The revision, version, and subversion of the Perl interpreter, 705represented as a L<version> object. 706 707This variable first appeared in perl v5.6.0; earlier versions of perl 708will see an undefined value. Before perl v5.10.0 C<$^V> was represented 709as a v-string rather than a L<version> object. 710 711C<$^V> can be used to determine whether the Perl interpreter executing 712a script is in the right range of versions. For example: 713 714 warn "Hashes not randomized!\n" if !$^V or $^V lt v5.8.1 715 716While version objects overload stringification, to portably convert 717C<$^V> into its string representation, use C<sprintf()>'s C<"%vd"> 718conversion, which works for both v-strings or version objects: 719 720 printf "version is v%vd\n", $^V; # Perl's version 721 722See the documentation of C<use VERSION> and C<require VERSION> 723for a convenient way to fail if the running Perl interpreter is too old. 724 725See also C<L</$]>> for a decimal representation of the Perl version. 726 727The main advantage of C<$^V> over C<$]> is that, for Perl v5.10.0 or 728later, it overloads operators, allowing easy comparison against other 729version representations (e.g. decimal, literal v-string, "v1.2.3", or 730objects). The disadvantage is that prior to v5.10.0, it was only a 731literal v-string, which can't be easily printed or compared, whereas 732the behavior of C<$]> is unchanged on all versions of Perl. 733 734Mnemonic: use ^V for a version object. 735 736=item ${^WIN32_SLOPPY_STAT} 737X<${^WIN32_SLOPPY_STAT}> X<sitecustomize> X<sitecustomize.pl> 738 739If this variable is set to a true value, then C<stat()> on Windows will 740not try to open the file. This means that the link count cannot be 741determined and file attributes may be out of date if additional 742hardlinks to the file exist. On the other hand, not opening the file 743is considerably faster, especially for files on network drives. 744 745This variable could be set in the F<sitecustomize.pl> file to 746configure the local Perl installation to use "sloppy" C<stat()> by 747default. See the documentation for B<-f> in 748L<perlrun|perlrun/"Command Switches"> for more information about site 749customization. 750 751This variable was added in Perl v5.10.0. 752 753=item $EXECUTABLE_NAME 754 755=item $^X 756X<$^X> X<$EXECUTABLE_NAME> 757 758The name used to execute the current copy of Perl, from C's 759C<argv[0]> or (where supported) F</proc/self/exe>. 760 761Depending on the host operating system, the value of C<$^X> may be 762a relative or absolute pathname of the perl program file, or may 763be the string used to invoke perl but not the pathname of the 764perl program file. Also, most operating systems permit invoking 765programs that are not in the PATH environment variable, so there 766is no guarantee that the value of C<$^X> is in PATH. For VMS, the 767value may or may not include a version number. 768 769You usually can use the value of C<$^X> to re-invoke an independent 770copy of the same perl that is currently running, e.g., 771 772 @first_run = `$^X -le "print int rand 100 for 1..100"`; 773 774But recall that not all operating systems support forking or 775capturing of the output of commands, so this complex statement 776may not be portable. 777 778It is not safe to use the value of C<$^X> as a path name of a file, 779as some operating systems that have a mandatory suffix on 780executable files do not require use of the suffix when invoking 781a command. To convert the value of C<$^X> to a path name, use the 782following statements: 783 784 # Build up a set of file names (not command names). 785 use Config; 786 my $this_perl = $^X; 787 if ($^O ne 'VMS') { 788 $this_perl .= $Config{_exe} 789 unless $this_perl =~ m/$Config{_exe}$/i; 790 } 791 792Because many operating systems permit anyone with read access to 793the Perl program file to make a copy of it, patch the copy, and 794then execute the copy, the security-conscious Perl programmer 795should take care to invoke the installed copy of perl, not the 796copy referenced by C<$^X>. The following statements accomplish 797this goal, and produce a pathname that can be invoked as a 798command or referenced as a file. 799 800 use Config; 801 my $secure_perl_path = $Config{perlpath}; 802 if ($^O ne 'VMS') { 803 $secure_perl_path .= $Config{_exe} 804 unless $secure_perl_path =~ m/$Config{_exe}$/i; 805 } 806 807=back 808 809=head2 Variables related to regular expressions 810 811Most of the special variables related to regular expressions are side 812effects. Perl sets these variables when it has a successful match, so 813you should check the match result before using them. For instance: 814 815 if( /P(A)TT(ER)N/ ) { 816 print "I found $1 and $2\n"; 817 } 818 819These variables are read-only and dynamically-scoped, unless we note 820otherwise. 821 822The dynamic nature of the regular expression variables means that 823their value is limited to the block that they are in, as demonstrated 824by this bit of code: 825 826 my $outer = 'Wallace and Grommit'; 827 my $inner = 'Mutt and Jeff'; 828 829 my $pattern = qr/(\S+) and (\S+)/; 830 831 sub show_n { print "\$1 is $1; \$2 is $2\n" } 832 833 { 834 OUTER: 835 show_n() if $outer =~ m/$pattern/; 836 837 INNER: { 838 show_n() if $inner =~ m/$pattern/; 839 } 840 841 show_n(); 842 } 843 844The output shows that while in the C<OUTER> block, the values of C<$1> 845and C<$2> are from the match against C<$outer>. Inside the C<INNER> 846block, the values of C<$1> and C<$2> are from the match against 847C<$inner>, but only until the end of the block (i.e. the dynamic 848scope). After the C<INNER> block completes, the values of C<$1> and 849C<$2> return to the values for the match against C<$outer> even though 850we have not made another match: 851 852 $1 is Wallace; $2 is Grommit 853 $1 is Mutt; $2 is Jeff 854 $1 is Wallace; $2 is Grommit 855 856=head3 Performance issues 857 858Traditionally in Perl, any use of any of the three variables C<$`>, C<$&> 859or C<$'> (or their C<use English> equivalents) anywhere in the code, caused 860all subsequent successful pattern matches to make a copy of the matched 861string, in case the code might subsequently access one of those variables. 862This imposed a considerable performance penalty across the whole program, 863so generally the use of these variables has been discouraged. 864 865In Perl 5.6.0 the C<@-> and C<@+> dynamic arrays were introduced that 866supply the indices of successful matches. So you could for example do 867this: 868 869 $str =~ /pattern/; 870 871 print $`, $&, $'; # bad: performance hit 872 873 print # good: no performance hit 874 substr($str, 0, $-[0]), 875 substr($str, $-[0], $+[0]-$-[0]), 876 substr($str, $+[0]); 877 878In Perl 5.10.0 the C</p> match operator flag and the C<${^PREMATCH}>, 879C<${^MATCH}>, and C<${^POSTMATCH}> variables were introduced, that allowed 880you to suffer the penalties only on patterns marked with C</p>. 881 882In Perl 5.18.0 onwards, perl started noting the presence of each of the 883three variables separately, and only copied that part of the string 884required; so in 885 886 $`; $&; "abcdefgh" =~ /d/ 887 888perl would only copy the "abcd" part of the string. That could make a big 889difference in something like 890 891 $str = 'x' x 1_000_000; 892 $&; # whoops 893 $str =~ /x/g # one char copied a million times, not a million chars 894 895In Perl 5.20.0 a new copy-on-write system was enabled by default, which 896finally fixes all performance issues with these three variables, and makes 897them safe to use anywhere. 898 899The C<Devel::NYTProf> and C<Devel::FindAmpersand> modules can help you 900find uses of these problematic match variables in your code. 901 902=over 8 903 904=item $<I<digits>> ($1, $2, ...) 905X<$1> X<$2> X<$3> X<$I<digits>> 906 907Contains the subpattern from the corresponding set of capturing 908parentheses from the last successful pattern match, not counting patterns 909matched in nested blocks that have been exited already. 910 911Note there is a distinction between a capture buffer which matches 912the empty string a capture buffer which is optional. Eg, C<(x?)> and 913C<(x)?> The latter may be undef, the former not. 914 915These variables are read-only and dynamically-scoped. 916 917Mnemonic: like \digits. 918 919=item @{^CAPTURE} 920X<@{^CAPTURE}> X<@^CAPTURE> 921 922An array which exposes the contents of the capture buffers, if any, of 923the last successful pattern match, not counting patterns matched 924in nested blocks that have been exited already. 925 926Note that the 0 index of @{^CAPTURE} is equivalent to $1, the 1 index 927is equivalent to $2, etc. 928 929 if ("foal"=~/(.)(.)(.)(.)/) { 930 print join "-", @{^CAPTURE}; 931 } 932 933should output "f-o-a-l". 934 935See also L<<< /$<I<digits>> ($1, $2, ...) >>>, L</%{^CAPTURE}> and 936L</%{^CAPTURE_ALL}>. 937 938Note that unlike most other regex magic variables there is no single 939letter equivalent to C<@{^CAPTURE}>. 940 941This variable was added in 5.25.7 942 943=item $MATCH 944 945=item $& 946X<$&> X<$MATCH> 947 948The string matched by the last successful pattern match (not counting 949any matches hidden within a BLOCK or C<eval()> enclosed by the current 950BLOCK). 951 952See L</Performance issues> above for the serious performance implications 953of using this variable (even once) in your code. 954 955This variable is read-only and dynamically-scoped. 956 957Mnemonic: like C<&> in some editors. 958 959=item ${^MATCH} 960X<${^MATCH}> 961 962This is similar to C<$&> (C<$MATCH>) except that it does not incur the 963performance penalty associated with that variable. 964 965See L</Performance issues> above. 966 967In Perl v5.18 and earlier, it is only guaranteed 968to return a defined value when the pattern was compiled or executed with 969the C</p> modifier. In Perl v5.20, the C</p> modifier does nothing, so 970C<${^MATCH}> does the same thing as C<$MATCH>. 971 972This variable was added in Perl v5.10.0. 973 974This variable is read-only and dynamically-scoped. 975 976=item $PREMATCH 977 978=item $` 979X<$`> X<$PREMATCH> X<${^PREMATCH}> 980 981The string preceding whatever was matched by the last successful 982pattern match, not counting any matches hidden within a BLOCK or C<eval> 983enclosed by the current BLOCK. 984 985See L</Performance issues> above for the serious performance implications 986of using this variable (even once) in your code. 987 988This variable is read-only and dynamically-scoped. 989 990Mnemonic: C<`> often precedes a quoted string. 991 992=item ${^PREMATCH} 993X<$`> X<${^PREMATCH}> 994 995This is similar to C<$`> ($PREMATCH) except that it does not incur the 996performance penalty associated with that variable. 997 998See L</Performance issues> above. 999 1000In Perl v5.18 and earlier, it is only guaranteed 1001to return a defined value when the pattern was compiled or executed with 1002the C</p> modifier. In Perl v5.20, the C</p> modifier does nothing, so 1003C<${^PREMATCH}> does the same thing as C<$PREMATCH>. 1004 1005This variable was added in Perl v5.10.0. 1006 1007This variable is read-only and dynamically-scoped. 1008 1009=item $POSTMATCH 1010 1011=item $' 1012X<$'> X<$POSTMATCH> X<${^POSTMATCH}> X<@-> 1013 1014The string following whatever was matched by the last successful 1015pattern match (not counting any matches hidden within a BLOCK or C<eval()> 1016enclosed by the current BLOCK). Example: 1017 1018 local $_ = 'abcdefghi'; 1019 /def/; 1020 print "$`:$&:$'\n"; # prints abc:def:ghi 1021 1022See L</Performance issues> above for the serious performance implications 1023of using this variable (even once) in your code. 1024 1025This variable is read-only and dynamically-scoped. 1026 1027Mnemonic: C<'> often follows a quoted string. 1028 1029=item ${^POSTMATCH} 1030X<${^POSTMATCH}> X<$'> X<$POSTMATCH> 1031 1032This is similar to C<$'> (C<$POSTMATCH>) except that it does not incur the 1033performance penalty associated with that variable. 1034 1035See L</Performance issues> above. 1036 1037In Perl v5.18 and earlier, it is only guaranteed 1038to return a defined value when the pattern was compiled or executed with 1039the C</p> modifier. In Perl v5.20, the C</p> modifier does nothing, so 1040C<${^POSTMATCH}> does the same thing as C<$POSTMATCH>. 1041 1042This variable was added in Perl v5.10.0. 1043 1044This variable is read-only and dynamically-scoped. 1045 1046=item $LAST_PAREN_MATCH 1047 1048=item $+ 1049X<$+> X<$LAST_PAREN_MATCH> 1050 1051The text matched by the highest used capture group of the last 1052successful search pattern. It is logically equivalent to the highest 1053numbered capture variable (C<$1>, C<$2>, ...) which has a defined value. 1054 1055This is useful if you don't know which one of a set of alternative patterns 1056matched. For example: 1057 1058 /Version: (.*)|Revision: (.*)/ && ($rev = $+); 1059 1060This variable is read-only and dynamically-scoped. 1061 1062Mnemonic: be positive and forward looking. 1063 1064=item $LAST_SUBMATCH_RESULT 1065 1066=item $^N 1067X<$^N> X<$LAST_SUBMATCH_RESULT> 1068 1069The text matched by the used group most-recently closed (i.e. the group 1070with the rightmost closing parenthesis) of the last successful search 1071pattern. This is subtly different from C<$+>. For example in 1072 1073 "ab" =~ /^((.)(.))$/ 1074 1075we have 1076 1077 $1,$^N have the value "ab" 1078 $2 has the value "a" 1079 $3,$+ have the value "b" 1080 1081This is primarily used inside C<(?{...})> blocks for examining text 1082recently matched. For example, to effectively capture text to a variable 1083(in addition to C<$1>, C<$2>, etc.), replace C<(...)> with 1084 1085 (?:(...)(?{ $var = $^N })) 1086 1087By setting and then using C<$var> in this way relieves you from having to 1088worry about exactly which numbered set of parentheses they are. 1089 1090This variable was added in Perl v5.8.0. 1091 1092Mnemonic: the (possibly) Nested parenthesis that most recently closed. 1093 1094=item @LAST_MATCH_END 1095 1096=item @+ 1097X<@+> X<@LAST_MATCH_END> 1098 1099This array holds the offsets of the ends of the last successful 1100submatches in the currently active dynamic scope. C<$+[0]> is 1101the offset into the string of the end of the entire match. This 1102is the same value as what the C<pos> function returns when called 1103on the variable that was matched against. The I<n>th element 1104of this array holds the offset of the I<n>th submatch, so 1105C<$+[1]> is the offset past where C<$1> ends, C<$+[2]> the offset 1106past where C<$2> ends, and so on. You can use C<$#+> to determine 1107how many subgroups were in the last successful match. See the 1108examples given for the C<@-> variable. 1109 1110This variable was added in Perl v5.6.0. 1111 1112=item %{^CAPTURE} 1113 1114=item %LAST_PAREN_MATCH 1115 1116=item %+ 1117X<%+> X<%LAST_PAREN_MATCH> X<%{^CAPTURE}> 1118 1119Similar to C<@+>, the C<%+> hash allows access to the named capture 1120buffers, should they exist, in the last successful match in the 1121currently active dynamic scope. 1122 1123For example, C<$+{foo}> is equivalent to C<$1> after the following match: 1124 1125 'foo' =~ /(?<foo>foo)/; 1126 1127The keys of the C<%+> hash list only the names of buffers that have 1128captured (and that are thus associated to defined values). 1129 1130If multiple distinct capture groups have the same name, then 1131C<$+{NAME}> will refer to the leftmost defined group in the match. 1132 1133The underlying behaviour of C<%+> is provided by the 1134L<Tie::Hash::NamedCapture> module. 1135 1136B<Note:> C<%-> and C<%+> are tied views into a common internal hash 1137associated with the last successful regular expression. Therefore mixing 1138iterative access to them via C<each> may have unpredictable results. 1139Likewise, if the last successful match changes, then the results may be 1140surprising. 1141 1142This variable was added in Perl v5.10.0. The C<%{^CAPTURE}> alias was 1143added in 5.25.7. 1144 1145This variable is read-only and dynamically-scoped. 1146 1147=item @LAST_MATCH_START 1148 1149=item @- 1150X<@-> X<@LAST_MATCH_START> 1151 1152C<$-[0]> is the offset of the start of the last successful match. 1153C<$-[I<n>]> is the offset of the start of the substring matched by 1154I<n>-th subpattern, or undef if the subpattern did not match. 1155 1156Thus, after a match against C<$_>, C<$&> coincides with C<substr $_, $-[0], 1157$+[0] - $-[0]>. Similarly, $I<n> coincides with C<substr $_, $-[n], 1158$+[n] - $-[n]> if C<$-[n]> is defined, and $+ coincides with 1159C<substr $_, $-[$#-], $+[$#-] - $-[$#-]>. One can use C<$#-> to find the 1160last matched subgroup in the last successful match. Contrast with 1161C<$#+>, the number of subgroups in the regular expression. Compare 1162with C<@+>. 1163 1164This array holds the offsets of the beginnings of the last 1165successful submatches in the currently active dynamic scope. 1166C<$-[0]> is the offset into the string of the beginning of the 1167entire match. The I<n>th element of this array holds the offset 1168of the I<n>th submatch, so C<$-[1]> is the offset where C<$1> 1169begins, C<$-[2]> the offset where C<$2> begins, and so on. 1170 1171After a match against some variable C<$var>: 1172 1173=over 5 1174 1175=item C<$`> is the same as C<substr($var, 0, $-[0])> 1176 1177=item C<$&> is the same as C<substr($var, $-[0], $+[0] - $-[0])> 1178 1179=item C<$'> is the same as C<substr($var, $+[0])> 1180 1181=item C<$1> is the same as C<substr($var, $-[1], $+[1] - $-[1])> 1182 1183=item C<$2> is the same as C<substr($var, $-[2], $+[2] - $-[2])> 1184 1185=item C<$3> is the same as C<substr($var, $-[3], $+[3] - $-[3])> 1186 1187=back 1188 1189This variable was added in Perl v5.6.0. 1190 1191=item %{^CAPTURE_ALL} 1192X<%{^CAPTURE_ALL}> 1193 1194=item %- 1195X<%-> 1196 1197Similar to C<%+>, this variable allows access to the named capture groups 1198in the last successful match in the currently active dynamic scope. To 1199each capture group name found in the regular expression, it associates a 1200reference to an array containing the list of values captured by all 1201buffers with that name (should there be several of them), in the order 1202where they appear. 1203 1204Here's an example: 1205 1206 if ('1234' =~ /(?<A>1)(?<B>2)(?<A>3)(?<B>4)/) { 1207 foreach my $bufname (sort keys %-) { 1208 my $ary = $-{$bufname}; 1209 foreach my $idx (0..$#$ary) { 1210 print "\$-{$bufname}[$idx] : ", 1211 (defined($ary->[$idx]) 1212 ? "'$ary->[$idx]'" 1213 : "undef"), 1214 "\n"; 1215 } 1216 } 1217 } 1218 1219would print out: 1220 1221 $-{A}[0] : '1' 1222 $-{A}[1] : '3' 1223 $-{B}[0] : '2' 1224 $-{B}[1] : '4' 1225 1226The keys of the C<%-> hash correspond to all buffer names found in 1227the regular expression. 1228 1229The behaviour of C<%-> is implemented via the 1230L<Tie::Hash::NamedCapture> module. 1231 1232B<Note:> C<%-> and C<%+> are tied views into a common internal hash 1233associated with the last successful regular expression. Therefore mixing 1234iterative access to them via C<each> may have unpredictable results. 1235Likewise, if the last successful match changes, then the results may be 1236surprising. 1237 1238This variable was added in Perl v5.10.0. The C<%{^CAPTURE_ALL}> alias was 1239added in 5.25.7. 1240 1241This variable is read-only and dynamically-scoped. 1242 1243=item $LAST_REGEXP_CODE_RESULT 1244 1245=item $^R 1246X<$^R> X<$LAST_REGEXP_CODE_RESULT> 1247 1248The result of evaluation of the last successful C<(?{ code })> 1249regular expression assertion (see L<perlre>). May be written to. 1250 1251This variable was added in Perl 5.005. 1252 1253=item ${^RE_COMPILE_RECURSION_LIMIT} 1254X<${^RE_COMPILE_RECURSION_LIMIT}> 1255 1256The current value giving the maximum number of open but unclosed 1257parenthetical groups there may be at any point during a regular 1258expression compilation. The default is currently 1000 nested groups. 1259You may adjust it depending on your needs and the amount of memory 1260available. 1261 1262This variable was added in Perl v5.30.0. 1263 1264=item ${^RE_DEBUG_FLAGS} 1265X<${^RE_DEBUG_FLAGS}> 1266 1267The current value of the regex debugging flags. Set to 0 for no debug output 1268even when the C<re 'debug'> module is loaded. See L<re> for details. 1269 1270This variable was added in Perl v5.10.0. 1271 1272=item ${^RE_TRIE_MAXBUF} 1273X<${^RE_TRIE_MAXBUF}> 1274 1275Controls how certain regex optimisations are applied and how much memory they 1276utilize. This value by default is 65536 which corresponds to a 512kB 1277temporary cache. Set this to a higher value to trade 1278memory for speed when matching large alternations. Set 1279it to a lower value if you want the optimisations to 1280be as conservative of memory as possible but still occur, and set it to a 1281negative value to prevent the optimisation and conserve the most memory. 1282Under normal situations this variable should be of no interest to you. 1283 1284This variable was added in Perl v5.10.0. 1285 1286=back 1287 1288=head2 Variables related to filehandles 1289 1290Variables that depend on the currently selected filehandle may be set 1291by calling an appropriate object method on the C<IO::Handle> object, 1292although this is less efficient than using the regular built-in 1293variables. (Summary lines below for this contain the word HANDLE.) 1294First you must say 1295 1296 use IO::Handle; 1297 1298after which you may use either 1299 1300 method HANDLE EXPR 1301 1302or more safely, 1303 1304 HANDLE->method(EXPR) 1305 1306Each method returns the old value of the C<IO::Handle> attribute. The 1307methods each take an optional EXPR, which, if supplied, specifies the 1308new value for the C<IO::Handle> attribute in question. If not 1309supplied, most methods do nothing to the current value--except for 1310C<autoflush()>, which will assume a 1 for you, just to be different. 1311 1312Because loading in the C<IO::Handle> class is an expensive operation, 1313you should learn how to use the regular built-in variables. 1314 1315A few of these variables are considered "read-only". This means that 1316if you try to assign to this variable, either directly or indirectly 1317through a reference, you'll raise a run-time exception. 1318 1319You should be very careful when modifying the default values of most 1320special variables described in this document. In most cases you want 1321to localize these variables before changing them, since if you don't, 1322the change may affect other modules which rely on the default values 1323of the special variables that you have changed. This is one of the 1324correct ways to read the whole file at once: 1325 1326 open my $fh, "<", "foo" or die $!; 1327 local $/; # enable localized slurp mode 1328 my $content = <$fh>; 1329 close $fh; 1330 1331But the following code is quite bad: 1332 1333 open my $fh, "<", "foo" or die $!; 1334 undef $/; # enable slurp mode 1335 my $content = <$fh>; 1336 close $fh; 1337 1338since some other module, may want to read data from some file in the 1339default "line mode", so if the code we have just presented has been 1340executed, the global value of C<$/> is now changed for any other code 1341running inside the same Perl interpreter. 1342 1343Usually when a variable is localized you want to make sure that this 1344change affects the shortest scope possible. So unless you are already 1345inside some short C<{}> block, you should create one yourself. For 1346example: 1347 1348 my $content = ''; 1349 open my $fh, "<", "foo" or die $!; 1350 { 1351 local $/; 1352 $content = <$fh>; 1353 } 1354 close $fh; 1355 1356Here is an example of how your own code can go broken: 1357 1358 for ( 1..3 ){ 1359 $\ = "\r\n"; 1360 nasty_break(); 1361 print "$_"; 1362 } 1363 1364 sub nasty_break { 1365 $\ = "\f"; 1366 # do something with $_ 1367 } 1368 1369You probably expect this code to print the equivalent of 1370 1371 "1\r\n2\r\n3\r\n" 1372 1373but instead you get: 1374 1375 "1\f2\f3\f" 1376 1377Why? Because C<nasty_break()> modifies C<$\> without localizing it 1378first. The value you set in C<nasty_break()> is still there when you 1379return. The fix is to add C<local()> so the value doesn't leak out of 1380C<nasty_break()>: 1381 1382 local $\ = "\f"; 1383 1384It's easy to notice the problem in such a short example, but in more 1385complicated code you are looking for trouble if you don't localize 1386changes to the special variables. 1387 1388=over 8 1389 1390=item $ARGV 1391X<$ARGV> 1392 1393Contains the name of the current file when reading from C<< <> >>. 1394 1395=item @ARGV 1396X<@ARGV> 1397 1398The array C<@ARGV> contains the command-line arguments intended for 1399the script. C<$#ARGV> is generally the number of arguments minus 1400one, because C<$ARGV[0]> is the first argument, I<not> the program's 1401command name itself. See L</$0> for the command name. 1402 1403=item ARGV 1404X<ARGV> 1405 1406The special filehandle that iterates over command-line filenames in 1407C<@ARGV>. Usually written as the null filehandle in the angle operator 1408C<< <> >>. Note that currently C<ARGV> only has its magical effect 1409within the C<< <> >> operator; elsewhere it is just a plain filehandle 1410corresponding to the last file opened by C<< <> >>. In particular, 1411passing C<\*ARGV> as a parameter to a function that expects a filehandle 1412may not cause your function to automatically read the contents of all the 1413files in C<@ARGV>. 1414 1415=item ARGVOUT 1416X<ARGVOUT> 1417 1418The special filehandle that points to the currently open output file 1419when doing edit-in-place processing with B<-i>. Useful when you have 1420to do a lot of inserting and don't want to keep modifying C<$_>. See 1421L<perlrun> for the B<-i> switch. 1422 1423=item IO::Handle->output_field_separator( EXPR ) 1424 1425=item $OUTPUT_FIELD_SEPARATOR 1426 1427=item $OFS 1428 1429=item $, 1430X<$,> X<$OFS> X<$OUTPUT_FIELD_SEPARATOR> 1431 1432The output field separator for the print operator. If defined, this 1433value is printed between each of print's arguments. Default is C<undef>. 1434 1435You cannot call C<output_field_separator()> on a handle, only as a 1436static method. See L<IO::Handle|IO::Handle>. 1437 1438Mnemonic: what is printed when there is a "," in your print statement. 1439 1440=item HANDLE->input_line_number( EXPR ) 1441 1442=item $INPUT_LINE_NUMBER 1443 1444=item $NR 1445 1446=item $. 1447X<$.> X<$NR> X<$INPUT_LINE_NUMBER> X<line number> 1448 1449Current line number for the last filehandle accessed. 1450 1451Each filehandle in Perl counts the number of lines that have been read 1452from it. (Depending on the value of C<$/>, Perl's idea of what 1453constitutes a line may not match yours.) When a line is read from a 1454filehandle (via C<readline()> or C<< <> >>), or when C<tell()> or 1455C<seek()> is called on it, C<$.> becomes an alias to the line counter 1456for that filehandle. 1457 1458You can adjust the counter by assigning to C<$.>, but this will not 1459actually move the seek pointer. I<Localizing C<$.> will not localize 1460the filehandle's line count>. Instead, it will localize perl's notion 1461of which filehandle C<$.> is currently aliased to. 1462 1463C<$.> is reset when the filehandle is closed, but B<not> when an open 1464filehandle is reopened without an intervening C<close()>. For more 1465details, see L<perlop/"IE<sol>O Operators">. Because C<< <> >> never does 1466an explicit close, line numbers increase across C<ARGV> files (but see 1467examples in L<perlfunc/eof>). 1468 1469You can also use C<< HANDLE->input_line_number(EXPR) >> to access the 1470line counter for a given filehandle without having to worry about 1471which handle you last accessed. 1472 1473Mnemonic: many programs use "." to mean the current line number. 1474 1475=item IO::Handle->input_record_separator( EXPR ) 1476 1477=item $INPUT_RECORD_SEPARATOR 1478 1479=item $RS 1480 1481=item $/ 1482X<$/> X<$RS> X<$INPUT_RECORD_SEPARATOR> 1483 1484The input record separator, newline by default. This influences Perl's 1485idea of what a "line" is. Works like B<awk>'s RS variable, including 1486treating empty lines as a terminator if set to the null string (an 1487empty line cannot contain any spaces or tabs). You may set it to a 1488multi-character string to match a multi-character terminator, or to 1489C<undef> to read through the end of file. Setting it to C<"\n\n"> 1490means something slightly different than setting to C<"">, if the file 1491contains consecutive empty lines. Setting to C<""> will treat two or 1492more consecutive empty lines as a single empty line. Setting to 1493C<"\n\n"> will blindly assume that the next input character belongs to 1494the next paragraph, even if it's a newline. 1495 1496 local $/; # enable "slurp" mode 1497 local $_ = <FH>; # whole file now here 1498 s/\n[ \t]+/ /g; 1499 1500Remember: the value of C<$/> is a string, not a regex. B<awk> has to 1501be better for something. :-) 1502 1503Setting C<$/> to an empty string -- the so-called I<paragraph mode> -- merits 1504special attention. When C<$/> is set to C<""> and the entire file is read in 1505with that setting, any sequence of consecutive newlines C<"\n\n"> at the 1506beginning of the file is discarded. With the exception of the final record in 1507the file, each sequence of characters ending in two or more newlines is 1508treated as one record and is read in to end in exactly two newlines. If the 1509last record in the file ends in zero or one consecutive newlines, that record 1510is read in with that number of newlines. If the last record ends in two or 1511more consecutive newlines, it is read in with two newlines like all preceding 1512records. 1513 1514Suppose we wrote the following string to a file: 1515 1516 my $string = "\n\n\n"; 1517 $string .= "alpha beta\ngamma delta\n\n\n"; 1518 $string .= "epsilon zeta eta\n\n"; 1519 $string .= "theta\n"; 1520 1521 my $file = 'simple_file.txt'; 1522 open my $OUT, '>', $file or die; 1523 print $OUT $string; 1524 close $OUT or die; 1525 1526Now we read that file in paragraph mode: 1527 1528 local $/ = ""; # paragraph mode 1529 open my $IN, '<', $file or die; 1530 my @records = <$IN>; 1531 close $IN or die; 1532 1533C<@records> will consist of these 3 strings: 1534 1535 ( 1536 "alpha beta\ngamma delta\n\n", 1537 "epsilon zeta eta\n\n", 1538 "theta\n", 1539 ) 1540 1541Setting C<$/> to a reference to an integer, scalar containing an 1542integer, or scalar that's convertible to an integer will attempt to 1543read records instead of lines, with the maximum record size being the 1544referenced integer number of characters. So this: 1545 1546 local $/ = \32768; # or \"32768", or \$var_containing_32768 1547 open my $fh, "<", $myfile or die $!; 1548 local $_ = <$fh>; 1549 1550will read a record of no more than 32768 characters from $fh. If you're 1551not reading from a record-oriented file (or your OS doesn't have 1552record-oriented files), then you'll likely get a full chunk of data 1553with every read. If a record is larger than the record size you've 1554set, you'll get the record back in pieces. Trying to set the record 1555size to zero or less is deprecated and will cause $/ to have the value 1556of "undef", which will cause reading in the (rest of the) whole file. 1557 1558As of 5.19.9 setting C<$/> to any other form of reference will throw a 1559fatal exception. This is in preparation for supporting new ways to set 1560C<$/> in the future. 1561 1562On VMS only, record reads bypass PerlIO layers and any associated 1563buffering, so you must not mix record and non-record reads on the 1564same filehandle. Record mode mixes with line mode only when the 1565same buffering layer is in use for both modes. 1566 1567You cannot call C<input_record_separator()> on a handle, only as a 1568static method. See L<IO::Handle|IO::Handle>. 1569 1570See also L<perlport/"Newlines">. Also see L</$.>. 1571 1572Mnemonic: / delimits line boundaries when quoting poetry. 1573 1574=item IO::Handle->output_record_separator( EXPR ) 1575 1576=item $OUTPUT_RECORD_SEPARATOR 1577 1578=item $ORS 1579 1580=item $\ 1581X<$\> X<$ORS> X<$OUTPUT_RECORD_SEPARATOR> 1582 1583The output record separator for the print operator. If defined, this 1584value is printed after the last of print's arguments. Default is C<undef>. 1585 1586You cannot call C<output_record_separator()> on a handle, only as a 1587static method. See L<IO::Handle|IO::Handle>. 1588 1589Mnemonic: you set C<$\> instead of adding "\n" at the end of the print. 1590Also, it's just like C<$/>, but it's what you get "back" from Perl. 1591 1592=item HANDLE->autoflush( EXPR ) 1593 1594=item $OUTPUT_AUTOFLUSH 1595 1596=item $| 1597X<$|> X<autoflush> X<flush> X<$OUTPUT_AUTOFLUSH> 1598 1599If set to nonzero, forces a flush right away and after every write or 1600print on the currently selected output channel. Default is 0 1601(regardless of whether the channel is really buffered by the system or 1602not; C<$|> tells you only whether you've asked Perl explicitly to 1603flush after each write). STDOUT will typically be line buffered if 1604output is to the terminal and block buffered otherwise. Setting this 1605variable is useful primarily when you are outputting to a pipe or 1606socket, such as when you are running a Perl program under B<rsh> and 1607want to see the output as it's happening. This has no effect on input 1608buffering. See L<perlfunc/getc> for that. See L<perlfunc/select> on 1609how to select the output channel. See also L<IO::Handle>. 1610 1611Mnemonic: when you want your pipes to be piping hot. 1612 1613=item ${^LAST_FH} 1614X<${^LAST_FH}> 1615 1616This read-only variable contains a reference to the last-read filehandle. 1617This is set by C<< <HANDLE> >>, C<readline>, C<tell>, C<eof> and C<seek>. 1618This is the same handle that C<$.> and C<tell> and C<eof> without arguments 1619use. It is also the handle used when Perl appends ", <STDIN> line 1" to 1620an error or warning message. 1621 1622This variable was added in Perl v5.18.0. 1623 1624=back 1625 1626=head3 Variables related to formats 1627 1628The special variables for formats are a subset of those for 1629filehandles. See L<perlform> for more information about Perl's 1630formats. 1631 1632=over 8 1633 1634=item $ACCUMULATOR 1635 1636=item $^A 1637X<$^A> X<$ACCUMULATOR> 1638 1639The current value of the C<write()> accumulator for C<format()> lines. 1640A format contains C<formline()> calls that put their result into 1641C<$^A>. After calling its format, C<write()> prints out the contents 1642of C<$^A> and empties. So you never really see the contents of C<$^A> 1643unless you call C<formline()> yourself and then look at it. See 1644L<perlform> and L<perlfunc/"formline PICTURE,LIST">. 1645 1646=item IO::Handle->format_formfeed(EXPR) 1647 1648=item $FORMAT_FORMFEED 1649 1650=item $^L 1651X<$^L> X<$FORMAT_FORMFEED> 1652 1653What formats output as a form feed. The default is C<\f>. 1654 1655You cannot call C<format_formfeed()> on a handle, only as a static 1656method. See L<IO::Handle|IO::Handle>. 1657 1658=item HANDLE->format_page_number(EXPR) 1659 1660=item $FORMAT_PAGE_NUMBER 1661 1662=item $% 1663X<$%> X<$FORMAT_PAGE_NUMBER> 1664 1665The current page number of the currently selected output channel. 1666 1667Mnemonic: C<%> is page number in B<nroff>. 1668 1669=item HANDLE->format_lines_left(EXPR) 1670 1671=item $FORMAT_LINES_LEFT 1672 1673=item $- 1674X<$-> X<$FORMAT_LINES_LEFT> 1675 1676The number of lines left on the page of the currently selected output 1677channel. 1678 1679Mnemonic: lines_on_page - lines_printed. 1680 1681=item IO::Handle->format_line_break_characters EXPR 1682 1683=item $FORMAT_LINE_BREAK_CHARACTERS 1684 1685=item $: 1686X<$:> X<FORMAT_LINE_BREAK_CHARACTERS> 1687 1688The current set of characters after which a string may be broken to 1689fill continuation fields (starting with C<^>) in a format. The default is 1690S<" \n-">, to break on a space, newline, or a hyphen. 1691 1692You cannot call C<format_line_break_characters()> on a handle, only as 1693a static method. See L<IO::Handle|IO::Handle>. 1694 1695Mnemonic: a "colon" in poetry is a part of a line. 1696 1697=item HANDLE->format_lines_per_page(EXPR) 1698 1699=item $FORMAT_LINES_PER_PAGE 1700 1701=item $= 1702X<$=> X<$FORMAT_LINES_PER_PAGE> 1703 1704The current page length (printable lines) of the currently selected 1705output channel. The default is 60. 1706 1707Mnemonic: = has horizontal lines. 1708 1709=item HANDLE->format_top_name(EXPR) 1710 1711=item $FORMAT_TOP_NAME 1712 1713=item $^ 1714X<$^> X<$FORMAT_TOP_NAME> 1715 1716The name of the current top-of-page format for the currently selected 1717output channel. The default is the name of the filehandle with C<_TOP> 1718appended. For example, the default format top name for the C<STDOUT> 1719filehandle is C<STDOUT_TOP>. 1720 1721Mnemonic: points to top of page. 1722 1723=item HANDLE->format_name(EXPR) 1724 1725=item $FORMAT_NAME 1726 1727=item $~ 1728X<$~> X<$FORMAT_NAME> 1729 1730The name of the current report format for the currently selected 1731output channel. The default format name is the same as the filehandle 1732name. For example, the default format name for the C<STDOUT> 1733filehandle is just C<STDOUT>. 1734 1735Mnemonic: brother to C<$^>. 1736 1737=back 1738 1739=head2 Error Variables 1740X<error> X<exception> 1741 1742The variables C<$@>, C<$!>, C<$^E>, and C<$?> contain information 1743about different types of error conditions that may appear during 1744execution of a Perl program. The variables are shown ordered by 1745the "distance" between the subsystem which reported the error and 1746the Perl process. They correspond to errors detected by the Perl 1747interpreter, C library, operating system, or an external program, 1748respectively. 1749 1750To illustrate the differences between these variables, consider the 1751following Perl expression, which uses a single-quoted string. After 1752execution of this statement, perl may have set all four special error 1753variables: 1754 1755 eval q{ 1756 open my $pipe, "/cdrom/install |" or die $!; 1757 my @res = <$pipe>; 1758 close $pipe or die "bad pipe: $?, $!"; 1759 }; 1760 1761When perl executes the C<eval()> expression, it translates the 1762C<open()>, C<< <PIPE> >>, and C<close> calls in the C run-time library 1763and thence to the operating system kernel. perl sets C<$!> to 1764the C library's C<errno> if one of these calls fails. 1765 1766C<$@> is set if the string to be C<eval>-ed did not compile (this may 1767happen if C<open> or C<close> were imported with bad prototypes), or 1768if Perl code executed during evaluation C<die()>d. In these cases the 1769value of C<$@> is the compile error, or the argument to C<die> (which 1770will interpolate C<$!> and C<$?>). (See also L<Fatal>, though.) 1771 1772Under a few operating systems, C<$^E> may contain a more verbose error 1773indicator, such as in this case, "CDROM tray not closed." Systems that 1774do not support extended error messages leave C<$^E> the same as C<$!>. 1775 1776Finally, C<$?> may be set to a non-0 value if the external program 1777F</cdrom/install> fails. The upper eight bits reflect specific error 1778conditions encountered by the program (the program's C<exit()> value). 1779The lower eight bits reflect mode of failure, like signal death and 1780core dump information. See L<wait(2)> for details. In contrast to 1781C<$!> and C<$^E>, which are set only if an error condition is detected, 1782the variable C<$?> is set on each C<wait> or pipe C<close>, 1783overwriting the old value. This is more like C<$@>, which on every 1784C<eval()> is always set on failure and cleared on success. 1785 1786For more details, see the individual descriptions at C<$@>, C<$!>, 1787C<$^E>, and C<$?>. 1788 1789=over 8 1790 1791=item ${^CHILD_ERROR_NATIVE} 1792X<$^CHILD_ERROR_NATIVE> 1793 1794The native status returned by the last pipe close, backtick (C<``>) 1795command, successful call to C<wait()> or C<waitpid()>, or from the 1796C<system()> operator. On POSIX-like systems this value can be decoded 1797with the WIFEXITED, WEXITSTATUS, WIFSIGNALED, WTERMSIG, WIFSTOPPED, 1798WSTOPSIG and WIFCONTINUED functions provided by the L<POSIX> module. 1799 1800Under VMS this reflects the actual VMS exit status; i.e. it is the 1801same as C<$?> when the pragma C<use vmsish 'status'> is in effect. 1802 1803This variable was added in Perl v5.10.0. 1804 1805=item $EXTENDED_OS_ERROR 1806 1807=item $^E 1808X<$^E> X<$EXTENDED_OS_ERROR> 1809 1810Error information specific to the current operating system. At the 1811moment, this differs from C<L</$!>> under only VMS, OS/2, and Win32 (and 1812for MacPerl). On all other platforms, C<$^E> is always just the same 1813as C<$!>. 1814 1815Under VMS, C<$^E> provides the VMS status value from the last system 1816error. This is more specific information about the last system error 1817than that provided by C<$!>. This is particularly important when C<$!> 1818is set to B<EVMSERR>. 1819 1820Under OS/2, C<$^E> is set to the error code of the last call to OS/2 1821API either via CRT, or directly from perl. 1822 1823Under Win32, C<$^E> always returns the last error information reported 1824by the Win32 call C<GetLastError()> which describes the last error 1825from within the Win32 API. Most Win32-specific code will report errors 1826via C<$^E>. ANSI C and Unix-like calls set C<errno> and so most 1827portable Perl code will report errors via C<$!>. 1828 1829Caveats mentioned in the description of C<L</$!>> generally apply to 1830C<$^E>, also. 1831 1832This variable was added in Perl 5.003. 1833 1834Mnemonic: Extra error explanation. 1835 1836=item $EXCEPTIONS_BEING_CAUGHT 1837 1838=item $^S 1839X<$^S> X<$EXCEPTIONS_BEING_CAUGHT> 1840 1841Current state of the interpreter. 1842 1843 $^S State 1844 --------- ------------------------------------- 1845 undef Parsing module, eval, or main program 1846 true (1) Executing an eval 1847 false (0) Otherwise 1848 1849The first state may happen in C<$SIG{__DIE__}> and C<$SIG{__WARN__}> 1850handlers. 1851 1852The English name $EXCEPTIONS_BEING_CAUGHT is slightly misleading, because 1853the C<undef> value does not indicate whether exceptions are being caught, 1854since compilation of the main program does not catch exceptions. 1855 1856This variable was added in Perl 5.004. 1857 1858=item $WARNING 1859 1860=item $^W 1861X<$^W> X<$WARNING> 1862 1863The current value of the warning switch, initially true if B<-w> was 1864used, false otherwise, but directly modifiable. 1865 1866See also L<warnings>. 1867 1868Mnemonic: related to the B<-w> switch. 1869 1870=item ${^WARNING_BITS} 1871X<${^WARNING_BITS}> 1872 1873The current set of warning checks enabled by the C<use warnings> pragma. 1874It has the same scoping as the C<$^H> and C<%^H> variables. The exact 1875values are considered internal to the L<warnings> pragma and may change 1876between versions of Perl. 1877 1878This variable was added in Perl v5.6.0. 1879 1880=item $OS_ERROR 1881 1882=item $ERRNO 1883 1884=item $! 1885X<$!> X<$ERRNO> X<$OS_ERROR> 1886 1887When referenced, C<$!> retrieves the current value 1888of the C C<errno> integer variable. 1889If C<$!> is assigned a numerical value, that value is stored in C<errno>. 1890When referenced as a string, C<$!> yields the system error string 1891corresponding to C<errno>. 1892 1893Many system or library calls set C<errno> if they fail, 1894to indicate the cause of failure. They usually do B<not> 1895set C<errno> to zero if they succeed. This means C<errno>, 1896hence C<$!>, is meaningful only I<immediately> after a B<failure>: 1897 1898 if (open my $fh, "<", $filename) { 1899 # Here $! is meaningless. 1900 ... 1901 } 1902 else { 1903 # ONLY here is $! meaningful. 1904 ... 1905 # Already here $! might be meaningless. 1906 } 1907 # Since here we might have either success or failure, 1908 # $! is meaningless. 1909 1910Here, I<meaningless> means that C<$!> may be unrelated to the outcome 1911of the C<open()> operator. Assignment to C<$!> is similarly ephemeral. 1912It can be used immediately before invoking the C<die()> operator, 1913to set the exit value, or to inspect the system error string 1914corresponding to error I<n>, or to restore C<$!> to a meaningful state. 1915 1916Mnemonic: What just went bang? 1917 1918=item %OS_ERROR 1919 1920=item %ERRNO 1921 1922=item %! 1923X<%!> X<%OS_ERROR> X<%ERRNO> 1924 1925Each element of C<%!> has a true value only if C<$!> is set to that 1926value. For example, C<$!{ENOENT}> is true if and only if the current 1927value of C<$!> is C<ENOENT>; that is, if the most recent error was "No 1928such file or directory" (or its moral equivalent: not all operating 1929systems give that exact error, and certainly not all languages). The 1930specific true value is not guaranteed, but in the past has generally 1931been the numeric value of C<$!>. To check if a particular key is 1932meaningful on your system, use C<exists $!{the_key}>; for a list of legal 1933keys, use C<keys %!>. See L<Errno> for more information, and also see 1934L</$!>. 1935 1936This variable was added in Perl 5.005. 1937 1938=item $CHILD_ERROR 1939 1940=item $? 1941X<$?> X<$CHILD_ERROR> 1942 1943The status returned by the last pipe close, backtick (C<``>) command, 1944successful call to C<wait()> or C<waitpid()>, or from the C<system()> 1945operator. This is just the 16-bit status word returned by the 1946traditional Unix C<wait()> system call (or else is made up to look 1947like it). Thus, the exit value of the subprocess is really (C<<< $? >> 19488 >>>), and C<$? & 127> gives which signal, if any, the process died 1949from, and C<$? & 128> reports whether there was a core dump. 1950 1951Additionally, if the C<h_errno> variable is supported in C, its value 1952is returned via C<$?> if any C<gethost*()> function fails. 1953 1954If you have installed a signal handler for C<SIGCHLD>, the 1955value of C<$?> will usually be wrong outside that handler. 1956 1957Inside an C<END> subroutine C<$?> contains the value that is going to be 1958given to C<exit()>. You can modify C<$?> in an C<END> subroutine to 1959change the exit status of your program. For example: 1960 1961 END { 1962 $? = 1 if $? == 255; # die would make it 255 1963 } 1964 1965Under VMS, the pragma C<use vmsish 'status'> makes C<$?> reflect the 1966actual VMS exit status, instead of the default emulation of POSIX 1967status; see L<perlvms/$?> for details. 1968 1969Mnemonic: similar to B<sh> and B<ksh>. 1970 1971=item $EVAL_ERROR 1972 1973=item $@ 1974X<$@> X<$EVAL_ERROR> 1975 1976The Perl error from the last C<eval> operator, i.e. the last exception that 1977was caught. For C<eval BLOCK>, this is either a runtime error message or the 1978string or reference C<die> was called with. The C<eval STRING> form also 1979catches syntax errors and other compile time exceptions. 1980 1981If no error occurs, C<eval> sets C<$@> to the empty string. 1982 1983Warning messages are not collected in this variable. You can, however, 1984set up a routine to process warnings by setting C<$SIG{__WARN__}> as 1985described in L</%SIG>. 1986 1987Mnemonic: Where was the error "at"? 1988 1989=back 1990 1991=head2 Variables related to the interpreter state 1992 1993These variables provide information about the current interpreter state. 1994 1995=over 8 1996 1997=item $COMPILING 1998 1999=item $^C 2000X<$^C> X<$COMPILING> 2001 2002The current value of the flag associated with the B<-c> switch. 2003Mainly of use with B<-MO=...> to allow code to alter its behavior 2004when being compiled, such as for example to C<AUTOLOAD> at compile 2005time rather than normal, deferred loading. Setting 2006C<$^C = 1> is similar to calling C<B::minus_c>. 2007 2008This variable was added in Perl v5.6.0. 2009 2010=item $DEBUGGING 2011 2012=item $^D 2013X<$^D> X<$DEBUGGING> 2014 2015The current value of the debugging flags. May be read or set. Like its 2016L<command-line equivalent|perlrun/B<-D>I<letters>>, you can use numeric 2017or symbolic values, e.g. C<$^D = 10> or C<$^D = "st">. See 2018L<perlrun/B<-D>I<number>>. The contents of this variable also affects the 2019debugger operation. See L<perldebguts/Debugger Internals>. 2020 2021Mnemonic: value of B<-D> switch. 2022 2023=item ${^ENCODING} 2024X<${^ENCODING}> 2025 2026This variable is no longer supported. 2027 2028It used to hold the I<object reference> to the C<Encode> object that was 2029used to convert the source code to Unicode. 2030 2031Its purpose was to allow your non-ASCII Perl 2032scripts not to have to be written in UTF-8; this was 2033useful before editors that worked on UTF-8 encoded text were common, but 2034that was long ago. It caused problems, such as affecting the operation 2035of other modules that weren't expecting it, causing general mayhem. 2036 2037If you need something like this functionality, it is recommended that use 2038you a simple source filter, such as L<Filter::Encoding>. 2039 2040If you are coming here because code of yours is being adversely affected 2041by someone's use of this variable, you can usually work around it by 2042doing this: 2043 2044 local ${^ENCODING}; 2045 2046near the beginning of the functions that are getting broken. This 2047undefines the variable during the scope of execution of the including 2048function. 2049 2050This variable was added in Perl 5.8.2 and removed in 5.26.0. 2051Setting it to anything other than C<undef> was made fatal in Perl 5.28.0. 2052 2053=item ${^GLOBAL_PHASE} 2054X<${^GLOBAL_PHASE}> 2055 2056The current phase of the perl interpreter. 2057 2058Possible values are: 2059 2060=over 8 2061 2062=item CONSTRUCT 2063 2064The C<PerlInterpreter*> is being constructed via C<perl_construct>. This 2065value is mostly there for completeness and for use via the 2066underlying C variable C<PL_phase>. It's not really possible for Perl 2067code to be executed unless construction of the interpreter is 2068finished. 2069 2070=item START 2071 2072This is the global compile-time. That includes, basically, every 2073C<BEGIN> block executed directly or indirectly from during the 2074compile-time of the top-level program. 2075 2076This phase is not called "BEGIN" to avoid confusion with 2077C<BEGIN>-blocks, as those are executed during compile-time of any 2078compilation unit, not just the top-level program. A new, localised 2079compile-time entered at run-time, for example by constructs as 2080C<eval "use SomeModule"> are not global interpreter phases, and 2081therefore aren't reflected by C<${^GLOBAL_PHASE}>. 2082 2083=item CHECK 2084 2085Execution of any C<CHECK> blocks. 2086 2087=item INIT 2088 2089Similar to "CHECK", but for C<INIT>-blocks, not C<CHECK> blocks. 2090 2091=item RUN 2092 2093The main run-time, i.e. the execution of C<PL_main_root>. 2094 2095=item END 2096 2097Execution of any C<END> blocks. 2098 2099=item DESTRUCT 2100 2101Global destruction. 2102 2103=back 2104 2105Also note that there's no value for UNITCHECK-blocks. That's because 2106those are run for each compilation unit individually, and therefore is 2107not a global interpreter phase. 2108 2109Not every program has to go through each of the possible phases, but 2110transition from one phase to another can only happen in the order 2111described in the above list. 2112 2113An example of all of the phases Perl code can see: 2114 2115 BEGIN { print "compile-time: ${^GLOBAL_PHASE}\n" } 2116 2117 INIT { print "init-time: ${^GLOBAL_PHASE}\n" } 2118 2119 CHECK { print "check-time: ${^GLOBAL_PHASE}\n" } 2120 2121 { 2122 package Print::Phase; 2123 2124 sub new { 2125 my ($class, $time) = @_; 2126 return bless \$time, $class; 2127 } 2128 2129 sub DESTROY { 2130 my $self = shift; 2131 print "$$self: ${^GLOBAL_PHASE}\n"; 2132 } 2133 } 2134 2135 print "run-time: ${^GLOBAL_PHASE}\n"; 2136 2137 my $runtime = Print::Phase->new( 2138 "lexical variables are garbage collected before END" 2139 ); 2140 2141 END { print "end-time: ${^GLOBAL_PHASE}\n" } 2142 2143 our $destruct = Print::Phase->new( 2144 "package variables are garbage collected after END" 2145 ); 2146 2147This will print out 2148 2149 compile-time: START 2150 check-time: CHECK 2151 init-time: INIT 2152 run-time: RUN 2153 lexical variables are garbage collected before END: RUN 2154 end-time: END 2155 package variables are garbage collected after END: DESTRUCT 2156 2157This variable was added in Perl 5.14.0. 2158 2159=item $^H 2160X<$^H> 2161 2162WARNING: This variable is strictly for 2163internal use only. Its availability, 2164behavior, and contents are subject to change without notice. 2165 2166This variable contains compile-time hints for the Perl interpreter. At the 2167end of compilation of a BLOCK the value of this variable is restored to the 2168value when the interpreter started to compile the BLOCK. 2169 2170When perl begins to parse any block construct that provides a lexical scope 2171(e.g., eval body, required file, subroutine body, loop body, or conditional 2172block), the existing value of C<$^H> is saved, but its value is left unchanged. 2173When the compilation of the block is completed, it regains the saved value. 2174Between the points where its value is saved and restored, code that 2175executes within BEGIN blocks is free to change the value of C<$^H>. 2176 2177This behavior provides the semantic of lexical scoping, and is used in, 2178for instance, the C<use strict> pragma. 2179 2180The contents should be an integer; different bits of it are used for 2181different pragmatic flags. Here's an example: 2182 2183 sub add_100 { $^H |= 0x100 } 2184 2185 sub foo { 2186 BEGIN { add_100() } 2187 bar->baz($boon); 2188 } 2189 2190Consider what happens during execution of the BEGIN block. At this point 2191the BEGIN block has already been compiled, but the body of C<foo()> is still 2192being compiled. The new value of C<$^H> 2193will therefore be visible only while 2194the body of C<foo()> is being compiled. 2195 2196Substitution of C<BEGIN { add_100() }> block with: 2197 2198 BEGIN { require strict; strict->import('vars') } 2199 2200demonstrates how C<use strict 'vars'> is implemented. Here's a conditional 2201version of the same lexical pragma: 2202 2203 BEGIN { 2204 require strict; strict->import('vars') if $condition 2205 } 2206 2207This variable was added in Perl 5.003. 2208 2209=item %^H 2210X<%^H> 2211 2212The C<%^H> hash provides the same scoping semantic as C<$^H>. This makes 2213it useful for implementation of lexically scoped pragmas. See 2214L<perlpragma>. All the entries are stringified when accessed at 2215runtime, so only simple values can be accommodated. This means no 2216pointers to objects, for example. 2217 2218When putting items into C<%^H>, in order to avoid conflicting with other 2219users of the hash there is a convention regarding which keys to use. 2220A module should use only keys that begin with the module's name (the 2221name of its main package) and a "/" character. For example, a module 2222C<Foo::Bar> should use keys such as C<Foo::Bar/baz>. 2223 2224This variable was added in Perl v5.6.0. 2225 2226=item ${^OPEN} 2227X<${^OPEN}> 2228 2229An internal variable used by PerlIO. A string in two parts, separated 2230by a C<\0> byte, the first part describes the input layers, the second 2231part describes the output layers. 2232 2233This variable was added in Perl v5.8.0. 2234 2235=item $PERLDB 2236 2237=item $^P 2238X<$^P> X<$PERLDB> 2239 2240The internal variable for debugging support. The meanings of the 2241various bits are subject to change, but currently indicate: 2242 2243=over 6 2244 2245=item 0x01 2246 2247Debug subroutine enter/exit. 2248 2249=item 0x02 2250 2251Line-by-line debugging. Causes C<DB::DB()> subroutine to be called for 2252each statement executed. Also causes saving source code lines (like 22530x400). 2254 2255=item 0x04 2256 2257Switch off optimizations. 2258 2259=item 0x08 2260 2261Preserve more data for future interactive inspections. 2262 2263=item 0x10 2264 2265Keep info about source lines on which a subroutine is defined. 2266 2267=item 0x20 2268 2269Start with single-step on. 2270 2271=item 0x40 2272 2273Use subroutine address instead of name when reporting. 2274 2275=item 0x80 2276 2277Report C<goto &subroutine> as well. 2278 2279=item 0x100 2280 2281Provide informative "file" names for evals based on the place they were compiled. 2282 2283=item 0x200 2284 2285Provide informative names to anonymous subroutines based on the place they 2286were compiled. 2287 2288=item 0x400 2289 2290Save source code lines into C<@{"_<$filename"}>. 2291 2292=item 0x800 2293 2294When saving source, include evals that generate no subroutines. 2295 2296=item 0x1000 2297 2298When saving source, include source that did not compile. 2299 2300=back 2301 2302Some bits may be relevant at compile-time only, some at 2303run-time only. This is a new mechanism and the details may change. 2304See also L<perldebguts>. 2305 2306=item ${^TAINT} 2307X<${^TAINT}> 2308 2309Reflects if taint mode is on or off. 1 for on (the program was run with 2310B<-T>), 0 for off, -1 when only taint warnings are enabled (i.e. with 2311B<-t> or B<-TU>). 2312 2313This variable is read-only. 2314 2315This variable was added in Perl v5.8.0. 2316 2317=item ${^SAFE_LOCALES} 2318X<${^SAFE_LOCALES}> 2319 2320Reflects if safe locale operations are available to this perl (when the 2321value is 1) or not (the value is 0). This variable is always 1 if the 2322perl has been compiled without threads. It is also 1 if this perl is 2323using thread-safe locale operations. Note that an individual thread may 2324choose to use the global locale (generally unsafe) by calling 2325L<perlapi/switch_to_global_locale>. This variable currently is still 2326set to 1 in such threads. 2327 2328This variable is read-only. 2329 2330This variable was added in Perl v5.28.0. 2331 2332=item ${^UNICODE} 2333X<${^UNICODE}> 2334 2335Reflects certain Unicode settings of Perl. See L<perlrun> 2336documentation for the C<-C> switch for more information about 2337the possible values. 2338 2339This variable is set during Perl startup and is thereafter read-only. 2340 2341This variable was added in Perl v5.8.2. 2342 2343=item ${^UTF8CACHE} 2344X<${^UTF8CACHE}> 2345 2346This variable controls the state of the internal UTF-8 offset caching code. 23471 for on (the default), 0 for off, -1 to debug the caching code by checking 2348all its results against linear scans, and panicking on any discrepancy. 2349 2350This variable was added in Perl v5.8.9. It is subject to change or 2351removal without notice, but is currently used to avoid recalculating the 2352boundaries of multi-byte UTF-8-encoded characters. 2353 2354=item ${^UTF8LOCALE} 2355X<${^UTF8LOCALE}> 2356 2357This variable indicates whether a UTF-8 locale was detected by perl at 2358startup. This information is used by perl when it's in 2359adjust-utf8ness-to-locale mode (as when run with the C<-CL> command-line 2360switch); see L<perlrun> for more info on this. 2361 2362This variable was added in Perl v5.8.8. 2363 2364=back 2365 2366=head2 Deprecated and removed variables 2367 2368Deprecating a variable announces the intent of the perl maintainers to 2369eventually remove the variable from the language. It may still be 2370available despite its status. Using a deprecated variable triggers 2371a warning. 2372 2373Once a variable is removed, its use triggers an error telling you 2374the variable is unsupported. 2375 2376See L<perldiag> for details about error messages. 2377 2378=over 8 2379 2380=item $# 2381X<$#> 2382 2383C<$#> was a variable that could be used to format printed numbers. 2384After a deprecation cycle, its magic was removed in Perl v5.10.0 and 2385using it now triggers a warning: C<$# is no longer supported>. 2386 2387This is not the sigil you use in front of an array name to get the 2388last index, like C<$#array>. That's still how you get the last index 2389of an array in Perl. The two have nothing to do with each other. 2390 2391Deprecated in Perl 5. 2392 2393Removed in Perl v5.10.0. 2394 2395=item $* 2396X<$*> 2397 2398C<$*> was a variable that you could use to enable multiline matching. 2399After a deprecation cycle, its magic was removed in Perl v5.10.0. 2400Using it now triggers a warning: C<$* is no longer supported>. 2401You should use the C</s> and C</m> regexp modifiers instead. 2402 2403Deprecated in Perl 5. 2404 2405Removed in Perl v5.10.0. 2406 2407=item $[ 2408X<$[> 2409 2410This variable stores the index of the first element in an array, and 2411of the first character in a substring. The default is 0, but you could 2412theoretically set it to 1 to make Perl behave more like B<awk> (or Fortran) 2413when subscripting and when evaluating the index() and substr() functions. 2414 2415As of release 5 of Perl, assignment to C<$[> is treated as a compiler 2416directive, and cannot influence the behavior of any other file. 2417(That's why you can only assign compile-time constants to it.) 2418Its use is highly discouraged. 2419 2420Prior to Perl v5.10.0, assignment to C<$[> could be seen from outer lexical 2421scopes in the same file, unlike other compile-time directives (such as 2422L<strict>). Using local() on it would bind its value strictly to a lexical 2423block. Now it is always lexically scoped. 2424 2425As of Perl v5.16.0, it is implemented by the L<arybase> module. 2426 2427As of Perl v5.30.0, or under C<use v5.16>, or C<no feature "array_base">, 2428C<$[> no longer has any effect, and always contains 0. 2429Assigning 0 to it is permitted, but any other value will produce an error. 2430 2431Mnemonic: [ begins subscripts. 2432 2433Deprecated in Perl v5.12.0. 2434 2435=back 2436 2437=cut 2438