This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perlvar: Fix broken link
[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
135226fa
KW
934See also L<<< /$<I<digits>> ($1, $2, ...) >>>, L</%{^CAPTURE}> and
935L</%{^CAPTURE_ALL}>.
27deb0cf 936
95013431
YO
937Note that unlike most other regex magic variables there is no single
938letter equivalent to C<@{^CAPTURE}>.
939
27deb0cf
YO
940This variable was added in 5.25.7
941
b0c22438 942=item $MATCH
a0d0e21e 943
b0c22438 944=item $&
945X<$&> X<$MATCH>
a0d0e21e 946
b0c22438 947The string matched by the last successful pattern match (not counting
948any matches hidden within a BLOCK or C<eval()> enclosed by the current
949BLOCK).
a0d0e21e 950
40445027
DM
951See L</Performance issues> above for the serious performance implications
952of using this variable (even once) in your code.
80bca1b4 953
b0c22438 954This variable is read-only and dynamically-scoped.
f9cbb277 955
b0c22438 956Mnemonic: like C<&> in some editors.
0b9346e6 957
b0c22438 958=item ${^MATCH}
959X<${^MATCH}>
a0d0e21e 960
b0c22438 961This is similar to C<$&> (C<$MATCH>) except that it does not incur the
13b0f67d 962performance penalty associated with that variable.
40445027
DM
963
964See L</Performance issues> above.
965
13b0f67d 966In Perl v5.18 and earlier, it is only guaranteed
b0c22438 967to return a defined value when the pattern was compiled or executed with
13b0f67d
DM
968the C</p> modifier. In Perl v5.20, the C</p> modifier does nothing, so
969C<${^MATCH}> does the same thing as C<$MATCH>.
80bca1b4 970
60cf4914 971This variable was added in Perl v5.10.0.
4bc88a62 972
b0c22438 973This variable is read-only and dynamically-scoped.
e2975953 974
b0c22438 975=item $PREMATCH
52c447a8 976
b0c22438 977=item $`
5b442a2a 978X<$`> X<$PREMATCH> X<${^PREMATCH}>
7636ea95 979
b0c22438 980The string preceding whatever was matched by the last successful
981pattern match, not counting any matches hidden within a BLOCK or C<eval>
0b9346e6 982enclosed by the current BLOCK.
a0d0e21e 983
40445027
DM
984See L</Performance issues> above for the serious performance implications
985of using this variable (even once) in your code.
a0d0e21e 986
b0c22438 987This variable is read-only and dynamically-scoped.
a0d0e21e 988
b0c22438 989Mnemonic: C<`> often precedes a quoted string.
f83ed198 990
b0c22438 991=item ${^PREMATCH}
5b442a2a 992X<$`> X<${^PREMATCH}>
a0d0e21e 993
b0c22438 994This is similar to C<$`> ($PREMATCH) except that it does not incur the
13b0f67d 995performance penalty associated with that variable.
40445027
DM
996
997See L</Performance issues> above.
998
13b0f67d 999In Perl v5.18 and earlier, it is only guaranteed
b0c22438 1000to return a defined value when the pattern was compiled or executed with
13b0f67d
DM
1001the C</p> modifier. In Perl v5.20, the C</p> modifier does nothing, so
1002C<${^PREMATCH}> does the same thing as C<$PREMATCH>.
a0d0e21e 1003
4a70680a 1004This variable was added in Perl v5.10.0.
a0d0e21e 1005
b0c22438 1006This variable is read-only and dynamically-scoped.
a0d0e21e 1007
b0c22438 1008=item $POSTMATCH
16070b82 1009
b0c22438 1010=item $'
5b442a2a 1011X<$'> X<$POSTMATCH> X<${^POSTMATCH}> X<@->
305aace0 1012
b0c22438 1013The string following whatever was matched by the last successful
1014pattern match (not counting any matches hidden within a BLOCK or C<eval()>
241a59d9 1015enclosed by the current BLOCK). Example:
305aace0 1016
9548c15c
FC
1017 local $_ = 'abcdefghi';
1018 /def/;
1019 print "$`:$&:$'\n"; # prints abc:def:ghi
305aace0 1020
40445027
DM
1021See L</Performance issues> above for the serious performance implications
1022of using this variable (even once) in your code.
a0d0e21e 1023
b0c22438 1024This variable is read-only and dynamically-scoped.
1025
1026Mnemonic: C<'> often follows a quoted string.
1027
1028=item ${^POSTMATCH}
5b442a2a 1029X<${^POSTMATCH}> X<$'> X<$POSTMATCH>
b0c22438 1030
1031This is similar to C<$'> (C<$POSTMATCH>) except that it does not incur the
13b0f67d 1032performance penalty associated with that variable.
40445027
DM
1033
1034See L</Performance issues> above.
1035
13b0f67d 1036In Perl v5.18 and earlier, it is only guaranteed
b0c22438 1037to return a defined value when the pattern was compiled or executed with
13b0f67d
DM
1038the C</p> modifier. In Perl v5.20, the C</p> modifier does nothing, so
1039C<${^POSTMATCH}> does the same thing as C<$POSTMATCH>.
b0c22438 1040
60cf4914 1041This variable was added in Perl v5.10.0.
b0c22438 1042
1043This variable is read-only and dynamically-scoped.
1044
1045=item $LAST_PAREN_MATCH
1046
1047=item $+
1048X<$+> X<$LAST_PAREN_MATCH>
1049
0b9dad94
DM
1050The text matched by the highest used capture group of the last
1051successful search pattern. It is logically equivalent to the highest
1052numbered capture variable (C<$1>, C<$2>, ...) which has a defined value.
1053
b0c22438 1054This is useful if you don't know which one of a set of alternative patterns
241a59d9 1055matched. For example:
b0c22438 1056
9548c15c 1057 /Version: (.*)|Revision: (.*)/ && ($rev = $+);
b0c22438 1058
1059This variable is read-only and dynamically-scoped.
1060
1061Mnemonic: be positive and forward looking.
1062
1063=item $LAST_SUBMATCH_RESULT
1064
1065=item $^N
5b442a2a 1066X<$^N> X<$LAST_SUBMATCH_RESULT>
b0c22438 1067
1068The text matched by the used group most-recently closed (i.e. the group
1069with the rightmost closing parenthesis) of the last successful search
0b9dad94
DM
1070pattern. This is subtly different from C<$+>. For example in
1071
1072 "ab" =~ /^((.)(.))$/
1073
1074we have
1075
1076 $1,$^N have the value "ab"
1077 $2 has the value "a"
1078 $3,$+ have the value "b"
b0c22438 1079
1080This is primarily used inside C<(?{...})> blocks for examining text
241a59d9 1081recently matched. For example, to effectively capture text to a variable
b0c22438 1082(in addition to C<$1>, C<$2>, etc.), replace C<(...)> with
1083
9548c15c 1084 (?:(...)(?{ $var = $^N }))
b0c22438 1085
1086By setting and then using C<$var> in this way relieves you from having to
1087worry about exactly which numbered set of parentheses they are.
1088
60cf4914 1089This variable was added in Perl v5.8.0.
b0c22438 1090
1091Mnemonic: the (possibly) Nested parenthesis that most recently closed.
1092
1093=item @LAST_MATCH_END
1094
1095=item @+
1096X<@+> X<@LAST_MATCH_END>
1097
1098This array holds the offsets of the ends of the last successful
241a59d9
FC
1099submatches in the currently active dynamic scope. C<$+[0]> is
1100the offset into the string of the end of the entire match. This
b0c22438 1101is the same value as what the C<pos> function returns when called
241a59d9 1102on the variable that was matched against. The I<n>th element
b0c22438 1103of this array holds the offset of the I<n>th submatch, so
1104C<$+[1]> is the offset past where C<$1> ends, C<$+[2]> the offset
241a59d9
FC
1105past where C<$2> ends, and so on. You can use C<$#+> to determine
1106how many subgroups were in the last successful match. See the
b0c22438 1107examples given for the C<@-> variable.
1108
60cf4914 1109This variable was added in Perl v5.6.0.
b0c22438 1110
27deb0cf
YO
1111=item %{^CAPTURE}
1112
b0c22438 1113=item %LAST_PAREN_MATCH
1114
1115=item %+
27deb0cf 1116X<%+> X<%LAST_PAREN_MATCH> X<%{^CAPTURE}>
b0c22438 1117
1118Similar to C<@+>, the C<%+> hash allows access to the named capture
1119buffers, should they exist, in the last successful match in the
1120currently active dynamic scope.
1121
1122For example, C<$+{foo}> is equivalent to C<$1> after the following match:
1123
9548c15c 1124 'foo' =~ /(?<foo>foo)/;
b0c22438 1125
1126The keys of the C<%+> hash list only the names of buffers that have
1127captured (and that are thus associated to defined values).
1128
33727e0f
LM
1129If multiple distinct capture groups have the same name, then
1130C<$+{NAME}> will refer to the leftmost defined group in the match.
1131
b0c22438 1132The underlying behaviour of C<%+> is provided by the
1133L<Tie::Hash::NamedCapture> module.
1134
1135B<Note:> C<%-> and C<%+> are tied views into a common internal hash
241a59d9 1136associated with the last successful regular expression. Therefore mixing
b0c22438 1137iterative access to them via C<each> may have unpredictable results.
1138Likewise, if the last successful match changes, then the results may be
1139surprising.
1140
27deb0cf
YO
1141This variable was added in Perl v5.10.0. The C<%{^CAPTURE}> alias was
1142added in 5.25.7.
a0d0e21e 1143
b0c22438 1144This variable is read-only and dynamically-scoped.
1145
1146=item @LAST_MATCH_START
1147
1148=item @-
1149X<@-> X<@LAST_MATCH_START>
1150
1151C<$-[0]> is the offset of the start of the last successful match.
1152C<$-[>I<n>C<]> is the offset of the start of the substring matched by
1153I<n>-th subpattern, or undef if the subpattern did not match.
1154
1155Thus, after a match against C<$_>, C<$&> coincides with C<substr $_, $-[0],
241a59d9 1156$+[0] - $-[0]>. Similarly, $I<n> coincides with C<substr $_, $-[n],
b0c22438 1157$+[n] - $-[n]> if C<$-[n]> is defined, and $+ coincides with
241a59d9
FC
1158C<substr $_, $-[$#-], $+[$#-] - $-[$#-]>. One can use C<$#-> to find the
1159last matched subgroup in the last successful match. Contrast with
1160C<$#+>, the number of subgroups in the regular expression. Compare
b0c22438 1161with C<@+>.
1162
1163This array holds the offsets of the beginnings of the last
1164successful submatches in the currently active dynamic scope.
1165C<$-[0]> is the offset into the string of the beginning of the
241a59d9 1166entire match. The I<n>th element of this array holds the offset
b0c22438 1167of the I<n>th submatch, so C<$-[1]> is the offset where C<$1>
1168begins, C<$-[2]> the offset where C<$2> begins, and so on.
1169
1170After a match against some variable C<$var>:
1171
1172=over 5
1173
1174=item C<$`> is the same as C<substr($var, 0, $-[0])>
1175
1176=item C<$&> is the same as C<substr($var, $-[0], $+[0] - $-[0])>
1177
1178=item C<$'> is the same as C<substr($var, $+[0])>
1179
1180=item C<$1> is the same as C<substr($var, $-[1], $+[1] - $-[1])>
1181
1182=item C<$2> is the same as C<substr($var, $-[2], $+[2] - $-[2])>
1183
1184=item C<$3> is the same as C<substr($var, $-[3], $+[3] - $-[3])>
1185
1186=back
1187
60cf4914 1188This variable was added in Perl v5.6.0.
b0c22438 1189
27deb0cf
YO
1190=item %{^CAPTURE_ALL}
1191X<%{^CAPTURE_ALL}>
1192
b0c22438 1193=item %-
2e67aae7 1194X<%->
b0c22438 1195
1196Similar to C<%+>, this variable allows access to the named capture groups
241a59d9 1197in the last successful match in the currently active dynamic scope. To
b0c22438 1198each capture group name found in the regular expression, it associates a
1199reference to an array containing the list of values captured by all
1200buffers with that name (should there be several of them), in the order
1201where they appear.
1202
1203Here's an example:
1204
1205 if ('1234' =~ /(?<A>1)(?<B>2)(?<A>3)(?<B>4)/) {
1206 foreach my $bufname (sort keys %-) {
1207 my $ary = $-{$bufname};
1208 foreach my $idx (0..$#$ary) {
1209 print "\$-{$bufname}[$idx] : ",
9548c15c
FC
1210 (defined($ary->[$idx])
1211 ? "'$ary->[$idx]'"
1212 : "undef"),
b0c22438 1213 "\n";
1214 }
1215 }
1216 }
1217
1218would print out:
1219
9548c15c
FC
1220 $-{A}[0] : '1'
1221 $-{A}[1] : '3'
1222 $-{B}[0] : '2'
1223 $-{B}[1] : '4'
b0c22438 1224
1225The keys of the C<%-> hash correspond to all buffer names found in
1226the regular expression.
1227
1228The behaviour of C<%-> is implemented via the
1229L<Tie::Hash::NamedCapture> module.
1230
1231B<Note:> C<%-> and C<%+> are tied views into a common internal hash
241a59d9 1232associated with the last successful regular expression. Therefore mixing
b0c22438 1233iterative access to them via C<each> may have unpredictable results.
1234Likewise, if the last successful match changes, then the results may be
1235surprising.
1236
27deb0cf
YO
1237This variable was added in Perl v5.10.0. The C<%{^CAPTURE_ALL}> alias was
1238added in 5.25.7.
b0c22438 1239
1240This variable is read-only and dynamically-scoped.
1241
1242=item $LAST_REGEXP_CODE_RESULT
1243
1244=item $^R
1245X<$^R> X<$LAST_REGEXP_CODE_RESULT>
1246
1247The result of evaluation of the last successful C<(?{ code })>
241a59d9 1248regular expression assertion (see L<perlre>). May be written to.
b0c22438 1249
1250This variable was added in Perl 5.005.
a0d0e21e 1251
a3621e74 1252=item ${^RE_DEBUG_FLAGS}
ca1b95ae 1253X<${^RE_DEBUG_FLAGS}>
a3621e74 1254
241a59d9
FC
1255The current value of the regex debugging flags. Set to 0 for no debug output
1256even when the C<re 'debug'> module is loaded. See L<re> for details.
b0c22438 1257
60cf4914 1258This variable was added in Perl v5.10.0.
a3621e74 1259
0111c4fd 1260=item ${^RE_TRIE_MAXBUF}
ca1b95ae 1261X<${^RE_TRIE_MAXBUF}>
a3621e74
YO
1262
1263Controls how certain regex optimisations are applied and how much memory they
241a59d9
FC
1264utilize. This value by default is 65536 which corresponds to a 512kB
1265temporary cache. Set this to a higher value to trade
1266memory for speed when matching large alternations. Set
1267it to a lower value if you want the optimisations to
a3621e74
YO
1268be as conservative of memory as possible but still occur, and set it to a
1269negative value to prevent the optimisation and conserve the most memory.
1270Under normal situations this variable should be of no interest to you.
1271
60cf4914 1272This variable was added in Perl v5.10.0.
a0d0e21e 1273
b0c22438 1274=back
a0d0e21e 1275
b0c22438 1276=head2 Variables related to filehandles
a0d0e21e 1277
b0c22438 1278Variables that depend on the currently selected filehandle may be set
1279by calling an appropriate object method on the C<IO::Handle> object,
1280although this is less efficient than using the regular built-in
241a59d9 1281variables. (Summary lines below for this contain the word HANDLE.)
b0c22438 1282First you must say
6e2995f4 1283
9548c15c 1284 use IO::Handle;
0462a1ab 1285
b0c22438 1286after which you may use either
0462a1ab 1287
9548c15c 1288 method HANDLE EXPR
0462a1ab 1289
b0c22438 1290or more safely,
0462a1ab 1291
9548c15c 1292 HANDLE->method(EXPR)
0462a1ab 1293
241a59d9 1294Each method returns the old value of the C<IO::Handle> attribute. The
b0c22438 1295methods each take an optional EXPR, which, if supplied, specifies the
241a59d9 1296new value for the C<IO::Handle> attribute in question. If not
b0c22438 1297supplied, most methods do nothing to the current value--except for
1298C<autoflush()>, which will assume a 1 for you, just to be different.
0462a1ab 1299
b0c22438 1300Because loading in the C<IO::Handle> class is an expensive operation,
1301you should learn how to use the regular built-in variables.
1302
241a59d9 1303A few of these variables are considered "read-only". This means that
b0c22438 1304if you try to assign to this variable, either directly or indirectly
1305through a reference, you'll raise a run-time exception.
1306
1307You should be very careful when modifying the default values of most
241a59d9 1308special variables described in this document. In most cases you want
b0c22438 1309to localize these variables before changing them, since if you don't,
1310the change may affect other modules which rely on the default values
241a59d9 1311of the special variables that you have changed. This is one of the
b0c22438 1312correct ways to read the whole file at once:
1313
9548c15c
FC
1314 open my $fh, "<", "foo" or die $!;
1315 local $/; # enable localized slurp mode
1316 my $content = <$fh>;
1317 close $fh;
b0c22438 1318
1319But the following code is quite bad:
1320
9548c15c
FC
1321 open my $fh, "<", "foo" or die $!;
1322 undef $/; # enable slurp mode
1323 my $content = <$fh>;
1324 close $fh;
b0c22438 1325
1326since some other module, may want to read data from some file in the
1327default "line mode", so if the code we have just presented has been
1328executed, the global value of C<$/> is now changed for any other code
1329running inside the same Perl interpreter.
1330
1331Usually when a variable is localized you want to make sure that this
241a59d9
FC
1332change affects the shortest scope possible. So unless you are already
1333inside some short C<{}> block, you should create one yourself. For
b0c22438 1334example:
1335
9548c15c
FC
1336 my $content = '';
1337 open my $fh, "<", "foo" or die $!;
1338 {
1339 local $/;
1340 $content = <$fh>;
1341 }
1342 close $fh;
0462a1ab 1343
b0c22438 1344Here is an example of how your own code can go broken:
0462a1ab 1345
9548c15c
FC
1346 for ( 1..3 ){
1347 $\ = "\r\n";
1348 nasty_break();
1349 print "$_";
1350 }
0b9346e6 1351
9548c15c 1352 sub nasty_break {
0b9346e6 1353 $\ = "\f";
1354 # do something with $_
9548c15c 1355 }
0462a1ab 1356
0b9346e6 1357You probably expect this code to print the equivalent of
0462a1ab 1358
0b9346e6 1359 "1\r\n2\r\n3\r\n"
0462a1ab 1360
b0c22438 1361but instead you get:
0462a1ab 1362
0b9346e6 1363 "1\f2\f3\f"
0462a1ab 1364
0b9346e6 1365Why? Because C<nasty_break()> modifies C<$\> without localizing it
241a59d9
FC
1366first. The value you set in C<nasty_break()> is still there when you
1367return. The fix is to add C<local()> so the value doesn't leak out of
0b9346e6 1368C<nasty_break()>:
6e2995f4 1369
9548c15c 1370 local $\ = "\f";
a0d0e21e 1371
b0c22438 1372It's easy to notice the problem in such a short example, but in more
1373complicated code you are looking for trouble if you don't localize
1374changes to the special variables.
a0d0e21e 1375
b0c22438 1376=over 8
a0d0e21e 1377
b0c22438 1378=item $ARGV
1379X<$ARGV>
fb73857a 1380
ca1b95ae 1381Contains the name of the current file when reading from C<< <> >>.
b0c22438 1382
1383=item @ARGV
1384X<@ARGV>
1385
ca1b95ae 1386The array C<@ARGV> contains the command-line arguments intended for
241a59d9 1387the script. C<$#ARGV> is generally the number of arguments minus
b0c22438 1388one, because C<$ARGV[0]> is the first argument, I<not> the program's
241a59d9 1389command name itself. See L</$0> for the command name.
b0c22438 1390
84dabc03 1391=item ARGV
1392X<ARGV>
1393
1394The special filehandle that iterates over command-line filenames in
241a59d9
FC
1395C<@ARGV>. Usually written as the null filehandle in the angle operator
1396C<< <> >>. Note that currently C<ARGV> only has its magical effect
84dabc03 1397within the C<< <> >> operator; elsewhere it is just a plain filehandle
241a59d9 1398corresponding to the last file opened by C<< <> >>. In particular,
84dabc03 1399passing C<\*ARGV> as a parameter to a function that expects a filehandle
1400may not cause your function to automatically read the contents of all the
1401files in C<@ARGV>.
1402
b0c22438 1403=item ARGVOUT
1404X<ARGVOUT>
1405
1406The special filehandle that points to the currently open output file
241a59d9
FC
1407when doing edit-in-place processing with B<-i>. Useful when you have
1408to do a lot of inserting and don't want to keep modifying C<$_>. See
b0c22438 1409L<perlrun> for the B<-i> switch.
1410
96948506 1411=item IO::Handle->output_field_separator( EXPR )
84dabc03 1412
1413=item $OUTPUT_FIELD_SEPARATOR
1414
1415=item $OFS
1416
1417=item $,
1418X<$,> X<$OFS> X<$OUTPUT_FIELD_SEPARATOR>
1419
241a59d9
FC
1420The output field separator for the print operator. If defined, this
1421value is printed between each of print's arguments. Default is C<undef>.
84dabc03 1422
96948506 1423You cannot call C<output_field_separator()> on a handle, only as a
008f9687 1424static method. See L<IO::Handle|IO::Handle>.
96948506 1425
84dabc03 1426Mnemonic: what is printed when there is a "," in your print statement.
1427
5b442a2a 1428=item HANDLE->input_line_number( EXPR )
b0c22438 1429
1430=item $INPUT_LINE_NUMBER
1431
1432=item $NR
1433
1434=item $.
1435X<$.> X<$NR> X<$INPUT_LINE_NUMBER> X<line number>
1436
1437Current line number for the last filehandle accessed.
1438
1439Each filehandle in Perl counts the number of lines that have been read
241a59d9 1440from it. (Depending on the value of C<$/>, Perl's idea of what
b0c22438 1441constitutes a line may not match yours.) When a line is read from a
1442filehandle (via C<readline()> or C<< <> >>), or when C<tell()> or
1443C<seek()> is called on it, C<$.> becomes an alias to the line counter
1444for that filehandle.
1445
1446You can adjust the counter by assigning to C<$.>, but this will not
241a59d9
FC
1447actually move the seek pointer. I<Localizing C<$.> will not localize
1448the filehandle's line count>. Instead, it will localize perl's notion
b0c22438 1449of which filehandle C<$.> is currently aliased to.
1450
1451C<$.> is reset when the filehandle is closed, but B<not> when an open
241a59d9
FC
1452filehandle is reopened without an intervening C<close()>. For more
1453details, see L<perlop/"IE<sol>O Operators">. Because C<< <> >> never does
b0c22438 1454an explicit close, line numbers increase across C<ARGV> files (but see
1455examples in L<perlfunc/eof>).
1456
1457You can also use C<< HANDLE->input_line_number(EXPR) >> to access the
1458line counter for a given filehandle without having to worry about
1459which handle you last accessed.
1460
1461Mnemonic: many programs use "." to mean the current line number.
1462
96948506 1463=item IO::Handle->input_record_separator( EXPR )
b0c22438 1464
1465=item $INPUT_RECORD_SEPARATOR
1466
1467=item $RS
1468
1469=item $/
1470X<$/> X<$RS> X<$INPUT_RECORD_SEPARATOR>
1471
241a59d9
FC
1472The input record separator, newline by default. This influences Perl's
1473idea of what a "line" is. Works like B<awk>'s RS variable, including
84dabc03 1474treating empty lines as a terminator if set to the null string (an
241a59d9 1475empty line cannot contain any spaces or tabs). You may set it to a
84dabc03 1476multi-character string to match a multi-character terminator, or to
241a59d9 1477C<undef> to read through the end of file. Setting it to C<"\n\n">
84dabc03 1478means something slightly different than setting to C<"">, if the file
241a59d9
FC
1479contains consecutive empty lines. Setting to C<""> will treat two or
1480more consecutive empty lines as a single empty line. Setting to
84dabc03 1481C<"\n\n"> will blindly assume that the next input character belongs to
1482the next paragraph, even if it's a newline.
b0c22438 1483
1484 local $/; # enable "slurp" mode
1485 local $_ = <FH>; # whole file now here
1486 s/\n[ \t]+/ /g;
1487
241a59d9 1488Remember: the value of C<$/> is a string, not a regex. B<awk> has to
b0c22438 1489be better for something. :-)
1490
440af013
JK
1491Setting C<$/> to an empty string -- the so-called I<paragraph mode> -- merits
1492special attention. When C<$/> is set to C<""> and the entire file is read in
1493with that setting, any sequence of consecutive newlines C<"\n\n"> at the
1494beginning of the file is discarded. With the exception of the final record in
1495the file, each sequence of characters ending in two or more newlines is
1496treated as one record and is read in to end in exactly two newlines. If the
1497last record in the file ends in zero or one consecutive newlines, that record
1498is read in with that number of newlines. If the last record ends in two or
1499more consecutive newlines, it is read in with two newlines like all preceding
1500records.
1501
1502Suppose we wrote the following string to a file:
1503
1504 my $string = "\n\n\n";
1505 $string .= "alpha beta\ngamma delta\n\n\n";
1506 $string .= "epsilon zeta eta\n\n";
1507 $string .= "theta\n";
1508
1509 my $file = 'simple_file.txt';
1510 open my $OUT, '>', $file or die;
1511 print $OUT $string;
1512 close $OUT or die;
1513
1514Now we read that file in paragraph mode:
1515
1516 local $/ = ""; # paragraph mode
1517 open my $IN, '<', $file or die;
1518 my @records = <$IN>;
1519 close $IN or die;
1520
1521C<@records> will consist of these 3 strings:
1522
1523 (
1524 "alpha beta\ngamma delta\n\n",
1525 "epsilon zeta eta\n\n",
1526 "theta\n",
1527 )
1528
b0c22438 1529Setting C<$/> to a reference to an integer, scalar containing an
1530integer, or scalar that's convertible to an integer will attempt to
1531read records instead of lines, with the maximum record size being the
3d249121 1532referenced integer number of characters. So this:
b0c22438 1533
1534 local $/ = \32768; # or \"32768", or \$var_containing_32768
1535 open my $fh, "<", $myfile or die $!;
1536 local $_ = <$fh>;
fb73857a 1537
f1ee460b 1538will read a record of no more than 32768 characters from $fh. If you're
b0c22438 1539not reading from a record-oriented file (or your OS doesn't have
1540record-oriented files), then you'll likely get a full chunk of data
241a59d9
FC
1541with every read. If a record is larger than the record size you've
1542set, you'll get the record back in pieces. Trying to set the record
b3a2acfa
YO
1543size to zero or less is deprecated and will cause $/ to have the value
1544of "undef", which will cause reading in the (rest of the) whole file.
1545
1546As of 5.19.9 setting C<$/> to any other form of reference will throw a
1547fatal exception. This is in preparation for supporting new ways to set
1548C<$/> in the future.
6e2995f4 1549
78c28381 1550On VMS only, record reads bypass PerlIO layers and any associated
3d249121 1551buffering, so you must not mix record and non-record reads on the
78c28381
CB
1552same filehandle. Record mode mixes with line mode only when the
1553same buffering layer is in use for both modes.
5c055ba3 1554
96948506 1555You cannot call C<input_record_separator()> on a handle, only as a
008f9687 1556static method. See L<IO::Handle|IO::Handle>.
96948506 1557
008f9687 1558See also L<perlport/"Newlines">. Also see L</$.>.
9bf22702 1559
b0c22438 1560Mnemonic: / delimits line boundaries when quoting poetry.
5c055ba3 1561
96948506 1562=item IO::Handle->output_record_separator( EXPR )
84902520 1563
b0c22438 1564=item $OUTPUT_RECORD_SEPARATOR
84902520 1565
b0c22438 1566=item $ORS
84902520 1567
b0c22438 1568=item $\
1569X<$\> X<$ORS> X<$OUTPUT_RECORD_SEPARATOR>
84902520 1570
241a59d9
FC
1571The output record separator for the print operator. If defined, this
1572value is printed after the last of print's arguments. Default is C<undef>.
84902520 1573
96948506 1574You cannot call C<output_record_separator()> on a handle, only as a
008f9687 1575static method. See L<IO::Handle|IO::Handle>.
96948506 1576
b0c22438 1577Mnemonic: you set C<$\> instead of adding "\n" at the end of the print.
1578Also, it's just like C<$/>, but it's what you get "back" from Perl.
84902520 1579
5b442a2a 1580=item HANDLE->autoflush( EXPR )
1581
1582=item $OUTPUT_AUTOFLUSH
1583
84dabc03 1584=item $|
1585X<$|> X<autoflush> X<flush> X<$OUTPUT_AUTOFLUSH>
84902520 1586
84dabc03 1587If set to nonzero, forces a flush right away and after every write or
241a59d9 1588print on the currently selected output channel. Default is 0
84dabc03 1589(regardless of whether the channel is really buffered by the system or
1590not; C<$|> tells you only whether you've asked Perl explicitly to
241a59d9
FC
1591flush after each write). STDOUT will typically be line buffered if
1592output is to the terminal and block buffered otherwise. Setting this
84dabc03 1593variable is useful primarily when you are outputting to a pipe or
1594socket, such as when you are running a Perl program under B<rsh> and
241a59d9
FC
1595want to see the output as it's happening. This has no effect on input
1596buffering. See L<perlfunc/getc> for that. See L<perlfunc/select> on
1597how to select the output channel. See also L<IO::Handle>.
84dabc03 1598
1599Mnemonic: when you want your pipes to be piping hot.
1600
8561ea1d
FC
1601=item ${^LAST_FH}
1602X<${^LAST_FH}>
1603
1604This read-only variable contains a reference to the last-read filehandle.
1605This is set by C<< <HANDLE> >>, C<readline>, C<tell>, C<eof> and C<seek>.
1606This is the same handle that C<$.> and C<tell> and C<eof> without arguments
1607use. It is also the handle used when Perl appends ", <STDIN> line 1" to
1608an error or warning message.
1609
1610This variable was added in Perl v5.18.0.
1611
84dabc03 1612=back
84902520 1613
b0c22438 1614=head3 Variables related to formats
83ee9e09 1615
b0c22438 1616The special variables for formats are a subset of those for
241a59d9 1617filehandles. See L<perlform> for more information about Perl's
69b55ccc 1618formats.
83ee9e09 1619
b0c22438 1620=over 8
83ee9e09 1621
84dabc03 1622=item $ACCUMULATOR
1623
1624=item $^A
1625X<$^A> X<$ACCUMULATOR>
1626
1627The current value of the C<write()> accumulator for C<format()> lines.
1628A format contains C<formline()> calls that put their result into
241a59d9
FC
1629C<$^A>. After calling its format, C<write()> prints out the contents
1630of C<$^A> and empties. So you never really see the contents of C<$^A>
1631unless you call C<formline()> yourself and then look at it. See
96090e4f 1632L<perlform> and L<perlfunc/"formline PICTURE,LIST">.
84dabc03 1633
96948506 1634=item IO::Handle->format_formfeed(EXPR)
5b442a2a 1635
1636=item $FORMAT_FORMFEED
1637
84dabc03 1638=item $^L
1639X<$^L> X<$FORMAT_FORMFEED>
1640
241a59d9 1641What formats output as a form feed. The default is C<\f>.
84dabc03 1642
96948506 1643You cannot call C<format_formfeed()> on a handle, only as a static
008f9687 1644method. See L<IO::Handle|IO::Handle>.
96948506 1645
b0c22438 1646=item HANDLE->format_page_number(EXPR)
83ee9e09 1647
b0c22438 1648=item $FORMAT_PAGE_NUMBER
83ee9e09 1649
b0c22438 1650=item $%
1651X<$%> X<$FORMAT_PAGE_NUMBER>
83ee9e09 1652
b0c22438 1653The current page number of the currently selected output channel.
83ee9e09 1654
b0c22438 1655Mnemonic: C<%> is page number in B<nroff>.
7619c85e 1656
b0c22438 1657=item HANDLE->format_lines_left(EXPR)
b9ac3b5b 1658
b0c22438 1659=item $FORMAT_LINES_LEFT
66558a10 1660
b0c22438 1661=item $-
1662X<$-> X<$FORMAT_LINES_LEFT>
fb73857a 1663
b0c22438 1664The number of lines left on the page of the currently selected output
1665channel.
fa05a9fd 1666
b0c22438 1667Mnemonic: lines_on_page - lines_printed.
fa05a9fd 1668
96948506 1669=item IO::Handle->format_line_break_characters EXPR
fb73857a 1670
84dabc03 1671=item $FORMAT_LINE_BREAK_CHARACTERS
a0d0e21e 1672
84dabc03 1673=item $:
1674X<$:> X<FORMAT_LINE_BREAK_CHARACTERS>
a0d0e21e 1675
84dabc03 1676The current set of characters after which a string may be broken to
241a59d9 1677fill continuation fields (starting with C<^>) in a format. The default is
84dabc03 1678S<" \n-">, to break on a space, newline, or a hyphen.
a0d0e21e 1679
96948506 1680You cannot call C<format_line_break_characters()> on a handle, only as
008f9687 1681a static method. See L<IO::Handle|IO::Handle>.
96948506 1682
84dabc03 1683Mnemonic: a "colon" in poetry is a part of a line.
1684
1685=item HANDLE->format_lines_per_page(EXPR)
1686
1687=item $FORMAT_LINES_PER_PAGE
1688
1689=item $=
1690X<$=> X<$FORMAT_LINES_PER_PAGE>
1691
1692The current page length (printable lines) of the currently selected
241a59d9 1693output channel. The default is 60.
84dabc03 1694
1695Mnemonic: = has horizontal lines.
7c36658b 1696
b0c22438 1697=item HANDLE->format_top_name(EXPR)
7c36658b 1698
b0c22438 1699=item $FORMAT_TOP_NAME
a05d7ebb 1700
b0c22438 1701=item $^
1702X<$^> X<$FORMAT_TOP_NAME>
fde18df1 1703
b0c22438 1704The name of the current top-of-page format for the currently selected
241a59d9
FC
1705output channel. The default is the name of the filehandle with C<_TOP>
1706appended. For example, the default format top name for the C<STDOUT>
12abbafd 1707filehandle is C<STDOUT_TOP>.
e07ea26a 1708
b0c22438 1709Mnemonic: points to top of page.
e07ea26a 1710
84dabc03 1711=item HANDLE->format_name(EXPR)
16070b82 1712
84dabc03 1713=item $FORMAT_NAME
aa2f2a36 1714
84dabc03 1715=item $~
1716X<$~> X<$FORMAT_NAME>
aa2f2a36 1717
84dabc03 1718The name of the current report format for the currently selected
241a59d9
FC
1719output channel. The default format name is the same as the filehandle
1720name. For example, the default format name for the C<STDOUT>
84dabc03 1721filehandle is just C<STDOUT>.
16070b82 1722
84dabc03 1723Mnemonic: brother to C<$^>.
16070b82 1724
b0c22438 1725=back
a0d0e21e 1726
84dabc03 1727=head2 Error Variables
b0c22438 1728X<error> X<exception>
a0d0e21e 1729
b0c22438 1730The variables C<$@>, C<$!>, C<$^E>, and C<$?> contain information
1731about different types of error conditions that may appear during
241a59d9 1732execution of a Perl program. The variables are shown ordered by
b0c22438 1733the "distance" between the subsystem which reported the error and
241a59d9 1734the Perl process. They correspond to errors detected by the Perl
b0c22438 1735interpreter, C library, operating system, or an external program,
1736respectively.
4438c4b7 1737
b0c22438 1738To illustrate the differences between these variables, consider the
241a59d9 1739following Perl expression, which uses a single-quoted string. After
7fd683ff 1740execution of this statement, perl may have set all four special error
7333b1c4 1741variables:
4438c4b7 1742
9548c15c
FC
1743 eval q{
1744 open my $pipe, "/cdrom/install |" or die $!;
1745 my @res = <$pipe>;
1746 close $pipe or die "bad pipe: $?, $!";
1747 };
a0d0e21e 1748
7333b1c4 1749When perl executes the C<eval()> expression, it translates the
1750C<open()>, C<< <PIPE> >>, and C<close> calls in the C run-time library
241a59d9 1751and thence to the operating system kernel. perl sets C<$!> to
7333b1c4 1752the C library's C<errno> if one of these calls fails.
2a8c8378 1753
84dabc03 1754C<$@> is set if the string to be C<eval>-ed did not compile (this may
1755happen if C<open> or C<close> were imported with bad prototypes), or
241a59d9 1756if Perl code executed during evaluation C<die()>d. In these cases the
0b9346e6 1757value of C<$@> is the compile error, or the argument to C<die> (which
241a59d9 1758will interpolate C<$!> and C<$?>). (See also L<Fatal>, though.)
2a8c8378 1759
84dabc03 1760Under a few operating systems, C<$^E> may contain a more verbose error
241a59d9 1761indicator, such as in this case, "CDROM tray not closed." Systems that
84dabc03 1762do not support extended error messages leave C<$^E> the same as C<$!>.
a0d0e21e 1763
2e6ba115 1764Finally, C<$?> may be set to a non-0 value if the external program
241a59d9 1765F</cdrom/install> fails. The upper eight bits reflect specific error
84dabc03 1766conditions encountered by the program (the program's C<exit()> value).
1767The lower eight bits reflect mode of failure, like signal death and
241a59d9 1768core dump information. See L<wait(2)> for details. In contrast to
2e6ba115 1769C<$!> and C<$^E>, which are set only if an error condition is detected,
84dabc03 1770the variable C<$?> is set on each C<wait> or pipe C<close>,
241a59d9 1771overwriting the old value. This is more like C<$@>, which on every
84dabc03 1772C<eval()> is always set on failure and cleared on success.
a0d0e21e 1773
b0c22438 1774For more details, see the individual descriptions at C<$@>, C<$!>,
1775C<$^E>, and C<$?>.
38e4f4ae 1776
0b9346e6 1777=over 8
1778
b0c22438 1779=item ${^CHILD_ERROR_NATIVE}
1780X<$^CHILD_ERROR_NATIVE>
a0d0e21e 1781
b0c22438 1782The native status returned by the last pipe close, backtick (C<``>)
1783command, successful call to C<wait()> or C<waitpid()>, or from the
241a59d9 1784C<system()> operator. On POSIX-like systems this value can be decoded
b0c22438 1785with the WIFEXITED, WEXITSTATUS, WIFSIGNALED, WTERMSIG, WIFSTOPPED,
1786WSTOPSIG and WIFCONTINUED functions provided by the L<POSIX> module.
a0d0e21e 1787
b0c22438 1788Under VMS this reflects the actual VMS exit status; i.e. it is the
1789same as C<$?> when the pragma C<use vmsish 'status'> is in effect.
a0d0e21e 1790
60cf4914 1791This variable was added in Perl v5.10.0.
a0d0e21e 1792
5b442a2a 1793=item $EXTENDED_OS_ERROR
1794
84dabc03 1795=item $^E
1796X<$^E> X<$EXTENDED_OS_ERROR>
1797
241a59d9 1798Error information specific to the current operating system. At the
a804e657 1799moment, this differs from C<L</$!>> under only VMS, OS/2, and Win32 (and
241a59d9 1800for MacPerl). On all other platforms, C<$^E> is always just the same
84dabc03 1801as C<$!>.
1802
1803Under VMS, C<$^E> provides the VMS status value from the last system
241a59d9
FC
1804error. This is more specific information about the last system error
1805than that provided by C<$!>. This is particularly important when C<$!>
84dabc03 1806is set to B<EVMSERR>.
1807
1808Under OS/2, C<$^E> is set to the error code of the last call to OS/2
1809API either via CRT, or directly from perl.
1810
1811Under Win32, C<$^E> always returns the last error information reported
1812by the Win32 call C<GetLastError()> which describes the last error
241a59d9
FC
1813from within the Win32 API. Most Win32-specific code will report errors
1814via C<$^E>. ANSI C and Unix-like calls set C<errno> and so most
84dabc03 1815portable Perl code will report errors via C<$!>.
1816
a95b3d6a 1817Caveats mentioned in the description of C<L</$!>> generally apply to
84dabc03 1818C<$^E>, also.
1819
1820This variable was added in Perl 5.003.
1821
1822Mnemonic: Extra error explanation.
0b9346e6 1823
84dabc03 1824=item $EXCEPTIONS_BEING_CAUGHT
1825
1826=item $^S
1827X<$^S> X<$EXCEPTIONS_BEING_CAUGHT>
1828
1829Current state of the interpreter.
1830
ca1b95ae 1831 $^S State
aa959a20
FC
1832 --------- -------------------------------------
1833 undef Parsing module, eval, or main program
ca1b95ae 1834 true (1) Executing an eval
1835 false (0) Otherwise
84dabc03 1836
1837The first state may happen in C<$SIG{__DIE__}> and C<$SIG{__WARN__}>
1838handlers.
1839
aa959a20
FC
1840The English name $EXCEPTIONS_BEING_CAUGHT is slightly misleading, because
1841the C<undef> value does not indicate whether exceptions are being caught,
1842since compilation of the main program does not catch exceptions.
1843
84dabc03 1844This variable was added in Perl 5.004.
1845
1846=item $WARNING
1847
1848=item $^W
1849X<$^W> X<$WARNING>
1850
1851The current value of the warning switch, initially true if B<-w> was
1852used, false otherwise, but directly modifiable.
1853
1854See also L<warnings>.
1855
0b9346e6 1856Mnemonic: related to the B<-w> switch.
84dabc03 1857
1858=item ${^WARNING_BITS}
ca1b95ae 1859X<${^WARNING_BITS}>
84dabc03 1860
1861The current set of warning checks enabled by the C<use warnings> pragma.
44567c86
FC
1862It has the same scoping as the C<$^H> and C<%^H> variables. The exact
1863values are considered internal to the L<warnings> pragma and may change
1864between versions of Perl.
84dabc03 1865
60cf4914 1866This variable was added in Perl v5.6.0.
84dabc03 1867
b0c22438 1868=item $OS_ERROR
5ccee41e 1869
b0c22438 1870=item $ERRNO
5ccee41e 1871
b0c22438 1872=item $!
1873X<$!> X<$ERRNO> X<$OS_ERROR>
9b0e6e7a 1874
a73bef78
JL
1875When referenced, C<$!> retrieves the current value
1876of the C C<errno> integer variable.
1877If C<$!> is assigned a numerical value, that value is stored in C<errno>.
1878When referenced as a string, C<$!> yields the system error string
1879corresponding to C<errno>.
1880
1881Many system or library calls set C<errno> if they fail,
1882to indicate the cause of failure. They usually do B<not>
1883set C<errno> to zero if they succeed. This means C<errno>,
1884hence C<$!>, is meaningful only I<immediately> after a B<failure>:
1885
1886 if (open my $fh, "<", $filename) {
ca1b95ae 1887 # Here $! is meaningless.
1888 ...
7fd683ff 1889 }
ca1b95ae 1890 else {
1891 # ONLY here is $! meaningful.
1892 ...
1893 # Already here $! might be meaningless.
b0c22438 1894 }
1895 # Since here we might have either success or failure,
a73bef78 1896 # $! is meaningless.
a0d0e21e 1897
a73bef78
JL
1898Here, I<meaningless> means that C<$!> may be unrelated to the outcome
1899of the C<open()> operator. Assignment to C<$!> is similarly ephemeral.
1900It can be used immediately before invoking the C<die()> operator,
1901to set the exit value, or to inspect the system error string
1902corresponding to error I<n>, or to restore C<$!> to a meaningful state.
d54b56d5 1903
b0c22438 1904Mnemonic: What just went bang?
314d39ce 1905
b0c22438 1906=item %OS_ERROR
fb73857a 1907
b0c22438 1908=item %ERRNO
fb73857a 1909
b0c22438 1910=item %!
5b442a2a 1911X<%!> X<%OS_ERROR> X<%ERRNO>
a0d0e21e 1912
b0c22438 1913Each element of C<%!> has a true value only if C<$!> is set to that
241a59d9 1914value. For example, C<$!{ENOENT}> is true if and only if the current
84dabc03 1915value of C<$!> is C<ENOENT>; that is, if the most recent error was "No
1916such file or directory" (or its moral equivalent: not all operating
3b90fd91
RS
1917systems give that exact error, and certainly not all languages). The
1918specific true value is not guaranteed, but in the past has generally
1919been the numeric value of C<$!>. To check if a particular key is
1920meaningful on your system, use C<exists $!{the_key}>; for a list of legal
1921keys, use C<keys %!>. See L<Errno> for more information, and also see
1922L</$!>.
a0d0e21e 1923
b0c22438 1924This variable was added in Perl 5.005.
44f0be63 1925
84dabc03 1926=item $CHILD_ERROR
b687b08b 1927
84dabc03 1928=item $?
1929X<$?> X<$CHILD_ERROR>
a0d0e21e 1930
84dabc03 1931The status returned by the last pipe close, backtick (C<``>) command,
1932successful call to C<wait()> or C<waitpid()>, or from the C<system()>
241a59d9 1933operator. This is just the 16-bit status word returned by the
84dabc03 1934traditional Unix C<wait()> system call (or else is made up to look
241a59d9 1935like it). Thus, the exit value of the subprocess is really (C<<< $? >>
84dabc03 19368 >>>), and C<$? & 127> gives which signal, if any, the process died
1937from, and C<$? & 128> reports whether there was a core dump.
a0d0e21e 1938
84dabc03 1939Additionally, if the C<h_errno> variable is supported in C, its value
1940is returned via C<$?> if any C<gethost*()> function fails.
b687b08b 1941
84dabc03 1942If you have installed a signal handler for C<SIGCHLD>, the
1943value of C<$?> will usually be wrong outside that handler.
a0d0e21e 1944
84dabc03 1945Inside an C<END> subroutine C<$?> contains the value that is going to be
241a59d9
FC
1946given to C<exit()>. You can modify C<$?> in an C<END> subroutine to
1947change the exit status of your program. For example:
a0d0e21e 1948
84dabc03 1949 END {
1950 $? = 1 if $? == 255; # die would make it 255
1951 }
a0d0e21e 1952
84dabc03 1953Under VMS, the pragma C<use vmsish 'status'> makes C<$?> reflect the
1954actual VMS exit status, instead of the default emulation of POSIX
1955status; see L<perlvms/$?> for details.
1956
1957Mnemonic: similar to B<sh> and B<ksh>.
a0d0e21e 1958
b0c22438 1959=item $EVAL_ERROR
f648820c 1960
b0c22438 1961=item $@
1962X<$@> X<$EVAL_ERROR>
a0d0e21e 1963
2e6ba115
LM
1964The Perl error from the last C<eval> operator, i.e. the last exception that
1965was caught. For C<eval BLOCK>, this is either a runtime error message or the
1966string or reference C<die> was called with. The C<eval STRING> form also
1967catches syntax errors and other compile time exceptions.
1968
1969If no error occurs, C<eval> sets C<$@> to the empty string.
a0d0e21e 1970
241a59d9 1971Warning messages are not collected in this variable. You can, however,
b0c22438 1972set up a routine to process warnings by setting C<$SIG{__WARN__}> as
7333b1c4 1973described in L</%SIG>.
748a9306 1974
2e6ba115 1975Mnemonic: Where was the error "at"?
7f315d2e 1976
b0c22438 1977=back
7f315d2e 1978
1fa81471
DR
1979=head2 Variables related to the interpreter state
1980
1981These variables provide information about the current interpreter state.
1982
1983=over 8
1984
1985=item $COMPILING
1986
1987=item $^C
1988X<$^C> X<$COMPILING>
1989
1990The current value of the flag associated with the B<-c> switch.
1991Mainly of use with B<-MO=...> to allow code to alter its behavior
1992when being compiled, such as for example to C<AUTOLOAD> at compile
241a59d9 1993time rather than normal, deferred loading. Setting
1fa81471
DR
1994C<$^C = 1> is similar to calling C<B::minus_c>.
1995
60cf4914 1996This variable was added in Perl v5.6.0.
1fa81471
DR
1997
1998=item $DEBUGGING
1999
2000=item $^D
2001X<$^D> X<$DEBUGGING>
2002
241a59d9 2003The current value of the debugging flags. May be read or set. Like its
a975eeba 2004L<command-line equivalent|perlrun/B<-D>I<letters>>, you can use numeric
8af589bf
KW
2005or symbolic values, e.g. C<$^D = 10> or C<$^D = "st">. See
2006L<perlrun/B<-D>I<number>>. The contents of this variable also affects the
2007debugger operation. See L<perldebguts/Debugger Internals>.
1fa81471
DR
2008
2009Mnemonic: value of B<-D> switch.
2010
2011=item ${^ENCODING}
2012X<${^ENCODING}>
2013
981b911e 2014This variable is no longer supported.
a3ee04ba 2015
981b911e
FC
2016It used to hold the I<object reference> to the C<Encode> object that was
2017used to convert the source code to Unicode.
a3ee04ba 2018
981b911e
FC
2019Its purpose was to allow your non-ASCII Perl
2020scripts not to have to be written in UTF-8; this was
a3ee04ba 2021useful before editors that worked on UTF-8 encoded text were common, but
981b911e
FC
2022that was long ago. It caused problems, such as affecting the operation
2023of other modules that weren't expecting it, causing general mayhem.
a3ee04ba 2024
981b911e
FC
2025If you need something like this functionality, it is recommended that use
2026you a simple source filter, such as L<Filter::Encoding>.
a3ee04ba
KW
2027
2028If you are coming here because code of yours is being adversely affected
2029by someone's use of this variable, you can usually work around it by
2030doing this:
2031
2032 local ${^ENCODING};
2033
2034near the beginning of the functions that are getting broken. This
2035undefines the variable during the scope of execution of the including
2036function.
1fa81471 2037
981b911e 2038This variable was added in Perl 5.8.2 and removed in 5.26.0.
fd503f5c 2039Setting it to anything other than C<undef> was made fatal in Perl 5.28.0.
1fa81471
DR
2040
2041=item ${^GLOBAL_PHASE}
2042X<${^GLOBAL_PHASE}>
2043
2044The current phase of the perl interpreter.
2045
2046Possible values are:
2047
2048=over 8
2049
2050=item CONSTRUCT
2051
241a59d9 2052The C<PerlInterpreter*> is being constructed via C<perl_construct>. This
1fa81471 2053value is mostly there for completeness and for use via the
241a59d9 2054underlying C variable C<PL_phase>. It's not really possible for Perl
1fa81471
DR
2055code to be executed unless construction of the interpreter is
2056finished.
2057
2058=item START
2059
241a59d9 2060This is the global compile-time. That includes, basically, every
1fa81471
DR
2061C<BEGIN> block executed directly or indirectly from during the
2062compile-time of the top-level program.
2063
2064This phase is not called "BEGIN" to avoid confusion with
2065C<BEGIN>-blocks, as those are executed during compile-time of any
241a59d9 2066compilation unit, not just the top-level program. A new, localised
1fa81471
DR
2067compile-time entered at run-time, for example by constructs as
2068C<eval "use SomeModule"> are not global interpreter phases, and
2069therefore aren't reflected by C<${^GLOBAL_PHASE}>.
2070
2071=item CHECK
2072
2073Execution of any C<CHECK> blocks.
2074
2075=item INIT
2076
2077Similar to "CHECK", but for C<INIT>-blocks, not C<CHECK> blocks.
2078
2079=item RUN
2080
2081The main run-time, i.e. the execution of C<PL_main_root>.
2082
2083=item END
2084
2085Execution of any C<END> blocks.
2086
2087=item DESTRUCT
2088
2089Global destruction.
2090
2091=back
2092
241a59d9 2093Also note that there's no value for UNITCHECK-blocks. That's because
1fa81471
DR
2094those are run for each compilation unit individually, and therefore is
2095not a global interpreter phase.
2096
2097Not every program has to go through each of the possible phases, but
2098transition from one phase to another can only happen in the order
2099described in the above list.
2100
2101An example of all of the phases Perl code can see:
2102
2103 BEGIN { print "compile-time: ${^GLOBAL_PHASE}\n" }
2104
2105 INIT { print "init-time: ${^GLOBAL_PHASE}\n" }
2106
2107 CHECK { print "check-time: ${^GLOBAL_PHASE}\n" }
2108
2109 {
2110 package Print::Phase;
2111
2112 sub new {
2113 my ($class, $time) = @_;
2114 return bless \$time, $class;
2115 }
2116
2117 sub DESTROY {
2118 my $self = shift;
2119 print "$$self: ${^GLOBAL_PHASE}\n";
2120 }
2121 }
2122
2123 print "run-time: ${^GLOBAL_PHASE}\n";
2124
2125 my $runtime = Print::Phase->new(
2126 "lexical variables are garbage collected before END"
2127 );
2128
2129 END { print "end-time: ${^GLOBAL_PHASE}\n" }
2130
2131 our $destruct = Print::Phase->new(
2132 "package variables are garbage collected after END"
2133 );
2134
2135This will print out
2136
2137 compile-time: START
2138 check-time: CHECK
2139 init-time: INIT
2140 run-time: RUN
2141 lexical variables are garbage collected before END: RUN
2142 end-time: END
2143 package variables are garbage collected after END: DESTRUCT
2144
2145This variable was added in Perl 5.14.0.
2146
2147=item $^H
2148X<$^H>
2149
241a59d9
FC
2150WARNING: This variable is strictly for
2151internal use only. Its availability,
1fa81471
DR
2152behavior, and contents are subject to change without notice.
2153
241a59d9 2154This variable contains compile-time hints for the Perl interpreter. At the
1fa81471
DR
2155end of compilation of a BLOCK the value of this variable is restored to the
2156value when the interpreter started to compile the BLOCK.
2157
2158When perl begins to parse any block construct that provides a lexical scope
2159(e.g., eval body, required file, subroutine body, loop body, or conditional
2160block), the existing value of C<$^H> is saved, but its value is left unchanged.
2161When the compilation of the block is completed, it regains the saved value.
2162Between the points where its value is saved and restored, code that
2163executes within BEGIN blocks is free to change the value of C<$^H>.
2164
2165This behavior provides the semantic of lexical scoping, and is used in,
2166for instance, the C<use strict> pragma.
2167
2168The contents should be an integer; different bits of it are used for
241a59d9 2169different pragmatic flags. Here's an example:
1fa81471 2170
9548c15c 2171 sub add_100 { $^H |= 0x100 }
1fa81471 2172
9548c15c
FC
2173 sub foo {
2174 BEGIN { add_100() }
2175 bar->baz($boon);
2176 }
1fa81471 2177
241a59d9 2178Consider what happens during execution of the BEGIN block. At this point
1fa81471 2179the BEGIN block has already been compiled, but the body of C<foo()> is still
241a59d9
FC
2180being compiled. The new value of C<$^H>
2181will therefore be visible only while
1fa81471
DR
2182the body of C<foo()> is being compiled.
2183
2184Substitution of C<BEGIN { add_100() }> block with:
2185
9548c15c 2186 BEGIN { require strict; strict->import('vars') }
1fa81471 2187
241a59d9 2188demonstrates how C<use strict 'vars'> is implemented. Here's a conditional
1fa81471
DR
2189version of the same lexical pragma:
2190
9548c15c
FC
2191 BEGIN {
2192 require strict; strict->import('vars') if $condition
2193 }
1fa81471
DR
2194
2195This variable was added in Perl 5.003.
2196
2197=item %^H
2198X<%^H>
2199
241a59d9
FC
2200The C<%^H> hash provides the same scoping semantic as C<$^H>. This makes
2201it useful for implementation of lexically scoped pragmas. See
112284f4
KW
2202L<perlpragma>. All the entries are stringified when accessed at
2203runtime, so only simple values can be accommodated. This means no
2204pointers to objects, for example.
1fa81471
DR
2205
2206When putting items into C<%^H>, in order to avoid conflicting with other
2207users of the hash there is a convention regarding which keys to use.
2208A module should use only keys that begin with the module's name (the
2209name of its main package) and a "/" character. For example, a module
2210C<Foo::Bar> should use keys such as C<Foo::Bar/baz>.
2211
60cf4914 2212This variable was added in Perl v5.6.0.
1fa81471
DR
2213
2214=item ${^OPEN}
2215X<${^OPEN}>
2216
241a59d9 2217An internal variable used by PerlIO. A string in two parts, separated
1fa81471
DR
2218by a C<\0> byte, the first part describes the input layers, the second
2219part describes the output layers.
2220
60cf4914 2221This variable was added in Perl v5.8.0.
1fa81471
DR
2222
2223=item $PERLDB
2224
2225=item $^P
2226X<$^P> X<$PERLDB>
2227
241a59d9 2228The internal variable for debugging support. The meanings of the
1fa81471
DR
2229various bits are subject to change, but currently indicate:
2230
2231=over 6
2232
2233=item 0x01
2234
2235Debug subroutine enter/exit.
2236
2237=item 0x02
2238
241a59d9
FC
2239Line-by-line debugging. Causes C<DB::DB()> subroutine to be called for
2240each statement executed. Also causes saving source code lines (like
22410x400).
1fa81471
DR
2242
2243=item 0x04
2244
2245Switch off optimizations.
2246
2247=item 0x08
2248
2249Preserve more data for future interactive inspections.
2250
2251=item 0x10
2252
2253Keep info about source lines on which a subroutine is defined.
2254
2255=item 0x20
2256
2257Start with single-step on.
2258
2259=item 0x40
2260
2261Use subroutine address instead of name when reporting.
2262
2263=item 0x80
2264
2265Report C<goto &subroutine> as well.
2266
2267=item 0x100
2268
2269Provide informative "file" names for evals based on the place they were compiled.
2270
2271=item 0x200
2272
2273Provide informative names to anonymous subroutines based on the place they
2274were compiled.
2275
2276=item 0x400
2277
2278Save source code lines into C<@{"_<$filename"}>.
2279
aab47982
RS
2280=item 0x800
2281
2282When saving source, include evals that generate no subroutines.
2283
2284=item 0x1000
2285
2286When saving source, include source that did not compile.
2287
1fa81471
DR
2288=back
2289
2290Some bits may be relevant at compile-time only, some at
241a59d9 2291run-time only. This is a new mechanism and the details may change.
1fa81471
DR
2292See also L<perldebguts>.
2293
2294=item ${^TAINT}
2295X<${^TAINT}>
2296
241a59d9 2297Reflects if taint mode is on or off. 1 for on (the program was run with
1fa81471
DR
2298B<-T>), 0 for off, -1 when only taint warnings are enabled (i.e. with
2299B<-t> or B<-TU>).
2300
2301This variable is read-only.
2302
60cf4914 2303This variable was added in Perl v5.8.0.
1fa81471 2304
f512d242
KW
2305=item ${^SAFE_LOCALES}
2306X<${^SAFE_LOCALES}>
2307
2308Reflects if safe locale operations are available to this perl (when the
2309value is 1) or not (the value is 0). This variable is always 1 if the
e9bc6d6b
KW
2310perl has been compiled without threads. It is also 1 if this perl is
2311using thread-safe locale operations. Note that an individual thread may
2312choose to use the global locale (generally unsafe) by calling
58e641fb 2313L<perlapi/switch_to_global_locale>. This variable currently is still
e9bc6d6b 2314set to 1 in such threads.
f512d242
KW
2315
2316This variable is read-only.
2317
2318This variable was added in Perl v5.28.0.
2319
1fa81471
DR
2320=item ${^UNICODE}
2321X<${^UNICODE}>
2322
241a59d9 2323Reflects certain Unicode settings of Perl. See L<perlrun>
1fa81471
DR
2324documentation for the C<-C> switch for more information about
2325the possible values.
2326
2327This variable is set during Perl startup and is thereafter read-only.
2328
60cf4914 2329This variable was added in Perl v5.8.2.
1fa81471
DR
2330
2331=item ${^UTF8CACHE}
2332X<${^UTF8CACHE}>
2333
2334This variable controls the state of the internal UTF-8 offset caching code.
23351 for on (the default), 0 for off, -1 to debug the caching code by checking
2336all its results against linear scans, and panicking on any discrepancy.
2337
94df5432
KW
2338This variable was added in Perl v5.8.9. It is subject to change or
2339removal without notice, but is currently used to avoid recalculating the
2340boundaries of multi-byte UTF-8-encoded characters.
1fa81471
DR
2341
2342=item ${^UTF8LOCALE}
2343X<${^UTF8LOCALE}>
2344
2345This variable indicates whether a UTF-8 locale was detected by perl at
241a59d9 2346startup. This information is used by perl when it's in
1fa81471
DR
2347adjust-utf8ness-to-locale mode (as when run with the C<-CL> command-line
2348switch); see L<perlrun> for more info on this.
2349
60cf4914 2350This variable was added in Perl v5.8.8.
1fa81471
DR
2351
2352=back
2353
b0c22438 2354=head2 Deprecated and removed variables
7f315d2e 2355
0b9346e6 2356Deprecating a variable announces the intent of the perl maintainers to
241a59d9
FC
2357eventually remove the variable from the language. It may still be
2358available despite its status. Using a deprecated variable triggers
b0c22438 2359a warning.
7f315d2e 2360
84dabc03 2361Once a variable is removed, its use triggers an error telling you
b0c22438 2362the variable is unsupported.
7f315d2e 2363
84dabc03 2364See L<perldiag> for details about error messages.
7f315d2e 2365
b0c22438 2366=over 8
7f315d2e 2367
84dabc03 2368=item $#
b7a15f05 2369X<$#>
84dabc03 2370
38e5787b 2371C<$#> was a variable that could be used to format printed numbers.
60cf4914 2372After a deprecation cycle, its magic was removed in Perl v5.10.0 and
84dabc03 2373using it now triggers a warning: C<$# is no longer supported>.
2374
2375This is not the sigil you use in front of an array name to get the
241a59d9
FC
2376last index, like C<$#array>. That's still how you get the last index
2377of an array in Perl. The two have nothing to do with each other.
84dabc03 2378
2379Deprecated in Perl 5.
2380
60cf4914 2381Removed in Perl v5.10.0.
84dabc03 2382
7f315d2e
CO
2383=item $*
2384X<$*>
2385
84dabc03 2386C<$*> was a variable that you could use to enable multiline matching.
60cf4914 2387After a deprecation cycle, its magic was removed in Perl v5.10.0.
7f315d2e 2388Using it now triggers a warning: C<$* is no longer supported>.
84dabc03 2389You should use the C</s> and C</m> regexp modifiers instead.
7f315d2e 2390
b0c22438 2391Deprecated in Perl 5.
7f315d2e 2392
60cf4914 2393Removed in Perl v5.10.0.
7f315d2e 2394
84dabc03 2395=item $[
b7a15f05 2396X<$[>
84dabc03 2397
b82b06b8
FC
2398This variable stores the index of the first element in an array, and
2399of the first character in a substring. The default is 0, but you could
2400theoretically set it to 1 to make Perl behave more like B<awk> (or Fortran)
2401when subscripting and when evaluating the index() and substr() functions.
84dabc03 2402
b82b06b8
FC
2403As of release 5 of Perl, assignment to C<$[> is treated as a compiler
2404directive, and cannot influence the behavior of any other file.
2405(That's why you can only assign compile-time constants to it.)
2406Its use is highly discouraged.
2407
60cf4914 2408Prior to Perl v5.10.0, assignment to C<$[> could be seen from outer lexical
b82b06b8
FC
2409scopes in the same file, unlike other compile-time directives (such as
2410L<strict>). Using local() on it would bind its value strictly to a lexical
2411block. Now it is always lexically scoped.
2412
c22e17d0 2413As of Perl v5.16.0, it is implemented by the L<arybase> module.
84dabc03 2414
c22e17d0
DIM
2415As of Perl v5.30.0, or under C<use v5.16>, or C<no feature "array_base">,
2416C<$[> no longer has any effect, and always contains 0.
2417Assigning 0 to it is permitted, but any other value will produce an error.
6b54f8ab 2418
b82b06b8
FC
2419Mnemonic: [ begins subscripts.
2420
60cf4914 2421Deprecated in Perl v5.12.0.
e1dccc0d 2422
b0c22438 2423=back
2b92dfce 2424
0b9346e6 2425=cut