1013 lines
33 KiB
Plaintext
1013 lines
33 KiB
Plaintext
=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 analogues in one of
|
|
the shells. Nevertheless, if you wish to use long variable names,
|
|
you just need to 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>.
|
|
|
|
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/Devel-SawAmpersand-0.10.readme)
|
|
for more information.
|
|
|
|
To go a step further, those variables that depend on the currently
|
|
selected filehandle may instead (and preferably) be set by calling an
|
|
object method on the FileHandle object. (Summary lines below for this
|
|
contain the word HANDLE.) First you must say
|
|
|
|
use FileHandle;
|
|
|
|
after which you may use either
|
|
|
|
method HANDLE EXPR
|
|
|
|
or more safely,
|
|
|
|
HANDLE->method(EXPR)
|
|
|
|
Each of the methods returns the old value of the FileHandle attribute.
|
|
The methods each take an optional EXPR, which if supplied specifies the
|
|
new value for the FileHandle attribute in question. If not supplied,
|
|
most of the methods do nothing to the current value, except for
|
|
autoflush(), which will assume a 1 for you, just to be different.
|
|
|
|
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 (except $^M was added in the wrong place).
|
|
This is somewhat obscured by the fact that %ENV and %SIG are listed as
|
|
$ENV{expr} and $SIG{expr}.
|
|
|
|
|
|
=over 8
|
|
|
|
=item $ARG
|
|
|
|
=item $_
|
|
|
|
The default input and pattern-searching space. The following pairs are
|
|
equivalent:
|
|
|
|
while (<>) {...} # equivalent in only while!
|
|
while (defined($_ = <>)) {...}
|
|
|
|
/^Subject:/
|
|
$_ =~ /^Subject:/
|
|
|
|
tr/a-z/A-Z/
|
|
$_ =~ tr/a-z/A-Z/
|
|
|
|
chop
|
|
chop($_)
|
|
|
|
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<E<lt>FHE<gt>>
|
|
operation's result is tested by itself as the sole criterion of a C<while>
|
|
test. Note that outside of a C<while> test, this will not happen.
|
|
|
|
=back
|
|
|
|
(Mnemonic: underline is understood in certain operations.)
|
|
|
|
=back
|
|
|
|
=over 8
|
|
|
|
=item $E<lt>I<digits>E<gt>
|
|
|
|
Contains the subpattern from the corresponding set of parentheses in
|
|
the last pattern matched, not counting patterns matched in nested
|
|
blocks that have been exited already. (Mnemonic: like \digits.)
|
|
These variables are all read-only.
|
|
|
|
=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.
|
|
|
|
The use of this variable anywhere in a program imposes a considerable
|
|
performance penalty on all regular expression matches. See the
|
|
Devel::SawAmpersand module from CPAN for more information.
|
|
|
|
=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 the
|
|
Devel::SawAmpersand module from CPAN for more information.
|
|
|
|
=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.
|
|
|
|
The use of this variable anywhere in a program imposes a considerable
|
|
performance penalty on all regular expression matches. See the
|
|
Devel::SawAmpersand module from CPAN for more information.
|
|
|
|
=item $LAST_PAREN_MATCH
|
|
|
|
=item $+
|
|
|
|
The last bracket matched by the last search pattern. This is useful if
|
|
you don't know which of a set of alternative patterns matched. For
|
|
example:
|
|
|
|
/Version: (.*)|Revision: (.*)/ && ($rev = $+);
|
|
|
|
(Mnemonic: be positive and forward looking.)
|
|
This variable is read-only.
|
|
|
|
=item $MULTILINE_MATCHING
|
|
|
|
=item $*
|
|
|
|
Set to 1 to do multi-line matching within a string, 0 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. Default
|
|
is 0. (Mnemonic: * matches multiple things.) Note that 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 Perls, supplanted by
|
|
the C</s> and C</m> modifiers on pattern matching.
|
|
|
|
=item input_line_number HANDLE EXPR
|
|
|
|
=item $INPUT_LINE_NUMBER
|
|
|
|
=item $NR
|
|
|
|
=item $.
|
|
|
|
The current input line number for the last file handle from
|
|
which you read (or performed 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 L<$/> on how
|
|
to affect that. An
|
|
explicit close on a filehandle resets the line number. Because
|
|
"C<E<lt>E<gt>>" never does an explicit close, line numbers increase
|
|
across ARGV files (but see examples under eof()). 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 is used to
|
|
influence Perl's idea of what a "line" is. Works like B<awk>'s RS
|
|
variable, including treating empty lines as delimiters if set to the
|
|
null string. (Note: An empty line cannot contain any spaces or tabs.)
|
|
You may set it to a multi-character string to match a multi-character
|
|
delimiter, or to C<undef> to read to end of file. Note that setting it
|
|
to C<"\n\n"> means something slightly different than setting it to
|
|
C<"">, if the file contains consecutive empty lines. Setting it to
|
|
C<""> will treat two or more consecutive empty lines as a single empty
|
|
line. Setting it to C<"\n\n"> will blindly assume that the next input
|
|
character belongs to the next paragraph, even if it's a newline.
|
|
(Mnemonic: / is used to delimit line boundaries when quoting poetry.)
|
|
|
|
undef $/; # enable "slurp" mode
|
|
$_ = <FH>; # whole file now here
|
|
s/\n[ \t]+/ /g;
|
|
|
|
Remember: the value of $/ is a string, not a regexp. AWK has to be
|
|
better for something :-)
|
|
|
|
Setting $/ to a reference to an integer, scalar containing an integer, or
|
|
scalar that's convertable 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
|
|
likely not a problem, as any file you'd want to read in record mode is
|
|
probably usable in line mode) Non-VMS systems perform normal I/O, so
|
|
it's safe to mix record and non-record reads of a file.
|
|
|
|
Also see L<$.>.
|
|
|
|
=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 actually buffered by the system or not; C<$|> tells you
|
|
only whether you've asked Perl explicitly to flush after each write).
|
|
Note that 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, such as when you are running
|
|
a Perl script under rsh and want to see the output as it's happening. This
|
|
has no effect on input buffering.
|
|
(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 the comma-separated fields you
|
|
specify. 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 the comma-separated fields you
|
|
specify, with no trailing newline or record separator assumed.
|
|
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 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>. Note that 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.
|
|
|
|
=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 is in fact
|
|
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.
|
|
(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. (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. (Mnemonic: lines_on_page - lines_printed.)
|
|
|
|
=item format_name HANDLE EXPR
|
|
|
|
=item $FORMAT_NAME
|
|
|
|
=item $~
|
|
|
|
The name of the current report format for the currently selected output
|
|
channel. Default is 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 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 to perform a form feed. Default is \f.
|
|
|
|
=item $ACCUMULATOR
|
|
|
|
=item $^A
|
|
|
|
The current value of the write() accumulator for format() lines. A format
|
|
contains formline() commands that put their result into C<$^A>. After
|
|
calling its format, write() prints out the contents of C<$^A> and empties.
|
|
So you never actually 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,
|
|
or system() operator. Note that this is the 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 actually (C<$? E<gt>E<gt> 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 of the C<gethost*()> functions fail.
|
|
|
|
Note that 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 the script.
|
|
|
|
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 in a numeric context, yields the current value of errno, 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 in a string
|
|
context, yields the corresponding system error string. You can assign
|
|
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() command. 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"?)
|
|
|
|
Note that 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. (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.)
|
|
Note: "C<$E<lt>>" and "C<$E<gt>>" 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 is used to set 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.)
|
|
|
|
Note: "C<$E<lt>>", "C<$E<gt>>", "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 file containing the Perl script being
|
|
executed. On some operating systems
|
|
assigning to "C<$0>" modifies the argument area that the ps(1)
|
|
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>.)
|
|
|
|
=item $[
|
|
|
|
The index of the first element in an array, and of the first character
|
|
in a substring. Default is 0, but you could 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 Perl 5, assignment to "C<$[>" is treated as a compiler directive,
|
|
and cannot influence the behavior of any other file. Its use is
|
|
discouraged.
|
|
|
|
=item $PERL_VERSION
|
|
|
|
=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 Perl interpreter is too old.
|
|
|
|
=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 behaviour when being compiled.
|
|
(For example to automatically AUTOLOADing at compile time rather than normal
|
|
deferred loading.) 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.) Note that the close-on-exec
|
|
status of a file descriptor will be decided according to the value of
|
|
C<$^F> when the open() or pipe() was called, not the time of the exec().
|
|
|
|
=item $^H
|
|
|
|
The current set of syntax checks enabled by C<use strict> and other block
|
|
scoped compiler hints. See the documentation of C<strict> for more details.
|
|
|
|
=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 it is not trappable. However, if
|
|
compiled for this, Perl may use the contents of C<$^M> as an emergency
|
|
pool after die()ing with this message. 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 when in emergency. See the F<INSTALL>
|
|
file for information on how to enable this option. As a disincentive to
|
|
casual use of this advanced feature, there is no L<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'}>.
|
|
|
|
=item $PERLDB
|
|
|
|
=item $^P
|
|
|
|
The internal variable for debugging support. Different bits mean the
|
|
following (subject to change):
|
|
|
|
=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.
|
|
|
|
=back
|
|
|
|
Note that 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 $^R
|
|
|
|
The result of evaluation of the last successful L<perlre/C<(?{ code })>>
|
|
regular expression assertion. (Excluding those used as switches.) May
|
|
be written to.
|
|
|
|
=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 script 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 $WARNING
|
|
|
|
=item $^W
|
|
|
|
The current value of the warning switch, either TRUE or FALSE.
|
|
(Mnemonic: related to the B<-w> switch.)
|
|
|
|
=item $EXECUTABLE_NAME
|
|
|
|
=item $^X
|
|
|
|
The name that the Perl binary itself was executed as, from C's C<argv[0]>.
|
|
|
|
=item $ARGV
|
|
|
|
contains the name of the current file when reading from E<lt>E<gt>.
|
|
|
|
=item @ARGV
|
|
|
|
The array @ARGV contains the command line arguments intended for the
|
|
script. Note that C<$#ARGV> is the generally number of arguments minus
|
|
one, because C<$ARGV[0]> is the first argument, I<NOT> the command name. See
|
|
"C<$0>" for the command name.
|
|
|
|
=item @INC
|
|
|
|
The array @INC contains the list of places to look for Perl scripts to
|
|
be evaluated by the C<do EXPR>, C<require>, or C<use> constructs. 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 that has
|
|
been included via C<do> or C<require>. The key is the filename you
|
|
specified, and the value is the location of the file actually found.
|
|
The C<require> command uses this array to determine whether a given 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 child processes.
|
|
|
|
=item %SIG
|
|
|
|
=item $SIG{expr}
|
|
|
|
The hash %SIG is used to set signal handlers for various
|
|
signals. 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.
|
|
|
|
The %SIG array contains values for only the signals actually set within
|
|
the Perl script. Here are some other examples:
|
|
|
|
$SIG{"PIPE"} = Plumber; # SCARY!!
|
|
$SIG{"PIPE"} = "Plumber"; # assumes main::Plumber (not recommended)
|
|
$SIG{"PIPE"} = \&Plumber; # just fine; assume current Plumber
|
|
$SIG{"PIPE"} = Plumber(); # oops, what did Plumber() return??
|
|
|
|
The one marked scary is problematic because it's a bareword, which means
|
|
sometimes it's a string representing the function, and sometimes it's
|
|
going to call the subroutine call right then and there! Best to be sure
|
|
and quote it or take a reference to it. *Plumber works too. See L<perlsub>.
|
|
|
|
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 it 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__>.
|
|
|
|
Note that the C<$SIG{__DIE__}> hook is called even inside eval()ed
|
|
blocks/strings. See L<perlfunc/die> and L<perlvar/$^S> for how to
|
|
circumvent this.
|
|
|
|
Note that 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 calls which result/may-result
|
|
in 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> and L<perlfunc/eval> for
|
|
additional info.
|
|
|
|
=back
|
|
|
|
=head2 Error Indicators
|
|
|
|
The variables L<$@>, L<$!>, L<$^E>, and L<$?> contain information about
|
|
different types of error conditions that may appear during execution of
|
|
Perl script. The variables are shown ordered by the "distance" between
|
|
the subsystem which reported the error and the Perl process, and
|
|
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:
|
|
|
|
eval '
|
|
open PIPE, "/cdrom/install |";
|
|
@res = <PIPE>;
|
|
close PIPE or die "bad pipe: $?, $!";
|
|
';
|
|
|
|
After execution of this statement all 4 variables may have been set.
|
|
|
|
$@ 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 (either implicitly, say,
|
|
if C<open> was imported from module L<Fatal>, or the C<die> after
|
|
C<close> was triggered). In these cases the value of $@ is the compile
|
|
error, or C<Fatal> error (which will interpolate C<$!>!), or the argument
|
|
to C<die> (which will interpolate C<$!> and C<$?>!).
|
|
|
|
When the above expression is executed, open(), C<<PIPEE<gt>>, and C<close>
|
|
are translated to C run-time library calls. $! is set if one of these
|
|
calls fails. The value is a symbolic indicator chosen by the C run-time
|
|
library, say C<No such file or directory>.
|
|
|
|
On some systems the above C library calls are further translated
|
|
to calls to the kernel. The kernel may have set more verbose error
|
|
indicator that one of the handful of standard C errors. In such cases $^E
|
|
contains this verbose error indicator, which may be, say, C<CDROM tray not
|
|
closed>. On systems where C library calls are identical to system calls
|
|
$^E is a duplicate of $!.
|
|
|
|
Finally, $? may be set to non-C<0> value if the external program
|
|
C</cdrom/install> fails. Upper bits of the particular value may reflect
|
|
specific error conditions encountered by this program (this is
|
|
program-dependent), lower-bits reflect mode of failure (segfault, completion,
|
|
etc.). Note that in contrast to $@, $!, and $^E, which are set only
|
|
if error condition is detected, the variable $? is set on each C<wait> or
|
|
pipe C<close>, overwriting the old value.
|
|
|
|
For more details, see the individual descriptions at L<$@>, L<$!>, L<$^E>,
|
|
and L<$?>.
|
|
|
|
|
|
=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 256 characters) and may
|
|
contain letters, digits, underscores, or the special sequence C<::>.
|
|
In this case the part before the last 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 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.
|
|
|
|
All Perl variables 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
|
|
|