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