3 perlvar - Perl predefined variables
7 =head2 The Syntax of Variable Names
9 Variable names in Perl can have several formats. Usually, they
10 must begin with a letter or underscore, in which case they can be
11 arbitrarily long (up to an internal limit of 251 characters) and
12 may contain letters, digits, underscores, or the special sequence
13 C<::> or C<'>. In this case, the part before the last C<::> or
14 C<'> is taken to be a I<package qualifier>; see L<perlmod>.
16 Perl variable names may also be a sequence of digits or a single
17 punctuation or control character. These names are all reserved for
18 special uses by Perl; for example, the all-digits names are used
19 to hold data captured by backreferences after a regular expression
20 match. Perl has a special syntax for the single-control-character
21 names: It understands C<^X> (caret C<X>) to mean the control-C<X>
22 character. For example, the notation C<$^W> (dollar-sign caret
23 C<W>) is the scalar variable whose name is the single character
24 control-C<W>. This is better than typing a literal control-C<W>
27 Since Perl 5.6, Perl variable names may be alphanumeric
28 strings that begin with control characters (or better yet, a caret).
29 These variables must be written in the form C<${^Foo}>; the braces
30 are not optional. C<${^Foo}> denotes the scalar variable whose
31 name is a control-C<F> followed by two C<o>'s. These variables are
32 reserved for future special uses by Perl, except for the ones that
33 begin with C<^_> (control-underscore or caret-underscore). No
34 control-character name that begins with C<^_> will acquire a special
35 meaning in any future version of Perl; such names may therefore be
36 used safely in programs. C<$^_> itself, however, I<is> reserved.
38 Perl identifiers that begin with digits, control characters, or
39 punctuation characters are exempt from the effects of the C<package>
40 declaration and are always forced to be in package C<main>; they are
41 also exempt from C<strict 'vars'> errors. A few other names are also
50 In particular, the special C<${^_XYZ}> variables are always taken
51 to be in package C<main>, regardless of any C<package> declarations
54 =head1 SPECIAL VARIABLES
56 The following names have special meaning to Perl. Most punctuation
57 names have reasonable mnemonics, or analogs in the shells.
58 Nevertheless, if you wish to use long variable names, you need only say:
62 at the top of your program. This aliases all the short names to the long
63 names in the current package. Some even have medium names, generally
64 borrowed from B<awk>. To avoid a performance hit, if you don't need the
65 C<$PREMATCH>, C<$MATCH>, or C<$POSTMATCH> it's best to use the C<English>
68 use English '-no_match_vars';
70 Before you continue, note the sort order for variables. In general, we
71 first list the variables in case-insensitive, almost-lexigraphical
72 order (ignoring the C<{> or C<^> preceding words, as in C<${^UNICODE}>
73 or C<$^T>), although C<$_> and C<@_> move up to the top of the pile.
74 For variables with the same identifier, we list it in order of scalar,
75 array, hash, and bareword.
77 =head2 General Variables
86 The default input and pattern-searching space. The following pairs are
89 while (<>) {...} # equivalent only in while!
90 while (defined($_ = <>)) {...}
101 Here are the places where Perl will assume C<$_> even if you don't use it:
107 The following functions use C<$_> as a default argument:
109 abs, alarm, chomp, chop, chr, chroot, cos, defined, eval, exp, glob,
110 hex, int, lc, lcfirst, length, log, lstat, mkdir, oct, ord, pos, print,
111 quotemeta, readlink, readpipe, ref, require, reverse (in scalar context only),
112 rmdir, sin, split (on its second argument), sqrt, stat, study, uc, ucfirst,
117 All file tests (C<-f>, C<-d>) except for C<-t>, which defaults to STDIN.
122 The pattern matching operations C<m//>, C<s///> and C<tr///> (aka C<y///>)
123 when used without an C<=~> operator.
127 The default iterator variable in a C<foreach> loop if no other
128 variable is supplied.
132 The implicit iterator variable in the C<grep()> and C<map()> functions.
136 The implicit variable of C<given()>.
140 The default place to put an input record when a C<< <FH> >>
141 operation's result is tested by itself as the sole criterion of a C<while>
142 test. Outside a C<while> test, this will not happen.
146 As C<$_> is a global variable, this may lead in some cases to unwanted
147 side-effects. As of perl 5.9.1, you can now use a lexical version of
148 C<$_> by declaring it in a file or in a block with C<my>. Moreover,
149 declaring C<our $_> restores the global C<$_> in the current scope.
151 Mnemonic: underline is understood in certain operations.
158 Within a subroutine the array C<@_> contains the parameters passed to
159 that subroutine. Inside a subroutine, C<@_> is the default array for
160 the array operators C<push>, C<pop>, C<shift>, and C<unshift>.
164 =item $LIST_SEPARATOR
167 X<$"> X<$LIST_SEPARATOR>
169 When an array or an array slice is interpolated into a double-quoted
170 string or a similar context such as C</.../>, its elements are
171 separated by this value. Default is a space. For example, this:
173 print "The array is: @array\n";
175 is equivalent to this:
177 print "The array is: " . join($", @array) . "\n";
179 Mnemonic: works in double-quoted context.
186 X<$$> X<$PID> X<$PROCESS_ID>
188 The process number of the Perl running this script. Though you I<can> set
189 this variable, doing so is generally discouraged, although it can be
190 invaluable for some testing purposes. It will be reset automatically
191 across C<fork()> calls.
193 Note for Linux users: on Linux, the C functions C<getpid()> and
194 C<getppid()> return different values from different threads. In order to
195 be portable, this behavior is not reflected by C<$$>, whose value remains
196 consistent across threads. If you want to call the underlying C<getpid()>,
197 you may use the CPAN module C<Linux::Pid>.
199 Mnemonic: same as shells.
206 X<$(> X<$GID> X<$REAL_GROUP_ID>
208 The real gid of this process. If you are on a machine that supports
209 membership in multiple groups simultaneously, gives a space separated
210 list of groups you are in. The first number is the one returned by
211 C<getgid()>, and the subsequent ones by C<getgroups()>, one of which may be
212 the same as the first number.
214 However, a value assigned to C<$(> must be a single number used to
215 set the real gid. So the value given by C<$(> should I<not> be assigned
216 back to C<$(> without being forced numeric, such as by adding zero. Note
217 that this is different to the effective gid (C<$)>) which does take a
220 You can change both the real gid and the effective gid at the same
221 time by using C<POSIX::setgid()>. Changes to C<$(> require a check to C<$!>
222 to detect any possible errors after an attempted change.
224 Mnemonic: parentheses are used to I<group> things. The real gid is the
225 group you I<left>, if you're running setgid.
227 =item $EFFECTIVE_GROUP_ID
232 X<$)> X<$EGID> X<$EFFECTIVE_GROUP_ID>
234 The effective gid of this process. If you are on a machine that
235 supports membership in multiple groups simultaneously, gives a space
236 separated list of groups you are in. The first number is the one
237 returned by C<getegid()>, and the subsequent ones by C<getgroups()>,
238 one of which may be the same as the first number.
240 Similarly, a value assigned to C<$)> must also be a space-separated
241 list of numbers. The first number sets the effective gid, and
242 the rest (if any) are passed to C<setgroups()>. To get the effect of an
243 empty list for C<setgroups()>, just repeat the new effective gid; that is,
244 to force an effective gid of 5 and an effectively empty C<setgroups()>
245 list, say C< $) = "5 5" >.
247 You can change both the effective gid and the real gid at the same
248 time by using C<POSIX::setgid()> (use only a single numeric argument).
249 Changes to C<$)> require a check to C<$!> to detect any possible errors
250 after an attempted change.
252 C<< $< >>, C<< $> >>, C<$(> and C<$)> can be set only on
253 machines that support the corresponding I<set[re][ug]id()> routine. C<$(>
254 and C<$)> can be swapped only on machines supporting C<setregid()>.
256 Mnemonic: parentheses are used to I<group> things. The effective gid
257 is the group that's I<right> for you, if you're running setgid.
262 X<$0> X<$PROGRAM_NAME>
264 Contains the name of the program being executed.
266 On some (but not all) operating systems assigning to C<$0> modifies
267 the argument area that the C<ps> program sees. On some platforms you
268 may have to use special C<ps> options or a different C<ps> to see the
269 changes. Modifying the C<$0> is more useful as a way of indicating the
270 current program state than it is for hiding the program you're
273 Note that there are platform-specific limitations on the maximum
274 length of C<$0>. In the most extreme case it may be limited to the
275 space occupied by the original C<$0>.
277 In some platforms there may be arbitrary amount of padding, for
278 example space characters, after the modified name as shown by C<ps>.
279 In some platforms this padding may extend all the way to the original
280 length of the argument area, no matter what you do (this is the case
281 for example with Linux 2.2).
283 Note for BSD users: setting C<$0> does not completely remove "perl"
284 from the ps(1) output. For example, setting C<$0> to C<"foobar"> may
285 result in C<"perl: foobar (perl)"> (whether both the C<"perl: "> prefix
286 and the " (perl)" suffix are shown depends on your exact BSD variant
287 and version). This is an operating system feature, Perl cannot help it.
289 In multithreaded scripts Perl coordinates the threads so that any
290 thread may modify its copy of the C<$0> and the change becomes visible
291 to ps(1) (assuming the operating system plays along). Note that
292 the view of C<$0> the other threads have will not change since they
293 have their own copies of it.
295 If the program has been given to perl via the switches C<-e> or C<-E>,
296 C<$0> will contain the string C<"-e">.
298 On Linux as of perl 5.14 the legacy process name will be set with
299 C<prctl(2)>, in addition to altering the POSIX name via C<argv[0]> as
300 perl has done since version 4.000. Now system utilities that read the
301 legacy process name such as ps, top and killall will recognize the
302 name you set when assigning to C<$0>. The string you supply will be
303 cut off at 16 bytes, this is a limitation imposed by Linux.
305 Mnemonic: same as B<sh> and B<ksh>.
307 =item $SUBSCRIPT_SEPARATOR
312 X<$;> X<$SUBSEP> X<SUBSCRIPT_SEPARATOR>
314 The subscript separator for multidimensional array emulation. If you
315 refer to a hash element as
321 $foo{join($;, $a, $b, $c)}
325 @foo{$a,$b,$c} # a slice--note the @
329 ($foo{$a},$foo{$b},$foo{$c})
331 Default is "\034", the same as SUBSEP in B<awk>. If your keys contain
332 binary data there might not be any safe value for C<$;>.
334 Consider using "real" multidimensional arrays as described
337 Mnemonic: comma (the syntactic subscript separator) is a semi-semicolon.
344 X<< $< >> X<$UID> X<$REAL_USER_ID>
346 The real uid of this process. You can change both the real uid and the
347 effective uid at the same time by using C<POSIX::setuid()>. Since
348 changes to C<< $< >> require a system call, check C<$!> after a change
349 attempt to detect any possible errors.
351 Mnemonic: it's the uid you came I<from>, if you're running setuid.
353 =item $EFFECTIVE_USER_ID
358 X<< $> >> X<$EUID> X<$EFFECTIVE_USER_ID>
360 The effective uid of this process. For example:
362 $< = $>; # set real to effective uid
363 ($<,$>) = ($>,$<); # swap real and effective uids
365 You can change both the effective uid and the real uid at the same
366 time by using C<POSIX::setuid()>. Changes to C<< $> >> require a check
367 to C<$!> to detect any possible errors after an attempted change.
369 C<< $< >> and C<< $> >> can be swapped only on machines
370 supporting C<setreuid()>.
372 Mnemonic: it's the uid you went I<to>, if you're running setuid.
379 Special package variables when using C<sort()>, see L<perlfunc/sort>.
380 Because of this specialness C<$a> and C<$b> don't need to be declared
381 (using C<use vars>, or C<our()>) even when using the C<strict 'vars'>
382 pragma. Don't lexicalize them with C<my $a> or C<my $b> if you want to
383 be able to use them in the C<sort()> comparison block or function.
390 The current value of the flag associated with the B<-c> switch.
391 Mainly of use with B<-MO=...> to allow code to alter its behavior
392 when being compiled, such as for example to C<AUTOLOAD> at compile
393 time rather than normal, deferred loading. Setting
394 C<$^C = 1> is similar to calling C<B::minus_c>.
396 This variable was added in Perl 5.6.
403 The current value of the debugging flags. May be read or set. Like its
404 command-line equivalent, you can use numeric or symbolic values, eg
405 C<$^D = 10> or C<$^D = "st">.
407 Mnemonic: value of B<-D> switch.
412 The I<object reference> to the C<Encode> object that is used to convert
413 the source code to Unicode. Thanks to this variable your Perl script
414 does not have to be written in UTF-8. Default is I<undef>. The direct
415 manipulation of this variable is highly discouraged.
417 This variable was added in Perl 5.8.2.
422 The hash C<%ENV> contains your current environment. Setting a
423 value in C<ENV> changes the environment for any child processes
424 you subsequently C<fork()> off.
429 X<$^F> X<$SYSTEM_FD_MAX>
431 The maximum system file descriptor, ordinarily 2. System file
432 descriptors are passed to C<exec()>ed processes, while higher file
433 descriptors are not. Also, during an C<open()>, system file descriptors are
434 preserved even if the C<open()> fails (ordinary file descriptors are
435 closed before the C<open()> is attempted). The close-on-exec
436 status of a file descriptor will be decided according to the value of
437 C<$^F> when the corresponding file, pipe, or socket was opened, not the
438 time of the C<exec()>.
443 The array C<@F> contains the fields of each line read in when autosplit
444 mode is turned on. See L<perlrun> for the B<-a> switch. This array
445 is package-specific, and must be declared or given a full package name
446 if not in package main when running under C<strict 'vars'>.
448 =item ${^GLOBAL_PHASE}
451 The current phase of the perl interpreter.
459 The C<PerlInterpreter*> is being constructed via C<perl_construct>. This
460 value is mostly there for completeness and for use via the
461 underlying C variable C<PL_phase>. It's not really possible for Perl
462 code to be executed unless construction of the interpreter is
467 This is the global compile-time. That includes, basically, every
468 C<BEGIN> block executed directly or indirectly from during the
469 compile-time of the top-level program.
471 This phase is not called "BEGIN" to avoid confusion with
472 C<BEGIN>-blocks, as those are executed during compile-time of any
473 compilation unit, not just the top-level program. A new, localised
474 compile-time entered at run-time, for example by constructs as
475 C<eval "use SomeModule"> are not global interpreter phases, and
476 therefore aren't reflected by C<${^GLOBAL_PHASE}>.
480 Execution of any C<CHECK> blocks.
484 Similar to "CHECK", but for C<INIT>-blocks, not C<CHECK> blocks.
488 The main run-time, i.e. the execution of C<PL_main_root>.
492 Execution of any C<END> blocks.
500 Also note that there's no value for UNITCHECK-blocks. That's because
501 those are run for each compilation unit individually, and therefore is
502 not a global interpreter phase.
504 Not every program has to go through each of the possible phases, but
505 transition from one phase to another can only happen in the order
506 described in the above list.
508 An example of all of the phases Perl code can see:
510 BEGIN { print "compile-time: ${^GLOBAL_PHASE}\n" }
512 INIT { print "init-time: ${^GLOBAL_PHASE}\n" }
514 CHECK { print "check-time: ${^GLOBAL_PHASE}\n" }
517 package Print::Phase;
520 my ($class, $time) = @_;
521 return bless \$time, $class;
526 print "$$self: ${^GLOBAL_PHASE}\n";
530 print "run-time: ${^GLOBAL_PHASE}\n";
532 my $runtime = Print::Phase->new(
533 "lexical variables are garbage collected before END"
536 END { print "end-time: ${^GLOBAL_PHASE}\n" }
538 our $destruct = Print::Phase->new(
539 "package variables are garbage collected after END"
548 lexical variables are garbage collected before END: RUN
550 package variables are garbage collected after END: DESTRUCT
552 This variable was added in Perl 5.14.0.
557 WARNING: This variable is strictly for internal use only. Its availability,
558 behavior, and contents are subject to change without notice.
560 This variable contains compile-time hints for the Perl interpreter. At the
561 end of compilation of a BLOCK the value of this variable is restored to the
562 value when the interpreter started to compile the BLOCK.
564 When perl begins to parse any block construct that provides a lexical scope
565 (e.g., eval body, required file, subroutine body, loop body, or conditional
566 block), the existing value of C<$^H> is saved, but its value is left unchanged.
567 When the compilation of the block is completed, it regains the saved value.
568 Between the points where its value is saved and restored, code that
569 executes within BEGIN blocks is free to change the value of C<$^H>.
571 This behavior provides the semantic of lexical scoping, and is used in,
572 for instance, the C<use strict> pragma.
574 The contents should be an integer; different bits of it are used for
575 different pragmatic flags. Here's an example:
577 sub add_100 { $^H |= 0x100 }
584 Consider what happens during execution of the BEGIN block. At this point
585 the BEGIN block has already been compiled, but the body of C<foo()> is still
586 being compiled. The new value of C<$^H> will therefore be visible only while
587 the body of C<foo()> is being compiled.
589 Substitution of C<BEGIN { add_100() }> block with:
591 BEGIN { require strict; strict->import('vars') }
593 demonstrates how C<use strict 'vars'> is implemented. Here's a conditional
594 version of the same lexical pragma:
596 BEGIN { require strict; strict->import('vars') if $condition }
598 This variable was added in Perl 5.003.
603 The C<%^H> hash provides the same scoping semantic as C<$^H>. This makes it
604 useful for implementation of lexically scoped pragmas. See L<perlpragma>.
606 This variable was added in Perl 5.6.
611 The array C<@INC> contains the list of places that the C<do EXPR>,
612 C<require>, or C<use> constructs look for their library files. It
613 initially consists of the arguments to any B<-I> command-line
614 switches, followed by the default Perl library, probably
615 F</usr/local/lib/perl>, followed by ".", to represent the current
616 directory. ("." will not be appended if taint checks are enabled,
617 either by C<-T> or by C<-t>.) If you need to modify this at runtime,
618 you should use the C<use lib> pragma to get the machine-dependent
619 library properly loaded also:
621 use lib '/mypath/libdir/';
624 You can also insert hooks into the file inclusion system by putting Perl
625 code directly into C<@INC>. Those hooks may be subroutine references, array
626 references or blessed objects. See L<perlfunc/require> for details.
631 The hash C<%INC> contains entries for each filename included via the
632 C<do>, C<require>, or C<use> operators. The key is the filename
633 you specified (with module names converted to pathnames), and the
634 value is the location of the file found. The C<require>
635 operator uses this hash to determine whether a particular file has
636 already been included.
638 If the file was loaded via a hook (e.g. a subroutine reference, see
639 L<perlfunc/require> for a description of these hooks), this hook is
640 by default inserted into C<%INC> in place of a filename. Note, however,
641 that the hook may have set the C<%INC> entry by itself to provide some more
647 X<$^I> X<$INPLACE_EDIT>
649 The current value of the inplace-edit extension. Use C<undef> to disable
652 Mnemonic: value of B<-i> switch.
657 By default, running out of memory is an untrappable, fatal error.
658 However, if suitably built, Perl can use the contents of C<$^M>
659 as an emergency memory pool after C<die()>ing. Suppose that your Perl
660 were compiled with C<-DPERL_EMERGENCY_SBRK> and used Perl's malloc.
663 $^M = 'a' x (1 << 16);
665 would allocate a 64K buffer for use in an emergency. See the
666 F<INSTALL> file in the Perl distribution for information on how to
667 add custom C compilation flags when compiling perl. To discourage casual
668 use of this advanced feature, there is no L<English|English> long name for
671 This variable was added in Perl 5.004.
678 The name of the operating system under which this copy of Perl was
679 built, as determined during the configuration process. For examples
680 see L<perlport/PLATFORMS>.
682 The value is identical to C<$Config{'osname'}>. See also L<Config>
683 and the B<-V> command-line switch documented in L<perlrun>.
685 In Windows platforms, C<$^O> is not very helpful: since it is always
686 C<MSWin32>, it doesn't tell the difference between
687 95/98/ME/NT/2000/XP/CE/.NET. Use C<Win32::GetOSName()> or
688 Win32::GetOSVersion() (see L<Win32> and L<perlport>) to distinguish
689 between the variants.
691 This variable was added in Perl 5.003.
696 An internal variable used by PerlIO. A string in two parts, separated
697 by a C<\0> byte, the first part describes the input layers, the second
698 part describes the output layers.
700 This variable was added in Perl 5.8.2.
707 The internal variable for debugging support. The meanings of the
708 various bits are subject to change, but currently indicate:
714 Debug subroutine enter/exit.
718 Line-by-line debugging. Causes C<DB::DB()> subroutine to be called for each
719 statement executed. Also causes saving source code lines (like 0x400).
723 Switch off optimizations.
727 Preserve more data for future interactive inspections.
731 Keep info about source lines on which a subroutine is defined.
735 Start with single-step on.
739 Use subroutine address instead of name when reporting.
743 Report C<goto &subroutine> as well.
747 Provide informative "file" names for evals based on the place they were compiled.
751 Provide informative names to anonymous subroutines based on the place they
756 Save source code lines into C<@{"_<$filename"}>.
760 Some bits may be relevant at compile-time only, some at
761 run-time only. This is a new mechanism and the details may change.
762 See also L<perldebguts>.
767 The hash C<%SIG> contains signal handlers for signals. For example:
769 sub handler { # 1st argument is signal name
771 print "Caught a SIG$sig--shutting down\n";
776 $SIG{'INT'} = \&handler;
777 $SIG{'QUIT'} = \&handler;
779 $SIG{'INT'} = 'DEFAULT'; # restore default action
780 $SIG{'QUIT'} = 'IGNORE'; # ignore SIGQUIT
782 Using a value of C<'IGNORE'> usually has the effect of ignoring the
783 signal, except for the C<CHLD> signal. See L<perlipc> for more about
786 Here are some other examples:
788 $SIG{"PIPE"} = "Plumber"; # assumes main::Plumber (not recommended)
789 $SIG{"PIPE"} = \&Plumber; # just fine; assume current Plumber
790 $SIG{"PIPE"} = *Plumber; # somewhat esoteric
791 $SIG{"PIPE"} = Plumber(); # oops, what did Plumber() return??
793 Be sure not to use a bareword as the name of a signal handler,
794 lest you inadvertently call it.
796 If your system has the C<sigaction()> function then signal handlers
797 are installed using it. This means you get reliable signal handling.
799 The default delivery policy of signals changed in Perl 5.8.0 from
800 immediate (also known as "unsafe") to deferred, also known as "safe
801 signals". See L<perlipc> for more information.
803 Certain internal hooks can be also set using the C<%SIG> hash. The
804 routine indicated by C<$SIG{__WARN__}> is called when a warning
805 message is about to be printed. The warning message is passed as the
806 first argument. The presence of a C<__WARN__> hook causes the
807 ordinary printing of warnings to C<STDERR> to be suppressed. You can
808 use this to save warnings in a variable, or turn warnings into fatal
811 local $SIG{__WARN__} = sub { die $_[0] };
814 As the C<'IGNORE'> hook is not supported by C<__WARN__>, you can
815 disable warnings using the empty subroutine:
817 local $SIG{__WARN__} = sub {};
819 The routine indicated by C<$SIG{__DIE__}> is called when a fatal
820 exception is about to be thrown. The error message is passed as the
821 first argument. When a C<__DIE__> hook routine returns, the exception
822 processing continues as it would have in the absence of the hook,
823 unless the hook routine itself exits via a C<goto>, a loop exit, or a
824 C<die()>. The C<__DIE__> handler is explicitly disabled during the
825 call, so that you can die from a C<__DIE__> handler. Similarly for
828 Due to an implementation glitch, the C<$SIG{__DIE__}> hook is called
829 even inside an C<eval()>. Do not use this to rewrite a pending
830 exception in C<$@>, or as a bizarre substitute for overriding
831 C<CORE::GLOBAL::die()>. This strange action at a distance may be fixed
832 in a future release so that C<$SIG{__DIE__}> is only called if your
833 program is about to exit, as was the original intent. Any other use is
836 C<__DIE__>/C<__WARN__> handlers are very special in one respect: they
837 may be called to report (probable) errors found by the parser. In such
838 a case the parser may be in inconsistent state, so any attempt to
839 evaluate Perl code from such a handler will probably result in a
840 segfault. This means that warnings or errors that result from parsing
841 Perl should be used with extreme caution, like this:
843 require Carp if defined $^S;
844 Carp::confess("Something wrong") if defined &Carp::confess;
845 die "Something wrong, but could not load Carp to give backtrace...
846 To see backtrace try starting Perl with -MCarp switch";
848 Here the first line will load C<Carp> I<unless> it is the parser who
849 called the handler. The second line will print backtrace and die if
850 C<Carp> was available. The third line will be executed only if C<Carp> was
853 Having to even think about the C<$^S> variable in your exception
854 handlers is simply wrong. C<$SIG{__DIE__}> as currently implemented
855 invites grievous and difficult to track down errors. Avoid it
856 and use an C<END{}> or CORE::GLOBAL::die override instead.
858 See L<perlfunc/die>, L<perlfunc/warn>, L<perlfunc/eval>, and
859 L<warnings> for additional information.
866 The time at which the program began running, in seconds since the
867 epoch (beginning of 1970). The values returned by the B<-M>, B<-A>,
868 and B<-C> filetests are based on this value.
873 Reflects if taint mode is on or off. 1 for on (the program was run with
874 B<-T>), 0 for off, -1 when only taint warnings are enabled (i.e. with
877 This variable is read-only.
879 This variable was added in Perl 5.8.
884 Reflects certain Unicode settings of Perl. See L<perlrun>
885 documentation for the C<-C> switch for more information about
888 This variable is set during Perl startup and is thereafter read-only.
890 This variable was added in Perl 5.8.2.
895 This variable controls the state of the internal UTF-8 offset caching code.
896 1 for on (the default), 0 for off, -1 to debug the caching code by checking
897 all its results against linear scans, and panicking on any discrepancy.
899 This variable was added in Perl 5.8.9.
904 This variable indicates whether a UTF-8 locale was detected by perl at
905 startup. This information is used by perl when it's in
906 adjust-utf8ness-to-locale mode (as when run with the C<-CL> command-line
907 switch); see L<perlrun> for more info on this.
909 This variable was added in Perl 5.8.8.
914 X<$^V> X<$PERL_VERSION>
916 The revision, version, and subversion of the Perl interpreter,
917 represented as a C<version> object.
919 This variable first appeared in perl 5.6.0; earlier versions of perl
920 will see an undefined value. Before perl 5.10.0 C<$^V> was represented
923 C<$^V> can be used to determine whether the Perl interpreter executing
924 a script is in the right range of versions. For example:
926 warn "Hashes not randomized!\n" if !$^V or $^V lt v5.8.1
928 To convert C<$^V> into its string representation use C<sprintf()>'s
931 printf "version is v%vd\n", $^V; # Perl's version
933 See the documentation of C<use VERSION> and C<require VERSION>
934 for a convenient way to fail if the running Perl interpreter is too old.
936 See also C<$]> for an older representation of the Perl version.
938 This variable was added in Perl 5.6.
940 Mnemonic: use ^V for Version Control.
942 =item ${^WIN32_SLOPPY_STAT}
943 X<${^WIN32_SLOPPY_STAT}> X<sitecustomize> X<sitecustomize.pl>
945 If this variable is set to a true value, then C<stat()> on Windows will
946 not try to open the file. This means that the link count cannot be
947 determined and file attributes may be out of date if additional
948 hardlinks to the file exist. On the other hand, not opening the file
949 is considerably faster, especially for files on network drives.
951 This variable could be set in the F<sitecustomize.pl> file to
952 configure the local Perl installation to use "sloppy" C<stat()> by
953 default. See the documentation for B<-f> in
954 L<perlrun|perlrun/"Command Switches"> for more information about site
957 This variable was added in Perl 5.10.
959 =item $EXECUTABLE_NAME
962 X<$^X> X<$EXECUTABLE_NAME>
964 The name used to execute the current copy of Perl, from C's
965 C<argv[0]> or (where supported) F</proc/self/exe>.
967 Depending on the host operating system, the value of C<$^X> may be
968 a relative or absolute pathname of the perl program file, or may
969 be the string used to invoke perl but not the pathname of the
970 perl program file. Also, most operating systems permit invoking
971 programs that are not in the PATH environment variable, so there
972 is no guarantee that the value of C<$^X> is in PATH. For VMS, the
973 value may or may not include a version number.
975 You usually can use the value of C<$^X> to re-invoke an independent
976 copy of the same perl that is currently running, e.g.,
978 @first_run = `$^X -le "print int rand 100 for 1..100"`;
980 But recall that not all operating systems support forking or
981 capturing of the output of commands, so this complex statement
984 It is not safe to use the value of C<$^X> as a path name of a file,
985 as some operating systems that have a mandatory suffix on
986 executable files do not require use of the suffix when invoking
987 a command. To convert the value of C<$^X> to a path name, use the
988 following statements:
990 # Build up a set of file names (not command names).
994 $this_perl .= $Config{_exe}
995 unless $this_perl =~ m/$Config{_exe}$/i;
998 Because many operating systems permit anyone with read access to
999 the Perl program file to make a copy of it, patch the copy, and
1000 then execute the copy, the security-conscious Perl programmer
1001 should take care to invoke the installed copy of perl, not the
1002 copy referenced by C<$^X>. The following statements accomplish
1003 this goal, and produce a pathname that can be invoked as a
1004 command or referenced as a file.
1007 my $secure_perl_path = $Config{perlpath};
1009 $secure_perl_path .= $Config{_exe}
1010 unless $secure_perl_path =~ m/$Config{_exe}$/i;
1015 =head2 Variables related to regular expressions
1017 Most of the special variables related to regular expressions are side
1018 effects. Perl sets these variables when it has a successful match, so
1019 you should check the match result before using them. For instance:
1021 if( /P(A)TT(ER)N/ ) {
1022 print "I found $1 and $2\n";
1025 These variables are read-only and dynamically-scoped, unless we note
1028 The dynamic nature of the regular expression variables means that
1029 their value is limited to the block that they are in, as demonstrated
1030 by this bit of code:
1032 my $outer = 'Wallace and Grommit';
1033 my $inner = 'Mutt and Jeff';
1035 my $pattern = qr/(\S+) and (\S+)/;
1037 sub show_n { print "\$1 is $1; \$2 is $2\n" }
1041 show_n() if $outer =~ m/$pattern/;
1044 show_n() if $inner =~ m/$pattern/;
1050 The output shows that while in the C<OUTER> block, the values of C<$1>
1051 and C<$2> are from the match against C<$outer>. Inside the C<INNER>
1052 block, the values of C<$1> and C<$2> are from the match against
1053 C<$inner>, but only until the end of the block (i.e. the dynamic
1054 scope). After the C<INNER> block completes, the values of C<$1> and
1055 C<$2> return to the values for the match against C<$outer> even though
1056 we have not made another match:
1058 $1 is Wallace; $2 is Grommit
1059 $1 is Mutt; $2 is Jeff
1060 $1 is Wallace; $2 is Grommit
1062 Due to an unfortunate accident of Perl's implementation, C<use
1063 English> imposes a considerable performance penalty on all regular
1064 expression matches in a program because it uses the C<$`>, C<$&>, and
1065 C<$'>, regardless of whether they occur in the scope of C<use
1066 English>. For that reason, saying C<use English> in libraries is
1067 strongly discouraged unless you import it without the match variables:
1069 use English '-no_match_vars'
1071 The C<Devel::NYTProf> and C<Devel::FindAmpersand>
1072 modules can help you find uses of these
1073 problematic match variables in your code.
1075 Since Perl 5.10, you can use the C</p> match operator flag and the
1076 C<${^PREMATCH}>, C<${^MATCH}>, and C<${^POSTMATCH}> variables instead
1077 so you only suffer the performance penalties.
1081 =item $<I<digits>> ($1, $2, ...)
1084 Contains the subpattern from the corresponding set of capturing
1085 parentheses from the last successful pattern match, not counting patterns
1086 matched in nested blocks that have been exited already.
1088 These variables are read-only and dynamically-scoped.
1090 Mnemonic: like \digits.
1097 The string matched by the last successful pattern match (not counting
1098 any matches hidden within a BLOCK or C<eval()> enclosed by the current
1101 The use of this variable anywhere in a program imposes a considerable
1102 performance penalty on all regular expression matches. To avoid this
1103 penalty, you can extract the same substring by using L</@->. Starting
1104 with Perl 5.10, you can use the </p> match flag and the C<${^MATCH}>
1105 variable to do the same thing for particular match operations.
1107 This variable is read-only and dynamically-scoped.
1109 Mnemonic: like C<&> in some editors.
1114 This is similar to C<$&> (C<$MATCH>) except that it does not incur the
1115 performance penalty associated with that variable, and is only guaranteed
1116 to return a defined value when the pattern was compiled or executed with
1119 This variable was added in Perl 5.10.
1121 This variable is read-only and dynamically-scoped.
1126 X<$`> X<$PREMATCH> X<${^PREMATCH}>
1128 The string preceding whatever was matched by the last successful
1129 pattern match, not counting any matches hidden within a BLOCK or C<eval>
1130 enclosed by the current BLOCK.
1132 The use of this variable anywhere in a program imposes a considerable
1133 performance penalty on all regular expression matches. To avoid this
1134 penalty, you can extract the same substring by using L</@->. Starting
1135 with Perl 5.10, you can use the </p> match flag and the
1136 C<${^PREMATCH}> variable to do the same thing for particular match
1139 This variable is read-only and dynamically-scoped.
1141 Mnemonic: C<`> often precedes a quoted string.
1144 X<$`> X<${^PREMATCH}>
1146 This is similar to C<$`> ($PREMATCH) except that it does not incur the
1147 performance penalty associated with that variable, and is only guaranteed
1148 to return a defined value when the pattern was compiled or executed with
1151 This variable was added in Perl 5.10
1153 This variable is read-only and dynamically-scoped.
1158 X<$'> X<$POSTMATCH> X<${^POSTMATCH}> X<@->
1160 The string following whatever was matched by the last successful
1161 pattern match (not counting any matches hidden within a BLOCK or C<eval()>
1162 enclosed by the current BLOCK). Example:
1164 local $_ = 'abcdefghi';
1166 print "$`:$&:$'\n"; # prints abc:def:ghi
1168 The use of this variable anywhere in a program imposes a considerable
1169 performance penalty on all regular expression matches.
1170 To avoid this penalty, you can extract the same substring by
1171 using L</@->. Starting with Perl 5.10, you can use the </p> match flag
1172 and the C<${^POSTMATCH}> variable to do the same thing for particular
1175 This variable is read-only and dynamically-scoped.
1177 Mnemonic: C<'> often follows a quoted string.
1180 X<${^POSTMATCH}> X<$'> X<$POSTMATCH>
1182 This is similar to C<$'> (C<$POSTMATCH>) except that it does not incur the
1183 performance penalty associated with that variable, and is only guaranteed
1184 to return a defined value when the pattern was compiled or executed with
1187 This variable was added in Perl 5.10.
1189 This variable is read-only and dynamically-scoped.
1191 =item $LAST_PAREN_MATCH
1194 X<$+> X<$LAST_PAREN_MATCH>
1196 The text matched by the last bracket of the last successful search pattern.
1197 This is useful if you don't know which one of a set of alternative patterns
1198 matched. For example:
1200 /Version: (.*)|Revision: (.*)/ && ($rev = $+);
1202 This variable is read-only and dynamically-scoped.
1204 Mnemonic: be positive and forward looking.
1206 =item $LAST_SUBMATCH_RESULT
1209 X<$^N> X<$LAST_SUBMATCH_RESULT>
1211 The text matched by the used group most-recently closed (i.e. the group
1212 with the rightmost closing parenthesis) of the last successful search
1215 This is primarily used inside C<(?{...})> blocks for examining text
1216 recently matched. For example, to effectively capture text to a variable
1217 (in addition to C<$1>, C<$2>, etc.), replace C<(...)> with
1219 (?:(...)(?{ $var = $^N }))
1221 By setting and then using C<$var> in this way relieves you from having to
1222 worry about exactly which numbered set of parentheses they are.
1224 This variable was added in Perl 5.8.
1226 Mnemonic: the (possibly) Nested parenthesis that most recently closed.
1228 =item @LAST_MATCH_END
1231 X<@+> X<@LAST_MATCH_END>
1233 This array holds the offsets of the ends of the last successful
1234 submatches in the currently active dynamic scope. C<$+[0]> is
1235 the offset into the string of the end of the entire match. This
1236 is the same value as what the C<pos> function returns when called
1237 on the variable that was matched against. The I<n>th element
1238 of this array holds the offset of the I<n>th submatch, so
1239 C<$+[1]> is the offset past where C<$1> ends, C<$+[2]> the offset
1240 past where C<$2> ends, and so on. You can use C<$#+> to determine
1241 how many subgroups were in the last successful match. See the
1242 examples given for the C<@-> variable.
1244 This variable was added in Perl 5.6.
1246 =item %LAST_PAREN_MATCH
1249 X<%+> X<%LAST_PAREN_MATCH>
1251 Similar to C<@+>, the C<%+> hash allows access to the named capture
1252 buffers, should they exist, in the last successful match in the
1253 currently active dynamic scope.
1255 For example, C<$+{foo}> is equivalent to C<$1> after the following match:
1257 'foo' =~ /(?<foo>foo)/;
1259 The keys of the C<%+> hash list only the names of buffers that have
1260 captured (and that are thus associated to defined values).
1262 The underlying behaviour of C<%+> is provided by the
1263 L<Tie::Hash::NamedCapture> module.
1265 B<Note:> C<%-> and C<%+> are tied views into a common internal hash
1266 associated with the last successful regular expression. Therefore mixing
1267 iterative access to them via C<each> may have unpredictable results.
1268 Likewise, if the last successful match changes, then the results may be
1271 This variable was added in Perl 5.10.
1273 This variable is read-only and dynamically-scoped.
1275 =item @LAST_MATCH_START
1278 X<@-> X<@LAST_MATCH_START>
1280 C<$-[0]> is the offset of the start of the last successful match.
1281 C<$-[>I<n>C<]> is the offset of the start of the substring matched by
1282 I<n>-th subpattern, or undef if the subpattern did not match.
1284 Thus, after a match against C<$_>, C<$&> coincides with C<substr $_, $-[0],
1285 $+[0] - $-[0]>. Similarly, $I<n> coincides with C<substr $_, $-[n],
1286 $+[n] - $-[n]> if C<$-[n]> is defined, and $+ coincides with
1287 C<substr $_, $-[$#-], $+[$#-] - $-[$#-]>. One can use C<$#-> to find the last
1288 matched subgroup in the last successful match. Contrast with
1289 C<$#+>, the number of subgroups in the regular expression. Compare
1292 This array holds the offsets of the beginnings of the last
1293 successful submatches in the currently active dynamic scope.
1294 C<$-[0]> is the offset into the string of the beginning of the
1295 entire match. The I<n>th element of this array holds the offset
1296 of the I<n>th submatch, so C<$-[1]> is the offset where C<$1>
1297 begins, C<$-[2]> the offset where C<$2> begins, and so on.
1299 After a match against some variable C<$var>:
1303 =item C<$`> is the same as C<substr($var, 0, $-[0])>
1305 =item C<$&> is the same as C<substr($var, $-[0], $+[0] - $-[0])>
1307 =item C<$'> is the same as C<substr($var, $+[0])>
1309 =item C<$1> is the same as C<substr($var, $-[1], $+[1] - $-[1])>
1311 =item C<$2> is the same as C<substr($var, $-[2], $+[2] - $-[2])>
1313 =item C<$3> is the same as C<substr($var, $-[3], $+[3] - $-[3])>
1317 This variable was added in Perl 5.6.
1319 =item %LAST_MATCH_START
1322 X<%-> X<%LAST_MATCH_START>
1324 Similar to C<%+>, this variable allows access to the named capture groups
1325 in the last successful match in the currently active dynamic scope. To
1326 each capture group name found in the regular expression, it associates a
1327 reference to an array containing the list of values captured by all
1328 buffers with that name (should there be several of them), in the order
1333 if ('1234' =~ /(?<A>1)(?<B>2)(?<A>3)(?<B>4)/) {
1334 foreach my $bufname (sort keys %-) {
1335 my $ary = $-{$bufname};
1336 foreach my $idx (0..$#$ary) {
1337 print "\$-{$bufname}[$idx] : ",
1338 (defined($ary->[$idx]) ? "'$ary->[$idx]'" : "undef"),
1351 The keys of the C<%-> hash correspond to all buffer names found in
1352 the regular expression.
1354 The behaviour of C<%-> is implemented via the
1355 L<Tie::Hash::NamedCapture> module.
1357 B<Note:> C<%-> and C<%+> are tied views into a common internal hash
1358 associated with the last successful regular expression. Therefore mixing
1359 iterative access to them via C<each> may have unpredictable results.
1360 Likewise, if the last successful match changes, then the results may be
1363 This variable was added in Perl 5.10
1365 This variable is read-only and dynamically-scoped.
1367 =item $LAST_REGEXP_CODE_RESULT
1370 X<$^R> X<$LAST_REGEXP_CODE_RESULT>
1372 The result of evaluation of the last successful C<(?{ code })>
1373 regular expression assertion (see L<perlre>). May be written to.
1375 This variable was added in Perl 5.005.
1377 =item ${^RE_DEBUG_FLAGS}
1378 X<${^RE_DEBUG_FLAGS}>
1380 The current value of the regex debugging flags. Set to 0 for no debug output
1381 even when the C<re 'debug'> module is loaded. See L<re> for details.
1383 This variable was added in Perl 5.10.
1385 =item ${^RE_TRIE_MAXBUF}
1386 X<${^RE_TRIE_MAXBUF}>
1388 Controls how certain regex optimisations are applied and how much memory they
1389 utilize. This value by default is 65536 which corresponds to a 512kB temporary
1390 cache. Set this to a higher value to trade memory for speed when matching
1391 large alternations. Set it to a lower value if you want the optimisations to
1392 be as conservative of memory as possible but still occur, and set it to a
1393 negative value to prevent the optimisation and conserve the most memory.
1394 Under normal situations this variable should be of no interest to you.
1396 This variable was added in Perl 5.10.
1400 =head2 Variables related to filehandles
1402 Variables that depend on the currently selected filehandle may be set
1403 by calling an appropriate object method on the C<IO::Handle> object,
1404 although this is less efficient than using the regular built-in
1405 variables. (Summary lines below for this contain the word HANDLE.)
1410 after which you may use either
1416 HANDLE->method(EXPR)
1418 Each method returns the old value of the C<IO::Handle> attribute. The
1419 methods each take an optional EXPR, which, if supplied, specifies the
1420 new value for the C<IO::Handle> attribute in question. If not
1421 supplied, most methods do nothing to the current value--except for
1422 C<autoflush()>, which will assume a 1 for you, just to be different.
1424 Because loading in the C<IO::Handle> class is an expensive operation,
1425 you should learn how to use the regular built-in variables.
1427 A few of these variables are considered "read-only". This means that
1428 if you try to assign to this variable, either directly or indirectly
1429 through a reference, you'll raise a run-time exception.
1431 You should be very careful when modifying the default values of most
1432 special variables described in this document. In most cases you want
1433 to localize these variables before changing them, since if you don't,
1434 the change may affect other modules which rely on the default values
1435 of the special variables that you have changed. This is one of the
1436 correct ways to read the whole file at once:
1438 open my $fh, "<", "foo" or die $!;
1439 local $/; # enable localized slurp mode
1440 my $content = <$fh>;
1443 But the following code is quite bad:
1445 open my $fh, "<", "foo" or die $!;
1446 undef $/; # enable slurp mode
1447 my $content = <$fh>;
1450 since some other module, may want to read data from some file in the
1451 default "line mode", so if the code we have just presented has been
1452 executed, the global value of C<$/> is now changed for any other code
1453 running inside the same Perl interpreter.
1455 Usually when a variable is localized you want to make sure that this
1456 change affects the shortest scope possible. So unless you are already
1457 inside some short C<{}> block, you should create one yourself. For
1461 open my $fh, "<", "foo" or die $!;
1468 Here is an example of how your own code can go broken:
1478 # do something with $_
1481 You probably expect this code to print the equivalent of
1485 but instead you get:
1489 Why? Because C<nasty_break()> modifies C<$\> without localizing it
1490 first. The value you set in C<nasty_break()> is still there when you
1491 return. The fix is to add C<local()> so the value doesn't leak out of
1496 It's easy to notice the problem in such a short example, but in more
1497 complicated code you are looking for trouble if you don't localize
1498 changes to the special variables.
1505 Contains the name of the current file when reading from C<< <> >>.
1510 The array C<@ARGV> contains the command-line arguments intended for
1511 the script. C<$#ARGV> is generally the number of arguments minus
1512 one, because C<$ARGV[0]> is the first argument, I<not> the program's
1513 command name itself. See L</$0> for the command name.
1518 The special filehandle that iterates over command-line filenames in
1519 C<@ARGV>. Usually written as the null filehandle in the angle operator
1520 C<< <> >>. Note that currently C<ARGV> only has its magical effect
1521 within the C<< <> >> operator; elsewhere it is just a plain filehandle
1522 corresponding to the last file opened by C<< <> >>. In particular,
1523 passing C<\*ARGV> as a parameter to a function that expects a filehandle
1524 may not cause your function to automatically read the contents of all the
1530 The special filehandle that points to the currently open output file
1531 when doing edit-in-place processing with B<-i>. Useful when you have
1532 to do a lot of inserting and don't want to keep modifying C<$_>. See
1533 L<perlrun> for the B<-i> switch.
1535 =item Handle->output_field_separator( EXPR )
1537 =item $OUTPUT_FIELD_SEPARATOR
1542 X<$,> X<$OFS> X<$OUTPUT_FIELD_SEPARATOR>
1544 The output field separator for the print operator. If defined, this
1545 value is printed between each of print's arguments. Default is C<undef>.
1547 Mnemonic: what is printed when there is a "," in your print statement.
1549 =item HANDLE->input_line_number( EXPR )
1551 =item $INPUT_LINE_NUMBER
1556 X<$.> X<$NR> X<$INPUT_LINE_NUMBER> X<line number>
1558 Current line number for the last filehandle accessed.
1560 Each filehandle in Perl counts the number of lines that have been read
1561 from it. (Depending on the value of C<$/>, Perl's idea of what
1562 constitutes a line may not match yours.) When a line is read from a
1563 filehandle (via C<readline()> or C<< <> >>), or when C<tell()> or
1564 C<seek()> is called on it, C<$.> becomes an alias to the line counter
1565 for that filehandle.
1567 You can adjust the counter by assigning to C<$.>, but this will not
1568 actually move the seek pointer. I<Localizing C<$.> will not localize
1569 the filehandle's line count>. Instead, it will localize perl's notion
1570 of which filehandle C<$.> is currently aliased to.
1572 C<$.> is reset when the filehandle is closed, but B<not> when an open
1573 filehandle is reopened without an intervening C<close()>. For more
1574 details, see L<perlop/"IE<sol>O Operators">. Because C<< <> >> never does
1575 an explicit close, line numbers increase across C<ARGV> files (but see
1576 examples in L<perlfunc/eof>).
1578 You can also use C<< HANDLE->input_line_number(EXPR) >> to access the
1579 line counter for a given filehandle without having to worry about
1580 which handle you last accessed.
1582 Mnemonic: many programs use "." to mean the current line number.
1584 =item HANDLE->input_record_separator( EXPR )
1586 =item $INPUT_RECORD_SEPARATOR
1591 X<$/> X<$RS> X<$INPUT_RECORD_SEPARATOR>
1593 The input record separator, newline by default. This influences Perl's
1594 idea of what a "line" is. Works like B<awk>'s RS variable, including
1595 treating empty lines as a terminator if set to the null string (an
1596 empty line cannot contain any spaces or tabs). You may set it to a
1597 multi-character string to match a multi-character terminator, or to
1598 C<undef> to read through the end of file. Setting it to C<"\n\n">
1599 means something slightly different than setting to C<"">, if the file
1600 contains consecutive empty lines. Setting to C<""> will treat two or
1601 more consecutive empty lines as a single empty line. Setting to
1602 C<"\n\n"> will blindly assume that the next input character belongs to
1603 the next paragraph, even if it's a newline.
1605 local $/; # enable "slurp" mode
1606 local $_ = <FH>; # whole file now here
1609 Remember: the value of C<$/> is a string, not a regex. B<awk> has to
1610 be better for something. :-)
1612 Setting C<$/> to a reference to an integer, scalar containing an
1613 integer, or scalar that's convertible to an integer will attempt to
1614 read records instead of lines, with the maximum record size being the
1615 referenced integer. So this:
1617 local $/ = \32768; # or \"32768", or \$var_containing_32768
1618 open my $fh, "<", $myfile or die $!;
1621 will read a record of no more than 32768 bytes from FILE. If you're
1622 not reading from a record-oriented file (or your OS doesn't have
1623 record-oriented files), then you'll likely get a full chunk of data
1624 with every read. If a record is larger than the record size you've
1625 set, you'll get the record back in pieces. Trying to set the record
1626 size to zero or less will cause reading in the (rest of the) whole file.
1628 On VMS, record reads are done with the equivalent of C<sysread>,
1629 so it's best not to mix record and non-record reads on the same
1630 file. (This is unlikely to be a problem, because any file you'd
1631 want to read in record mode is probably unusable in line mode.)
1632 Non-VMS systems do normal I/O, so it's safe to mix record and
1633 non-record reads of a file.
1635 See also L<perlport/"Newlines">. Also see L</$.>.
1637 Mnemonic: / delimits line boundaries when quoting poetry.
1639 =item Handle->output_record_separator( EXPR )
1641 =item $OUTPUT_RECORD_SEPARATOR
1646 X<$\> X<$ORS> X<$OUTPUT_RECORD_SEPARATOR>
1648 The output record separator for the print operator. If defined, this
1649 value is printed after the last of print's arguments. Default is C<undef>.
1651 Mnemonic: you set C<$\> instead of adding "\n" at the end of the print.
1652 Also, it's just like C<$/>, but it's what you get "back" from Perl.
1654 =item HANDLE->autoflush( EXPR )
1656 =item $OUTPUT_AUTOFLUSH
1659 X<$|> X<autoflush> X<flush> X<$OUTPUT_AUTOFLUSH>
1661 If set to nonzero, forces a flush right away and after every write or
1662 print on the currently selected output channel. Default is 0
1663 (regardless of whether the channel is really buffered by the system or
1664 not; C<$|> tells you only whether you've asked Perl explicitly to
1665 flush after each write). STDOUT will typically be line buffered if
1666 output is to the terminal and block buffered otherwise. Setting this
1667 variable is useful primarily when you are outputting to a pipe or
1668 socket, such as when you are running a Perl program under B<rsh> and
1669 want to see the output as it's happening. This has no effect on input
1670 buffering. See L<perlfunc/getc> for that. See L<perlfunc/select> on
1671 how to select the output channel. See also L<IO::Handle>.
1673 Mnemonic: when you want your pipes to be piping hot.
1677 =head3 Variables related to formats
1679 The special variables for formats are a subset of those for
1680 filehandles. See L<perlform> for more information about Perl's
1688 X<$^A> X<$ACCUMULATOR>
1690 The current value of the C<write()> accumulator for C<format()> lines.
1691 A format contains C<formline()> calls that put their result into
1692 C<$^A>. After calling its format, C<write()> prints out the contents
1693 of C<$^A> and empties. So you never really see the contents of C<$^A>
1694 unless you call C<formline()> yourself and then look at it. See
1695 L<perlform> and L<perlfunc/"formline PICTURE,LIST">.
1697 =item HANDLE->format_formfeed(EXPR)
1699 =item $FORMAT_FORMFEED
1702 X<$^L> X<$FORMAT_FORMFEED>
1704 What formats output as a form feed. The default is C<\f>.
1706 =item HANDLE->format_page_number(EXPR)
1708 =item $FORMAT_PAGE_NUMBER
1711 X<$%> X<$FORMAT_PAGE_NUMBER>
1713 The current page number of the currently selected output channel.
1715 Mnemonic: C<%> is page number in B<nroff>.
1717 =item HANDLE->format_lines_left(EXPR)
1719 =item $FORMAT_LINES_LEFT
1722 X<$-> X<$FORMAT_LINES_LEFT>
1724 The number of lines left on the page of the currently selected output
1727 Mnemonic: lines_on_page - lines_printed.
1729 =item Handle->format_line_break_characters EXPR
1731 =item $FORMAT_LINE_BREAK_CHARACTERS
1734 X<$:> X<FORMAT_LINE_BREAK_CHARACTERS>
1736 The current set of characters after which a string may be broken to
1737 fill continuation fields (starting with C<^>) in a format. The default is
1738 S<" \n-">, to break on a space, newline, or a hyphen.
1740 Mnemonic: a "colon" in poetry is a part of a line.
1742 =item HANDLE->format_lines_per_page(EXPR)
1744 =item $FORMAT_LINES_PER_PAGE
1747 X<$=> X<$FORMAT_LINES_PER_PAGE>
1749 The current page length (printable lines) of the currently selected
1750 output channel. The default is 60.
1752 Mnemonic: = has horizontal lines.
1754 =item HANDLE->format_top_name(EXPR)
1756 =item $FORMAT_TOP_NAME
1759 X<$^> X<$FORMAT_TOP_NAME>
1761 The name of the current top-of-page format for the currently selected
1762 output channel. The default is the name of the filehandle with C<_TOP>
1763 appended. For example, the default format top name for the C<STDOUT>
1764 filehanlde is C<STDOUT_TOP>.
1766 Mnemonic: points to top of page.
1768 =item HANDLE->format_name(EXPR)
1773 X<$~> X<$FORMAT_NAME>
1775 The name of the current report format for the currently selected
1776 output channel. The default format name is the same as the filehandle
1777 name. For example, the default format name for the C<STDOUT>
1778 filehandle is just C<STDOUT>.
1780 Mnemonic: brother to C<$^>.
1784 =head2 Error Variables
1785 X<error> X<exception>
1787 The variables C<$@>, C<$!>, C<$^E>, and C<$?> contain information
1788 about different types of error conditions that may appear during
1789 execution of a Perl program. The variables are shown ordered by
1790 the "distance" between the subsystem which reported the error and
1791 the Perl process. They correspond to errors detected by the Perl
1792 interpreter, C library, operating system, or an external program,
1795 To illustrate the differences between these variables, consider the
1796 following Perl expression, which uses a single-quoted string. After
1797 execution of this statement, perl may have set all four special error
1801 open my $pipe, "/cdrom/install |" or die $!;
1803 close $pipe or die "bad pipe: $?, $!";
1806 When perl executes the C<eval()> expression, it translates the
1807 C<open()>, C<< <PIPE> >>, and C<close> calls in the C run-time library
1808 and thence to the operating system kernel. perl sets C<$!> to
1809 the C library's C<errno> if one of these calls fails.
1811 C<$@> is set if the string to be C<eval>-ed did not compile (this may
1812 happen if C<open> or C<close> were imported with bad prototypes), or
1813 if Perl code executed during evaluation C<die()>d. In these cases the
1814 value of C<$@> is the compile error, or the argument to C<die> (which
1815 will interpolate C<$!> and C<$?>). (See also L<Fatal>, though.)
1817 Under a few operating systems, C<$^E> may contain a more verbose error
1818 indicator, such as in this case, "CDROM tray not closed." Systems that
1819 do not support extended error messages leave C<$^E> the same as C<$!>.
1821 Finally, C<$?> may be set to non-0 value if the external program
1822 F</cdrom/install> fails. The upper eight bits reflect specific error
1823 conditions encountered by the program (the program's C<exit()> value).
1824 The lower eight bits reflect mode of failure, like signal death and
1825 core dump information. See L<wait(2)> for details. In contrast to
1826 C<$!> and C<$^E>, which are set only if error condition is detected,
1827 the variable C<$?> is set on each C<wait> or pipe C<close>,
1828 overwriting the old value. This is more like C<$@>, which on every
1829 C<eval()> is always set on failure and cleared on success.
1831 For more details, see the individual descriptions at C<$@>, C<$!>,
1836 =item ${^CHILD_ERROR_NATIVE}
1837 X<$^CHILD_ERROR_NATIVE>
1839 The native status returned by the last pipe close, backtick (C<``>)
1840 command, successful call to C<wait()> or C<waitpid()>, or from the
1841 C<system()> operator. On POSIX-like systems this value can be decoded
1842 with the WIFEXITED, WEXITSTATUS, WIFSIGNALED, WTERMSIG, WIFSTOPPED,
1843 WSTOPSIG and WIFCONTINUED functions provided by the L<POSIX> module.
1845 Under VMS this reflects the actual VMS exit status; i.e. it is the
1846 same as C<$?> when the pragma C<use vmsish 'status'> is in effect.
1848 This variable was added in Perl 5.8.9.
1850 =item $EXTENDED_OS_ERROR
1853 X<$^E> X<$EXTENDED_OS_ERROR>
1855 Error information specific to the current operating system. At the
1856 moment, this differs from C<$!> under only VMS, OS/2, and Win32 (and
1857 for MacPerl). On all other platforms, C<$^E> is always just the same
1860 Under VMS, C<$^E> provides the VMS status value from the last system
1861 error. This is more specific information about the last system error
1862 than that provided by C<$!>. This is particularly important when C<$!>
1863 is set to B<EVMSERR>.
1865 Under OS/2, C<$^E> is set to the error code of the last call to OS/2
1866 API either via CRT, or directly from perl.
1868 Under Win32, C<$^E> always returns the last error information reported
1869 by the Win32 call C<GetLastError()> which describes the last error
1870 from within the Win32 API. Most Win32-specific code will report errors
1871 via C<$^E>. ANSI C and Unix-like calls set C<errno> and so most
1872 portable Perl code will report errors via C<$!>.
1874 Caveats mentioned in the description of C<$!> generally apply to
1877 This variable was added in Perl 5.003.
1879 Mnemonic: Extra error explanation.
1881 =item $EXCEPTIONS_BEING_CAUGHT
1884 X<$^S> X<$EXCEPTIONS_BEING_CAUGHT>
1886 Current state of the interpreter.
1889 --------- -------------------
1890 undef Parsing module/eval
1891 true (1) Executing an eval
1894 The first state may happen in C<$SIG{__DIE__}> and C<$SIG{__WARN__}>
1897 This variable was added in Perl 5.004.
1904 The current value of the warning switch, initially true if B<-w> was
1905 used, false otherwise, but directly modifiable.
1907 See also L<warnings>.
1909 Mnemonic: related to the B<-w> switch.
1911 =item ${^WARNING_BITS}
1914 The current set of warning checks enabled by the C<use warnings> pragma.
1915 See the documentation of C<warnings> for more details.
1917 This variable was added in Perl 5.10.
1924 X<$!> X<$ERRNO> X<$OS_ERROR>
1926 When referenced, C<$!> retrieves the current value
1927 of the C C<errno> integer variable.
1928 If C<$!> is assigned a numerical value, that value is stored in C<errno>.
1929 When referenced as a string, C<$!> yields the system error string
1930 corresponding to C<errno>.
1932 Many system or library calls set C<errno> if they fail,
1933 to indicate the cause of failure. They usually do B<not>
1934 set C<errno> to zero if they succeed. This means C<errno>,
1935 hence C<$!>, is meaningful only I<immediately> after a B<failure>:
1937 if (open my $fh, "<", $filename) {
1938 # Here $! is meaningless.
1942 # ONLY here is $! meaningful.
1944 # Already here $! might be meaningless.
1946 # Since here we might have either success or failure,
1947 # $! is meaningless.
1949 Here, I<meaningless> means that C<$!> may be unrelated to the outcome
1950 of the C<open()> operator. Assignment to C<$!> is similarly ephemeral.
1951 It can be used immediately before invoking the C<die()> operator,
1952 to set the exit value, or to inspect the system error string
1953 corresponding to error I<n>, or to restore C<$!> to a meaningful state.
1955 Mnemonic: What just went bang?
1962 X<%!> X<%OS_ERROR> X<%ERRNO>
1964 Each element of C<%!> has a true value only if C<$!> is set to that
1965 value. For example, C<$!{ENOENT}> is true if and only if the current
1966 value of C<$!> is C<ENOENT>; that is, if the most recent error was "No
1967 such file or directory" (or its moral equivalent: not all operating
1968 systems give that exact error, and certainly not all languages). To
1969 check if a particular key is meaningful on your system, use C<exists
1970 $!{the_key}>; for a list of legal keys, use C<keys %!>. See L<Errno>
1971 for more information, and also see L</$!>.
1973 This variable was added in Perl 5.005.
1978 X<$?> X<$CHILD_ERROR>
1980 The status returned by the last pipe close, backtick (C<``>) command,
1981 successful call to C<wait()> or C<waitpid()>, or from the C<system()>
1982 operator. This is just the 16-bit status word returned by the
1983 traditional Unix C<wait()> system call (or else is made up to look
1984 like it). Thus, the exit value of the subprocess is really (C<<< $? >>
1985 8 >>>), and C<$? & 127> gives which signal, if any, the process died
1986 from, and C<$? & 128> reports whether there was a core dump.
1988 Additionally, if the C<h_errno> variable is supported in C, its value
1989 is returned via C<$?> if any C<gethost*()> function fails.
1991 If you have installed a signal handler for C<SIGCHLD>, the
1992 value of C<$?> will usually be wrong outside that handler.
1994 Inside an C<END> subroutine C<$?> contains the value that is going to be
1995 given to C<exit()>. You can modify C<$?> in an C<END> subroutine to
1996 change the exit status of your program. For example:
1999 $? = 1 if $? == 255; # die would make it 255
2002 Under VMS, the pragma C<use vmsish 'status'> makes C<$?> reflect the
2003 actual VMS exit status, instead of the default emulation of POSIX
2004 status; see L<perlvms/$?> for details.
2006 Mnemonic: similar to B<sh> and B<ksh>.
2011 X<$@> X<$EVAL_ERROR>
2013 The Perl syntax error message from the last C<eval()> operator. If C<$@> is
2014 the null string, the last C<eval()> parsed and executed correctly
2015 (although the operations you invoked may have failed in the normal
2018 Warning messages are not collected in this variable. You can, however,
2019 set up a routine to process warnings by setting C<$SIG{__WARN__}> as
2020 described in L</%SIG>.
2022 Mnemonic: Where was the syntax error "at"?
2026 =head2 Deprecated and removed variables
2028 Deprecating a variable announces the intent of the perl maintainers to
2029 eventually remove the variable from the language. It may still be
2030 available despite its status. Using a deprecated variable triggers
2033 Once a variable is removed, its use triggers an error telling you
2034 the variable is unsupported.
2036 See L<perldiag> for details about error messages.
2045 C<$#> was a variable that could be used to format printed numbers.
2046 After a deprecation cycle, its magic was removed in Perl 5.10 and
2047 using it now triggers a warning: C<$# is no longer supported>.
2049 This is not the sigil you use in front of an array name to get the
2050 last index, like C<$#array>. That's still how you get the last index
2051 of an array in Perl. The two have nothing to do with each other.
2053 Deprecated in Perl 5.
2055 Removed in Perl 5.10.
2060 C<$*> was a variable that you could use to enable multiline matching.
2061 After a deprecation cycle, its magic was removed in Perl 5.10.
2062 Using it now triggers a warning: C<$* is no longer supported>.
2063 You should use the C</s> and C</m> regexp modifiers instead.
2065 Deprecated in Perl 5.
2067 Removed in Perl 5.10.
2072 X<$[> X<$ARRAY_BASE>
2074 This variable stores the index of the first element in an array, and
2075 of the first character in a substring. The default is 0, but you could
2076 theoretically set it to 1 to make Perl behave more like B<awk> (or Fortran)
2077 when subscripting and when evaluating the index() and substr() functions.
2079 As of release 5 of Perl, assignment to C<$[> is treated as a compiler
2080 directive, and cannot influence the behavior of any other file.
2081 (That's why you can only assign compile-time constants to it.)
2082 Its use is highly discouraged.
2084 Prior to Perl 5.10, assignment to C<$[> could be seen from outer lexical
2085 scopes in the same file, unlike other compile-time directives (such as
2086 L<strict>). Using local() on it would bind its value strictly to a lexical
2087 block. Now it is always lexically scoped.
2089 Mnemonic: [ begins subscripts.
2091 Deprecated in Perl 5.12.
2093 =item $OLD_PERL_VERSION
2096 X<$]> X<$OLD_PERL_VERSION>
2098 See L</$^V> for a more modern representation of the Perl version that allows
2099 accurate string comparisons.
2101 The version + patchlevel / 1000 of the Perl interpreter. This variable
2102 can be used to determine whether the Perl interpreter executing a
2103 script is in the right range of versions:
2105 warn "No checksumming!\n" if $] < 3.019;
2107 The floating point representation can sometimes lead to inaccurate
2108 numeric comparisons.
2110 See also the documentation of C<use VERSION> and C<require VERSION>
2111 for a convenient way to fail if the running Perl interpreter is too old.
2113 Mnemonic: Is this version of perl in the right bracket?
2115 Deprecated in Perl 5.6.