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