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>.
15 A Unicode letter that is not ASCII is not considered to be a letter
16 unless S<C<"use utf8">> is in effect, and somewhat more complicated
17 rules apply; see L<perldata/Identifier parsing> for details.
19 Perl variable names may also be a sequence of digits, a single
20 punctuation character, or the two-character sequence: C<^> (caret or
21 CIRCUMFLEX ACCENT) followed by any one of the characters C<[][A-Z^_?\]>.
22 These names are all reserved for
23 special uses by Perl; for example, the all-digits names are used
24 to hold data captured by backreferences after a regular expression
27 Since Perl v5.6.0, Perl variable names may also be alphanumeric strings
28 preceded by a caret. These must all be written using the demarcated
29 variable form using curly braces such as C<${^Foo}>;
30 the braces are B<not> optional. C<${^Foo}> denotes the scalar variable
31 whose name is considered to be a control-C<F> followed by two C<o>'s.
32 (See L<perldata/"Demarcated variable names using braces"> for more
33 information on this form of spelling a variable name or specifying
34 access to an element of an array or a hash).
36 reserved for future special uses by Perl, except for the ones that
37 begin with C<^_> (caret-underscore). No
38 name that begins with C<^_> will acquire a special
39 meaning in any future version of Perl; such names may therefore be
40 used safely in programs. C<$^_> itself, however, I<is> reserved.
42 Note that you also B<must> use the demarcated form to access subscripts
43 of variables of this type when interpolating, for instance to access the
44 first element of the C<@{^CAPTURE}> variable inside of a double quoted
45 string you would write C<"${^CAPTURE[0]}"> and NOT C<"${^CAPTURE}[0]">
46 which would mean to reference a scalar variable named C<${^CAPTURE}> and
47 not index 0 of the magic C<@{^CAPTURE}> array which is populated by the
50 Perl identifiers that begin with digits or
51 punctuation characters are exempt from the effects of the C<package>
52 declaration and are always forced to be in package C<main>; they are
53 also exempt from C<strict 'vars'> errors. A few other names are also
62 In particular, the special C<${^_XYZ}> variables are always taken
63 to be in package C<main>, regardless of any C<package> declarations
66 =head1 SPECIAL VARIABLES
68 The following names have special meaning to Perl. Most punctuation
69 names have reasonable mnemonics, or analogs in the shells.
70 Nevertheless, if you wish to use long variable names, you need only say:
74 at the top of your program. This aliases all the short names to the long
75 names in the current package. Some even have medium names, generally
76 borrowed from B<awk>. For more info, please see L<English>.
78 Before you continue, note the sort order for variables. In general, we
79 first list the variables in case-insensitive, almost-lexigraphical
80 order (ignoring the C<{> or C<^> preceding words, as in C<${^UNICODE}>
81 or C<$^T>), although C<$_> and C<@_> move up to the top of the pile.
82 For variables with the same identifier, we list it in order of scalar,
83 array, hash, and bareword.
85 =head2 General Variables
94 The default input and pattern-searching space. The following pairs are
97 while (<>) {...} # equivalent only in while!
98 while (defined($_ = <>)) {...}
109 Here are the places where Perl will assume C<$_> even if you don't use it:
115 The following functions use C<$_> as a default argument:
117 abs, alarm, chomp, chop, chr, chroot,
118 cos, defined, eval, evalbytes, exp, fc, glob, hex, int, lc,
119 lcfirst, length, log, lstat, mkdir, oct, ord, pos, print, printf,
120 quotemeta, readlink, readpipe, ref, require, reverse (in scalar context only),
121 rmdir, say, sin, split (for its second
122 argument), sqrt, stat, study, uc, ucfirst,
127 All file tests (C<-f>, C<-d>) except for C<-t>, which defaults to STDIN.
132 The pattern matching operations C<m//>, C<s///> and C<tr///> (aka C<y///>)
133 when used without an C<=~> operator.
137 The default iterator variable in a C<foreach> loop if no other
138 variable is supplied.
142 The implicit iterator variable in the C<grep()> and C<map()> functions.
146 The implicit variable of C<given()>.
150 The default place to put the next value or input record
151 when a C<< <FH> >>, C<readline>, C<readdir> or C<each>
152 operation's result is tested by itself as the sole criterion of a C<while>
153 test. Outside a C<while> test, this will not happen.
157 C<$_> is a global variable.
159 However, between perl v5.10.0 and v5.24.0, it could be used lexically by
160 writing C<my $_>. Making C<$_> refer to the global C<$_> in the same scope
161 was then possible with C<our $_>. This experimental feature was removed and is
162 now a fatal error, but you may encounter it in older code.
164 Mnemonic: underline is understood in certain operations.
171 Within a subroutine the array C<@_> contains the parameters passed to
172 that subroutine. Inside a subroutine, C<@_> is the default array for
173 the array operators C<pop> and C<shift>.
177 =item $LIST_SEPARATOR
180 X<$"> X<$LIST_SEPARATOR>
182 When an array or an array slice is interpolated into a double-quoted
183 string or a similar context such as C</.../>, its elements are
184 separated by this value. Default is a space. For example, this:
186 print "The array is: @array\n";
188 is equivalent to this:
190 print "The array is: " . join($", @array) . "\n";
192 Mnemonic: works in double-quoted context.
199 X<$$> X<$PID> X<$PROCESS_ID>
201 The process number of the Perl running this script. Though you I<can> set
202 this variable, doing so is generally discouraged, although it can be
203 invaluable for some testing purposes. It will be reset automatically
204 across C<fork()> calls.
206 Note for Linux and Debian GNU/kFreeBSD users: Before Perl v5.16.0 perl
207 would emulate POSIX semantics on Linux systems using LinuxThreads, a
208 partial implementation of POSIX Threads that has since been superseded
209 by the Native POSIX Thread Library (NPTL).
211 LinuxThreads is now obsolete on Linux, and caching C<getpid()>
212 like this made embedding perl unnecessarily complex (since you'd have
213 to manually update the value of $$), so now C<$$> and C<getppid()>
214 will always return the same values as the underlying C library.
216 Debian GNU/kFreeBSD systems also used LinuxThreads up until and
217 including the 6.0 release, but after that moved to FreeBSD thread
218 semantics, which are POSIX-like.
220 To see if your system is affected by this discrepancy check if
221 C<getconf GNU_LIBPTHREAD_VERSION | grep -q NPTL> returns a false
222 value. NTPL threads preserve the POSIX semantics.
224 Mnemonic: same as shells.
229 X<$0> X<$PROGRAM_NAME>
231 Contains the name of the program being executed.
233 On some (but not all) operating systems assigning to C<$0> modifies
234 the argument area that the C<ps> program sees. On some platforms you
235 may have to use special C<ps> options or a different C<ps> to see the
236 changes. Modifying the C<$0> is more useful as a way of indicating the
237 current program state than it is for hiding the program you're
240 Note that there are platform-specific limitations on the maximum
241 length of C<$0>. In the most extreme case it may be limited to the
242 space occupied by the original C<$0>.
244 In some platforms there may be arbitrary amount of padding, for
245 example space characters, after the modified name as shown by C<ps>.
246 In some platforms this padding may extend all the way to the original
247 length of the argument area, no matter what you do (this is the case
248 for example with Linux 2.2).
250 Note for BSD users: setting C<$0> does not completely remove "perl"
251 from the ps(1) output. For example, setting C<$0> to C<"foobar"> may
252 result in C<"perl: foobar (perl)"> (whether both the C<"perl: "> prefix
253 and the " (perl)" suffix are shown depends on your exact BSD variant
254 and version). This is an operating system feature, Perl cannot help it.
256 In multithreaded scripts Perl coordinates the threads so that any
257 thread may modify its copy of the C<$0> and the change becomes visible
258 to ps(1) (assuming the operating system plays along). Note that
259 the view of C<$0> the other threads have will not change since they
260 have their own copies of it.
262 If the program has been given to perl via the switches C<-e> or C<-E>,
263 C<$0> will contain the string C<"-e">.
265 On Linux as of perl v5.14.0 the legacy process name will be set with
266 C<prctl(2)>, in addition to altering the POSIX name via C<argv[0]> as
267 perl has done since version 4.000. Now system utilities that read the
268 legacy process name such as ps, top and killall will recognize the
269 name you set when assigning to C<$0>. The string you supply will be
270 cut off at 16 bytes, this is a limitation imposed by Linux.
272 Wide characters are invalid in C<$0> values. For historical reasons,
273 though, Perl accepts them and encodes them to UTF-8. When this
274 happens a wide-character warning is triggered.
276 Mnemonic: same as B<sh> and B<ksh>.
283 X<$(> X<$GID> X<$REAL_GROUP_ID>
285 The real gid of this process. If you are on a machine that supports
286 membership in multiple groups simultaneously, gives a space separated
287 list of groups you are in. The first number is the one returned by
288 C<getgid()>, and the subsequent ones by C<getgroups()>, one of which may be
289 the same as the first number.
291 However, a value assigned to C<$(> must be a single number used to
292 set the real gid. So the value given by C<$(> should I<not> be assigned
293 back to C<$(> without being forced numeric, such as by adding zero. Note
294 that this is different to the effective gid (C<$)>) which does take a
297 You can change both the real gid and the effective gid at the same
298 time by using C<POSIX::setgid()>. Changes
299 to C<$(> require a check to C<$!>
300 to detect any possible errors after an attempted change.
302 Mnemonic: parentheses are used to I<group> things. The real gid is the
303 group you I<left>, if you're running setgid.
305 =item $EFFECTIVE_GROUP_ID
310 X<$)> X<$EGID> X<$EFFECTIVE_GROUP_ID>
312 The effective gid of this process. If you are on a machine that
313 supports membership in multiple groups simultaneously, gives a space
314 separated list of groups you are in. The first number is the one
315 returned by C<getegid()>, and the subsequent ones by C<getgroups()>,
316 one of which may be the same as the first number.
318 Similarly, a value assigned to C<$)> must also be a space-separated
319 list of numbers. The first number sets the effective gid, and
320 the rest (if any) are passed to C<setgroups()>. To get the effect of an
321 empty list for C<setgroups()>, just repeat the new effective gid; that is,
322 to force an effective gid of 5 and an effectively empty C<setgroups()>
323 list, say C< $) = "5 5" >.
325 You can change both the effective gid and the real gid at the same
326 time by using C<POSIX::setgid()> (use only a single numeric argument).
327 Changes to C<$)> require a check to C<$!> to detect any possible errors
328 after an attempted change.
330 C<< $< >>, C<< $> >>, C<$(> and C<$)> can be set only on
331 machines that support the corresponding I<set[re][ug]id()> routine. C<$(>
332 and C<$)> can be swapped only on machines supporting C<setregid()>.
334 Mnemonic: parentheses are used to I<group> things. The effective gid
335 is the group that's I<right> for you, if you're running setgid.
342 X<< $< >> X<$UID> X<$REAL_USER_ID>
344 The real uid of this process. You can change both the real uid and the
345 effective uid at the same time by using C<POSIX::setuid()>. Since
346 changes to C<< $< >> require a system call, check C<$!> after a change
347 attempt to detect any possible errors.
349 Mnemonic: it's the uid you came I<from>, if you're running setuid.
351 =item $EFFECTIVE_USER_ID
356 X<< $> >> X<$EUID> X<$EFFECTIVE_USER_ID>
358 The effective uid of this process. For example:
360 $< = $>; # set real to effective uid
361 ($<,$>) = ($>,$<); # swap real and effective uids
363 You can change both the effective uid and the real uid at the same
364 time by using C<POSIX::setuid()>. Changes to C<< $> >> require a check
365 to C<$!> to detect any possible errors after an attempted change.
367 C<< $< >> and C<< $> >> can be swapped only on machines
368 supporting C<setreuid()>.
370 Mnemonic: it's the uid you went I<to>, if you're running setuid.
372 =item $SUBSCRIPT_SEPARATOR
377 X<$;> X<$SUBSEP> X<SUBSCRIPT_SEPARATOR>
379 The subscript separator for multidimensional array emulation. If you
380 refer to a hash element as
386 $foo{join($;, $x, $y, $z)}
390 @foo{$x,$y,$z} # a slice--note the @
394 ($foo{$x},$foo{$y},$foo{$z})
396 Default is "\034", the same as SUBSEP in B<awk>. If your keys contain
397 binary data there might not be any safe value for C<$;>.
399 Consider using "real" multidimensional arrays as described
402 Mnemonic: comma (the syntactic subscript separator) is a semi-semicolon.
409 Special package variables when using C<sort()>, see L<perlfunc/sort>.
410 Because of this specialness C<$a> and C<$b> don't need to be declared
411 (using C<use vars>, or C<our()>) even when using the C<strict 'vars'>
412 pragma. Don't lexicalize them with C<my $a> or C<my $b> if you want to
413 be able to use them in the C<sort()> comparison block or function.
418 The hash C<%ENV> contains your current environment. Setting a
419 value in C<ENV> changes the environment for any child processes
420 you subsequently C<fork()> off.
422 As of v5.18.0, both keys and values stored in C<%ENV> are stringified.
426 if( ref $ENV{'bar'} ) {
427 say "Pre 5.18.0 Behaviour";
429 say "Post 5.18.0 Behaviour";
432 Previously, only child processes received stringified values:
437 # Always printed 'non ref'
439 q/print ( ref $ENV{'bar'} ? 'ref' : 'non ref' ) /);
441 This happens because you can't really share arbitrary data structures with
444 =item $OLD_PERL_VERSION
447 X<$]> X<$OLD_PERL_VERSION>
449 The revision, version, and subversion of the Perl interpreter, represented
450 as a decimal of the form 5.XXXYYY, where XXX is the version / 1e3 and YYY
451 is the subversion / 1e6. For example, Perl v5.10.1 would be "5.010001".
453 This variable can be used to determine whether the Perl interpreter
454 executing a script is in the right range of versions:
456 warn "No PerlIO!\n" if "$]" < 5.008;
458 When comparing C<$]>, numeric comparison operators should be used, but the
459 variable should be stringified first to avoid issues where its original
460 numeric value is inaccurate.
462 See also the documentation of C<use VERSION> and C<require VERSION>
463 for a convenient way to fail if the running Perl interpreter is too old.
465 See L</$^V> for a representation of the Perl version as a L<version>
466 object, which allows more flexible string comparisons.
468 The main advantage of C<$]> over C<$^V> is that it works the same on any
469 version of Perl. The disadvantages are that it can't easily be compared
470 to versions in other formats (e.g. literal v-strings, "v1.2.3" or
471 version objects) and numeric comparisons are subject to the binary
472 floating point representation; it's good for numeric literal version
473 checks and bad for comparing to a variable that hasn't been
476 The C<$OLD_PERL_VERSION> form was added in Perl v5.20.0 for historical
477 reasons but its use is discouraged. (If your reason to use C<$]> is to
478 run code on old perls then referring to it as C<$OLD_PERL_VERSION> would
481 Mnemonic: Is this version of perl in the right bracket?
486 X<$^F> X<$SYSTEM_FD_MAX>
488 The maximum system file descriptor, ordinarily 2. System file
489 descriptors are passed to C<exec()>ed processes, while higher file
490 descriptors are not. Also, during an
491 C<open()>, system file descriptors are
492 preserved even if the C<open()> fails (ordinary file descriptors are
493 closed before the C<open()> is attempted). The close-on-exec
494 status of a file descriptor will be decided according to the value of
495 C<$^F> when the corresponding file, pipe, or socket was opened, not the
496 time of the C<exec()>.
501 The array C<@F> contains the fields of each line read in when autosplit
502 mode is turned on. See L<perlrun|perlrun/-a> for the B<-a> switch. This
503 array is package-specific, and must be declared or given a full package
504 name if not in package main when running under C<strict 'vars'>.
509 The array C<@INC> contains the list of places that the C<do EXPR>,
510 C<require>, or C<use> constructs look for their library files. It
511 initially consists of the arguments to any B<-I> command-line
512 switches, followed by the default Perl library, probably
513 F</usr/local/lib/perl>.
514 Prior to Perl 5.26, C<.> -which represents the current directory, was included
515 in C<@INC>; it has been removed. This change in behavior is documented
516 in L<C<PERL_USE_UNSAFE_INC>|perlrun/PERL_USE_UNSAFE_INC> and it is
517 not recommended that C<.> be re-added to C<@INC>.
518 If you need to modify C<@INC> at runtime, you should use the C<use lib> pragma
519 to get the machine-dependent library properly loaded as well:
521 use lib '/mypath/libdir/';
524 You can also insert hooks into the file inclusion system by putting Perl
525 code directly into C<@INC>. Those hooks may be subroutine references,
526 array references or blessed objects. See L<perlfunc/require> for details.
531 The hash C<%INC> contains entries for each filename included via the
532 C<do>, C<require>, or C<use> operators. The key is the filename
533 you specified (with module names converted to pathnames), and the
534 value is the location of the file found. The C<require>
535 operator uses this hash to determine whether a particular file has
536 already been included.
538 If the file was loaded via a hook (e.g. a subroutine reference, see
539 L<perlfunc/require> for a description of these hooks), this hook is
540 by default inserted into C<%INC> in place of a filename. Note, however,
541 that the hook may have set the C<%INC> entry by itself to provide some more
547 X<$^I> X<$INPLACE_EDIT>
549 The current value of the inplace-edit extension. Use C<undef> to disable
552 Mnemonic: value of B<-i> switch.
557 Each package contains a special array called C<@ISA> which contains a list
558 of that class's parent classes, if any. This array is simply a list of
559 scalars, each of which is a string that corresponds to a package name. The
560 array is examined when Perl does method resolution, which is covered in
563 To load packages while adding them to C<@ISA>, see the L<parent> pragma. The
564 discouraged L<base> pragma does this as well, but should not be used except
565 when compatibility with the discouraged L<fields> pragma is required.
570 By default, running out of memory is an untrappable, fatal error.
571 However, if suitably built, Perl can use the contents of C<$^M>
572 as an emergency memory pool after C<die()>ing. Suppose that your Perl
573 were compiled with C<-DPERL_EMERGENCY_SBRK> and used Perl's malloc.
576 $^M = 'a' x (1 << 16);
578 would allocate a 64K buffer for use in an emergency. See the
579 F<INSTALL> file in the Perl distribution for information on how to
580 add custom C compilation flags when compiling perl. To discourage casual
581 use of this advanced feature, there is no L<English|English> long name for
584 This variable was added in Perl 5.004.
591 The name of the operating system under which this copy of Perl was
592 built, as determined during the configuration process. For examples
593 see L<perlport/PLATFORMS>.
595 The value is identical to C<$Config{'osname'}>. See also L<Config>
596 and the B<-V> command-line switch documented in L<perlrun|perlrun/-V>.
598 In Windows platforms, C<$^O> is not very helpful: since it is always
599 C<MSWin32>, it doesn't tell the difference between
600 95/98/ME/NT/2000/XP/CE/.NET. Use C<Win32::GetOSName()> or
601 Win32::GetOSVersion() (see L<Win32> and L<perlport>) to distinguish
602 between the variants.
604 This variable was added in Perl 5.003.
609 The hash C<%SIG> contains signal handlers for signals. For example:
611 sub handler { # 1st argument is signal name
613 print "Caught a SIG$sig--shutting down\n";
618 $SIG{'INT'} = \&handler;
619 $SIG{'QUIT'} = \&handler;
621 $SIG{'INT'} = 'DEFAULT'; # restore default action
622 $SIG{'QUIT'} = 'IGNORE'; # ignore SIGQUIT
624 Using a value of C<'IGNORE'> usually has the effect of ignoring the
625 signal, except for the C<CHLD> signal. See L<perlipc> for more about
626 this special case. Using an empty string or C<undef> as the value has
627 the same effect as C<'DEFAULT'>.
629 Here are some other examples:
631 $SIG{"PIPE"} = "Plumber"; # assumes main::Plumber (not
633 $SIG{"PIPE"} = \&Plumber; # just fine; assume current
635 $SIG{"PIPE"} = *Plumber; # somewhat esoteric
636 $SIG{"PIPE"} = Plumber(); # oops, what did Plumber()
639 Be sure not to use a bareword as the name of a signal handler,
640 lest you inadvertently call it.
642 Using a string that doesn't correspond to any existing function or a
643 glob that doesn't contain a code slot is equivalent to C<'IGNORE'>,
644 but a warning is emitted when the handler is being called (the warning
645 is not emitted for the internal hooks described below).
647 If your system has the C<sigaction()> function then signal handlers
648 are installed using it. This means you get reliable signal handling.
650 The default delivery policy of signals changed in Perl v5.8.0 from
651 immediate (also known as "unsafe") to deferred, also known as "safe
652 signals". See L<perlipc> for more information.
654 Certain internal hooks can be also set using the C<%SIG> hash. The
655 routine indicated by C<$SIG{__WARN__}> is called when a warning
656 message is about to be printed. The warning message is passed as the
657 first argument. The presence of a C<__WARN__> hook causes the
658 ordinary printing of warnings to C<STDERR> to be suppressed. You can
659 use this to save warnings in a variable, or turn warnings into fatal
662 local $SIG{__WARN__} = sub { die $_[0] };
665 As the C<'IGNORE'> hook is not supported by C<__WARN__>, its effect is
666 the same as using C<'DEFAULT'>. You can disable warnings using the
669 local $SIG{__WARN__} = sub {};
671 The routine indicated by C<$SIG{__DIE__}> is called when a fatal
672 exception is about to be thrown. The error message is passed as the
673 first argument. When a C<__DIE__> hook routine returns, the exception
674 processing continues as it would have in the absence of the hook,
675 unless the hook routine itself exits via a C<goto &sub>, a loop exit,
676 or a C<die()>. The C<__DIE__> handler is explicitly disabled during
677 the call, so that you can die from a C<__DIE__> handler. Similarly
680 The C<$SIG{__DIE__}> hook is called even inside an C<eval()>. It was
681 never intended to happen this way, but an implementation glitch made
682 this possible. This used to be deprecated, as it allowed strange action
683 at a distance like rewriting a pending exception in C<$@>. Plans to
684 rectify this have been scrapped, as users found that rewriting a
685 pending exception is actually a useful feature, and not a bug.
687 The C<$SIG{__DIE__}> doesn't support C<'IGNORE'>; it has the same
688 effect as C<'DEFAULT'>.
690 C<__DIE__>/C<__WARN__> handlers are very special in one respect: they
691 may be called to report (probable) errors found by the parser. In such
692 a case the parser may be in inconsistent state, so any attempt to
693 evaluate Perl code from such a handler will probably result in a
694 segfault. This means that warnings or errors that result from parsing
695 Perl should be used with extreme caution, like this:
697 require Carp if defined $^S;
698 Carp::confess("Something wrong") if defined &Carp::confess;
699 die "Something wrong, but could not load Carp to give "
701 . "To see backtrace try starting Perl with -MCarp switch";
703 Here the first line will load C<Carp> I<unless> it is the parser who
704 called the handler. The second line will print backtrace and die if
705 C<Carp> was available. The third line will be executed only if C<Carp> was
708 Having to even think about the C<$^S> variable in your exception
709 handlers is simply wrong. C<$SIG{__DIE__}> as currently implemented
710 invites grievous and difficult to track down errors. Avoid it
711 and use an C<END{}> or CORE::GLOBAL::die override instead.
713 See L<perlfunc/die>, L<perlfunc/warn>, L<perlfunc/eval>, and
714 L<warnings> for additional information.
721 The time at which the program began running, in seconds since the
722 epoch (beginning of 1970). The values returned by the B<-M>, B<-A>,
723 and B<-C> filetests are based on this value.
728 X<$^V> X<$PERL_VERSION>
731 These are documented in the generated file lib/Config.pod. This looks
732 like as good a place as any to give notice that they are documented.
734 The revision, version, and subversion of the Perl interpreter,
735 represented as a L<version> object.
737 This variable first appeared in perl v5.6.0; earlier versions of perl
738 will see an undefined value. Before perl v5.10.0 C<$^V> was represented
739 as a v-string rather than a L<version> object.
741 C<$^V> can be used to determine whether the Perl interpreter executing
742 a script is in the right range of versions. For example:
744 warn "Hashes not randomized!\n" if !$^V or $^V lt v5.8.1
746 While version objects overload stringification, to portably convert
747 C<$^V> into its string representation, use C<sprintf()>'s C<"%vd">
748 conversion, which works for both v-strings or version objects:
750 printf "version is v%vd\n", $^V; # Perl's version
752 See the documentation of C<use VERSION> and C<require VERSION>
753 for a convenient way to fail if the running Perl interpreter is too old.
755 See also C<L</$]>> for a decimal representation of the Perl version.
757 The main advantage of C<$^V> over C<$]> is that, for Perl v5.10.0 or
758 later, it overloads operators, allowing easy comparison against other
759 version representations (e.g. decimal, literal v-string, "v1.2.3", or
760 objects). The disadvantage is that prior to v5.10.0, it was only a
761 literal v-string, which can't be easily printed or compared, whereas
762 the behavior of C<$]> is unchanged on all versions of Perl.
764 Mnemonic: use ^V for a version object.
766 =item $EXECUTABLE_NAME
769 X<$^X> X<$EXECUTABLE_NAME>
771 The name used to execute the current copy of Perl, from C's
772 C<argv[0]> or (where supported) F</proc/self/exe>.
774 Depending on the host operating system, the value of C<$^X> may be
775 a relative or absolute pathname of the perl program file, or may
776 be the string used to invoke perl but not the pathname of the
777 perl program file. Also, most operating systems permit invoking
778 programs that are not in the PATH environment variable, so there
779 is no guarantee that the value of C<$^X> is in PATH. For VMS, the
780 value may or may not include a version number.
782 You usually can use the value of C<$^X> to re-invoke an independent
783 copy of the same perl that is currently running, e.g.,
785 @first_run = `$^X -le "print int rand 100 for 1..100"`;
787 But recall that not all operating systems support forking or
788 capturing of the output of commands, so this complex statement
791 It is not safe to use the value of C<$^X> as a path name of a file,
792 as some operating systems that have a mandatory suffix on
793 executable files do not require use of the suffix when invoking
794 a command. To convert the value of C<$^X> to a path name, use the
795 following statements:
797 # Build up a set of file names (not command names).
801 $this_perl .= $Config{_exe}
802 unless $this_perl =~ m/$Config{_exe}$/i;
805 Because many operating systems permit anyone with read access to
806 the Perl program file to make a copy of it, patch the copy, and
807 then execute the copy, the security-conscious Perl programmer
808 should take care to invoke the installed copy of perl, not the
809 copy referenced by C<$^X>. The following statements accomplish
810 this goal, and produce a pathname that can be invoked as a
811 command or referenced as a file.
814 my $secure_perl_path = $Config{perlpath};
816 $secure_perl_path .= $Config{_exe}
817 unless $secure_perl_path =~ m/$Config{_exe}$/i;
822 =head2 Variables related to regular expressions
824 Most of the special variables related to regular expressions are side
825 effects. Perl sets these variables when it has a successful match, so
826 you should check the match result before using them. For instance:
828 if( /P(A)TT(ER)N/ ) {
829 print "I found $1 and $2\n";
832 These variables are read-only and dynamically-scoped, unless we note
835 The dynamic nature of the regular expression variables means that
836 their value is limited to the block that they are in, as demonstrated
839 my $outer = 'Wallace and Grommit';
840 my $inner = 'Mutt and Jeff';
842 my $pattern = qr/(\S+) and (\S+)/;
844 sub show_n { print "\$1 is $1; \$2 is $2\n" }
848 show_n() if $outer =~ m/$pattern/;
851 show_n() if $inner =~ m/$pattern/;
857 The output shows that while in the C<OUTER> block, the values of C<$1>
858 and C<$2> are from the match against C<$outer>. Inside the C<INNER>
859 block, the values of C<$1> and C<$2> are from the match against
860 C<$inner>, but only until the end of the block (i.e. the dynamic
861 scope). After the C<INNER> block completes, the values of C<$1> and
862 C<$2> return to the values for the match against C<$outer> even though
863 we have not made another match:
865 $1 is Wallace; $2 is Grommit
866 $1 is Mutt; $2 is Jeff
867 $1 is Wallace; $2 is Grommit
869 =head3 Performance issues
871 Traditionally in Perl, any use of any of the three variables C<$`>, C<$&>
872 or C<$'> (or their C<use English> equivalents) anywhere in the code, caused
873 all subsequent successful pattern matches to make a copy of the matched
874 string, in case the code might subsequently access one of those variables.
875 This imposed a considerable performance penalty across the whole program,
876 so generally the use of these variables has been discouraged.
878 In Perl 5.6.0 the C<@-> and C<@+> dynamic arrays were introduced that
879 supply the indices of successful matches. So you could for example do
884 print $`, $&, $'; # bad: performance hit
886 print # good: no performance hit
887 substr($str, 0, $-[0]),
888 substr($str, $-[0], $+[0]-$-[0]),
891 In Perl 5.10.0 the C</p> match operator flag and the C<${^PREMATCH}>,
892 C<${^MATCH}>, and C<${^POSTMATCH}> variables were introduced, that allowed
893 you to suffer the penalties only on patterns marked with C</p>.
895 In Perl 5.18.0 onwards, perl started noting the presence of each of the
896 three variables separately, and only copied that part of the string
899 $`; $&; "abcdefgh" =~ /d/
901 perl would only copy the "abcd" part of the string. That could make a big
902 difference in something like
904 $str = 'x' x 1_000_000;
906 $str =~ /x/g # one char copied a million times, not a million chars
908 In Perl 5.20.0 a new copy-on-write system was enabled by default, which
909 finally fixes all performance issues with these three variables, and makes
910 them safe to use anywhere.
912 The C<Devel::NYTProf> and C<Devel::FindAmpersand> modules can help you
913 find uses of these problematic match variables in your code.
917 =item $<I<digits>> ($1, $2, ...)
918 X<$1> X<$2> X<$3> X<$I<digits>>
920 Contains the subpattern from the corresponding set of capturing
921 parentheses from the last successful pattern match, not counting patterns
922 matched in nested blocks that have been exited already.
924 Note there is a distinction between a capture buffer which matches
925 the empty string a capture buffer which is optional. Eg, C<(x?)> and
926 C<(x)?> The latter may be undef, the former not.
928 These variables are read-only and dynamically-scoped.
930 Mnemonic: like \digits.
933 X<@{^CAPTURE}> X<@^CAPTURE>
935 An array which exposes the contents of the capture buffers, if any, of
936 the last successful pattern match, not counting patterns matched
937 in nested blocks that have been exited already.
939 Note that the 0 index of @{^CAPTURE} is equivalent to $1, the 1 index
940 is equivalent to $2, etc.
942 if ("foal"=~/(.)(.)(.)(.)/) {
943 print join "-", @{^CAPTURE};
946 should output "f-o-a-l".
948 See also L<<< /$<I<digits>> ($1, $2, ...) >>>, L</%{^CAPTURE}> and
951 Note that unlike most other regex magic variables there is no single
952 letter equivalent to C<@{^CAPTURE}>. Also be aware that when
953 interpolating subscripts of this array you B<must> use the demarcated
954 variable form, for instance
956 print "${^CAPTURE[0]}"
958 see L<perldata/"Demarcated variable names using braces"> for more
959 information on this form and its uses.
961 This variable was added in 5.25.7
968 The string matched by the last successful pattern match (not counting
969 any matches hidden within a BLOCK or C<eval()> enclosed by the current
972 See L</Performance issues> above for the serious performance implications
973 of using this variable (even once) in your code.
975 This variable is read-only and dynamically-scoped.
977 Mnemonic: like C<&> in some editors.
982 This is similar to C<$&> (C<$MATCH>) except that it does not incur the
983 performance penalty associated with that variable.
985 See L</Performance issues> above.
987 In Perl v5.18 and earlier, it is only guaranteed
988 to return a defined value when the pattern was compiled or executed with
989 the C</p> modifier. In Perl v5.20, the C</p> modifier does nothing, so
990 C<${^MATCH}> does the same thing as C<$MATCH>.
992 This variable was added in Perl v5.10.0.
994 This variable is read-only and dynamically-scoped.
999 X<$`> X<$PREMATCH> X<${^PREMATCH}>
1001 The string preceding whatever was matched by the last successful
1002 pattern match, not counting any matches hidden within a BLOCK or C<eval>
1003 enclosed by the current BLOCK.
1005 See L</Performance issues> above for the serious performance implications
1006 of using this variable (even once) in your code.
1008 This variable is read-only and dynamically-scoped.
1010 Mnemonic: C<`> often precedes a quoted string.
1013 X<$`> X<${^PREMATCH}>
1015 This is similar to C<$`> ($PREMATCH) except that it does not incur the
1016 performance penalty associated with that variable.
1018 See L</Performance issues> above.
1020 In Perl v5.18 and earlier, it is only guaranteed
1021 to return a defined value when the pattern was compiled or executed with
1022 the C</p> modifier. In Perl v5.20, the C</p> modifier does nothing, so
1023 C<${^PREMATCH}> does the same thing as C<$PREMATCH>.
1025 This variable was added in Perl v5.10.0.
1027 This variable is read-only and dynamically-scoped.
1032 X<$'> X<$POSTMATCH> X<${^POSTMATCH}> X<@->
1034 The string following whatever was matched by the last successful
1035 pattern match (not counting any matches hidden within a BLOCK or C<eval()>
1036 enclosed by the current BLOCK). Example:
1038 local $_ = 'abcdefghi';
1040 print "$`:$&:$'\n"; # prints abc:def:ghi
1042 See L</Performance issues> above for the serious performance implications
1043 of using this variable (even once) in your code.
1045 This variable is read-only and dynamically-scoped.
1047 Mnemonic: C<'> often follows a quoted string.
1050 X<${^POSTMATCH}> X<$'> X<$POSTMATCH>
1052 This is similar to C<$'> (C<$POSTMATCH>) except that it does not incur the
1053 performance penalty associated with that variable.
1055 See L</Performance issues> above.
1057 In Perl v5.18 and earlier, it is only guaranteed
1058 to return a defined value when the pattern was compiled or executed with
1059 the C</p> modifier. In Perl v5.20, the C</p> modifier does nothing, so
1060 C<${^POSTMATCH}> does the same thing as C<$POSTMATCH>.
1062 This variable was added in Perl v5.10.0.
1064 This variable is read-only and dynamically-scoped.
1066 =item $LAST_PAREN_MATCH
1069 X<$+> X<$LAST_PAREN_MATCH>
1071 The text matched by the highest used capture group of the last
1072 successful search pattern. It is logically equivalent to the highest
1073 numbered capture variable (C<$1>, C<$2>, ...) which has a defined value.
1075 This is useful if you don't know which one of a set of alternative patterns
1076 matched. For example:
1078 /Version: (.*)|Revision: (.*)/ && ($rev = $+);
1080 This variable is read-only and dynamically-scoped.
1082 Mnemonic: be positive and forward looking.
1084 =item $LAST_SUBMATCH_RESULT
1087 X<$^N> X<$LAST_SUBMATCH_RESULT>
1089 The text matched by the used group most-recently closed (i.e. the group
1090 with the rightmost closing parenthesis) of the last successful search
1091 pattern. This is subtly different from C<$+>. For example in
1093 "ab" =~ /^((.)(.))$/
1097 $1,$^N have the value "ab"
1098 $2 has the value "a"
1099 $3,$+ have the value "b"
1101 This is primarily used inside C<(?{...})> blocks for examining text
1102 recently matched. For example, to effectively capture text to a variable
1103 (in addition to C<$1>, C<$2>, etc.), replace C<(...)> with
1105 (?:(...)(?{ $var = $^N }))
1107 By setting and then using C<$var> in this way relieves you from having to
1108 worry about exactly which numbered set of parentheses they are.
1110 This variable was added in Perl v5.8.0.
1112 Mnemonic: the (possibly) Nested parenthesis that most recently closed.
1114 =item @LAST_MATCH_END
1117 X<@+> X<@LAST_MATCH_END>
1119 This array holds the offsets of the ends of the last successful
1120 submatches in the currently active dynamic scope. C<$+[0]> is
1121 the offset into the string of the end of the entire match. This
1122 is the same value as what the C<pos> function returns when called
1123 on the variable that was matched against. The I<n>th element
1124 of this array holds the offset of the I<n>th submatch, so
1125 C<$+[1]> is the offset past where C<$1> ends, C<$+[2]> the offset
1126 past where C<$2> ends, and so on. You can use C<$#+> to determine
1127 how many subgroups were in the last successful match. See the
1128 examples given for the C<@-> variable.
1130 This variable was added in Perl v5.6.0.
1134 =item %LAST_PAREN_MATCH
1137 X<%+> X<%LAST_PAREN_MATCH> X<%{^CAPTURE}>
1139 Similar to C<@+>, the C<%+> hash allows access to the named capture
1140 buffers, should they exist, in the last successful match in the
1141 currently active dynamic scope.
1143 For example, C<$+{foo}> is equivalent to C<$1> after the following match:
1145 'foo' =~ /(?<foo>foo)/;
1147 The keys of the C<%+> hash list only the names of buffers that have
1148 captured (and that are thus associated to defined values).
1150 If multiple distinct capture groups have the same name, then
1151 C<$+{NAME}> will refer to the leftmost defined group in the match.
1153 The underlying behaviour of C<%+> is provided by the
1154 L<Tie::Hash::NamedCapture> module.
1156 B<Note:> C<%-> and C<%+> are tied views into a common internal hash
1157 associated with the last successful regular expression. Therefore mixing
1158 iterative access to them via C<each> may have unpredictable results.
1159 Likewise, if the last successful match changes, then the results may be
1162 This variable was added in Perl v5.10.0. The C<%{^CAPTURE}> alias was
1165 This variable is read-only and dynamically-scoped.
1167 =item @LAST_MATCH_START
1170 X<@-> X<@LAST_MATCH_START>
1172 C<$-[0]> is the offset of the start of the last successful match.
1173 C<$-[I<n>]> is the offset of the start of the substring matched by
1174 I<n>-th subpattern, or undef if the subpattern did not match.
1176 Thus, after a match against C<$_>, C<$&> coincides with C<substr $_, $-[0],
1177 $+[0] - $-[0]>. Similarly, $I<n> coincides with C<substr $_, $-[n],
1178 $+[n] - $-[n]> if C<$-[n]> is defined, and $+ coincides with
1179 C<substr $_, $-[$#-], $+[$#-] - $-[$#-]>. One can use C<$#-> to find the
1180 last matched subgroup in the last successful match. Contrast with
1181 C<$#+>, the number of subgroups in the regular expression. Compare
1184 This array holds the offsets of the beginnings of the last
1185 successful submatches in the currently active dynamic scope.
1186 C<$-[0]> is the offset into the string of the beginning of the
1187 entire match. The I<n>th element of this array holds the offset
1188 of the I<n>th submatch, so C<$-[1]> is the offset where C<$1>
1189 begins, C<$-[2]> the offset where C<$2> begins, and so on.
1191 After a match against some variable C<$var>:
1195 =item C<$`> is the same as C<substr($var, 0, $-[0])>
1197 =item C<$&> is the same as C<substr($var, $-[0], $+[0] - $-[0])>
1199 =item C<$'> is the same as C<substr($var, $+[0])>
1201 =item C<$1> is the same as C<substr($var, $-[1], $+[1] - $-[1])>
1203 =item C<$2> is the same as C<substr($var, $-[2], $+[2] - $-[2])>
1205 =item C<$3> is the same as C<substr($var, $-[3], $+[3] - $-[3])>
1209 This variable was added in Perl v5.6.0.
1211 =item %{^CAPTURE_ALL}
1217 Similar to C<%+>, this variable allows access to the named capture groups
1218 in the last successful match in the currently active dynamic scope. To
1219 each capture group name found in the regular expression, it associates a
1220 reference to an array containing the list of values captured by all
1221 buffers with that name (should there be several of them), in the order
1226 if ('1234' =~ /(?<A>1)(?<B>2)(?<A>3)(?<B>4)/) {
1227 foreach my $bufname (sort keys %-) {
1228 my $ary = $-{$bufname};
1229 foreach my $idx (0..$#$ary) {
1230 print "\$-{$bufname}[$idx] : ",
1231 (defined($ary->[$idx])
1246 The keys of the C<%-> hash correspond to all buffer names found in
1247 the regular expression.
1249 The behaviour of C<%-> is implemented via the
1250 L<Tie::Hash::NamedCapture> module.
1252 B<Note:> C<%-> and C<%+> are tied views into a common internal hash
1253 associated with the last successful regular expression. Therefore mixing
1254 iterative access to them via C<each> may have unpredictable results.
1255 Likewise, if the last successful match changes, then the results may be
1258 This variable was added in Perl v5.10.0. The C<%{^CAPTURE_ALL}> alias was
1261 This variable is read-only and dynamically-scoped.
1263 =item $LAST_REGEXP_CODE_RESULT
1266 X<$^R> X<$LAST_REGEXP_CODE_RESULT>
1268 The result of evaluation of the last successful C<(?{ code })>
1269 regular expression assertion (see L<perlre>). May be written to.
1271 This variable was added in Perl 5.005.
1273 =item ${^RE_COMPILE_RECURSION_LIMIT}
1274 X<${^RE_COMPILE_RECURSION_LIMIT}>
1276 The current value giving the maximum number of open but unclosed
1277 parenthetical groups there may be at any point during a regular
1278 expression compilation. The default is currently 1000 nested groups.
1279 You may adjust it depending on your needs and the amount of memory
1282 This variable was added in Perl v5.30.0.
1284 =item ${^RE_DEBUG_FLAGS}
1285 X<${^RE_DEBUG_FLAGS}>
1287 The current value of the regex debugging flags. Set to 0 for no debug output
1288 even when the C<re 'debug'> module is loaded. See L<re> for details.
1290 This variable was added in Perl v5.10.0.
1292 =item ${^RE_TRIE_MAXBUF}
1293 X<${^RE_TRIE_MAXBUF}>
1295 Controls how certain regex optimisations are applied and how much memory they
1296 utilize. This value by default is 65536 which corresponds to a 512kB
1297 temporary cache. Set this to a higher value to trade
1298 memory for speed when matching large alternations. Set
1299 it to a lower value if you want the optimisations to
1300 be as conservative of memory as possible but still occur, and set it to a
1301 negative value to prevent the optimisation and conserve the most memory.
1302 Under normal situations this variable should be of no interest to you.
1304 This variable was added in Perl v5.10.0.
1308 =head2 Variables related to filehandles
1310 Variables that depend on the currently selected filehandle may be set
1311 by calling an appropriate object method on the C<IO::Handle> object,
1312 although this is less efficient than using the regular built-in
1313 variables. (Summary lines below for this contain the word HANDLE.)
1318 after which you may use either
1324 HANDLE->method(EXPR)
1326 Each method returns the old value of the C<IO::Handle> attribute. The
1327 methods each take an optional EXPR, which, if supplied, specifies the
1328 new value for the C<IO::Handle> attribute in question. If not
1329 supplied, most methods do nothing to the current value--except for
1330 C<autoflush()>, which will assume a 1 for you, just to be different.
1332 Because loading in the C<IO::Handle> class is an expensive operation,
1333 you should learn how to use the regular built-in variables.
1335 A few of these variables are considered "read-only". This means that
1336 if you try to assign to this variable, either directly or indirectly
1337 through a reference, you'll raise a run-time exception.
1339 You should be very careful when modifying the default values of most
1340 special variables described in this document. In most cases you want
1341 to localize these variables before changing them, since if you don't,
1342 the change may affect other modules which rely on the default values
1343 of the special variables that you have changed. This is one of the
1344 correct ways to read the whole file at once:
1346 open my $fh, "<", "foo" or die $!;
1347 local $/; # enable localized slurp mode
1348 my $content = <$fh>;
1351 But the following code is quite bad:
1353 open my $fh, "<", "foo" or die $!;
1354 undef $/; # enable slurp mode
1355 my $content = <$fh>;
1358 since some other module, may want to read data from some file in the
1359 default "line mode", so if the code we have just presented has been
1360 executed, the global value of C<$/> is now changed for any other code
1361 running inside the same Perl interpreter.
1363 Usually when a variable is localized you want to make sure that this
1364 change affects the shortest scope possible. So unless you are already
1365 inside some short C<{}> block, you should create one yourself. For
1369 open my $fh, "<", "foo" or die $!;
1376 Here is an example of how your own code can go broken:
1386 # do something with $_
1389 You probably expect this code to print the equivalent of
1393 but instead you get:
1397 Why? Because C<nasty_break()> modifies C<$\> without localizing it
1398 first. The value you set in C<nasty_break()> is still there when you
1399 return. The fix is to add C<local()> so the value doesn't leak out of
1404 It's easy to notice the problem in such a short example, but in more
1405 complicated code you are looking for trouble if you don't localize
1406 changes to the special variables.
1413 Contains the name of the current file when reading from C<< <> >>.
1418 The array C<@ARGV> contains the command-line arguments intended for
1419 the script. C<$#ARGV> is generally the number of arguments minus
1420 one, because C<$ARGV[0]> is the first argument, I<not> the program's
1421 command name itself. See L</$0> for the command name.
1426 The special filehandle that iterates over command-line filenames in
1427 C<@ARGV>. Usually written as the null filehandle in the angle operator
1428 C<< <> >>. Note that currently C<ARGV> only has its magical effect
1429 within the C<< <> >> operator; elsewhere it is just a plain filehandle
1430 corresponding to the last file opened by C<< <> >>. In particular,
1431 passing C<\*ARGV> as a parameter to a function that expects a filehandle
1432 may not cause your function to automatically read the contents of all the
1438 The special filehandle that points to the currently open output file
1439 when doing edit-in-place processing with B<-i>. Useful when you have
1440 to do a lot of inserting and don't want to keep modifying C<$_>. See
1441 L<perlrun|perlrun/-i[extension]> for the B<-i> switch.
1443 =item IO::Handle->output_field_separator( EXPR )
1445 =item $OUTPUT_FIELD_SEPARATOR
1450 X<$,> X<$OFS> X<$OUTPUT_FIELD_SEPARATOR>
1452 The output field separator for the print operator. If defined, this
1453 value is printed between each of print's arguments. Default is C<undef>.
1455 You cannot call C<output_field_separator()> on a handle, only as a
1456 static method. See L<IO::Handle|IO::Handle>.
1458 Mnemonic: what is printed when there is a "," in your print statement.
1460 =item HANDLE->input_line_number( EXPR )
1462 =item $INPUT_LINE_NUMBER
1467 X<$.> X<$NR> X<$INPUT_LINE_NUMBER> X<line number>
1469 Current line number for the last filehandle accessed.
1471 Each filehandle in Perl counts the number of lines that have been read
1472 from it. (Depending on the value of C<$/>, Perl's idea of what
1473 constitutes a line may not match yours.) When a line is read from a
1474 filehandle (via C<readline()> or C<< <> >>), or when C<tell()> or
1475 C<seek()> is called on it, C<$.> becomes an alias to the line counter
1476 for that filehandle.
1478 You can adjust the counter by assigning to C<$.>, but this will not
1479 actually move the seek pointer. I<Localizing C<$.> will not localize
1480 the filehandle's line count>. Instead, it will localize perl's notion
1481 of which filehandle C<$.> is currently aliased to.
1483 C<$.> is reset when the filehandle is closed, but B<not> when an open
1484 filehandle is reopened without an intervening C<close()>. For more
1485 details, see L<perlop/"IE<sol>O Operators">. Because C<< <> >> never does
1486 an explicit close, line numbers increase across C<ARGV> files (but see
1487 examples in L<perlfunc/eof>).
1489 You can also use C<< HANDLE->input_line_number(EXPR) >> to access the
1490 line counter for a given filehandle without having to worry about
1491 which handle you last accessed.
1493 Mnemonic: many programs use "." to mean the current line number.
1495 =item IO::Handle->input_record_separator( EXPR )
1497 =item $INPUT_RECORD_SEPARATOR
1502 X<$/> X<$RS> X<$INPUT_RECORD_SEPARATOR>
1504 The input record separator, newline by default. This influences Perl's
1505 idea of what a "line" is. Works like B<awk>'s RS variable, including
1506 treating empty lines as a terminator if set to the null string (an
1507 empty line cannot contain any spaces or tabs). You may set it to a
1508 multi-character string to match a multi-character terminator, or to
1509 C<undef> to read through the end of file. Setting it to C<"\n\n">
1510 means something slightly different than setting to C<"">, if the file
1511 contains consecutive empty lines. Setting to C<""> will treat two or
1512 more consecutive empty lines as a single empty line. Setting to
1513 C<"\n\n"> will blindly assume that the next input character belongs to
1514 the next paragraph, even if it's a newline.
1516 local $/; # enable "slurp" mode
1517 local $_ = <FH>; # whole file now here
1520 Remember: the value of C<$/> is a string, not a regex. B<awk> has to
1521 be better for something. :-)
1523 Setting C<$/> to an empty string -- the so-called I<paragraph mode> -- merits
1524 special attention. When C<$/> is set to C<""> and the entire file is read in
1525 with that setting, any sequence of one or more consecutive newlines at the
1526 beginning of the file is discarded. With the exception of the final record in
1527 the file, each sequence of characters ending in two or more newlines is
1528 treated as one record and is read in to end in exactly two newlines. If the
1529 last record in the file ends in zero or one consecutive newlines, that record
1530 is read in with that number of newlines. If the last record ends in two or
1531 more consecutive newlines, it is read in with two newlines like all preceding
1534 Suppose we wrote the following string to a file:
1536 my $string = "\n\n\n";
1537 $string .= "alpha beta\ngamma delta\n\n\n";
1538 $string .= "epsilon zeta eta\n\n";
1539 $string .= "theta\n";
1541 my $file = 'simple_file.txt';
1542 open my $OUT, '>', $file or die;
1546 Now we read that file in paragraph mode:
1548 local $/ = ""; # paragraph mode
1549 open my $IN, '<', $file or die;
1550 my @records = <$IN>;
1553 C<@records> will consist of these 3 strings:
1556 "alpha beta\ngamma delta\n\n",
1557 "epsilon zeta eta\n\n",
1561 Setting C<$/> to a reference to an integer, scalar containing an
1562 integer, or scalar that's convertible to an integer will attempt to
1563 read records instead of lines, with the maximum record size being the
1564 referenced integer number of characters. So this:
1566 local $/ = \32768; # or \"32768", or \$var_containing_32768
1567 open my $fh, "<", $myfile or die $!;
1570 will read a record of no more than 32768 characters from $fh. If you're
1571 not reading from a record-oriented file (or your OS doesn't have
1572 record-oriented files), then you'll likely get a full chunk of data
1573 with every read. If a record is larger than the record size you've
1574 set, you'll get the record back in pieces. Trying to set the record
1575 size to zero or less is deprecated and will cause $/ to have the value
1576 of "undef", which will cause reading in the (rest of the) whole file.
1578 As of 5.19.9 setting C<$/> to any other form of reference will throw a
1579 fatal exception. This is in preparation for supporting new ways to set
1580 C<$/> in the future.
1582 On VMS only, record reads bypass PerlIO layers and any associated
1583 buffering, so you must not mix record and non-record reads on the
1584 same filehandle. Record mode mixes with line mode only when the
1585 same buffering layer is in use for both modes.
1587 You cannot call C<input_record_separator()> on a handle, only as a
1588 static method. See L<IO::Handle|IO::Handle>.
1590 See also L<perlport/"Newlines">. Also see L</$.>.
1592 Mnemonic: / delimits line boundaries when quoting poetry.
1594 =item IO::Handle->output_record_separator( EXPR )
1596 =item $OUTPUT_RECORD_SEPARATOR
1601 X<$\> X<$ORS> X<$OUTPUT_RECORD_SEPARATOR>
1603 The output record separator for the print operator. If defined, this
1604 value is printed after the last of print's arguments. Default is C<undef>.
1606 You cannot call C<output_record_separator()> on a handle, only as a
1607 static method. See L<IO::Handle|IO::Handle>.
1609 Mnemonic: you set C<$\> instead of adding "\n" at the end of the print.
1610 Also, it's just like C<$/>, but it's what you get "back" from Perl.
1612 =item HANDLE->autoflush( EXPR )
1614 =item $OUTPUT_AUTOFLUSH
1617 X<$|> X<autoflush> X<flush> X<$OUTPUT_AUTOFLUSH>
1619 If set to nonzero, forces a flush right away and after every write or
1620 print on the currently selected output channel. Default is 0
1621 (regardless of whether the channel is really buffered by the system or
1622 not; C<$|> tells you only whether you've asked Perl explicitly to
1623 flush after each write). STDOUT will typically be line buffered if
1624 output is to the terminal and block buffered otherwise. Setting this
1625 variable is useful primarily when you are outputting to a pipe or
1626 socket, such as when you are running a Perl program under B<rsh> and
1627 want to see the output as it's happening. This has no effect on input
1628 buffering. See L<perlfunc/getc> for that. See L<perlfunc/select> on
1629 how to select the output channel. See also L<IO::Handle>.
1631 Mnemonic: when you want your pipes to be piping hot.
1636 This read-only variable contains a reference to the last-read filehandle.
1637 This is set by C<< <HANDLE> >>, C<readline>, C<tell>, C<eof> and C<seek>.
1638 This is the same handle that C<$.> and C<tell> and C<eof> without arguments
1639 use. It is also the handle used when Perl appends ", <STDIN> line 1" to
1640 an error or warning message.
1642 This variable was added in Perl v5.18.0.
1646 =head3 Variables related to formats
1648 The special variables for formats are a subset of those for
1649 filehandles. See L<perlform> for more information about Perl's
1657 X<$^A> X<$ACCUMULATOR>
1659 The current value of the C<write()> accumulator for C<format()> lines.
1660 A format contains C<formline()> calls that put their result into
1661 C<$^A>. After calling its format, C<write()> prints out the contents
1662 of C<$^A> and empties. So you never really see the contents of C<$^A>
1663 unless you call C<formline()> yourself and then look at it. See
1664 L<perlform> and L<perlfunc/"formline PICTURE,LIST">.
1666 =item IO::Handle->format_formfeed(EXPR)
1668 =item $FORMAT_FORMFEED
1671 X<$^L> X<$FORMAT_FORMFEED>
1673 What formats output as a form feed. The default is C<\f>.
1675 You cannot call C<format_formfeed()> on a handle, only as a static
1676 method. See L<IO::Handle|IO::Handle>.
1678 =item HANDLE->format_page_number(EXPR)
1680 =item $FORMAT_PAGE_NUMBER
1683 X<$%> X<$FORMAT_PAGE_NUMBER>
1685 The current page number of the currently selected output channel.
1687 Mnemonic: C<%> is page number in B<nroff>.
1689 =item HANDLE->format_lines_left(EXPR)
1691 =item $FORMAT_LINES_LEFT
1694 X<$-> X<$FORMAT_LINES_LEFT>
1696 The number of lines left on the page of the currently selected output
1699 Mnemonic: lines_on_page - lines_printed.
1701 =item IO::Handle->format_line_break_characters EXPR
1703 =item $FORMAT_LINE_BREAK_CHARACTERS
1706 X<$:> X<FORMAT_LINE_BREAK_CHARACTERS>
1708 The current set of characters after which a string may be broken to
1709 fill continuation fields (starting with C<^>) in a format. The default is
1710 S<" \n-">, to break on a space, newline, or a hyphen.
1712 You cannot call C<format_line_break_characters()> on a handle, only as
1713 a static method. See L<IO::Handle|IO::Handle>.
1715 Mnemonic: a "colon" in poetry is a part of a line.
1717 =item HANDLE->format_lines_per_page(EXPR)
1719 =item $FORMAT_LINES_PER_PAGE
1722 X<$=> X<$FORMAT_LINES_PER_PAGE>
1724 The current page length (printable lines) of the currently selected
1725 output channel. The default is 60.
1727 Mnemonic: = has horizontal lines.
1729 =item HANDLE->format_top_name(EXPR)
1731 =item $FORMAT_TOP_NAME
1734 X<$^> X<$FORMAT_TOP_NAME>
1736 The name of the current top-of-page format for the currently selected
1737 output channel. The default is the name of the filehandle with C<_TOP>
1738 appended. For example, the default format top name for the C<STDOUT>
1739 filehandle is C<STDOUT_TOP>.
1741 Mnemonic: points to top of page.
1743 =item HANDLE->format_name(EXPR)
1748 X<$~> X<$FORMAT_NAME>
1750 The name of the current report format for the currently selected
1751 output channel. The default format name is the same as the filehandle
1752 name. For example, the default format name for the C<STDOUT>
1753 filehandle is just C<STDOUT>.
1755 Mnemonic: brother to C<$^>.
1759 =head2 Error Variables
1760 X<error> X<exception>
1762 The variables C<$@>, C<$!>, C<$^E>, and C<$?> contain information
1763 about different types of error conditions that may appear during
1764 execution of a Perl program. The variables are shown ordered by
1765 the "distance" between the subsystem which reported the error and
1766 the Perl process. They correspond to errors detected by the Perl
1767 interpreter, C library, operating system, or an external program,
1770 To illustrate the differences between these variables, consider the
1771 following Perl expression, which uses a single-quoted string. After
1772 execution of this statement, perl may have set all four special error
1776 open my $pipe, "/cdrom/install |" or die $!;
1778 close $pipe or die "bad pipe: $?, $!";
1781 When perl executes the C<eval()> expression, it translates the
1782 C<open()>, C<< <PIPE> >>, and C<close> calls in the C run-time library
1783 and thence to the operating system kernel. perl sets C<$!> to
1784 the C library's C<errno> if one of these calls fails.
1786 C<$@> is set if the string to be C<eval>-ed did not compile (this may
1787 happen if C<open> or C<close> were imported with bad prototypes), or
1788 if Perl code executed during evaluation C<die()>d. In these cases the
1789 value of C<$@> is the compile error, or the argument to C<die> (which
1790 will interpolate C<$!> and C<$?>). (See also L<Fatal>, though.)
1792 Under a few operating systems, C<$^E> may contain a more verbose error
1793 indicator, such as in this case, "CDROM tray not closed." Systems that
1794 do not support extended error messages leave C<$^E> the same as C<$!>.
1796 Finally, C<$?> may be set to a non-0 value if the external program
1797 F</cdrom/install> fails. The upper eight bits reflect specific error
1798 conditions encountered by the program (the program's C<exit()> value).
1799 The lower eight bits reflect mode of failure, like signal death and
1800 core dump information. See L<wait(2)> for details. In contrast to
1801 C<$!> and C<$^E>, which are set only if an error condition is detected,
1802 the variable C<$?> is set on each C<wait> or pipe C<close>,
1803 overwriting the old value. This is more like C<$@>, which on every
1804 C<eval()> is always set on failure and cleared on success.
1806 For more details, see the individual descriptions at C<$@>, C<$!>,
1811 =item ${^CHILD_ERROR_NATIVE}
1812 X<$^CHILD_ERROR_NATIVE>
1814 The native status returned by the last pipe close, backtick (C<``>)
1815 command, successful call to C<wait()> or C<waitpid()>, or from the
1816 C<system()> operator. On POSIX-like systems this value can be decoded
1817 with the WIFEXITED, WEXITSTATUS, WIFSIGNALED, WTERMSIG, WIFSTOPPED, and
1818 WSTOPSIG functions provided by the L<POSIX> module.
1820 Under VMS this reflects the actual VMS exit status; i.e. it is the
1821 same as C<$?> when the pragma C<use vmsish 'status'> is in effect.
1823 This variable was added in Perl v5.10.0.
1825 =item $EXTENDED_OS_ERROR
1828 X<$^E> X<$EXTENDED_OS_ERROR>
1830 Error information specific to the current operating system. At the
1831 moment, this differs from C<L</$!>> under only VMS, OS/2, and Win32 (and
1832 for MacPerl). On all other platforms, C<$^E> is always just the same
1835 Under VMS, C<$^E> provides the VMS status value from the last system
1836 error. This is more specific information about the last system error
1837 than that provided by C<$!>. This is particularly important when C<$!>
1838 is set to B<EVMSERR>.
1840 Under OS/2, C<$^E> is set to the error code of the last call to OS/2
1841 API either via CRT, or directly from perl.
1843 Under Win32, C<$^E> always returns the last error information reported
1844 by the Win32 call C<GetLastError()> which describes the last error
1845 from within the Win32 API. Most Win32-specific code will report errors
1846 via C<$^E>. ANSI C and Unix-like calls set C<errno> and so most
1847 portable Perl code will report errors via C<$!>.
1849 Caveats mentioned in the description of C<L</$!>> generally apply to
1852 This variable was added in Perl 5.003.
1854 Mnemonic: Extra error explanation.
1856 =item $EXCEPTIONS_BEING_CAUGHT
1859 X<$^S> X<$EXCEPTIONS_BEING_CAUGHT>
1861 Current state of the interpreter.
1864 --------- -------------------------------------
1865 undef Parsing module, eval, or main program
1866 true (1) Executing an eval or try block
1869 The first state may happen in C<$SIG{__DIE__}> and C<$SIG{__WARN__}>
1872 The English name $EXCEPTIONS_BEING_CAUGHT is slightly misleading, because
1873 the C<undef> value does not indicate whether exceptions are being caught,
1874 since compilation of the main program does not catch exceptions.
1876 This variable was added in Perl 5.004.
1883 The current value of the warning switch, initially true if B<-w> was
1884 used, false otherwise, but directly modifiable.
1886 See also L<warnings>.
1888 Mnemonic: related to the B<-w> switch.
1890 =item ${^WARNING_BITS}
1893 The current set of warning checks enabled by the C<use warnings> pragma.
1894 It has the same scoping as the C<$^H> and C<%^H> variables. The exact
1895 values are considered internal to the L<warnings> pragma and may change
1896 between versions of Perl.
1898 Each time a statement completes being compiled, the current value of
1899 C<${^WARNING_BITS}> is stored with that statement, and can later be
1900 retrieved via C<(caller($level))[9]>.
1902 This variable was added in Perl v5.6.0.
1909 X<$!> X<$ERRNO> X<$OS_ERROR>
1911 When referenced, C<$!> retrieves the current value
1912 of the C C<errno> integer variable.
1913 If C<$!> is assigned a numerical value, that value is stored in C<errno>.
1914 When referenced as a string, C<$!> yields the system error string
1915 corresponding to C<errno>.
1917 Many system or library calls set C<errno> if they fail,
1918 to indicate the cause of failure. They usually do B<not>
1919 set C<errno> to zero if they succeed and may set C<errno> to a
1920 non-zero value on success. This means C<errno>, hence C<$!>, is
1921 meaningful only I<immediately> after a B<failure>:
1923 if (open my $fh, "<", $filename) {
1924 # Here $! is meaningless.
1928 # ONLY here is $! meaningful.
1930 # Already here $! might be meaningless.
1932 # Since here we might have either success or failure,
1933 # $! is meaningless.
1935 Here, I<meaningless> means that C<$!> may be unrelated to the outcome
1936 of the C<open()> operator. Assignment to C<$!> is similarly ephemeral.
1937 It can be used immediately before invoking the C<die()> operator,
1938 to set the exit value, or to inspect the system error string
1939 corresponding to error I<n>, or to restore C<$!> to a meaningful state.
1941 Perl itself may set C<errno> to a non-zero on failure even if no
1942 system call is performed.
1944 Mnemonic: What just went bang?
1951 X<%!> X<%OS_ERROR> X<%ERRNO>
1953 Each element of C<%!> has a true value only if C<$!> is set to that
1954 value. For example, C<$!{ENOENT}> is true if and only if the current
1955 value of C<$!> is C<ENOENT>; that is, if the most recent error was "No
1956 such file or directory" (or its moral equivalent: not all operating
1957 systems give that exact error, and certainly not all languages). The
1958 specific true value is not guaranteed, but in the past has generally
1959 been the numeric value of C<$!>. To check if a particular key is
1960 meaningful on your system, use C<exists $!{the_key}>; for a list of legal
1961 keys, use C<keys %!>. See L<Errno> for more information, and also see
1964 This variable was added in Perl 5.005.
1969 X<$?> X<$CHILD_ERROR>
1971 The status returned by the last pipe close, backtick (C<``>) command,
1972 successful call to C<wait()> or C<waitpid()>, or from the C<system()>
1973 operator. This is just the 16-bit status word returned by the
1974 traditional Unix C<wait()> system call (or else is made up to look
1975 like it). Thus, the exit value of the subprocess is really (C<<< $? >>
1976 8 >>>), and C<$? & 127> gives which signal, if any, the process died
1977 from, and C<$? & 128> reports whether there was a core dump.
1979 Additionally, if the C<h_errno> variable is supported in C, its value
1980 is returned via C<$?> if any C<gethost*()> function fails.
1982 If you have installed a signal handler for C<SIGCHLD>, the
1983 value of C<$?> will usually be wrong outside that handler.
1985 Inside an C<END> subroutine C<$?> contains the value that is going to be
1986 given to C<exit()>. You can modify C<$?> in an C<END> subroutine to
1987 change the exit status of your program. For example:
1990 $? = 1 if $? == 255; # die would make it 255
1993 Under VMS, the pragma C<use vmsish 'status'> makes C<$?> reflect the
1994 actual VMS exit status, instead of the default emulation of POSIX
1995 status; see L<perlvms/$?> for details.
1997 Mnemonic: similar to B<sh> and B<ksh>.
2002 X<$@> X<$EVAL_ERROR>
2004 The Perl error from the last C<eval> operator, i.e. the last exception that
2005 was caught. For C<eval BLOCK>, this is either a runtime error message or the
2006 string or reference C<die> was called with. The C<eval STRING> form also
2007 catches syntax errors and other compile time exceptions.
2009 If no error occurs, C<eval> sets C<$@> to the empty string.
2011 Warning messages are not collected in this variable. You can, however,
2012 set up a routine to process warnings by setting C<$SIG{__WARN__}> as
2013 described in L</%SIG>.
2015 Mnemonic: Where was the error "at"?
2019 =head2 Variables related to the interpreter state
2021 These variables provide information about the current interpreter state.
2028 X<$^C> X<$COMPILING>
2030 The current value of the flag associated with the B<-c> switch.
2031 Mainly of use with B<-MO=...> to allow code to alter its behavior
2032 when being compiled, such as for example to C<AUTOLOAD> at compile
2033 time rather than normal, deferred loading. Setting
2034 C<$^C = 1> is similar to calling C<B::minus_c>.
2036 This variable was added in Perl v5.6.0.
2041 X<$^D> X<$DEBUGGING>
2043 The current value of the debugging flags. May be read or set. Like its
2044 L<command-line equivalent|perlrun/B<-D>I<letters>>, you can use numeric
2045 or symbolic values, e.g. C<$^D = 10> or C<$^D = "st">. See
2046 L<perlrun/B<-D>I<number>>. The contents of this variable also affects the
2047 debugger operation. See L<perldebguts/Debugger Internals>.
2049 Mnemonic: value of B<-D> switch.
2051 =item ${^GLOBAL_PHASE}
2054 The current phase of the perl interpreter.
2056 Possible values are:
2062 The C<PerlInterpreter*> is being constructed via C<perl_construct>. This
2063 value is mostly there for completeness and for use via the
2064 underlying C variable C<PL_phase>. It's not really possible for Perl
2065 code to be executed unless construction of the interpreter is
2070 This is the global compile-time. That includes, basically, every
2071 C<BEGIN> block executed directly or indirectly from during the
2072 compile-time of the top-level program.
2074 This phase is not called "BEGIN" to avoid confusion with
2075 C<BEGIN>-blocks, as those are executed during compile-time of any
2076 compilation unit, not just the top-level program. A new, localised
2077 compile-time entered at run-time, for example by constructs as
2078 C<eval "use SomeModule"> are not global interpreter phases, and
2079 therefore aren't reflected by C<${^GLOBAL_PHASE}>.
2083 Execution of any C<CHECK> blocks.
2087 Similar to "CHECK", but for C<INIT>-blocks, not C<CHECK> blocks.
2091 The main run-time, i.e. the execution of C<PL_main_root>.
2095 Execution of any C<END> blocks.
2103 Also note that there's no value for UNITCHECK-blocks. That's because
2104 those are run for each compilation unit individually, and therefore is
2105 not a global interpreter phase.
2107 Not every program has to go through each of the possible phases, but
2108 transition from one phase to another can only happen in the order
2109 described in the above list.
2111 An example of all of the phases Perl code can see:
2113 BEGIN { print "compile-time: ${^GLOBAL_PHASE}\n" }
2115 INIT { print "init-time: ${^GLOBAL_PHASE}\n" }
2117 CHECK { print "check-time: ${^GLOBAL_PHASE}\n" }
2120 package Print::Phase;
2123 my ($class, $time) = @_;
2124 return bless \$time, $class;
2129 print "$$self: ${^GLOBAL_PHASE}\n";
2133 print "run-time: ${^GLOBAL_PHASE}\n";
2135 my $runtime = Print::Phase->new(
2136 "lexical variables are garbage collected before END"
2139 END { print "end-time: ${^GLOBAL_PHASE}\n" }
2141 our $destruct = Print::Phase->new(
2142 "package variables are garbage collected after END"
2151 lexical variables are garbage collected before END: RUN
2153 package variables are garbage collected after END: DESTRUCT
2155 This variable was added in Perl 5.14.0.
2160 WARNING: This variable is strictly for
2161 internal use only. Its availability,
2162 behavior, and contents are subject to change without notice.
2164 This variable contains compile-time hints for the Perl interpreter. At the
2165 end of compilation of a BLOCK the value of this variable is restored to the
2166 value when the interpreter started to compile the BLOCK.
2168 Each time a statement completes being compiled, the current value of
2169 C<$^H> is stored with that statement, and can later be retrieved via
2170 C<(caller($level))[8]>.
2172 When perl begins to parse any block construct that provides a lexical scope
2173 (e.g., eval body, required file, subroutine body, loop body, or conditional
2174 block), the existing value of C<$^H> is saved, but its value is left unchanged.
2175 When the compilation of the block is completed, it regains the saved value.
2176 Between the points where its value is saved and restored, code that
2177 executes within BEGIN blocks is free to change the value of C<$^H>.
2179 This behavior provides the semantic of lexical scoping, and is used in,
2180 for instance, the C<use strict> pragma.
2182 The contents should be an integer; different bits of it are used for
2183 different pragmatic flags. Here's an example:
2185 sub add_100 { $^H |= 0x100 }
2192 Consider what happens during execution of the BEGIN block. At this point
2193 the BEGIN block has already been compiled, but the body of C<foo()> is still
2194 being compiled. The new value of C<$^H>
2195 will therefore be visible only while
2196 the body of C<foo()> is being compiled.
2198 Substitution of C<BEGIN { add_100() }> block with:
2200 BEGIN { require strict; strict->import('vars') }
2202 demonstrates how C<use strict 'vars'> is implemented. Here's a conditional
2203 version of the same lexical pragma:
2206 require strict; strict->import('vars') if $condition
2209 This variable was added in Perl 5.003.
2214 The C<%^H> hash provides the same scoping semantic as C<$^H>. This makes
2215 it useful for implementation of lexically scoped pragmas. See
2216 L<perlpragma>. All the entries are stringified when accessed at
2217 runtime, so only simple values can be accommodated. This means no
2218 pointers to objects, for example.
2220 Each time a statement completes being compiled, the current value of
2221 C<%^H> is stored with that statement, and can later be retrieved via
2222 C<(caller($level))[10]>.
2224 When putting items into C<%^H>, in order to avoid conflicting with other
2225 users of the hash there is a convention regarding which keys to use.
2226 A module should use only keys that begin with the module's name (the
2227 name of its main package) and a "/" character. For example, a module
2228 C<Foo::Bar> should use keys such as C<Foo::Bar/baz>.
2230 This variable was added in Perl v5.6.0.
2235 An internal variable used by L<PerlIO>. A string in two parts, separated
2236 by a C<\0> byte, the first part describes the input layers, the second
2237 part describes the output layers.
2239 This is the mechanism that applies the lexical effects of the L<open>
2240 pragma, and the main program scope effects of the C<io> or C<D> options
2241 for the L<-C command-line switch|perlrun/-C [I<numberE<sol>list>]> and
2242 L<PERL_UNICODE environment variable|perlrun/PERL_UNICODE>.
2244 The functions C<accept()>, C<open()>, C<pipe()>, C<readpipe()> (as well
2245 as the related C<qx> and C<`STRING`> operators), C<socket()>,
2246 C<socketpair()>, and C<sysopen()> are affected by the lexical value of
2247 this variable. The implicit L</ARGV> handle opened by C<readline()> (or
2248 the related C<< <> >> and C<<< <<>> >>> operators) on passed filenames is
2249 also affected (but not if it opens C<STDIN>). If this variable is not
2250 set, these functions will set the default layers as described in
2251 L<PerlIO/Defaults and how to override them>.
2253 C<open()> ignores this variable (and the default layers) when called with
2254 3 arguments and explicit layers are specified. Indirect calls to these
2255 functions via modules like L<IO::Handle> are not affected as they occur
2256 in a different lexical scope. Directory handles such as opened by
2257 C<opendir()> are not currently affected.
2259 This variable was added in Perl v5.8.0.
2266 The internal variable for debugging support. The meanings of the
2267 various bits are subject to change, but currently indicate:
2273 Debug subroutine enter/exit.
2277 Line-by-line debugging. Causes C<DB::DB()> subroutine to be called for
2278 each statement executed. Also causes saving source code lines (like
2283 Switch off optimizations.
2287 Preserve more data for future interactive inspections.
2291 Keep info about source lines on which a subroutine is defined.
2295 Start with single-step on.
2299 Use subroutine address instead of name when reporting.
2303 Report C<goto &subroutine> as well.
2307 Provide informative "file" names for evals based on the place they were compiled.
2311 Provide informative names to anonymous subroutines based on the place they
2316 Save source code lines into C<@{"_<$filename"}>.
2320 When saving source, include evals that generate no subroutines.
2324 When saving source, include source that did not compile.
2328 Some bits may be relevant at compile-time only, some at
2329 run-time only. This is a new mechanism and the details may change.
2330 See also L<perldebguts>.
2335 Reflects if taint mode is on or off. 1 for on (the program was run with
2336 B<-T>), 0 for off, -1 when only taint warnings are enabled (i.e. with
2339 This variable is read-only.
2341 This variable was added in Perl v5.8.0.
2343 =item ${^SAFE_LOCALES}
2346 Reflects if safe locale operations are available to this perl (when the
2347 value is 1) or not (the value is 0). This variable is always 1 if the
2348 perl has been compiled without threads. It is also 1 if this perl is
2349 using thread-safe locale operations. Note that an individual thread may
2350 choose to use the global locale (generally unsafe) by calling
2351 L<perlapi/switch_to_global_locale>. This variable currently is still
2352 set to 1 in such threads.
2354 This variable is read-only.
2356 This variable was added in Perl v5.28.0.
2361 Reflects certain Unicode settings of Perl. See
2362 L<perlrun|perlrun/-C [numberE<sol>list]> documentation for the C<-C>
2363 switch for more information about the possible values.
2365 This variable is set during Perl startup and is thereafter read-only.
2367 This variable was added in Perl v5.8.2.
2372 This variable controls the state of the internal UTF-8 offset caching code.
2373 1 for on (the default), 0 for off, -1 to debug the caching code by checking
2374 all its results against linear scans, and panicking on any discrepancy.
2376 This variable was added in Perl v5.8.9. It is subject to change or
2377 removal without notice, but is currently used to avoid recalculating the
2378 boundaries of multi-byte UTF-8-encoded characters.
2380 =item ${^UTF8LOCALE}
2383 This variable indicates whether a UTF-8 locale was detected by perl at
2384 startup. This information is used by perl when it's in
2385 adjust-utf8ness-to-locale mode (as when run with the C<-CL> command-line
2386 switch); see L<perlrun|perlrun/-C [numberE<sol>list]> for more info on
2389 This variable was added in Perl v5.8.8.
2393 =head2 Deprecated and removed variables
2395 Deprecating a variable announces the intent of the perl maintainers to
2396 eventually remove the variable from the language. It may still be
2397 available despite its status. Using a deprecated variable triggers
2400 Once a variable is removed, its use triggers an error telling you
2401 the variable is unsupported.
2403 See L<perldiag> for details about error messages.
2410 C<$#> was a variable that could be used to format printed numbers.
2411 After a deprecation cycle, its magic was removed in Perl v5.10.0 and
2412 using it now triggers a warning: C<$# is no longer supported>.
2414 This is not the sigil you use in front of an array name to get the
2415 last index, like C<$#array>. That's still how you get the last index
2416 of an array in Perl. The two have nothing to do with each other.
2418 Deprecated in Perl 5.
2420 Removed in Perl v5.10.0.
2425 C<$*> was a variable that you could use to enable multiline matching.
2426 After a deprecation cycle, its magic was removed in Perl v5.10.0.
2427 Using it now triggers a warning: C<$* is no longer supported>.
2428 You should use the C</s> and C</m> regexp modifiers instead.
2430 Deprecated in Perl 5.
2432 Removed in Perl v5.10.0.
2437 This variable stores the index of the first element in an array, and
2438 of the first character in a substring. The default is 0, but you could
2439 theoretically set it to 1 to make Perl behave more like B<awk> (or Fortran)
2440 when subscripting and when evaluating the index() and substr() functions.
2442 As of release 5 of Perl, assignment to C<$[> is treated as a compiler
2443 directive, and cannot influence the behavior of any other file.
2444 (That's why you can only assign compile-time constants to it.)
2445 Its use is highly discouraged.
2447 Prior to Perl v5.10.0, assignment to C<$[> could be seen from outer lexical
2448 scopes in the same file, unlike other compile-time directives (such as
2449 L<strict>). Using local() on it would bind its value strictly to a lexical
2450 block. Now it is always lexically scoped.
2452 As of Perl v5.16.0, it is implemented by the L<arybase> module.
2454 As of Perl v5.30.0, or under C<use v5.16>, or C<no feature "array_base">,
2455 C<$[> no longer has any effect, and always contains 0.
2456 Assigning 0 to it is permitted, but any other value will produce an error.
2458 Mnemonic: [ begins subscripts.
2460 Deprecated in Perl v5.12.0.
2465 This variable is no longer supported.
2467 It used to hold the I<object reference> to the C<Encode> object that was
2468 used to convert the source code to Unicode.
2470 Its purpose was to allow your non-ASCII Perl
2471 scripts not to have to be written in UTF-8; this was
2472 useful before editors that worked on UTF-8 encoded text were common, but
2473 that was long ago. It caused problems, such as affecting the operation
2474 of other modules that weren't expecting it, causing general mayhem.
2476 If you need something like this functionality, it is recommended that use
2477 you a simple source filter, such as L<Filter::Encoding>.
2479 If you are coming here because code of yours is being adversely affected
2480 by someone's use of this variable, you can usually work around it by
2485 near the beginning of the functions that are getting broken. This
2486 undefines the variable during the scope of execution of the including
2489 This variable was added in Perl 5.8.2 and removed in 5.26.0.
2490 Setting it to anything other than C<undef> was made fatal in Perl 5.28.0.
2492 =item ${^WIN32_SLOPPY_STAT}
2493 X<${^WIN32_SLOPPY_STAT}> X<sitecustomize> X<sitecustomize.pl>
2495 This variable no longer has any function.
2497 This variable was added in Perl v5.10.0 and removed in Perl v5.34.0.