Commit | Line | Data |
---|---|---|
a0d0e21e LW |
1 | =head1 NAME |
2 | ||
3 | perlvar - Perl predefined variables | |
4 | ||
5 | =head1 DESCRIPTION | |
6 | ||
7 | =head2 Predefined Names | |
8 | ||
9 | The following names have special meaning to Perl. Most of the | |
5f05dabc | 10 | punctuation names have reasonable mnemonics, or analogues in one of |
a0d0e21e LW |
11 | the shells. Nevertheless, if you wish to use the long variable names, |
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 | |
17 | long names in the current package. Some of them even have medium names, | |
18 | generally borrowed from B<awk>. | |
19 | ||
20 | To go a step further, those variables that depend on the currently | |
21 | selected filehandle may instead be set by calling an object method on | |
22 | the FileHandle object. (Summary lines below for this contain the word | |
23 | HANDLE.) First you must say | |
24 | ||
25 | use FileHandle; | |
26 | ||
27 | after which you may use either | |
28 | ||
29 | method HANDLE EXPR | |
30 | ||
31 | or | |
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 LW |
44 | |
45 | =over 8 | |
46 | ||
47 | =item $ARG | |
48 | ||
49 | =item $_ | |
50 | ||
51 | The default input and pattern-searching space. The following pairs are | |
52 | equivalent: | |
53 | ||
5f05dabc | 54 | while (<>) {...} # equivalent in only while! |
a0d0e21e LW |
55 | while ($_ = <>) {...} |
56 | ||
57 | /^Subject:/ | |
58 | $_ =~ /^Subject:/ | |
59 | ||
60 | tr/a-z/A-Z/ | |
61 | $_ =~ tr/a-z/A-Z/ | |
62 | ||
63 | chop | |
64 | chop($_) | |
65 | ||
cb1a09d0 AD |
66 | Here are the places where Perl will assume $_ even if you |
67 | don't use it: | |
68 | ||
69 | =over 3 | |
70 | ||
71 | =item * | |
72 | ||
73 | Various unary functions, including functions like ord() and int(), as well | |
74 | as the all file tests (C<-f>, C<-d>) except for C<-t>, which defaults to | |
75 | STDIN. | |
76 | ||
77 | =item * | |
78 | ||
79 | Various list functions like print() and unlink(). | |
80 | ||
81 | =item * | |
82 | ||
83 | The pattern matching operations C<m//>, C<s///>, and C<tr///> when used | |
84 | without an C<=~> operator. | |
85 | ||
86 | =item * | |
87 | ||
88 | The default iterator variable in a C<foreach> loop if no other | |
89 | variable is supplied. | |
90 | ||
91 | =item * | |
92 | ||
93 | The implicit iterator variable in the grep() and map() functions. | |
94 | ||
95 | =item * | |
96 | ||
97 | The default place to put an input record when a C<E<lt>FHE<gt>> | |
98 | operation's result is tested by itself as the sole criterion of a C<while> | |
99 | test. Note that outside of a C<while> test, this will not happen. | |
100 | ||
101 | =back | |
102 | ||
a0d0e21e LW |
103 | (Mnemonic: underline is understood in certain operations.) |
104 | ||
6e2995f4 | 105 | =back |
106 | ||
107 | =over 8 | |
108 | ||
a8f8344d | 109 | =item $E<lt>I<digit>E<gt> |
a0d0e21e | 110 | |
5f05dabc | 111 | Contains the sub-pattern from the corresponding set of parentheses in |
a0d0e21e LW |
112 | the last pattern matched, not counting patterns matched in nested |
113 | blocks that have been exited already. (Mnemonic: like \digit.) | |
114 | These variables are all read-only. | |
115 | ||
116 | =item $MATCH | |
117 | ||
118 | =item $& | |
119 | ||
120 | The string matched by the last successful pattern match (not counting | |
121 | any matches hidden within a BLOCK or eval() enclosed by the current | |
122 | BLOCK). (Mnemonic: like & in some editors.) This variable is read-only. | |
123 | ||
124 | =item $PREMATCH | |
125 | ||
126 | =item $` | |
127 | ||
128 | The string preceding whatever was matched by the last successful | |
129 | pattern match (not counting any matches hidden within a BLOCK or eval | |
a8f8344d | 130 | enclosed by the current BLOCK). (Mnemonic: C<`> often precedes a quoted |
a0d0e21e LW |
131 | string.) This variable is read-only. |
132 | ||
133 | =item $POSTMATCH | |
134 | ||
135 | =item $' | |
136 | ||
137 | The string following whatever was matched by the last successful | |
138 | pattern match (not counting any matches hidden within a BLOCK or eval() | |
a8f8344d | 139 | enclosed by the current BLOCK). (Mnemonic: C<'> often follows a quoted |
a0d0e21e LW |
140 | string.) Example: |
141 | ||
142 | $_ = 'abcdefghi'; | |
143 | /def/; | |
144 | print "$`:$&:$'\n"; # prints abc:def:ghi | |
145 | ||
146 | This variable is read-only. | |
147 | ||
148 | =item $LAST_PAREN_MATCH | |
149 | ||
150 | =item $+ | |
151 | ||
152 | The last bracket matched by the last search pattern. This is useful if | |
153 | you don't know which of a set of alternative patterns matched. For | |
154 | example: | |
155 | ||
156 | /Version: (.*)|Revision: (.*)/ && ($rev = $+); | |
157 | ||
158 | (Mnemonic: be positive and forward looking.) | |
159 | This variable is read-only. | |
160 | ||
161 | =item $MULTILINE_MATCHING | |
162 | ||
163 | =item $* | |
164 | ||
5f05dabc | 165 | Set to 1 to do multi-line matching within a string, 0 to tell Perl |
a0d0e21e LW |
166 | that it can assume that strings contain a single line, for the purpose |
167 | of optimizing pattern matches. Pattern matches on strings containing | |
168 | multiple newlines can produce confusing results when "C<$*>" is 0. Default | |
169 | is 0. (Mnemonic: * matches multiple things.) Note that this variable | |
5f05dabc | 170 | influences the interpretation of only "C<^>" and "C<$>". A literal newline can |
a0d0e21e LW |
171 | be searched for even when C<$* == 0>. |
172 | ||
5f05dabc | 173 | Use of "C<$*>" is deprecated in modern perls. |
a0d0e21e LW |
174 | |
175 | =item input_line_number HANDLE EXPR | |
176 | ||
177 | =item $INPUT_LINE_NUMBER | |
178 | ||
179 | =item $NR | |
180 | ||
181 | =item $. | |
182 | ||
6e2995f4 | 183 | The current input line number for the last file handle from |
a8f8344d | 184 | which you read (or performed a C<seek> or C<tell> on). An |
5f05dabc | 185 | explicit close on a filehandle resets the line number. Because |
4633a7c4 LW |
186 | "C<E<lt>E<gt>>" never does an explicit close, line numbers increase |
187 | across ARGV files (but see examples under eof()). Localizing C<$.> has | |
188 | the effect of also localizing Perl's notion of "the last read | |
189 | filehandle". (Mnemonic: many programs use "." to mean the current line | |
190 | number.) | |
a0d0e21e LW |
191 | |
192 | =item input_record_separator HANDLE EXPR | |
193 | ||
194 | =item $INPUT_RECORD_SEPARATOR | |
195 | ||
196 | =item $RS | |
197 | ||
198 | =item $/ | |
199 | ||
200 | The input record separator, newline by default. Works like B<awk>'s RS | |
303f2f76 | 201 | variable, including treating empty lines as delimiters if set to the |
a8f8344d | 202 | null string. (Note: An empty line cannot contain any spaces or |
303f2f76 | 203 | tabs.) You may set it to a multicharacter string to match a |
a0d0e21e LW |
204 | multi-character delimiter. Note that setting it to C<"\n\n"> means |
205 | something slightly different than setting it to C<"">, if the file | |
303f2f76 | 206 | contains consecutive empty lines. Setting it to C<""> will treat two |
207 | or more consecutive empty lines as a single empty line. Setting it to | |
208 | C<"\n\n"> will blindly assume that the next input character belongs to | |
209 | the next paragraph, even if it's a newline. (Mnemonic: / is used to | |
a0d0e21e LW |
210 | delimit line boundaries when quoting poetry.) |
211 | ||
212 | undef $/; | |
213 | $_ = <FH>; # whole file now here | |
214 | s/\n[ \t]+/ /g; | |
215 | ||
216 | =item autoflush HANDLE EXPR | |
217 | ||
218 | =item $OUTPUT_AUTOFLUSH | |
219 | ||
220 | =item $| | |
221 | ||
222 | If set to nonzero, forces a flush after every write or print on the | |
6e2995f4 | 223 | currently selected output channel. Default is 0 (regardless of whether |
5f05dabc | 224 | the channel is actually buffered by the system or not; C<$|> tells you |
225 | only whether you've asked Perl explicitly to flush after each write). | |
6e2995f4 | 226 | Note that STDOUT will typically be line buffered if output is to the |
227 | terminal and block buffered otherwise. Setting this variable is useful | |
228 | primarily when you are outputting to a pipe, such as when you are running | |
229 | a Perl script under rsh and want to see the output as it's happening. This | |
230 | has no effect on input buffering. | |
cb1a09d0 | 231 | (Mnemonic: when you want your pipes to be piping hot.) |
a0d0e21e LW |
232 | |
233 | =item output_field_separator HANDLE EXPR | |
234 | ||
235 | =item $OUTPUT_FIELD_SEPARATOR | |
236 | ||
237 | =item $OFS | |
238 | ||
239 | =item $, | |
240 | ||
241 | The output field separator for the print operator. Ordinarily the | |
5f05dabc | 242 | print operator simply prints out the comma-separated fields you |
243 | specify. To get behavior more like B<awk>, set this variable | |
a0d0e21e LW |
244 | as you would set B<awk>'s OFS variable to specify what is printed |
245 | between fields. (Mnemonic: what is printed when there is a , in your | |
246 | print statement.) | |
247 | ||
248 | =item output_record_separator HANDLE EXPR | |
249 | ||
250 | =item $OUTPUT_RECORD_SEPARATOR | |
251 | ||
252 | =item $ORS | |
253 | ||
254 | =item $\ | |
255 | ||
256 | The output record separator for the print operator. Ordinarily the | |
5f05dabc | 257 | print operator simply prints out the comma-separated fields you |
258 | specify, with no trailing newline or record separator assumed. | |
259 | To get behavior more like B<awk>, set this variable as you would | |
a0d0e21e LW |
260 | set B<awk>'s ORS variable to specify what is printed at the end of the |
261 | print. (Mnemonic: you set "C<$\>" instead of adding \n at the end of the | |
a8f8344d | 262 | print. Also, it's just like C<$/>, but it's what you get "back" from |
a0d0e21e LW |
263 | Perl.) |
264 | ||
265 | =item $LIST_SEPARATOR | |
266 | ||
267 | =item $" | |
268 | ||
269 | This is like "C<$,>" except that it applies to array values interpolated | |
270 | into a double-quoted string (or similar interpreted string). Default | |
271 | is a space. (Mnemonic: obvious, I think.) | |
272 | ||
273 | =item $SUBSCRIPT_SEPARATOR | |
274 | ||
275 | =item $SUBSEP | |
276 | ||
277 | =item $; | |
278 | ||
279 | The subscript separator for multi-dimensional array emulation. If you | |
280 | refer to a hash element as | |
281 | ||
282 | $foo{$a,$b,$c} | |
283 | ||
284 | it really means | |
285 | ||
286 | $foo{join($;, $a, $b, $c)} | |
287 | ||
288 | But don't put | |
289 | ||
290 | @foo{$a,$b,$c} # a slice--note the @ | |
291 | ||
292 | which means | |
293 | ||
294 | ($foo{$a},$foo{$b},$foo{$c}) | |
295 | ||
296 | Default is "\034", the same as SUBSEP in B<awk>. Note that if your | |
297 | keys contain binary data there might not be any safe value for "C<$;>". | |
298 | (Mnemonic: comma (the syntactic subscript separator) is a | |
299 | semi-semicolon. Yeah, I know, it's pretty lame, but "C<$,>" is already | |
300 | taken for something more important.) | |
301 | ||
5f05dabc | 302 | Consider using "real" multi-dimensional arrays. |
a0d0e21e LW |
303 | |
304 | =item $OFMT | |
305 | ||
306 | =item $# | |
307 | ||
308 | The output format for printed numbers. This variable is a half-hearted | |
309 | attempt to emulate B<awk>'s OFMT variable. There are times, however, | |
310 | when B<awk> and Perl have differing notions of what is in fact | |
6e2995f4 | 311 | numeric. The initial value is %.I<n>g, where I<n> is the value |
312 | of the macro DBL_DIG from your system's F<float.h>. This is different from | |
313 | B<awk>'s default OFMT setting of %.6g, so you need to set "C<$#>" | |
314 | explicitly to get B<awk>'s value. (Mnemonic: # is the number sign.) | |
a0d0e21e | 315 | |
5f05dabc | 316 | Use of "C<$#>" is deprecated. |
a0d0e21e LW |
317 | |
318 | =item format_page_number HANDLE EXPR | |
319 | ||
320 | =item $FORMAT_PAGE_NUMBER | |
321 | ||
322 | =item $% | |
323 | ||
324 | The current page number of the currently selected output channel. | |
325 | (Mnemonic: % is page number in B<nroff>.) | |
326 | ||
327 | =item format_lines_per_page HANDLE EXPR | |
328 | ||
329 | =item $FORMAT_LINES_PER_PAGE | |
330 | ||
331 | =item $= | |
332 | ||
333 | The current page length (printable lines) of the currently selected | |
334 | output channel. Default is 60. (Mnemonic: = has horizontal lines.) | |
335 | ||
336 | =item format_lines_left HANDLE EXPR | |
337 | ||
338 | =item $FORMAT_LINES_LEFT | |
339 | ||
340 | =item $- | |
341 | ||
342 | The number of lines left on the page of the currently selected output | |
343 | channel. (Mnemonic: lines_on_page - lines_printed.) | |
344 | ||
345 | =item format_name HANDLE EXPR | |
346 | ||
347 | =item $FORMAT_NAME | |
348 | ||
349 | =item $~ | |
350 | ||
351 | The name of the current report format for the currently selected output | |
352 | channel. Default is name of the filehandle. (Mnemonic: brother to | |
353 | "C<$^>".) | |
354 | ||
355 | =item format_top_name HANDLE EXPR | |
356 | ||
357 | =item $FORMAT_TOP_NAME | |
358 | ||
359 | =item $^ | |
360 | ||
361 | The name of the current top-of-page format for the currently selected | |
362 | output channel. Default is name of the filehandle with _TOP | |
363 | appended. (Mnemonic: points to top of page.) | |
364 | ||
365 | =item format_line_break_characters HANDLE EXPR | |
366 | ||
367 | =item $FORMAT_LINE_BREAK_CHARACTERS | |
368 | ||
369 | =item $: | |
370 | ||
371 | The current set of characters after which a string may be broken to | |
372 | fill continuation fields (starting with ^) in a format. Default is | |
373 | S<" \n-">, to break on whitespace or hyphens. (Mnemonic: a "colon" in | |
374 | poetry is a part of a line.) | |
375 | ||
376 | =item format_formfeed HANDLE EXPR | |
377 | ||
378 | =item $FORMAT_FORMFEED | |
379 | ||
380 | =item $^L | |
381 | ||
5f05dabc | 382 | What formats output to perform a form feed. Default is \f. |
a0d0e21e LW |
383 | |
384 | =item $ACCUMULATOR | |
385 | ||
386 | =item $^A | |
387 | ||
388 | The current value of the write() accumulator for format() lines. A format | |
389 | contains formline() commands that put their result into C<$^A>. After | |
390 | calling its format, write() prints out the contents of C<$^A> and empties. | |
391 | So you never actually see the contents of C<$^A> unless you call | |
392 | formline() yourself and then look at it. See L<perlform> and | |
393 | L<perlfunc/formline()>. | |
394 | ||
395 | =item $CHILD_ERROR | |
396 | ||
397 | =item $? | |
398 | ||
5f05dabc | 399 | The status returned by the last pipe close, back-tick (C<``>) command, |
a0d0e21e LW |
400 | or system() operator. Note that this is the status word returned by |
401 | the wait() system call, so the exit value of the subprocess is actually | |
402 | (C<$? E<gt>E<gt> 8>). Thus on many systems, C<$? & 255> gives which signal, | |
403 | if any, the process died from, and whether there was a core dump. | |
404 | (Mnemonic: similar to B<sh> and B<ksh>.) | |
405 | ||
a8f8344d | 406 | Inside an C<END> subroutine C<$?> contains the value that is going to be |
407 | given to C<exit()>. You can modify C<$?> in an C<END> subroutine to | |
408 | change the exit status of the script. | |
409 | ||
a0d0e21e LW |
410 | =item $OS_ERROR |
411 | ||
412 | =item $ERRNO | |
413 | ||
414 | =item $! | |
415 | ||
416 | If used in a numeric context, yields the current value of errno, with | |
417 | all the usual caveats. (This means that you shouldn't depend on the | |
418 | value of "C<$!>" to be anything in particular unless you've gotten a | |
419 | specific error return indicating a system error.) If used in a string | |
420 | context, yields the corresponding system error string. You can assign | |
5f05dabc | 421 | to "C<$!>" to set I<errno> if, for instance, you want "C<$!>" to return the |
a0d0e21e LW |
422 | string for error I<n>, or you want to set the exit value for the die() |
423 | operator. (Mnemonic: What just went bang?) | |
424 | ||
5c055ba3 | 425 | =item $EXTENDED_OS_ERROR |
426 | ||
427 | =item $^E | |
428 | ||
429 | More specific information about the last system error than that | |
2c19844b IZ |
430 | provided by C<$!>, if available. (If not, it's just C<$!> again, except under |
431 | OS/2.) | |
5f05dabc | 432 | At the moment, this differs from C<$!> under only VMS and OS/2, where it |
2c19844b IZ |
433 | provides the VMS status value from the last system error, and OS/2 error |
434 | code of the last call to OS/2 API which was not directed via CRT. The | |
5c055ba3 | 435 | caveats mentioned in the description of C<$!> apply here, too. |
436 | (Mnemonic: Extra error explanation.) | |
437 | ||
2c19844b IZ |
438 | Note that under OS/2 C<$!> and C<$^E> do not track each other, so if an |
439 | OS/2-specific call is performed, you may need to check both. | |
5c055ba3 | 440 | |
a0d0e21e LW |
441 | =item $EVAL_ERROR |
442 | ||
443 | =item $@ | |
444 | ||
445 | The Perl syntax error message from the last eval() command. If null, the | |
446 | last eval() parsed and executed correctly (although the operations you | |
447 | invoked may have failed in the normal fashion). (Mnemonic: Where was | |
448 | the syntax error "at"?) | |
449 | ||
748a9306 | 450 | Note that warning messages are not collected in this variable. You can, |
a8f8344d | 451 | however, set up a routine to process warnings by setting C<$SIG{__WARN__}> |
452 | below. | |
748a9306 | 453 | |
a0d0e21e LW |
454 | =item $PROCESS_ID |
455 | ||
456 | =item $PID | |
457 | ||
458 | =item $$ | |
459 | ||
460 | The process number of the Perl running this script. (Mnemonic: same | |
461 | as shells.) | |
462 | ||
463 | =item $REAL_USER_ID | |
464 | ||
465 | =item $UID | |
466 | ||
467 | =item $< | |
468 | ||
469 | The real uid of this process. (Mnemonic: it's the uid you came I<FROM>, | |
470 | if you're running setuid.) | |
471 | ||
472 | =item $EFFECTIVE_USER_ID | |
473 | ||
474 | =item $EUID | |
475 | ||
476 | =item $> | |
477 | ||
478 | The effective uid of this process. Example: | |
479 | ||
480 | $< = $>; # set real to effective uid | |
481 | ($<,$>) = ($>,$<); # swap real and effective uid | |
482 | ||
483 | (Mnemonic: it's the uid you went I<TO>, if you're running setuid.) Note: | |
5f05dabc | 484 | "C<$E<lt>>" and "C<$E<gt>>" can be swapped on only machines supporting setreuid(). |
a0d0e21e LW |
485 | |
486 | =item $REAL_GROUP_ID | |
487 | ||
488 | =item $GID | |
489 | ||
490 | =item $( | |
491 | ||
492 | The real gid of this process. If you are on a machine that supports | |
493 | membership in multiple groups simultaneously, gives a space separated | |
494 | list of groups you are in. The first number is the one returned by | |
495 | getgid(), and the subsequent ones by getgroups(), one of which may be | |
496 | the same as the first number. (Mnemonic: parentheses are used to I<GROUP> | |
497 | things. The real gid is the group you I<LEFT>, if you're running setgid.) | |
498 | ||
499 | =item $EFFECTIVE_GROUP_ID | |
500 | ||
501 | =item $EGID | |
502 | ||
503 | =item $) | |
504 | ||
505 | The effective gid of this process. If you are on a machine that | |
506 | supports membership in multiple groups simultaneously, gives a space | |
507 | separated list of groups you are in. The first number is the one | |
508 | returned by getegid(), and the subsequent ones by getgroups(), one of | |
509 | which may be the same as the first number. (Mnemonic: parentheses are | |
510 | used to I<GROUP> things. The effective gid is the group that's I<RIGHT> for | |
511 | you, if you're running setgid.) | |
512 | ||
5f05dabc | 513 | Note: "C<$E<lt>>", "C<$E<gt>>", "C<$(>" and "C<$)>" can be set only on |
514 | machines that support the corresponding I<set[re][ug]id()> routine. "C<$(>" | |
515 | and "C<$)>" can be swapped on only machines supporting setregid(). Because | |
516 | Perl doesn't currently use initgroups(), you can't set your group vector to | |
517 | multiple groups. | |
a0d0e21e LW |
518 | |
519 | =item $PROGRAM_NAME | |
520 | ||
521 | =item $0 | |
522 | ||
523 | Contains the name of the file containing the Perl script being | |
524 | executed. Assigning to "C<$0>" modifies the argument area that the ps(1) | |
525 | program sees. This is more useful as a way of indicating the | |
526 | current program state than it is for hiding the program you're running. | |
527 | (Mnemonic: same as B<sh> and B<ksh>.) | |
528 | ||
529 | =item $[ | |
530 | ||
531 | The index of the first element in an array, and of the first character | |
532 | in a substring. Default is 0, but you could set it to 1 to make | |
533 | Perl behave more like B<awk> (or Fortran) when subscripting and when | |
534 | evaluating the index() and substr() functions. (Mnemonic: [ begins | |
535 | subscripts.) | |
536 | ||
537 | As of Perl 5, assignment to "C<$[>" is treated as a compiler directive, | |
538 | and cannot influence the behavior of any other file. Its use is | |
539 | discouraged. | |
540 | ||
541 | =item $PERL_VERSION | |
542 | ||
543 | =item $] | |
544 | ||
cb1a09d0 AD |
545 | The string printed out when you say C<perl -v>. |
546 | (This is currently I<BROKEN>). | |
547 | It can be used to | |
a0d0e21e LW |
548 | determine at the beginning of a script whether the perl interpreter |
549 | executing the script is in the right range of versions. If used in a | |
550 | numeric context, returns the version + patchlevel / 1000. Example: | |
551 | ||
552 | # see if getc is available | |
553 | ($version,$patchlevel) = | |
554 | $] =~ /(\d+\.\d+).*\nPatch level: (\d+)/; | |
555 | print STDERR "(No filename completion available.)\n" | |
556 | if $version * 1000 + $patchlevel < 2016; | |
557 | ||
558 | or, used numerically, | |
559 | ||
560 | warn "No checksumming!\n" if $] < 3.019; | |
561 | ||
562 | (Mnemonic: Is this version of perl in the right bracket?) | |
563 | ||
564 | =item $DEBUGGING | |
565 | ||
566 | =item $^D | |
567 | ||
568 | The current value of the debugging flags. (Mnemonic: value of B<-D> | |
569 | switch.) | |
570 | ||
571 | =item $SYSTEM_FD_MAX | |
572 | ||
573 | =item $^F | |
574 | ||
575 | The maximum system file descriptor, ordinarily 2. System file | |
576 | descriptors are passed to exec()ed processes, while higher file | |
577 | descriptors are not. Also, during an open(), system file descriptors are | |
578 | preserved even if the open() fails. (Ordinary file descriptors are | |
579 | closed before the open() is attempted.) Note that the close-on-exec | |
580 | status of a file descriptor will be decided according to the value of | |
581 | C<$^F> at the time of the open, not the time of the exec. | |
582 | ||
6e2995f4 | 583 | =item $^H |
584 | ||
585 | The current set of syntax checks enabled by C<use strict>. See the | |
586 | documentation of C<strict> for more details. | |
587 | ||
a0d0e21e LW |
588 | =item $INPLACE_EDIT |
589 | ||
590 | =item $^I | |
591 | ||
592 | The current value of the inplace-edit extension. Use C<undef> to disable | |
593 | inplace editing. (Mnemonic: value of B<-i> switch.) | |
594 | ||
5c055ba3 | 595 | =item $OSNAME |
6e2995f4 | 596 | |
5c055ba3 | 597 | =item $^O |
598 | ||
599 | The name of the operating system under which this copy of Perl was | |
600 | built, as determined during the configuration process. The value | |
601 | is identical to C<$Config{'osname'}>. | |
602 | ||
a0d0e21e LW |
603 | =item $PERLDB |
604 | ||
605 | =item $^P | |
606 | ||
607 | The internal flag that the debugger clears so that it doesn't debug | |
5c055ba3 | 608 | itself. You could conceivably disable debugging yourself by clearing |
a0d0e21e LW |
609 | it. |
610 | ||
611 | =item $BASETIME | |
612 | ||
613 | =item $^T | |
614 | ||
615 | The time at which the script began running, in seconds since the | |
5f05dabc | 616 | epoch (beginning of 1970). The values returned by the B<-M>, B<-A>, |
a0d0e21e LW |
617 | and B<-C> filetests are |
618 | based on this value. | |
619 | ||
620 | =item $WARNING | |
621 | ||
622 | =item $^W | |
623 | ||
303f2f76 | 624 | The current value of the warning switch, either TRUE or FALSE. |
625 | (Mnemonic: related to the B<-w> switch.) | |
a0d0e21e LW |
626 | |
627 | =item $EXECUTABLE_NAME | |
628 | ||
629 | =item $^X | |
630 | ||
631 | The name that the Perl binary itself was executed as, from C's C<argv[0]>. | |
632 | ||
633 | =item $ARGV | |
634 | ||
a8f8344d | 635 | contains the name of the current file when reading from E<lt>E<gt>. |
a0d0e21e LW |
636 | |
637 | =item @ARGV | |
638 | ||
639 | The array @ARGV contains the command line arguments intended for the | |
640 | script. Note that C<$#ARGV> is the generally number of arguments minus | |
5f05dabc | 641 | one, because C<$ARGV[0]> is the first argument, I<NOT> the command name. See |
a0d0e21e LW |
642 | "C<$0>" for the command name. |
643 | ||
644 | =item @INC | |
645 | ||
646 | The array @INC contains the list of places to look for Perl scripts to | |
647 | be evaluated by the C<do EXPR>, C<require>, or C<use> constructs. It | |
648 | initially consists of the arguments to any B<-I> command line switches, | |
6e2995f4 | 649 | followed by the default Perl library, probably F</usr/local/lib/perl>, |
cb1a09d0 | 650 | followed by ".", to represent the current directory. If you need to |
5f05dabc | 651 | modify this at runtime, you should use the C<use lib> pragma |
652 | to get the machine-dependent library properly loaded also: | |
a0d0e21e | 653 | |
cb1a09d0 AD |
654 | use lib '/mypath/libdir/'; |
655 | use SomeMod; | |
303f2f76 | 656 | |
a0d0e21e LW |
657 | =item %INC |
658 | ||
659 | The hash %INC contains entries for each filename that has | |
660 | been included via C<do> or C<require>. The key is the filename you | |
661 | specified, and the value is the location of the file actually found. | |
662 | The C<require> command uses this array to determine whether a given file | |
663 | has already been included. | |
664 | ||
665 | =item $ENV{expr} | |
666 | ||
667 | The hash %ENV contains your current environment. Setting a | |
668 | value in C<ENV> changes the environment for child processes. | |
669 | ||
670 | =item $SIG{expr} | |
671 | ||
672 | The hash %SIG is used to set signal handlers for various | |
673 | signals. Example: | |
674 | ||
675 | sub handler { # 1st argument is signal name | |
676 | local($sig) = @_; | |
677 | print "Caught a SIG$sig--shutting down\n"; | |
678 | close(LOG); | |
679 | exit(0); | |
680 | } | |
681 | ||
682 | $SIG{'INT'} = 'handler'; | |
683 | $SIG{'QUIT'} = 'handler'; | |
684 | ... | |
685 | $SIG{'INT'} = 'DEFAULT'; # restore default action | |
686 | $SIG{'QUIT'} = 'IGNORE'; # ignore SIGQUIT | |
687 | ||
5f05dabc | 688 | The %SIG array contains values for only the signals actually set within |
a0d0e21e LW |
689 | the Perl script. Here are some other examples: |
690 | ||
691 | $SIG{PIPE} = Plumber; # SCARY!! | |
692 | $SIG{"PIPE"} = "Plumber"; # just fine, assumes main::Plumber | |
693 | $SIG{"PIPE"} = \&Plumber; # just fine; assume current Plumber | |
694 | $SIG{"PIPE"} = Plumber(); # oops, what did Plumber() return?? | |
695 | ||
696 | The one marked scary is problematic because it's a bareword, which means | |
697 | sometimes it's a string representing the function, and sometimes it's | |
698 | going to call the subroutine call right then and there! Best to be sure | |
a8f8344d | 699 | and quote it or take a reference to it. *Plumber works too. See L<perlsub>. |
748a9306 | 700 | |
44a8e56a | 701 | If your system has the sigaction() function then signal handlers are |
702 | installed using it. This means you get reliable signal handling. If | |
703 | your system has the SA_RESTART flag it is used when signals handlers are | |
704 | installed. This means that system calls for which it is supported | |
705 | continue rather than returning when a signal arrives. If you want your | |
706 | system calls to be interrupted by signal delivery then do something like | |
707 | this: | |
708 | ||
709 | use POSIX ':signal_h'; | |
710 | ||
711 | my $alarm = 0; | |
712 | sigaction SIGALRM, new POSIX::SigAction sub { $alarm = 1 } | |
713 | or die "Error setting SIGALRM handler: $!\n"; | |
714 | ||
715 | See L<POSIX>. | |
716 | ||
748a9306 | 717 | Certain internal hooks can be also set using the %SIG hash. The |
a8f8344d | 718 | routine indicated by C<$SIG{__WARN__}> is called when a warning message is |
748a9306 LW |
719 | about to be printed. The warning message is passed as the first |
720 | argument. The presence of a __WARN__ hook causes the ordinary printing | |
721 | of warnings to STDERR to be suppressed. You can use this to save warnings | |
722 | in a variable, or turn warnings into fatal errors, like this: | |
723 | ||
724 | local $SIG{__WARN__} = sub { die $_[0] }; | |
725 | eval $proggie; | |
726 | ||
a8f8344d | 727 | The routine indicated by C<$SIG{__DIE__}> is called when a fatal exception |
748a9306 LW |
728 | is about to be thrown. The error message is passed as the first |
729 | argument. When a __DIE__ hook routine returns, the exception | |
730 | processing continues as it would have in the absence of the hook, | |
cb1a09d0 AD |
731 | unless the hook routine itself exits via a C<goto>, a loop exit, or a die(). |
732 | The __DIE__ handler is explicitly disabled during the call, so that you | |
733 | can die from a __DIE__ handler. Similarly for __WARN__. | |
a0d0e21e LW |
734 | |
735 | =back |