1PERLVAR(1) Perl Programmers Reference Guide PERLVAR(1)
2
6 perlvar - Perl predefined variables
7
9 Predefined Names
10 The following names have special meaning to Perl. Most punctuation
11 names have reasonable mnemonics, or analogs in the shells.
12 Nevertheless, if you wish to use long variable names, you need only say
13 use English;
15 at the top of your program. This aliases all the short names to the
17 long names in the current package. Some even have medium names,
18 generally borrowed from awk. In general, it's best to use the
19 use English '-no_match_vars';
21 invocation if you don't need $PREMATCH, $MATCH, or $POSTMATCH, as it
23 avoids a certain performance hit with the use of regular expressions.
24 See English.
25 Variables that depend on the currently selected filehandle may be set
27 by calling an appropriate object method on the IO::Handle object,
28 although this is less efficient than using the regular built-in
29 variables. (Summary lines below for this contain the word HANDLE.)
30 First you must say
31 use IO::Handle;
33 after which you may use either
35 method HANDLE EXPR
37 or more safely,
39 HANDLE->method(EXPR)
41 Each method returns the old value of the IO::Handle attribute. The
43 methods each take an optional EXPR, which, if supplied, specifies the
44 new value for the IO::Handle attribute in question. If not supplied,
45 most methods do nothing to the current value--except for autoflush(),
46 which will assume a 1 for you, just to be different.
47 Because loading in the IO::Handle class is an expensive operation, you
49 should learn how to use the regular built-in variables.
50 A few of these variables are considered "read-only". This means that
52 if you try to assign to this variable, either directly or indirectly
53 through a reference, you'll raise a run-time exception.
54 You should be very careful when modifying the default values of most
56 special variables described in this document. In most cases you want to
57 localize these variables before changing them, since if you don't, the
58 change may affect other modules which rely on the default values of the
59 special variables that you have changed. This is one of the correct
60 ways to read the whole file at once:
61 open my $fh, "<", "foo" or die $!;
63 local $/; # enable localized slurp mode
64 my $content = <$fh>;
65 close $fh;
66 But the following code is quite bad:
68 open my $fh, "<", "foo" or die $!;
70 undef $/; # enable slurp mode
71 my $content = <$fh>;
72 close $fh;
73 since some other module, may want to read data from some file in the
75 default "line mode", so if the code we have just presented has been
76 executed, the global value of $/ is now changed for any other code
77 running inside the same Perl interpreter.
78 Usually when a variable is localized you want to make sure that this
80 change affects the shortest scope possible. So unless you are already
81 inside some short "{}" block, you should create one yourself. For
82 example:
83 my $content = '';
85 open my $fh, "<", "foo" or die $!;
86 {
87 local $/;
88 $content = <$fh>;
89 }
90 close $fh;
91 Here is an example of how your own code can go broken:
93 for (1..5){
95 nasty_break();
96 print "$_ ";
97 }
98 sub nasty_break {
99 $_ = 5;
100 # do something with $_
101 }
102 You probably expect this code to print:
104 1 2 3 4 5
106 but instead you get:
108 5 5 5 5 5
110 Why? Because nasty_break() modifies $_ without localizing it first. The
112 fix is to add local():
113 local $_ = 5;
115 It's easy to notice the problem in such a short example, but in more
117 complicated code you are looking for trouble if you don't localize
118 changes to the special variables.
119 The following list is ordered by scalar variables first, then the
121 arrays, then the hashes.
122 $ARG
124 $_ The default input and pattern-searching space. The following
125 pairs are equivalent:
126 while (<>) {...} # equivalent only in while!
128 while (defined($_ = <>)) {...}
129 /^Subject:/
131 $_ =~ /^Subject:/
132 tr/a-z/A-Z/
134 $_ =~ tr/a-z/A-Z/
135 chomp
137 chomp($_)
138 Here are the places where Perl will assume $_ even if you don't
140 use it:
141 · The following functions:
143 abs, alarm, chomp, chop, chr, chroot, cos, defined, eval,
145 exp, glob, hex, int, lc, lcfirst, length, log, lstat, mkdir,
146 oct, ord, pos, print, quotemeta, readlink, readpipe, ref,
147 require, reverse (in scalar context only), rmdir, sin, split
148 (on its second argument), sqrt, stat, study, uc, ucfirst,
149 unlink, unpack.
150 · All file tests ("-f", "-d") except for "-t", which defaults
152 to STDIN. See "-X" in perlfunc
153 · The pattern matching operations "m//", "s///" and "tr///"
155 (aka "y///") when used without an "=~" operator.
156 · The default iterator variable in a "foreach" loop if no
158 other variable is supplied.
159 · The implicit iterator variable in the grep() and map()
161 functions.
162 · The implicit variable of given().
164 · The default place to put an input record when a "<FH>"
166 operation's result is tested by itself as the sole criterion
167 of a "while" test. Outside a "while" test, this will not
168 happen.
169 As $_ is a global variable, this may lead in some cases to
171 unwanted side-effects. As of perl 5.9.1, you can now use a
172 lexical version of $_ by declaring it in a file or in a block
173 with "my". Moreover, declaring "our $_" restores the global $_
174 in the current scope.
175 (Mnemonic: underline is understood in certain operations.)
177 $a
179 $b Special package variables when using sort(), see "sort" in
180 perlfunc. Because of this specialness $a and $b don't need to
181 be declared (using use vars, or our()) even when using the
182 "strict 'vars'" pragma. Don't lexicalize them with "my $a" or
183 "my $b" if you want to be able to use them in the sort()
184 comparison block or function.
185 $<digits>
187 Contains the subpattern from the corresponding set of capturing
188 parentheses from the last pattern match, not counting patterns
189 matched in nested blocks that have been exited already.
190 (Mnemonic: like \digits.) These variables are all read-only
191 and dynamically scoped to the current BLOCK.
192 $MATCH
194 $& The string matched by the last successful pattern match (not
195 counting any matches hidden within a BLOCK or eval() enclosed
196 by the current BLOCK). (Mnemonic: like & in some editors.)
197 This variable is read-only and dynamically scoped to the
198 current BLOCK.
199 The use of this variable anywhere in a program imposes a
201 considerable performance penalty on all regular expression
202 matches. See "BUGS".
203 See "@-" for a replacement.
205 ${^MATCH}
207 This is similar to $& ($MATCH) except that it does not incur
208 the performance penalty associated with that variable, and is
209 only guaranteed to return a defined value when the pattern was
210 compiled or executed with the "/p" modifier.
211 $PREMATCH
213 "$`" The string preceding whatever was matched by the last
214 successful pattern match (not counting any matches hidden
215 within a BLOCK or eval enclosed by the current BLOCK).
216 (Mnemonic: "`" often precedes a quoted string.) This variable
217 is read-only.
218 The use of this variable anywhere in a program imposes a
220 considerable performance penalty on all regular expression
221 matches. See "BUGS".
222 See "@-" for a replacement.
224 ${^PREMATCH}
226 This is similar to "$`" ($PREMATCH) except that it does not
227 incur the performance penalty associated with that variable,
228 and is only guaranteed to return a defined value when the
229 pattern was compiled or executed with the "/p" modifier.
230 $POSTMATCH
232 "$'" The string following whatever was matched by the last
233 successful pattern match (not counting any matches hidden
234 within a BLOCK or eval() enclosed by the current BLOCK).
235 (Mnemonic: "'" often follows a quoted string.) Example:
236 local $_ = 'abcdefghi';
238 /def/;
239 print "$`:$&:$'\n"; # prints abc:def:ghi
240 This variable is read-only and dynamically scoped to the
242 current BLOCK.
243 The use of this variable anywhere in a program imposes a
245 considerable performance penalty on all regular expression
246 matches. See "BUGS".
247 See "@-" for a replacement.
249 ${^POSTMATCH}
251 This is similar to "$'" ($POSTMATCH) except that it does not
252 incur the performance penalty associated with that variable,
253 and is only guaranteed to return a defined value when the
254 pattern was compiled or executed with the "/p" modifier.
255 $LAST_PAREN_MATCH
257 $+ The text matched by the last bracket of the last successful
258 search pattern. This is useful if you don't know which one of
259 a set of alternative patterns matched. For example:
260 /Version: (.*)|Revision: (.*)/ && ($rev = $+);
262 (Mnemonic: be positive and forward looking.) This variable is
264 read-only and dynamically scoped to the current BLOCK.
265 $LAST_SUBMATCH_RESULT
267 $^N The text matched by the used group most-recently closed (i.e.
268 the group with the rightmost closing parenthesis) of the last
269 successful search pattern. (Mnemonic: the (possibly) Nested
270 parenthesis that most recently closed.)
271 This is primarily used inside "(?{...})" blocks for examining
273 text recently matched. For example, to effectively capture text
274 to a variable (in addition to $1, $2, etc.), replace "(...)"
275 with
276 (?:(...)(?{ $var = $^N }))
278 By setting and then using $var in this way relieves you from
280 having to worry about exactly which numbered set of parentheses
281 they are.
282 This variable is dynamically scoped to the current BLOCK.
284 @LAST_MATCH_END
286 @+ This array holds the offsets of the ends of the last successful
287 submatches in the currently active dynamic scope. $+[0] is the
288 offset into the string of the end of the entire match. This is
289 the same value as what the "pos" function returns when called
290 on the variable that was matched against. The nth element of
291 this array holds the offset of the nth submatch, so $+[1] is
292 the offset past where $1 ends, $+[2] the offset past where $2
293 ends, and so on. You can use $#+ to determine how many
294 subgroups were in the last successful match. See the examples
295 given for the "@-" variable.
296 %LAST_PAREN_MATCH
298 %+ Similar to "@+", the "%+" hash allows access to the named
299 capture buffers, should they exist, in the last successful
300 match in the currently active dynamic scope.
301 For example, $+{foo} is equivalent to $1 after the following
303 match:
304 'foo' =~ /(?<foo>foo)/;
306 The keys of the "%+" hash list only the names of buffers that
308 have captured (and that are thus associated to defined values).
309 The underlying behaviour of "%+" is provided by the
311 Tie::Hash::NamedCapture module.
312 Note: "%-" and "%+" are tied views into a common internal hash
314 associated with the last successful regular expression.
315 Therefore mixing iterative access to them via "each" may have
316 unpredictable results. Likewise, if the last successful match
317 changes, then the results may be surprising.
318 HANDLE->input_line_number(EXPR)
320 $INPUT_LINE_NUMBER
321 $NR
322 $. Current line number for the last filehandle accessed.
323 Each filehandle in Perl counts the number of lines that have
325 been read from it. (Depending on the value of $/, Perl's idea
326 of what constitutes a line may not match yours.) When a line
327 is read from a filehandle (via readline() or "<>"), or when
328 tell() or seek() is called on it, $. becomes an alias to the
329 line counter for that filehandle.
330 You can adjust the counter by assigning to $., but this will
332 not actually move the seek pointer. Localizing $. will not
333 localize the filehandle's line count. Instead, it will
334 localize perl's notion of which filehandle $. is currently
335 aliased to.
336 $. is reset when the filehandle is closed, but not when an open
338 filehandle is reopened without an intervening close(). For
339 more details, see "I/O Operators" in perlop. Because "<>"
340 never does an explicit close, line numbers increase across ARGV
341 files (but see examples in "eof" in perlfunc).
342 You can also use "HANDLE->input_line_number(EXPR)" to access
344 the line counter for a given filehandle without having to worry
345 about which handle you last accessed.
346 (Mnemonic: many programs use "." to mean the current line
348 number.)
349 IO::Handle->input_record_separator(EXPR)
351 $INPUT_RECORD_SEPARATOR
352 $RS
353 $/ The input record separator, newline by default. This
354 influences Perl's idea of what a "line" is. Works like awk's
355 RS variable, including treating empty lines as a terminator if
356 set to the null string. (An empty line cannot contain any
357 spaces or tabs.) You may set it to a multi-character string to
358 match a multi-character terminator, or to "undef" to read
359 through the end of file. Setting it to "\n\n" means something
360 slightly different than setting to "", if the file contains
361 consecutive empty lines. Setting to "" will treat two or more
362 consecutive empty lines as a single empty line. Setting to
363 "\n\n" will blindly assume that the next input character
364 belongs to the next paragraph, even if it's a newline.
365 (Mnemonic: / delimits line boundaries when quoting poetry.)
366 local $/; # enable "slurp" mode
368 local $_ = <FH>; # whole file now here
369 s/\n[ \t]+/ /g;
370 Remember: the value of $/ is a string, not a regex. awk has to
372 be better for something. :-)
373 Setting $/ to a reference to an integer, scalar containing an
375 integer, or scalar that's convertible to an integer will
376 attempt to read records instead of lines, with the maximum
377 record size being the referenced integer. So this:
378 local $/ = \32768; # or \"32768", or \$var_containing_32768
380 open my $fh, "<", $myfile or die $!;
381 local $_ = <$fh>;
382 will read a record of no more than 32768 bytes from FILE. If
384 you're not reading from a record-oriented file (or your OS
385 doesn't have record-oriented files), then you'll likely get a
386 full chunk of data with every read. If a record is larger than
387 the record size you've set, you'll get the record back in
388 pieces. Trying to set the record size to zero or less will
389 cause reading in the (rest of the) whole file.
390 On VMS, record reads are done with the equivalent of "sysread",
392 so it's best not to mix record and non-record reads on the same
393 file. (This is unlikely to be a problem, because any file
394 you'd want to read in record mode is probably unusable in line
395 mode.) Non-VMS systems do normal I/O, so it's safe to mix
396 record and non-record reads of a file.
397 See also "Newlines" in perlport. Also see $..
399 HANDLE->autoflush(EXPR)
401 $OUTPUT_AUTOFLUSH
402 $| If set to nonzero, forces a flush right away and after every
403 write or print on the currently selected output channel.
404 Default is 0 (regardless of whether the channel is really
405 buffered by the system or not; $| tells you only whether you've
406 asked Perl explicitly to flush after each write). STDOUT will
407 typically be line buffered if output is to the terminal and
408 block buffered otherwise. Setting this variable is useful
409 primarily when you are outputting to a pipe or socket, such as
410 when you are running a Perl program under rsh and want to see
411 the output as it's happening. This has no effect on input
412 buffering. See "getc" in perlfunc for that. See "select" in
413 perldoc on how to select the output channel. See also
414 IO::Handle. (Mnemonic: when you want your pipes to be piping
415 hot.)
416 IO::Handle->output_field_separator EXPR
418 $OUTPUT_FIELD_SEPARATOR
419 $OFS
420 $, The output field separator for the print operator. If defined,
421 this value is printed between each of print's arguments.
422 Default is "undef". (Mnemonic: what is printed when there is a
423 "," in your print statement.)
424 IO::Handle->output_record_separator EXPR
426 $OUTPUT_RECORD_SEPARATOR
427 $ORS
428 $\ The output record separator for the print operator. If
429 defined, this value is printed after the last of print's
430 arguments. Default is "undef". (Mnemonic: you set "$\"
431 instead of adding "\n" at the end of the print. Also, it's
432 just like $/, but it's what you get "back" from Perl.)
433 $LIST_SEPARATOR
435 $" This is like $, except that it applies to array and slice
436 values interpolated into a double-quoted string (or similar
437 interpreted string). Default is a space. (Mnemonic: obvious,
438 I think.)
439 $SUBSCRIPT_SEPARATOR
441 $SUBSEP
442 $; The subscript separator for multidimensional array emulation.
443 If you refer to a hash element as
444 $foo{$a,$b,$c}
446 it really means
448 $foo{join($;, $a, $b, $c)}
450 But don't put
452 @foo{$a,$b,$c} # a slice--note the @
454 which means
456 ($foo{$a},$foo{$b},$foo{$c})
458 Default is "\034", the same as SUBSEP in awk. If your keys
460 contain binary data there might not be any safe value for $;.
461 (Mnemonic: comma (the syntactic subscript separator) is a semi-
462 semicolon. Yeah, I know, it's pretty lame, but $, is already
463 taken for something more important.)
464 Consider using "real" multidimensional arrays as described in
466 perllol.
467 HANDLE->format_page_number(EXPR)
469 $FORMAT_PAGE_NUMBER
470 $% The current page number of the currently selected output
471 channel. Used with formats. (Mnemonic: % is page number in
472 nroff.)
473 HANDLE->format_lines_per_page(EXPR)
475 $FORMAT_LINES_PER_PAGE
476 $= The current page length (printable lines) of the currently
477 selected output channel. Default is 60. Used with formats.
478 (Mnemonic: = has horizontal lines.)
479 HANDLE->format_lines_left(EXPR)
481 $FORMAT_LINES_LEFT
482 $- The number of lines left on the page of the currently selected
483 output channel. Used with formats. (Mnemonic: lines_on_page -
484 lines_printed.)
485 @LAST_MATCH_START
487 @- $-[0] is the offset of the start of the last successful match.
488 "$-["n"]" is the offset of the start of the substring matched
489 by n-th subpattern, or undef if the subpattern did not match.
490 Thus after a match against $_, $& coincides with "substr $_,
492 $-[0], $+[0] - $-[0]". Similarly, $n coincides with "substr
493 $_, $-[n], $+[n] - $-[n]" if "$-[n]" is defined, and $+
494 coincides with "substr $_, $-[$#-], $+[$#-] - $-[$#-]". One
495 can use "$#-" to find the last matched subgroup in the last
496 successful match. Contrast with $#+, the number of subgroups
497 in the regular expression. Compare with "@+".
498 This array holds the offsets of the beginnings of the last
500 successful submatches in the currently active dynamic scope.
501 "$-[0]" is the offset into the string of the beginning of the
502 entire match. The nth element of this array holds the offset
503 of the nth submatch, so "$-[1]" is the offset where $1 begins,
504 "$-[2]" the offset where $2 begins, and so on.
505 After a match against some variable $var:
507 "$`" is the same as "substr($var, 0, $-[0])"
509 $& is the same as "substr($var, $-[0], $+[0] - $-[0])"
510 "$'" is the same as "substr($var, $+[0])"
511 $1 is the same as "substr($var, $-[1], $+[1] - $-[1])"
512 $2 is the same as "substr($var, $-[2], $+[2] - $-[2])"
513 $3 is the same as "substr($var, $-[3], $+[3] - $-[3])"
514 %- Similar to "%+", this variable allows access to the named
515 capture buffers in the last successful match in the currently
516 active dynamic scope. To each capture buffer name found in the
517 regular expression, it associates a reference to an array
518 containing the list of values captured by all buffers with that
519 name (should there be several of them), in the order where they
520 appear.
521 Here's an example:
523 if ('1234' =~ /(?<A>1)(?<B>2)(?<A>3)(?<B>4)/) {
525 foreach my $bufname (sort keys %-) {
526 my $ary = $-{$bufname};
527 foreach my $idx (0..$#$ary) {
528 print "\$-{$bufname}[$idx] : ",
529 (defined($ary->[$idx]) ? "'$ary->[$idx]'" : "undef"),
530 "\n";
531 }
532 }
533 }
534 would print out:
536 $-{A}[0] : '1'
538 $-{A}[1] : '3'
539 $-{B}[0] : '2'
540 $-{B}[1] : '4'
541 The keys of the "%-" hash correspond to all buffer names found
543 in the regular expression.
544 The behaviour of "%-" is implemented via the
546 Tie::Hash::NamedCapture module.
547 Note: "%-" and "%+" are tied views into a common internal hash
549 associated with the last successful regular expression.
550 Therefore mixing iterative access to them via "each" may have
551 unpredictable results. Likewise, if the last successful match
552 changes, then the results may be surprising.
553 HANDLE->format_name(EXPR)
555 $FORMAT_NAME
556 $~ The name of the current report format for the currently
557 selected output channel. Default is the name of the
558 filehandle. (Mnemonic: brother to $^.)
559 HANDLE->format_top_name(EXPR)
561 $FORMAT_TOP_NAME
562 $^ The name of the current top-of-page format for the currently
563 selected output channel. Default is the name of the filehandle
564 with _TOP appended. (Mnemonic: points to top of page.)
565 IO::Handle->format_line_break_characters EXPR
567 $FORMAT_LINE_BREAK_CHARACTERS
568 $: The current set of characters after which a string may be
569 broken to fill continuation fields (starting with ^) in a
570 format. Default is " \n-", to break on whitespace or hyphens.
571 (Mnemonic: a "colon" in poetry is a part of a line.)
572 IO::Handle->format_formfeed EXPR
574 $FORMAT_FORMFEED
575 $^L What formats output as a form feed. Default is \f.
576 $ACCUMULATOR
578 $^A The current value of the write() accumulator for format()
579 lines. A format contains formline() calls that put their
580 result into $^A. After calling its format, write() prints out
581 the contents of $^A and empties. So you never really see the
582 contents of $^A unless you call formline() yourself and then
583 look at it. See perlform and "formline()" in perlfunc.
584 $CHILD_ERROR
586 $? The status returned by the last pipe close, backtick ("``")
587 command, successful call to wait() or waitpid(), or from the
588 system() operator. This is just the 16-bit status word
589 returned by the traditional Unix wait() system call (or else is
590 made up to look like it). Thus, the exit value of the
591 subprocess is really ("$? >> 8"), and "$? & 127" gives which
592 signal, if any, the process died from, and "$? & 128" reports
593 whether there was a core dump. (Mnemonic: similar to sh and
594 ksh.)
595 Additionally, if the "h_errno" variable is supported in C, its
597 value is returned via $? if any "gethost*()" function fails.
598 If you have installed a signal handler for "SIGCHLD", the value
600 of $? will usually be wrong outside that handler.
601 Inside an "END" subroutine $? contains the value that is going
603 to be given to "exit()". You can modify $? in an "END"
604 subroutine to change the exit status of your program. For
605 example:
606 END {
608 $? = 1 if $? == 255; # die would make it 255
609 }
610 Under VMS, the pragma "use vmsish 'status'" makes $? reflect
612 the actual VMS exit status, instead of the default emulation of
613 POSIX status; see "$?" in perlvms for details.
614 Also see "Error Indicators".
616 ${^CHILD_ERROR_NATIVE}
618 The native status returned by the last pipe close, backtick
619 ("``") command, successful call to wait() or waitpid(), or from
620 the system() operator. On POSIX-like systems this value can be
621 decoded with the WIFEXITED, WEXITSTATUS, WIFSIGNALED, WTERMSIG,
622 WIFSTOPPED, WSTOPSIG and WIFCONTINUED functions provided by the
623 POSIX module.
624 Under VMS this reflects the actual VMS exit status; i.e. it is
626 the same as $? when the pragma "use vmsish 'status'" is in
627 effect.
628 ${^ENCODING}
630 The object reference to the Encode object that is used to
631 convert the source code to Unicode. Thanks to this variable
632 your perl script does not have to be written in UTF-8. Default
633 is undef. The direct manipulation of this variable is highly
634 discouraged.
635 $OS_ERROR
637 $ERRNO
638 $! If used numerically, yields the current value of the C "errno"
639 variable, or in other words, if a system or library call fails,
640 it sets this variable. This means that the value of $! is
641 meaningful only immediately after a failure:
642 if (open my $fh, "<", $filename) {
644 # Here $! is meaningless.
645 ...
646 } else {
647 # ONLY here is $! meaningful.
648 ...
649 # Already here $! might be meaningless.
650 }
651 # Since here we might have either success or failure,
652 # here $! is meaningless.
653 In the above meaningless stands for anything: zero, non-zero,
655 "undef". A successful system or library call does not set the
656 variable to zero.
657 If used as a string, yields the corresponding system error
659 string. You can assign a number to $! to set errno if, for
660 instance, you want "$!" to return the string for error n, or
661 you want to set the exit value for the die() operator.
662 (Mnemonic: What just went bang?)
663 Also see "Error Indicators".
665 %OS_ERROR
667 %ERRNO
668 %! Each element of "%!" has a true value only if $! is set to that
669 value. For example, $!{ENOENT} is true if and only if the
670 current value of $! is "ENOENT"; that is, if the most recent
671 error was "No such file or directory" (or its moral equivalent:
672 not all operating systems give that exact error, and certainly
673 not all languages). To check if a particular key is meaningful
674 on your system, use "exists $!{the_key}"; for a list of legal
675 keys, use "keys %!". See Errno for more information, and also
676 see above for the validity of $!.
677 $EXTENDED_OS_ERROR
679 $^E Error information specific to the current operating system. At
680 the moment, this differs from $! under only VMS, OS/2, and
681 Win32 (and for MacPerl). On all other platforms, $^E is always
682 just the same as $!.
683 Under VMS, $^E provides the VMS status value from the last
685 system error. This is more specific information about the last
686 system error than that provided by $!. This is particularly
687 important when $! is set to EVMSERR.
688 Under OS/2, $^E is set to the error code of the last call to
690 OS/2 API either via CRT, or directly from perl.
691 Under Win32, $^E always returns the last error information
693 reported by the Win32 call "GetLastError()" which describes the
694 last error from within the Win32 API. Most Win32-specific code
695 will report errors via $^E. ANSI C and Unix-like calls set
696 "errno" and so most portable Perl code will report errors via
697 $!.
698 Caveats mentioned in the description of $! generally apply to
700 $^E, also. (Mnemonic: Extra error explanation.)
701 Also see "Error Indicators".
703 $EVAL_ERROR
705 $@ The Perl syntax error message from the last eval() operator.
706 If $@ is the null string, the last eval() parsed and executed
707 correctly (although the operations you invoked may have failed
708 in the normal fashion). (Mnemonic: Where was the syntax error
709 "at"?)
710 Warning messages are not collected in this variable. You can,
712 however, set up a routine to process warnings by setting
713 $SIG{__WARN__} as described below.
714 Also see "Error Indicators".
716 $PROCESS_ID
718 $PID
719 $$ The process number of the Perl running this script. You should
720 consider this variable read-only, although it will be altered
721 across fork() calls. (Mnemonic: same as shells.)
722 Note for Linux users: on Linux, the C functions "getpid()" and
724 "getppid()" return different values from different threads. In
725 order to be portable, this behavior is not reflected by $$,
726 whose value remains consistent across threads. If you want to
727 call the underlying "getpid()", you may use the CPAN module
728 "Linux::Pid".
729 $REAL_USER_ID
731 $UID
732 $< The real uid of this process. (Mnemonic: it's the uid you came
733 from, if you're running setuid.) You can change both the real
734 uid and the effective uid at the same time by using
735 POSIX::setuid(). Since changes to $< require a system call,
736 check $! after a change attempt to detect any possible errors.
737 $EFFECTIVE_USER_ID
739 $EUID
740 $> The effective uid of this process. Example:
741 $< = $>; # set real to effective uid
743 ($<,$>) = ($>,$<); # swap real and effective uid
744 You can change both the effective uid and the real uid at the
746 same time by using POSIX::setuid(). Changes to $> require a
747 check to $! to detect any possible errors after an attempted
748 change.
749 (Mnemonic: it's the uid you went to, if you're running setuid.)
751 $< and $> can be swapped only on machines supporting
752 setreuid().
753 $REAL_GROUP_ID
755 $GID
756 $( The real gid of this process. If you are on a machine that
757 supports membership in multiple groups simultaneously, gives a
758 space separated list of groups you are in. The first number is
759 the one returned by getgid(), and the subsequent ones by
760 getgroups(), one of which may be the same as the first number.
761 However, a value assigned to $( must be a single number used to
763 set the real gid. So the value given by $( should not be
764 assigned back to $( without being forced numeric, such as by
765 adding zero. Note that this is different to the effective gid
766 ($)) which does take a list.
767 You can change both the real gid and the effective gid at the
769 same time by using POSIX::setgid(). Changes to $( require a
770 check to $! to detect any possible errors after an attempted
771 change.
772 (Mnemonic: parentheses are used to group things. The real gid
774 is the group you left, if you're running setgid.)
775 $EFFECTIVE_GROUP_ID
777 $EGID
778 $) The effective gid of this process. If you are on a machine
779 that supports membership in multiple groups simultaneously,
780 gives a space separated list of groups you are in. The first
781 number is the one returned by getegid(), and the subsequent
782 ones by getgroups(), one of which may be the same as the first
783 number.
784 Similarly, a value assigned to $) must also be a space-
786 separated list of numbers. The first number sets the effective
787 gid, and the rest (if any) are passed to setgroups(). To get
788 the effect of an empty list for setgroups(), just repeat the
789 new effective gid; that is, to force an effective gid of 5 and
790 an effectively empty setgroups() list, say " $) = "5 5" ".
791 You can change both the effective gid and the real gid at the
793 same time by using POSIX::setgid() (use only a single numeric
794 argument). Changes to $) require a check to $! to detect any
795 possible errors after an attempted change.
796 (Mnemonic: parentheses are used to group things. The effective
798 gid is the group that's right for you, if you're running
799 setgid.)
800 $<, $>, $( and $) can be set only on machines that support the
802 corresponding set[re][ug]id() routine. $( and $) can be
803 swapped only on machines supporting setregid().
804 $PROGRAM_NAME
806 $0 Contains the name of the program being executed.
807 On some (read: not all) operating systems assigning to $0
809 modifies the argument area that the "ps" program sees. On some
810 platforms you may have to use special "ps" options or a
811 different "ps" to see the changes. Modifying the $0 is more
812 useful as a way of indicating the current program state than it
813 is for hiding the program you're running. (Mnemonic: same as
814 sh and ksh.)
815 Note that there are platform specific limitations on the
817 maximum length of $0. In the most extreme case it may be
818 limited to the space occupied by the original $0.
819 In some platforms there may be arbitrary amount of padding, for
821 example space characters, after the modified name as shown by
822 "ps". In some platforms this padding may extend all the way to
823 the original length of the argument area, no matter what you do
824 (this is the case for example with Linux 2.2).
825 Note for BSD users: setting $0 does not completely remove
827 "perl" from the ps(1) output. For example, setting $0 to
828 "foobar" may result in "perl: foobar (perl)" (whether both the
829 "perl: " prefix and the " (perl)" suffix are shown depends on
830 your exact BSD variant and version). This is an operating
831 system feature, Perl cannot help it.
832 In multithreaded scripts Perl coordinates the threads so that
834 any thread may modify its copy of the $0 and the change becomes
835 visible to ps(1) (assuming the operating system plays along).
836 Note that the view of $0 the other threads have will not change
837 since they have their own copies of it.
838 If the program has been given to perl via the switches "-e" or
840 "-E", $0 will contain the string "-e".
841 $[ The index of the first element in an array, and of the first
843 character in a substring. Default is 0, but you could
844 theoretically set it to 1 to make Perl behave more like awk (or
845 Fortran) when subscripting and when evaluating the index() and
846 substr() functions. (Mnemonic: [ begins subscripts.)
847 As of release 5 of Perl, assignment to $[ is treated as a
849 compiler directive, and cannot influence the behavior of any
850 other file. (That's why you can only assign compile-time
851 constants to it.) Its use is highly discouraged.
852 Note that, unlike other compile-time directives (such as
854 strict), assignment to $[ can be seen from outer lexical scopes
855 in the same file. However, you can use local() on it to
856 strictly bind its value to a lexical block.
857 $] The version + patchlevel / 1000 of the Perl interpreter. This
859 variable can be used to determine whether the Perl interpreter
860 executing a script is in the right range of versions.
861 (Mnemonic: Is this version of perl in the right bracket?)
862 Example:
863 warn "No checksumming!\n" if $] < 3.019;
865 See also the documentation of "use VERSION" and "require
867 VERSION" for a convenient way to fail if the running Perl
868 interpreter is too old.
869 The floating point representation can sometimes lead to
871 inaccurate numeric comparisons. See $^V for a more modern
872 representation of the Perl version that allows accurate string
873 comparisons.
874 $COMPILING
876 $^C The current value of the flag associated with the -c switch.
877 Mainly of use with -MO=... to allow code to alter its behavior
878 when being compiled, such as for example to AUTOLOAD at compile
879 time rather than normal, deferred loading. Setting "$^C = 1"
880 is similar to calling "B::minus_c".
881 $DEBUGGING
883 $^D The current value of the debugging flags. (Mnemonic: value of
884 -D switch.) May be read or set. Like its command-line
885 equivalent, you can use numeric or symbolic values, eg "$^D =
886 10" or "$^D = "st"".
887 ${^RE_DEBUG_FLAGS}
889 The current value of the regex debugging flags. Set to 0 for no
890 debug output even when the re 'debug' module is loaded. See re
891 for details.
892 ${^RE_TRIE_MAXBUF}
894 Controls how certain regex optimisations are applied and how
895 much memory they utilize. This value by default is 65536 which
896 corresponds to a 512kB temporary cache. Set this to a higher
897 value to trade memory for speed when matching large
898 alternations. Set it to a lower value if you want the
899 optimisations to be as conservative of memory as possible but
900 still occur, and set it to a negative value to prevent the
901 optimisation and conserve the most memory. Under normal
902 situations this variable should be of no interest to you.
903 $SYSTEM_FD_MAX
905 $^F The maximum system file descriptor, ordinarily 2. System file
906 descriptors are passed to exec()ed processes, while higher file
907 descriptors are not. Also, during an open(), system file
908 descriptors are preserved even if the open() fails. (Ordinary
909 file descriptors are closed before the open() is attempted.)
910 The close-on-exec status of a file descriptor will be decided
911 according to the value of $^F when the corresponding file,
912 pipe, or socket was opened, not the time of the exec().
913 $^H WARNING: This variable is strictly for internal use only. Its
915 availability, behavior, and contents are subject to change
916 without notice.
917 This variable contains compile-time hints for the Perl
919 interpreter. At the end of compilation of a BLOCK the value of
920 this variable is restored to the value when the interpreter
921 started to compile the BLOCK.
922 When perl begins to parse any block construct that provides a
924 lexical scope (e.g., eval body, required file, subroutine body,
925 loop body, or conditional block), the existing value of $^H is
926 saved, but its value is left unchanged. When the compilation
927 of the block is completed, it regains the saved value. Between
928 the points where its value is saved and restored, code that
929 executes within BEGIN blocks is free to change the value of
930 $^H.
931 This behavior provides the semantic of lexical scoping, and is
933 used in, for instance, the "use strict" pragma.
934 The contents should be an integer; different bits of it are
936 used for different pragmatic flags. Here's an example:
937 sub add_100 { $^H |= 0x100 }
939 sub foo {
941 BEGIN { add_100() }
942 bar->baz($boon);
943 }
944 Consider what happens during execution of the BEGIN block. At
946 this point the BEGIN block has already been compiled, but the
947 body of foo() is still being compiled. The new value of $^H
948 will therefore be visible only while the body of foo() is being
949 compiled.
950 Substitution of the above BEGIN block with:
952 BEGIN { require strict; strict->import('vars') }
954 demonstrates how "use strict 'vars'" is implemented. Here's a
956 conditional version of the same lexical pragma:
957 BEGIN { require strict; strict->import('vars') if $condition }
959 %^H The %^H hash provides the same scoping semantic as $^H. This
961 makes it useful for implementation of lexically scoped pragmas.
962 See perlpragma.
963 $INPLACE_EDIT
965 $^I The current value of the inplace-edit extension. Use "undef"
966 to disable inplace editing. (Mnemonic: value of -i switch.)
967 $^M By default, running out of memory is an untrappable, fatal
969 error. However, if suitably built, Perl can use the contents
970 of $^M as an emergency memory pool after die()ing. Suppose
971 that your Perl were compiled with "-DPERL_EMERGENCY_SBRK" and
972 used Perl's malloc. Then
973 $^M = 'a' x (1 << 16);
975 would allocate a 64K buffer for use in an emergency. See the
977 INSTALL file in the Perl distribution for information on how to
978 add custom C compilation flags when compiling perl. To
979 discourage casual use of this advanced feature, there is no
980 English long name for this variable.
981 $OSNAME
983 $^O The name of the operating system under which this copy of Perl
984 was built, as determined during the configuration process. The
985 value is identical to $Config{'osname'}. See also Config and
986 the -V command-line switch documented in perlrun.
987 In Windows platforms, $^O is not very helpful: since it is
989 always "MSWin32", it doesn't tell the difference between
990 95/98/ME/NT/2000/XP/CE/.NET. Use Win32::GetOSName() or
991 Win32::GetOSVersion() (see Win32 and perlport) to distinguish
992 between the variants.
993 ${^OPEN}
995 An internal variable used by PerlIO. A string in two parts,
996 separated by a "\0" byte, the first part describes the input
997 layers, the second part describes the output layers.
998 $PERLDB
1000 $^P The internal variable for debugging support. The meanings of
1001 the various bits are subject to change, but currently indicate:
1002 0x01 Debug subroutine enter/exit.
1004 0x02 Line-by-line debugging. Causes DB::DB() subroutine to be
1006 called for each statement executed. Also causes saving
1007 source code lines (like 0x400).
1008 0x04 Switch off optimizations.
1010 0x08 Preserve more data for future interactive inspections.
1012 0x10 Keep info about source lines on which a subroutine is
1014 defined.
1015 0x20 Start with single-step on.
1017 0x40 Use subroutine address instead of name when reporting.
1019 0x80 Report "goto &subroutine" as well.
1021 0x100 Provide informative "file" names for evals based on the
1023 place they were compiled.
1024 0x200 Provide informative names to anonymous subroutines based
1026 on the place they were compiled.
1027 0x400 Save source code lines into "@{"_<$filename"}".
1029 Some bits may be relevant at compile-time only, some at run-
1031 time only. This is a new mechanism and the details may change.
1032 See also perldebguts.
1033 $LAST_REGEXP_CODE_RESULT
1035 $^R The result of evaluation of the last successful "(?{ code })"
1036 regular expression assertion (see perlre). May be written to.
1037 $EXCEPTIONS_BEING_CAUGHT
1039 $^S Current state of the interpreter.
1040 $^S State
1042 --------- -------------------
1043 undef Parsing module/eval
1044 true (1) Executing an eval
1045 false (0) Otherwise
1046 The first state may happen in $SIG{__DIE__} and $SIG{__WARN__}
1048 handlers.
1049 $BASETIME
1051 $^T The time at which the program began running, in seconds since
1052 the epoch (beginning of 1970). The values returned by the -M,
1053 -A, and -C filetests are based on this value.
1054 ${^TAINT}
1056 Reflects if taint mode is on or off. 1 for on (the program was
1057 run with -T), 0 for off, -1 when only taint warnings are
1058 enabled (i.e. with -t or -TU). This variable is read-only.
1059 ${^UNICODE}
1061 Reflects certain Unicode settings of Perl. See perlrun
1062 documentation for the "-C" switch for more information about
1063 the possible values. This variable is set during Perl startup
1064 and is thereafter read-only.
1065 ${^UTF8CACHE}
1067 This variable controls the state of the internal UTF-8 offset
1068 caching code. 1 for on (the default), 0 for off, -1 to debug
1069 the caching code by checking all its results against linear
1070 scans, and panicking on any discrepancy.
1071 ${^UTF8LOCALE}
1073 This variable indicates whether an UTF-8 locale was detected by
1074 perl at startup. This information is used by perl when it's in
1075 adjust-utf8ness-to-locale mode (as when run with the "-CL"
1076 command-line switch); see perlrun for more info on this.
1077 $PERL_VERSION
1079 $^V The revision, version, and subversion of the Perl interpreter,
1080 represented as a "version" object.
1081 This variable first appeared in perl 5.6.0; earlier versions of
1083 perl will see an undefined value. Before perl 5.10.0 $^V was
1084 represented as a v-string.
1085 $^V can be used to determine whether the Perl interpreter
1087 executing a script is in the right range of versions.
1088 (Mnemonic: use ^V for Version Control.) Example:
1089 warn "Hashes not randomized!\n" if !$^V or $^V lt v5.8.1
1091 To convert $^V into its string representation use sprintf()'s
1093 "%vd" conversion:
1094 printf "version is v%vd\n", $^V; # Perl's version
1096 See the documentation of "use VERSION" and "require VERSION"
1098 for a convenient way to fail if the running Perl interpreter is
1099 too old.
1100 See also $] for an older representation of the Perl version.
1102 $WARNING
1104 $^W The current value of the warning switch, initially true if -w
1105 was used, false otherwise, but directly modifiable. (Mnemonic:
1106 related to the -w switch.) See also warnings.
1107 ${^WARNING_BITS}
1109 The current set of warning checks enabled by the "use warnings"
1110 pragma. See the documentation of "warnings" for more details.
1111 ${^WIN32_SLOPPY_STAT}
1113 If this variable is set to a true value, then stat() on Windows
1114 will not try to open the file. This means that the link count
1115 cannot be determined and file attributes may be out of date if
1116 additional hardlinks to the file exist. On the other hand, not
1117 opening the file is considerably faster, especially for files
1118 on network drives.
1119 This variable could be set in the sitecustomize.pl file to
1121 configure the local Perl installation to use "sloppy" stat() by
1122 default. See perlrun for more information about site
1123 customization.
1124 $EXECUTABLE_NAME
1126 $^X The name used to execute the current copy of Perl, from C's
1127 "argv[0]" or (where supported) /proc/self/exe.
1128 Depending on the host operating system, the value of $^X may be
1130 a relative or absolute pathname of the perl program file, or
1131 may be the string used to invoke perl but not the pathname of
1132 the perl program file. Also, most operating systems permit
1133 invoking programs that are not in the PATH environment
1134 variable, so there is no guarantee that the value of $^X is in
1135 PATH. For VMS, the value may or may not include a version
1136 number.
1137 You usually can use the value of $^X to re-invoke an
1139 independent copy of the same perl that is currently running,
1140 e.g.,
1141 @first_run = `$^X -le "print int rand 100 for 1..100"`;
1143 But recall that not all operating systems support forking or
1145 capturing of the output of commands, so this complex statement
1146 may not be portable.
1147 It is not safe to use the value of $^X as a path name of a
1149 file, as some operating systems that have a mandatory suffix on
1150 executable files do not require use of the suffix when invoking
1151 a command. To convert the value of $^X to a path name, use the
1152 following statements:
1153 # Build up a set of file names (not command names).
1155 use Config;
1156 $this_perl = $^X;
1157 if ($^O ne 'VMS')
1158 {$this_perl .= $Config{_exe}
1159 unless $this_perl =~ m/$Config{_exe}$/i;}
1160 Because many operating systems permit anyone with read access
1162 to the Perl program file to make a copy of it, patch the copy,
1163 and then execute the copy, the security-conscious Perl
1164 programmer should take care to invoke the installed copy of
1165 perl, not the copy referenced by $^X. The following statements
1166 accomplish this goal, and produce a pathname that can be
1167 invoked as a command or referenced as a file.
1168 use Config;
1170 $secure_perl_path = $Config{perlpath};
1171 if ($^O ne 'VMS')
1172 {$secure_perl_path .= $Config{_exe}
1173 unless $secure_perl_path =~ m/$Config{_exe}$/i;}
1174 ARGV The special filehandle that iterates over command-line
1176 filenames in @ARGV. Usually written as the null filehandle in
1177 the angle operator "<>". Note that currently "ARGV" only has
1178 its magical effect within the "<>" operator; elsewhere it is
1179 just a plain filehandle corresponding to the last file opened
1180 by "<>". In particular, passing "\*ARGV" as a parameter to a
1181 function that expects a filehandle may not cause your function
1182 to automatically read the contents of all the files in @ARGV.
1183 $ARGV contains the name of the current file when reading from <>.
1185 @ARGV The array @ARGV contains the command-line arguments intended
1187 for the script. $#ARGV is generally the number of arguments
1188 minus one, because $ARGV[0] is the first argument, not the
1189 program's command name itself. See $0 for the command name.
1190 ARGVOUT The special filehandle that points to the currently open output
1192 file when doing edit-in-place processing with -i. Useful when
1193 you have to do a lot of inserting and don't want to keep
1194 modifying $_. See perlrun for the -i switch.
1195 @F The array @F contains the fields of each line read in when
1197 autosplit mode is turned on. See perlrun for the -a switch.
1198 This array is package-specific, and must be declared or given a
1199 full package name if not in package main when running under
1200 "strict 'vars'".
1201 @INC The array @INC contains the list of places that the "do EXPR",
1203 "require", or "use" constructs look for their library files.
1204 It initially consists of the arguments to any -I command-line
1205 switches, followed by the default Perl library, probably
1206 /usr/local/lib/perl, followed by ".", to represent the current
1207 directory. ("." will not be appended if taint checks are
1208 enabled, either by "-T" or by "-t".) If you need to modify
1209 this at runtime, you should use the "use lib" pragma to get the
1210 machine-dependent library properly loaded also:
1211 use lib '/mypath/libdir/';
1213 use SomeMod;
1214 You can also insert hooks into the file inclusion system by
1216 putting Perl code directly into @INC. Those hooks may be
1217 subroutine references, array references or blessed objects.
1218 See "require" in perlfunc for details.
1219 @ARG
1221 @_ Within a subroutine the array @_ contains the parameters passed
1222 to that subroutine. See perlsub.
1223 %INC The hash %INC contains entries for each filename included via
1225 the "do", "require", or "use" operators. The key is the
1226 filename you specified (with module names converted to
1227 pathnames), and the value is the location of the file found.
1228 The "require" operator uses this hash to determine whether a
1229 particular file has already been included.
1230 If the file was loaded via a hook (e.g. a subroutine reference,
1232 see "require" in perlfunc for a description of these hooks),
1233 this hook is by default inserted into %INC in place of a
1234 filename. Note, however, that the hook may have set the %INC
1235 entry by itself to provide some more specific info.
1236 %ENV
1238 $ENV{expr}
1239 The hash %ENV contains your current environment. Setting a
1240 value in "ENV" changes the environment for any child processes
1241 you subsequently fork() off.
1242 %SIG
1244 $SIG{expr}
1245 The hash %SIG contains signal handlers for signals. For
1246 example:
1247 sub handler { # 1st argument is signal name
1249 my($sig) = @_;
1250 print "Caught a SIG$sig--shutting down\n";
1251 close(LOG);
1252 exit(0);
1253 }
1254 $SIG{'INT'} = \&handler;
1256 $SIG{'QUIT'} = \&handler;
1257 ...
1258 $SIG{'INT'} = 'DEFAULT'; # restore default action
1259 $SIG{'QUIT'} = 'IGNORE'; # ignore SIGQUIT
1260 Using a value of 'IGNORE' usually has the effect of ignoring
1262 the signal, except for the "CHLD" signal. See perlipc for more
1263 about this special case.
1264 Here are some other examples:
1266 $SIG{"PIPE"} = "Plumber"; # assumes main::Plumber (not recommended)
1268 $SIG{"PIPE"} = \&Plumber; # just fine; assume current Plumber
1269 $SIG{"PIPE"} = *Plumber; # somewhat esoteric
1270 $SIG{"PIPE"} = Plumber(); # oops, what did Plumber() return??
1271 Be sure not to use a bareword as the name of a signal handler,
1273 lest you inadvertently call it.
1274 If your system has the sigaction() function then signal
1276 handlers are installed using it. This means you get reliable
1277 signal handling.
1278 The default delivery policy of signals changed in Perl 5.8.0
1280 from immediate (also known as "unsafe") to deferred, also known
1281 as "safe signals". See perlipc for more information.
1282 Certain internal hooks can be also set using the %SIG hash.
1284 The routine indicated by $SIG{__WARN__} is called when a
1285 warning message is about to be printed. The warning message is
1286 passed as the first argument. The presence of a "__WARN__"
1287 hook causes the ordinary printing of warnings to "STDERR" to be
1288 suppressed. You can use this to save warnings in a variable,
1289 or turn warnings into fatal errors, like this:
1290 local $SIG{__WARN__} = sub { die $_[0] };
1292 eval $proggie;
1293 As the 'IGNORE' hook is not supported by "__WARN__", you can
1295 disable warnings using the empty subroutine:
1296 local $SIG{__WARN__} = sub {};
1298 The routine indicated by $SIG{__DIE__} is called when a fatal
1300 exception is about to be thrown. The error message is passed
1301 as the first argument. When a "__DIE__" hook routine returns,
1302 the exception processing continues as it would have in the
1303 absence of the hook, unless the hook routine itself exits via a
1304 "goto", a loop exit, or a "die()". The "__DIE__" handler is
1305 explicitly disabled during the call, so that you can die from a
1306 "__DIE__" handler. Similarly for "__WARN__".
1307 Due to an implementation glitch, the $SIG{__DIE__} hook is
1309 called even inside an eval(). Do not use this to rewrite a
1310 pending exception in $@, or as a bizarre substitute for
1311 overriding "CORE::GLOBAL::die()". This strange action at a
1312 distance may be fixed in a future release so that $SIG{__DIE__}
1313 is only called if your program is about to exit, as was the
1314 original intent. Any other use is deprecated.
1315 "__DIE__"/"__WARN__" handlers are very special in one respect:
1317 they may be called to report (probable) errors found by the
1318 parser. In such a case the parser may be in inconsistent
1319 state, so any attempt to evaluate Perl code from such a handler
1320 will probably result in a segfault. This means that warnings
1321 or errors that result from parsing Perl should be used with
1322 extreme caution, like this:
1323 require Carp if defined $^S;
1325 Carp::confess("Something wrong") if defined &Carp::confess;
1326 die "Something wrong, but could not load Carp to give backtrace...
1327 To see backtrace try starting Perl with -MCarp switch";
1328 Here the first line will load Carp unless it is the parser who
1330 called the handler. The second line will print backtrace and
1331 die if Carp was available. The third line will be executed
1332 only if Carp was not available.
1333 See "die" in perlfunc, "warn" in perlfunc, "eval" in perlfunc,
1335 and warnings for additional information.
1336 Error Indicators
1338 The variables $@, $!, $^E, and $? contain information about different
1339 types of error conditions that may appear during execution of a Perl
1340 program. The variables are shown ordered by the "distance" between the
1341 subsystem which reported the error and the Perl process. They
1342 correspond to errors detected by the Perl interpreter, C library,
1343 operating system, or an external program, respectively.
1344 To illustrate the differences between these variables, consider the
1346 following Perl expression, which uses a single-quoted string:
1347 eval q{
1349 open my $pipe, "/cdrom/install |" or die $!;
1350 my @res = <$pipe>;
1351 close $pipe or die "bad pipe: $?, $!";
1352 };
1353 After execution of this statement all 4 variables may have been set.
1355 $@ is set if the string to be "eval"-ed did not compile (this may
1357 happen if "open" or "close" were imported with bad prototypes), or if
1358 Perl code executed during evaluation die()d . In these cases the value
1359 of $@ is the compile error, or the argument to "die" (which will
1360 interpolate $! and $?). (See also Fatal, though.)
1361 When the eval() expression above is executed, open(), "<PIPE>", and
1363 "close" are translated to calls in the C run-time library and thence to
1364 the operating system kernel. $! is set to the C library's "errno" if
1365 one of these calls fails.
1366 Under a few operating systems, $^E may contain a more verbose error
1368 indicator, such as in this case, "CDROM tray not closed." Systems that
1369 do not support extended error messages leave $^E the same as $!.
1370 Finally, $? may be set to non-0 value if the external program
1372 /cdrom/install fails. The upper eight bits reflect specific error
1373 conditions encountered by the program (the program's exit() value).
1374 The lower eight bits reflect mode of failure, like signal death and
1375 core dump information See wait(2) for details. In contrast to $! and
1376 $^E, which are set only if error condition is detected, the variable $?
1377 is set on each "wait" or pipe "close", overwriting the old value. This
1378 is more like $@, which on every eval() is always set on failure and
1379 cleared on success.
1380 For more details, see the individual descriptions at $@, $!, $^E, and
1382 $?.
1383 Technical Note on the Syntax of Variable Names
1385 Variable names in Perl can have several formats. Usually, they must
1386 begin with a letter or underscore, in which case they can be
1387 arbitrarily long (up to an internal limit of 251 characters) and may
1388 contain letters, digits, underscores, or the special sequence "::" or
1389 "'". In this case, the part before the last "::" or "'" is taken to be
1390 a package qualifier; see perlmod.
1391 Perl variable names may also be a sequence of digits or a single
1393 punctuation or control character. These names are all reserved for
1394 special uses by Perl; for example, the all-digits names are used to
1395 hold data captured by backreferences after a regular expression match.
1396 Perl has a special syntax for the single-control-character names: It
1397 understands "^X" (caret "X") to mean the control-"X" character. For
1398 example, the notation $^W (dollar-sign caret "W") is the scalar
1399 variable whose name is the single character control-"W". This is
1400 better than typing a literal control-"W" into your program.
1401 Finally, new in Perl 5.6, Perl variable names may be alphanumeric
1403 strings that begin with control characters (or better yet, a caret).
1404 These variables must be written in the form "${^Foo}"; the braces are
1405 not optional. "${^Foo}" denotes the scalar variable whose name is a
1406 control-"F" followed by two "o"'s. These variables are reserved for
1407 future special uses by Perl, except for the ones that begin with "^_"
1408 (control-underscore or caret-underscore). No control-character name
1409 that begins with "^_" will acquire a special meaning in any future
1410 version of Perl; such names may therefore be used safely in programs.
1411 $^_ itself, however, is reserved.
1412 Perl identifiers that begin with digits, control characters, or
1414 punctuation characters are exempt from the effects of the "package"
1415 declaration and are always forced to be in package "main"; they are
1416 also exempt from "strict 'vars'" errors. A few other names are also
1417 exempt in these ways:
1418 ENV STDIN
1420 INC STDOUT
1421 ARGV STDERR
1422 ARGVOUT _
1423 SIG
1424 In particular, the new special "${^_XYZ}" variables are always taken to
1426 be in package "main", regardless of any "package" declarations
1427 presently in scope.
1428
1430 Due to an unfortunate accident of Perl's implementation, "use English"
1431 imposes a considerable performance penalty on all regular expression
1432 matches in a program, regardless of whether they occur in the scope of
1433 "use English". For that reason, saying "use English" in libraries is
1434 strongly discouraged. See the Devel::SawAmpersand module documentation
1435 from CPAN ( http://www.cpan.org/modules/by-module/Devel/ ) for more
1436 information. Writing "use English '-no_match_vars';" avoids the
1437 performance penalty.
1438 Having to even think about the $^S variable in your exception handlers
1440 is simply wrong. $SIG{__DIE__} as currently implemented invites
1441 grievous and difficult to track down errors. Avoid it and use an
1442 "END{}" or CORE::GLOBAL::die override instead.
1443perl v5.10.1 2017-03-22 PERLVAR(1)