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