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