| =head1 NAME |
| |
| perlvar - Perl predefined variables |
| |
| =head1 DESCRIPTION |
| |
| =head2 Predefined Names |
| |
| The following names have special meaning to Perl. Most |
| punctuation names have reasonable mnemonics, or analogs in the |
| shells. Nevertheless, if you wish to use long variable names, |
| you need only say |
| |
| use English; |
| |
| at the top of your program. This will alias all the short names to the |
| long names in the current package. Some even have medium names, |
| generally borrowed from B<awk>. |
| |
| If you don't mind the performance hit, variables that depend on the |
| currently selected filehandle may instead be set by calling an |
| appropriate object method on the IO::Handle object. (Summary lines |
| below for this contain the word HANDLE.) First you must say |
| |
| use IO::Handle; |
| |
| after which you may use either |
| |
| method HANDLE EXPR |
| |
| or more safely, |
| |
| HANDLE->method(EXPR) |
| |
| Each method returns the old value of the IO::Handle attribute. |
| The methods each take an optional EXPR, which if supplied specifies the |
| new value for the IO::Handle attribute in question. If not supplied, |
| most methods do nothing to the current value--except for |
| autoflush(), which will assume a 1 for you, just to be different. |
| Because loading in the IO::Handle class is an expensive operation, you should |
| learn how to use the regular built-in variables. |
| |
| A few of these variables are considered "read-only". This means that if |
| you try to assign to this variable, either directly or indirectly through |
| a reference, you'll raise a run-time exception. |
| |
| The following list is ordered by scalar variables first, then the |
| arrays, then the hashes. |
| |
| =over 8 |
| |
| =item $ARG |
| |
| =item $_ |
| |
| The default input and pattern-searching space. The following pairs are |
| equivalent: |
| |
| while (<>) {...} # equivalent only in while! |
| while (defined($_ = <>)) {...} |
| |
| /^Subject:/ |
| $_ =~ /^Subject:/ |
| |
| tr/a-z/A-Z/ |
| $_ =~ tr/a-z/A-Z/ |
| |
| chomp |
| chomp($_) |
| |
| Here are the places where Perl will assume $_ even if you |
| don't use it: |
| |
| =over 3 |
| |
| =item * |
| |
| Various unary functions, including functions like ord() and int(), as well |
| as the all file tests (C<-f>, C<-d>) except for C<-t>, which defaults to |
| STDIN. |
| |
| =item * |
| |
| Various list functions like print() and unlink(). |
| |
| =item * |
| |
| The pattern matching operations C<m//>, C<s///>, and C<tr///> when used |
| without an C<=~> operator. |
| |
| =item * |
| |
| The default iterator variable in a C<foreach> loop if no other |
| variable is supplied. |
| |
| =item * |
| |
| The implicit iterator variable in the grep() and map() functions. |
| |
| =item * |
| |
| The default place to put an input record when a C<< <FH> >> |
| operation's result is tested by itself as the sole criterion of a C<while> |
| test. Outside a C<while> test, this will not happen. |
| |
| =back |
| |
| (Mnemonic: underline is understood in certain operations.) |
| |
| =back |
| |
| =over 8 |
| |
| =item $<I<digits>> |
| |
| Contains the subpattern from the corresponding set of capturing |
| parentheses from the last pattern match, not counting patterns |
| matched in nested blocks that have been exited already. (Mnemonic: |
| like \digits.) These variables are all read-only and dynamically |
| scoped to the current BLOCK. |
| |
| =item $MATCH |
| |
| =item $& |
| |
| The string matched by the last successful pattern match (not counting |
| any matches hidden within a BLOCK or eval() enclosed by the current |
| BLOCK). (Mnemonic: like & in some editors.) This variable is read-only |
| and dynamically scoped to the current BLOCK. |
| |
| The use of this variable anywhere in a program imposes a considerable |
| performance penalty on all regular expression matches. See L<BUGS>. |
| |
| =item $PREMATCH |
| |
| =item $` |
| |
| The string preceding whatever was matched by the last successful |
| pattern match (not counting any matches hidden within a BLOCK or eval |
| enclosed by the current BLOCK). (Mnemonic: C<`> often precedes a quoted |
| string.) This variable is read-only. |
| |
| The use of this variable anywhere in a program imposes a considerable |
| performance penalty on all regular expression matches. See L<BUGS>. |
| |
| =item $POSTMATCH |
| |
| =item $' |
| |
| The string following whatever was matched by the last successful |
| pattern match (not counting any matches hidden within a BLOCK or eval() |
| enclosed by the current BLOCK). (Mnemonic: C<'> often follows a quoted |
| string.) Example: |
| |
| $_ = 'abcdefghi'; |
| /def/; |
| print "$`:$&:$'\n"; # prints abc:def:ghi |
| |
| This variable is read-only and dynamically scoped to the current BLOCK. |
| |
| The use of this variable anywhere in a program imposes a considerable |
| performance penalty on all regular expression matches. See L<BUGS>. |
| |
| =item $LAST_PAREN_MATCH |
| |
| =item $+ |
| |
| The last bracket matched by the last search pattern. This is useful if |
| you don't know which one of a set of alternative patterns matched. For |
| example: |
| |
| /Version: (.*)|Revision: (.*)/ && ($rev = $+); |
| |
| (Mnemonic: be positive and forward looking.) |
| This variable is read-only and dynamically scoped to the current BLOCK. |
| |
| =item @LAST_MATCH_END |
| |
| =item @+ |
| |
| This array holds the offsets of the ends of the last successful |
| submatches in the currently active dynamic scope. C<$+[0]> is |
| the offset into the string of the end of the entire match. This |
| is the same value as what the C<pos> function returns when called |
| on the variable that was matched against. The I<n>th element |
| of this array holds the offset of the I<n>th submatch, so |
| C<$+[1]> is the offset past where $1 ends, C<$+[2]> the offset |
| past where $2 ends, and so on. You can use C<$#+> to determine |
| how many subgroups were in the last successful match. See the |
| examples given for the C<@-> variable. |
| |
| =item $MULTILINE_MATCHING |
| |
| =item $* |
| |
| Set to a non-zero integer value to do multi-line matching within a |
| string, 0 (or undefined) to tell Perl that it can assume that strings |
| contain a single line, for the purpose of optimizing pattern matches. |
| Pattern matches on strings containing multiple newlines can produce |
| confusing results when C<$*> is 0 or undefined. Default is undefined. |
| (Mnemonic: * matches multiple things.) This variable influences the |
| interpretation of only C<^> and C<$>. A literal newline can be searched |
| for even when C<$* == 0>. |
| |
| Use of C<$*> is deprecated in modern Perl, supplanted by |
| the C</s> and C</m> modifiers on pattern matching. |
| |
| Assigning a non-numerical value to C<$*> triggers a warning (and makes |
| C<$*> act if C<$* == 0>), while assigning a numerical value to C<$*> |
| makes that an implicit C<int> is applied on the value. |
| |
| =item input_line_number HANDLE EXPR |
| |
| =item $INPUT_LINE_NUMBER |
| |
| =item $NR |
| |
| =item $. |
| |
| The current input record number for the last file handle from which |
| you just read() (or called a C<seek> or C<tell> on). The value |
| may be different from the actual physical line number in the file, |
| depending on what notion of "line" is in effect--see C<$/> on how |
| to change that. An explicit close on a filehandle resets the line |
| number. Because C<< <> >> never does an explicit close, line |
| numbers increase across ARGV files (but see examples in L<perlfunc/eof>). |
| Consider this variable read-only: setting it does not reposition |
| the seek pointer; you'll have to do that on your own. Localizing C<$.> |
| has the effect of also localizing Perl's notion of "the last read |
| filehandle". (Mnemonic: many programs use "." to mean the current line |
| number.) |
| |
| =item input_record_separator HANDLE EXPR |
| |
| =item $INPUT_RECORD_SEPARATOR |
| |
| =item $RS |
| |
| =item $/ |
| |
| The input record separator, newline by default. This |
| influences Perl's idea of what a "line" is. Works like B<awk>'s RS |
| variable, including treating empty lines as a terminator if set to |
| the null string. (An empty line cannot contain any spaces |
| or tabs.) You may set it to a multi-character string to match a |
| multi-character terminator, or to C<undef> to read through the end |
| of file. Setting it to C<"\n\n"> means something slightly |
| different than setting to C<"">, if the file contains consecutive |
| empty lines. Setting to C<""> will treat two or more consecutive |
| empty lines as a single empty line. Setting to C<"\n\n"> will |
| blindly assume that the next input character belongs to the next |
| paragraph, even if it's a newline. (Mnemonic: / delimits |
| line boundaries when quoting poetry.) |
| |
| undef $/; # enable "slurp" mode |
| $_ = <FH>; # whole file now here |
| s/\n[ \t]+/ /g; |
| |
| Remember: the value of C<$/> is a string, not a regex. B<awk> has to be |
| better for something. :-) |
| |
| Setting C<$/> to a reference to an integer, scalar containing an integer, or |
| scalar that's convertible to an integer will attempt to read records |
| instead of lines, with the maximum record size being the referenced |
| integer. So this: |
| |
| $/ = \32768; # or \"32768", or \$var_containing_32768 |
| open(FILE, $myfile); |
| $_ = <FILE>; |
| |
| will read a record of no more than 32768 bytes from FILE. If you're |
| not reading from a record-oriented file (or your OS doesn't have |
| record-oriented files), then you'll likely get a full chunk of data |
| with every read. If a record is larger than the record size you've |
| set, you'll get the record back in pieces. |
| |
| On VMS, record reads are done with the equivalent of C<sysread>, |
| so it's best not to mix record and non-record reads on the same |
| file. (This is unlikely to be a problem, because any file you'd |
| want to read in record mode is probably unusable in line mode.) |
| Non-VMS systems do normal I/O, so it's safe to mix record and |
| non-record reads of a file. |
| |
| See also L<perlport/"Newlines">. Also see C<$.>. |
| |
| =item autoflush HANDLE EXPR |
| |
| =item $OUTPUT_AUTOFLUSH |
| |
| =item $| |
| |
| If set to nonzero, forces a flush right away and after every write |
| or print on the currently selected output channel. Default is 0 |
| (regardless of whether the channel is really buffered by the |
| system or not; C<$|> tells you only whether you've asked Perl |
| explicitly to flush after each write). STDOUT will |
| typically be line buffered if output is to the terminal and block |
| buffered otherwise. Setting this variable is useful primarily when |
| you are outputting to a pipe or socket, such as when you are running |
| a Perl program under B<rsh> and want to see the output as it's |
| happening. This has no effect on input buffering. See L<perlfunc/getc> |
| for that. (Mnemonic: when you want your pipes to be piping hot.) |
| |
| =item output_field_separator HANDLE EXPR |
| |
| =item $OUTPUT_FIELD_SEPARATOR |
| |
| =item $OFS |
| |
| =item $, |
| |
| The output field separator for the print operator. Ordinarily the |
| print operator simply prints out its arguments without further |
| adornment. To get behavior more like B<awk>, set this variable as |
| you would set B<awk>'s OFS variable to specify what is printed |
| between fields. (Mnemonic: what is printed when there is a "," in |
| your print statement.) |
| |
| =item output_record_separator HANDLE EXPR |
| |
| =item $OUTPUT_RECORD_SEPARATOR |
| |
| =item $ORS |
| |
| =item $\ |
| |
| The output record separator for the print operator. Ordinarily the |
| print operator simply prints out its arguments as is, with no |
| trailing newline or other end-of-record string added. To get |
| behavior more like B<awk>, set this variable as you would set |
| B<awk>'s ORS variable to specify what is printed at the end of the |
| print. (Mnemonic: you set C<$\> instead of adding "\n" at the |
| end of the print. Also, it's just like C<$/>, but it's what you |
| get "back" from Perl.) |
| |
| =item $LIST_SEPARATOR |
| |
| =item $" |
| |
| This is like C<$,> except that it applies to array and slice values |
| interpolated into a double-quoted string (or similar interpreted |
| string). Default is a space. (Mnemonic: obvious, I think.) |
| |
| =item $SUBSCRIPT_SEPARATOR |
| |
| =item $SUBSEP |
| |
| =item $; |
| |
| The subscript separator for multidimensional array emulation. If you |
| refer to a hash element as |
| |
| $foo{$a,$b,$c} |
| |
| it really means |
| |
| $foo{join($;, $a, $b, $c)} |
| |
| But don't put |
| |
| @foo{$a,$b,$c} # a slice--note the @ |
| |
| which means |
| |
| ($foo{$a},$foo{$b},$foo{$c}) |
| |
| Default is "\034", the same as SUBSEP in B<awk>. If your |
| keys contain binary data there might not be any safe value for C<$;>. |
| (Mnemonic: comma (the syntactic subscript separator) is a |
| semi-semicolon. Yeah, I know, it's pretty lame, but C<$,> is already |
| taken for something more important.) |
| |
| Consider using "real" multidimensional arrays as described |
| in L<perllol>. |
| |
| =item $OFMT |
| |
| =item $# |
| |
| The output format for printed numbers. This variable is a half-hearted |
| attempt to emulate B<awk>'s OFMT variable. There are times, however, |
| when B<awk> and Perl have differing notions of what counts as |
| numeric. The initial value is "%.I<n>g", where I<n> is the value |
| of the macro DBL_DIG from your system's F<float.h>. This is different from |
| B<awk>'s default OFMT setting of "%.6g", so you need to set C<$#> |
| explicitly to get B<awk>'s value. (Mnemonic: # is the number sign.) |
| |
| Use of C<$#> is deprecated. |
| |
| =item format_page_number HANDLE EXPR |
| |
| =item $FORMAT_PAGE_NUMBER |
| |
| =item $% |
| |
| The current page number of the currently selected output channel. |
| Used with formats. |
| (Mnemonic: % is page number in B<nroff>.) |
| |
| =item format_lines_per_page HANDLE EXPR |
| |
| =item $FORMAT_LINES_PER_PAGE |
| |
| =item $= |
| |
| The current page length (printable lines) of the currently selected |
| output channel. Default is 60. |
| Used with formats. |
| (Mnemonic: = has horizontal lines.) |
| |
| =item format_lines_left HANDLE EXPR |
| |
| =item $FORMAT_LINES_LEFT |
| |
| =item $- |
| |
| The number of lines left on the page of the currently selected output |
| channel. |
| Used with formats. |
| (Mnemonic: lines_on_page - lines_printed.) |
| |
| =item @LAST_MATCH_START |
| |
| =item @- |
| |
| $-[0] is the offset of the start of the last successful match. |
| C<$-[>I<n>C<]> is the offset of the start of the substring matched by |
| I<n>-th subpattern, or undef if the subpattern did not match. |
| |
| Thus after a match against $_, $& coincides with C<substr $_, $-[0], |
| $+[0] - $-[0]>. Similarly, C<$>I<n> coincides with C<substr $_, $-[>I<n>C<], |
| $+[>I<n>C<] - $-[>I<n>C<]> if C<$-[>I<n>C<]> is defined, and $+ coincides with |
| C<substr $_, $-[$#-], $+[$#-]>. One can use C<$#-> to find the last |
| matched subgroup in the last successful match. Contrast with |
| C<$#+>, the number of subgroups in the regular expression. Compare |
| with C<@+>. |
| |
| This array holds the offsets of the beginnings of the last |
| successful submatches in the currently active dynamic scope. |
| C<$-[0]> is the offset into the string of the beginning of the |
| entire match. The I<n>th element of this array holds the offset |
| of the I<n>th submatch, so C<$+[1]> is the offset where $1 |
| begins, C<$+[2]> the offset where $2 begins, and so on. |
| You can use C<$#-> to determine how many subgroups were in the |
| last successful match. Compare with the C<@+> variable. |
| |
| After a match against some variable $var: |
| |
| =over 5 |
| |
| =item C<$`> is the same as C<substr($var, 0, $-[0])> |
| |
| =item C<$&> is the same as C<substr($var, $-[0], $+[0] - $-[0])> |
| |
| =item C<$'> is the same as C<substr($var, $+[0])> |
| |
| =item C<$1> is the same as C<substr($var, $-[1], $+[1] - $-[1])> |
| |
| =item C<$2> is the same as C<substr($var, $-[2], $+[2] - $-[2])> |
| |
| =item C<$3> is the same as C<substr $var, $-[3], $+[3] - $-[3])> |
| |
| =back |
| |
| =item format_name HANDLE EXPR |
| |
| =item $FORMAT_NAME |
| |
| =item $~ |
| |
| The name of the current report format for the currently selected output |
| channel. Default is the name of the filehandle. (Mnemonic: brother to |
| C<$^>.) |
| |
| =item format_top_name HANDLE EXPR |
| |
| =item $FORMAT_TOP_NAME |
| |
| =item $^ |
| |
| The name of the current top-of-page format for the currently selected |
| output channel. Default is the name of the filehandle with _TOP |
| appended. (Mnemonic: points to top of page.) |
| |
| =item format_line_break_characters HANDLE EXPR |
| |
| =item $FORMAT_LINE_BREAK_CHARACTERS |
| |
| =item $: |
| |
| The current set of characters after which a string may be broken to |
| fill continuation fields (starting with ^) in a format. Default is |
| S<" \n-">, to break on whitespace or hyphens. (Mnemonic: a "colon" in |
| poetry is a part of a line.) |
| |
| =item format_formfeed HANDLE EXPR |
| |
| =item $FORMAT_FORMFEED |
| |
| =item $^L |
| |
| What formats output as a form feed. Default is \f. |
| |
| =item $ACCUMULATOR |
| |
| =item $^A |
| |
| The current value of the write() accumulator for format() lines. A format |
| contains formline() calls that put their result into C<$^A>. After |
| calling its format, write() prints out the contents of C<$^A> and empties. |
| So you never really see the contents of C<$^A> unless you call |
| formline() yourself and then look at it. See L<perlform> and |
| L<perlfunc/formline()>. |
| |
| =item $CHILD_ERROR |
| |
| =item $? |
| |
| The status returned by the last pipe close, backtick (C<``>) command, |
| successful call to wait() or waitpid(), or from the system() |
| operator. This is just the 16-bit status word returned by the |
| wait() system call (or else is made up to look like it). Thus, the |
| exit value of the subprocess is really (C<<< $? >> 8 >>>), and |
| C<$? & 127> gives which signal, if any, the process died from, and |
| C<$? & 128> reports whether there was a core dump. (Mnemonic: |
| similar to B<sh> and B<ksh>.) |
| |
| Additionally, if the C<h_errno> variable is supported in C, its value |
| is returned via $? if any C<gethost*()> function fails. |
| |
| If you have installed a signal handler for C<SIGCHLD>, the |
| value of C<$?> will usually be wrong outside that handler. |
| |
| Inside an C<END> subroutine C<$?> contains the value that is going to be |
| given to C<exit()>. You can modify C<$?> in an C<END> subroutine to |
| change the exit status of your program. For example: |
| |
| END { |
| $? = 1 if $? == 255; # die would make it 255 |
| } |
| |
| Under VMS, the pragma C<use vmsish 'status'> makes C<$?> reflect the |
| actual VMS exit status, instead of the default emulation of POSIX |
| status. |
| |
| Also see L<Error Indicators>. |
| |
| =item $OS_ERROR |
| |
| =item $ERRNO |
| |
| =item $! |
| |
| If used numerically, yields the current value of the C C<errno> |
| variable, with all the usual caveats. (This means that you shouldn't |
| depend on the value of C<$!> to be anything in particular unless |
| you've gotten a specific error return indicating a system error.) |
| If used an a string, yields the corresponding system error string. |
| You can assign a number to C<$!> to set I<errno> if, for instance, |
| you want C<"$!"> to return the string for error I<n>, or you want |
| to set the exit value for the die() operator. (Mnemonic: What just |
| went bang?) |
| |
| Also see L<Error Indicators>. |
| |
| =item $EXTENDED_OS_ERROR |
| |
| =item $^E |
| |
| Error information specific to the current operating system. At |
| the moment, this differs from C<$!> under only VMS, OS/2, and Win32 |
| (and for MacPerl). On all other platforms, C<$^E> is always just |
| the same as C<$!>. |
| |
| Under VMS, C<$^E> provides the VMS status value from the last |
| system error. This is more specific information about the last |
| system error than that provided by C<$!>. This is particularly |
| important when C<$!> is set to B<EVMSERR>. |
| |
| Under OS/2, C<$^E> is set to the error code of the last call to |
| OS/2 API either via CRT, or directly from perl. |
| |
| Under Win32, C<$^E> always returns the last error information |
| reported by the Win32 call C<GetLastError()> which describes |
| the last error from within the Win32 API. Most Win32-specific |
| code will report errors via C<$^E>. ANSI C and Unix-like calls |
| set C<errno> and so most portable Perl code will report errors |
| via C<$!>. |
| |
| Caveats mentioned in the description of C<$!> generally apply to |
| C<$^E>, also. (Mnemonic: Extra error explanation.) |
| |
| Also see L<Error Indicators>. |
| |
| =item $EVAL_ERROR |
| |
| =item $@ |
| |
| The Perl syntax error message from the last eval() operator. If null, the |
| last eval() parsed and executed correctly (although the operations you |
| invoked may have failed in the normal fashion). (Mnemonic: Where was |
| the syntax error "at"?) |
| |
| Warning messages are not collected in this variable. You can, |
| however, set up a routine to process warnings by setting C<$SIG{__WARN__}> |
| as described below. |
| |
| Also see L<Error Indicators>. |
| |
| =item $PROCESS_ID |
| |
| =item $PID |
| |
| =item $$ |
| |
| The process number of the Perl running this script. You should |
| consider this variable read-only, although it will be altered |
| across fork() calls. (Mnemonic: same as shells.) |
| |
| =item $REAL_USER_ID |
| |
| =item $UID |
| |
| =item $< |
| |
| The real uid of this process. (Mnemonic: it's the uid you came I<from>, |
| if you're running setuid.) |
| |
| =item $EFFECTIVE_USER_ID |
| |
| =item $EUID |
| |
| =item $> |
| |
| The effective uid of this process. Example: |
| |
| $< = $>; # set real to effective uid |
| ($<,$>) = ($>,$<); # swap real and effective uid |
| |
| (Mnemonic: it's the uid you went I<to>, if you're running setuid.) |
| C<< $< >> and C<< $> >> can be swapped only on machines |
| supporting setreuid(). |
| |
| =item $REAL_GROUP_ID |
| |
| =item $GID |
| |
| =item $( |
| |
| The real gid of this process. If you are on a machine that supports |
| membership in multiple groups simultaneously, gives a space separated |
| list of groups you are in. The first number is the one returned by |
| getgid(), and the subsequent ones by getgroups(), one of which may be |
| the same as the first number. |
| |
| However, a value assigned to C<$(> must be a single number used to |
| set the real gid. So the value given by C<$(> should I<not> be assigned |
| back to C<$(> without being forced numeric, such as by adding zero. |
| |
| (Mnemonic: parentheses are used to I<group> things. The real gid is the |
| group you I<left>, if you're running setgid.) |
| |
| =item $EFFECTIVE_GROUP_ID |
| |
| =item $EGID |
| |
| =item $) |
| |
| The effective gid of this process. If you are on a machine that |
| supports membership in multiple groups simultaneously, gives a space |
| separated list of groups you are in. The first number is the one |
| returned by getegid(), and the subsequent ones by getgroups(), one of |
| which may be the same as the first number. |
| |
| Similarly, a value assigned to C<$)> must also be a space-separated |
| list of numbers. The first number sets the effective gid, and |
| the rest (if any) are passed to setgroups(). To get the effect of an |
| empty list for setgroups(), just repeat the new effective gid; that is, |
| to force an effective gid of 5 and an effectively empty setgroups() |
| list, say C< $) = "5 5" >. |
| |
| (Mnemonic: parentheses are used to I<group> things. The effective gid |
| is the group that's I<right> for you, if you're running setgid.) |
| |
| C<< $< >>, C<< $> >>, C<$(> and C<$)> can be set only on |
| machines that support the corresponding I<set[re][ug]id()> routine. C<$(> |
| and C<$)> can be swapped only on machines supporting setregid(). |
| |
| =item $PROGRAM_NAME |
| |
| =item $0 |
| |
| Contains the name of the program being executed. On some operating |
| systems assigning to C<$0> modifies the argument area that the B<ps> |
| program sees. This is more useful as a way of indicating the current |
| program state than it is for hiding the program you're running. |
| (Mnemonic: same as B<sh> and B<ksh>.) |
| |
| Note for BSD users: setting C<$0> does not completely remove "perl" |
| from the ps(1) output. For example, setting C<$0> to C<"foobar"> will |
| result in C<"perl: foobar (perl)">. This is an operating system |
| feature. |
| |
| =item $[ |
| |
| The index of the first element in an array, and of the first character |
| in a substring. Default is 0, but you could theoretically set it |
| to 1 to make Perl behave more like B<awk> (or Fortran) when |
| subscripting and when evaluating the index() and substr() functions. |
| (Mnemonic: [ begins subscripts.) |
| |
| As of release 5 of Perl, assignment to C<$[> is treated as a compiler |
| directive, and cannot influence the behavior of any other file. |
| Its use is highly discouraged. |
| |
| =item $] |
| |
| The version + patchlevel / 1000 of the Perl interpreter. This variable |
| can be used to determine whether the Perl interpreter executing a |
| script is in the right range of versions. (Mnemonic: Is this version |
| of perl in the right bracket?) Example: |
| |
| warn "No checksumming!\n" if $] < 3.019; |
| |
| See also the documentation of C<use VERSION> and C<require VERSION> |
| for a convenient way to fail if the running Perl interpreter is too old. |
| |
| The use of this variable is deprecated. The floating point representation |
| can sometimes lead to inaccurate numeric comparisons. See C<$^V> for a |
| more modern representation of the Perl version that allows accurate string |
| comparisons. |
| |
| =item $COMPILING |
| |
| =item $^C |
| |
| The current value of the flag associated with the B<-c> switch. |
| Mainly of use with B<-MO=...> to allow code to alter its behavior |
| when being compiled, such as for example to AUTOLOAD at compile |
| time rather than normal, deferred loading. See L<perlcc>. Setting |
| C<$^C = 1> is similar to calling C<B::minus_c>. |
| |
| =item $DEBUGGING |
| |
| =item $^D |
| |
| The current value of the debugging flags. (Mnemonic: value of B<-D> |
| switch.) |
| |
| =item $SYSTEM_FD_MAX |
| |
| =item $^F |
| |
| The maximum system file descriptor, ordinarily 2. System file |
| descriptors are passed to exec()ed processes, while higher file |
| descriptors are not. Also, during an open(), system file descriptors are |
| preserved even if the open() fails. (Ordinary file descriptors are |
| closed before the open() is attempted.) The close-on-exec |
| status of a file descriptor will be decided according to the value of |
| C<$^F> when the corresponding file, pipe, or socket was opened, not the |
| time of the exec(). |
| |
| =item $^H |
| |
| WARNING: This variable is strictly for internal use only. Its availability, |
| behavior, and contents are subject to change without notice. |
| |
| This variable contains compile-time hints for the Perl interpreter. At the |
| end of compilation of a BLOCK the value of this variable is restored to the |
| value when the interpreter started to compile the BLOCK. |
| |
| When perl begins to parse any block construct that provides a lexical scope |
| (e.g., eval body, required file, subroutine body, loop body, or conditional |
| block), the existing value of $^H is saved, but its value is left unchanged. |
| When the compilation of the block is completed, it regains the saved value. |
| Between the points where its value is saved and restored, code that |
| executes within BEGIN blocks is free to change the value of $^H. |
| |
| This behavior provides the semantic of lexical scoping, and is used in, |
| for instance, the C<use strict> pragma. |
| |
| The contents should be an integer; different bits of it are used for |
| different pragmatic flags. Here's an example: |
| |
| sub add_100 { $^H |= 0x100 } |
| |
| sub foo { |
| BEGIN { add_100() } |
| bar->baz($boon); |
| } |
| |
| Consider what happens during execution of the BEGIN block. At this point |
| the BEGIN block has already been compiled, but the body of foo() is still |
| being compiled. The new value of $^H will therefore be visible only while |
| the body of foo() is being compiled. |
| |
| Substitution of the above BEGIN block with: |
| |
| BEGIN { require strict; strict->import('vars') } |
| |
| demonstrates how C<use strict 'vars'> is implemented. Here's a conditional |
| version of the same lexical pragma: |
| |
| BEGIN { require strict; strict->import('vars') if $condition } |
| |
| =item %^H |
| |
| WARNING: This variable is strictly for internal use only. Its availability, |
| behavior, and contents are subject to change without notice. |
| |
| The %^H hash provides the same scoping semantic as $^H. This makes it |
| useful for implementation of lexically scoped pragmas. |
| |
| =item $INPLACE_EDIT |
| |
| =item $^I |
| |
| The current value of the inplace-edit extension. Use C<undef> to disable |
| inplace editing. (Mnemonic: value of B<-i> switch.) |
| |
| =item $^M |
| |
| By default, running out of memory is an untrappable, fatal error. |
| However, if suitably built, Perl can use the contents of C<$^M> |
| as an emergency memory pool after die()ing. Suppose that your Perl |
| were compiled with -DPERL_EMERGENCY_SBRK and used Perl's malloc. |
| Then |
| |
| $^M = 'a' x (1 << 16); |
| |
| would allocate a 64K buffer for use in an emergency. See the |
| F<INSTALL> file in the Perl distribution for information on how to |
| enable this option. To discourage casual use of this advanced |
| feature, there is no L<English|English> long name for this variable. |
| |
| =item $OSNAME |
| |
| =item $^O |
| |
| The name of the operating system under which this copy of Perl was |
| built, as determined during the configuration process. The value |
| is identical to C<$Config{'osname'}>. See also L<Config> and the |
| B<-V> command-line switch documented in L<perlrun>. |
| |
| =item $PERLDB |
| |
| =item $^P |
| |
| The internal variable for debugging support. The meanings of the |
| various bits are subject to change, but currently indicate: |
| |
| =over 6 |
| |
| =item 0x01 |
| |
| Debug subroutine enter/exit. |
| |
| =item 0x02 |
| |
| Line-by-line debugging. |
| |
| =item 0x04 |
| |
| Switch off optimizations. |
| |
| =item 0x08 |
| |
| Preserve more data for future interactive inspections. |
| |
| =item 0x10 |
| |
| Keep info about source lines on which a subroutine is defined. |
| |
| =item 0x20 |
| |
| Start with single-step on. |
| |
| =item 0x40 |
| |
| Use subroutine address instead of name when reporting. |
| |
| =item 0x80 |
| |
| Report C<goto &subroutine> as well. |
| |
| =item 0x100 |
| |
| Provide informative "file" names for evals based on the place they were compiled. |
| |
| =item 0x200 |
| |
| Provide informative names to anonymous subroutines based on the place they |
| were compiled. |
| |
| =back |
| |
| Some bits may be relevant at compile-time only, some at |
| run-time only. This is a new mechanism and the details may change. |
| |
| =item $LAST_REGEXP_CODE_RESULT |
| |
| =item $^R |
| |
| The result of evaluation of the last successful C<(?{ code })> |
| regular expression assertion (see L<perlre>). May be written to. |
| |
| =item $EXCEPTIONS_BEING_CAUGHT |
| |
| =item $^S |
| |
| Current state of the interpreter. Undefined if parsing of the current |
| module/eval is not finished (may happen in $SIG{__DIE__} and |
| $SIG{__WARN__} handlers). True if inside an eval(), otherwise false. |
| |
| =item $BASETIME |
| |
| =item $^T |
| |
| The time at which the program began running, in seconds since the |
| epoch (beginning of 1970). The values returned by the B<-M>, B<-A>, |
| and B<-C> filetests are based on this value. |
| |
| =item $PERL_VERSION |
| |
| =item $^V |
| |
| The revision, version, and subversion of the Perl interpreter, represented |
| as a string composed of characters with those ordinals. Thus in Perl v5.6.0 |
| it equals C<chr(5) . chr(6) . chr(0)> and will return true for |
| C<$^V eq v5.6.0>. Note that the characters in this string value can |
| potentially be in Unicode range. |
| |
| This can be used to determine whether the Perl interpreter executing a |
| script is in the right range of versions. (Mnemonic: use ^V for Version |
| Control.) Example: |
| |
| warn "No \"our\" declarations!\n" if $^V and $^V lt v5.6.0; |
| |
| See the documentation of C<use VERSION> and C<require VERSION> |
| for a convenient way to fail if the running Perl interpreter is too old. |
| |
| See also C<$]> for an older representation of the Perl version. |
| |
| =item $WARNING |
| |
| =item $^W |
| |
| The current value of the warning switch, initially true if B<-w> |
| was used, false otherwise, but directly modifiable. (Mnemonic: |
| related to the B<-w> switch.) See also L<warnings>. |
| |
| =item ${^WARNING_BITS} |
| |
| The current set of warning checks enabled by the C<use warnings> pragma. |
| See the documentation of C<warnings> for more details. |
| |
| =item ${^WIDE_SYSTEM_CALLS} |
| |
| Global flag that enables system calls made by Perl to use wide character |
| APIs native to the system, if available. This is currently only implemented |
| on the Windows platform. |
| |
| This can also be enabled from the command line using the C<-C> switch. |
| |
| The initial value is typically C<0> for compatibility with Perl versions |
| earlier than 5.6, but may be automatically set to C<1> by Perl if the system |
| provides a user-settable default (e.g., C<$ENV{LC_CTYPE}>). |
| |
| The C<bytes> pragma always overrides the effect of this flag in the current |
| lexical scope. See L<bytes>. |
| |
| =item $EXECUTABLE_NAME |
| |
| =item $^X |
| |
| The name that the Perl binary itself was executed as, from C's C<argv[0]>. |
| This may not be a full pathname, nor even necessarily in your path. |
| |
| =item $ARGV |
| |
| contains the name of the current file when reading from <>. |
| |
| =item @ARGV |
| |
| The array @ARGV contains the command-line arguments intended for |
| the script. C<$#ARGV> is generally the number of arguments minus |
| one, because C<$ARGV[0]> is the first argument, I<not> the program's |
| command name itself. See C<$0> for the command name. |
| |
| =item @INC |
| |
| The array @INC contains the list of places that the C<do EXPR>, |
| C<require>, or C<use> constructs look for their library files. It |
| initially consists of the arguments to any B<-I> command-line |
| switches, followed by the default Perl library, probably |
| F</usr/local/lib/perl>, followed by ".", to represent the current |
| directory. If you need to modify this at runtime, you should use |
| the C<use lib> pragma to get the machine-dependent library properly |
| loaded also: |
| |
| use lib '/mypath/libdir/'; |
| use SomeMod; |
| |
| =item @_ |
| |
| Within a subroutine the array @_ contains the parameters passed to that |
| subroutine. See L<perlsub>. |
| |
| =item %INC |
| |
| The hash %INC contains entries for each filename included via the |
| C<do>, C<require>, or C<use> operators. The key is the filename |
| you specified (with module names converted to pathnames), and the |
| value is the location of the file found. The C<require> |
| operator uses this hash to determine whether a particular file has |
| already been included. |
| |
| =item %ENV |
| |
| =item $ENV{expr} |
| |
| The hash %ENV contains your current environment. Setting a |
| value in C<ENV> changes the environment for any child processes |
| you subsequently fork() off. |
| |
| =item %SIG |
| |
| =item $SIG{expr} |
| |
| The hash %SIG contains signal handlers for signals. For example: |
| |
| sub handler { # 1st argument is signal name |
| my($sig) = @_; |
| print "Caught a SIG$sig--shutting down\n"; |
| close(LOG); |
| exit(0); |
| } |
| |
| $SIG{'INT'} = \&handler; |
| $SIG{'QUIT'} = \&handler; |
| ... |
| $SIG{'INT'} = 'DEFAULT'; # restore default action |
| $SIG{'QUIT'} = 'IGNORE'; # ignore SIGQUIT |
| |
| Using a value of C<'IGNORE'> usually has the effect of ignoring the |
| signal, except for the C<CHLD> signal. See L<perlipc> for more about |
| this special case. |
| |
| Here are some other examples: |
| |
| $SIG{"PIPE"} = "Plumber"; # assumes main::Plumber (not recommended) |
| $SIG{"PIPE"} = \&Plumber; # just fine; assume current Plumber |
| $SIG{"PIPE"} = *Plumber; # somewhat esoteric |
| $SIG{"PIPE"} = Plumber(); # oops, what did Plumber() return?? |
| |
| Be sure not to use a bareword as the name of a signal handler, |
| lest you inadvertently call it. |
| |
| If your system has the sigaction() function then signal handlers are |
| installed using it. This means you get reliable signal handling. If |
| your system has the SA_RESTART flag it is used when signals handlers are |
| installed. This means that system calls for which restarting is supported |
| continue rather than returning when a signal arrives. If you want your |
| system calls to be interrupted by signal delivery then do something like |
| this: |
| |
| use POSIX ':signal_h'; |
| |
| my $alarm = 0; |
| sigaction SIGALRM, new POSIX::SigAction sub { $alarm = 1 } |
| or die "Error setting SIGALRM handler: $!\n"; |
| |
| See L<POSIX>. |
| |
| Certain internal hooks can be also set using the %SIG hash. The |
| routine indicated by C<$SIG{__WARN__}> is called when a warning message is |
| about to be printed. The warning message is passed as the first |
| argument. The presence of a __WARN__ hook causes the ordinary printing |
| of warnings to STDERR to be suppressed. You can use this to save warnings |
| in a variable, or turn warnings into fatal errors, like this: |
| |
| local $SIG{__WARN__} = sub { die $_[0] }; |
| eval $proggie; |
| |
| The routine indicated by C<$SIG{__DIE__}> is called when a fatal exception |
| is about to be thrown. The error message is passed as the first |
| argument. When a __DIE__ hook routine returns, the exception |
| processing continues as it would have in the absence of the hook, |
| unless the hook routine itself exits via a C<goto>, a loop exit, or a die(). |
| The C<__DIE__> handler is explicitly disabled during the call, so that you |
| can die from a C<__DIE__> handler. Similarly for C<__WARN__>. |
| |
| Due to an implementation glitch, the C<$SIG{__DIE__}> hook is called |
| even inside an eval(). Do not use this to rewrite a pending exception |
| in C<$@>, or as a bizarre substitute for overriding CORE::GLOBAL::die(). |
| This strange action at a distance may be fixed in a future release |
| so that C<$SIG{__DIE__}> is only called if your program is about |
| to exit, as was the original intent. Any other use is deprecated. |
| |
| C<__DIE__>/C<__WARN__> handlers are very special in one respect: |
| they may be called to report (probable) errors found by the parser. |
| In such a case the parser may be in inconsistent state, so any |
| attempt to evaluate Perl code from such a handler will probably |
| result in a segfault. This means that warnings or errors that |
| result from parsing Perl should be used with extreme caution, like |
| this: |
| |
| require Carp if defined $^S; |
| Carp::confess("Something wrong") if defined &Carp::confess; |
| die "Something wrong, but could not load Carp to give backtrace... |
| To see backtrace try starting Perl with -MCarp switch"; |
| |
| Here the first line will load Carp I<unless> it is the parser who |
| called the handler. The second line will print backtrace and die if |
| Carp was available. The third line will be executed only if Carp was |
| not available. |
| |
| See L<perlfunc/die>, L<perlfunc/warn>, L<perlfunc/eval>, and |
| L<warnings> for additional information. |
| |
| =back |
| |
| =head2 Error Indicators |
| |
| The variables C<$@>, C<$!>, C<$^E>, and C<$?> contain information |
| about different types of error conditions that may appear during |
| execution of a Perl program. The variables are shown ordered by |
| the "distance" between the subsystem which reported the error and |
| the Perl process. They correspond to errors detected by the Perl |
| interpreter, C library, operating system, or an external program, |
| respectively. |
| |
| To illustrate the differences between these variables, consider the |
| following Perl expression, which uses a single-quoted string: |
| |
| eval q{ |
| open PIPE, "/cdrom/install |"; |
| @res = <PIPE>; |
| close PIPE or die "bad pipe: $?, $!"; |
| }; |
| |
| After execution of this statement all 4 variables may have been set. |
| |
| C<$@> is set if the string to be C<eval>-ed did not compile (this |
| may happen if C<open> or C<close> were imported with bad prototypes), |
| or if Perl code executed during evaluation die()d . In these cases |
| the value of $@ is the compile error, or the argument to C<die> |
| (which will interpolate C<$!> and C<$?>!). (See also L<Fatal>, |
| though.) |
| |
| When the eval() expression above is executed, open(), C<< <PIPE> >>, |
| and C<close> are translated to calls in the C run-time library and |
| thence to the operating system kernel. C<$!> is set to the C library's |
| C<errno> if one of these calls fails. |
| |
| Under a few operating systems, C<$^E> may contain a more verbose |
| error indicator, such as in this case, "CDROM tray not closed." |
| Systems that do not support extended error messages leave C<$^E> |
| the same as C<$!>. |
| |
| Finally, C<$?> may be set to non-0 value if the external program |
| F</cdrom/install> fails. The upper eight bits reflect specific |
| error conditions encountered by the program (the program's exit() |
| value). The lower eight bits reflect mode of failure, like signal |
| death and core dump information See wait(2) for details. In |
| contrast to C<$!> and C<$^E>, which are set only if error condition |
| is detected, the variable C<$?> is set on each C<wait> or pipe |
| C<close>, overwriting the old value. This is more like C<$@>, which |
| on every eval() is always set on failure and cleared on success. |
| |
| For more details, see the individual descriptions at C<$@>, C<$!>, C<$^E>, |
| and C<$?>. |
| |
| =head2 Technical Note on the Syntax of Variable Names |
| |
| Variable names in Perl can have several formats. Usually, they |
| must begin with a letter or underscore, in which case they can be |
| arbitrarily long (up to an internal limit of 251 characters) and |
| may contain letters, digits, underscores, or the special sequence |
| C<::> or C<'>. In this case, the part before the last C<::> or |
| C<'> is taken to be a I<package qualifier>; see L<perlmod>. |
| |
| Perl variable names may also be a sequence of digits or a single |
| punctuation or control character. These names are all reserved for |
| special uses by Perl; for example, the all-digits names are used |
| to hold data captured by backreferences after a regular expression |
| match. Perl has a special syntax for the single-control-character |
| names: It understands C<^X> (caret C<X>) to mean the control-C<X> |
| character. For example, the notation C<$^W> (dollar-sign caret |
| C<W>) is the scalar variable whose name is the single character |
| control-C<W>. This is better than typing a literal control-C<W> |
| into your program. |
| |
| Finally, new in Perl 5.6, Perl variable names may be alphanumeric |
| strings that begin with control characters (or better yet, a caret). |
| These variables must be written in the form C<${^Foo}>; the braces |
| are not optional. C<${^Foo}> denotes the scalar variable whose |
| name is a control-C<F> followed by two C<o>'s. These variables are |
| reserved for future special uses by Perl, except for the ones that |
| begin with C<^_> (control-underscore or caret-underscore). No |
| control-character name that begins with C<^_> will acquire a special |
| meaning in any future version of Perl; such names may therefore be |
| used safely in programs. C<$^_> itself, however, I<is> reserved. |
| |
| Perl identifiers that begin with digits, control characters, or |
| punctuation characters are exempt from the effects of the C<package> |
| declaration and are always forced to be in package C<main>. A few |
| other names are also exempt: |
| |
| ENV STDIN |
| INC STDOUT |
| ARGV STDERR |
| ARGVOUT |
| SIG |
| |
| In particular, the new special C<${^_XYZ}> variables are always taken |
| to be in package C<main>, regardless of any C<package> declarations |
| presently in scope. |
| |
| =head1 BUGS |
| |
| Due to an unfortunate accident of Perl's implementation, C<use |
| English> imposes a considerable performance penalty on all regular |
| expression matches in a program, regardless of whether they occur |
| in the scope of C<use English>. For that reason, saying C<use |
| English> in libraries is strongly discouraged. See the |
| Devel::SawAmpersand module documentation from CPAN |
| (http://www.perl.com/CPAN/modules/by-module/Devel/) |
| for more information. |
| |
| Having to even think about the C<$^S> variable in your exception |
| handlers is simply wrong. C<$SIG{__DIE__}> as currently implemented |
| invites grievous and difficult to track down errors. Avoid it |
| and use an C<END{}> or CORE::GLOBAL::die override instead. |