This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Add Porting/apply to MANIFEST.
[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
16at the top of your program. This will alias all the short names to the
5a964f20 17long names in the current package. Some even have medium names,
a0d0e21e
LW
18generally borrowed from B<awk>.
19
19799a22
GS
20If you don't mind the performance hit, variables that depend on the
21currently selected filehandle may instead be set by calling an
22appropriate object method on the IO::Handle object. (Summary lines
23below for this contain the word HANDLE.) First you must say
a0d0e21e 24
19799a22 25 use IO::Handle;
a0d0e21e
LW
26
27after which you may use either
28
29 method HANDLE EXPR
30
5a964f20 31or more safely,
a0d0e21e
LW
32
33 HANDLE->method(EXPR)
34
14218588 35Each method returns the old value of the IO::Handle attribute.
a0d0e21e 36The methods each take an optional EXPR, which if supplied specifies the
19799a22 37new value for the IO::Handle attribute in question. If not supplied,
14218588 38most methods do nothing to the current value--except for
a0d0e21e 39autoflush(), which will assume a 1 for you, just to be different.
14218588 40Because loading in the IO::Handle class is an expensive operation, you should
19799a22 41learn how to use the regular built-in variables.
a0d0e21e 42
748a9306
LW
43A few of these variables are considered "read-only". This means that if
44you try to assign to this variable, either directly or indirectly through
45a reference, you'll raise a run-time exception.
a0d0e21e 46
fb73857a 47The following list is ordered by scalar variables first, then the
87275199 48arrays, then the hashes.
fb73857a 49
a0d0e21e
LW
50=over 8
51
52=item $ARG
53
54=item $_
55
56The default input and pattern-searching space. The following pairs are
57equivalent:
58
19799a22 59 while (<>) {...} # equivalent only in while!
54310121 60 while (defined($_ = <>)) {...}
a0d0e21e
LW
61
62 /^Subject:/
63 $_ =~ /^Subject:/
64
65 tr/a-z/A-Z/
66 $_ =~ tr/a-z/A-Z/
67
19799a22
GS
68 chomp
69 chomp($_)
a0d0e21e 70
54310121 71Here are the places where Perl will assume $_ even if you
cb1a09d0
AD
72don't use it:
73
74=over 3
75
76=item *
77
78Various unary functions, including functions like ord() and int(), as well
79as the all file tests (C<-f>, C<-d>) except for C<-t>, which defaults to
80STDIN.
81
82=item *
83
84Various list functions like print() and unlink().
85
86=item *
87
88The pattern matching operations C<m//>, C<s///>, and C<tr///> when used
89without an C<=~> operator.
90
54310121 91=item *
cb1a09d0
AD
92
93The default iterator variable in a C<foreach> loop if no other
94variable is supplied.
95
54310121 96=item *
cb1a09d0
AD
97
98The implicit iterator variable in the grep() and map() functions.
99
54310121 100=item *
cb1a09d0 101
c47ff5f1 102The default place to put an input record when a C<< <FH> >>
cb1a09d0 103operation's result is tested by itself as the sole criterion of a C<while>
14218588 104test. Outside a C<while> test, this will not happen.
cb1a09d0
AD
105
106=back
107
a0d0e21e
LW
108(Mnemonic: underline is understood in certain operations.)
109
6e2995f4
PP
110=back
111
112=over 8
113
a1db74c9
JH
114=item $a
115
116=item $b
117
118Special package variables when using sort(), see L<perlfunc/sort>.
119Because of this specialness $a and $b don't need to be declared
120(using local(), use vars, or our()) even when using the strict
53e56e0a
JH
121vars pragma. Don't lexicalize them with C<my $a> or C<my $b>
122if you want to be able to use them in the sort() comparison block
123or function.
a1db74c9
JH
124
125=back
126
127=over 8
128
c47ff5f1 129=item $<I<digits>>
a0d0e21e 130
19799a22
GS
131Contains the subpattern from the corresponding set of capturing
132parentheses from the last pattern match, not counting patterns
133matched in nested blocks that have been exited already. (Mnemonic:
134like \digits.) These variables are all read-only and dynamically
135scoped to the current BLOCK.
a0d0e21e
LW
136
137=item $MATCH
138
139=item $&
140
141The string matched by the last successful pattern match (not counting
142any matches hidden within a BLOCK or eval() enclosed by the current
19799a22
GS
143BLOCK). (Mnemonic: like & in some editors.) This variable is read-only
144and dynamically scoped to the current BLOCK.
a0d0e21e 145
19ddd453 146The use of this variable anywhere in a program imposes a considerable
19799a22 147performance penalty on all regular expression matches. See L<BUGS>.
19ddd453 148
a0d0e21e
LW
149=item $PREMATCH
150
151=item $`
152
153The string preceding whatever was matched by the last successful
154pattern match (not counting any matches hidden within a BLOCK or eval
a8f8344d 155enclosed by the current BLOCK). (Mnemonic: C<`> often precedes a quoted
a0d0e21e
LW
156string.) This variable is read-only.
157
19ddd453 158The use of this variable anywhere in a program imposes a considerable
19799a22 159performance penalty on all regular expression matches. See L<BUGS>.
19ddd453 160
a0d0e21e
LW
161=item $POSTMATCH
162
163=item $'
164
165The string following whatever was matched by the last successful
166pattern match (not counting any matches hidden within a BLOCK or eval()
a8f8344d 167enclosed by the current BLOCK). (Mnemonic: C<'> often follows a quoted
a0d0e21e
LW
168string.) Example:
169
170 $_ = 'abcdefghi';
171 /def/;
172 print "$`:$&:$'\n"; # prints abc:def:ghi
173
19799a22 174This variable is read-only and dynamically scoped to the current BLOCK.
a0d0e21e 175
19ddd453 176The use of this variable anywhere in a program imposes a considerable
19799a22 177performance penalty on all regular expression matches. See L<BUGS>.
19ddd453 178
a0d0e21e
LW
179=item $LAST_PAREN_MATCH
180
181=item $+
182
a01268b5
JH
183The text matched by the last bracket of the last successful search pattern.
184This is useful if you don't know which one of a set of alternative patterns
185matched. For example:
a0d0e21e
LW
186
187 /Version: (.*)|Revision: (.*)/ && ($rev = $+);
188
189(Mnemonic: be positive and forward looking.)
19799a22 190This variable is read-only and dynamically scoped to the current BLOCK.
a0d0e21e 191
a01268b5
JH
192=item $^N
193
194The text matched by the used group most-recently closed (i.e. the group
195with the rightmost closing parenthesis) of the last successful search
ad83b128
PN
196pattern. (Mnemonic: the (possibly) Nested parenthesis that most
197recently closed.)
198
199This is primarly used inside C<(?{...})> blocks for examining text
a01268b5
JH
200recently matched. For example, to effectively capture text to a variable
201(in addition to C<$1>, C<$2>, etc.), replace C<(...)> with
202
203 (?:(...)(?{ $var = $^N }))
204
205By setting and then using C<$var> in this way relieves you from having to
206worry about exactly which numbered set of parentheses they are.
207
208This variable is dynamically scoped to the current BLOCK.
209
fe307981
GS
210=item @LAST_MATCH_END
211
6cef1e77
IZ
212=item @+
213
4ba05bdc
GS
214This array holds the offsets of the ends of the last successful
215submatches in the currently active dynamic scope. C<$+[0]> is
216the offset into the string of the end of the entire match. This
217is the same value as what the C<pos> function returns when called
218on the variable that was matched against. The I<n>th element
219of this array holds the offset of the I<n>th submatch, so
220C<$+[1]> is the offset past where $1 ends, C<$+[2]> the offset
221past where $2 ends, and so on. You can use C<$#+> to determine
222how many subgroups were in the last successful match. See the
223examples given for the C<@-> variable.
6cef1e77 224
a0d0e21e
LW
225=item $MULTILINE_MATCHING
226
227=item $*
228
1555b0cb
A
229Set to a non-zero integer value to do multi-line matching within a
230string, 0 (or undefined) to tell Perl that it can assume that strings
231contain a single line, for the purpose of optimizing pattern matches.
232Pattern matches on strings containing multiple newlines can produce
233confusing results when C<$*> is 0 or undefined. Default is undefined.
234(Mnemonic: * matches multiple things.) This variable influences the
235interpretation of only C<^> and C<$>. A literal newline can be searched
236for even when C<$* == 0>.
a0d0e21e 237
19799a22 238Use of C<$*> is deprecated in modern Perl, supplanted by
5a964f20 239the C</s> and C</m> modifiers on pattern matching.
a0d0e21e 240
1555b0cb
A
241Assigning a non-numerical value to C<$*> triggers a warning (and makes
242C<$*> act if C<$* == 0>), while assigning a numerical value to C<$*>
243makes that an implicit C<int> is applied on the value.
244
a0d0e21e
LW
245=item input_line_number HANDLE EXPR
246
247=item $INPUT_LINE_NUMBER
248
249=item $NR
250
251=item $.
252
19799a22 253The current input record number for the last file handle from which
14218588 254you just read() (or called a C<seek> or C<tell> on). The value
883faa13 255may be different from the actual physical line number in the file,
19799a22
GS
256depending on what notion of "line" is in effect--see C<$/> on how
257to change that. An explicit close on a filehandle resets the line
c47ff5f1 258number. Because C<< <> >> never does an explicit close, line
19799a22
GS
259numbers increase across ARGV files (but see examples in L<perlfunc/eof>).
260Consider this variable read-only: setting it does not reposition
1e374101
PJ
261the seek pointer; you'll have to do that on your own. Localizing C<$.>
262has the effect of also localizing Perl's notion of "the last read
263filehandle". (Mnemonic: many programs use "." to mean the current line
264number.)
a0d0e21e 265
46550894 266=item IO::Handle->input_record_separator EXPR
a0d0e21e
LW
267
268=item $INPUT_RECORD_SEPARATOR
269
270=item $RS
271
272=item $/
273
14218588
GS
274The input record separator, newline by default. This
275influences Perl's idea of what a "line" is. Works like B<awk>'s RS
19799a22 276variable, including treating empty lines as a terminator if set to
14218588
GS
277the null string. (An empty line cannot contain any spaces
278or tabs.) You may set it to a multi-character string to match a
19799a22
GS
279multi-character terminator, or to C<undef> to read through the end
280of file. Setting it to C<"\n\n"> means something slightly
281different than setting to C<"">, if the file contains consecutive
282empty lines. Setting to C<""> will treat two or more consecutive
283empty lines as a single empty line. Setting to C<"\n\n"> will
284blindly assume that the next input character belongs to the next
14218588 285paragraph, even if it's a newline. (Mnemonic: / delimits
19799a22 286line boundaries when quoting poetry.)
a0d0e21e 287
fbad3eb5
GS
288 undef $/; # enable "slurp" mode
289 $_ = <FH>; # whole file now here
a0d0e21e
LW
290 s/\n[ \t]+/ /g;
291
19799a22
GS
292Remember: the value of C<$/> is a string, not a regex. B<awk> has to be
293better for something. :-)
68dc0745 294
19799a22
GS
295Setting C<$/> to a reference to an integer, scalar containing an integer, or
296scalar that's convertible to an integer will attempt to read records
5b2b9c68 297instead of lines, with the maximum record size being the referenced
19799a22 298integer. So this:
5b2b9c68
HM
299
300 $/ = \32768; # or \"32768", or \$var_containing_32768
301 open(FILE, $myfile);
302 $_ = <FILE>;
303
19799a22
GS
304will read a record of no more than 32768 bytes from FILE. If you're
305not reading from a record-oriented file (or your OS doesn't have
306record-oriented files), then you'll likely get a full chunk of data
307with every read. If a record is larger than the record size you've
308set, you'll get the record back in pieces.
5b2b9c68 309
19799a22
GS
310On VMS, record reads are done with the equivalent of C<sysread>,
311so it's best not to mix record and non-record reads on the same
312file. (This is unlikely to be a problem, because any file you'd
83763826 313want to read in record mode is probably unusable in line mode.)
14218588 314Non-VMS systems do normal I/O, so it's safe to mix record and
19799a22 315non-record reads of a file.
5b2b9c68 316
14218588 317See also L<perlport/"Newlines">. Also see C<$.>.
883faa13 318
a0d0e21e
LW
319=item autoflush HANDLE EXPR
320
321=item $OUTPUT_AUTOFLUSH
322
323=item $|
324
19799a22
GS
325If set to nonzero, forces a flush right away and after every write
326or print on the currently selected output channel. Default is 0
14218588 327(regardless of whether the channel is really buffered by the
19799a22
GS
328system or not; C<$|> tells you only whether you've asked Perl
329explicitly to flush after each write). STDOUT will
330typically be line buffered if output is to the terminal and block
331buffered otherwise. Setting this variable is useful primarily when
332you are outputting to a pipe or socket, such as when you are running
333a Perl program under B<rsh> and want to see the output as it's
334happening. This has no effect on input buffering. See L<perlfunc/getc>
335for that. (Mnemonic: when you want your pipes to be piping hot.)
a0d0e21e 336
46550894 337=item IO::Handle->output_field_separator EXPR
a0d0e21e
LW
338
339=item $OUTPUT_FIELD_SEPARATOR
340
341=item $OFS
342
343=item $,
344
345The output field separator for the print operator. Ordinarily the
19799a22
GS
346print operator simply prints out its arguments without further
347adornment. To get behavior more like B<awk>, set this variable as
348you would set B<awk>'s OFS variable to specify what is printed
349between fields. (Mnemonic: what is printed when there is a "," in
350your print statement.)
a0d0e21e 351
46550894 352=item IO::Handle->output_record_separator EXPR
a0d0e21e
LW
353
354=item $OUTPUT_RECORD_SEPARATOR
355
356=item $ORS
357
358=item $\
359
360The output record separator for the print operator. Ordinarily the
19799a22
GS
361print operator simply prints out its arguments as is, with no
362trailing newline or other end-of-record string added. To get
363behavior more like B<awk>, set this variable as you would set
364B<awk>'s ORS variable to specify what is printed at the end of the
365print. (Mnemonic: you set C<$\> instead of adding "\n" at the
366end of the print. Also, it's just like C<$/>, but it's what you
367get "back" from Perl.)
a0d0e21e
LW
368
369=item $LIST_SEPARATOR
370
371=item $"
372
19799a22
GS
373This is like C<$,> except that it applies to array and slice values
374interpolated into a double-quoted string (or similar interpreted
375string). Default is a space. (Mnemonic: obvious, I think.)
a0d0e21e
LW
376
377=item $SUBSCRIPT_SEPARATOR
378
379=item $SUBSEP
380
381=item $;
382
54310121 383The subscript separator for multidimensional array emulation. If you
a0d0e21e
LW
384refer to a hash element as
385
386 $foo{$a,$b,$c}
387
388it really means
389
390 $foo{join($;, $a, $b, $c)}
391
392But don't put
393
394 @foo{$a,$b,$c} # a slice--note the @
395
396which means
397
398 ($foo{$a},$foo{$b},$foo{$c})
399
19799a22
GS
400Default is "\034", the same as SUBSEP in B<awk>. If your
401keys contain binary data there might not be any safe value for C<$;>.
a0d0e21e 402(Mnemonic: comma (the syntactic subscript separator) is a
19799a22 403semi-semicolon. Yeah, I know, it's pretty lame, but C<$,> is already
a0d0e21e
LW
404taken for something more important.)
405
19799a22
GS
406Consider using "real" multidimensional arrays as described
407in L<perllol>.
a0d0e21e
LW
408
409=item $OFMT
410
411=item $#
412
413The output format for printed numbers. This variable is a half-hearted
414attempt to emulate B<awk>'s OFMT variable. There are times, however,
14218588 415when B<awk> and Perl have differing notions of what counts as
19799a22 416numeric. The initial value is "%.I<n>g", where I<n> is the value
6e2995f4 417of the macro DBL_DIG from your system's F<float.h>. This is different from
19799a22 418B<awk>'s default OFMT setting of "%.6g", so you need to set C<$#>
6e2995f4 419explicitly to get B<awk>'s value. (Mnemonic: # is the number sign.)
a0d0e21e 420
19799a22 421Use of C<$#> is deprecated.
a0d0e21e
LW
422
423=item format_page_number HANDLE EXPR
424
425=item $FORMAT_PAGE_NUMBER
426
427=item $%
428
429The current page number of the currently selected output channel.
19799a22 430Used with formats.
a0d0e21e
LW
431(Mnemonic: % is page number in B<nroff>.)
432
433=item format_lines_per_page HANDLE EXPR
434
435=item $FORMAT_LINES_PER_PAGE
436
437=item $=
438
439The current page length (printable lines) of the currently selected
19799a22
GS
440output channel. Default is 60.
441Used with formats.
442(Mnemonic: = has horizontal lines.)
a0d0e21e
LW
443
444=item format_lines_left HANDLE EXPR
445
446=item $FORMAT_LINES_LEFT
447
448=item $-
449
450The number of lines left on the page of the currently selected output
19799a22
GS
451channel.
452Used with formats.
453(Mnemonic: lines_on_page - lines_printed.)
a0d0e21e 454
fe307981
GS
455=item @LAST_MATCH_START
456
6cef1e77
IZ
457=item @-
458
19799a22 459$-[0] is the offset of the start of the last successful match.
6cef1e77 460C<$-[>I<n>C<]> is the offset of the start of the substring matched by
8f580fb8 461I<n>-th subpattern, or undef if the subpattern did not match.
6cef1e77
IZ
462
463Thus after a match against $_, $& coincides with C<substr $_, $-[0],
8f580fb8
IZ
464$+[0] - $-[0]>. Similarly, C<$>I<n> coincides with C<substr $_, $-[>I<n>C<],
465$+[>I<n>C<] - $-[>I<n>C<]> if C<$-[>I<n>C<]> is defined, and $+ coincides with
c47ff5f1 466C<substr $_, $-[$#-], $+[$#-]>. One can use C<$#-> to find the last
14218588
GS
467matched subgroup in the last successful match. Contrast with
468C<$#+>, the number of subgroups in the regular expression. Compare
19799a22 469with C<@+>.
6cef1e77 470
4ba05bdc
GS
471This array holds the offsets of the beginnings of the last
472successful submatches in the currently active dynamic scope.
473C<$-[0]> is the offset into the string of the beginning of the
474entire match. The I<n>th element of this array holds the offset
0926d669
JP
475of the I<n>th submatch, so C<$-[1]> is the offset where $1
476begins, C<$-[2]> the offset where $2 begins, and so on.
4ba05bdc
GS
477
478After a match against some variable $var:
479
480=over 5
481
4375e838 482=item C<$`> is the same as C<substr($var, 0, $-[0])>
4ba05bdc 483
4375e838 484=item C<$&> is the same as C<substr($var, $-[0], $+[0] - $-[0])>
4ba05bdc 485
4375e838 486=item C<$'> is the same as C<substr($var, $+[0])>
4ba05bdc
GS
487
488=item C<$1> is the same as C<substr($var, $-[1], $+[1] - $-[1])>
489
490=item C<$2> is the same as C<substr($var, $-[2], $+[2] - $-[2])>
491
4375e838 492=item C<$3> is the same as C<substr $var, $-[3], $+[3] - $-[3])>
4ba05bdc
GS
493
494=back
495
a0d0e21e
LW
496=item format_name HANDLE EXPR
497
498=item $FORMAT_NAME
499
500=item $~
501
502The name of the current report format for the currently selected output
14218588 503channel. Default is the name of the filehandle. (Mnemonic: brother to
19799a22 504C<$^>.)
a0d0e21e
LW
505
506=item format_top_name HANDLE EXPR
507
508=item $FORMAT_TOP_NAME
509
510=item $^
511
512The name of the current top-of-page format for the currently selected
14218588 513output channel. Default is the name of the filehandle with _TOP
a0d0e21e
LW
514appended. (Mnemonic: points to top of page.)
515
46550894 516=item IO::Handle->format_line_break_characters EXPR
a0d0e21e
LW
517
518=item $FORMAT_LINE_BREAK_CHARACTERS
519
520=item $:
521
522The current set of characters after which a string may be broken to
54310121 523fill continuation fields (starting with ^) in a format. Default is
a0d0e21e
LW
524S<" \n-">, to break on whitespace or hyphens. (Mnemonic: a "colon" in
525poetry is a part of a line.)
526
46550894 527=item IO::Handle->format_formfeed EXPR
a0d0e21e
LW
528
529=item $FORMAT_FORMFEED
530
531=item $^L
532
14218588 533What formats output as a form feed. Default is \f.
a0d0e21e
LW
534
535=item $ACCUMULATOR
536
537=item $^A
538
539The current value of the write() accumulator for format() lines. A format
19799a22 540contains formline() calls that put their result into C<$^A>. After
a0d0e21e 541calling its format, write() prints out the contents of C<$^A> and empties.
14218588 542So you never really see the contents of C<$^A> unless you call
a0d0e21e
LW
543formline() yourself and then look at it. See L<perlform> and
544L<perlfunc/formline()>.
545
546=item $CHILD_ERROR
547
548=item $?
549
54310121 550The status returned by the last pipe close, backtick (C<``>) command,
19799a22
GS
551successful call to wait() or waitpid(), or from the system()
552operator. This is just the 16-bit status word returned by the
553wait() system call (or else is made up to look like it). Thus, the
c47ff5f1 554exit value of the subprocess is really (C<<< $? >> 8 >>>), and
19799a22
GS
555C<$? & 127> gives which signal, if any, the process died from, and
556C<$? & 128> reports whether there was a core dump. (Mnemonic:
557similar to B<sh> and B<ksh>.)
a0d0e21e 558
7b8d334a 559Additionally, if the C<h_errno> variable is supported in C, its value
14218588 560is returned via $? if any C<gethost*()> function fails.
7b8d334a 561
19799a22 562If you have installed a signal handler for C<SIGCHLD>, the
aa689395
PP
563value of C<$?> will usually be wrong outside that handler.
564
a8f8344d
PP
565Inside an C<END> subroutine C<$?> contains the value that is going to be
566given to C<exit()>. You can modify C<$?> in an C<END> subroutine to
19799a22
GS
567change the exit status of your program. For example:
568
569 END {
570 $? = 1 if $? == 255; # die would make it 255
571 }
a8f8344d 572
aa689395 573Under VMS, the pragma C<use vmsish 'status'> makes C<$?> reflect the
ff0cee69 574actual VMS exit status, instead of the default emulation of POSIX
9bc98430 575status; see L<perlvms/$?> for details.
f86702cc 576
55602bd2
IZ
577Also see L<Error Indicators>.
578
a0d0e21e
LW
579=item $OS_ERROR
580
581=item $ERRNO
582
583=item $!
584
19799a22
GS
585If used numerically, yields the current value of the C C<errno>
586variable, with all the usual caveats. (This means that you shouldn't
587depend on the value of C<$!> to be anything in particular unless
588you've gotten a specific error return indicating a system error.)
589If used an a string, yields the corresponding system error string.
590You can assign a number to C<$!> to set I<errno> if, for instance,
591you want C<"$!"> to return the string for error I<n>, or you want
592to set the exit value for the die() operator. (Mnemonic: What just
593went bang?)
a0d0e21e 594
55602bd2
IZ
595Also see L<Error Indicators>.
596
5c055ba3
PP
597=item $EXTENDED_OS_ERROR
598
599=item $^E
600
22fae026
TM
601Error information specific to the current operating system. At
602the moment, this differs from C<$!> under only VMS, OS/2, and Win32
603(and for MacPerl). On all other platforms, C<$^E> is always just
604the same as C<$!>.
605
606Under VMS, C<$^E> provides the VMS status value from the last
607system error. This is more specific information about the last
608system error than that provided by C<$!>. This is particularly
d516a115 609important when C<$!> is set to B<EVMSERR>.
22fae026 610
1c1c7f20
GS
611Under OS/2, C<$^E> is set to the error code of the last call to
612OS/2 API either via CRT, or directly from perl.
22fae026
TM
613
614Under Win32, C<$^E> always returns the last error information
615reported by the Win32 call C<GetLastError()> which describes
616the last error from within the Win32 API. Most Win32-specific
19799a22 617code will report errors via C<$^E>. ANSI C and Unix-like calls
22fae026
TM
618set C<errno> and so most portable Perl code will report errors
619via C<$!>.
620
621Caveats mentioned in the description of C<$!> generally apply to
622C<$^E>, also. (Mnemonic: Extra error explanation.)
5c055ba3 623
55602bd2
IZ
624Also see L<Error Indicators>.
625
a0d0e21e
LW
626=item $EVAL_ERROR
627
628=item $@
629
4a280ebe
JG
630The Perl syntax error message from the last eval() operator.
631If $@ is the null string, the last eval() parsed and executed
632correctly (although the operations you invoked may have failed in the
633normal fashion). (Mnemonic: Where was the syntax error "at"?)
a0d0e21e 634
19799a22 635Warning messages are not collected in this variable. You can,
a8f8344d 636however, set up a routine to process warnings by setting C<$SIG{__WARN__}>
54310121 637as described below.
748a9306 638
55602bd2
IZ
639Also see L<Error Indicators>.
640
a0d0e21e
LW
641=item $PROCESS_ID
642
643=item $PID
644
645=item $$
646
19799a22
GS
647The process number of the Perl running this script. You should
648consider this variable read-only, although it will be altered
649across fork() calls. (Mnemonic: same as shells.)
a0d0e21e
LW
650
651=item $REAL_USER_ID
652
653=item $UID
654
655=item $<
656
19799a22 657The real uid of this process. (Mnemonic: it's the uid you came I<from>,
a043a685
GW
658if you're running setuid.) You can change both the real uid and
659the effective uid at the same time by using POSIX::setuid().
a0d0e21e
LW
660
661=item $EFFECTIVE_USER_ID
662
663=item $EUID
664
665=item $>
666
667The effective uid of this process. Example:
668
669 $< = $>; # set real to effective uid
670 ($<,$>) = ($>,$<); # swap real and effective uid
671
a043a685
GW
672You can change both the effective uid and the real uid at the same
673time by using POSIX::setuid().
674
19799a22 675(Mnemonic: it's the uid you went I<to>, if you're running setuid.)
c47ff5f1 676C<< $< >> and C<< $> >> can be swapped only on machines
8cc95fdb 677supporting setreuid().
a0d0e21e
LW
678
679=item $REAL_GROUP_ID
680
681=item $GID
682
683=item $(
684
685The real gid of this process. If you are on a machine that supports
686membership in multiple groups simultaneously, gives a space separated
687list of groups you are in. The first number is the one returned by
688getgid(), and the subsequent ones by getgroups(), one of which may be
8cc95fdb
PP
689the same as the first number.
690
19799a22
GS
691However, a value assigned to C<$(> must be a single number used to
692set the real gid. So the value given by C<$(> should I<not> be assigned
693back to C<$(> without being forced numeric, such as by adding zero.
8cc95fdb 694
a043a685
GW
695You can change both the real gid and the effective gid at the same
696time by using POSIX::setgid().
697
19799a22
GS
698(Mnemonic: parentheses are used to I<group> things. The real gid is the
699group you I<left>, if you're running setgid.)
a0d0e21e
LW
700
701=item $EFFECTIVE_GROUP_ID
702
703=item $EGID
704
705=item $)
706
707The effective gid of this process. If you are on a machine that
708supports membership in multiple groups simultaneously, gives a space
709separated list of groups you are in. The first number is the one
710returned by getegid(), and the subsequent ones by getgroups(), one of
8cc95fdb
PP
711which may be the same as the first number.
712
19799a22 713Similarly, a value assigned to C<$)> must also be a space-separated
14218588 714list of numbers. The first number sets the effective gid, and
8cc95fdb
PP
715the rest (if any) are passed to setgroups(). To get the effect of an
716empty list for setgroups(), just repeat the new effective gid; that is,
717to force an effective gid of 5 and an effectively empty setgroups()
718list, say C< $) = "5 5" >.
719
a043a685
GW
720You can change both the effective gid and the real gid at the same
721time by using POSIX::setgid() (use only a single numeric argument).
722
19799a22
GS
723(Mnemonic: parentheses are used to I<group> things. The effective gid
724is the group that's I<right> for you, if you're running setgid.)
a0d0e21e 725
c47ff5f1 726C<< $< >>, C<< $> >>, C<$(> and C<$)> can be set only on
19799a22
GS
727machines that support the corresponding I<set[re][ug]id()> routine. C<$(>
728and C<$)> can be swapped only on machines supporting setregid().
a0d0e21e
LW
729
730=item $PROGRAM_NAME
731
732=item $0
733
19799a22
GS
734Contains the name of the program being executed. On some operating
735systems assigning to C<$0> modifies the argument area that the B<ps>
736program sees. This is more useful as a way of indicating the current
737program state than it is for hiding the program you're running.
a0d0e21e
LW
738(Mnemonic: same as B<sh> and B<ksh>.)
739
4bc88a62
PS
740Note for BSD users: setting C<$0> does not completely remove "perl"
741from the ps(1) output. For example, setting C<$0> to C<"foobar"> will
742result in C<"perl: foobar (perl)">. This is an operating system
743feature.
744
a0d0e21e
LW
745=item $[
746
747The index of the first element in an array, and of the first character
19799a22
GS
748in a substring. Default is 0, but you could theoretically set it
749to 1 to make Perl behave more like B<awk> (or Fortran) when
750subscripting and when evaluating the index() and substr() functions.
751(Mnemonic: [ begins subscripts.)
a0d0e21e 752
19799a22
GS
753As of release 5 of Perl, assignment to C<$[> is treated as a compiler
754directive, and cannot influence the behavior of any other file.
755Its use is highly discouraged.
a0d0e21e 756
a0d0e21e
LW
757=item $]
758
54310121
PP
759The version + patchlevel / 1000 of the Perl interpreter. This variable
760can be used to determine whether the Perl interpreter executing a
761script is in the right range of versions. (Mnemonic: Is this version
762of perl in the right bracket?) Example:
a0d0e21e
LW
763
764 warn "No checksumming!\n" if $] < 3.019;
765
54310121 766See also the documentation of C<use VERSION> and C<require VERSION>
19799a22 767for a convenient way to fail if the running Perl interpreter is too old.
a0d0e21e 768
44dcb63b
GS
769The use of this variable is deprecated. The floating point representation
770can sometimes lead to inaccurate numeric comparisons. See C<$^V> for a
771more modern representation of the Perl version that allows accurate string
772comparisons.
16070b82 773
305aace0
NIS
774=item $COMPILING
775
776=item $^C
777
19799a22
GS
778The current value of the flag associated with the B<-c> switch.
779Mainly of use with B<-MO=...> to allow code to alter its behavior
780when being compiled, such as for example to AUTOLOAD at compile
781time rather than normal, deferred loading. See L<perlcc>. Setting
782C<$^C = 1> is similar to calling C<B::minus_c>.
305aace0 783
a0d0e21e
LW
784=item $DEBUGGING
785
786=item $^D
787
788The current value of the debugging flags. (Mnemonic: value of B<-D>
789switch.)
790
791=item $SYSTEM_FD_MAX
792
793=item $^F
794
795The maximum system file descriptor, ordinarily 2. System file
796descriptors are passed to exec()ed processes, while higher file
797descriptors are not. Also, during an open(), system file descriptors are
798preserved even if the open() fails. (Ordinary file descriptors are
19799a22 799closed before the open() is attempted.) The close-on-exec
a0d0e21e 800status of a file descriptor will be decided according to the value of
8d2a6795
GS
801C<$^F> when the corresponding file, pipe, or socket was opened, not the
802time of the exec().
a0d0e21e 803
6e2995f4
PP
804=item $^H
805
0462a1ab
GS
806WARNING: This variable is strictly for internal use only. Its availability,
807behavior, and contents are subject to change without notice.
808
809This variable contains compile-time hints for the Perl interpreter. At the
810end of compilation of a BLOCK the value of this variable is restored to the
811value when the interpreter started to compile the BLOCK.
812
813When perl begins to parse any block construct that provides a lexical scope
814(e.g., eval body, required file, subroutine body, loop body, or conditional
815block), the existing value of $^H is saved, but its value is left unchanged.
816When the compilation of the block is completed, it regains the saved value.
817Between the points where its value is saved and restored, code that
818executes within BEGIN blocks is free to change the value of $^H.
819
820This behavior provides the semantic of lexical scoping, and is used in,
821for instance, the C<use strict> pragma.
822
823The contents should be an integer; different bits of it are used for
824different pragmatic flags. Here's an example:
825
826 sub add_100 { $^H |= 0x100 }
827
828 sub foo {
829 BEGIN { add_100() }
830 bar->baz($boon);
831 }
832
833Consider what happens during execution of the BEGIN block. At this point
834the BEGIN block has already been compiled, but the body of foo() is still
835being compiled. The new value of $^H will therefore be visible only while
836the body of foo() is being compiled.
837
838Substitution of the above BEGIN block with:
839
840 BEGIN { require strict; strict->import('vars') }
841
842demonstrates how C<use strict 'vars'> is implemented. Here's a conditional
843version of the same lexical pragma:
844
845 BEGIN { require strict; strict->import('vars') if $condition }
846
847=item %^H
848
849WARNING: This variable is strictly for internal use only. Its availability,
850behavior, and contents are subject to change without notice.
851
852The %^H hash provides the same scoping semantic as $^H. This makes it
853useful for implementation of lexically scoped pragmas.
6e2995f4 854
a0d0e21e
LW
855=item $INPLACE_EDIT
856
857=item $^I
858
859The current value of the inplace-edit extension. Use C<undef> to disable
860inplace editing. (Mnemonic: value of B<-i> switch.)
861
fb73857a
PP
862=item $^M
863
19799a22
GS
864By default, running out of memory is an untrappable, fatal error.
865However, if suitably built, Perl can use the contents of C<$^M>
866as an emergency memory pool after die()ing. Suppose that your Perl
867were compiled with -DPERL_EMERGENCY_SBRK and used Perl's malloc.
868Then
fb73857a 869
19799a22 870 $^M = 'a' x (1 << 16);
fb73857a 871
51ee6500 872would allocate a 64K buffer for use in an emergency. See the
19799a22
GS
873F<INSTALL> file in the Perl distribution for information on how to
874enable this option. To discourage casual use of this advanced
4ec0190b 875feature, there is no L<English|English> long name for this variable.
fb73857a 876
5c055ba3 877=item $OSNAME
6e2995f4 878
5c055ba3
PP
879=item $^O
880
881The name of the operating system under which this copy of Perl was
882built, as determined during the configuration process. The value
19799a22
GS
883is identical to C<$Config{'osname'}>. See also L<Config> and the
884B<-V> command-line switch documented in L<perlrun>.
5c055ba3 885
a0d0e21e
LW
886=item $PERLDB
887
888=item $^P
889
19799a22
GS
890The internal variable for debugging support. The meanings of the
891various bits are subject to change, but currently indicate:
84902520
TB
892
893=over 6
894
895=item 0x01
896
897Debug subroutine enter/exit.
898
899=item 0x02
900
901Line-by-line debugging.
902
903=item 0x04
904
905Switch off optimizations.
906
907=item 0x08
908
909Preserve more data for future interactive inspections.
910
911=item 0x10
912
913Keep info about source lines on which a subroutine is defined.
914
915=item 0x20
916
917Start with single-step on.
918
83ee9e09
GS
919=item 0x40
920
921Use subroutine address instead of name when reporting.
922
923=item 0x80
924
925Report C<goto &subroutine> as well.
926
927=item 0x100
928
929Provide informative "file" names for evals based on the place they were compiled.
930
931=item 0x200
932
933Provide informative names to anonymous subroutines based on the place they
934were compiled.
935
84902520
TB
936=back
937
19799a22
GS
938Some bits may be relevant at compile-time only, some at
939run-time only. This is a new mechanism and the details may change.
a0d0e21e 940
66558a10
GS
941=item $LAST_REGEXP_CODE_RESULT
942
b9ac3b5b
GS
943=item $^R
944
19799a22
GS
945The result of evaluation of the last successful C<(?{ code })>
946regular expression assertion (see L<perlre>). May be written to.
b9ac3b5b 947
66558a10
GS
948=item $EXCEPTIONS_BEING_CAUGHT
949
fb73857a
PP
950=item $^S
951
952Current state of the interpreter. Undefined if parsing of the current
953module/eval is not finished (may happen in $SIG{__DIE__} and
19799a22 954$SIG{__WARN__} handlers). True if inside an eval(), otherwise false.
fb73857a 955
a0d0e21e
LW
956=item $BASETIME
957
958=item $^T
959
19799a22 960The time at which the program began running, in seconds since the
5f05dabc 961epoch (beginning of 1970). The values returned by the B<-M>, B<-A>,
19799a22 962and B<-C> filetests are based on this value.
a0d0e21e 963
44dcb63b 964=item $PERL_VERSION
b459063d 965
16070b82
GS
966=item $^V
967
968The revision, version, and subversion of the Perl interpreter, represented
da2094fd 969as a string composed of characters with those ordinals. Thus in Perl v5.6.0
44dcb63b
GS
970it equals C<chr(5) . chr(6) . chr(0)> and will return true for
971C<$^V eq v5.6.0>. Note that the characters in this string value can
972potentially be in Unicode range.
16070b82
GS
973
974This can be used to determine whether the Perl interpreter executing a
975script is in the right range of versions. (Mnemonic: use ^V for Version
44dcb63b 976Control.) Example:
16070b82 977
3fd4402b 978 warn "No \"our\" declarations!\n" if $^V and $^V lt v5.6.0;
16070b82 979
44dcb63b 980See the documentation of C<use VERSION> and C<require VERSION>
16070b82
GS
981for a convenient way to fail if the running Perl interpreter is too old.
982
983See also C<$]> for an older representation of the Perl version.
984
a0d0e21e
LW
985=item $WARNING
986
987=item $^W
988
19799a22
GS
989The current value of the warning switch, initially true if B<-w>
990was used, false otherwise, but directly modifiable. (Mnemonic:
4438c4b7
JH
991related to the B<-w> switch.) See also L<warnings>.
992
6a818117 993=item ${^WARNING_BITS}
4438c4b7
JH
994
995The current set of warning checks enabled by the C<use warnings> pragma.
996See the documentation of C<warnings> for more details.
a0d0e21e 997
46487f74
GS
998=item ${^WIDE_SYSTEM_CALLS}
999
1000Global flag that enables system calls made by Perl to use wide character
1001APIs native to the system, if available. This is currently only implemented
1002on the Windows platform.
1003
1004This can also be enabled from the command line using the C<-C> switch.
1005
1006The initial value is typically C<0> for compatibility with Perl versions
1007earlier than 5.6, but may be automatically set to C<1> by Perl if the system
1008provides a user-settable default (e.g., C<$ENV{LC_CTYPE}>).
1009
8058d7ab
GS
1010The C<bytes> pragma always overrides the effect of this flag in the current
1011lexical scope. See L<bytes>.
46487f74 1012
a0d0e21e
LW
1013=item $EXECUTABLE_NAME
1014
1015=item $^X
1016
1017The name that the Perl binary itself was executed as, from C's C<argv[0]>.
19799a22 1018This may not be a full pathname, nor even necessarily in your path.
a0d0e21e
LW
1019
1020=item $ARGV
1021
c47ff5f1 1022contains the name of the current file when reading from <>.
a0d0e21e
LW
1023
1024=item @ARGV
1025
19799a22 1026The array @ARGV contains the command-line arguments intended for
14218588 1027the script. C<$#ARGV> is generally the number of arguments minus
19799a22
GS
1028one, because C<$ARGV[0]> is the first argument, I<not> the program's
1029command name itself. See C<$0> for the command name.
a0d0e21e 1030
9b0e6e7a
JP
1031=item @F
1032
1033The array @F contains the fields of each line read in when autosplit
1034mode is turned on. See L<perlrun> for the B<-a> switch. This array
1035is package-specific, and must be declared or given a full package name
1036if not in package main when running under C<strict 'vars'>.
1037
a0d0e21e
LW
1038=item @INC
1039
19799a22
GS
1040The array @INC contains the list of places that the C<do EXPR>,
1041C<require>, or C<use> constructs look for their library files. It
1042initially consists of the arguments to any B<-I> command-line
1043switches, followed by the default Perl library, probably
1044F</usr/local/lib/perl>, followed by ".", to represent the current
1045directory. If you need to modify this at runtime, you should use
1046the C<use lib> pragma to get the machine-dependent library properly
1047loaded also:
a0d0e21e 1048
cb1a09d0
AD
1049 use lib '/mypath/libdir/';
1050 use SomeMod;
303f2f76 1051
fb73857a
PP
1052=item @_
1053
1054Within a subroutine the array @_ contains the parameters passed to that
19799a22 1055subroutine. See L<perlsub>.
fb73857a 1056
a0d0e21e
LW
1057=item %INC
1058
19799a22
GS
1059The hash %INC contains entries for each filename included via the
1060C<do>, C<require>, or C<use> operators. The key is the filename
1061you specified (with module names converted to pathnames), and the
14218588 1062value is the location of the file found. The C<require>
87275199 1063operator uses this hash to determine whether a particular file has
19799a22 1064already been included.
a0d0e21e 1065
b687b08b
TC
1066=item %ENV
1067
1068=item $ENV{expr}
a0d0e21e
LW
1069
1070The hash %ENV contains your current environment. Setting a
19799a22
GS
1071value in C<ENV> changes the environment for any child processes
1072you subsequently fork() off.
a0d0e21e 1073
b687b08b
TC
1074=item %SIG
1075
1076=item $SIG{expr}
a0d0e21e 1077
14218588 1078The hash %SIG contains signal handlers for signals. For example:
a0d0e21e
LW
1079
1080 sub handler { # 1st argument is signal name
fb73857a 1081 my($sig) = @_;
a0d0e21e
LW
1082 print "Caught a SIG$sig--shutting down\n";
1083 close(LOG);
1084 exit(0);
1085 }
1086
fb73857a
PP
1087 $SIG{'INT'} = \&handler;
1088 $SIG{'QUIT'} = \&handler;
a0d0e21e 1089 ...
19799a22 1090 $SIG{'INT'} = 'DEFAULT'; # restore default action
a0d0e21e
LW
1091 $SIG{'QUIT'} = 'IGNORE'; # ignore SIGQUIT
1092
f648820c
GS
1093Using a value of C<'IGNORE'> usually has the effect of ignoring the
1094signal, except for the C<CHLD> signal. See L<perlipc> for more about
1095this special case.
1096
19799a22 1097Here are some other examples:
a0d0e21e 1098
fb73857a 1099 $SIG{"PIPE"} = "Plumber"; # assumes main::Plumber (not recommended)
a0d0e21e 1100 $SIG{"PIPE"} = \&Plumber; # just fine; assume current Plumber
19799a22 1101 $SIG{"PIPE"} = *Plumber; # somewhat esoteric
a0d0e21e
LW
1102 $SIG{"PIPE"} = Plumber(); # oops, what did Plumber() return??
1103
19799a22
GS
1104Be sure not to use a bareword as the name of a signal handler,
1105lest you inadvertently call it.
748a9306 1106
44a8e56a
PP
1107If your system has the sigaction() function then signal handlers are
1108installed using it. This means you get reliable signal handling. If
1109your system has the SA_RESTART flag it is used when signals handlers are
19799a22 1110installed. This means that system calls for which restarting is supported
44a8e56a
PP
1111continue rather than returning when a signal arrives. If you want your
1112system calls to be interrupted by signal delivery then do something like
1113this:
1114
1115 use POSIX ':signal_h';
1116
1117 my $alarm = 0;
1118 sigaction SIGALRM, new POSIX::SigAction sub { $alarm = 1 }
1119 or die "Error setting SIGALRM handler: $!\n";
1120
1121See L<POSIX>.
1122
748a9306 1123Certain internal hooks can be also set using the %SIG hash. The
a8f8344d 1124routine indicated by C<$SIG{__WARN__}> is called when a warning message is
748a9306
LW
1125about to be printed. The warning message is passed as the first
1126argument. The presence of a __WARN__ hook causes the ordinary printing
1127of warnings to STDERR to be suppressed. You can use this to save warnings
1128in a variable, or turn warnings into fatal errors, like this:
1129
1130 local $SIG{__WARN__} = sub { die $_[0] };
1131 eval $proggie;
1132
a8f8344d 1133The routine indicated by C<$SIG{__DIE__}> is called when a fatal exception
748a9306
LW
1134is about to be thrown. The error message is passed as the first
1135argument. When a __DIE__ hook routine returns, the exception
1136processing continues as it would have in the absence of the hook,
cb1a09d0 1137unless the hook routine itself exits via a C<goto>, a loop exit, or a die().
774d564b 1138The C<__DIE__> handler is explicitly disabled during the call, so that you
fb73857a
PP
1139can die from a C<__DIE__> handler. Similarly for C<__WARN__>.
1140
19799a22
GS
1141Due to an implementation glitch, the C<$SIG{__DIE__}> hook is called
1142even inside an eval(). Do not use this to rewrite a pending exception
1143in C<$@>, or as a bizarre substitute for overriding CORE::GLOBAL::die().
1144This strange action at a distance may be fixed in a future release
1145so that C<$SIG{__DIE__}> is only called if your program is about
1146to exit, as was the original intent. Any other use is deprecated.
1147
1148C<__DIE__>/C<__WARN__> handlers are very special in one respect:
1149they may be called to report (probable) errors found by the parser.
1150In such a case the parser may be in inconsistent state, so any
1151attempt to evaluate Perl code from such a handler will probably
1152result in a segfault. This means that warnings or errors that
1153result from parsing Perl should be used with extreme caution, like
1154this:
fb73857a
PP
1155
1156 require Carp if defined $^S;
1157 Carp::confess("Something wrong") if defined &Carp::confess;
1158 die "Something wrong, but could not load Carp to give backtrace...
1159 To see backtrace try starting Perl with -MCarp switch";
1160
1161Here the first line will load Carp I<unless> it is the parser who
1162called the handler. The second line will print backtrace and die if
1163Carp was available. The third line will be executed only if Carp was
1164not available.
1165
19799a22 1166See L<perlfunc/die>, L<perlfunc/warn>, L<perlfunc/eval>, and
4438c4b7 1167L<warnings> for additional information.
68dc0745 1168
a0d0e21e 1169=back
55602bd2
IZ
1170
1171=head2 Error Indicators
1172
19799a22
GS
1173The variables C<$@>, C<$!>, C<$^E>, and C<$?> contain information
1174about different types of error conditions that may appear during
1175execution of a Perl program. The variables are shown ordered by
1176the "distance" between the subsystem which reported the error and
1177the Perl process. They correspond to errors detected by the Perl
1178interpreter, C library, operating system, or an external program,
1179respectively.
55602bd2
IZ
1180
1181To illustrate the differences between these variables, consider the
19799a22 1182following Perl expression, which uses a single-quoted string:
55602bd2 1183
19799a22
GS
1184 eval q{
1185 open PIPE, "/cdrom/install |";
1186 @res = <PIPE>;
1187 close PIPE or die "bad pipe: $?, $!";
1188 };
55602bd2
IZ
1189
1190After execution of this statement all 4 variables may have been set.
1191
19799a22
GS
1192C<$@> is set if the string to be C<eval>-ed did not compile (this
1193may happen if C<open> or C<close> were imported with bad prototypes),
1194or if Perl code executed during evaluation die()d . In these cases
1195the value of $@ is the compile error, or the argument to C<die>
1196(which will interpolate C<$!> and C<$?>!). (See also L<Fatal>,
1197though.)
1198
c47ff5f1 1199When the eval() expression above is executed, open(), C<< <PIPE> >>,
19799a22
GS
1200and C<close> are translated to calls in the C run-time library and
1201thence to the operating system kernel. C<$!> is set to the C library's
1202C<errno> if one of these calls fails.
1203
1204Under a few operating systems, C<$^E> may contain a more verbose
1205error indicator, such as in this case, "CDROM tray not closed."
14218588 1206Systems that do not support extended error messages leave C<$^E>
19799a22
GS
1207the same as C<$!>.
1208
1209Finally, C<$?> may be set to non-0 value if the external program
1210F</cdrom/install> fails. The upper eight bits reflect specific
1211error conditions encountered by the program (the program's exit()
1212value). The lower eight bits reflect mode of failure, like signal
1213death and core dump information See wait(2) for details. In
1214contrast to C<$!> and C<$^E>, which are set only if error condition
1215is detected, the variable C<$?> is set on each C<wait> or pipe
1216C<close>, overwriting the old value. This is more like C<$@>, which
1217on every eval() is always set on failure and cleared on success.
2b92dfce 1218
19799a22
GS
1219For more details, see the individual descriptions at C<$@>, C<$!>, C<$^E>,
1220and C<$?>.
2b92dfce
GS
1221
1222=head2 Technical Note on the Syntax of Variable Names
1223
19799a22
GS
1224Variable names in Perl can have several formats. Usually, they
1225must begin with a letter or underscore, in which case they can be
1226arbitrarily long (up to an internal limit of 251 characters) and
1227may contain letters, digits, underscores, or the special sequence
1228C<::> or C<'>. In this case, the part before the last C<::> or
1229C<'> is taken to be a I<package qualifier>; see L<perlmod>.
2b92dfce
GS
1230
1231Perl variable names may also be a sequence of digits or a single
1232punctuation or control character. These names are all reserved for
19799a22
GS
1233special uses by Perl; for example, the all-digits names are used
1234to hold data captured by backreferences after a regular expression
1235match. Perl has a special syntax for the single-control-character
1236names: It understands C<^X> (caret C<X>) to mean the control-C<X>
1237character. For example, the notation C<$^W> (dollar-sign caret
1238C<W>) is the scalar variable whose name is the single character
1239control-C<W>. This is better than typing a literal control-C<W>
1240into your program.
2b92dfce 1241
87275199 1242Finally, new in Perl 5.6, Perl variable names may be alphanumeric
19799a22
GS
1243strings that begin with control characters (or better yet, a caret).
1244These variables must be written in the form C<${^Foo}>; the braces
1245are not optional. C<${^Foo}> denotes the scalar variable whose
1246name is a control-C<F> followed by two C<o>'s. These variables are
1247reserved for future special uses by Perl, except for the ones that
1248begin with C<^_> (control-underscore or caret-underscore). No
1249control-character name that begins with C<^_> will acquire a special
1250meaning in any future version of Perl; such names may therefore be
1251used safely in programs. C<$^_> itself, however, I<is> reserved.
1252
1253Perl identifiers that begin with digits, control characters, or
2b92dfce
GS
1254punctuation characters are exempt from the effects of the C<package>
1255declaration and are always forced to be in package C<main>. A few
1256other names are also exempt:
1257
1258 ENV STDIN
1259 INC STDOUT
1260 ARGV STDERR
1261 ARGVOUT
1262 SIG
1263
1264In particular, the new special C<${^_XYZ}> variables are always taken
19799a22 1265to be in package C<main>, regardless of any C<package> declarations
2b92dfce
GS
1266presently in scope.
1267
19799a22
GS
1268=head1 BUGS
1269
1270Due to an unfortunate accident of Perl's implementation, C<use
1271English> imposes a considerable performance penalty on all regular
1272expression matches in a program, regardless of whether they occur
1273in the scope of C<use English>. For that reason, saying C<use
1274English> in libraries is strongly discouraged. See the
1275Devel::SawAmpersand module documentation from CPAN
6cecdcac 1276(http://www.perl.com/CPAN/modules/by-module/Devel/)
19799a22 1277for more information.
2b92dfce 1278
19799a22
GS
1279Having to even think about the C<$^S> variable in your exception
1280handlers is simply wrong. C<$SIG{__DIE__}> as currently implemented
1281invites grievous and difficult to track down errors. Avoid it
1282and use an C<END{}> or CORE::GLOBAL::die override instead.