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