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