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