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