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 in the form "${^Foo}";
29       the braces are not optional.  "${^Foo}" denotes the scalar variable
30       whose name is considered to be a control-"F" followed by two "o"'s.
31       These variables are reserved for future special uses by Perl, except
32       for the ones that begin with "^_" (caret-underscore).  No name that
33       begins with "^_" will acquire a special meaning in any future version
34       of Perl; such names may therefore be used safely in programs.  $^_
35       itself, however, is reserved.
36
37       Perl identifiers that begin with digits or punctuation characters are
38       exempt from the effects of the "package" declaration and are always
39       forced to be in package "main"; they are also exempt from "strict
40       'vars'" errors.  A few other names are also exempt in these ways:
41
42           ENV      STDIN
43           INC      STDOUT
44           ARGV     STDERR
45           ARGVOUT
46           SIG
47
48       In particular, the special "${^_XYZ}" variables are always taken to be
49       in package "main", regardless of any "package" declarations presently
50       in scope.
51

SPECIAL VARIABLES

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