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