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