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