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 by default a global variable. However, as of perl
120 v5.10.0, you can use a lexical version of $_ by declaring it in
121 a file or in a block with "my". Moreover, declaring "our $_"
122 restores the global $_ in the current scope. Though this
123 seemed like a good idea at the time it was introduced, lexical
124 $_ actually causes more problems than it solves. If you call a
125 function that expects to be passed information via $_, it may
126 or may not work, depending on how the function is written,
127 there not being any easy way to solve this. Just avoid lexical
128 $_, unless you are feeling particularly masochistic. For this
129 reason lexical $_ is still experimental and will produce a
130 warning unless warnings have been disabled. As with other
131 experimental features, the behavior of lexical $_ is subject to
132 change without notice, including change into a fatal error.
133 Mnemonic: underline is understood in certain operations.
135 @ARG
137 @_ Within a subroutine the array @_ contains the parameters passed
138 to that subroutine. Inside a subroutine, @_ is the default
139 array for the array operators "pop" and "shift".
140 See perlsub.
142 $LIST_SEPARATOR
144 $" When an array or an array slice is interpolated into a double-
145 quoted string or a similar context such as "/.../", its
146 elements are separated by this value. Default is a space. For
147 example, this:
148 print "The array is: @array\n";
150 is equivalent to this:
152 print "The array is: " . join($", @array) . "\n";
154 Mnemonic: works in double-quoted context.
156 $PROCESS_ID
158 $PID
159 $$ The process number of the Perl running this script. Though you
160 can set this variable, doing so is generally discouraged,
161 although it can be invaluable for some testing purposes. It
162 will be reset automatically across "fork()" calls.
163 Note for Linux and Debian GNU/kFreeBSD users: Before Perl
165 v5.16.0 perl would emulate POSIX semantics on Linux systems
166 using LinuxThreads, a partial implementation of POSIX Threads
167 that has since been superseded by the Native POSIX Thread
168 Library (NPTL).
169 LinuxThreads is now obsolete on Linux, and caching "getpid()"
171 like this made embedding perl unnecessarily complex (since
172 you'd have to manually update the value of $$), so now $$ and
173 "getppid()" will always return the same values as the
174 underlying C library.
175 Debian GNU/kFreeBSD systems also used LinuxThreads up until and
177 including the 6.0 release, but after that moved to FreeBSD
178 thread semantics, which are POSIX-like.
179 To see if your system is affected by this discrepancy check if
181 "getconf GNU_LIBPTHREAD_VERSION | grep -q NPTL" returns a false
182 value. NTPL threads preserve the POSIX semantics.
183 Mnemonic: same as shells.
185 $PROGRAM_NAME
187 $0 Contains the name of the program being executed.
188 On some (but not all) operating systems assigning to $0
190 modifies the argument area that the "ps" program sees. On some
191 platforms you may have to use special "ps" options or a
192 different "ps" to see the changes. Modifying the $0 is more
193 useful as a way of indicating the current program state than it
194 is for hiding the program you're running.
195 Note that there are platform-specific limitations on the
197 maximum length of $0. In the most extreme case it may be
198 limited to the space occupied by the original $0.
199 In some platforms there may be arbitrary amount of padding, for
201 example space characters, after the modified name as shown by
202 "ps". In some platforms this padding may extend all the way to
203 the original length of the argument area, no matter what you do
204 (this is the case for example with Linux 2.2).
205 Note for BSD users: setting $0 does not completely remove
207 "perl" from the ps(1) output. For example, setting $0 to
208 "foobar" may result in "perl: foobar (perl)" (whether both the
209 "perl: " prefix and the " (perl)" suffix are shown depends on
210 your exact BSD variant and version). This is an operating
211 system feature, Perl cannot help it.
212 In multithreaded scripts Perl coordinates the threads so that
214 any thread may modify its copy of the $0 and the change becomes
215 visible to ps(1) (assuming the operating system plays along).
216 Note that the view of $0 the other threads have will not change
217 since they have their own copies of it.
218 If the program has been given to perl via the switches "-e" or
220 "-E", $0 will contain the string "-e".
221 On Linux as of perl v5.14.0 the legacy process name will be set
223 with prctl(2), in addition to altering the POSIX name via
224 "argv[0]" as perl has done since version 4.000. Now system
225 utilities that read the legacy process name such as ps, top and
226 killall will recognize the name you set when assigning to $0.
227 The string you supply will be cut off at 16 bytes, this is a
228 limitation imposed by Linux.
229 Mnemonic: same as sh and ksh.
231 $REAL_GROUP_ID
233 $GID
234 $( The real gid of this process. If you are on a machine that
235 supports membership in multiple groups simultaneously, gives a
236 space separated list of groups you are in. The first number is
237 the one returned by "getgid()", and the subsequent ones by
238 "getgroups()", one of which may be the same as the first
239 number.
240 However, a value assigned to $( must be a single number used to
242 set the real gid. So the value given by $( should not be
243 assigned back to $( without being forced numeric, such as by
244 adding zero. Note that this is different to the effective gid
245 ($)) which does take a list.
246 You can change both the real gid and the effective gid at the
248 same time by using "POSIX::setgid()". Changes to $( require a
249 check to $! to detect any possible errors after an attempted
250 change.
251 Mnemonic: parentheses are used to group things. The real gid
253 is the group you left, if you're running setgid.
254 $EFFECTIVE_GROUP_ID
256 $EGID
257 $) The effective gid of this process. If you are on a machine
258 that supports membership in multiple groups simultaneously,
259 gives a space separated list of groups you are in. The first
260 number is the one returned by "getegid()", and the subsequent
261 ones by "getgroups()", one of which may be the same as the
262 first number.
263 Similarly, a value assigned to $) must also be a space-
265 separated list of numbers. The first number sets the effective
266 gid, and the rest (if any) are passed to "setgroups()". To get
267 the effect of an empty list for "setgroups()", just repeat the
268 new effective gid; that is, to force an effective gid of 5 and
269 an effectively empty "setgroups()" list, say " $) = "5 5" ".
270 You can change both the effective gid and the real gid at the
272 same time by using "POSIX::setgid()" (use only a single numeric
273 argument). Changes to $) require a check to $! to detect any
274 possible errors after an attempted change.
275 $<, $>, $( and $) can be set only on machines that support the
277 corresponding set[re][ug]id() routine. $( and $) can be
278 swapped only on machines supporting "setregid()".
279 Mnemonic: parentheses are used to group things. The effective
281 gid is the group that's right for you, if you're running
282 setgid.
283 $REAL_USER_ID
285 $UID
286 $< The real uid of this process. You can change both the real uid
287 and the effective uid at the same time by using
288 "POSIX::setuid()". Since changes to $< require a system call,
289 check $! after a change attempt to detect any possible errors.
290 Mnemonic: it's the uid you came from, if you're running setuid.
292 $EFFECTIVE_USER_ID
294 $EUID
295 $> The effective uid of this process. For example:
296 $< = $>; # set real to effective uid
298 ($<,$>) = ($>,$<); # swap real and effective uids
299 You can change both the effective uid and the real uid at the
301 same time by using "POSIX::setuid()". Changes to $> require a
302 check to $! to detect any possible errors after an attempted
303 change.
304 $< and $> can be swapped only on machines supporting
306 "setreuid()".
307 Mnemonic: it's the uid you went to, if you're running setuid.
309 $SUBSCRIPT_SEPARATOR
311 $SUBSEP
312 $; The subscript separator for multidimensional array emulation.
313 If you refer to a hash element as
314 $foo{$x,$y,$z}
316 it really means
318 $foo{join($;, $x, $y, $z)}
320 But don't put
322 @foo{$x,$y,$z} # a slice--note the @
324 which means
326 ($foo{$x},$foo{$y},$foo{$z})
328 Default is "\034", the same as SUBSEP in awk. If your keys
330 contain binary data there might not be any safe value for $;.
331 Consider using "real" multidimensional arrays as described in
333 perllol.
334 Mnemonic: comma (the syntactic subscript separator) is a semi-
336 semicolon.
337 $a
339 $b Special package variables when using "sort()", see "sort" in
340 perlfunc. Because of this specialness $a and $b don't need to
341 be declared (using "use vars", or "our()") even when using the
342 "strict 'vars'" pragma. Don't lexicalize them with "my $a" or
343 "my $b" if you want to be able to use them in the "sort()"
344 comparison block or function.
345 %ENV The hash %ENV contains your current environment. Setting a
347 value in "ENV" changes the environment for any child processes
348 you subsequently "fork()" off.
349 As of v5.18.0, both keys and values stored in %ENV are
351 stringified.
352 my $foo = 1;
354 $ENV{'bar'} = \$foo;
355 if( ref $ENV{'bar'} ) {
356 say "Pre 5.18.0 Behaviour";
357 } else {
358 say "Post 5.18.0 Behaviour";
359 }
360 Previously, only child processes received stringified values:
362 my $foo = 1;
364 $ENV{'bar'} = \$foo;
365 # Always printed 'non ref'
367 system($^X, '-e',
368 q/print ( ref $ENV{'bar'} ? 'ref' : 'non ref' ) /);
369 This happens because you can't really share arbitrary data
371 structures with foreign processes.
372 $OLD_PERL_VERSION
374 $] The revision, version, and subversion of the Perl interpreter,
375 represented as a decimal of the form 5.XXXYYY, where XXX is the
376 version / 1e3 and YYY is the subversion / 1e6. For example,
377 Perl v5.10.1 would be "5.010001".
378 This variable can be used to determine whether the Perl
380 interpreter executing a script is in the right range of
381 versions:
382 warn "No PerlIO!\n" if $] lt '5.008';
384 When comparing $], string comparison operators are highly
386 recommended. The inherent limitations of binary floating point
387 representation can sometimes lead to incorrect comparisons for
388 some numbers on some architectures.
389 See also the documentation of "use VERSION" and "require
391 VERSION" for a convenient way to fail if the running Perl
392 interpreter is too old.
393 See "$^V" for a representation of the Perl version as a version
395 object, which allows more flexible string comparisons.
396 The main advantage of $] over $^V is that it works the same on
398 any version of Perl. The disadvantages are that it can't
399 easily be compared to versions in other formats (e.g. literal
400 v-strings, "v1.2.3" or version objects) and numeric comparisons
401 can occasionally fail; it's good for string literal version
402 checks and bad for comparing to a variable that hasn't been
403 sanity-checked.
404 The $OLD_PERL_VERSION form was added in Perl v5.20.0 for
406 historical reasons but its use is discouraged. (If your reason
407 to use $] is to run code on old perls then referring to it as
408 $OLD_PERL_VERSION would be self-defeating.)
409 Mnemonic: Is this version of perl in the right bracket?
411 $SYSTEM_FD_MAX
413 $^F The maximum system file descriptor, ordinarily 2. System file
414 descriptors are passed to "exec()"ed processes, while higher
415 file descriptors are not. Also, during an "open()", system
416 file descriptors are preserved even if the "open()" fails
417 (ordinary file descriptors are closed before the "open()" is
418 attempted). The close-on-exec status of a file descriptor will
419 be decided according to the value of $^F when the corresponding
420 file, pipe, or socket was opened, not the time of the "exec()".
421 @F The array @F contains the fields of each line read in when
423 autosplit mode is turned on. See perlrun for the -a switch.
424 This array is package-specific, and must be declared or given a
425 full package name if not in package main when running under
426 "strict 'vars'".
427 @INC The array @INC contains the list of places that the "do EXPR",
429 "require", or "use" constructs look for their library files.
430 It initially consists of the arguments to any -I command-line
431 switches, followed by the default Perl library, probably
432 /usr/local/lib/perl, followed by ".", to represent the current
433 directory. ("." will not be appended if taint checks are
434 enabled, either by "-T" or by "-t", or if configured not to do
435 so by the "-Ddefault_inc_excludes_dot" compile time option.)
436 If you need to modify this at runtime, you should use the "use
437 lib" pragma to get the machine-dependent library properly
438 loaded also:
439 use lib '/mypath/libdir/';
441 use SomeMod;
442 You can also insert hooks into the file inclusion system by
444 putting Perl code directly into @INC. Those hooks may be
445 subroutine references, array references or blessed objects.
446 See "require" in perlfunc for details.
447 %INC The hash %INC contains entries for each filename included via
449 the "do", "require", or "use" operators. The key is the
450 filename you specified (with module names converted to
451 pathnames), and the value is the location of the file found.
452 The "require" operator uses this hash to determine whether a
453 particular file has already been included.
454 If the file was loaded via a hook (e.g. a subroutine reference,
456 see "require" in perlfunc for a description of these hooks),
457 this hook is by default inserted into %INC in place of a
458 filename. Note, however, that the hook may have set the %INC
459 entry by itself to provide some more specific info.
460 $INPLACE_EDIT
462 $^I The current value of the inplace-edit extension. Use "undef"
463 to disable inplace editing.
464 Mnemonic: value of -i switch.
466 @ISA Each package contains a special array called @ISA which
468 contains a list of that class's parent classes, if any. This
469 array is simply a list of scalars, each of which is a string
470 that corresponds to a package name. The array is examined when
471 Perl does method resolution, which is covered in perlobj.
472 To load packages while adding them to @ISA, see the parent
474 pragma. The discouraged base pragma does this as well, but
475 should not be used except when compatibility with the
476 discouraged fields pragma is required.
477 $^M By default, running out of memory is an untrappable, fatal
479 error. However, if suitably built, Perl can use the contents
480 of $^M as an emergency memory pool after "die()"ing. Suppose
481 that your Perl were compiled with "-DPERL_EMERGENCY_SBRK" and
482 used Perl's malloc. Then
483 $^M = 'a' x (1 << 16);
485 would allocate a 64K buffer for use in an emergency. See the
487 INSTALL file in the Perl distribution for information on how to
488 add custom C compilation flags when compiling perl. To
489 discourage casual use of this advanced feature, there is no
490 English long name for this variable.
491 This variable was added in Perl 5.004.
493 $OSNAME
495 $^O The name of the operating system under which this copy of Perl
496 was built, as determined during the configuration process. For
497 examples see "PLATFORMS" in perlport.
498 The value is identical to $Config{'osname'}. See also Config
500 and the -V command-line switch documented in perlrun.
501 In Windows platforms, $^O is not very helpful: since it is
503 always "MSWin32", it doesn't tell the difference between
504 95/98/ME/NT/2000/XP/CE/.NET. Use "Win32::GetOSName()" or
505 Win32::GetOSVersion() (see Win32 and perlport) to distinguish
506 between the variants.
507 This variable was added in Perl 5.003.
509 %SIG The hash %SIG contains signal handlers for signals. For
511 example:
512 sub handler { # 1st argument is signal name
514 my($sig) = @_;
515 print "Caught a SIG$sig--shutting down\n";
516 close(LOG);
517 exit(0);
518 }
519 $SIG{'INT'} = \&handler;
521 $SIG{'QUIT'} = \&handler;
522 ...
523 $SIG{'INT'} = 'DEFAULT'; # restore default action
524 $SIG{'QUIT'} = 'IGNORE'; # ignore SIGQUIT
525 Using a value of 'IGNORE' usually has the effect of ignoring
527 the signal, except for the "CHLD" signal. See perlipc for more
528 about this special case.
529 Here are some other examples:
531 $SIG{"PIPE"} = "Plumber"; # assumes main::Plumber (not
533 # recommended)
534 $SIG{"PIPE"} = \&Plumber; # just fine; assume current
535 # Plumber
536 $SIG{"PIPE"} = *Plumber; # somewhat esoteric
537 $SIG{"PIPE"} = Plumber(); # oops, what did Plumber()
538 # return??
539 Be sure not to use a bareword as the name of a signal handler,
541 lest you inadvertently call it.
542 If your system has the "sigaction()" function then signal
544 handlers are installed using it. This means you get reliable
545 signal handling.
546 The default delivery policy of signals changed in Perl v5.8.0
548 from immediate (also known as "unsafe") to deferred, also known
549 as "safe signals". See perlipc for more information.
550 Certain internal hooks can be also set using the %SIG hash.
552 The routine indicated by $SIG{__WARN__} is called when a
553 warning message is about to be printed. The warning message is
554 passed as the first argument. The presence of a "__WARN__"
555 hook causes the ordinary printing of warnings to "STDERR" to be
556 suppressed. You can use this to save warnings in a variable,
557 or turn warnings into fatal errors, like this:
558 local $SIG{__WARN__} = sub { die $_[0] };
560 eval $proggie;
561 As the 'IGNORE' hook is not supported by "__WARN__", you can
563 disable warnings using 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 "__DIE__"/"__WARN__" handlers are very special in one respect:
585 they may be called to report (probable) errors found by the
586 parser. In such a case the parser may be in inconsistent
587 state, so any attempt to evaluate Perl code from such a handler
588 will probably result in a segfault. This means that warnings
589 or errors that result from parsing Perl should be used with
590 extreme caution, like this:
591 require Carp if defined $^S;
593 Carp::confess("Something wrong") if defined &Carp::confess;
594 die "Something wrong, but could not load Carp to give "
595 . "backtrace...\n\t"
596 . "To see backtrace try starting Perl with -MCarp switch";
597 Here the first line will load "Carp" unless it is the parser
599 who called the handler. The second line will print backtrace
600 and die if "Carp" was available. The third line will be
601 executed only if "Carp" was not available.
602 Having to even think about the $^S variable in your exception
604 handlers is simply wrong. $SIG{__DIE__} as currently
605 implemented invites grievous and difficult to track down
606 errors. Avoid it and use an "END{}" or CORE::GLOBAL::die
607 override instead.
608 See "die" in perlfunc, "warn" in perlfunc, "eval" in perlfunc,
610 and warnings for additional information.
611 $BASETIME
613 $^T The time at which the program began running, in seconds since
614 the epoch (beginning of 1970). The values returned by the -M,
615 -A, and -C filetests are based on this value.
616 $PERL_VERSION
618 $^V The revision, version, and subversion of the Perl interpreter,
619 represented as a version object.
620 This variable first appeared in perl v5.6.0; earlier versions
622 of perl will see an undefined value. Before perl v5.10.0 $^V
623 was represented as a v-string rather than a version object.
624 $^V can be used to determine whether the Perl interpreter
626 executing a script is in the right range of versions. For
627 example:
628 warn "Hashes not randomized!\n" if !$^V or $^V lt v5.8.1
630 While version objects overload stringification, to portably
632 convert $^V into its string representation, use "sprintf()"'s
633 "%vd" conversion, which works for both v-strings or version
634 objects:
635 printf "version is v%vd\n", $^V; # Perl's version
637 See the documentation of "use VERSION" and "require VERSION"
639 for a convenient way to fail if the running Perl interpreter is
640 too old.
641 See also "$]" for a decimal representation of the Perl version.
643 The main advantage of $^V over $] is that, for Perl v5.10.0 or
645 later, it overloads operators, allowing easy comparison against
646 other version representations (e.g. decimal, literal v-string,
647 "v1.2.3", or objects). The disadvantage is that prior to
648 v5.10.0, it was only a literal v-string, which can't be easily
649 printed or compared, whereas the behavior of $] is unchanged on
650 all versions of Perl.
651 Mnemonic: use ^V for a version object.
653 ${^WIN32_SLOPPY_STAT}
655 If this variable is set to a true value, then "stat()" on
656 Windows will not try to open the file. This means that the
657 link count cannot be determined and file attributes may be out
658 of date if additional hardlinks to the file exist. On the
659 other hand, not opening the file is considerably faster,
660 especially for files on network drives.
661 This variable could be set in the sitecustomize.pl file to
663 configure the local Perl installation to use "sloppy" "stat()"
664 by default. See the documentation for -f in perlrun for more
665 information about site customization.
666 This variable was added in Perl v5.10.0.
668 $EXECUTABLE_NAME
670 $^X The name used to execute the current copy of Perl, from C's
671 "argv[0]" or (where supported) /proc/self/exe.
672 Depending on the host operating system, the value of $^X may be
674 a relative or absolute pathname of the perl program file, or
675 may be the string used to invoke perl but not the pathname of
676 the perl program file. Also, most operating systems permit
677 invoking programs that are not in the PATH environment
678 variable, so there is no guarantee that the value of $^X is in
679 PATH. For VMS, the value may or may not include a version
680 number.
681 You usually can use the value of $^X to re-invoke an
683 independent copy of the same perl that is currently running,
684 e.g.,
685 @first_run = `$^X -le "print int rand 100 for 1..100"`;
687 But recall that not all operating systems support forking or
689 capturing of the output of commands, so this complex statement
690 may not be portable.
691 It is not safe to use the value of $^X as a path name of a
693 file, as some operating systems that have a mandatory suffix on
694 executable files do not require use of the suffix when invoking
695 a command. To convert the value of $^X to a path name, use the
696 following statements:
697 # Build up a set of file names (not command names).
699 use Config;
700 my $this_perl = $^X;
701 if ($^O ne 'VMS') {
702 $this_perl .= $Config{_exe}
703 unless $this_perl =~ m/$Config{_exe}$/i;
704 }
705 Because many operating systems permit anyone with read access
707 to the Perl program file to make a copy of it, patch the copy,
708 and then execute the copy, the security-conscious Perl
709 programmer should take care to invoke the installed copy of
710 perl, not the copy referenced by $^X. The following statements
711 accomplish this goal, and produce a pathname that can be
712 invoked as a command or referenced as a file.
713 use Config;
715 my $secure_perl_path = $Config{perlpath};
716 if ($^O ne 'VMS') {
717 $secure_perl_path .= $Config{_exe}
718 unless $secure_perl_path =~ m/$Config{_exe}$/i;
719 }
720 Variables related to regular expressions
722 Most of the special variables related to regular expressions are side
723 effects. Perl sets these variables when it has a successful match, so
724 you should check the match result before using them. For instance:
725 if( /P(A)TT(ER)N/ ) {
727 print "I found $1 and $2\n";
728 }
729 These variables are read-only and dynamically-scoped, unless we note
731 otherwise.
732 The dynamic nature of the regular expression variables means that their
734 value is limited to the block that they are in, as demonstrated by this
735 bit of code:
736 my $outer = 'Wallace and Grommit';
738 my $inner = 'Mutt and Jeff';
739 my $pattern = qr/(\S+) and (\S+)/;
741 sub show_n { print "\$1 is $1; \$2 is $2\n" }
743 {
745 OUTER:
746 show_n() if $outer =~ m/$pattern/;
747 INNER: {
749 show_n() if $inner =~ m/$pattern/;
750 }
751 show_n();
753 }
754 The output shows that while in the "OUTER" block, the values of $1 and
756 $2 are from the match against $outer. Inside the "INNER" block, the
757 values of $1 and $2 are from the match against $inner, but only until
758 the end of the block (i.e. the dynamic scope). After the "INNER" block
759 completes, the values of $1 and $2 return to the values for the match
760 against $outer even though we have not made another match:
761 $1 is Wallace; $2 is Grommit
763 $1 is Mutt; $2 is Jeff
764 $1 is Wallace; $2 is Grommit
765 Performance issues
767 Traditionally in Perl, any use of any of the three variables "$`", $&
769 or "$'" (or their "use English" equivalents) anywhere in the code,
770 caused all subsequent successful pattern matches to make a copy of the
771 matched string, in case the code might subsequently access one of those
772 variables. This imposed a considerable performance penalty across the
773 whole program, so generally the use of these variables has been
774 discouraged.
775 In Perl 5.6.0 the "@-" and "@+" dynamic arrays were introduced that
777 supply the indices of successful matches. So you could for example do
778 this:
779 $str =~ /pattern/;
781 print $`, $&, $'; # bad: perfomance hit
783 print # good: no perfomance hit
785 substr($str, 0, $-[0]),
786 substr($str, $-[0], $+[0]-$-[0]),
787 substr($str, $+[0]);
788 In Perl 5.10.0 the "/p" match operator flag and the "${^PREMATCH}",
790 "${^MATCH}", and "${^POSTMATCH}" variables were introduced, that
791 allowed you to suffer the penalties only on patterns marked with "/p".
792 In Perl 5.18.0 onwards, perl started noting the presence of each of the
794 three variables separately, and only copied that part of the string
795 required; so in
796 $`; $&; "abcdefgh" =~ /d/
798 perl would only copy the "abcd" part of the string. That could make a
800 big difference in something like
801 $str = 'x' x 1_000_000;
803 $&; # whoops
804 $str =~ /x/g # one char copied a million times, not a million chars
805 In Perl 5.20.0 a new copy-on-write system was enabled by default, which
807 finally fixes all performance issues with these three variables, and
808 makes them safe to use anywhere.
809 The "Devel::NYTProf" and "Devel::FindAmpersand" modules can help you
811 find uses of these problematic match variables in your code.
812 $<digits> ($1, $2, ...)
814 Contains the subpattern from the corresponding set of capturing
815 parentheses from the last successful pattern match, not
816 counting patterns matched in nested blocks that have been
817 exited already.
818 Note there is a distinction between a capture buffer which
820 matches the empty string a capture buffer which is optional.
821 Eg, "(x?)" and "(x)?" The latter may be undef, the former not.
822 These variables are read-only and dynamically-scoped.
824 Mnemonic: like \digits.
826 @{^CAPTURE}
828 An array which exposes the contents of the capture buffers, if
829 any, of the last successful pattern match, not counting
830 patterns matched in nested blocks that have been exited
831 already.
832 Note that the 0 index of @{^CAPTURE} is equivalent to $1, the 1
834 index is equivalent to $2, etc.
835 if ("foal"=~/(.)(.)(.)(.)/) {
837 print join "-", @{^CAPTURE};
838 }
839 should output "f-o-a-l".
841 See also "$digits", "%{^CAPTURE}" and "%{^CAPTURE_ALL}".
843 Note that unlike most other regex magic variables there is no
845 single letter equivalent to "@{^CAPTURE}".
846 This variable was added in 5.25.7
848 $MATCH
850 $& The string matched by the last successful pattern match (not
851 counting any matches hidden within a BLOCK or "eval()" enclosed
852 by the current BLOCK).
853 See "Performance issues" above for the serious performance
855 implications of using this variable (even once) in your code.
856 This variable is read-only and dynamically-scoped.
858 Mnemonic: like "&" in some editors.
860 ${^MATCH}
862 This is similar to $& ($MATCH) except that it does not incur
863 the performance penalty associated with that variable.
864 See "Performance issues" above.
866 In Perl v5.18 and earlier, it is only guaranteed to return a
868 defined value when the pattern was compiled or executed with
869 the "/p" modifier. In Perl v5.20, the "/p" modifier does
870 nothing, so "${^MATCH}" does the same thing as $MATCH.
871 This variable was added in Perl v5.10.0.
873 This variable is read-only and dynamically-scoped.
875 $PREMATCH
877 $` The string preceding whatever was matched by the last
878 successful pattern match, not counting any matches hidden
879 within a BLOCK or "eval" enclosed by the current BLOCK.
880 See "Performance issues" above for the serious performance
882 implications of using this variable (even once) in your code.
883 This variable is read-only and dynamically-scoped.
885 Mnemonic: "`" often precedes a quoted string.
887 ${^PREMATCH}
889 This is similar to "$`" ($PREMATCH) except that it does not
890 incur the performance penalty associated with that variable.
891 See "Performance issues" above.
893 In Perl v5.18 and earlier, it is only guaranteed to return a
895 defined value when the pattern was compiled or executed with
896 the "/p" modifier. In Perl v5.20, the "/p" modifier does
897 nothing, so "${^PREMATCH}" does the same thing as $PREMATCH.
898 This variable was added in Perl v5.10.0.
900 This variable is read-only and dynamically-scoped.
902 $POSTMATCH
904 $' The string following whatever was matched by the last
905 successful pattern match (not counting any matches hidden
906 within a BLOCK or "eval()" enclosed by the current BLOCK).
907 Example:
908 local $_ = 'abcdefghi';
910 /def/;
911 print "$`:$&:$'\n"; # prints abc:def:ghi
912 See "Performance issues" above for the serious performance
914 implications of using this variable (even once) in your code.
915 This variable is read-only and dynamically-scoped.
917 Mnemonic: "'" often follows a quoted string.
919 ${^POSTMATCH}
921 This is similar to "$'" ($POSTMATCH) except that it does not
922 incur the performance penalty associated with that variable.
923 See "Performance issues" above.
925 In Perl v5.18 and earlier, it is only guaranteed to return a
927 defined value when the pattern was compiled or executed with
928 the "/p" modifier. In Perl v5.20, the "/p" modifier does
929 nothing, so "${^POSTMATCH}" does the same thing as $POSTMATCH.
930 This variable was added in Perl v5.10.0.
932 This variable is read-only and dynamically-scoped.
934 $LAST_PAREN_MATCH
936 $+ The text matched by the last bracket of the last successful
937 search pattern. This is useful if you don't know which one of
938 a set of alternative patterns matched. For example:
939 /Version: (.*)|Revision: (.*)/ && ($rev = $+);
941 This variable is read-only and dynamically-scoped.
943 Mnemonic: be positive and forward looking.
945 $LAST_SUBMATCH_RESULT
947 $^N The text matched by the used group most-recently closed (i.e.
948 the group with the rightmost closing parenthesis) of the last
949 successful search pattern.
950 This is primarily used inside "(?{...})" blocks for examining
952 text recently matched. For example, to effectively capture
953 text to a variable (in addition to $1, $2, etc.), replace
954 "(...)" with
955 (?:(...)(?{ $var = $^N }))
957 By setting and then using $var in this way relieves you from
959 having to worry about exactly which numbered set of parentheses
960 they are.
961 This variable was added in Perl v5.8.0.
963 Mnemonic: the (possibly) Nested parenthesis that most recently
965 closed.
966 @LAST_MATCH_END
968 @+ This array holds the offsets of the ends of the last successful
969 submatches in the currently active dynamic scope. $+[0] is the
970 offset into the string of the end of the entire match. This is
971 the same value as what the "pos" function returns when called
972 on the variable that was matched against. The nth element of
973 this array holds the offset of the nth submatch, so $+[1] is
974 the offset past where $1 ends, $+[2] the offset past where $2
975 ends, and so on. You can use $#+ to determine how many
976 subgroups were in the last successful match. See the examples
977 given for the "@-" variable.
978 This variable was added in Perl v5.6.0.
980 %{^CAPTURE}
982 %LAST_PAREN_MATCH
983 %+ Similar to "@+", the "%+" hash allows access to the named
984 capture buffers, should they exist, in the last successful
985 match in the currently active dynamic scope.
986 For example, $+{foo} is equivalent to $1 after the following
988 match:
989 'foo' =~ /(?<foo>foo)/;
991 The keys of the "%+" hash list only the names of buffers that
993 have captured (and that are thus associated to defined values).
994 The underlying behaviour of "%+" is provided by the
996 Tie::Hash::NamedCapture module.
997 Note: "%-" and "%+" are tied views into a common internal hash
999 associated with the last successful regular expression.
1000 Therefore mixing iterative access to them via "each" may have
1001 unpredictable results. Likewise, if the last successful match
1002 changes, then the results may be surprising.
1003 This variable was added in Perl v5.10.0. The "%{^CAPTURE}"
1005 alias was added in 5.25.7.
1006 This variable is read-only and dynamically-scoped.
1008 @LAST_MATCH_START
1010 @- "$-[0]" is the offset of the start of the last successful
1011 match. "$-["n"]" is the offset of the start of the substring
1012 matched by n-th subpattern, or undef if the subpattern did not
1013 match.
1014 Thus, after a match against $_, $& coincides with "substr $_,
1016 $-[0], $+[0] - $-[0]". Similarly, $n coincides with "substr
1017 $_, $-[n], $+[n] - $-[n]" if "$-[n]" is defined, and $+
1018 coincides with "substr $_, $-[$#-], $+[$#-] - $-[$#-]". One
1019 can use "$#-" to find the last matched subgroup in the last
1020 successful match. Contrast with $#+, the number of subgroups
1021 in the regular expression. Compare with "@+".
1022 This array holds the offsets of the beginnings of the last
1024 successful submatches in the currently active dynamic scope.
1025 "$-[0]" is the offset into the string of the beginning of the
1026 entire match. The nth element of this array holds the offset
1027 of the nth submatch, so "$-[1]" is the offset where $1 begins,
1028 "$-[2]" the offset where $2 begins, and so on.
1029 After a match against some variable $var:
1031 "$`" is the same as "substr($var, 0, $-[0])"
1033 $& is the same as "substr($var, $-[0], $+[0] - $-[0])"
1034 "$'" is the same as "substr($var, $+[0])"
1035 $1 is the same as "substr($var, $-[1], $+[1] - $-[1])"
1036 $2 is the same as "substr($var, $-[2], $+[2] - $-[2])"
1037 $3 is the same as "substr($var, $-[3], $+[3] - $-[3])"
1038 This variable was added in Perl v5.6.0.
1040 %{^CAPTURE_ALL}
1042 %- Similar to "%+", this variable allows access to the named
1043 capture groups in the last successful match in the currently
1044 active dynamic scope. To each capture group name found in the
1045 regular expression, it associates a reference to an array
1046 containing the list of values captured by all buffers with that
1047 name (should there be several of them), in the order where they
1048 appear.
1049 Here's an example:
1051 if ('1234' =~ /(?<A>1)(?<B>2)(?<A>3)(?<B>4)/) {
1053 foreach my $bufname (sort keys %-) {
1054 my $ary = $-{$bufname};
1055 foreach my $idx (0..$#$ary) {
1056 print "\$-{$bufname}[$idx] : ",
1057 (defined($ary->[$idx])
1058 ? "'$ary->[$idx]'"
1059 : "undef"),
1060 "\n";
1061 }
1062 }
1063 }
1064 would print out:
1066 $-{A}[0] : '1'
1068 $-{A}[1] : '3'
1069 $-{B}[0] : '2'
1070 $-{B}[1] : '4'
1071 The keys of the "%-" hash correspond to all buffer names found
1073 in the regular expression.
1074 The behaviour of "%-" is implemented via the
1076 Tie::Hash::NamedCapture module.
1077 Note: "%-" and "%+" are tied views into a common internal hash
1079 associated with the last successful regular expression.
1080 Therefore mixing iterative access to them via "each" may have
1081 unpredictable results. Likewise, if the last successful match
1082 changes, then the results may be surprising.
1083 This variable was added in Perl v5.10.0. The "%{^CAPTURE_ALL}"
1085 alias was added in 5.25.7.
1086 This variable is read-only and dynamically-scoped.
1088 $LAST_REGEXP_CODE_RESULT
1090 $^R The result of evaluation of the last successful "(?{ code })"
1091 regular expression assertion (see perlre). May be written to.
1092 This variable was added in Perl 5.005.
1094 ${^RE_DEBUG_FLAGS}
1096 The current value of the regex debugging flags. Set to 0 for
1097 no debug output even when the "re 'debug'" module is loaded.
1098 See re for details.
1099 This variable was added in Perl v5.10.0.
1101 ${^RE_TRIE_MAXBUF}
1103 Controls how certain regex optimisations are applied and how
1104 much memory they utilize. This value by default is 65536 which
1105 corresponds to a 512kB temporary cache. Set this to a higher
1106 value to trade memory for speed when matching large
1107 alternations. Set it to a lower value if you want the
1108 optimisations to be as conservative of memory as possible but
1109 still occur, and set it to a negative value to prevent the
1110 optimisation and conserve the most memory. Under normal
1111 situations this variable should be of no interest to you.
1112 This variable was added in Perl v5.10.0.
1114 Variables related to filehandles
1116 Variables that depend on the currently selected filehandle may be set
1117 by calling an appropriate object method on the "IO::Handle" object,
1118 although this is less efficient than using the regular built-in
1119 variables. (Summary lines below for this contain the word HANDLE.)
1120 First you must say
1121 use IO::Handle;
1123 after which you may use either
1125 method HANDLE EXPR
1127 or more safely,
1129 HANDLE->method(EXPR)
1131 Each method returns the old value of the "IO::Handle" attribute. The
1133 methods each take an optional EXPR, which, if supplied, specifies the
1134 new value for the "IO::Handle" attribute in question. If not supplied,
1135 most methods do nothing to the current value--except for "autoflush()",
1136 which will assume a 1 for you, just to be different.
1137 Because loading in the "IO::Handle" class is an expensive operation,
1139 you should learn how to use the regular built-in variables.
1140 A few of these variables are considered "read-only". This means that
1142 if you try to assign to this variable, either directly or indirectly
1143 through a reference, you'll raise a run-time exception.
1144 You should be very careful when modifying the default values of most
1146 special variables described in this document. In most cases you want
1147 to localize these variables before changing them, since if you don't,
1148 the change may affect other modules which rely on the default values of
1149 the special variables that you have changed. This is one of the
1150 correct ways to read the whole file at once:
1151 open my $fh, "<", "foo" or die $!;
1153 local $/; # enable localized slurp mode
1154 my $content = <$fh>;
1155 close $fh;
1156 But the following code is quite bad:
1158 open my $fh, "<", "foo" or die $!;
1160 undef $/; # enable slurp mode
1161 my $content = <$fh>;
1162 close $fh;
1163 since some other module, may want to read data from some file in the
1165 default "line mode", so if the code we have just presented has been
1166 executed, the global value of $/ is now changed for any other code
1167 running inside the same Perl interpreter.
1168 Usually when a variable is localized you want to make sure that this
1170 change affects the shortest scope possible. So unless you are already
1171 inside some short "{}" block, you should create one yourself. For
1172 example:
1173 my $content = '';
1175 open my $fh, "<", "foo" or die $!;
1176 {
1177 local $/;
1178 $content = <$fh>;
1179 }
1180 close $fh;
1181 Here is an example of how your own code can go broken:
1183 for ( 1..3 ){
1185 $\ = "\r\n";
1186 nasty_break();
1187 print "$_";
1188 }
1189 sub nasty_break {
1191 $\ = "\f";
1192 # do something with $_
1193 }
1194 You probably expect this code to print the equivalent of
1196 "1\r\n2\r\n3\r\n"
1198 but instead you get:
1200 "1\f2\f3\f"
1202 Why? Because "nasty_break()" modifies "$\" without localizing it first.
1204 The value you set in "nasty_break()" is still there when you return.
1205 The fix is to add "local()" so the value doesn't leak out of
1206 "nasty_break()":
1207 local $\ = "\f";
1209 It's easy to notice the problem in such a short example, but in more
1211 complicated code you are looking for trouble if you don't localize
1212 changes to the special variables.
1213 $ARGV Contains the name of the current file when reading from "<>".
1215 @ARGV The array @ARGV contains the command-line arguments intended
1217 for the script. $#ARGV is generally the number of arguments
1218 minus one, because $ARGV[0] is the first argument, not the
1219 program's command name itself. See "$0" for the command name.
1220 ARGV The special filehandle that iterates over command-line
1222 filenames in @ARGV. Usually written as the null filehandle in
1223 the angle operator "<>". Note that currently "ARGV" only has
1224 its magical effect within the "<>" operator; elsewhere it is
1225 just a plain filehandle corresponding to the last file opened
1226 by "<>". In particular, passing "\*ARGV" as a parameter to a
1227 function that expects a filehandle may not cause your function
1228 to automatically read the contents of all the files in @ARGV.
1229 ARGVOUT The special filehandle that points to the currently open output
1231 file when doing edit-in-place processing with -i. Useful when
1232 you have to do a lot of inserting and don't want to keep
1233 modifying $_. See perlrun for the -i switch.
1234 IO::Handle->output_field_separator( EXPR )
1236 $OUTPUT_FIELD_SEPARATOR
1237 $OFS
1238 $, The output field separator for the print operator. If defined,
1239 this value is printed between each of print's arguments.
1240 Default is "undef".
1241 You cannot call "output_field_separator()" on a handle, only as
1243 a static method. See IO::Handle.
1244 Mnemonic: what is printed when there is a "," in your print
1246 statement.
1247 HANDLE->input_line_number( EXPR )
1249 $INPUT_LINE_NUMBER
1250 $NR
1251 $. Current line number for the last filehandle accessed.
1252 Each filehandle in Perl counts the number of lines that have
1254 been read from it. (Depending on the value of $/, Perl's idea
1255 of what constitutes a line may not match yours.) When a line
1256 is read from a filehandle (via "readline()" or "<>"), or when
1257 "tell()" or "seek()" is called on it, $. becomes an alias to
1258 the line counter for that filehandle.
1259 You can adjust the counter by assigning to $., but this will
1261 not actually move the seek pointer. Localizing $. will not
1262 localize the filehandle's line count. Instead, it will
1263 localize perl's notion of which filehandle $. is currently
1264 aliased to.
1265 $. is reset when the filehandle is closed, but not when an open
1267 filehandle is reopened without an intervening "close()". For
1268 more details, see "I/O Operators" in perlop. Because "<>"
1269 never does an explicit close, line numbers increase across
1270 "ARGV" files (but see examples in "eof" in perlfunc).
1271 You can also use "HANDLE->input_line_number(EXPR)" to access
1273 the line counter for a given filehandle without having to worry
1274 about which handle you last accessed.
1275 Mnemonic: many programs use "." to mean the current line
1277 number.
1278 IO::Handle->input_record_separator( EXPR )
1280 $INPUT_RECORD_SEPARATOR
1281 $RS
1282 $/ The input record separator, newline by default. This
1283 influences Perl's idea of what a "line" is. Works like awk's
1284 RS variable, including treating empty lines as a terminator if
1285 set to the null string (an empty line cannot contain any spaces
1286 or tabs). You may set it to a multi-character string to match
1287 a multi-character terminator, or to "undef" to read through the
1288 end of file. Setting it to "\n\n" means something slightly
1289 different than setting to "", if the file contains consecutive
1290 empty lines. Setting to "" will treat two or more consecutive
1291 empty lines as a single empty line. Setting to "\n\n" will
1292 blindly assume that the next input character belongs to the
1293 next paragraph, even if it's a newline.
1294 local $/; # enable "slurp" mode
1296 local $_ = <FH>; # whole file now here
1297 s/\n[ \t]+/ /g;
1298 Remember: the value of $/ is a string, not a regex. awk has to
1300 be better for something. :-)
1301 Setting $/ to a reference to an integer, scalar containing an
1303 integer, or scalar that's convertible to an integer will
1304 attempt to read records instead of lines, with the maximum
1305 record size being the referenced integer number of characters.
1306 So this:
1307 local $/ = \32768; # or \"32768", or \$var_containing_32768
1309 open my $fh, "<", $myfile or die $!;
1310 local $_ = <$fh>;
1311 will read a record of no more than 32768 characters from $fh.
1313 If you're not reading from a record-oriented file (or your OS
1314 doesn't have record-oriented files), then you'll likely get a
1315 full chunk of data with every read. If a record is larger than
1316 the record size you've set, you'll get the record back in
1317 pieces. Trying to set the record size to zero or less is
1318 deprecated and will cause $/ to have the value of "undef",
1319 which will cause reading in the (rest of the) whole file.
1320 As of 5.19.9 setting $/ to any other form of reference will
1322 throw a fatal exception. This is in preparation for supporting
1323 new ways to set $/ in the future.
1324 On VMS only, record reads bypass PerlIO layers and any
1326 associated buffering, so you must not mix record and non-record
1327 reads on the same filehandle. Record mode mixes with line mode
1328 only when the same buffering layer is in use for both modes.
1329 You cannot call "input_record_separator()" on a handle, only as
1331 a static method. See IO::Handle.
1332 See also "Newlines" in perlport. Also see "$.".
1334 Mnemonic: / delimits line boundaries when quoting poetry.
1336 IO::Handle->output_record_separator( EXPR )
1338 $OUTPUT_RECORD_SEPARATOR
1339 $ORS
1340 $\ The output record separator for the print operator. If
1341 defined, this value is printed after the last of print's
1342 arguments. Default is "undef".
1343 You cannot call "output_record_separator()" on a handle, only
1345 as a static method. See IO::Handle.
1346 Mnemonic: you set "$\" instead of adding "\n" at the end of the
1348 print. Also, it's just like $/, but it's what you get "back"
1349 from Perl.
1350 HANDLE->autoflush( EXPR )
1352 $OUTPUT_AUTOFLUSH
1353 $| If set to nonzero, forces a flush right away and after every
1354 write or print on the currently selected output channel.
1355 Default is 0 (regardless of whether the channel is really
1356 buffered by the system or not; $| tells you only whether you've
1357 asked Perl explicitly to flush after each write). STDOUT will
1358 typically be line buffered if output is to the terminal and
1359 block buffered otherwise. Setting this variable is useful
1360 primarily when you are outputting to a pipe or socket, such as
1361 when you are running a Perl program under rsh and want to see
1362 the output as it's happening. This has no effect on input
1363 buffering. See "getc" in perlfunc for that. See "select" in
1364 perlfunc on how to select the output channel. See also
1365 IO::Handle.
1366 Mnemonic: when you want your pipes to be piping hot.
1368 ${^LAST_FH}
1370 This read-only variable contains a reference to the last-read
1371 filehandle. This is set by "<HANDLE>", "readline", "tell",
1372 "eof" and "seek". This is the same handle that $. and "tell"
1373 and "eof" without arguments use. It is also the handle used
1374 when Perl appends ", <STDIN> line 1" to an error or warning
1375 message.
1376 This variable was added in Perl v5.18.0.
1378 Variables related to formats
1380 The special variables for formats are a subset of those for
1382 filehandles. See perlform for more information about Perl's formats.
1383 $ACCUMULATOR
1385 $^A The current value of the "write()" accumulator for "format()"
1386 lines. A format contains "formline()" calls that put their
1387 result into $^A. After calling its format, "write()" prints
1388 out the contents of $^A and empties. So you never really see
1389 the contents of $^A unless you call "formline()" yourself and
1390 then look at it. See perlform and "formline PICTURE,LIST" in
1391 perlfunc.
1392 IO::Handle->format_formfeed(EXPR)
1394 $FORMAT_FORMFEED
1395 $^L What formats output as a form feed. The default is "\f".
1396 You cannot call "format_formfeed()" on a handle, only as a
1398 static method. See IO::Handle.
1399 HANDLE->format_page_number(EXPR)
1401 $FORMAT_PAGE_NUMBER
1402 $% The current page number of the currently selected output
1403 channel.
1404 Mnemonic: "%" is page number in nroff.
1406 HANDLE->format_lines_left(EXPR)
1408 $FORMAT_LINES_LEFT
1409 $- The number of lines left on the page of the currently selected
1410 output channel.
1411 Mnemonic: lines_on_page - lines_printed.
1413 IO::Handle->format_line_break_characters EXPR
1415 $FORMAT_LINE_BREAK_CHARACTERS
1416 $: The current set of characters after which a string may be
1417 broken to fill continuation fields (starting with "^") in a
1418 format. The default is " \n-", to break on a space, newline,
1419 or a hyphen.
1420 You cannot call "format_line_break_characters()" on a handle,
1422 only as a static method. See IO::Handle.
1423 Mnemonic: a "colon" in poetry is a part of a line.
1425 HANDLE->format_lines_per_page(EXPR)
1427 $FORMAT_LINES_PER_PAGE
1428 $= The current page length (printable lines) of the currently
1429 selected output channel. The default is 60.
1430 Mnemonic: = has horizontal lines.
1432 HANDLE->format_top_name(EXPR)
1434 $FORMAT_TOP_NAME
1435 $^ The name of the current top-of-page format for the currently
1436 selected output channel. The default is the name of the
1437 filehandle with "_TOP" appended. For example, the default
1438 format top name for the "STDOUT" filehandle is "STDOUT_TOP".
1439 Mnemonic: points to top of page.
1441 HANDLE->format_name(EXPR)
1443 $FORMAT_NAME
1444 $~ The name of the current report format for the currently
1445 selected output channel. The default format name is the same
1446 as the filehandle name. For example, the default format name
1447 for the "STDOUT" filehandle is just "STDOUT".
1448 Mnemonic: brother to $^.
1450 Error Variables
1452 The variables $@, $!, $^E, and $? contain information about different
1453 types of error conditions that may appear during execution of a Perl
1454 program. The variables are shown ordered by the "distance" between the
1455 subsystem which reported the error and the Perl process. They
1456 correspond to errors detected by the Perl interpreter, C library,
1457 operating system, or an external program, respectively.
1458 To illustrate the differences between these variables, consider the
1460 following Perl expression, which uses a single-quoted string. After
1461 execution of this statement, perl may have set all four special error
1462 variables:
1463 eval q{
1465 open my $pipe, "/cdrom/install |" or die $!;
1466 my @res = <$pipe>;
1467 close $pipe or die "bad pipe: $?, $!";
1468 };
1469 When perl executes the "eval()" expression, it translates the "open()",
1471 "<PIPE>", and "close" calls in the C run-time library and thence to the
1472 operating system kernel. perl sets $! to the C library's "errno" if
1473 one of these calls fails.
1474 $@ is set if the string to be "eval"-ed did not compile (this may
1476 happen if "open" or "close" were imported with bad prototypes), or if
1477 Perl code executed during evaluation "die()"d. In these cases the
1478 value of $@ is the compile error, or the argument to "die" (which will
1479 interpolate $! and $?). (See also Fatal, though.)
1480 Under a few operating systems, $^E may contain a more verbose error
1482 indicator, such as in this case, "CDROM tray not closed." Systems that
1483 do not support extended error messages leave $^E the same as $!.
1484 Finally, $? may be set to a non-0 value if the external program
1486 /cdrom/install fails. The upper eight bits reflect specific error
1487 conditions encountered by the program (the program's "exit()" value).
1488 The lower eight bits reflect mode of failure, like signal death and
1489 core dump information. See wait(2) for details. In contrast to $! and
1490 $^E, which are set only if an error condition is detected, the variable
1491 $? is set on each "wait" or pipe "close", overwriting the old value.
1492 This is more like $@, which on every "eval()" is always set on failure
1493 and cleared on success.
1494 For more details, see the individual descriptions at $@, $!, $^E, and
1496 $?.
1497 ${^CHILD_ERROR_NATIVE}
1499 The native status returned by the last pipe close, backtick
1500 ("``") command, successful call to "wait()" or "waitpid()", or
1501 from the "system()" operator. On POSIX-like systems this value
1502 can be decoded with the WIFEXITED, WEXITSTATUS, WIFSIGNALED,
1503 WTERMSIG, WIFSTOPPED, WSTOPSIG and WIFCONTINUED functions
1504 provided by the POSIX module.
1505 Under VMS this reflects the actual VMS exit status; i.e. it is
1507 the same as $? when the pragma "use vmsish 'status'" is in
1508 effect.
1509 This variable was added in Perl v5.10.0.
1511 $EXTENDED_OS_ERROR
1513 $^E Error information specific to the current operating system. At
1514 the moment, this differs from "$!" under only VMS, OS/2, and
1515 Win32 (and for MacPerl). On all other platforms, $^E is always
1516 just the same as $!.
1517 Under VMS, $^E provides the VMS status value from the last
1519 system error. This is more specific information about the last
1520 system error than that provided by $!. This is particularly
1521 important when $! is set to EVMSERR.
1522 Under OS/2, $^E is set to the error code of the last call to
1524 OS/2 API either via CRT, or directly from perl.
1525 Under Win32, $^E always returns the last error information
1527 reported by the Win32 call "GetLastError()" which describes the
1528 last error from within the Win32 API. Most Win32-specific code
1529 will report errors via $^E. ANSI C and Unix-like calls set
1530 "errno" and so most portable Perl code will report errors via
1531 $!.
1532 Caveats mentioned in the description of "$!" generally apply to
1534 $^E, also.
1535 This variable was added in Perl 5.003.
1537 Mnemonic: Extra error explanation.
1539 $EXCEPTIONS_BEING_CAUGHT
1541 $^S Current state of the interpreter.
1542 $^S State
1544 --------- -------------------------------------
1545 undef Parsing module, eval, or main program
1546 true (1) Executing an eval
1547 false (0) Otherwise
1548 The first state may happen in $SIG{__DIE__} and $SIG{__WARN__}
1550 handlers.
1551 The English name $EXCEPTIONS_BEING_CAUGHT is slightly
1553 misleading, because the "undef" value does not indicate whether
1554 exceptions are being caught, since compilation of the main
1555 program does not catch exceptions.
1556 This variable was added in Perl 5.004.
1558 $WARNING
1560 $^W The current value of the warning switch, initially true if -w
1561 was used, false otherwise, but directly modifiable.
1562 See also warnings.
1564 Mnemonic: related to the -w switch.
1566 ${^WARNING_BITS}
1568 The current set of warning checks enabled by the "use warnings"
1569 pragma. It has the same scoping as the $^H and "%^H"
1570 variables. The exact values are considered internal to the
1571 warnings pragma and may change between versions of Perl.
1572 This variable was added in Perl v5.6.0.
1574 $OS_ERROR
1576 $ERRNO
1577 $! When referenced, $! retrieves the current value of the C
1578 "errno" integer variable. If $! is assigned a numerical value,
1579 that value is stored in "errno". When referenced as a string,
1580 $! yields the system error string corresponding to "errno".
1581 Many system or library calls set "errno" if they fail, to
1583 indicate the cause of failure. They usually do not set "errno"
1584 to zero if they succeed. This means "errno", hence $!, is
1585 meaningful only immediately after a failure:
1586 if (open my $fh, "<", $filename) {
1588 # Here $! is meaningless.
1589 ...
1590 }
1591 else {
1592 # ONLY here is $! meaningful.
1593 ...
1594 # Already here $! might be meaningless.
1595 }
1596 # Since here we might have either success or failure,
1597 # $! is meaningless.
1598 Here, meaningless means that $! may be unrelated to the outcome
1600 of the "open()" operator. Assignment to $! is similarly
1601 ephemeral. It can be used immediately before invoking the
1602 "die()" operator, to set the exit value, or to inspect the
1603 system error string corresponding to error n, or to restore $!
1604 to a meaningful state.
1605 Mnemonic: What just went bang?
1607 %OS_ERROR
1609 %ERRNO
1610 %! Each element of "%!" has a true value only if $! is set to that
1611 value. For example, $!{ENOENT} is true if and only if the
1612 current value of $! is "ENOENT"; that is, if the most recent
1613 error was "No such file or directory" (or its moral equivalent:
1614 not all operating systems give that exact error, and certainly
1615 not all languages). The specific true value is not guaranteed,
1616 but in the past has generally been the numeric value of $!. To
1617 check if a particular key is meaningful on your system, use
1618 "exists $!{the_key}"; for a list of legal keys, use "keys %!".
1619 See Errno for more information, and also see "$!".
1620 This variable was added in Perl 5.005.
1622 $CHILD_ERROR
1624 $? The status returned by the last pipe close, backtick ("``")
1625 command, successful call to "wait()" or "waitpid()", or from
1626 the "system()" operator. This is just the 16-bit status word
1627 returned by the traditional Unix "wait()" system call (or else
1628 is made up to look like it). Thus, the exit value of the
1629 subprocess is really ("$? >> 8"), and "$? & 127" gives which
1630 signal, if any, the process died from, and "$? & 128" reports
1631 whether there was a core dump.
1632 Additionally, if the "h_errno" variable is supported in C, its
1634 value is returned via $? if any "gethost*()" function fails.
1635 If you have installed a signal handler for "SIGCHLD", the value
1637 of $? will usually be wrong outside that handler.
1638 Inside an "END" subroutine $? contains the value that is going
1640 to be given to "exit()". You can modify $? in an "END"
1641 subroutine to change the exit status of your program. For
1642 example:
1643 END {
1645 $? = 1 if $? == 255; # die would make it 255
1646 }
1647 Under VMS, the pragma "use vmsish 'status'" makes $? reflect
1649 the actual VMS exit status, instead of the default emulation of
1650 POSIX status; see "$?" in perlvms for details.
1651 Mnemonic: similar to sh and ksh.
1653 $EVAL_ERROR
1655 $@ The Perl error from the last "eval" operator, i.e. the last
1656 exception that was caught. For "eval BLOCK", this is either a
1657 runtime error message or the string or reference "die" was
1658 called with. The "eval STRING" form also catches syntax errors
1659 and other compile time exceptions.
1660 If no error occurs, "eval" sets $@ to the empty string.
1662 Warning messages are not collected in this variable. You can,
1664 however, set up a routine to process warnings by setting
1665 $SIG{__WARN__} as described in "%SIG".
1666 Mnemonic: Where was the error "at"?
1668 Variables related to the interpreter state
1670 These variables provide information about the current interpreter
1671 state.
1672 $COMPILING
1674 $^C The current value of the flag associated with the -c switch.
1675 Mainly of use with -MO=... to allow code to alter its behavior
1676 when being compiled, such as for example to "AUTOLOAD" at
1677 compile time rather than normal, deferred loading. Setting
1678 "$^C = 1" is similar to calling "B::minus_c".
1679 This variable was added in Perl v5.6.0.
1681 $DEBUGGING
1683 $^D The current value of the debugging flags. May be read or set.
1684 Like its command-line equivalent, you can use numeric or
1685 symbolic values, e.g. "$^D = 10" or "$^D = "st"". See
1686 "-Dnumber" in perlrun. The contents of this variable also
1687 affects the debugger operation. See "Debugger Internals" in
1688 perldebguts.
1689 Mnemonic: value of -D switch.
1691 ${^ENCODING}
1693 This variable is no longer supported.
1694 It used to hold the object reference to the "Encode" object
1696 that was used to convert the source code to Unicode.
1697 Its purpose was to allow your non-ASCII Perl scripts not to
1699 have to be written in UTF-8; this was useful before editors
1700 that worked on UTF-8 encoded text were common, but that was
1701 long ago. It caused problems, such as affecting the operation
1702 of other modules that weren't expecting it, causing general
1703 mayhem.
1704 If you need something like this functionality, it is
1706 recommended that use you a simple source filter, such as
1707 Filter::Encoding.
1708 If you are coming here because code of yours is being adversely
1710 affected by someone's use of this variable, you can usually
1711 work around it by doing this:
1712 local ${^ENCODING};
1714 near the beginning of the functions that are getting broken.
1716 This undefines the variable during the scope of execution of
1717 the including function.
1718 This variable was added in Perl 5.8.2 and removed in 5.26.0.
1720 ${^GLOBAL_PHASE}
1722 The current phase of the perl interpreter.
1723 Possible values are:
1725 CONSTRUCT
1727 The "PerlInterpreter*" is being constructed via
1728 "perl_construct". This value is mostly there for
1729 completeness and for use via the underlying C variable
1730 "PL_phase". It's not really possible for Perl code to
1731 be executed unless construction of the interpreter is
1732 finished.
1733 START This is the global compile-time. That includes,
1735 basically, every "BEGIN" block executed directly or
1736 indirectly from during the compile-time of the top-
1737 level program.
1738 This phase is not called "BEGIN" to avoid confusion
1740 with "BEGIN"-blocks, as those are executed during
1741 compile-time of any compilation unit, not just the top-
1742 level program. A new, localised compile-time entered
1743 at run-time, for example by constructs as "eval "use
1744 SomeModule"" are not global interpreter phases, and
1745 therefore aren't reflected by "${^GLOBAL_PHASE}".
1746 CHECK Execution of any "CHECK" blocks.
1748 INIT Similar to "CHECK", but for "INIT"-blocks, not "CHECK"
1750 blocks.
1751 RUN The main run-time, i.e. the execution of
1753 "PL_main_root".
1754 END Execution of any "END" blocks.
1756 DESTRUCT
1758 Global destruction.
1759 Also note that there's no value for UNITCHECK-blocks. That's
1761 because those are run for each compilation unit individually,
1762 and therefore is not a global interpreter phase.
1763 Not every program has to go through each of the possible
1765 phases, but transition from one phase to another can only
1766 happen in the order described in the above list.
1767 An example of all of the phases Perl code can see:
1769 BEGIN { print "compile-time: ${^GLOBAL_PHASE}\n" }
1771 INIT { print "init-time: ${^GLOBAL_PHASE}\n" }
1773 CHECK { print "check-time: ${^GLOBAL_PHASE}\n" }
1775 {
1777 package Print::Phase;
1778 sub new {
1780 my ($class, $time) = @_;
1781 return bless \$time, $class;
1782 }
1783 sub DESTROY {
1785 my $self = shift;
1786 print "$$self: ${^GLOBAL_PHASE}\n";
1787 }
1788 }
1789 print "run-time: ${^GLOBAL_PHASE}\n";
1791 my $runtime = Print::Phase->new(
1793 "lexical variables are garbage collected before END"
1794 );
1795 END { print "end-time: ${^GLOBAL_PHASE}\n" }
1797 our $destruct = Print::Phase->new(
1799 "package variables are garbage collected after END"
1800 );
1801 This will print out
1803 compile-time: START
1805 check-time: CHECK
1806 init-time: INIT
1807 run-time: RUN
1808 lexical variables are garbage collected before END: RUN
1809 end-time: END
1810 package variables are garbage collected after END: DESTRUCT
1811 This variable was added in Perl 5.14.0.
1813 $^H WARNING: This variable is strictly for internal use only. Its
1815 availability, behavior, and contents are subject to change
1816 without notice.
1817 This variable contains compile-time hints for the Perl
1819 interpreter. At the end of compilation of a BLOCK the value of
1820 this variable is restored to the value when the interpreter
1821 started to compile the BLOCK.
1822 When perl begins to parse any block construct that provides a
1824 lexical scope (e.g., eval body, required file, subroutine body,
1825 loop body, or conditional block), the existing value of $^H is
1826 saved, but its value is left unchanged. When the compilation
1827 of the block is completed, it regains the saved value. Between
1828 the points where its value is saved and restored, code that
1829 executes within BEGIN blocks is free to change the value of
1830 $^H.
1831 This behavior provides the semantic of lexical scoping, and is
1833 used in, for instance, the "use strict" pragma.
1834 The contents should be an integer; different bits of it are
1836 used for different pragmatic flags. Here's an example:
1837 sub add_100 { $^H |= 0x100 }
1839 sub foo {
1841 BEGIN { add_100() }
1842 bar->baz($boon);
1843 }
1844 Consider what happens during execution of the BEGIN block. At
1846 this point the BEGIN block has already been compiled, but the
1847 body of "foo()" is still being compiled. The new value of $^H
1848 will therefore be visible only while the body of "foo()" is
1849 being compiled.
1850 Substitution of "BEGIN { add_100() }" block with:
1852 BEGIN { require strict; strict->import('vars') }
1854 demonstrates how "use strict 'vars'" is implemented. Here's a
1856 conditional version of the same lexical pragma:
1857 BEGIN {
1859 require strict; strict->import('vars') if $condition
1860 }
1861 This variable was added in Perl 5.003.
1863 %^H The "%^H" hash provides the same scoping semantic as $^H. This
1865 makes it useful for implementation of lexically scoped pragmas.
1866 See perlpragma. All the entries are stringified when accessed
1867 at runtime, so only simple values can be accommodated. This
1868 means no pointers to objects, for example.
1869 When putting items into "%^H", in order to avoid conflicting
1871 with other users of the hash there is a convention regarding
1872 which keys to use. A module should use only keys that begin
1873 with the module's name (the name of its main package) and a "/"
1874 character. For example, a module "Foo::Bar" should use keys
1875 such as "Foo::Bar/baz".
1876 This variable was added in Perl v5.6.0.
1878 ${^OPEN}
1880 An internal variable used by PerlIO. A string in two parts,
1881 separated by a "\0" byte, the first part describes the input
1882 layers, the second part describes the output layers.
1883 This variable was added in Perl v5.8.0.
1885 $PERLDB
1887 $^P The internal variable for debugging support. The meanings of
1888 the various bits are subject to change, but currently indicate:
1889 0x01 Debug subroutine enter/exit.
1891 0x02 Line-by-line debugging. Causes "DB::DB()" subroutine to
1893 be called for each statement executed. Also causes
1894 saving source code lines (like 0x400).
1895 0x04 Switch off optimizations.
1897 0x08 Preserve more data for future interactive inspections.
1899 0x10 Keep info about source lines on which a subroutine is
1901 defined.
1902 0x20 Start with single-step on.
1904 0x40 Use subroutine address instead of name when reporting.
1906 0x80 Report "goto &subroutine" as well.
1908 0x100 Provide informative "file" names for evals based on the
1910 place they were compiled.
1911 0x200 Provide informative names to anonymous subroutines based
1913 on the place they were compiled.
1914 0x400 Save source code lines into "@{"_<$filename"}".
1916 0x800 When saving source, include evals that generate no
1918 subroutines.
1919 0x1000
1921 When saving source, include source that did not compile.
1922 Some bits may be relevant at compile-time only, some at run-
1924 time only. This is a new mechanism and the details may change.
1925 See also perldebguts.
1926 ${^TAINT}
1928 Reflects if taint mode is on or off. 1 for on (the program was
1929 run with -T), 0 for off, -1 when only taint warnings are
1930 enabled (i.e. with -t or -TU).
1931 This variable is read-only.
1933 This variable was added in Perl v5.8.0.
1935 ${^UNICODE}
1937 Reflects certain Unicode settings of Perl. See perlrun
1938 documentation for the "-C" switch for more information about
1939 the possible values.
1940 This variable is set during Perl startup and is thereafter
1942 read-only.
1943 This variable was added in Perl v5.8.2.
1945 ${^UTF8CACHE}
1947 This variable controls the state of the internal UTF-8 offset
1948 caching code. 1 for on (the default), 0 for off, -1 to debug
1949 the caching code by checking all its results against linear
1950 scans, and panicking on any discrepancy.
1951 This variable was added in Perl v5.8.9. It is subject to
1953 change or removal without notice, but is currently used to
1954 avoid recalculating the boundaries of multi-byte UTF-8-encoded
1955 characters.
1956 ${^UTF8LOCALE}
1958 This variable indicates whether a UTF-8 locale was detected by
1959 perl at startup. This information is used by perl when it's in
1960 adjust-utf8ness-to-locale mode (as when run with the "-CL"
1961 command-line switch); see perlrun for more info on this.
1962 This variable was added in Perl v5.8.8.
1964 Deprecated and removed variables
1966 Deprecating a variable announces the intent of the perl maintainers to
1967 eventually remove the variable from the language. It may still be
1968 available despite its status. Using a deprecated variable triggers a
1969 warning.
1970 Once a variable is removed, its use triggers an error telling you the
1972 variable is unsupported.
1973 See perldiag for details about error messages.
1975 $# $# was a variable that could be used to format printed numbers.
1977 After a deprecation cycle, its magic was removed in Perl
1978 v5.10.0 and using it now triggers a warning: "$# is no longer
1979 supported".
1980 This is not the sigil you use in front of an array name to get
1982 the last index, like $#array. That's still how you get the
1983 last index of an array in Perl. The two have nothing to do
1984 with each other.
1985 Deprecated in Perl 5.
1987 Removed in Perl v5.10.0.
1989 $* $* was a variable that you could use to enable multiline
1991 matching. After a deprecation cycle, its magic was removed in
1992 Perl v5.10.0. Using it now triggers a warning: "$* is no
1993 longer supported". You should use the "/s" and "/m" regexp
1994 modifiers instead.
1995 Deprecated in Perl 5.
1997 Removed in Perl v5.10.0.
1999 $[ This variable stores the index of the first element in an
2001 array, and of the first character in a substring. The default
2002 is 0, but you could theoretically set it to 1 to make Perl
2003 behave more like awk (or Fortran) when subscripting and when
2004 evaluating the index() and substr() functions.
2005 As of release 5 of Perl, assignment to $[ is treated as a
2007 compiler directive, and cannot influence the behavior of any
2008 other file. (That's why you can only assign compile-time
2009 constants to it.) Its use is highly discouraged.
2010 Prior to Perl v5.10.0, assignment to $[ could be seen from
2012 outer lexical scopes in the same file, unlike other compile-
2013 time directives (such as strict). Using local() on it would
2014 bind its value strictly to a lexical block. Now it is always
2015 lexically scoped.
2016 As of Perl v5.16.0, it is implemented by the arybase module.
2018 See arybase for more details on its behaviour.
2019 Under "use v5.16", or "no feature "array_base"", $[ no longer
2021 has any effect, and always contains 0. Assigning 0 to it is
2022 permitted, but any other value will produce an error.
2023 Mnemonic: [ begins subscripts.
2025 Deprecated in Perl v5.12.0.
2027perl v5.26.3 2018-03-23 PERLVAR(1)