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