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