1PERLVAR(1)             Perl Programmers Reference Guide             PERLVAR(1)
2
3
4

NAME

6       perlvar - Perl predefined variables
7

DESCRIPTION

9   The Syntax of Variable Names
10       Variable names in Perl can have several formats.  Usually, they must
11       begin with a letter or underscore, in which case they can be
12       arbitrarily long (up to an internal limit of 251 characters) and may
13       contain letters, digits, underscores, or the special sequence "::" or
14       "'".  In this case, the part before the last "::" or "'" is taken to be
15       a package qualifier; see perlmod.  A Unicode letter that is not ASCII
16       is not considered to be a letter unless "use utf8" is in effect, and
17       somewhat more complicated rules apply; see "Identifier parsing" in
18       perldata for details.
19
20       Perl variable names may also be a sequence of digits, a single
21       punctuation character, or the two-character sequence: "^" (caret or
22       CIRCUMFLEX ACCENT) followed by any one of the characters "[][A-Z^_?\]".
23       These names are all reserved for special uses by Perl; for example, the
24       all-digits names are used to hold data captured by backreferences after
25       a regular expression match.
26
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 "${^Foo}"; the braces are not
30       optional.  "${^Foo}" denotes the scalar variable whose name is
31       considered to be a control-"F" followed by two "o"'s.  (See "Demarcated
32       variable names using braces" in perldata for more information on this
33       form of spelling a variable name or specifying access to an element of
34       an array or a hash).  These variables are reserved for future special
35       uses by Perl, except for the ones that begin with "^_" (caret-
36       underscore).  No name that begins with "^_" will acquire a special
37       meaning in any future version of Perl; such names may therefore be used
38       safely in programs.  $^_ itself, however, is reserved.
39
40       Note that you also must use the demarcated form to access subscripts of
41       variables of this type when interpolating, for instance to access the
42       first element of the "@{^CAPTURE}" variable inside of a double quoted
43       string you would write "${^CAPTURE[0]}" and NOT "${^CAPTURE}[0]" which
44       would mean to reference a scalar variable named "${^CAPTURE}" and not
45       index 0 of the magic "@{^CAPTURE}" array which is populated by the
46       regex engine.
47
48       Perl identifiers that begin with digits or punctuation characters are
49       exempt from the effects of the "package" declaration and are always
50       forced to be in package "main"; they are also exempt from "strict
51       'vars'" errors.  A few other names are also exempt in these ways:
52
53           ENV      STDIN
54           INC      STDOUT
55           ARGV     STDERR
56           ARGVOUT
57           SIG
58
59       In particular, the special "${^_XYZ}" variables are always taken to be
60       in package "main", regardless of any "package" declarations presently
61       in scope.
62

SPECIAL VARIABLES

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