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> ($1, $2, ...)
187 Contains the subpattern from the corresponding set of capturing
188 parentheses from the last successful pattern match, not
189 counting patterns matched in nested blocks that have been
190 exited already. (Mnemonic: like \digits.) These variables are
191 all read-only 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 deprecated, and by default will
852 trigger a warning.
853 Note that, unlike other compile-time directives (such as
855 strict), assignment to $[ can be seen from outer lexical scopes
856 in the same file. However, you can use local() on it to
857 strictly bind its value to a lexical block.
858 $] The version + patchlevel / 1000 of the Perl interpreter. This
860 variable can be used to determine whether the Perl interpreter
861 executing a script is in the right range of versions.
862 (Mnemonic: Is this version of perl in the right bracket?)
863 Example:
864 warn "No checksumming!\n" if $] < 3.019;
866 See also the documentation of "use VERSION" and "require
868 VERSION" for a convenient way to fail if the running Perl
869 interpreter is too old.
870 The floating point representation can sometimes lead to
872 inaccurate numeric comparisons. See $^V for a more modern
873 representation of the Perl version that allows accurate string
874 comparisons.
875 $COMPILING
877 $^C The current value of the flag associated with the -c switch.
878 Mainly of use with -MO=... to allow code to alter its behavior
879 when being compiled, such as for example to AUTOLOAD at compile
880 time rather than normal, deferred loading. Setting "$^C = 1"
881 is similar to calling "B::minus_c".
882 $DEBUGGING
884 $^D The current value of the debugging flags. (Mnemonic: value of
885 -D switch.) May be read or set. Like its command-line
886 equivalent, you can use numeric or symbolic values, eg "$^D =
887 10" or "$^D = "st"".
888 ${^RE_DEBUG_FLAGS}
890 The current value of the regex debugging flags. Set to 0 for no
891 debug output even when the re 'debug' module is loaded. See re
892 for details.
893 ${^RE_TRIE_MAXBUF}
895 Controls how certain regex optimisations are applied and how
896 much memory they utilize. This value by default is 65536 which
897 corresponds to a 512kB temporary cache. Set this to a higher
898 value to trade memory for speed when matching large
899 alternations. Set it to a lower value if you want the
900 optimisations to be as conservative of memory as possible but
901 still occur, and set it to a negative value to prevent the
902 optimisation and conserve the most memory. Under normal
903 situations this variable should be of no interest to you.
904 $SYSTEM_FD_MAX
906 $^F The maximum system file descriptor, ordinarily 2. System file
907 descriptors are passed to exec()ed processes, while higher file
908 descriptors are not. Also, during an open(), system file
909 descriptors are preserved even if the open() fails. (Ordinary
910 file descriptors are closed before the open() is attempted.)
911 The close-on-exec status of a file descriptor will be decided
912 according to the value of $^F when the corresponding file,
913 pipe, or socket was opened, not the time of the exec().
914 $^H WARNING: This variable is strictly for internal use only. Its
916 availability, behavior, and contents are subject to change
917 without notice.
918 This variable contains compile-time hints for the Perl
920 interpreter. At the end of compilation of a BLOCK the value of
921 this variable is restored to the value when the interpreter
922 started to compile the BLOCK.
923 When perl begins to parse any block construct that provides a
925 lexical scope (e.g., eval body, required file, subroutine body,
926 loop body, or conditional block), the existing value of $^H is
927 saved, but its value is left unchanged. When the compilation
928 of the block is completed, it regains the saved value. Between
929 the points where its value is saved and restored, code that
930 executes within BEGIN blocks is free to change the value of
931 $^H.
932 This behavior provides the semantic of lexical scoping, and is
934 used in, for instance, the "use strict" pragma.
935 The contents should be an integer; different bits of it are
937 used for different pragmatic flags. Here's an example:
938 sub add_100 { $^H |= 0x100 }
940 sub foo {
942 BEGIN { add_100() }
943 bar->baz($boon);
944 }
945 Consider what happens during execution of the BEGIN block. At
947 this point the BEGIN block has already been compiled, but the
948 body of foo() is still being compiled. The new value of $^H
949 will therefore be visible only while the body of foo() is being
950 compiled.
951 Substitution of the above BEGIN block with:
953 BEGIN { require strict; strict->import('vars') }
955 demonstrates how "use strict 'vars'" is implemented. Here's a
957 conditional version of the same lexical pragma:
958 BEGIN { require strict; strict->import('vars') if $condition }
960 %^H The %^H hash provides the same scoping semantic as $^H. This
962 makes it useful for implementation of lexically scoped pragmas.
963 See perlpragma.
964 $INPLACE_EDIT
966 $^I The current value of the inplace-edit extension. Use "undef"
967 to disable inplace editing. (Mnemonic: value of -i switch.)
968 $^M By default, running out of memory is an untrappable, fatal
970 error. However, if suitably built, Perl can use the contents
971 of $^M as an emergency memory pool after die()ing. Suppose
972 that your Perl were compiled with "-DPERL_EMERGENCY_SBRK" and
973 used Perl's malloc. Then
974 $^M = 'a' x (1 << 16);
976 would allocate a 64K buffer for use in an emergency. See the
978 INSTALL file in the Perl distribution for information on how to
979 add custom C compilation flags when compiling perl. To
980 discourage casual use of this advanced feature, there is no
981 English long name for this variable.
982 $OSNAME
984 $^O The name of the operating system under which this copy of Perl
985 was built, as determined during the configuration process. For
986 examples see "PLATFORMS" in perlport.
987 The value is identical to $Config{'osname'}. See also Config
989 and the -V command-line switch documented in perlrun.
990 In Windows platforms, $^O is not very helpful: since it is
992 always "MSWin32", it doesn't tell the difference between
993 95/98/ME/NT/2000/XP/CE/.NET. Use Win32::GetOSName() or
994 Win32::GetOSVersion() (see Win32 and perlport) to distinguish
995 between the variants.
996 ${^OPEN}
998 An internal variable used by PerlIO. A string in two parts,
999 separated by a "\0" byte, the first part describes the input
1000 layers, the second part describes the output layers.
1001 $PERLDB
1003 $^P The internal variable for debugging support. The meanings of
1004 the various bits are subject to change, but currently indicate:
1005 0x01 Debug subroutine enter/exit.
1007 0x02 Line-by-line debugging. Causes DB::DB() subroutine to be
1009 called for each statement executed. Also causes saving
1010 source code lines (like 0x400).
1011 0x04 Switch off optimizations.
1013 0x08 Preserve more data for future interactive inspections.
1015 0x10 Keep info about source lines on which a subroutine is
1017 defined.
1018 0x20 Start with single-step on.
1020 0x40 Use subroutine address instead of name when reporting.
1022 0x80 Report "goto &subroutine" as well.
1024 0x100 Provide informative "file" names for evals based on the
1026 place they were compiled.
1027 0x200 Provide informative names to anonymous subroutines based
1029 on the place they were compiled.
1030 0x400 Save source code lines into "@{"_<$filename"}".
1032 Some bits may be relevant at compile-time only, some at run-
1034 time only. This is a new mechanism and the details may change.
1035 See also perldebguts.
1036 $LAST_REGEXP_CODE_RESULT
1038 $^R The result of evaluation of the last successful "(?{ code })"
1039 regular expression assertion (see perlre). May be written to.
1040 $EXCEPTIONS_BEING_CAUGHT
1042 $^S Current state of the interpreter.
1043 $^S State
1045 --------- -------------------
1046 undef Parsing module/eval
1047 true (1) Executing an eval
1048 false (0) Otherwise
1049 The first state may happen in $SIG{__DIE__} and $SIG{__WARN__}
1051 handlers.
1052 $BASETIME
1054 $^T The time at which the program began running, in seconds since
1055 the epoch (beginning of 1970). The values returned by the -M,
1056 -A, and -C filetests are based on this value.
1057 ${^TAINT}
1059 Reflects if taint mode is on or off. 1 for on (the program was
1060 run with -T), 0 for off, -1 when only taint warnings are
1061 enabled (i.e. with -t or -TU). This variable is read-only.
1062 ${^UNICODE}
1064 Reflects certain Unicode settings of Perl. See perlrun
1065 documentation for the "-C" switch for more information about
1066 the possible values. This variable is set during Perl startup
1067 and is thereafter read-only.
1068 ${^UTF8CACHE}
1070 This variable controls the state of the internal UTF-8 offset
1071 caching code. 1 for on (the default), 0 for off, -1 to debug
1072 the caching code by checking all its results against linear
1073 scans, and panicking on any discrepancy.
1074 ${^UTF8LOCALE}
1076 This variable indicates whether a UTF-8 locale was detected by
1077 perl at startup. This information is used by perl when it's in
1078 adjust-utf8ness-to-locale mode (as when run with the "-CL"
1079 command-line switch); see perlrun for more info on this.
1080 $PERL_VERSION
1082 $^V The revision, version, and subversion of the Perl interpreter,
1083 represented as a "version" object.
1084 This variable first appeared in perl 5.6.0; earlier versions of
1086 perl will see an undefined value. Before perl 5.10.0 $^V was
1087 represented as a v-string.
1088 $^V can be used to determine whether the Perl interpreter
1090 executing a script is in the right range of versions.
1091 (Mnemonic: use ^V for Version Control.) Example:
1092 warn "Hashes not randomized!\n" if !$^V or $^V lt v5.8.1
1094 To convert $^V into its string representation use sprintf()'s
1096 "%vd" conversion:
1097 printf "version is v%vd\n", $^V; # Perl's version
1099 See the documentation of "use VERSION" and "require VERSION"
1101 for a convenient way to fail if the running Perl interpreter is
1102 too old.
1103 See also $] for an older representation of the Perl version.
1105 $WARNING
1107 $^W The current value of the warning switch, initially true if -w
1108 was used, false otherwise, but directly modifiable. (Mnemonic:
1109 related to the -w switch.) See also warnings.
1110 ${^WARNING_BITS}
1112 The current set of warning checks enabled by the "use warnings"
1113 pragma. See the documentation of "warnings" for more details.
1114 ${^WIN32_SLOPPY_STAT}
1116 If this variable is set to a true value, then stat() on Windows
1117 will not try to open the file. This means that the link count
1118 cannot be determined and file attributes may be out of date if
1119 additional hardlinks to the file exist. On the other hand, not
1120 opening the file is considerably faster, especially for files
1121 on network drives.
1122 This variable could be set in the sitecustomize.pl file to
1124 configure the local Perl installation to use "sloppy" stat() by
1125 default. See the documentation for -f in perlrun for more
1126 information about site customization.
1127 $EXECUTABLE_NAME
1129 $^X The name used to execute the current copy of Perl, from C's
1130 "argv[0]" or (where supported) /proc/self/exe.
1131 Depending on the host operating system, the value of $^X may be
1133 a relative or absolute pathname of the perl program file, or
1134 may be the string used to invoke perl but not the pathname of
1135 the perl program file. Also, most operating systems permit
1136 invoking programs that are not in the PATH environment
1137 variable, so there is no guarantee that the value of $^X is in
1138 PATH. For VMS, the value may or may not include a version
1139 number.
1140 You usually can use the value of $^X to re-invoke an
1142 independent copy of the same perl that is currently running,
1143 e.g.,
1144 @first_run = `$^X -le "print int rand 100 for 1..100"`;
1146 But recall that not all operating systems support forking or
1148 capturing of the output of commands, so this complex statement
1149 may not be portable.
1150 It is not safe to use the value of $^X as a path name of a
1152 file, as some operating systems that have a mandatory suffix on
1153 executable files do not require use of the suffix when invoking
1154 a command. To convert the value of $^X to a path name, use the
1155 following statements:
1156 # Build up a set of file names (not command names).
1158 use Config;
1159 $this_perl = $^X;
1160 if ($^O ne 'VMS')
1161 {$this_perl .= $Config{_exe}
1162 unless $this_perl =~ m/$Config{_exe}$/i;}
1163 Because many operating systems permit anyone with read access
1165 to the Perl program file to make a copy of it, patch the copy,
1166 and then execute the copy, the security-conscious Perl
1167 programmer should take care to invoke the installed copy of
1168 perl, not the copy referenced by $^X. The following statements
1169 accomplish this goal, and produce a pathname that can be
1170 invoked as a command or referenced as a file.
1171 use Config;
1173 $secure_perl_path = $Config{perlpath};
1174 if ($^O ne 'VMS')
1175 {$secure_perl_path .= $Config{_exe}
1176 unless $secure_perl_path =~ m/$Config{_exe}$/i;}
1177 ARGV The special filehandle that iterates over command-line
1179 filenames in @ARGV. Usually written as the null filehandle in
1180 the angle operator "<>". Note that currently "ARGV" only has
1181 its magical effect within the "<>" operator; elsewhere it is
1182 just a plain filehandle corresponding to the last file opened
1183 by "<>". In particular, passing "\*ARGV" as a parameter to a
1184 function that expects a filehandle may not cause your function
1185 to automatically read the contents of all the files in @ARGV.
1186 $ARGV contains the name of the current file when reading from <>.
1188 @ARGV The array @ARGV contains the command-line arguments intended
1190 for the script. $#ARGV is generally the number of arguments
1191 minus one, because $ARGV[0] is the first argument, not the
1192 program's command name itself. See $0 for the command name.
1193 ARGVOUT The special filehandle that points to the currently open output
1195 file when doing edit-in-place processing with -i. Useful when
1196 you have to do a lot of inserting and don't want to keep
1197 modifying $_. See perlrun for the -i switch.
1198 @F The array @F contains the fields of each line read in when
1200 autosplit mode is turned on. See perlrun for the -a switch.
1201 This array is package-specific, and must be declared or given a
1202 full package name if not in package main when running under
1203 "strict 'vars'".
1204 @INC The array @INC contains the list of places that the "do EXPR",
1206 "require", or "use" constructs look for their library files.
1207 It initially consists of the arguments to any -I command-line
1208 switches, followed by the default Perl library, probably
1209 /usr/local/lib/perl, followed by ".", to represent the current
1210 directory. ("." will not be appended if taint checks are
1211 enabled, either by "-T" or by "-t".) If you need to modify
1212 this at runtime, you should use the "use lib" pragma to get the
1213 machine-dependent library properly loaded also:
1214 use lib '/mypath/libdir/';
1216 use SomeMod;
1217 You can also insert hooks into the file inclusion system by
1219 putting Perl code directly into @INC. Those hooks may be
1220 subroutine references, array references or blessed objects.
1221 See "require" in perlfunc for details.
1222 @ARG
1224 @_ Within a subroutine the array @_ contains the parameters passed
1225 to that subroutine. See perlsub.
1226 %INC The hash %INC contains entries for each filename included via
1228 the "do", "require", or "use" operators. The key is the
1229 filename you specified (with module names converted to
1230 pathnames), and the value is the location of the file found.
1231 The "require" operator uses this hash to determine whether a
1232 particular file has already been included.
1233 If the file was loaded via a hook (e.g. a subroutine reference,
1235 see "require" in perlfunc for a description of these hooks),
1236 this hook is by default inserted into %INC in place of a
1237 filename. Note, however, that the hook may have set the %INC
1238 entry by itself to provide some more specific info.
1239 %ENV
1241 $ENV{expr}
1242 The hash %ENV contains your current environment. Setting a
1243 value in "ENV" changes the environment for any child processes
1244 you subsequently fork() off.
1245 %SIG
1247 $SIG{expr}
1248 The hash %SIG contains signal handlers for signals. For
1249 example:
1250 sub handler { # 1st argument is signal name
1252 my($sig) = @_;
1253 print "Caught a SIG$sig--shutting down\n";
1254 close(LOG);
1255 exit(0);
1256 }
1257 $SIG{'INT'} = \&handler;
1259 $SIG{'QUIT'} = \&handler;
1260 ...
1261 $SIG{'INT'} = 'DEFAULT'; # restore default action
1262 $SIG{'QUIT'} = 'IGNORE'; # ignore SIGQUIT
1263 Using a value of 'IGNORE' usually has the effect of ignoring
1265 the signal, except for the "CHLD" signal. See perlipc for more
1266 about this special case.
1267 Here are some other examples:
1269 $SIG{"PIPE"} = "Plumber"; # assumes main::Plumber (not recommended)
1271 $SIG{"PIPE"} = \&Plumber; # just fine; assume current Plumber
1272 $SIG{"PIPE"} = *Plumber; # somewhat esoteric
1273 $SIG{"PIPE"} = Plumber(); # oops, what did Plumber() return??
1274 Be sure not to use a bareword as the name of a signal handler,
1276 lest you inadvertently call it.
1277 If your system has the sigaction() function then signal
1279 handlers are installed using it. This means you get reliable
1280 signal handling.
1281 The default delivery policy of signals changed in Perl 5.8.0
1283 from immediate (also known as "unsafe") to deferred, also known
1284 as "safe signals". See perlipc for more information.
1285 Certain internal hooks can be also set using the %SIG hash.
1287 The routine indicated by $SIG{__WARN__} is called when a
1288 warning message is about to be printed. The warning message is
1289 passed as the first argument. The presence of a "__WARN__"
1290 hook causes the ordinary printing of warnings to "STDERR" to be
1291 suppressed. You can use this to save warnings in a variable,
1292 or turn warnings into fatal errors, like this:
1293 local $SIG{__WARN__} = sub { die $_[0] };
1295 eval $proggie;
1296 As the 'IGNORE' hook is not supported by "__WARN__", you can
1298 disable warnings using the empty subroutine:
1299 local $SIG{__WARN__} = sub {};
1301 The routine indicated by $SIG{__DIE__} is called when a fatal
1303 exception is about to be thrown. The error message is passed
1304 as the first argument. When a "__DIE__" hook routine returns,
1305 the exception processing continues as it would have in the
1306 absence of the hook, unless the hook routine itself exits via a
1307 "goto", a loop exit, or a "die()". The "__DIE__" handler is
1308 explicitly disabled during the call, so that you can die from a
1309 "__DIE__" handler. Similarly for "__WARN__".
1310 Due to an implementation glitch, the $SIG{__DIE__} hook is
1312 called even inside an eval(). Do not use this to rewrite a
1313 pending exception in $@, or as a bizarre substitute for
1314 overriding "CORE::GLOBAL::die()". This strange action at a
1315 distance may be fixed in a future release so that $SIG{__DIE__}
1316 is only called if your program is about to exit, as was the
1317 original intent. Any other use is deprecated.
1318 "__DIE__"/"__WARN__" handlers are very special in one respect:
1320 they may be called to report (probable) errors found by the
1321 parser. In such a case the parser may be in inconsistent
1322 state, so any attempt to evaluate Perl code from such a handler
1323 will probably result in a segfault. This means that warnings
1324 or errors that result from parsing Perl should be used with
1325 extreme caution, like this:
1326 require Carp if defined $^S;
1328 Carp::confess("Something wrong") if defined &Carp::confess;
1329 die "Something wrong, but could not load Carp to give backtrace...
1330 To see backtrace try starting Perl with -MCarp switch";
1331 Here the first line will load Carp unless it is the parser who
1333 called the handler. The second line will print backtrace and
1334 die if Carp was available. The third line will be executed
1335 only if Carp was not available.
1336 See "die" in perlfunc, "warn" in perlfunc, "eval" in perlfunc,
1338 and warnings for additional information.
1339 Names that are no longer special
1341 These variables had special meaning in prior versions of Perl but now
1342 have no effect and will cause warnings if used. They are included here
1343 for historical reference.
1344 $# $# used to be a variable that could be used to format printed
1346 numbers. After a deprecation cycle, its magic was removed in
1347 Perl 5.10 and using it now triggers a warning: "$# is no longer
1348 supported".
1349 $# is also used as sigil, which, when prepended on the name of
1351 an array, gives the index of the last element in that array.
1352 my @array = ("a", "b", "c");
1354 my $last_index = $#array; # $last_index is 2
1355 for my $i (0 .. $#array) {
1357 print "The value of index $i is $array[$i]\n";
1358 }
1359 Also see perldata.
1361 $* $* used to be a variable that enabled multiline matching.
1363 After a deprecation cycle, its magic was removed in Perl 5.10.
1364 Using it now triggers a warning: "$* is no longer supported".
1365 Use the "/s" and "/m" regexp modifiers instead.
1366 Also see perlre.
1368 Error Indicators
1370 The variables $@, $!, $^E, and $? contain information about different
1371 types of error conditions that may appear during execution of a Perl
1372 program. The variables are shown ordered by the "distance" between the
1373 subsystem which reported the error and the Perl process. They
1374 correspond to errors detected by the Perl interpreter, C library,
1375 operating system, or an external program, respectively.
1376 To illustrate the differences between these variables, consider the
1378 following Perl expression, which uses a single-quoted string:
1379 eval q{
1381 open my $pipe, "/cdrom/install |" or die $!;
1382 my @res = <$pipe>;
1383 close $pipe or die "bad pipe: $?, $!";
1384 };
1385 After execution of this statement all 4 variables may have been set.
1387 $@ is set if the string to be "eval"-ed did not compile (this may
1389 happen if "open" or "close" were imported with bad prototypes), or if
1390 Perl code executed during evaluation die()d . In these cases the value
1391 of $@ is the compile error, or the argument to "die" (which will
1392 interpolate $! and $?). (See also Fatal, though.)
1393 When the eval() expression above is executed, open(), "<PIPE>", and
1395 "close" are translated to calls in the C run-time library and thence to
1396 the operating system kernel. $! is set to the C library's "errno" if
1397 one of these calls fails.
1398 Under a few operating systems, $^E may contain a more verbose error
1400 indicator, such as in this case, "CDROM tray not closed." Systems that
1401 do not support extended error messages leave $^E the same as $!.
1402 Finally, $? may be set to non-0 value if the external program
1404 /cdrom/install fails. The upper eight bits reflect specific error
1405 conditions encountered by the program (the program's exit() value).
1406 The lower eight bits reflect mode of failure, like signal death and
1407 core dump information See wait(2) for details. In contrast to $! and
1408 $^E, which are set only if error condition is detected, the variable $?
1409 is set on each "wait" or pipe "close", overwriting the old value. This
1410 is more like $@, which on every eval() is always set on failure and
1411 cleared on success.
1412 For more details, see the individual descriptions at $@, $!, $^E, and
1414 $?.
1415 Technical Note on the Syntax of Variable Names
1417 Variable names in Perl can have several formats. Usually, they must
1418 begin with a letter or underscore, in which case they can be
1419 arbitrarily long (up to an internal limit of 251 characters) and may
1420 contain letters, digits, underscores, or the special sequence "::" or
1421 "'". In this case, the part before the last "::" or "'" is taken to be
1422 a package qualifier; see perlmod.
1423 Perl variable names may also be a sequence of digits or a single
1425 punctuation or control character. These names are all reserved for
1426 special uses by Perl; for example, the all-digits names are used to
1427 hold data captured by backreferences after a regular expression match.
1428 Perl has a special syntax for the single-control-character names: It
1429 understands "^X" (caret "X") to mean the control-"X" character. For
1430 example, the notation $^W (dollar-sign caret "W") is the scalar
1431 variable whose name is the single character control-"W". This is
1432 better than typing a literal control-"W" into your program.
1433 Finally, new in Perl 5.6, Perl variable names may be alphanumeric
1435 strings that begin with control characters (or better yet, a caret).
1436 These variables must be written in the form "${^Foo}"; the braces are
1437 not optional. "${^Foo}" denotes the scalar variable whose name is a
1438 control-"F" followed by two "o"'s. These variables are reserved for
1439 future special uses by Perl, except for the ones that begin with "^_"
1440 (control-underscore or caret-underscore). No control-character name
1441 that begins with "^_" will acquire a special meaning in any future
1442 version of Perl; such names may therefore be used safely in programs.
1443 $^_ itself, however, is reserved.
1444 Perl identifiers that begin with digits, control characters, or
1446 punctuation characters are exempt from the effects of the "package"
1447 declaration and are always forced to be in package "main"; they are
1448 also exempt from "strict 'vars'" errors. A few other names are also
1449 exempt in these ways:
1450 ENV STDIN
1452 INC STDOUT
1453 ARGV STDERR
1454 ARGVOUT _
1455 SIG
1456 In particular, the new special "${^_XYZ}" variables are always taken to
1458 be in package "main", regardless of any "package" declarations
1459 presently in scope.
1460
1462 Due to an unfortunate accident of Perl's implementation, "use English"
1463 imposes a considerable performance penalty on all regular expression
1464 matches in a program, regardless of whether they occur in the scope of
1465 "use English". For that reason, saying "use English" in libraries is
1466 strongly discouraged. See the Devel::SawAmpersand module documentation
1467 from CPAN ( http://www.cpan.org/modules/by-module/Devel/ ) for more
1468 information. Writing "use English '-no_match_vars';" avoids the
1469 performance penalty.
1470 Having to even think about the $^S variable in your exception handlers
1472 is simply wrong. $SIG{__DIE__} as currently implemented invites
1473 grievous and difficult to track down errors. Avoid it and use an
1474 "END{}" or CORE::GLOBAL::die override instead.
1475perl v5.12.4 2011-06-07 PERLVAR(1)