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