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