This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perlvar: Note a deprecation
[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
9548c15c 374 $foo{$a,$b,$c}
0b9346e6 375
376it really means
377
9548c15c 378 $foo{join($;, $a, $b, $c)}
0b9346e6 379
380But don't put
381
9548c15c 382 @foo{$a,$b,$c} # a slice--note the @
0b9346e6 383
384which means
385
9548c15c 386 ($foo{$a},$foo{$b},$foo{$c})
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,
660represented as a C<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
b0c22438 664as a v-string.
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
b0c22438 671To convert C<$^V> into its string representation use C<sprintf()>'s
672C<"%vd"> conversion:
a0d0e21e 673
9548c15c 674 printf "version is v%vd\n", $^V; # Perl's version
a0d0e21e 675
b0c22438 676See the documentation of C<use VERSION> and C<require VERSION>
677for a convenient way to fail if the running Perl interpreter is too old.
4d76a344 678
b0c22438 679See also C<$]> for an older representation of the Perl version.
a0d0e21e 680
60cf4914 681This variable was added in Perl v5.6.0.
a0d0e21e 682
b0c22438 683Mnemonic: use ^V for Version Control.
a0d0e21e 684
b0c22438 685=item ${^WIN32_SLOPPY_STAT}
5b442a2a 686X<${^WIN32_SLOPPY_STAT}> X<sitecustomize> X<sitecustomize.pl>
a0d0e21e 687
b0c22438 688If this variable is set to a true value, then C<stat()> on Windows will
241a59d9 689not try to open the file. This means that the link count cannot be
b0c22438 690determined and file attributes may be out of date if additional
241a59d9 691hardlinks to the file exist. On the other hand, not opening the file
b0c22438 692is considerably faster, especially for files on network drives.
a0d0e21e 693
b0c22438 694This variable could be set in the F<sitecustomize.pl> file to
695configure the local Perl installation to use "sloppy" C<stat()> by
241a59d9 696default. See the documentation for B<-f> in
b0c22438 697L<perlrun|perlrun/"Command Switches"> for more information about site
698customization.
a0d0e21e 699
60cf4914 700This variable was added in Perl v5.10.0.
a0d0e21e 701
b0c22438 702=item $EXECUTABLE_NAME
a0d0e21e 703
b0c22438 704=item $^X
705X<$^X> X<$EXECUTABLE_NAME>
a0d0e21e 706
b0c22438 707The name used to execute the current copy of Perl, from C's
708C<argv[0]> or (where supported) F</proc/self/exe>.
a043a685 709
b0c22438 710Depending on the host operating system, the value of C<$^X> may be
711a relative or absolute pathname of the perl program file, or may
712be the string used to invoke perl but not the pathname of the
241a59d9 713perl program file. Also, most operating systems permit invoking
b0c22438 714programs that are not in the PATH environment variable, so there
241a59d9 715is no guarantee that the value of C<$^X> is in PATH. For VMS, the
b0c22438 716value may or may not include a version number.
a0d0e21e 717
b0c22438 718You usually can use the value of C<$^X> to re-invoke an independent
719copy of the same perl that is currently running, e.g.,
a0d0e21e 720
9548c15c 721 @first_run = `$^X -le "print int rand 100 for 1..100"`;
a0d0e21e 722
b0c22438 723But recall that not all operating systems support forking or
724capturing of the output of commands, so this complex statement
725may not be portable.
a0d0e21e 726
b0c22438 727It is not safe to use the value of C<$^X> as a path name of a file,
728as some operating systems that have a mandatory suffix on
729executable files do not require use of the suffix when invoking
241a59d9 730a command. To convert the value of C<$^X> to a path name, use the
b0c22438 731following statements:
8cc95fdb 732
9548c15c
FC
733 # Build up a set of file names (not command names).
734 use Config;
735 my $this_perl = $^X;
736 if ($^O ne 'VMS') {
737 $this_perl .= $Config{_exe}
738 unless $this_perl =~ m/$Config{_exe}$/i;
739 }
8cc95fdb 740
b0c22438 741Because many operating systems permit anyone with read access to
742the Perl program file to make a copy of it, patch the copy, and
743then execute the copy, the security-conscious Perl programmer
744should take care to invoke the installed copy of perl, not the
241a59d9 745copy referenced by C<$^X>. The following statements accomplish
b0c22438 746this goal, and produce a pathname that can be invoked as a
747command or referenced as a file.
a043a685 748
9548c15c
FC
749 use Config;
750 my $secure_perl_path = $Config{perlpath};
751 if ($^O ne 'VMS') {
752 $secure_perl_path .= $Config{_exe}
753 unless $secure_perl_path =~ m/$Config{_exe}$/i;
754 }
a0d0e21e 755
b0c22438 756=back
a0d0e21e 757
b0c22438 758=head2 Variables related to regular expressions
759
760Most of the special variables related to regular expressions are side
241a59d9
FC
761effects. Perl sets these variables when it has a successful match, so
762you should check the match result before using them. For instance:
b0c22438 763
9548c15c
FC
764 if( /P(A)TT(ER)N/ ) {
765 print "I found $1 and $2\n";
766 }
b0c22438 767
0b9346e6 768These variables are read-only and dynamically-scoped, unless we note
b0c22438 769otherwise.
770
0b9346e6 771The dynamic nature of the regular expression variables means that
772their value is limited to the block that they are in, as demonstrated
773by this bit of code:
b0c22438 774
9548c15c
FC
775 my $outer = 'Wallace and Grommit';
776 my $inner = 'Mutt and Jeff';
0b9346e6 777
9548c15c 778 my $pattern = qr/(\S+) and (\S+)/;
0b9346e6 779
9548c15c 780 sub show_n { print "\$1 is $1; \$2 is $2\n" }
0b9346e6 781
9548c15c
FC
782 {
783 OUTER:
784 show_n() if $outer =~ m/$pattern/;
0b9346e6 785
9548c15c
FC
786 INNER: {
787 show_n() if $inner =~ m/$pattern/;
788 }
0b9346e6 789
9548c15c
FC
790 show_n();
791 }
b0c22438 792
0b9346e6 793The output shows that while in the C<OUTER> block, the values of C<$1>
241a59d9 794and C<$2> are from the match against C<$outer>. Inside the C<INNER>
0b9346e6 795block, the values of C<$1> and C<$2> are from the match against
796C<$inner>, but only until the end of the block (i.e. the dynamic
241a59d9 797scope). After the C<INNER> block completes, the values of C<$1> and
0b9346e6 798C<$2> return to the values for the match against C<$outer> even though
b0c22438 799we have not made another match:
800
9548c15c
FC
801 $1 is Wallace; $2 is Grommit
802 $1 is Mutt; $2 is Jeff
803 $1 is Wallace; $2 is Grommit
a0d0e21e 804
40445027 805=head3 Performance issues
0b9346e6 806
40445027
DM
807Traditionally in Perl, any use of any of the three variables C<$`>, C<$&>
808or C<$'> (or their C<use English> equivalents) anywhere in the code, caused
809all subsequent successful pattern matches to make a copy of the matched
810string, in case the code might subsequently access one of those variables.
811This imposed a considerable performance penalty across the whole program,
812so generally the use of these variables has been discouraged.
0b9346e6 813
40445027
DM
814In Perl 5.6.0 the C<@-> and C<@+> dynamic arrays were introduced that
815supply the indices of successful matches. So you could for example do
816this:
817
818 $str =~ /pattern/;
819
820 print $`, $&, $'; # bad: perfomance hit
821
822 print # good: no perfomance hit
823 substr($str, 0, $-[0]),
824 substr($str, $-[0], $+[0]-$-[0]),
825 substr($str, $+[0]);
826
827In Perl 5.10.0 the C</p> match operator flag and the C<${^PREMATCH}>,
828C<${^MATCH}>, and C<${^POSTMATCH}> variables were introduced, that allowed
829you to suffer the penalties only on patterns marked with C</p>.
830
831In Perl 5.18.0 onwards, perl started noting the presence of each of the
832three variables separately, and only copied that part of the string
833required; so in
834
835 $`; $&; "abcdefgh" =~ /d/
836
837perl would only copy the "abcd" part of the string. That could make a big
838difference in something like
839
840 $str = 'x' x 1_000_000;
841 $&; # whoops
842 $str =~ /x/g # one char copied a million times, not a million chars
843
844In Perl 5.20.0 a new copy-on-write system was enabled by default, which
845finally fixes all performance issues with these three variables, and makes
846them safe to use anywhere.
847
848The C<Devel::NYTProf> and C<Devel::FindAmpersand> modules can help you
849find uses of these problematic match variables in your code.
13b0f67d 850
b0c22438 851=over 8
a0d0e21e 852
b0c22438 853=item $<I<digits>> ($1, $2, ...)
854X<$1> X<$2> X<$3>
8cc95fdb 855
b0c22438 856Contains the subpattern from the corresponding set of capturing
857parentheses from the last successful pattern match, not counting patterns
858matched in nested blocks that have been exited already.
8cc95fdb 859
b0c22438 860These variables are read-only and dynamically-scoped.
a043a685 861
b0c22438 862Mnemonic: like \digits.
a0d0e21e 863
b0c22438 864=item $MATCH
a0d0e21e 865
b0c22438 866=item $&
867X<$&> X<$MATCH>
a0d0e21e 868
b0c22438 869The string matched by the last successful pattern match (not counting
870any matches hidden within a BLOCK or C<eval()> enclosed by the current
871BLOCK).
a0d0e21e 872
40445027
DM
873See L</Performance issues> above for the serious performance implications
874of using this variable (even once) in your code.
80bca1b4 875
b0c22438 876This variable is read-only and dynamically-scoped.
f9cbb277 877
b0c22438 878Mnemonic: like C<&> in some editors.
0b9346e6 879
b0c22438 880=item ${^MATCH}
881X<${^MATCH}>
a0d0e21e 882
b0c22438 883This is similar to C<$&> (C<$MATCH>) except that it does not incur the
13b0f67d 884performance penalty associated with that variable.
40445027
DM
885
886See L</Performance issues> above.
887
13b0f67d 888In Perl v5.18 and earlier, it is only guaranteed
b0c22438 889to return a defined value when the pattern was compiled or executed with
13b0f67d
DM
890the C</p> modifier. In Perl v5.20, the C</p> modifier does nothing, so
891C<${^MATCH}> does the same thing as C<$MATCH>.
80bca1b4 892
60cf4914 893This variable was added in Perl v5.10.0.
4bc88a62 894
b0c22438 895This variable is read-only and dynamically-scoped.
e2975953 896
b0c22438 897=item $PREMATCH
52c447a8 898
b0c22438 899=item $`
5b442a2a 900X<$`> X<$PREMATCH> X<${^PREMATCH}>
7636ea95 901
b0c22438 902The string preceding whatever was matched by the last successful
903pattern match, not counting any matches hidden within a BLOCK or C<eval>
0b9346e6 904enclosed by the current BLOCK.
a0d0e21e 905
40445027
DM
906See L</Performance issues> above for the serious performance implications
907of using this variable (even once) in your code.
a0d0e21e 908
b0c22438 909This variable is read-only and dynamically-scoped.
a0d0e21e 910
b0c22438 911Mnemonic: C<`> often precedes a quoted string.
f83ed198 912
b0c22438 913=item ${^PREMATCH}
5b442a2a 914X<$`> X<${^PREMATCH}>
a0d0e21e 915
b0c22438 916This is similar to C<$`> ($PREMATCH) except that it does not incur the
13b0f67d 917performance penalty associated with that variable.
40445027
DM
918
919See L</Performance issues> above.
920
13b0f67d 921In Perl v5.18 and earlier, it is only guaranteed
b0c22438 922to return a defined value when the pattern was compiled or executed with
13b0f67d
DM
923the C</p> modifier. In Perl v5.20, the C</p> modifier does nothing, so
924C<${^PREMATCH}> does the same thing as C<$PREMATCH>.
a0d0e21e 925
4a70680a 926This variable was added in Perl v5.10.0.
a0d0e21e 927
b0c22438 928This variable is read-only and dynamically-scoped.
a0d0e21e 929
b0c22438 930=item $POSTMATCH
16070b82 931
b0c22438 932=item $'
5b442a2a 933X<$'> X<$POSTMATCH> X<${^POSTMATCH}> X<@->
305aace0 934
b0c22438 935The string following whatever was matched by the last successful
936pattern match (not counting any matches hidden within a BLOCK or C<eval()>
241a59d9 937enclosed by the current BLOCK). Example:
305aace0 938
9548c15c
FC
939 local $_ = 'abcdefghi';
940 /def/;
941 print "$`:$&:$'\n"; # prints abc:def:ghi
305aace0 942
40445027
DM
943See L</Performance issues> above for the serious performance implications
944of using this variable (even once) in your code.
a0d0e21e 945
b0c22438 946This variable is read-only and dynamically-scoped.
947
948Mnemonic: C<'> often follows a quoted string.
949
950=item ${^POSTMATCH}
5b442a2a 951X<${^POSTMATCH}> X<$'> X<$POSTMATCH>
b0c22438 952
953This is similar to C<$'> (C<$POSTMATCH>) except that it does not incur the
13b0f67d 954performance penalty associated with that variable.
40445027
DM
955
956See L</Performance issues> above.
957
13b0f67d 958In Perl v5.18 and earlier, it is only guaranteed
b0c22438 959to return a defined value when the pattern was compiled or executed with
13b0f67d
DM
960the C</p> modifier. In Perl v5.20, the C</p> modifier does nothing, so
961C<${^POSTMATCH}> does the same thing as C<$POSTMATCH>.
b0c22438 962
60cf4914 963This variable was added in Perl v5.10.0.
b0c22438 964
965This variable is read-only and dynamically-scoped.
966
967=item $LAST_PAREN_MATCH
968
969=item $+
970X<$+> X<$LAST_PAREN_MATCH>
971
972The text matched by the last bracket of the last successful search pattern.
973This is useful if you don't know which one of a set of alternative patterns
241a59d9 974matched. For example:
b0c22438 975
9548c15c 976 /Version: (.*)|Revision: (.*)/ && ($rev = $+);
b0c22438 977
978This variable is read-only and dynamically-scoped.
979
980Mnemonic: be positive and forward looking.
981
982=item $LAST_SUBMATCH_RESULT
983
984=item $^N
5b442a2a 985X<$^N> X<$LAST_SUBMATCH_RESULT>
b0c22438 986
987The text matched by the used group most-recently closed (i.e. the group
988with the rightmost closing parenthesis) of the last successful search
989pattern.
990
991This is primarily used inside C<(?{...})> blocks for examining text
241a59d9 992recently matched. For example, to effectively capture text to a variable
b0c22438 993(in addition to C<$1>, C<$2>, etc.), replace C<(...)> with
994
9548c15c 995 (?:(...)(?{ $var = $^N }))
b0c22438 996
997By setting and then using C<$var> in this way relieves you from having to
998worry about exactly which numbered set of parentheses they are.
999
60cf4914 1000This variable was added in Perl v5.8.0.
b0c22438 1001
1002Mnemonic: the (possibly) Nested parenthesis that most recently closed.
1003
1004=item @LAST_MATCH_END
1005
1006=item @+
1007X<@+> X<@LAST_MATCH_END>
1008
1009This array holds the offsets of the ends of the last successful
241a59d9
FC
1010submatches in the currently active dynamic scope. C<$+[0]> is
1011the offset into the string of the end of the entire match. This
b0c22438 1012is the same value as what the C<pos> function returns when called
241a59d9 1013on the variable that was matched against. The I<n>th element
b0c22438 1014of this array holds the offset of the I<n>th submatch, so
1015C<$+[1]> is the offset past where C<$1> ends, C<$+[2]> the offset
241a59d9
FC
1016past where C<$2> ends, and so on. You can use C<$#+> to determine
1017how many subgroups were in the last successful match. See the
b0c22438 1018examples given for the C<@-> variable.
1019
60cf4914 1020This variable was added in Perl v5.6.0.
b0c22438 1021
1022=item %LAST_PAREN_MATCH
1023
1024=item %+
5b442a2a 1025X<%+> X<%LAST_PAREN_MATCH>
b0c22438 1026
1027Similar to C<@+>, the C<%+> hash allows access to the named capture
1028buffers, should they exist, in the last successful match in the
1029currently active dynamic scope.
1030
1031For example, C<$+{foo}> is equivalent to C<$1> after the following match:
1032
9548c15c 1033 'foo' =~ /(?<foo>foo)/;
b0c22438 1034
1035The keys of the C<%+> hash list only the names of buffers that have
1036captured (and that are thus associated to defined values).
1037
1038The underlying behaviour of C<%+> is provided by the
1039L<Tie::Hash::NamedCapture> module.
1040
1041B<Note:> C<%-> and C<%+> are tied views into a common internal hash
241a59d9 1042associated with the last successful regular expression. Therefore mixing
b0c22438 1043iterative access to them via C<each> may have unpredictable results.
1044Likewise, if the last successful match changes, then the results may be
1045surprising.
1046
60cf4914 1047This variable was added in Perl v5.10.0.
a0d0e21e 1048
b0c22438 1049This variable is read-only and dynamically-scoped.
1050
1051=item @LAST_MATCH_START
1052
1053=item @-
1054X<@-> X<@LAST_MATCH_START>
1055
1056C<$-[0]> is the offset of the start of the last successful match.
1057C<$-[>I<n>C<]> is the offset of the start of the substring matched by
1058I<n>-th subpattern, or undef if the subpattern did not match.
1059
1060Thus, after a match against C<$_>, C<$&> coincides with C<substr $_, $-[0],
241a59d9 1061$+[0] - $-[0]>. Similarly, $I<n> coincides with C<substr $_, $-[n],
b0c22438 1062$+[n] - $-[n]> if C<$-[n]> is defined, and $+ coincides with
241a59d9
FC
1063C<substr $_, $-[$#-], $+[$#-] - $-[$#-]>. One can use C<$#-> to find the
1064last matched subgroup in the last successful match. Contrast with
1065C<$#+>, the number of subgroups in the regular expression. Compare
b0c22438 1066with C<@+>.
1067
1068This array holds the offsets of the beginnings of the last
1069successful submatches in the currently active dynamic scope.
1070C<$-[0]> is the offset into the string of the beginning of the
241a59d9 1071entire match. The I<n>th element of this array holds the offset
b0c22438 1072of the I<n>th submatch, so C<$-[1]> is the offset where C<$1>
1073begins, C<$-[2]> the offset where C<$2> begins, and so on.
1074
1075After a match against some variable C<$var>:
1076
1077=over 5
1078
1079=item C<$`> is the same as C<substr($var, 0, $-[0])>
1080
1081=item C<$&> is the same as C<substr($var, $-[0], $+[0] - $-[0])>
1082
1083=item C<$'> is the same as C<substr($var, $+[0])>
1084
1085=item C<$1> is the same as C<substr($var, $-[1], $+[1] - $-[1])>
1086
1087=item C<$2> is the same as C<substr($var, $-[2], $+[2] - $-[2])>
1088
1089=item C<$3> is the same as C<substr($var, $-[3], $+[3] - $-[3])>
1090
1091=back
1092
60cf4914 1093This variable was added in Perl v5.6.0.
b0c22438 1094
5b442a2a 1095=item %LAST_MATCH_START
1096
b0c22438 1097=item %-
5b442a2a 1098X<%-> X<%LAST_MATCH_START>
b0c22438 1099
1100Similar to C<%+>, this variable allows access to the named capture groups
241a59d9 1101in the last successful match in the currently active dynamic scope. To
b0c22438 1102each capture group name found in the regular expression, it associates a
1103reference to an array containing the list of values captured by all
1104buffers with that name (should there be several of them), in the order
1105where they appear.
1106
1107Here's an example:
1108
1109 if ('1234' =~ /(?<A>1)(?<B>2)(?<A>3)(?<B>4)/) {
1110 foreach my $bufname (sort keys %-) {
1111 my $ary = $-{$bufname};
1112 foreach my $idx (0..$#$ary) {
1113 print "\$-{$bufname}[$idx] : ",
9548c15c
FC
1114 (defined($ary->[$idx])
1115 ? "'$ary->[$idx]'"
1116 : "undef"),
b0c22438 1117 "\n";
1118 }
1119 }
1120 }
1121
1122would print out:
1123
9548c15c
FC
1124 $-{A}[0] : '1'
1125 $-{A}[1] : '3'
1126 $-{B}[0] : '2'
1127 $-{B}[1] : '4'
b0c22438 1128
1129The keys of the C<%-> hash correspond to all buffer names found in
1130the regular expression.
1131
1132The behaviour of C<%-> is implemented via the
1133L<Tie::Hash::NamedCapture> module.
1134
1135B<Note:> C<%-> and C<%+> are tied views into a common internal hash
241a59d9 1136associated with the last successful regular expression. Therefore mixing
b0c22438 1137iterative access to them via C<each> may have unpredictable results.
1138Likewise, if the last successful match changes, then the results may be
1139surprising.
1140
60cf4914 1141This variable was added in Perl v5.10.0.
b0c22438 1142
1143This variable is read-only and dynamically-scoped.
1144
1145=item $LAST_REGEXP_CODE_RESULT
1146
1147=item $^R
1148X<$^R> X<$LAST_REGEXP_CODE_RESULT>
1149
1150The result of evaluation of the last successful C<(?{ code })>
241a59d9 1151regular expression assertion (see L<perlre>). May be written to.
b0c22438 1152
1153This variable was added in Perl 5.005.
a0d0e21e 1154
a3621e74 1155=item ${^RE_DEBUG_FLAGS}
ca1b95ae 1156X<${^RE_DEBUG_FLAGS}>
a3621e74 1157
241a59d9
FC
1158The current value of the regex debugging flags. Set to 0 for no debug output
1159even when the C<re 'debug'> module is loaded. See L<re> for details.
b0c22438 1160
60cf4914 1161This variable was added in Perl v5.10.0.
a3621e74 1162
0111c4fd 1163=item ${^RE_TRIE_MAXBUF}
ca1b95ae 1164X<${^RE_TRIE_MAXBUF}>
a3621e74
YO
1165
1166Controls how certain regex optimisations are applied and how much memory they
241a59d9
FC
1167utilize. This value by default is 65536 which corresponds to a 512kB
1168temporary cache. Set this to a higher value to trade
1169memory for speed when matching large alternations. Set
1170it to a lower value if you want the optimisations to
a3621e74
YO
1171be as conservative of memory as possible but still occur, and set it to a
1172negative value to prevent the optimisation and conserve the most memory.
1173Under normal situations this variable should be of no interest to you.
1174
60cf4914 1175This variable was added in Perl v5.10.0.
a0d0e21e 1176
b0c22438 1177=back
a0d0e21e 1178
b0c22438 1179=head2 Variables related to filehandles
a0d0e21e 1180
b0c22438 1181Variables that depend on the currently selected filehandle may be set
1182by calling an appropriate object method on the C<IO::Handle> object,
1183although this is less efficient than using the regular built-in
241a59d9 1184variables. (Summary lines below for this contain the word HANDLE.)
b0c22438 1185First you must say
6e2995f4 1186
9548c15c 1187 use IO::Handle;
0462a1ab 1188
b0c22438 1189after which you may use either
0462a1ab 1190
9548c15c 1191 method HANDLE EXPR
0462a1ab 1192
b0c22438 1193or more safely,
0462a1ab 1194
9548c15c 1195 HANDLE->method(EXPR)
0462a1ab 1196
241a59d9 1197Each method returns the old value of the C<IO::Handle> attribute. The
b0c22438 1198methods each take an optional EXPR, which, if supplied, specifies the
241a59d9 1199new value for the C<IO::Handle> attribute in question. If not
b0c22438 1200supplied, most methods do nothing to the current value--except for
1201C<autoflush()>, which will assume a 1 for you, just to be different.
0462a1ab 1202
b0c22438 1203Because loading in the C<IO::Handle> class is an expensive operation,
1204you should learn how to use the regular built-in variables.
1205
241a59d9 1206A few of these variables are considered "read-only". This means that
b0c22438 1207if you try to assign to this variable, either directly or indirectly
1208through a reference, you'll raise a run-time exception.
1209
1210You should be very careful when modifying the default values of most
241a59d9 1211special variables described in this document. In most cases you want
b0c22438 1212to localize these variables before changing them, since if you don't,
1213the change may affect other modules which rely on the default values
241a59d9 1214of the special variables that you have changed. This is one of the
b0c22438 1215correct ways to read the whole file at once:
1216
9548c15c
FC
1217 open my $fh, "<", "foo" or die $!;
1218 local $/; # enable localized slurp mode
1219 my $content = <$fh>;
1220 close $fh;
b0c22438 1221
1222But the following code is quite bad:
1223
9548c15c
FC
1224 open my $fh, "<", "foo" or die $!;
1225 undef $/; # enable slurp mode
1226 my $content = <$fh>;
1227 close $fh;
b0c22438 1228
1229since some other module, may want to read data from some file in the
1230default "line mode", so if the code we have just presented has been
1231executed, the global value of C<$/> is now changed for any other code
1232running inside the same Perl interpreter.
1233
1234Usually when a variable is localized you want to make sure that this
241a59d9
FC
1235change affects the shortest scope possible. So unless you are already
1236inside some short C<{}> block, you should create one yourself. For
b0c22438 1237example:
1238
9548c15c
FC
1239 my $content = '';
1240 open my $fh, "<", "foo" or die $!;
1241 {
1242 local $/;
1243 $content = <$fh>;
1244 }
1245 close $fh;
0462a1ab 1246
b0c22438 1247Here is an example of how your own code can go broken:
0462a1ab 1248
9548c15c
FC
1249 for ( 1..3 ){
1250 $\ = "\r\n";
1251 nasty_break();
1252 print "$_";
1253 }
0b9346e6 1254
9548c15c 1255 sub nasty_break {
0b9346e6 1256 $\ = "\f";
1257 # do something with $_
9548c15c 1258 }
0462a1ab 1259
0b9346e6 1260You probably expect this code to print the equivalent of
0462a1ab 1261
0b9346e6 1262 "1\r\n2\r\n3\r\n"
0462a1ab 1263
b0c22438 1264but instead you get:
0462a1ab 1265
0b9346e6 1266 "1\f2\f3\f"
0462a1ab 1267
0b9346e6 1268Why? Because C<nasty_break()> modifies C<$\> without localizing it
241a59d9
FC
1269first. The value you set in C<nasty_break()> is still there when you
1270return. The fix is to add C<local()> so the value doesn't leak out of
0b9346e6 1271C<nasty_break()>:
6e2995f4 1272
9548c15c 1273 local $\ = "\f";
a0d0e21e 1274
b0c22438 1275It's easy to notice the problem in such a short example, but in more
1276complicated code you are looking for trouble if you don't localize
1277changes to the special variables.
a0d0e21e 1278
b0c22438 1279=over 8
a0d0e21e 1280
b0c22438 1281=item $ARGV
1282X<$ARGV>
fb73857a 1283
ca1b95ae 1284Contains the name of the current file when reading from C<< <> >>.
b0c22438 1285
1286=item @ARGV
1287X<@ARGV>
1288
ca1b95ae 1289The array C<@ARGV> contains the command-line arguments intended for
241a59d9 1290the script. C<$#ARGV> is generally the number of arguments minus
b0c22438 1291one, because C<$ARGV[0]> is the first argument, I<not> the program's
241a59d9 1292command name itself. See L</$0> for the command name.
b0c22438 1293
84dabc03 1294=item ARGV
1295X<ARGV>
1296
1297The special filehandle that iterates over command-line filenames in
241a59d9
FC
1298C<@ARGV>. Usually written as the null filehandle in the angle operator
1299C<< <> >>. Note that currently C<ARGV> only has its magical effect
84dabc03 1300within the C<< <> >> operator; elsewhere it is just a plain filehandle
241a59d9 1301corresponding to the last file opened by C<< <> >>. In particular,
84dabc03 1302passing C<\*ARGV> as a parameter to a function that expects a filehandle
1303may not cause your function to automatically read the contents of all the
1304files in C<@ARGV>.
1305
b0c22438 1306=item ARGVOUT
1307X<ARGVOUT>
1308
1309The special filehandle that points to the currently open output file
241a59d9
FC
1310when doing edit-in-place processing with B<-i>. Useful when you have
1311to do a lot of inserting and don't want to keep modifying C<$_>. See
b0c22438 1312L<perlrun> for the B<-i> switch.
1313
96948506 1314=item IO::Handle->output_field_separator( EXPR )
84dabc03 1315
1316=item $OUTPUT_FIELD_SEPARATOR
1317
1318=item $OFS
1319
1320=item $,
1321X<$,> X<$OFS> X<$OUTPUT_FIELD_SEPARATOR>
1322
241a59d9
FC
1323The output field separator for the print operator. If defined, this
1324value is printed between each of print's arguments. Default is C<undef>.
84dabc03 1325
96948506 1326You cannot call C<output_field_separator()> on a handle, only as a
008f9687 1327static method. See L<IO::Handle|IO::Handle>.
96948506 1328
84dabc03 1329Mnemonic: what is printed when there is a "," in your print statement.
1330
5b442a2a 1331=item HANDLE->input_line_number( EXPR )
b0c22438 1332
1333=item $INPUT_LINE_NUMBER
1334
1335=item $NR
1336
1337=item $.
1338X<$.> X<$NR> X<$INPUT_LINE_NUMBER> X<line number>
1339
1340Current line number for the last filehandle accessed.
1341
1342Each filehandle in Perl counts the number of lines that have been read
241a59d9 1343from it. (Depending on the value of C<$/>, Perl's idea of what
b0c22438 1344constitutes a line may not match yours.) When a line is read from a
1345filehandle (via C<readline()> or C<< <> >>), or when C<tell()> or
1346C<seek()> is called on it, C<$.> becomes an alias to the line counter
1347for that filehandle.
1348
1349You can adjust the counter by assigning to C<$.>, but this will not
241a59d9
FC
1350actually move the seek pointer. I<Localizing C<$.> will not localize
1351the filehandle's line count>. Instead, it will localize perl's notion
b0c22438 1352of which filehandle C<$.> is currently aliased to.
1353
1354C<$.> is reset when the filehandle is closed, but B<not> when an open
241a59d9
FC
1355filehandle is reopened without an intervening C<close()>. For more
1356details, see L<perlop/"IE<sol>O Operators">. Because C<< <> >> never does
b0c22438 1357an explicit close, line numbers increase across C<ARGV> files (but see
1358examples in L<perlfunc/eof>).
1359
1360You can also use C<< HANDLE->input_line_number(EXPR) >> to access the
1361line counter for a given filehandle without having to worry about
1362which handle you last accessed.
1363
1364Mnemonic: many programs use "." to mean the current line number.
1365
96948506 1366=item IO::Handle->input_record_separator( EXPR )
b0c22438 1367
1368=item $INPUT_RECORD_SEPARATOR
1369
1370=item $RS
1371
1372=item $/
1373X<$/> X<$RS> X<$INPUT_RECORD_SEPARATOR>
1374
241a59d9
FC
1375The input record separator, newline by default. This influences Perl's
1376idea of what a "line" is. Works like B<awk>'s RS variable, including
84dabc03 1377treating empty lines as a terminator if set to the null string (an
241a59d9 1378empty line cannot contain any spaces or tabs). You may set it to a
84dabc03 1379multi-character string to match a multi-character terminator, or to
241a59d9 1380C<undef> to read through the end of file. Setting it to C<"\n\n">
84dabc03 1381means something slightly different than setting to C<"">, if the file
241a59d9
FC
1382contains consecutive empty lines. Setting to C<""> will treat two or
1383more consecutive empty lines as a single empty line. Setting to
84dabc03 1384C<"\n\n"> will blindly assume that the next input character belongs to
1385the next paragraph, even if it's a newline.
b0c22438 1386
1387 local $/; # enable "slurp" mode
1388 local $_ = <FH>; # whole file now here
1389 s/\n[ \t]+/ /g;
1390
241a59d9 1391Remember: the value of C<$/> is a string, not a regex. B<awk> has to
b0c22438 1392be better for something. :-)
1393
1394Setting C<$/> to a reference to an integer, scalar containing an
1395integer, or scalar that's convertible to an integer will attempt to
1396read records instead of lines, with the maximum record size being the
3d249121 1397referenced integer number of characters. So this:
b0c22438 1398
1399 local $/ = \32768; # or \"32768", or \$var_containing_32768
1400 open my $fh, "<", $myfile or die $!;
1401 local $_ = <$fh>;
fb73857a 1402
f1ee460b 1403will read a record of no more than 32768 characters from $fh. If you're
b0c22438 1404not reading from a record-oriented file (or your OS doesn't have
1405record-oriented files), then you'll likely get a full chunk of data
241a59d9
FC
1406with every read. If a record is larger than the record size you've
1407set, you'll get the record back in pieces. Trying to set the record
b3a2acfa
YO
1408size to zero or less is deprecated and will cause $/ to have the value
1409of "undef", which will cause reading in the (rest of the) whole file.
1410
1411As of 5.19.9 setting C<$/> to any other form of reference will throw a
1412fatal exception. This is in preparation for supporting new ways to set
1413C<$/> in the future.
6e2995f4 1414
78c28381 1415On VMS only, record reads bypass PerlIO layers and any associated
3d249121 1416buffering, so you must not mix record and non-record reads on the
78c28381
CB
1417same filehandle. Record mode mixes with line mode only when the
1418same buffering layer is in use for both modes.
5c055ba3 1419
96948506 1420You cannot call C<input_record_separator()> on a handle, only as a
008f9687 1421static method. See L<IO::Handle|IO::Handle>.
96948506 1422
008f9687 1423See also L<perlport/"Newlines">. Also see L</$.>.
9bf22702 1424
b0c22438 1425Mnemonic: / delimits line boundaries when quoting poetry.
5c055ba3 1426
96948506 1427=item IO::Handle->output_record_separator( EXPR )
84902520 1428
b0c22438 1429=item $OUTPUT_RECORD_SEPARATOR
84902520 1430
b0c22438 1431=item $ORS
84902520 1432
b0c22438 1433=item $\
1434X<$\> X<$ORS> X<$OUTPUT_RECORD_SEPARATOR>
84902520 1435
241a59d9
FC
1436The output record separator for the print operator. If defined, this
1437value is printed after the last of print's arguments. Default is C<undef>.
84902520 1438
96948506 1439You cannot call C<output_record_separator()> on a handle, only as a
008f9687 1440static method. See L<IO::Handle|IO::Handle>.
96948506 1441
b0c22438 1442Mnemonic: you set C<$\> instead of adding "\n" at the end of the print.
1443Also, it's just like C<$/>, but it's what you get "back" from Perl.
84902520 1444
5b442a2a 1445=item HANDLE->autoflush( EXPR )
1446
1447=item $OUTPUT_AUTOFLUSH
1448
84dabc03 1449=item $|
1450X<$|> X<autoflush> X<flush> X<$OUTPUT_AUTOFLUSH>
84902520 1451
84dabc03 1452If set to nonzero, forces a flush right away and after every write or
241a59d9 1453print on the currently selected output channel. Default is 0
84dabc03 1454(regardless of whether the channel is really buffered by the system or
1455not; C<$|> tells you only whether you've asked Perl explicitly to
241a59d9
FC
1456flush after each write). STDOUT will typically be line buffered if
1457output is to the terminal and block buffered otherwise. Setting this
84dabc03 1458variable is useful primarily when you are outputting to a pipe or
1459socket, such as when you are running a Perl program under B<rsh> and
241a59d9
FC
1460want to see the output as it's happening. This has no effect on input
1461buffering. See L<perlfunc/getc> for that. See L<perlfunc/select> on
1462how to select the output channel. See also L<IO::Handle>.
84dabc03 1463
1464Mnemonic: when you want your pipes to be piping hot.
1465
8561ea1d
FC
1466=item ${^LAST_FH}
1467X<${^LAST_FH}>
1468
1469This read-only variable contains a reference to the last-read filehandle.
1470This is set by C<< <HANDLE> >>, C<readline>, C<tell>, C<eof> and C<seek>.
1471This is the same handle that C<$.> and C<tell> and C<eof> without arguments
1472use. It is also the handle used when Perl appends ", <STDIN> line 1" to
1473an error or warning message.
1474
1475This variable was added in Perl v5.18.0.
1476
84dabc03 1477=back
84902520 1478
b0c22438 1479=head3 Variables related to formats
83ee9e09 1480
b0c22438 1481The special variables for formats are a subset of those for
241a59d9 1482filehandles. See L<perlform> for more information about Perl's
69b55ccc 1483formats.
83ee9e09 1484
b0c22438 1485=over 8
83ee9e09 1486
84dabc03 1487=item $ACCUMULATOR
1488
1489=item $^A
1490X<$^A> X<$ACCUMULATOR>
1491
1492The current value of the C<write()> accumulator for C<format()> lines.
1493A format contains C<formline()> calls that put their result into
241a59d9
FC
1494C<$^A>. After calling its format, C<write()> prints out the contents
1495of C<$^A> and empties. So you never really see the contents of C<$^A>
1496unless you call C<formline()> yourself and then look at it. See
96090e4f 1497L<perlform> and L<perlfunc/"formline PICTURE,LIST">.
84dabc03 1498
96948506 1499=item IO::Handle->format_formfeed(EXPR)
5b442a2a 1500
1501=item $FORMAT_FORMFEED
1502
84dabc03 1503=item $^L
1504X<$^L> X<$FORMAT_FORMFEED>
1505
241a59d9 1506What formats output as a form feed. The default is C<\f>.
84dabc03 1507
96948506 1508You cannot call C<format_formfeed()> on a handle, only as a static
008f9687 1509method. See L<IO::Handle|IO::Handle>.
96948506 1510
b0c22438 1511=item HANDLE->format_page_number(EXPR)
83ee9e09 1512
b0c22438 1513=item $FORMAT_PAGE_NUMBER
83ee9e09 1514
b0c22438 1515=item $%
1516X<$%> X<$FORMAT_PAGE_NUMBER>
83ee9e09 1517
b0c22438 1518The current page number of the currently selected output channel.
83ee9e09 1519
b0c22438 1520Mnemonic: C<%> is page number in B<nroff>.
7619c85e 1521
b0c22438 1522=item HANDLE->format_lines_left(EXPR)
b9ac3b5b 1523
b0c22438 1524=item $FORMAT_LINES_LEFT
66558a10 1525
b0c22438 1526=item $-
1527X<$-> X<$FORMAT_LINES_LEFT>
fb73857a 1528
b0c22438 1529The number of lines left on the page of the currently selected output
1530channel.
fa05a9fd 1531
b0c22438 1532Mnemonic: lines_on_page - lines_printed.
fa05a9fd 1533
96948506 1534=item IO::Handle->format_line_break_characters EXPR
fb73857a 1535
84dabc03 1536=item $FORMAT_LINE_BREAK_CHARACTERS
a0d0e21e 1537
84dabc03 1538=item $:
1539X<$:> X<FORMAT_LINE_BREAK_CHARACTERS>
a0d0e21e 1540
84dabc03 1541The current set of characters after which a string may be broken to
241a59d9 1542fill continuation fields (starting with C<^>) in a format. The default is
84dabc03 1543S<" \n-">, to break on a space, newline, or a hyphen.
a0d0e21e 1544
96948506 1545You cannot call C<format_line_break_characters()> on a handle, only as
008f9687 1546a static method. See L<IO::Handle|IO::Handle>.
96948506 1547
84dabc03 1548Mnemonic: a "colon" in poetry is a part of a line.
1549
1550=item HANDLE->format_lines_per_page(EXPR)
1551
1552=item $FORMAT_LINES_PER_PAGE
1553
1554=item $=
1555X<$=> X<$FORMAT_LINES_PER_PAGE>
1556
1557The current page length (printable lines) of the currently selected
241a59d9 1558output channel. The default is 60.
84dabc03 1559
1560Mnemonic: = has horizontal lines.
7c36658b 1561
b0c22438 1562=item HANDLE->format_top_name(EXPR)
7c36658b 1563
b0c22438 1564=item $FORMAT_TOP_NAME
a05d7ebb 1565
b0c22438 1566=item $^
1567X<$^> X<$FORMAT_TOP_NAME>
fde18df1 1568
b0c22438 1569The name of the current top-of-page format for the currently selected
241a59d9
FC
1570output channel. The default is the name of the filehandle with C<_TOP>
1571appended. For example, the default format top name for the C<STDOUT>
12abbafd 1572filehandle is C<STDOUT_TOP>.
e07ea26a 1573
b0c22438 1574Mnemonic: points to top of page.
e07ea26a 1575
84dabc03 1576=item HANDLE->format_name(EXPR)
16070b82 1577
84dabc03 1578=item $FORMAT_NAME
aa2f2a36 1579
84dabc03 1580=item $~
1581X<$~> X<$FORMAT_NAME>
aa2f2a36 1582
84dabc03 1583The name of the current report format for the currently selected
241a59d9
FC
1584output channel. The default format name is the same as the filehandle
1585name. For example, the default format name for the C<STDOUT>
84dabc03 1586filehandle is just C<STDOUT>.
16070b82 1587
84dabc03 1588Mnemonic: brother to C<$^>.
16070b82 1589
b0c22438 1590=back
a0d0e21e 1591
84dabc03 1592=head2 Error Variables
b0c22438 1593X<error> X<exception>
a0d0e21e 1594
b0c22438 1595The variables C<$@>, C<$!>, C<$^E>, and C<$?> contain information
1596about different types of error conditions that may appear during
241a59d9 1597execution of a Perl program. The variables are shown ordered by
b0c22438 1598the "distance" between the subsystem which reported the error and
241a59d9 1599the Perl process. They correspond to errors detected by the Perl
b0c22438 1600interpreter, C library, operating system, or an external program,
1601respectively.
4438c4b7 1602
b0c22438 1603To illustrate the differences between these variables, consider the
241a59d9 1604following Perl expression, which uses a single-quoted string. After
7fd683ff 1605execution of this statement, perl may have set all four special error
7333b1c4 1606variables:
4438c4b7 1607
9548c15c
FC
1608 eval q{
1609 open my $pipe, "/cdrom/install |" or die $!;
1610 my @res = <$pipe>;
1611 close $pipe or die "bad pipe: $?, $!";
1612 };
a0d0e21e 1613
7333b1c4 1614When perl executes the C<eval()> expression, it translates the
1615C<open()>, C<< <PIPE> >>, and C<close> calls in the C run-time library
241a59d9 1616and thence to the operating system kernel. perl sets C<$!> to
7333b1c4 1617the C library's C<errno> if one of these calls fails.
2a8c8378 1618
84dabc03 1619C<$@> is set if the string to be C<eval>-ed did not compile (this may
1620happen if C<open> or C<close> were imported with bad prototypes), or
241a59d9 1621if Perl code executed during evaluation C<die()>d. In these cases the
0b9346e6 1622value of C<$@> is the compile error, or the argument to C<die> (which
241a59d9 1623will interpolate C<$!> and C<$?>). (See also L<Fatal>, though.)
2a8c8378 1624
84dabc03 1625Under a few operating systems, C<$^E> may contain a more verbose error
241a59d9 1626indicator, such as in this case, "CDROM tray not closed." Systems that
84dabc03 1627do not support extended error messages leave C<$^E> the same as C<$!>.
a0d0e21e 1628
b0c22438 1629Finally, C<$?> may be set to non-0 value if the external program
241a59d9 1630F</cdrom/install> fails. The upper eight bits reflect specific error
84dabc03 1631conditions encountered by the program (the program's C<exit()> value).
1632The lower eight bits reflect mode of failure, like signal death and
241a59d9 1633core dump information. See L<wait(2)> for details. In contrast to
84dabc03 1634C<$!> and C<$^E>, which are set only if error condition is detected,
1635the variable C<$?> is set on each C<wait> or pipe C<close>,
241a59d9 1636overwriting the old value. This is more like C<$@>, which on every
84dabc03 1637C<eval()> is always set on failure and cleared on success.
a0d0e21e 1638
b0c22438 1639For more details, see the individual descriptions at C<$@>, C<$!>,
1640C<$^E>, and C<$?>.
38e4f4ae 1641
0b9346e6 1642=over 8
1643
b0c22438 1644=item ${^CHILD_ERROR_NATIVE}
1645X<$^CHILD_ERROR_NATIVE>
a0d0e21e 1646
b0c22438 1647The native status returned by the last pipe close, backtick (C<``>)
1648command, successful call to C<wait()> or C<waitpid()>, or from the
241a59d9 1649C<system()> operator. On POSIX-like systems this value can be decoded
b0c22438 1650with the WIFEXITED, WEXITSTATUS, WIFSIGNALED, WTERMSIG, WIFSTOPPED,
1651WSTOPSIG and WIFCONTINUED functions provided by the L<POSIX> module.
a0d0e21e 1652
b0c22438 1653Under VMS this reflects the actual VMS exit status; i.e. it is the
1654same as C<$?> when the pragma C<use vmsish 'status'> is in effect.
a0d0e21e 1655
60cf4914 1656This variable was added in Perl v5.10.0.
a0d0e21e 1657
5b442a2a 1658=item $EXTENDED_OS_ERROR
1659
84dabc03 1660=item $^E
1661X<$^E> X<$EXTENDED_OS_ERROR>
1662
241a59d9 1663Error information specific to the current operating system. At the
84dabc03 1664moment, this differs from C<$!> under only VMS, OS/2, and Win32 (and
241a59d9 1665for MacPerl). On all other platforms, C<$^E> is always just the same
84dabc03 1666as C<$!>.
1667
1668Under VMS, C<$^E> provides the VMS status value from the last system
241a59d9
FC
1669error. This is more specific information about the last system error
1670than that provided by C<$!>. This is particularly important when C<$!>
84dabc03 1671is set to B<EVMSERR>.
1672
1673Under OS/2, C<$^E> is set to the error code of the last call to OS/2
1674API either via CRT, or directly from perl.
1675
1676Under Win32, C<$^E> always returns the last error information reported
1677by the Win32 call C<GetLastError()> which describes the last error
241a59d9
FC
1678from within the Win32 API. Most Win32-specific code will report errors
1679via C<$^E>. ANSI C and Unix-like calls set C<errno> and so most
84dabc03 1680portable Perl code will report errors via C<$!>.
1681
1682Caveats mentioned in the description of C<$!> generally apply to
1683C<$^E>, also.
1684
1685This variable was added in Perl 5.003.
1686
1687Mnemonic: Extra error explanation.
0b9346e6 1688
84dabc03 1689=item $EXCEPTIONS_BEING_CAUGHT
1690
1691=item $^S
1692X<$^S> X<$EXCEPTIONS_BEING_CAUGHT>
1693
1694Current state of the interpreter.
1695
ca1b95ae 1696 $^S State
aa959a20
FC
1697 --------- -------------------------------------
1698 undef Parsing module, eval, or main program
ca1b95ae 1699 true (1) Executing an eval
1700 false (0) Otherwise
84dabc03 1701
1702The first state may happen in C<$SIG{__DIE__}> and C<$SIG{__WARN__}>
1703handlers.
1704
aa959a20
FC
1705The English name $EXCEPTIONS_BEING_CAUGHT is slightly misleading, because
1706the C<undef> value does not indicate whether exceptions are being caught,
1707since compilation of the main program does not catch exceptions.
1708
84dabc03 1709This variable was added in Perl 5.004.
1710
1711=item $WARNING
1712
1713=item $^W
1714X<$^W> X<$WARNING>
1715
1716The current value of the warning switch, initially true if B<-w> was
1717used, false otherwise, but directly modifiable.
1718
1719See also L<warnings>.
1720
0b9346e6 1721Mnemonic: related to the B<-w> switch.
84dabc03 1722
1723=item ${^WARNING_BITS}
ca1b95ae 1724X<${^WARNING_BITS}>
84dabc03 1725
1726The current set of warning checks enabled by the C<use warnings> pragma.
44567c86
FC
1727It has the same scoping as the C<$^H> and C<%^H> variables. The exact
1728values are considered internal to the L<warnings> pragma and may change
1729between versions of Perl.
84dabc03 1730
60cf4914 1731This variable was added in Perl v5.6.0.
84dabc03 1732
b0c22438 1733=item $OS_ERROR
5ccee41e 1734
b0c22438 1735=item $ERRNO
5ccee41e 1736
b0c22438 1737=item $!
1738X<$!> X<$ERRNO> X<$OS_ERROR>
9b0e6e7a 1739
a73bef78
JL
1740When referenced, C<$!> retrieves the current value
1741of the C C<errno> integer variable.
1742If C<$!> is assigned a numerical value, that value is stored in C<errno>.
1743When referenced as a string, C<$!> yields the system error string
1744corresponding to C<errno>.
1745
1746Many system or library calls set C<errno> if they fail,
1747to indicate the cause of failure. They usually do B<not>
1748set C<errno> to zero if they succeed. This means C<errno>,
1749hence C<$!>, is meaningful only I<immediately> after a B<failure>:
1750
1751 if (open my $fh, "<", $filename) {
ca1b95ae 1752 # Here $! is meaningless.
1753 ...
7fd683ff 1754 }
ca1b95ae 1755 else {
1756 # ONLY here is $! meaningful.
1757 ...
1758 # Already here $! might be meaningless.
b0c22438 1759 }
1760 # Since here we might have either success or failure,
a73bef78 1761 # $! is meaningless.
a0d0e21e 1762
a73bef78
JL
1763Here, I<meaningless> means that C<$!> may be unrelated to the outcome
1764of the C<open()> operator. Assignment to C<$!> is similarly ephemeral.
1765It can be used immediately before invoking the C<die()> operator,
1766to set the exit value, or to inspect the system error string
1767corresponding to error I<n>, or to restore C<$!> to a meaningful state.
d54b56d5 1768
b0c22438 1769Mnemonic: What just went bang?
314d39ce 1770
b0c22438 1771=item %OS_ERROR
fb73857a 1772
b0c22438 1773=item %ERRNO
fb73857a 1774
b0c22438 1775=item %!
5b442a2a 1776X<%!> X<%OS_ERROR> X<%ERRNO>
a0d0e21e 1777
b0c22438 1778Each element of C<%!> has a true value only if C<$!> is set to that
241a59d9 1779value. For example, C<$!{ENOENT}> is true if and only if the current
84dabc03 1780value of C<$!> is C<ENOENT>; that is, if the most recent error was "No
1781such file or directory" (or its moral equivalent: not all operating
241a59d9 1782systems give that exact error, and certainly not all languages). To
84dabc03 1783check if a particular key is meaningful on your system, use C<exists
241a59d9 1784$!{the_key}>; for a list of legal keys, use C<keys %!>. See L<Errno>
7333b1c4 1785for more information, and also see L</$!>.
a0d0e21e 1786
b0c22438 1787This variable was added in Perl 5.005.
44f0be63 1788
84dabc03 1789=item $CHILD_ERROR
b687b08b 1790
84dabc03 1791=item $?
1792X<$?> X<$CHILD_ERROR>
a0d0e21e 1793
84dabc03 1794The status returned by the last pipe close, backtick (C<``>) command,
1795successful call to C<wait()> or C<waitpid()>, or from the C<system()>
241a59d9 1796operator. This is just the 16-bit status word returned by the
84dabc03 1797traditional Unix C<wait()> system call (or else is made up to look
241a59d9 1798like it). Thus, the exit value of the subprocess is really (C<<< $? >>
84dabc03 17998 >>>), and C<$? & 127> gives which signal, if any, the process died
1800from, and C<$? & 128> reports whether there was a core dump.
a0d0e21e 1801
84dabc03 1802Additionally, if the C<h_errno> variable is supported in C, its value
1803is returned via C<$?> if any C<gethost*()> function fails.
b687b08b 1804
84dabc03 1805If you have installed a signal handler for C<SIGCHLD>, the
1806value of C<$?> will usually be wrong outside that handler.
a0d0e21e 1807
84dabc03 1808Inside an C<END> subroutine C<$?> contains the value that is going to be
241a59d9
FC
1809given to C<exit()>. You can modify C<$?> in an C<END> subroutine to
1810change the exit status of your program. For example:
a0d0e21e 1811
84dabc03 1812 END {
1813 $? = 1 if $? == 255; # die would make it 255
1814 }
a0d0e21e 1815
84dabc03 1816Under VMS, the pragma C<use vmsish 'status'> makes C<$?> reflect the
1817actual VMS exit status, instead of the default emulation of POSIX
1818status; see L<perlvms/$?> for details.
1819
1820Mnemonic: similar to B<sh> and B<ksh>.
a0d0e21e 1821
b0c22438 1822=item $EVAL_ERROR
f648820c 1823
b0c22438 1824=item $@
1825X<$@> X<$EVAL_ERROR>
a0d0e21e 1826
241a59d9
FC
1827The Perl syntax error message from the
1828last C<eval()> operator. If C<$@> is
0b9346e6 1829the null string, the last C<eval()> parsed and executed correctly
b0c22438 1830(although the operations you invoked may have failed in the normal
1831fashion).
a0d0e21e 1832
241a59d9 1833Warning messages are not collected in this variable. You can, however,
b0c22438 1834set up a routine to process warnings by setting C<$SIG{__WARN__}> as
7333b1c4 1835described in L</%SIG>.
748a9306 1836
b0c22438 1837Mnemonic: Where was the syntax error "at"?
7f315d2e 1838
b0c22438 1839=back
7f315d2e 1840
1fa81471
DR
1841=head2 Variables related to the interpreter state
1842
1843These variables provide information about the current interpreter state.
1844
1845=over 8
1846
1847=item $COMPILING
1848
1849=item $^C
1850X<$^C> X<$COMPILING>
1851
1852The current value of the flag associated with the B<-c> switch.
1853Mainly of use with B<-MO=...> to allow code to alter its behavior
1854when being compiled, such as for example to C<AUTOLOAD> at compile
241a59d9 1855time rather than normal, deferred loading. Setting
1fa81471
DR
1856C<$^C = 1> is similar to calling C<B::minus_c>.
1857
60cf4914 1858This variable was added in Perl v5.6.0.
1fa81471
DR
1859
1860=item $DEBUGGING
1861
1862=item $^D
1863X<$^D> X<$DEBUGGING>
1864
241a59d9 1865The current value of the debugging flags. May be read or set. Like its
1fa81471
DR
1866command-line equivalent, you can use numeric or symbolic values, eg
1867C<$^D = 10> or C<$^D = "st">.
1868
1869Mnemonic: value of B<-D> switch.
1870
1871=item ${^ENCODING}
1872X<${^ENCODING}>
1873
1874The I<object reference> to the C<Encode> object that is used to convert
241a59d9
FC
1875the source code to Unicode. Thanks to this variable your Perl script
1876does not have to be written in UTF-8. Default is I<undef>. The direct
1fa81471
DR
1877manipulation of this variable is highly discouraged.
1878
1879This variable was added in Perl 5.8.2.
1880
1881=item ${^GLOBAL_PHASE}
1882X<${^GLOBAL_PHASE}>
1883
1884The current phase of the perl interpreter.
1885
1886Possible values are:
1887
1888=over 8
1889
1890=item CONSTRUCT
1891
241a59d9 1892The C<PerlInterpreter*> is being constructed via C<perl_construct>. This
1fa81471 1893value is mostly there for completeness and for use via the
241a59d9 1894underlying C variable C<PL_phase>. It's not really possible for Perl
1fa81471
DR
1895code to be executed unless construction of the interpreter is
1896finished.
1897
1898=item START
1899
241a59d9 1900This is the global compile-time. That includes, basically, every
1fa81471
DR
1901C<BEGIN> block executed directly or indirectly from during the
1902compile-time of the top-level program.
1903
1904This phase is not called "BEGIN" to avoid confusion with
1905C<BEGIN>-blocks, as those are executed during compile-time of any
241a59d9 1906compilation unit, not just the top-level program. A new, localised
1fa81471
DR
1907compile-time entered at run-time, for example by constructs as
1908C<eval "use SomeModule"> are not global interpreter phases, and
1909therefore aren't reflected by C<${^GLOBAL_PHASE}>.
1910
1911=item CHECK
1912
1913Execution of any C<CHECK> blocks.
1914
1915=item INIT
1916
1917Similar to "CHECK", but for C<INIT>-blocks, not C<CHECK> blocks.
1918
1919=item RUN
1920
1921The main run-time, i.e. the execution of C<PL_main_root>.
1922
1923=item END
1924
1925Execution of any C<END> blocks.
1926
1927=item DESTRUCT
1928
1929Global destruction.
1930
1931=back
1932
241a59d9 1933Also note that there's no value for UNITCHECK-blocks. That's because
1fa81471
DR
1934those are run for each compilation unit individually, and therefore is
1935not a global interpreter phase.
1936
1937Not every program has to go through each of the possible phases, but
1938transition from one phase to another can only happen in the order
1939described in the above list.
1940
1941An example of all of the phases Perl code can see:
1942
1943 BEGIN { print "compile-time: ${^GLOBAL_PHASE}\n" }
1944
1945 INIT { print "init-time: ${^GLOBAL_PHASE}\n" }
1946
1947 CHECK { print "check-time: ${^GLOBAL_PHASE}\n" }
1948
1949 {
1950 package Print::Phase;
1951
1952 sub new {
1953 my ($class, $time) = @_;
1954 return bless \$time, $class;
1955 }
1956
1957 sub DESTROY {
1958 my $self = shift;
1959 print "$$self: ${^GLOBAL_PHASE}\n";
1960 }
1961 }
1962
1963 print "run-time: ${^GLOBAL_PHASE}\n";
1964
1965 my $runtime = Print::Phase->new(
1966 "lexical variables are garbage collected before END"
1967 );
1968
1969 END { print "end-time: ${^GLOBAL_PHASE}\n" }
1970
1971 our $destruct = Print::Phase->new(
1972 "package variables are garbage collected after END"
1973 );
1974
1975This will print out
1976
1977 compile-time: START
1978 check-time: CHECK
1979 init-time: INIT
1980 run-time: RUN
1981 lexical variables are garbage collected before END: RUN
1982 end-time: END
1983 package variables are garbage collected after END: DESTRUCT
1984
1985This variable was added in Perl 5.14.0.
1986
1987=item $^H
1988X<$^H>
1989
241a59d9
FC
1990WARNING: This variable is strictly for
1991internal use only. Its availability,
1fa81471
DR
1992behavior, and contents are subject to change without notice.
1993
241a59d9 1994This variable contains compile-time hints for the Perl interpreter. At the
1fa81471
DR
1995end of compilation of a BLOCK the value of this variable is restored to the
1996value when the interpreter started to compile the BLOCK.
1997
1998When perl begins to parse any block construct that provides a lexical scope
1999(e.g., eval body, required file, subroutine body, loop body, or conditional
2000block), the existing value of C<$^H> is saved, but its value is left unchanged.
2001When the compilation of the block is completed, it regains the saved value.
2002Between the points where its value is saved and restored, code that
2003executes within BEGIN blocks is free to change the value of C<$^H>.
2004
2005This behavior provides the semantic of lexical scoping, and is used in,
2006for instance, the C<use strict> pragma.
2007
2008The contents should be an integer; different bits of it are used for
241a59d9 2009different pragmatic flags. Here's an example:
1fa81471 2010
9548c15c 2011 sub add_100 { $^H |= 0x100 }
1fa81471 2012
9548c15c
FC
2013 sub foo {
2014 BEGIN { add_100() }
2015 bar->baz($boon);
2016 }
1fa81471 2017
241a59d9 2018Consider what happens during execution of the BEGIN block. At this point
1fa81471 2019the BEGIN block has already been compiled, but the body of C<foo()> is still
241a59d9
FC
2020being compiled. The new value of C<$^H>
2021will therefore be visible only while
1fa81471
DR
2022the body of C<foo()> is being compiled.
2023
2024Substitution of C<BEGIN { add_100() }> block with:
2025
9548c15c 2026 BEGIN { require strict; strict->import('vars') }
1fa81471 2027
241a59d9 2028demonstrates how C<use strict 'vars'> is implemented. Here's a conditional
1fa81471
DR
2029version of the same lexical pragma:
2030
9548c15c
FC
2031 BEGIN {
2032 require strict; strict->import('vars') if $condition
2033 }
1fa81471
DR
2034
2035This variable was added in Perl 5.003.
2036
2037=item %^H
2038X<%^H>
2039
241a59d9
FC
2040The C<%^H> hash provides the same scoping semantic as C<$^H>. This makes
2041it useful for implementation of lexically scoped pragmas. See
2042L<perlpragma>.
1fa81471
DR
2043
2044When putting items into C<%^H>, in order to avoid conflicting with other
2045users of the hash there is a convention regarding which keys to use.
2046A module should use only keys that begin with the module's name (the
2047name of its main package) and a "/" character. For example, a module
2048C<Foo::Bar> should use keys such as C<Foo::Bar/baz>.
2049
60cf4914 2050This variable was added in Perl v5.6.0.
1fa81471
DR
2051
2052=item ${^OPEN}
2053X<${^OPEN}>
2054
241a59d9 2055An internal variable used by PerlIO. A string in two parts, separated
1fa81471
DR
2056by a C<\0> byte, the first part describes the input layers, the second
2057part describes the output layers.
2058
60cf4914 2059This variable was added in Perl v5.8.0.
1fa81471
DR
2060
2061=item $PERLDB
2062
2063=item $^P
2064X<$^P> X<$PERLDB>
2065
241a59d9 2066The internal variable for debugging support. The meanings of the
1fa81471
DR
2067various bits are subject to change, but currently indicate:
2068
2069=over 6
2070
2071=item 0x01
2072
2073Debug subroutine enter/exit.
2074
2075=item 0x02
2076
241a59d9
FC
2077Line-by-line debugging. Causes C<DB::DB()> subroutine to be called for
2078each statement executed. Also causes saving source code lines (like
20790x400).
1fa81471
DR
2080
2081=item 0x04
2082
2083Switch off optimizations.
2084
2085=item 0x08
2086
2087Preserve more data for future interactive inspections.
2088
2089=item 0x10
2090
2091Keep info about source lines on which a subroutine is defined.
2092
2093=item 0x20
2094
2095Start with single-step on.
2096
2097=item 0x40
2098
2099Use subroutine address instead of name when reporting.
2100
2101=item 0x80
2102
2103Report C<goto &subroutine> as well.
2104
2105=item 0x100
2106
2107Provide informative "file" names for evals based on the place they were compiled.
2108
2109=item 0x200
2110
2111Provide informative names to anonymous subroutines based on the place they
2112were compiled.
2113
2114=item 0x400
2115
2116Save source code lines into C<@{"_<$filename"}>.
2117
aab47982
RS
2118=item 0x800
2119
2120When saving source, include evals that generate no subroutines.
2121
2122=item 0x1000
2123
2124When saving source, include source that did not compile.
2125
1fa81471
DR
2126=back
2127
2128Some bits may be relevant at compile-time only, some at
241a59d9 2129run-time only. This is a new mechanism and the details may change.
1fa81471
DR
2130See also L<perldebguts>.
2131
2132=item ${^TAINT}
2133X<${^TAINT}>
2134
241a59d9 2135Reflects if taint mode is on or off. 1 for on (the program was run with
1fa81471
DR
2136B<-T>), 0 for off, -1 when only taint warnings are enabled (i.e. with
2137B<-t> or B<-TU>).
2138
2139This variable is read-only.
2140
60cf4914 2141This variable was added in Perl v5.8.0.
1fa81471
DR
2142
2143=item ${^UNICODE}
2144X<${^UNICODE}>
2145
241a59d9 2146Reflects certain Unicode settings of Perl. See L<perlrun>
1fa81471
DR
2147documentation for the C<-C> switch for more information about
2148the possible values.
2149
2150This variable is set during Perl startup and is thereafter read-only.
2151
60cf4914 2152This variable was added in Perl v5.8.2.
1fa81471
DR
2153
2154=item ${^UTF8CACHE}
2155X<${^UTF8CACHE}>
2156
2157This variable controls the state of the internal UTF-8 offset caching code.
21581 for on (the default), 0 for off, -1 to debug the caching code by checking
2159all its results against linear scans, and panicking on any discrepancy.
2160
94df5432
KW
2161This variable was added in Perl v5.8.9. It is subject to change or
2162removal without notice, but is currently used to avoid recalculating the
2163boundaries of multi-byte UTF-8-encoded characters.
1fa81471
DR
2164
2165=item ${^UTF8LOCALE}
2166X<${^UTF8LOCALE}>
2167
2168This variable indicates whether a UTF-8 locale was detected by perl at
241a59d9 2169startup. This information is used by perl when it's in
1fa81471
DR
2170adjust-utf8ness-to-locale mode (as when run with the C<-CL> command-line
2171switch); see L<perlrun> for more info on this.
2172
60cf4914 2173This variable was added in Perl v5.8.8.
1fa81471
DR
2174
2175=back
2176
b0c22438 2177=head2 Deprecated and removed variables
7f315d2e 2178
0b9346e6 2179Deprecating a variable announces the intent of the perl maintainers to
241a59d9
FC
2180eventually remove the variable from the language. It may still be
2181available despite its status. Using a deprecated variable triggers
b0c22438 2182a warning.
7f315d2e 2183
84dabc03 2184Once a variable is removed, its use triggers an error telling you
b0c22438 2185the variable is unsupported.
7f315d2e 2186
84dabc03 2187See L<perldiag> for details about error messages.
7f315d2e 2188
b0c22438 2189=over 8
7f315d2e 2190
84dabc03 2191=item $#
b7a15f05 2192X<$#>
84dabc03 2193
38e5787b 2194C<$#> was a variable that could be used to format printed numbers.
60cf4914 2195After a deprecation cycle, its magic was removed in Perl v5.10.0 and
84dabc03 2196using it now triggers a warning: C<$# is no longer supported>.
2197
2198This is not the sigil you use in front of an array name to get the
241a59d9
FC
2199last index, like C<$#array>. That's still how you get the last index
2200of an array in Perl. The two have nothing to do with each other.
84dabc03 2201
2202Deprecated in Perl 5.
2203
60cf4914 2204Removed in Perl v5.10.0.
84dabc03 2205
7f315d2e
CO
2206=item $*
2207X<$*>
2208
84dabc03 2209C<$*> was a variable that you could use to enable multiline matching.
60cf4914 2210After a deprecation cycle, its magic was removed in Perl v5.10.0.
7f315d2e 2211Using it now triggers a warning: C<$* is no longer supported>.
84dabc03 2212You should use the C</s> and C</m> regexp modifiers instead.
7f315d2e 2213
b0c22438 2214Deprecated in Perl 5.
7f315d2e 2215
60cf4914 2216Removed in Perl v5.10.0.
7f315d2e 2217
84dabc03 2218=item $[
b7a15f05 2219X<$[>
84dabc03 2220
b82b06b8
FC
2221This variable stores the index of the first element in an array, and
2222of the first character in a substring. The default is 0, but you could
2223theoretically set it to 1 to make Perl behave more like B<awk> (or Fortran)
2224when subscripting and when evaluating the index() and substr() functions.
84dabc03 2225
b82b06b8
FC
2226As of release 5 of Perl, assignment to C<$[> is treated as a compiler
2227directive, and cannot influence the behavior of any other file.
2228(That's why you can only assign compile-time constants to it.)
2229Its use is highly discouraged.
2230
60cf4914 2231Prior to Perl v5.10.0, assignment to C<$[> could be seen from outer lexical
b82b06b8
FC
2232scopes in the same file, unlike other compile-time directives (such as
2233L<strict>). Using local() on it would bind its value strictly to a lexical
2234block. Now it is always lexically scoped.
2235
60cf4914 2236As of Perl v5.16.0, it is implemented by the L<arybase> module. See
b82b06b8 2237L<arybase> for more details on its behaviour.
84dabc03 2238
6b54f8ab
FC
2239Under C<use v5.16>, or C<no feature "array_base">, C<$[> no longer has any
2240effect, and always contains 0. Assigning 0 to it is permitted, but any
2241other value will produce an error.
2242
b82b06b8
FC
2243Mnemonic: [ begins subscripts.
2244
60cf4914 2245Deprecated in Perl v5.12.0.
e1dccc0d 2246
b0c22438 2247=item $]
b7a15f05 2248X<$]>
55602bd2 2249
57f6eff5 2250See L</$^V> for a more modern representation of the Perl version that allows
d4ba9bf2 2251accurate string comparisons.
2252
241a59d9 2253The version + patchlevel / 1000 of the Perl interpreter. This variable
b0c22438 2254can be used to determine whether the Perl interpreter executing a
2255script is in the right range of versions:
55602bd2 2256
9016991b 2257 warn "No PerlIO!\n" if $] lt '5.008';
55602bd2 2258
d4ba9bf2 2259The floating point representation can sometimes lead to inaccurate
9016991b 2260numeric comparisons, so string comparisons are recommended.
d4ba9bf2 2261
b0c22438 2262See also the documentation of C<use VERSION> and C<require VERSION>
2263for a convenient way to fail if the running Perl interpreter is too old.
55602bd2 2264
b0c22438 2265Mnemonic: Is this version of perl in the right bracket?
19799a22 2266
b0c22438 2267=back
2b92dfce 2268
0b9346e6 2269=cut