Commit | Line | Data |
---|---|---|
a0d0e21e LW |
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 GS |
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 LW |
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 LW |
18 | generally borrowed from B<awk>. |
19 | ||
19799a22 GS |
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 LW |
26 | |
27 | after which you may use either | |
28 | ||
29 | method HANDLE EXPR | |
30 | ||
5a964f20 | 31 | or more safely, |
a0d0e21e LW |
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 LW |
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 |
48 | arrays, then the hashes (except $^M was added in the wrong place). | |
14218588 | 49 | This is somewhat obscured because %ENV and %SIG are listed as |
fb73857a | 50 | $ENV{expr} and $SIG{expr}. |
51 | ||
a0d0e21e LW |
52 | =over 8 |
53 | ||
54 | =item $ARG | |
55 | ||
56 | =item $_ | |
57 | ||
58 | The default input and pattern-searching space. The following pairs are | |
59 | equivalent: | |
60 | ||
19799a22 | 61 | while (<>) {...} # equivalent only in while! |
54310121 | 62 | while (defined($_ = <>)) {...} |
a0d0e21e LW |
63 | |
64 | /^Subject:/ | |
65 | $_ =~ /^Subject:/ | |
66 | ||
67 | tr/a-z/A-Z/ | |
68 | $_ =~ tr/a-z/A-Z/ | |
69 | ||
19799a22 GS |
70 | chomp |
71 | chomp($_) | |
a0d0e21e | 72 | |
54310121 | 73 | Here are the places where Perl will assume $_ even if you |
cb1a09d0 AD |
74 | don't use it: |
75 | ||
76 | =over 3 | |
77 | ||
78 | =item * | |
79 | ||
80 | Various unary functions, including functions like ord() and int(), as well | |
81 | as the all file tests (C<-f>, C<-d>) except for C<-t>, which defaults to | |
82 | STDIN. | |
83 | ||
84 | =item * | |
85 | ||
86 | Various list functions like print() and unlink(). | |
87 | ||
88 | =item * | |
89 | ||
90 | The pattern matching operations C<m//>, C<s///>, and C<tr///> when used | |
91 | without an C<=~> operator. | |
92 | ||
54310121 | 93 | =item * |
cb1a09d0 AD |
94 | |
95 | The default iterator variable in a C<foreach> loop if no other | |
96 | variable is supplied. | |
97 | ||
54310121 | 98 | =item * |
cb1a09d0 AD |
99 | |
100 | The implicit iterator variable in the grep() and map() functions. | |
101 | ||
54310121 | 102 | =item * |
cb1a09d0 AD |
103 | |
104 | The default place to put an input record when a C<E<lt>FHE<gt>> | |
105 | operation's result is tested by itself as the sole criterion of a C<while> | |
14218588 | 106 | test. Outside a C<while> test, this will not happen. |
cb1a09d0 AD |
107 | |
108 | =back | |
109 | ||
a0d0e21e LW |
110 | (Mnemonic: underline is understood in certain operations.) |
111 | ||
6e2995f4 | 112 | =back |
113 | ||
114 | =over 8 | |
115 | ||
5a964f20 | 116 | =item $E<lt>I<digits>E<gt> |
a0d0e21e | 117 | |
19799a22 GS |
118 | Contains the subpattern from the corresponding set of capturing |
119 | parentheses from the last pattern match, not counting patterns | |
120 | matched in nested blocks that have been exited already. (Mnemonic: | |
121 | like \digits.) These variables are all read-only and dynamically | |
122 | scoped to the current BLOCK. | |
a0d0e21e LW |
123 | |
124 | =item $MATCH | |
125 | ||
126 | =item $& | |
127 | ||
128 | The string matched by the last successful pattern match (not counting | |
129 | any matches hidden within a BLOCK or eval() enclosed by the current | |
19799a22 GS |
130 | BLOCK). (Mnemonic: like & in some editors.) This variable is read-only |
131 | and dynamically scoped to the current BLOCK. | |
a0d0e21e | 132 | |
19ddd453 | 133 | The use of this variable anywhere in a program imposes a considerable |
19799a22 | 134 | performance penalty on all regular expression matches. See L<BUGS>. |
19ddd453 | 135 | |
a0d0e21e LW |
136 | =item $PREMATCH |
137 | ||
138 | =item $` | |
139 | ||
140 | The string preceding whatever was matched by the last successful | |
141 | pattern match (not counting any matches hidden within a BLOCK or eval | |
a8f8344d | 142 | enclosed by the current BLOCK). (Mnemonic: C<`> often precedes a quoted |
a0d0e21e LW |
143 | string.) This variable is read-only. |
144 | ||
19ddd453 | 145 | The use of this variable anywhere in a program imposes a considerable |
19799a22 | 146 | performance penalty on all regular expression matches. See L<BUGS>. |
19ddd453 | 147 | |
a0d0e21e LW |
148 | =item $POSTMATCH |
149 | ||
150 | =item $' | |
151 | ||
152 | The string following whatever was matched by the last successful | |
153 | pattern match (not counting any matches hidden within a BLOCK or eval() | |
a8f8344d | 154 | enclosed by the current BLOCK). (Mnemonic: C<'> often follows a quoted |
a0d0e21e LW |
155 | string.) Example: |
156 | ||
157 | $_ = 'abcdefghi'; | |
158 | /def/; | |
159 | print "$`:$&:$'\n"; # prints abc:def:ghi | |
160 | ||
19799a22 | 161 | This variable is read-only and dynamically scoped to the current BLOCK. |
a0d0e21e | 162 | |
19ddd453 | 163 | The use of this variable anywhere in a program imposes a considerable |
19799a22 | 164 | performance penalty on all regular expression matches. See L<BUGS>. |
19ddd453 | 165 | |
a0d0e21e LW |
166 | =item $LAST_PAREN_MATCH |
167 | ||
168 | =item $+ | |
169 | ||
170 | The last bracket matched by the last search pattern. This is useful if | |
19799a22 | 171 | you don't know which one of a set of alternative patterns matched. For |
a0d0e21e LW |
172 | example: |
173 | ||
174 | /Version: (.*)|Revision: (.*)/ && ($rev = $+); | |
175 | ||
176 | (Mnemonic: be positive and forward looking.) | |
19799a22 | 177 | This variable is read-only and dynamically scoped to the current BLOCK. |
a0d0e21e | 178 | |
6cef1e77 IZ |
179 | =item @+ |
180 | ||
19799a22 | 181 | $+[0] is the offset of the end of the last successful match. |
6cef1e77 | 182 | C<$+[>I<n>C<]> is the offset of the end of the substring matched by |
8f580fb8 | 183 | I<n>-th subpattern, or undef if the subpattern did not match. |
6cef1e77 IZ |
184 | |
185 | Thus after a match against $_, $& coincides with C<substr $_, $-[0], | |
8f580fb8 IZ |
186 | $+[0] - $-[0]>. Similarly, C<$>I<n> coincides with C<substr $_, $-[>I<n>C<], |
187 | $+[>I<n>C<] - $-[>I<n>C<]> if C<$-[>I<n>C<]> is defined, and $+ coincides with | |
188 | C<substr $_, $-[$#-], $+[$#-]>. One can use C<$#+> to find the number | |
14218588 GS |
189 | of subgroups in the last successful match. Contrast with |
190 | C<$#->, the last I<matched> subgroup. Compare with C<@->. | |
6cef1e77 | 191 | |
a0d0e21e LW |
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 LW |
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 GS |
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 LW |
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 LW |
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 GS |
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 | |
220 | number. Because C<E<lt>E<gt>> never does an explicit close, line | |
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 PJ |
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 LW |
227 | |
228 | =item input_record_separator HANDLE EXPR | |
229 | ||
230 | =item $INPUT_RECORD_SEPARATOR | |
231 | ||
232 | =item $RS | |
233 | ||
234 | =item $/ | |
235 | ||
14218588 GS |
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 GS |
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 GS |
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 GS |
250 | undef $/; # enable "slurp" mode |
251 | $_ = <FH>; # whole file now here | |
a0d0e21e LW |
252 | s/\n[ \t]+/ /g; |
253 | ||
19799a22 GS |
254 | Remember: the value of C<$/> is a string, not a regex. B<awk> has to be |
255 | better for something. :-) | |
68dc0745 | 256 | |
19799a22 GS |
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 HM |
261 | |
262 | $/ = \32768; # or \"32768", or \$var_containing_32768 | |
263 | open(FILE, $myfile); | |
264 | $_ = <FILE>; | |
265 | ||
19799a22 GS |
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 GS |
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 | |
275 | want to read in record mode is probably usable 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 LW |
281 | =item autoflush HANDLE EXPR |
282 | ||
283 | =item $OUTPUT_AUTOFLUSH | |
284 | ||
285 | =item $| | |
286 | ||
19799a22 GS |
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 GS |
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 LW |
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 GS |
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 LW |
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 GS |
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 LW |
330 | |
331 | =item $LIST_SEPARATOR | |
332 | ||
333 | =item $" | |
334 | ||
19799a22 GS |
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 LW |
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 LW |
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 GS |
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 LW |
366 | taken for something more important.) |
367 | ||
19799a22 GS |
368 | Consider using "real" multidimensional arrays as described |
369 | in L<perllol>. | |
a0d0e21e LW |
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 LW |
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 LW |
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 GS |
402 | output channel. Default is 60. |
403 | Used with formats. | |
404 | (Mnemonic: = has horizontal lines.) | |
a0d0e21e LW |
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 GS |
413 | channel. |
414 | Used with formats. | |
415 | (Mnemonic: lines_on_page - lines_printed.) | |
a0d0e21e | 416 | |
6cef1e77 IZ |
417 | =item @- |
418 | ||
19799a22 | 419 | $-[0] is the offset of the start of the last successful match. |
6cef1e77 | 420 | C<$-[>I<n>C<]> is the offset of the start of the substring matched by |
8f580fb8 | 421 | I<n>-th subpattern, or undef if the subpattern did not match. |
6cef1e77 IZ |
422 | |
423 | Thus after a match against $_, $& coincides with C<substr $_, $-[0], | |
8f580fb8 IZ |
424 | $+[0] - $-[0]>. Similarly, C<$>I<n> coincides with C<substr $_, $-[>I<n>C<], |
425 | $+[>I<n>C<] - $-[>I<n>C<]> if C<$-[>I<n>C<]> is defined, and $+ coincides with | |
426 | C<substr $_, $-[$#-], $+[$#-]>. One can use C<$#-> to find the last | |
14218588 GS |
427 | matched subgroup in the last successful match. Contrast with |
428 | C<$#+>, the number of subgroups in the regular expression. Compare | |
19799a22 | 429 | with C<@+>. |
6cef1e77 | 430 | |
a0d0e21e LW |
431 | =item format_name HANDLE EXPR |
432 | ||
433 | =item $FORMAT_NAME | |
434 | ||
435 | =item $~ | |
436 | ||
437 | The name of the current report format for the currently selected output | |
14218588 | 438 | channel. Default is the name of the filehandle. (Mnemonic: brother to |
19799a22 | 439 | C<$^>.) |
a0d0e21e LW |
440 | |
441 | =item format_top_name HANDLE EXPR | |
442 | ||
443 | =item $FORMAT_TOP_NAME | |
444 | ||
445 | =item $^ | |
446 | ||
447 | The name of the current top-of-page format for the currently selected | |
14218588 | 448 | output channel. Default is the name of the filehandle with _TOP |
a0d0e21e LW |
449 | appended. (Mnemonic: points to top of page.) |
450 | ||
451 | =item format_line_break_characters HANDLE EXPR | |
452 | ||
453 | =item $FORMAT_LINE_BREAK_CHARACTERS | |
454 | ||
455 | =item $: | |
456 | ||
457 | The current set of characters after which a string may be broken to | |
54310121 | 458 | fill continuation fields (starting with ^) in a format. Default is |
a0d0e21e LW |
459 | S<" \n-">, to break on whitespace or hyphens. (Mnemonic: a "colon" in |
460 | poetry is a part of a line.) | |
461 | ||
462 | =item format_formfeed HANDLE EXPR | |
463 | ||
464 | =item $FORMAT_FORMFEED | |
465 | ||
466 | =item $^L | |
467 | ||
14218588 | 468 | What formats output as a form feed. Default is \f. |
a0d0e21e LW |
469 | |
470 | =item $ACCUMULATOR | |
471 | ||
472 | =item $^A | |
473 | ||
474 | The current value of the write() accumulator for format() lines. A format | |
19799a22 | 475 | contains formline() calls that put their result into C<$^A>. After |
a0d0e21e | 476 | calling its format, write() prints out the contents of C<$^A> and empties. |
14218588 | 477 | So you never really see the contents of C<$^A> unless you call |
a0d0e21e LW |
478 | formline() yourself and then look at it. See L<perlform> and |
479 | L<perlfunc/formline()>. | |
480 | ||
481 | =item $CHILD_ERROR | |
482 | ||
483 | =item $? | |
484 | ||
54310121 | 485 | The status returned by the last pipe close, backtick (C<``>) command, |
19799a22 GS |
486 | successful call to wait() or waitpid(), or from the system() |
487 | operator. This is just the 16-bit status word returned by the | |
488 | wait() system call (or else is made up to look like it). Thus, the | |
14218588 | 489 | exit value of the subprocess is really (C<$? E<gt>E<gt> 8>), and |
19799a22 GS |
490 | C<$? & 127> gives which signal, if any, the process died from, and |
491 | C<$? & 128> reports whether there was a core dump. (Mnemonic: | |
492 | similar to B<sh> and B<ksh>.) | |
a0d0e21e | 493 | |
7b8d334a | 494 | Additionally, if the C<h_errno> variable is supported in C, its value |
14218588 | 495 | is returned via $? if any C<gethost*()> function fails. |
7b8d334a | 496 | |
19799a22 | 497 | If you have installed a signal handler for C<SIGCHLD>, the |
aa689395 | 498 | value of C<$?> will usually be wrong outside that handler. |
499 | ||
a8f8344d | 500 | Inside an C<END> subroutine C<$?> contains the value that is going to be |
501 | given to C<exit()>. You can modify C<$?> in an C<END> subroutine to | |
19799a22 GS |
502 | change the exit status of your program. For example: |
503 | ||
504 | END { | |
505 | $? = 1 if $? == 255; # die would make it 255 | |
506 | } | |
a8f8344d | 507 | |
aa689395 | 508 | Under VMS, the pragma C<use vmsish 'status'> makes C<$?> reflect the |
ff0cee69 | 509 | actual VMS exit status, instead of the default emulation of POSIX |
510 | status. | |
f86702cc | 511 | |
55602bd2 IZ |
512 | Also see L<Error Indicators>. |
513 | ||
a0d0e21e LW |
514 | =item $OS_ERROR |
515 | ||
516 | =item $ERRNO | |
517 | ||
518 | =item $! | |
519 | ||
19799a22 GS |
520 | If used numerically, yields the current value of the C C<errno> |
521 | variable, with all the usual caveats. (This means that you shouldn't | |
522 | depend on the value of C<$!> to be anything in particular unless | |
523 | you've gotten a specific error return indicating a system error.) | |
524 | If used an a string, yields the corresponding system error string. | |
525 | You can assign a number to C<$!> to set I<errno> if, for instance, | |
526 | you want C<"$!"> to return the string for error I<n>, or you want | |
527 | to set the exit value for the die() operator. (Mnemonic: What just | |
528 | went bang?) | |
a0d0e21e | 529 | |
55602bd2 IZ |
530 | Also see L<Error Indicators>. |
531 | ||
5c055ba3 | 532 | =item $EXTENDED_OS_ERROR |
533 | ||
534 | =item $^E | |
535 | ||
22fae026 TM |
536 | Error information specific to the current operating system. At |
537 | the moment, this differs from C<$!> under only VMS, OS/2, and Win32 | |
538 | (and for MacPerl). On all other platforms, C<$^E> is always just | |
539 | the same as C<$!>. | |
540 | ||
541 | Under VMS, C<$^E> provides the VMS status value from the last | |
542 | system error. This is more specific information about the last | |
543 | system error than that provided by C<$!>. This is particularly | |
d516a115 | 544 | important when C<$!> is set to B<EVMSERR>. |
22fae026 | 545 | |
1c1c7f20 GS |
546 | Under OS/2, C<$^E> is set to the error code of the last call to |
547 | OS/2 API either via CRT, or directly from perl. | |
22fae026 TM |
548 | |
549 | Under Win32, C<$^E> always returns the last error information | |
550 | reported by the Win32 call C<GetLastError()> which describes | |
551 | the last error from within the Win32 API. Most Win32-specific | |
19799a22 | 552 | code will report errors via C<$^E>. ANSI C and Unix-like calls |
22fae026 TM |
553 | set C<errno> and so most portable Perl code will report errors |
554 | via C<$!>. | |
555 | ||
556 | Caveats mentioned in the description of C<$!> generally apply to | |
557 | C<$^E>, also. (Mnemonic: Extra error explanation.) | |
5c055ba3 | 558 | |
55602bd2 IZ |
559 | Also see L<Error Indicators>. |
560 | ||
a0d0e21e LW |
561 | =item $EVAL_ERROR |
562 | ||
563 | =item $@ | |
564 | ||
19799a22 | 565 | The Perl syntax error message from the last eval() operator. If null, the |
a0d0e21e LW |
566 | last eval() parsed and executed correctly (although the operations you |
567 | invoked may have failed in the normal fashion). (Mnemonic: Where was | |
568 | the syntax error "at"?) | |
569 | ||
19799a22 | 570 | Warning messages are not collected in this variable. You can, |
a8f8344d | 571 | however, set up a routine to process warnings by setting C<$SIG{__WARN__}> |
54310121 | 572 | as described below. |
748a9306 | 573 | |
55602bd2 IZ |
574 | Also see L<Error Indicators>. |
575 | ||
a0d0e21e LW |
576 | =item $PROCESS_ID |
577 | ||
578 | =item $PID | |
579 | ||
580 | =item $$ | |
581 | ||
19799a22 GS |
582 | The process number of the Perl running this script. You should |
583 | consider this variable read-only, although it will be altered | |
584 | across fork() calls. (Mnemonic: same as shells.) | |
a0d0e21e LW |
585 | |
586 | =item $REAL_USER_ID | |
587 | ||
588 | =item $UID | |
589 | ||
590 | =item $< | |
591 | ||
19799a22 | 592 | The real uid of this process. (Mnemonic: it's the uid you came I<from>, |
a0d0e21e LW |
593 | if you're running setuid.) |
594 | ||
595 | =item $EFFECTIVE_USER_ID | |
596 | ||
597 | =item $EUID | |
598 | ||
599 | =item $> | |
600 | ||
601 | The effective uid of this process. Example: | |
602 | ||
603 | $< = $>; # set real to effective uid | |
604 | ($<,$>) = ($>,$<); # swap real and effective uid | |
605 | ||
19799a22 | 606 | (Mnemonic: it's the uid you went I<to>, if you're running setuid.) |
14218588 | 607 | C<$E<lt>> and C<$E<gt>> can be swapped only on machines |
8cc95fdb | 608 | supporting setreuid(). |
a0d0e21e LW |
609 | |
610 | =item $REAL_GROUP_ID | |
611 | ||
612 | =item $GID | |
613 | ||
614 | =item $( | |
615 | ||
616 | The real gid of this process. If you are on a machine that supports | |
617 | membership in multiple groups simultaneously, gives a space separated | |
618 | list of groups you are in. The first number is the one returned by | |
619 | getgid(), and the subsequent ones by getgroups(), one of which may be | |
8cc95fdb | 620 | the same as the first number. |
621 | ||
19799a22 GS |
622 | However, a value assigned to C<$(> must be a single number used to |
623 | set the real gid. So the value given by C<$(> should I<not> be assigned | |
624 | back to C<$(> without being forced numeric, such as by adding zero. | |
8cc95fdb | 625 | |
19799a22 GS |
626 | (Mnemonic: parentheses are used to I<group> things. The real gid is the |
627 | group you I<left>, if you're running setgid.) | |
a0d0e21e LW |
628 | |
629 | =item $EFFECTIVE_GROUP_ID | |
630 | ||
631 | =item $EGID | |
632 | ||
633 | =item $) | |
634 | ||
635 | The effective gid of this process. If you are on a machine that | |
636 | supports membership in multiple groups simultaneously, gives a space | |
637 | separated list of groups you are in. The first number is the one | |
638 | returned by getegid(), and the subsequent ones by getgroups(), one of | |
8cc95fdb | 639 | which may be the same as the first number. |
640 | ||
19799a22 | 641 | Similarly, a value assigned to C<$)> must also be a space-separated |
14218588 | 642 | list of numbers. The first number sets the effective gid, and |
8cc95fdb | 643 | the rest (if any) are passed to setgroups(). To get the effect of an |
644 | empty list for setgroups(), just repeat the new effective gid; that is, | |
645 | to force an effective gid of 5 and an effectively empty setgroups() | |
646 | list, say C< $) = "5 5" >. | |
647 | ||
19799a22 GS |
648 | (Mnemonic: parentheses are used to I<group> things. The effective gid |
649 | is the group that's I<right> for you, if you're running setgid.) | |
a0d0e21e | 650 | |
14218588 | 651 | C<$E<lt>>, C<$E<gt>>, C<$(> and C<$)> can be set only on |
19799a22 GS |
652 | machines that support the corresponding I<set[re][ug]id()> routine. C<$(> |
653 | and C<$)> can be swapped only on machines supporting setregid(). | |
a0d0e21e LW |
654 | |
655 | =item $PROGRAM_NAME | |
656 | ||
657 | =item $0 | |
658 | ||
19799a22 GS |
659 | Contains the name of the program being executed. On some operating |
660 | systems assigning to C<$0> modifies the argument area that the B<ps> | |
661 | program sees. This is more useful as a way of indicating the current | |
662 | program state than it is for hiding the program you're running. | |
a0d0e21e LW |
663 | (Mnemonic: same as B<sh> and B<ksh>.) |
664 | ||
665 | =item $[ | |
666 | ||
667 | The index of the first element in an array, and of the first character | |
19799a22 GS |
668 | in a substring. Default is 0, but you could theoretically set it |
669 | to 1 to make Perl behave more like B<awk> (or Fortran) when | |
670 | subscripting and when evaluating the index() and substr() functions. | |
671 | (Mnemonic: [ begins subscripts.) | |
a0d0e21e | 672 | |
19799a22 GS |
673 | As of release 5 of Perl, assignment to C<$[> is treated as a compiler |
674 | directive, and cannot influence the behavior of any other file. | |
675 | Its use is highly discouraged. | |
a0d0e21e LW |
676 | |
677 | =item $PERL_VERSION | |
678 | ||
679 | =item $] | |
680 | ||
54310121 | 681 | The version + patchlevel / 1000 of the Perl interpreter. This variable |
682 | can be used to determine whether the Perl interpreter executing a | |
683 | script is in the right range of versions. (Mnemonic: Is this version | |
684 | of perl in the right bracket?) Example: | |
a0d0e21e LW |
685 | |
686 | warn "No checksumming!\n" if $] < 3.019; | |
687 | ||
54310121 | 688 | See also the documentation of C<use VERSION> and C<require VERSION> |
19799a22 | 689 | for a convenient way to fail if the running Perl interpreter is too old. |
a0d0e21e | 690 | |
305aace0 NIS |
691 | =item $COMPILING |
692 | ||
693 | =item $^C | |
694 | ||
19799a22 GS |
695 | The current value of the flag associated with the B<-c> switch. |
696 | Mainly of use with B<-MO=...> to allow code to alter its behavior | |
697 | when being compiled, such as for example to AUTOLOAD at compile | |
698 | time rather than normal, deferred loading. See L<perlcc>. Setting | |
699 | C<$^C = 1> is similar to calling C<B::minus_c>. | |
305aace0 | 700 | |
a0d0e21e LW |
701 | =item $DEBUGGING |
702 | ||
703 | =item $^D | |
704 | ||
705 | The current value of the debugging flags. (Mnemonic: value of B<-D> | |
706 | switch.) | |
707 | ||
708 | =item $SYSTEM_FD_MAX | |
709 | ||
710 | =item $^F | |
711 | ||
712 | The maximum system file descriptor, ordinarily 2. System file | |
713 | descriptors are passed to exec()ed processes, while higher file | |
714 | descriptors are not. Also, during an open(), system file descriptors are | |
715 | preserved even if the open() fails. (Ordinary file descriptors are | |
19799a22 | 716 | closed before the open() is attempted.) The close-on-exec |
a0d0e21e | 717 | status of a file descriptor will be decided according to the value of |
4771b018 | 718 | C<$^F> when the open() or pipe() was called, not the time of the exec(). |
a0d0e21e | 719 | |
6e2995f4 | 720 | =item $^H |
721 | ||
fb73857a | 722 | The current set of syntax checks enabled by C<use strict> and other block |
723 | scoped compiler hints. See the documentation of C<strict> for more details. | |
6e2995f4 | 724 | |
a0d0e21e LW |
725 | =item $INPLACE_EDIT |
726 | ||
727 | =item $^I | |
728 | ||
729 | The current value of the inplace-edit extension. Use C<undef> to disable | |
730 | inplace editing. (Mnemonic: value of B<-i> switch.) | |
731 | ||
fb73857a | 732 | =item $^M |
733 | ||
19799a22 GS |
734 | By default, running out of memory is an untrappable, fatal error. |
735 | However, if suitably built, Perl can use the contents of C<$^M> | |
736 | as an emergency memory pool after die()ing. Suppose that your Perl | |
737 | were compiled with -DPERL_EMERGENCY_SBRK and used Perl's malloc. | |
738 | Then | |
fb73857a | 739 | |
19799a22 | 740 | $^M = 'a' x (1 << 16); |
fb73857a | 741 | |
19799a22 GS |
742 | would allocate a 64K buffer for use when in emergency. See the |
743 | F<INSTALL> file in the Perl distribution for information on how to | |
744 | enable this option. To discourage casual use of this advanced | |
745 | feature, there is no L<English> long name for this variable. | |
fb73857a | 746 | |
5c055ba3 | 747 | =item $OSNAME |
6e2995f4 | 748 | |
5c055ba3 | 749 | =item $^O |
750 | ||
751 | The name of the operating system under which this copy of Perl was | |
752 | built, as determined during the configuration process. The value | |
19799a22 GS |
753 | is identical to C<$Config{'osname'}>. See also L<Config> and the |
754 | B<-V> command-line switch documented in L<perlrun>. | |
5c055ba3 | 755 | |
a0d0e21e LW |
756 | =item $PERLDB |
757 | ||
758 | =item $^P | |
759 | ||
19799a22 GS |
760 | The internal variable for debugging support. The meanings of the |
761 | various bits are subject to change, but currently indicate: | |
84902520 TB |
762 | |
763 | =over 6 | |
764 | ||
765 | =item 0x01 | |
766 | ||
767 | Debug subroutine enter/exit. | |
768 | ||
769 | =item 0x02 | |
770 | ||
771 | Line-by-line debugging. | |
772 | ||
773 | =item 0x04 | |
774 | ||
775 | Switch off optimizations. | |
776 | ||
777 | =item 0x08 | |
778 | ||
779 | Preserve more data for future interactive inspections. | |
780 | ||
781 | =item 0x10 | |
782 | ||
783 | Keep info about source lines on which a subroutine is defined. | |
784 | ||
785 | =item 0x20 | |
786 | ||
787 | Start with single-step on. | |
788 | ||
789 | =back | |
790 | ||
19799a22 GS |
791 | Some bits may be relevant at compile-time only, some at |
792 | run-time only. This is a new mechanism and the details may change. | |
a0d0e21e | 793 | |
b9ac3b5b GS |
794 | =item $^R |
795 | ||
19799a22 GS |
796 | The result of evaluation of the last successful C<(?{ code })> |
797 | regular expression assertion (see L<perlre>). May be written to. | |
b9ac3b5b | 798 | |
fb73857a | 799 | =item $^S |
800 | ||
801 | Current state of the interpreter. Undefined if parsing of the current | |
802 | module/eval is not finished (may happen in $SIG{__DIE__} and | |
19799a22 | 803 | $SIG{__WARN__} handlers). True if inside an eval(), otherwise false. |
fb73857a | 804 | |
a0d0e21e LW |
805 | =item $BASETIME |
806 | ||
807 | =item $^T | |
808 | ||
19799a22 | 809 | The time at which the program began running, in seconds since the |
5f05dabc | 810 | epoch (beginning of 1970). The values returned by the B<-M>, B<-A>, |
19799a22 | 811 | and B<-C> filetests are based on this value. |
a0d0e21e LW |
812 | |
813 | =item $WARNING | |
814 | ||
815 | =item $^W | |
816 | ||
19799a22 GS |
817 | The current value of the warning switch, initially true if B<-w> |
818 | was used, false otherwise, but directly modifiable. (Mnemonic: | |
819 | related to the B<-w> switch.) See also L<warning>. | |
a0d0e21e LW |
820 | |
821 | =item $EXECUTABLE_NAME | |
822 | ||
823 | =item $^X | |
824 | ||
825 | The name that the Perl binary itself was executed as, from C's C<argv[0]>. | |
19799a22 | 826 | This may not be a full pathname, nor even necessarily in your path. |
a0d0e21e LW |
827 | |
828 | =item $ARGV | |
829 | ||
a8f8344d | 830 | contains the name of the current file when reading from E<lt>E<gt>. |
a0d0e21e LW |
831 | |
832 | =item @ARGV | |
833 | ||
19799a22 | 834 | The array @ARGV contains the command-line arguments intended for |
14218588 | 835 | the script. C<$#ARGV> is generally the number of arguments minus |
19799a22 GS |
836 | one, because C<$ARGV[0]> is the first argument, I<not> the program's |
837 | command name itself. See C<$0> for the command name. | |
a0d0e21e LW |
838 | |
839 | =item @INC | |
840 | ||
19799a22 GS |
841 | The array @INC contains the list of places that the C<do EXPR>, |
842 | C<require>, or C<use> constructs look for their library files. It | |
843 | initially consists of the arguments to any B<-I> command-line | |
844 | switches, followed by the default Perl library, probably | |
845 | F</usr/local/lib/perl>, followed by ".", to represent the current | |
846 | directory. If you need to modify this at runtime, you should use | |
847 | the C<use lib> pragma to get the machine-dependent library properly | |
848 | loaded also: | |
a0d0e21e | 849 | |
cb1a09d0 AD |
850 | use lib '/mypath/libdir/'; |
851 | use SomeMod; | |
303f2f76 | 852 | |
fb73857a | 853 | =item @_ |
854 | ||
855 | Within a subroutine the array @_ contains the parameters passed to that | |
19799a22 | 856 | subroutine. See L<perlsub>. |
fb73857a | 857 | |
a0d0e21e LW |
858 | =item %INC |
859 | ||
19799a22 GS |
860 | The hash %INC contains entries for each filename included via the |
861 | C<do>, C<require>, or C<use> operators. The key is the filename | |
862 | you specified (with module names converted to pathnames), and the | |
14218588 | 863 | value is the location of the file found. The C<require> |
19799a22 GS |
864 | operator uses this array to determine whether a particular file has |
865 | already been included. | |
a0d0e21e | 866 | |
b687b08b TC |
867 | =item %ENV |
868 | ||
869 | =item $ENV{expr} | |
a0d0e21e LW |
870 | |
871 | The hash %ENV contains your current environment. Setting a | |
19799a22 GS |
872 | value in C<ENV> changes the environment for any child processes |
873 | you subsequently fork() off. | |
a0d0e21e | 874 | |
b687b08b TC |
875 | =item %SIG |
876 | ||
877 | =item $SIG{expr} | |
a0d0e21e | 878 | |
14218588 | 879 | The hash %SIG contains signal handlers for signals. For example: |
a0d0e21e LW |
880 | |
881 | sub handler { # 1st argument is signal name | |
fb73857a | 882 | my($sig) = @_; |
a0d0e21e LW |
883 | print "Caught a SIG$sig--shutting down\n"; |
884 | close(LOG); | |
885 | exit(0); | |
886 | } | |
887 | ||
fb73857a | 888 | $SIG{'INT'} = \&handler; |
889 | $SIG{'QUIT'} = \&handler; | |
a0d0e21e | 890 | ... |
19799a22 | 891 | $SIG{'INT'} = 'DEFAULT'; # restore default action |
a0d0e21e LW |
892 | $SIG{'QUIT'} = 'IGNORE'; # ignore SIGQUIT |
893 | ||
f648820c GS |
894 | Using a value of C<'IGNORE'> usually has the effect of ignoring the |
895 | signal, except for the C<CHLD> signal. See L<perlipc> for more about | |
896 | this special case. | |
897 | ||
19799a22 | 898 | Here are some other examples: |
a0d0e21e | 899 | |
fb73857a | 900 | $SIG{"PIPE"} = "Plumber"; # assumes main::Plumber (not recommended) |
a0d0e21e | 901 | $SIG{"PIPE"} = \&Plumber; # just fine; assume current Plumber |
19799a22 | 902 | $SIG{"PIPE"} = *Plumber; # somewhat esoteric |
a0d0e21e LW |
903 | $SIG{"PIPE"} = Plumber(); # oops, what did Plumber() return?? |
904 | ||
19799a22 GS |
905 | Be sure not to use a bareword as the name of a signal handler, |
906 | lest you inadvertently call it. | |
748a9306 | 907 | |
44a8e56a | 908 | If your system has the sigaction() function then signal handlers are |
909 | installed using it. This means you get reliable signal handling. If | |
910 | your system has the SA_RESTART flag it is used when signals handlers are | |
19799a22 | 911 | installed. This means that system calls for which restarting is supported |
44a8e56a | 912 | continue rather than returning when a signal arrives. If you want your |
913 | system calls to be interrupted by signal delivery then do something like | |
914 | this: | |
915 | ||
916 | use POSIX ':signal_h'; | |
917 | ||
918 | my $alarm = 0; | |
919 | sigaction SIGALRM, new POSIX::SigAction sub { $alarm = 1 } | |
920 | or die "Error setting SIGALRM handler: $!\n"; | |
921 | ||
922 | See L<POSIX>. | |
923 | ||
748a9306 | 924 | Certain internal hooks can be also set using the %SIG hash. The |
a8f8344d | 925 | routine indicated by C<$SIG{__WARN__}> is called when a warning message is |
748a9306 LW |
926 | about to be printed. The warning message is passed as the first |
927 | argument. The presence of a __WARN__ hook causes the ordinary printing | |
928 | of warnings to STDERR to be suppressed. You can use this to save warnings | |
929 | in a variable, or turn warnings into fatal errors, like this: | |
930 | ||
931 | local $SIG{__WARN__} = sub { die $_[0] }; | |
932 | eval $proggie; | |
933 | ||
a8f8344d | 934 | The routine indicated by C<$SIG{__DIE__}> is called when a fatal exception |
748a9306 LW |
935 | is about to be thrown. The error message is passed as the first |
936 | argument. When a __DIE__ hook routine returns, the exception | |
937 | processing continues as it would have in the absence of the hook, | |
cb1a09d0 | 938 | unless the hook routine itself exits via a C<goto>, a loop exit, or a die(). |
774d564b | 939 | The C<__DIE__> handler is explicitly disabled during the call, so that you |
fb73857a | 940 | can die from a C<__DIE__> handler. Similarly for C<__WARN__>. |
941 | ||
19799a22 GS |
942 | Due to an implementation glitch, the C<$SIG{__DIE__}> hook is called |
943 | even inside an eval(). Do not use this to rewrite a pending exception | |
944 | in C<$@>, or as a bizarre substitute for overriding CORE::GLOBAL::die(). | |
945 | This strange action at a distance may be fixed in a future release | |
946 | so that C<$SIG{__DIE__}> is only called if your program is about | |
947 | to exit, as was the original intent. Any other use is deprecated. | |
948 | ||
949 | C<__DIE__>/C<__WARN__> handlers are very special in one respect: | |
950 | they may be called to report (probable) errors found by the parser. | |
951 | In such a case the parser may be in inconsistent state, so any | |
952 | attempt to evaluate Perl code from such a handler will probably | |
953 | result in a segfault. This means that warnings or errors that | |
954 | result from parsing Perl should be used with extreme caution, like | |
955 | this: | |
fb73857a | 956 | |
957 | require Carp if defined $^S; | |
958 | Carp::confess("Something wrong") if defined &Carp::confess; | |
959 | die "Something wrong, but could not load Carp to give backtrace... | |
960 | To see backtrace try starting Perl with -MCarp switch"; | |
961 | ||
962 | Here the first line will load Carp I<unless> it is the parser who | |
963 | called the handler. The second line will print backtrace and die if | |
964 | Carp was available. The third line will be executed only if Carp was | |
965 | not available. | |
966 | ||
19799a22 GS |
967 | See L<perlfunc/die>, L<perlfunc/warn>, L<perlfunc/eval>, and |
968 | L<warning> for additional information. | |
68dc0745 | 969 | |
a0d0e21e | 970 | =back |
55602bd2 IZ |
971 | |
972 | =head2 Error Indicators | |
973 | ||
19799a22 GS |
974 | The variables C<$@>, C<$!>, C<$^E>, and C<$?> contain information |
975 | about different types of error conditions that may appear during | |
976 | execution of a Perl program. The variables are shown ordered by | |
977 | the "distance" between the subsystem which reported the error and | |
978 | the Perl process. They correspond to errors detected by the Perl | |
979 | interpreter, C library, operating system, or an external program, | |
980 | respectively. | |
55602bd2 IZ |
981 | |
982 | To illustrate the differences between these variables, consider the | |
19799a22 | 983 | following Perl expression, which uses a single-quoted string: |
55602bd2 | 984 | |
19799a22 GS |
985 | eval q{ |
986 | open PIPE, "/cdrom/install |"; | |
987 | @res = <PIPE>; | |
988 | close PIPE or die "bad pipe: $?, $!"; | |
989 | }; | |
55602bd2 IZ |
990 | |
991 | After execution of this statement all 4 variables may have been set. | |
992 | ||
19799a22 GS |
993 | C<$@> is set if the string to be C<eval>-ed did not compile (this |
994 | may happen if C<open> or C<close> were imported with bad prototypes), | |
995 | or if Perl code executed during evaluation die()d . In these cases | |
996 | the value of $@ is the compile error, or the argument to C<die> | |
997 | (which will interpolate C<$!> and C<$?>!). (See also L<Fatal>, | |
998 | though.) | |
999 | ||
1000 | When the eval() expression above is executed, open(), C<<PIPEE<gt>>, | |
1001 | and C<close> are translated to calls in the C run-time library and | |
1002 | thence to the operating system kernel. C<$!> is set to the C library's | |
1003 | C<errno> if one of these calls fails. | |
1004 | ||
1005 | Under a few operating systems, C<$^E> may contain a more verbose | |
1006 | error indicator, such as in this case, "CDROM tray not closed." | |
14218588 | 1007 | Systems that do not support extended error messages leave C<$^E> |
19799a22 GS |
1008 | the same as C<$!>. |
1009 | ||
1010 | Finally, C<$?> may be set to non-0 value if the external program | |
1011 | F</cdrom/install> fails. The upper eight bits reflect specific | |
1012 | error conditions encountered by the program (the program's exit() | |
1013 | value). The lower eight bits reflect mode of failure, like signal | |
1014 | death and core dump information See wait(2) for details. In | |
1015 | contrast to C<$!> and C<$^E>, which are set only if error condition | |
1016 | is detected, the variable C<$?> is set on each C<wait> or pipe | |
1017 | C<close>, overwriting the old value. This is more like C<$@>, which | |
1018 | on every eval() is always set on failure and cleared on success. | |
2b92dfce | 1019 | |
19799a22 GS |
1020 | For more details, see the individual descriptions at C<$@>, C<$!>, C<$^E>, |
1021 | and C<$?>. | |
2b92dfce GS |
1022 | |
1023 | =head2 Technical Note on the Syntax of Variable Names | |
1024 | ||
19799a22 GS |
1025 | Variable names in Perl can have several formats. Usually, they |
1026 | must begin with a letter or underscore, in which case they can be | |
1027 | arbitrarily long (up to an internal limit of 251 characters) and | |
1028 | may contain letters, digits, underscores, or the special sequence | |
1029 | C<::> or C<'>. In this case, the part before the last C<::> or | |
1030 | C<'> is taken to be a I<package qualifier>; see L<perlmod>. | |
2b92dfce GS |
1031 | |
1032 | Perl variable names may also be a sequence of digits or a single | |
1033 | punctuation or control character. These names are all reserved for | |
19799a22 GS |
1034 | special uses by Perl; for example, the all-digits names are used |
1035 | to hold data captured by backreferences after a regular expression | |
1036 | match. Perl has a special syntax for the single-control-character | |
1037 | names: It understands C<^X> (caret C<X>) to mean the control-C<X> | |
1038 | character. For example, the notation C<$^W> (dollar-sign caret | |
1039 | C<W>) is the scalar variable whose name is the single character | |
1040 | control-C<W>. This is better than typing a literal control-C<W> | |
1041 | into your program. | |
2b92dfce GS |
1042 | |
1043 | Finally, new in Perl 5.006, Perl variable names may be alphanumeric | |
19799a22 GS |
1044 | strings that begin with control characters (or better yet, a caret). |
1045 | These variables must be written in the form C<${^Foo}>; the braces | |
1046 | are not optional. C<${^Foo}> denotes the scalar variable whose | |
1047 | name is a control-C<F> followed by two C<o>'s. These variables are | |
1048 | reserved for future special uses by Perl, except for the ones that | |
1049 | begin with C<^_> (control-underscore or caret-underscore). No | |
1050 | control-character name that begins with C<^_> will acquire a special | |
1051 | meaning in any future version of Perl; such names may therefore be | |
1052 | used safely in programs. C<$^_> itself, however, I<is> reserved. | |
1053 | ||
1054 | Perl identifiers that begin with digits, control characters, or | |
2b92dfce GS |
1055 | punctuation characters are exempt from the effects of the C<package> |
1056 | declaration and are always forced to be in package C<main>. A few | |
1057 | other names are also exempt: | |
1058 | ||
1059 | ENV STDIN | |
1060 | INC STDOUT | |
1061 | ARGV STDERR | |
1062 | ARGVOUT | |
1063 | SIG | |
1064 | ||
1065 | In particular, the new special C<${^_XYZ}> variables are always taken | |
19799a22 | 1066 | to be in package C<main>, regardless of any C<package> declarations |
2b92dfce GS |
1067 | presently in scope. |
1068 | ||
19799a22 GS |
1069 | =head1 BUGS |
1070 | ||
1071 | Due to an unfortunate accident of Perl's implementation, C<use | |
1072 | English> imposes a considerable performance penalty on all regular | |
1073 | expression matches in a program, regardless of whether they occur | |
1074 | in the scope of C<use English>. For that reason, saying C<use | |
1075 | English> in libraries is strongly discouraged. See the | |
1076 | Devel::SawAmpersand module documentation from CPAN | |
1077 | (http://www.perl.com/CPAN/modules/by-module/Devel/Devel-SawAmpersand-0.10.readme) | |
1078 | for more information. | |
2b92dfce | 1079 | |
19799a22 GS |
1080 | Having to even think about the C<$^S> variable in your exception |
1081 | handlers is simply wrong. C<$SIG{__DIE__}> as currently implemented | |
1082 | invites grievous and difficult to track down errors. Avoid it | |
1083 | and use an C<END{}> or CORE::GLOBAL::die override instead. |