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