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