We've alphabetized these entries according to the long variable name. If you don't know the long name of a variable, you can find it in the previous section. (Variables without alphabetical names are sorted to the front.)
So that we don't have to keep repeating ourselves, each variable description starts with one or more of these annotations:
Annotation | Meaning |
---|---|
XXX | Deprecated, do not use in anything new. |
NOT | Not Officially There (internal use only). |
ALL | Truly global, shared by all packages. |
PKG | Package global; each package can have its own. |
FHA | Filehandle attribute; one per I/O object. |
DYN | Dynamically scoped automatically (implies ALL). |
LEX | Lexically scoped at compile time. |
RO | Read only; raises an exception if you modify. |
When more than one variable name or symbol is listed, only the
short one is available by default. Using the
English
module makes the longer synonyms available
to the current package, and only to the current package, even if the
variable is marked [ALL].
Entries of the form method
HANDLE EXPR
show object-oriented interfaces to the
per-filehandle variables provided by the FileHandle
and various IO:
: modules. (You may also use the
HANDLE
->
method
(
EXPR
)
notation if you prefer.) These let you avoid having to call
select
to change the default output handle before
examining or changing that variable. Each such method returns the old
value of the FileHandle
attribute; a new value is
set if the EXPR
argument is supplied. If
not supplied, most of the methods do nothing to the current value,
except for autoflush
, which assumes an argument of
1
, just to be different.
_
(underline)[ALL] This is the special filehandle used to cache the
information from the last successful stat
,
lstat
, or file test operator (like
-w $file
or -d
$file
).
$
digits
[DYN,RO] The numbered variables
$1
, $2
, and so on (up just
as high as you want)[1] contain the text that is matched by the
corresponding set of parentheses in the last matched pattern
within the currently active dynamic scope. (Mnemonic: like
digits
.)
$[
[XXX,LEX] The index of the first element in an
array and of the first character in a substring. Default is 0,
but we used to set it to 1 to make Perl behave more like
awk (or FORTRAN) when subscripting and when
evaluating the index
and
substr
functions. Because it was found to be
so dangerous, assignment to $[
is now treated
as a lexically scoped compiler directive and cannot influence
the behavior of any other file. (Mnemonic: [
begins subscripts.)
$#
[XXX,ALL] Don't use this; use
printf
instead. $#
contains the output format for printed numbers, in a
half-hearted attempt to emulate awk's
OFMT
variable. (Mnemonic:
#
is the number sign, but if you're sharp,
you'll just forget it so you don't make a hash of your program
and get pounded for it.)
$*
[XXX,ALL] Wow, three deprecated variables in a
row! This one can (but shouldn't) be set to true to get Perl to
assume /m
on every pattern match that doesn't
have an explicit /s
. (Mnemonic:
*
matches multiple things.)
$a
[PKG] This variable is used by the
sort
function to hold the first of each pair
of values to be compared ($b
is the second of
each pair). The package for $a
is the same
one that the sort
operator was compiled in,
which is not necessarily the same as the one its comparison
function was compiled into. This variable is implicitly
localized within the sort
comparison block.
Because it is a global, it is exempt from use
strict
complaints. Because it is an alias for the
actual array value, you might think you can modify it, but you
shouldn't. See the sort
function.
$ACCUMULATOR
$^A
[ALL] The current value of the
write
accumulator for
format
lines. A format contains
formline
commands that put their result into
$^A
. After calling its format,
write
prints out the contents of
$^A
and empties it. So you never actually see
the contents of $^A
unless you call
formline
yourself and then look at it. See
the formline
function.
$ARG
$_
[ALL] The default input and pattern-search space. These pairs are equivalent:
while (<>) {…} # equivalent only in unadorned while test while (defined($_ = <>)) {…} chomp chomp($_) /^Subject:/ $_ =~ /^Subject:/ tr/a-z/A-Z/ $_ =~ tr/a-z/A-Z/
Here are the places where Perl will assume
$_
if you don't specify something to operate
on:
List functions like print
and
unlink
, and unary functions like
ord
, pos
, and
int
, as well as the all file tests
(except for -t
, which defaults to
STDIN
). All functions that default to
$_
are so marked in Chapter 29.
The pattern-matching operations m//
and s///
and the transliteration
operations y///
and
tr///
, when used without an
=~
operator.
The iterator variable in a foreach
loop (even when spelled for
or when used
as a statement modifier) if no other variable is
supplied.
The implicit iterator variable in the
grep
and map
functions. (There is no way to specify a different variable
for these.)
The default place to put an input record when a
<FH>
, readline
,
or glob
operation's result is tested by
itself as the sole criterion of a while
test. This assignment does not occur outside of a
while
test or if any additional elements
are included in the while
expression.
(Mnemonic: underline is the underlying operand in certain operations.)
@ARG
@_
[ALL] Within a subroutine, this array holds the
argument list passed to that subroutine. See Chapter 6. A
split
in scalar context splits to this array,
but this usage is deprecated.
ARGV
[ALL] The special filehandle that iterates over
command-line filenames in @ARGV
. Usually
written as the null filehandle in the angle operator:
<>
.
$ARGV
[ALL] Contains the name of the current file when
reading from the ARGV
handle using the
<>
or readline
operators.
@ARGV
[ALL] The array containing the command-line
arguments intended for the script. Note that
$#ARGV
is generally the number of arguments
minus one, since $ARGV[0]
is the first
argument, not the command name; use scalar
@ARGV
for the number of program arguments. See
$0
for the program name.
ARGVOUT
[ALL] The special filehandle is used while
processing the ARGV
handle under the
-i
switch or the $^I
variable. See the -i
switch in Chapter 19.
$b
[PKG] The variable, companion to $a
,
used in sort
comparisons. See
$a
and the sort
function
for details.
$BASETIME
$^T
[ALL] The time at which the script began running,
in seconds since the epoch (the beginning of 1970, for Unix
systems). The values returned by the -M
,
-A
, and -C
file tests are
relative to this moment.
$CHILD_ERROR
$?
[ALL] The status returned by the last pipe close,
backtick (``
) command, or
wait
, waitpid
, or
system
functions. Note that this is not just
the simple exit code, but the entire 16-bit status word returned
by the underlying wait (2) or
waitpid (2) syscall (or
equivalent). Thus, the exit value of the subprocess is in the
high byte, that is, $? >> 8
; in the low
byte, $? & 127
says which signal (if any)
the process died from, while $? & 128
reports whether its demise produced a core dump. (Mnemonic:
similar to $?
in the sh
and its offspring.)
Inside an END
block,
$?
contains the value that is going to be
given to exit
. You can modify
$?
in an END
to change the
exit status of the script.
Under VMS, the pragma use vmsish
'status
' makes $?
reflect the true
VMS exit status, instead of the default emulation of POSIX
status.
If the h_errno
variable is supported in
C, its numeric value is returned via $?
if
any of the gethost*()
functions fail.
$COMPILING
$^C
[ALL] The current value of the internal flag
associated with the -c
switch, mainly of
use with -MO
and the
perlcc (1) tool to let code alter
its behavior when being compiled for code generation. For
example, you might want to AUTOLOAD
at
compile time instead of using the normal, deferred loading so
that code can be generated right away. See Chapter 18.
DATA
[PKG] This special filehandle refers to anything
following either the __END__
token or the
__DATA__
token in the current file. The
__END__
token always opens the
main::DATA
filehandle, and so is used in the
main program. The __DATA__
token opens the
DATA
handle in whichever package is in effect
at the time, so different modules can each have their own
DATA
filehandle, since they (presumably) have
different package names.
$DEBUGGING
$^D
[ALL] The current value of the internal debugging
flags, set from the -D
switch on the
command line; see Chapter
19 for the bit values. (Mnemonic: value of the
-D
switch.)
$EFFECTIVE_GROUP_ID
$EGID
$)
[ALL] The effective GID (group ID) 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 (2),
and the subsequent ones by getgroups
(2), one of which may be the same as the first
number.
Similarly, a value assigned to $)
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 the setgroups
(2) syscall. To get the effect of an empty list for
setgroups
, just repeat the new effective GID;
for example, to force an effective GID of 5 and
an effectively empty setgroups
list,
say:
$) = "5 5";
(Mnemonic: parentheses are used to
group things. The effective GID is the
group that's right for you, if you're
running setgid.) Note: $<
,
$>
, $(
, and
$)
can only be set on machines that support
the corresponding system set-id routine. $(
and $)
can be swapped only on machines
supporting setregid (2).
$EFFECTIVE_USER_ID
$EUID
$>
[ALL] The effective UID of this process as returned by the geteuid (2) syscall. Example:
$< = $>; # set real to effective uid ($<,$>) = ($>,$<); # swap real and effective uid
(Mnemonic: it's the UID you went to,
if you're running setuid.) Note: $<
and
$>
can only be swapped on machines
supporting setreuid (2). And
sometimes not even then.
%ENV
[ALL] The hash containing your current
environment variables. Setting a value in
%ENV
changes the environment for both your
process and child processes launched after the assignment. (It
cannot change a parent process's environment on any system
resembling Unix.)
$ENV{PATH} = "/bin:/usr/bin"; $ENV{PAGER} = "less"; $ENV{LESS} = "MQeicsnf"; # our favorite switches to less(1) system "man perl"; # picks up new settings
To remove something from your environment, make sure to
use the delete
function instead of
undef
on the hash value.
Note that processes running as
crontab (5) entries inherit a
particularly impoverished set of environment variables. (If your
program runs fine from the command line but not under
cron, this is probably why.) Also note that
you should set $ENV{PATH}
,
$ENV{SHELL}
,
$ENV{BASH_ENV}
, and
$ENV{IFS}
if you are running as a setuid
script. See Chapter
23.
$EVAL_ERROR
$@
[ALL] The currently raised exception or the Perl
syntax error message from the last eval
operation. (Mnemonic: where was the syntax error
“at”?) Unlike $!
($OS_ERROR
), which is set on failure but not
cleared on success, $@
is guaranteed to be
set (to a true value) if the last eval
had a
compilation error or run-time exception, and guaranteed to be
cleared (to a false value) if no such problem occurred.
Warning messages are not collected in this variable. You
can, however, set up a routine to process warnings by setting
$SIG{__WARN__}
as described later in this
section.
Note that the value of $@
may be an
exception object rather than a string. If so, you can still
probably treat it as a string if the exception object has
stringification overloading defined for its class. If you
propagate an exception by saying:
die if $@;
then an exception object will call
$@->PROPAGATE
to see what to do. (A string
exception merely adds a "propagated at" line to the
string.)
$EXCEPTIONS_BEING_CAUGHT
$^S
[ALL] This variable reflects the current state of
the interpreter, returning true if inside an
eval
, false otherwise. It's undefined if
parsing of the current compilation unit hasn't finished yet,
which may be the case in $SIG{__DIE__}
and
$SIG{__WARN__}
handlers. (Mnemonic: state of
eval
.)
$EXECUTABLE_NAME
$^X
[ALL] The name that the perl
binary itself was executed as, from C's
argv[0]
.
@EXPORT
[PKG] This array variable is consulted by the
Exporter
module's import
method to find the list of other package variables and
subroutines to be exported by default when the module is
use
d, or when the :DEFAULT
import tag is used. It is not exempt from use
strict
complaints, so it must be declared with
our
or fully qualified by package name if
you've enabled that pragma. However, all variables whose names
begin with the string "EXPORT
" are exempt
from warnings about being used only once. See Chapter 11.
@EXPORT_OK
[PKG] This array variable is consulted by the
Exporter
module's import
method to determine whether a requested import is legal. It is
not exempt from use strict
. See Chapter 11.
%EXPORT_TAGS
[PKG] This hash variable is consulted by the
Exporter
module's import
method when an import symbol with a leading colon is requested,
as in use POSIX ":sys_wait_h
". The keys are
the colon tags, but without the loading colon. The values should
be references to arrays containing symbols to import when the
colon tag is requested, all of which must also appear in either
@EXPORT
or @EXPORT_OK
. It
is not exempt from use strict
. See Chapter 11.
$EXTENDED_OS_ERROR
$^E
[ALL] Error information specific to the current operating
system. Under Unix, $^E
is identical to
$!
($OS_ERROR
), but it
differs under OS/2, VMS, and Microsoft systems, and on MacPerl.
See your port's information for specifics. Caveats mentioned in
the description of $!
generally apply to
$^E
as well. (Mnemonic: extra error
explanation.)
@F
[PKG] The array into which the input line's
fields are split when the -a
command-line
switch is given. If the
-a
option is not used, this array has no
special meaning. (This array is actually only
@main::F
, and not in all packages at
once.)
%FIELDS
[NOT,PKG] This hash is for internal use by the
use fields
pragma to determine the current
legal fields in an object hash. See use
fields
, use base
, and "Field
Declarations with use fields" in Chapter 12.
format_formfeed
HANDLE
EXPR
$FORMAT_FORMFEED
$^L
[ALL] What a write
function
implicitly outputs to perform a form feed before it emits a top
of form header. Default is "f
".
format_lines_left
HANDLE
EXPR
$FORMAT_LINES_LEFT
$-
[FHA] The number of lines left on the page of the
currently selected output handle, for use with the
format
declaration and the
write
function. (Mnemonic:
lines_on_page - lines_printed
.)
format_lines_per_page
HANDLE
EXPR
$FORMAT_LINES_PER_PAGE
$=
[FHA] The current page length (printable lines)
of the currently selected output handle, for use with
format
and write
. Default
is 60. (Mnemonic: =
has horizontal
lines.)
format_line_break_characters
HANDLE EXPR
$FORMAT_LINE_BREAK_CHARACTERS
$
: [ALL] The current set of characters after which a
string may be broken to fill continuation fields (starting with
^
) in a format. Default is "
-
", to break on whitespace or hyphens. (Mnemonic: a
colon is a technical word meaning part of a line in poetry. Now
you just have to remember the mnemonic...)
format_name
HANDLE
EXPR
$FORMAT_NAME
$~
[FHA] The name of the current report format for
the currently selected output handle. Default is the
filehandle's name. (Mnemonic: takes a turn after
$^
.)
format_page_number
HANDLE
EXPR
$FORMAT_PAGE_NUMBER
$%
[FHA] The current page number of the currently
selected output handle, for use with format
and write
. (Mnemonic: %
is
the page number register in troff (1).
What, you don't know what troff is?)
format_top_name
HANDLE
EXPR
$FORMAT_TOP_NAME
$^
[FHA] The name of the current top-of-page format
for the currently selected output handle. Default is name of the
filehandle with _TOP
appended. (Mnemonic:
points to top of page.)
$^H
[NOT,LEX] This variable contains lexically scoped status bits (a.k.a. hints) for the Perl parser. This variable is strictly for internal use only. Its availability, behavior, and contents are subject to change without notice. If you touch it, you will undoubtedly die a horrible death of some loathsome tropical disease unknown to science. (Mnemonic: we won't give you a hint.)
%^H
[NOT,LEX] The %^H
hash provides the
same lexical scoping semantics as $^H
, making
it useful for implementation of lexically scoped pragmas. Read
the dire warnings listed under $^H
, and then
add to them the fact that this variable is still
experimental.
%INC
[ALL] The hash containing entries for the filename of each
Perl file loaded via do
FILE
, require
, or
use
. The key is the filename you specified,
and the value is the location of the file actually found. The
require
operator uses this array to determine
whether a given file has already been loaded. For
example:
% perl -MLWP::Simple -le 'print $INC{"LWP/Simple.pm"}'
/opt/perl/5.6.0/lib/site_perl/LWP/Simple.pm
@INC
[ALL] The array containing the list of
directories where Perl modules may be found by
do
FILE
,
require
, or use
. It
initially consists of the arguments to any
-I
command-line switches and directories
in the PERL5LIB
environment variable,
followed by the default Perl libraries, such as:
/usr/local/lib/perl5/5.6.0/sun4-solaris /usr/local/lib/perl5/5.6.0 /usr/local/lib/perl5/site_perl/5.6.0/sun4-solaris /usr/local/lib/perl5/site_perl/5.6.0 /usr/local/lib/perl5/site_perl/5.00552/sun4-solaris /usr/local/lib/perl5/site_perl/5.00552 /usr/local/lib/perl5/site_perl/5.005/sun4-solaris /usr/local/lib/perl5/site_perl/5.005 /usr/local/lib/perl5/site_perl
followed by ".", to represent the current directory. If
you need to modify this list from within your program, try the
use lib
pragma, which not only modifies the
variable at compile time, but also adds in any related
architecture-dependent directories (such as those that contain
the shared libraries used by XS modules):
use lib "/mypath/libdir/"; use SomeMod;
$INPLACE_EDIT
$^I
[ALL] The current value of the inplace-edit extension. Use
undef
to disable inplace editing. You can use
this from within your program to get the same behavior as the
-i
switch provides. For example, to do
the equivalent of this command:
% perl -i.orig -pe 's/foo/bar/g' *.c
you can use the following equivalent code in your program:
local $^I = '.orig'; local @ARGV = glob("*.c"); while (<>) { s/foo/bar/g; print; }
(Mnemonic: value of the -i
switch.)
$INPUT_LINE_NUMBER
$NR
$
. [ALL] The current record number (usually line
number) for the last filehandle you read from (or called
seek
or 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
$/
($INPUT_RECORD_SEPARATOR
) on how to affect
that. An explicit close on a filehandle resets the line number.
Because <>
never does an explicit
close, line numbers increase across ARGV
files (but see examples under eof
).
Localizing $
. also localizes Perl's notion of
"the last read filehandle". (Mnemonic: many programs use "." to
mean the current line number.)
$INPUT_RECORD_SEPARATOR
$RS
$/
[ALL] The input record separator, newline by
default, which is consulted by the readline
function, the <FH>
operator, and the
chomp
function. It works like
awk's RS
variable, and,
if set to the null string, treats one or more blank lines as a
record terminator. (But a blank line must contain no hidden
spaces or tabs.) You may set it to a multicharacter string to
match a multicharacter terminator, but you may not set it to a
pattern--awk has to be better at
something.
Note that setting $/
to
"
" means something slightly different
than setting it to "", if the file contains consecutive blank
lines. Setting it to "" will treat two or
more consecutive blank lines as a single
blank line. Setting it to "
" means Perl
will blindly assume that a third newline belongs to the next
paragraph.
Entirely undefining $/
makes the next
line input operation slurp in the remainder of the file as one
scalar value:
undef $/; # enable whole-file mode $_ = <FH>; # whole file now here s/ [ ]+/ /g; # fold indented lines
If you're using the while (<>)
construct to access ARGV
handle while
$/
is undefined, each read gets the next
file:
undef $/; while (<>) { # $_ has the whole next file in it … }
Although we used undef
above, it's
safer to undefine $/
using
local
:
{ local $/; $_ = <FH>; }
Setting $/
to a reference to either an
integer, a scalar containing an integer, or a scalar that's
convertible to an integer will make readline
and <FH>
operations read in
fixed-length records (with the maximum record size being the
referenced integer) instead of variable-length record terminated
by a particular string. So this:
$/ = 32768; # or "32768" or $scalar_var_containing_32768 open(FILE, $myfile); $record = <FILE>;
will read a record of no more than 32,768 bytes from the
FILE
handle. If you're not reading from a
record-oriented file (or your operating system 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. Record mode
mixes well with line mode only on systems where standard I/O
supplies a read (3) function; VMS
is a notable exception.
Calling chomp
when
$/
is set to enable record mode--or when it
is undefined--has no effect. See also the
-0
(the digit) and the
-l
(the letter) command-line switches in
Chapter 19. (Mnemonic:
/
is used to separate lines when quoting
poetry.)
@ISA
[PKG] This array contains names of other packages
to look through when a method call cannot be found in the
current package. That is, it contains the base classes of the
package. The use base
pragma sets this
implicitly. It is not exempt from use strict
.
See Chapter 12.
@LAST_MATCH_END
@+
This array holds the offsets of the ends of the
last successful submatches in the currently active dynamic
scope. $+[0]
is the offset of the end of the
entire match. This is the same value the pos
function returns when called on the variable that was matched
against. (When we say "offset of the end", we really mean the
offset to the first character following the
end of whatever matched, so that we can subtract beginning
offsets from end offsets and arrive at the length.) The
nth element of this array holds the offset
of the nth submatch, so
$+[1]
is the offset where
$1
ends, $+[2]
the offset
where $2
ends, and so on. You can use
$#+
to determine how many subgroups were in
the last successful match. See also @-
(@LAST_MATCH_START
).
After a successful match against some variable
$var
:
@LAST_MATCH_START
@-
[DYN,RO] This array holds the offsets of the
beginnings of the last successful submatches in the currently
active dynamic scope. $-[0]
is the offset of
the beginning of the entire match. The nth
element of this array holds the offset of the
nth submatch, so $-[1]
is the offset where $1
begins,
$-[2]
the offset where $2
begins, and so on. You can use $#-
to
determine how many subgroups were in the last successful match.
See also @+
(@LAST_MATCH_END
).
$LAST_PAREN_MATCH
$+
[DYN,RO] This returns the last parenthesized submatch from the last successful pattern in the currently active dynamic scope. This is useful when you don't know (or care) which of a set of alternative patterns matched. (Mnemonic: be positive and forward looking.) Example:
$rev = $+ if /Version: (.*)|Revision: (.*)/;
$LAST_REGEXP_CODE_RESULT
$^R
[DYN] This contains the result of the last snippet of code
executed inside a successful pattern with the
(?{
CODE
})
construct. $^R
gives you a way to execute
code and remember the result for use later in the pattern, or
even afterward.
As the Perl regular expression engine moves through the
pattern, it may encounter multiple
(?{
CODE
})
expressions. As it does, it remembers each value of
$^R
so that if it later has to backtrack past
an expression, it restores the previous value of
$^R
. In other words, $^R
has a dynamic scope within the pattern, much like
$1
and friends.
So $^R
is not simply the result of the
last snippet of code executed inside a pattern. It's the result
of the last snippet of code leading to a successful
match. A corollary is that if the match was not
successful, $^R
will be restored to whatever
value it had before the match occurred.
If the
(?{
CODE
})
pattern is functioning directly as the conditional of a
(?(
COND
)
IFTRUE
|
IFFALSE
)
subpattern, $^R
is not set.
$LIST_SEPARATOR
$
"[ALL] When an array or slice is interpolated into a double-quoted string (or the like), this variable specifies the string to put between individual elements. Default is a space. (Mnemonic: obvious, one hopes.)
$^M
[ALL] By default, running out of memory is not
trappable. However, if your perl was
compiled to take advantage of $^M
, you may
use it as an emergency memory pool. If your Perl is compiled
with -DPERL_EMERGENCY_SBRK
and uses
Perl's malloc
, then:
$^M = 'a' x (1 << 16);
would allocate a 64K buffer for emergency use. See the
INSTALL file in the Perl source
distribution directory for information on how to enable this
option. As a disincentive to casual use of this advanced
feature, there is no use English
long name
for this variable (and we won't tell you what the mnemonic
is).
$MATCH
$&
[DYN,RO] The string matched by the last
successful pattern match in the currently active dynamic scope.
(Mnemonic: like &
in some
editors.)
$OLD_PERL_VERSION
$]
[ALL] Returns the version + patchlevel/1000. It can be used to determine at the beginning of a script whether the Perl interpreter executing the script is in the right range of versions. (Mnemonic: is this version of Perl in the right bracket?) Example:
warn "No checksumming! " if $] < 3.019; die "Must have prototyping available " if $] < 5.003;
See also the documentation of use
VERSION
and
require
VERSION
for a convenient way to fail if the Perl interpreter is too old.
See $^V
for a more flexible UTF-8
representation of the Perl version.
$OSNAME
$^O
[ALL] This variable contains the name of the
platform (usually the operating system) the current
perl binary was compiled for. It's a cheap
alternative to pulling it out of the Config
module.
$OS_ERROR
$ERRNO
$!
[ALL] If used in a numeric context, yields the
current value of the last syscall error, with all the usual
caveats. (This means that you shouldn't depend on the value of
$!
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 an error
number to $!
if, for instance, you want
$!
to return the string for that particular
error, or you want to set the exit value for
die
. See also the Errno
module in Chapter 32.
(Mnemonic: what just went bang?)
%OS_ERROR
%ERRNO
%!
[ALL] This hash is defined only if you've loaded the
standard Errno
module described in Chapter 32. Once you've done
this, you can subscript into %!
using a
particular error string, and its value is true only if that's
the current error. For example, $!{ENOENT}
is
true only if the C errno
variable is
currently set to the C #define
value,
ENOENT
. This is convenient for accessing
vendor-specific symbols.
autoflush
HANDLE
EXPR
$OUTPUT_AUTOFLUSH
$AUTOFLUSH
$|
[FHA] If set to true, forces a buffer flush after
every print
, printf
, and
write
on the currently selected output
handle. (We call this command buffering.
Contrary to popular belief, setting this variable does not turn
off buffering.) The default is false, which on many systems
means that STDOUT
will be line buffered if
output is to the terminal, and block buffered otherwise, even on
pipes and sockets. Setting this variable is useful when you are
outputting to a pipe, such as when you are running a Perl script
under rsh (1) and want to see the
output as it's happening. If you have pending, unflushed data in
the currently selected filehandle's output buffer when this
variable is set to true, that buffer will be immediately flushed
as a side-effect of assignment. See the one-argument form of
select
for examples of controlling buffering
on filehandles other than STDOUT
. (Mnemonic:
when you want your pipes to be piping hot.)
This variable has no effect on input buffering; for that,
see getc
in Chapter 29 or the example in the
POSIX
module in Chapter 32.
$OUTPUT_FIELD_SEPARATOR
$OFS
$
, [ALL] The output field separator (terminator,
actually) for print
. Ordinarily,
print
simply prints out the list elements you
specify without anything between them. Set this variable as you
would set awk's OFS
variable to specify what is printed between fields. (Mnemonic:
what is printed when there is a "," in your
print
statement.)
$OUTPUT_RECORD_SEPARATOR
$ORS
$
[ALL] The output record separator (terminator,
actually) for print
. Ordinarily,
print
simply prints out the comma-separated
fields you specify, with no trailing newline or record separator
assumed. Set this variable as you would set
awk's ORS
variable to
specify what is printed at the end of the
print
. (Mnemonic: you set
$
instead of adding "
"
at the end of the print. Also, it's just like
/
, but it's what you get "back" from Perl.)
See also the -l
(for "line") command-line
switch in Chapter
19.
%OVERLOAD
[NOT,PKG] This hash's entries are set internally by the
use overload
pragma to implement operator
overloading for objects of the current package's class. See
Chapter 13.
$PERLDB
$^P
[NOT,ALL] The internal variable for enabling the Perl debugger (perl -d).
$PERL_VERSION
$^V
[ALL] The revision, version, and subversion of
the Perl interpreter, represented as a binary "version string".
V-strings don't generally have a a numeric value, but this
variable is dual-valued, and has a numeric value equivalent to
the old $]
variable; that is, a
floating-point number that amounts to revision + version/1000 +
subversion/1,000,000. The string value is made of UTF-8
characters: chr($revision) . chr($version) .
chr($subversion)
. This means that
$^V
is not printable. To
print it, you have to say:
printf "%vd", $^V;
On the plus side, it also means that ordinary string comparison can be used to determine whether the Perl interpreter executing your script is in the right range of versions. (This applies to any version numbers represented with v-strings, not just Perl's.) Example:
warn "No 'our' declarations! " if $^V lt v5.6;
See the documentation of use
VERSION
and
require
VERSION
for a convenient way to fail if the running Perl interpreter is
older than you were hoping. See also $]
for
the original representation of the Perl version.
$POSTMATCH
$
'[DYN,RO] The string following whatever was matched by the last successful pattern in the currently active dynamic scope. (Mnemonic: ' often follows a quoted string.) Example:
$_ = 'abcdefghi'; /def/; print "$`:$&:$' "; # prints abc:def:ghi
Thanks to dynamic scope, Perl can't know which patterns
will need their results saved away into these variables, so
mentioning $`
or $
'
anywhere in a program incurs a performance penalty on all
pattern matches throughout the program. This isn't much of an
issue in small programs, but you probably should avoid this pair
when you're writing reusable module code. The example above can
be equivalently recoded like this, but without the global
performance hit:
$_ = 'abcdefghi'; /(.*?)(def)(.*)/s; # /s in case $1 contains newlines print "$1:$2:$3 "; # prints abc:def:ghi
$PREMATCH
$`
[DYN,RO] The string preceding whatever was
matched by the last successful pattern in the currently active
dynamic scope. (Mnemonic: `
often precedes a
quoted string.) See the performance note under
$
' previously.
$PROCESS_ID
$PID
$$
[ALL] The process number (PID) of the Perl
running this script. This variable is automatically updated upon
a fork
. In fact, you can even set
$$
yourself; this will not, however, change
your PID. That would be a neat trick. (Mnemonic: same as in the
various shells.)
You need to be careful not to use $$
anywhere it might be misinterpreted as a dereference:
$$alphanum
. In this situation, write
${$}alphanum
to distinguish it from
${$alphanum}
.
$PROGRAM_NAME
$0
[ALL] Contains the name of the file containing
the Perl script being executed. Assignment to
$0
is magical: it attempts to modify the
argument area that the ps (1)
program normally reports on. This is more useful as a way of
indicating the current program state than it is for hiding the
program you're running. But it doesn't work on all systems.
(Mnemonic: same as sh,
ksh, bash,
etc.)
$REAL_GROUP_ID
$GID
$(
[ALL] The real group ID (GID) of this process. If
you are on a platform that supports simultaneous membership in
multiple groups, $(
gives a space-separated
list of groups you are in. The first
number is the one returned by getgid
(2), and the subsequent ones by
getgroups (2), one of which may be
the same as the first number.
However, a value assigned to $(
must be
a single number used to set the real GID. So the value given by
$(
should not be
assigned back to $(
without being forced to
be numeric, such as by adding zero. This is because you can have
only one real group. See $)
($EFFECTIVE_GROUP_ID
) instead, which allows
you to set multiple effective groups.
(Mnemonic: parentheses are used to group things. The real GID is the group you left, if you're running setgid.)
$REAL_USER_ID
$UID
$<
[ALL] The real user ID (UID) of this process as
returned by the getuid (2)
syscall. Whether and how you can modify this is subject to the
vagaries of your system's implementation--see examples under
$>
($EFFECTIVE_USER_ID
). (Mnemonic: it's the UID
you came from, if you're running
setuid.)
%SIG
[ALL] The hash used to set signal handlers for various signals. (See Section 16.1 in Chapter 16.) For example:
sub handler { my $sig = shift; # 1st argument is signal name syswrite STDERR, "Caught a SIG$sig--shutting down "; # Avoid standard I/O in async handlers to suppress # core dumpage. (Even that string concat is risky.) close LOG; # This calls standard I/O, so may dump core anyway! exit 1; # But since we're exiting, no harm in trying. } $SIG{INT} = &handler; $SIG{QUIT} = &handler; … $SIG{INT} = 'DEFAULT'; # restore default action $SIG{QUIT} = 'IGNORE'; # ignore SIGQUIT
The %SIG
hash contains undefined values
corresponding to those signals for which no handler has been
set. A handler may be specified as a subroutine reference or as
a string. A string value that is not one of the two special
actions "DEFAULT
" or
"IGNORE
" is the name of a function, which, if
unqualified by package, is interpreted to be the
main
package. Here are some other examples:
$SIG{PIPE} = "Plumber"; # okay, assumes main::Plumber $SIG{PIPE} = &Plumber; # fine, use Plumber from current package
Certain internal hooks can also be set using the
%SIG
hash. The routine indicated by
$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 to turn warnings into
fatal errors, like this:
local $SIG{__WARN__} = sub { die $_[0] }; eval $proggie;
This is similar to saying:
use warnings qw/FATAL all/; eval $proggie;
except that the first has dynamic scope, whereas the second has lexical scope.
The routine indicated by
$SIG{__DIE__}
provides a way to turn a frog
exception into a prince exception with a magical kiss, which
often doesn't work. The best use is for a moribund program
that's about to die of an untrapped exception to do some
last-moment processing on its way out. You can't save yourself
this way, but you can give one last hurrah.
The exception message is passed as the first argument.
When a __DIE__
hook routine returns,
exception processing continues as it would have in the absence
of the hook, unless the hook routine itself exits via a
goto
, a loop exit, or a
die
. The __DIE__
handler
is explicitly disabled during the call, so that you yourself can
then call the real die
from a
__DIE__
handler. (If it weren't disabled, the
handler would call itself recursively forever.) The handler for
$SIG{__WARN__}
works similarly.
Only the main program should set
$SIG{__DIE__}
, not modules. That's because
currently, even exceptions that are being trapped still trigger
a $SIG{__DIE__}
handler. This is strongly
discouraged because of its potential for breaking innocent
modules who aren't expecting their predicted exceptions to be
mysteriously altered. Use this feature only as a last resort,
and if you must, always put a local
on the
front to limit the period of danger.
Do not attempt to build an exception-handling mechanism on
this feature. Use eval {}
to trap exceptions
instead.
STDERR
[ALL] The special filehandle for standard error in any package.
STDIN
[ALL] The special filehandle for standard input in any package.
STDOUT
[ALL] The special filehandle for standard output in any package.
$SUBSCRIPT_SEPARATOR
$SUBSEP
$;
[ALL] The subscript separator for multidimensional hash 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})
The default is "