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