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