Special Variables in Alphabetical Order (Programming Perl)

28.2. Special Variables in Alphabetical Order

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.)

[1] Although many regular expression engines only support up to nine backreferences, Perl has no such limit, so if you go around writing $768, Perl won't mind, although maintainers of your code might if you actually use that many parentheses in your regular expressions.

$[

[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:

@ARG

@_

[ALL] Within a subroutine, this array holds the argument list passed to that subroutine. See Chapter 6, "Subroutines". 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, "The Command-Line Interface".

$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, "Compiling".

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, "The Command-Line Interface" 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, "Security".

$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 used, 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, "Modules".

@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, "Modules".

%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, "Modules".

$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, "Objects".

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 " \n-", 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 doFILE, 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 doFILE, 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 "\n\n" 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 "\n\n" 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/\n[ \t]+/ /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, "The Command-Line Interface". (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, "Objects".

@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:

$` is the same as substr($var, 0, $-[0])
$& is the same as substr($var, $-[0], $+[0] - $-[0])
$' is the same as substr($var, $+[0])
$1 is the same as substr($var, $-[1], $+[1] - $-[1])
$2 is the same as substr($var, $-[2], $+[2] - $-[2])
$3 is the same as substr($var, $-[3], $+[3] - $-[2]), and so on.

@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!\n" if $] < 3.019;
die "Must have prototyping available\n" if $] < 5.003;

See also the documentation of useVERSION and requireVERSION 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, "Standard Modules". (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, "Standard Modules". 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, "Functions" or the example in the POSIX module in Chapter 32, "Standard Modules".

$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 "\n" 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, "The Command-Line Interface".

%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, "Overloading".

$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!\n" if $^V lt v5.6;

See the documentation of useVERSION and requireVERSION 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 "$`:$&:$'\n";         # 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\n";         # 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 the section "Signals" in Chapter 16, "Interprocess Communication".) For example:

sub handler {
    my $sig = shift;   # 1st argument is signal name
    syswrite STDERR, "Caught a SIG$sig--shutting down\n";
                       # 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 "\034", the same as SUBSEP in awk. Note that if your keys contain binary data, there might not be any safe value for $;. (Mnemonic: comma--the syntactic subscript separator--is a semi-semicolon. Yeah, we know, it's pretty lame, but $, is already taken for something more important.)

Although we haven't deprecated this feature, you should instead consider using "real" multidimensional hashes now, such as $foo{$a}{$b}{$c} instead of $foo{$a,$b,$c}. The fake ones may be easier to sort, however, and are much more amenable to use as DBM files.

$SYSTEM_FD_MAX

$^F

[ALL] The maximum "system" file descriptor, ordinarily 2. System file descriptors are passed to new programs during an exec, 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 and stay closed if the open fails.) Note that the close-on-exec status of a file descriptor will be decided according to the value of $^F at the time of the open, not the time of the exec. Avoid this by temporarily jacking $^F through the roof first:

{
    local $^F = 10_000;
    pipe(HITHER,THITHER) or die "can't pipe: $!";
}

$VERSION

[PKG] This variable is accessed whenever a minimum acceptable version of a module is specified, as in use SomeMod 2.5. If $SomeMod::VERSION is less than that, an exception is raised. Technically, it's the UNIVERSAL->VERSION method that looks at this variable, so you could define your own VERSION function in the current package if you want something other than the default behavior. See Chapter 12, "Objects".

$WARNING

$^W

[ALL] The current Boolean value of the global warning switch (not to be confused with the global warming switch, about which we hear many global warnings). See also the use warnings pragma in Chapter 31, "Pragmatic Modules", and the -W and -X command-line switches for lexically scoped warnings, which are unaffected by this variable. (Mnemonic: the value is related to the -w switch.)

${^WARNING_BITS}

[NOT,ALL] The current set of warning checks enabled by the use warnings pragma. See usewarnings in Chapter 31, "Pragmatic Modules" for more details.

${^WIDE_SYSTEM_CALLS}

[ALL] Global flag that enables all syscalls made by Perl to use wide-character APIs native to the system, if available. This can also be enabled from the command line using the -C command-line switch. The initial value is typically 0 for compatibility with Perl versions earlier than 5.6, but may be automatically set to 1 by Perl if the system provides a user-settable default (such as via $ENV{LC_CTYPE}). The use bytes pragma always overrides the effect of this flag in the current lexical scope.

Now brace yourself for a big chapter...


28.1. Special Names Grouped by Type		29. Functions