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