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