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