by Mícheál Ó Foghlú
This chapter looks in detail at the special variables used in Perl. Understanding these variables is crucial to programming effectively in Perl. Some of the variables are essential for nearly all Perl programs. Other variables are merely useful shortcuts that eliminate the need to run external programs that extract information from the system.
Each variable might have three possible names:
Most existing Perl programs use only the short name form. This fact is unfortunate, because the short name usually is a cryptic symbol. The use of these symbols in Perl programs may be daunting at first, especially in complex expressions that comprise multiple variables. With the aid of this chapter, however, you soon will be able to identify their meanings, and thus understand the programs.
The long name was introduced in Perl 5. This chapter lists all the special variables of this English name in alphabetical order. In Perl 4, you must use the short name. In Perl 5, you can use any of the name forms, but if you want to use the long English name, you must include the following command:
Use English;
This command enables the long names in the Perl 5 program.
This chapter categorizes special variables in several ways to make it easier for you to use the list as a reference source. The most important of these categories is Scope, which can have the following values:
| NOTE |
You should pay special attention to variables that can be localized. A well-known principle of programming is that any subroutine or function should not produce unexpected side effects. A subroutine to print a line on a printer, for example, should not alter the $; ($SUBSCRIPT_SEPARATOR) variable for the rest of the program. If, for some reason, the subroutine does need to change the value, it should do so merely locally within the subroutine itself by localizing the variable. If global changes are required in the global variables, they should be made very explicit so that anyone who reads the program can see clearly what is going on. |
The other important special-variable category used in this chapter is File Handle Call. Special variables that implicitly refer to the current active file handle can be explicitly bound to any existing file handle. This facility must be activated by the following call:
use FileHandle;
This call enables calls of these forms:
FILEHANDLE->method(EXPR) method FILEHANDLE EXPR
The relevant method name usually is the full long name of the special variable. The optional EXPR is an expression for changing the current value of the file handle, as well as referring to another file handle for purposes of the special-variable reference. This syntax might be confusing at first, but when used consistently, it can make Perl programs with formatting much more readable.
Both the English long names and the use of file handles in references to formats are new features in Perl 5. If you are using Perl 4, you must use the short names and allow format operations to take place in relation to the current active file handle (which you can change by using the select() function).
Short Name: $1, $2, ... $<N> Scope: local (read-only)
These variables are used to refer back to pattern matches. In any pattern to be matched, sets of parentheses are used to mark subpatterns. These subpatterns are numbered from left to right. After a match has been made, each subpattern match is referenced by these variables, up to and including the number of subpatterns that are actually specified. $1 is the first subpattern; $2 is the second; and so on, up to and including $<N>, the Nth subpattern specified.
Example:
$_ = "AlphaBetaGamma"; /^(Alpha)(.*)(Gamma)$/; print "$1 then $2 then $3\n";
| TIP |
If you have alternative patterns and do not know which one may have matched, try using $LAST_PAREN_MATCH instead. |
Short Name: $[ Scope: localize
This variable, which is usually set to a value of zero, represents the index of the first element in any array. Programmers who are used to using 1 as the index of the first element of an array could change the value of this variable to suit their preference.
Example:
$[ = 1; $_ = "AlphaBetaGamma"; $tmp = index($_,"Beta"); print "Beta located at: $tmp\n"; $[ = 0; $_ = "AlphaBetaGamma"; $tmp = index($_,"Beta"); print "Beta located at: $tmp\n";
Short Name: $^A Scope: always global
This variable allows direct access to the line of output built up with the Perl formatting commands. Normally, this access is not necessary, but it is possible.
Example:
$tmp = formline<<'FINISH', Alpha, Beta, Gamma; @<<<<<<<<<< @|||||||||||| @<<<<<<<<< FINISH print "Accumulator now contains:\n $^A\n"; $^A = "";
This variable is not available in Perl 4.
Short Name: $_ Scope: localize
This variable is the default pattern space. When reading a file, $ARG usually takes on the value of each line in turn. You can assign a value to $ARG directly. Many functions and operators take this variable as the default upon which to operate, so you can make the code more concise by using $ARG.
Example:
$_ = "\$\_ is the default for many operations including print().\n"; print;
Short Name: $ARGV Scope: always global
When processing an input file, this variable provides access to the name of this file.
Example:
print("Assuming this script has been called with an argument as an i/p file:_
while (<>){
print "$ARGV\n";
};
Short Name: $^T Scope: localize
This variable is the time when the Perl program was started, as measured in the basic time units (seconds since the start of 1970).
Example:
$nicetime = localtime($^T); print "This program started at $^T (i.e. $nicetime).\n";
Short Name: $? Scope: localize
If a Perl script spawns child processes, you can examine their error codes by using this variable.
Example:
'ls -lgd /vir'; print "Child Process error was: $?\n";
See the section on the $OS_ERROR variable for system error messages.
Short Name: $^D Scope: localize
Perl can be run in debugging mode. This variable allows the value of this flag to be accessed and altered.
Example:
print "The debug flags are: $^D\n";
Short Name: $) Intermediate Name: $EGID Scope: localize
In systems that support users and groups, as well as setting new users and groups within a process, Perl can access both the original and the effective user and group information. The effective group variable provides access to a list of numbers that represents the effective group identifiers (GIDs).
Example:
print("Effective Group ID is a list of GIDs: $)\n");
Short Name: $> Intermediate Name: $EUID Scope: localize
In systems that support users and groups, as well as setting new users and groups within a process, Perl can access both the original and the effective user and group information. The effective user variable provides access to a single number that represents the effective user identifier (UID).
Example:
print("Effective User ID is one UID: $>\n");
Short Name: $@ Scope: localize
Perl allows explicit calls to the eval() function to evaluate Perl syntax with a Perl script. This variable allows access to the returned error after such an operation. The error is a string that contains the relevant error message.
Example:
print "Passing eval a malformed Perl expression:\n"; eval 'print "Hello'; print "Error: $@\n";
Short Name: $^X Scope: localize
This variable provides access to the name of the Perl executable used by the script.
Example:
print "Executable name of Perl is: $^X\n";
Short Name: $^L Scope: global to a global file handle File Handle Call: format_formfeed FILEHANDLE EXPR
When you use the Perl formatting commands, you can specify formats to manipulate centering and other formatting of the text. One additional option is to specify the exact code to be inserted between pages of output in the file. The default value is a form-feed character (\f), but this value can be changed.
Example:
if ($^L = '\f')
{
print "The formfeed character is the default break between pages.\n";
}
The $^L variable is not available in Perl 4.
Short Name: $- Scope: local File Handle Call: format_lines_left FILEHANDLE EXPR
When you use the Perl formatting commands, this counter (which exists for each file handle with an associated format) is decremented every time a line is output until it reaches zero, when a new page is generated. You can manually set this variable to zero to force a page break in the output.
Example:
format EG_FORMAT = @<<<<<<<<<< @|||||||||||| @>>>>>>>>> ^|||||||||| $one, $two, $three $fitme . open(EG_FORMAT,">-"); select(EG_FORMAT); $one = 'Left'; $two = 'Center'; $three = 'Right'; $fitme= ""; write; $one = $-; $two = $-; $three = $-; write; $one = $-; $two = $-; $three = $-; write; select(STDOUT);
Short Name: $= Scope: local File Handle Call: format_lines_per_page FILEHANDLE EXPR
Each format file handle has an associated number of lines per page, which you can access and change by using this variable.
Example:
select(EG_FORMAT); $one = 'Left'; $two = 'Center'; $three = 'Right'; $fitme= ""; write; $one = $=; $two = $=; $three = $=; write; select(STDOUT);
Short Name: $: Scope: localize File Handle Call: format_line_break_characters FILEHANDLE EXPR
When you are outputting a value to a formatted area by using the format code
^||||||||||||||
(or the other multiple-line formats), the line-break character determines how strings are split into lines to fit into the formatted space. By default, the legal break characters are space, hyphen, and new line.
Example:
select(EG_FORMAT); $: = ' \n-'; $one = 1; $two = 2; $three = 3; $fitme= "One-One-One-One-One-One"; write; write; write; select(STDOUT);
Short Name: $~ Scope: local File Handle Call: format_name FILEHANDLE EXPR
Each format has a name, which may also be the name of the file handle. You can access the name directly through this variable.
Example:
select(EG_FORMAT); $one = $~; $two = $~; $three = $~; write; select(STDOUT);
Short Name: $% Scope: always global File Handle Call: format_page_number FILEHANDLE EXPR
Because each format can produce multiple pages of output, this counter simply counts them.
Example:
select(EG_FORMAT); $one = $%; $two = $%; $three = $%; write; select(STDOUT);
Short Name: $^ Scope: always global File Handle Call: format_top_name FILEHANDLE EXPR
Each format can have an associated format that is reproduced every time a new page is generated. (No equivalent automatic page footer exists.) By default, these are given the same name as the base format with a _TOP suffix, although any name can be set.
Example:
format EG_TOP =
[Sample Page Header]
To the left In the center To the right
----------- ------------- ------------
.
open(EG_FORMAT,">-");
select(EG_FORMAT);
$- = 0;
$^ = EG_TOP;
$one = '111';
$two = '222';
$three = '333';
$fitme= "";
write;
write;
write;
select(STDOUT);
Short Name: $^I Scope: localize
Perl often is used to edit files and sometimes, the input file is also the output file (the result replaces the original). In this case, you can specify (with command-line options) the suffix to be used for the temporary file created while the edits are in progress. You can set or simply access this value from within the script itself by using this variable.
Example:
$^I=bak; print "Tmp file extension when editing in place... $^I\n";
Short Name: $. Intermediate Name: $NR Scope: localize (read-only) File Handle Call: input_line_number FILEHANDLE EXPR
This variable counts the number of lines of input from a file and is reset when the file is closed. The variable counts lines cumulatively across all input files read with the <> construct (because these are not closed explicitly).
Example:
print "The last file read had $. lines\n";
Short Name: $/ Intermediate Name: $RS Scope: localize File Handle Call: input_record_separator FILEHANDLE EXPR
By default, an input file is split into records, each of which comprises one line. The input-record separator is a new-line character. This variable can be set to have no value (in which case entire input files are read in at the same time) or to have other values, as required.
Example:
undef $/; open(INFILE,"infile.tst"); $buffer = <INFILE>; print "$buffer\n";
Short Name: $+ Scope: local
This variable returns the value of the last pattern marked with parentheses. In most contexts, you could simply use $1, $2, and so on rather than $+. When the pattern has a series of sets of parentheses as alternatives to be matched, using $+ is useful.
Example:
$_ = "AlphaBetaDeltaGamma"; /Alpha(.*)Delta(.*)/; print "The last match was $+\n";
Short Name: $" Scope: localize
When arrays are converted to strings, the elements are separated by spaces by default (which is what happens when arrays are printed, for example). This variable allows you to specify any string as the list separator, which may be useful for output formatting or for other reasons.
Example:
$" = ' ! '; @thisarray = (Alpha, Beta, Gamma); print "@thisarray.\n"; $" = ' ';
Short Name: $& Scope: local (read-only)
This variable references the entire pattern that matched the most recent pattern-matching operation.
Example:
$_ = "AlphaBetaGamma"; /B[aet]*/; print "Matched: $&\n";
Short Name: $* Scope: localize
By default, Perl optimizes pattern matching on the assumption that each pattern does not contain embedded new lines-that is, it is optimized for single-line matching. If you are using a pattern that has embedded new lines, you should set this variable to a value of 1 so that this optimization is disabled and the correct result is obtained.
Example:
print("\nTest 26 Perl Version ($])\n");
$_ = "Alpha\nBeta\nGamma\n";
$* = 0; # Assume string comprises a single line
/^.*$/;
print "a) Assuming single line: $& (which is wrong - the assumption was wrong).\n";
$* = 1; # Do not assume string comprises a single line
/^.*$/;
print "a) Not assuming single line: $& (which is correct).\n";
$* = 0;
Short Name: $# Scope: localize
This variable mimics the UNIX awk utility variable of the same name, which permits numeric formatting. The default value is:
%.2g
See the UNIX awk documentation for information about the possible values.
$# = "%.6g";
print 5467.4567, "\n"; $# = "%.8g"; print 5467.4567, "\n";
| TIP |
Use of the $OFMT variable is discouraged. You can format values by using the print() function directly. |
Short Name: $! Intermediate Name: $ERRNO Scope: localize
If an operating-system-error condition exists, this variable is set to the error number (and, if it is evaluated in a string context, to the equivalent error message). You can manually set the error number and then access the relevant error message in a string context.
Example:
ls -lgd /vir'; print "OS Error was $!\n";
See the section on the $CHILD_ERROR variable for subprocess errors, which are not necessarily system errors.
Short Name: $| Scope: always global File Handle Call: autoflush FILEHANDLE EXPR
If this Boolean variable (which is associated with a file handle)
has a nonzero value, that file is autoflushed (the output is written
after each print or write operation) rather than being buffered.
| TIP |
When the output file is a pipe, it is best to set autoflush on so that other programs can access the pipe immediately after each write or print operation. |
Example:
select(STDERR); $| = 1; select(STDOUT); print "Autoflush setting for STDOUT is $|\n";
Short Name: $, Intermediate Name: $OFS Scope: localize File Handle Call: output_field_separator FILEHANDLE EXPR
This variable can alter the behavior of the print() function. The default behavior of print(), when it is given a comma-separated list of arguments, is to print each argument with no output separator. You can use this variable to specify any string as a separator.
Example:
$, = "="; print STDOUT a, b, c, "\n"; $, = "";
Short Name: $\ Intermediate Name: $ORS Scope: localize File Handle Call: output_record_separator FILEHANDLE EXPR
This variable can alter the behavior of the print() function. The default behavior of print(), when it is given a comma-separated list of arguments, is to print each argument. If a new line is required at the end, you must add it explicitly. You can use this record-separator variable to specify any string as the end-of-record string, and you most commonly would set it to the new-line character to avert the need for explicit new lines.
Example:
$\ = "\n"; print "No need for an explicit newline now."; $\ = "";
Short Name: $^P Scope: localize
This flag represents the debug level of the Perl script. Normally, $PERLDB is used internally by the debugger to disable debugging of the debugger script itself.
Example:
print "Value of internal Boolean debug flag: $^P\n";
Short Name: $] Scope: localize
This variable represents the version string that identifies the Perl version that is being run. You can assign a value to the variable, if necessary. In a numeric context, the variable evaluates to a number made up of the version plus the (patch level/1000).
Example:
$ver = $]+0; print "So every test has tested the version $] (numeric $ver).\n";
Short Name: $' Scope: local (read-only)
When a string is matched by pattern, the pattern is actually split into three parts: the part of the string before the match, the part of the string that matched, and the part of the string after the match. Any of these parts could be empty, of course. This variable refers to the part of the string after the match.
Example:
$_ = "AlphaBetaGamma"; /Beta/; print "Postmatch = $'\n";
Short Name: $' Scope: local (read-only)
When a string is matched by pattern, the pattern is actually split into three parts: the part of the string before the match, the part of the string that matched, and the part of the string after the match. Any of these parts could be empty, of course. This variable refers to the part of the string before the match.
Example:
$_ = "AlphaBetaGamma"; /Beta/; print "Prematch = $`\n";
Short Name: $$ Intermediate Name: $PID Scope: localize
In systems that support multiple processes, Perl can identify the process number of the Perl script process itself via this variable.
Example:
print "The process ID (PID) is: $$\n";
Short Name: $0 Scope: localize
This variable contains the name of the Perl script that is being executed. You can alter this variable if you want the script to identify itself to the operating system as having a particular name.
Example:
print "The program name is: $0\n";
Short Name: $( Intermediate Name: $GID Scope: localize
In systems that support users and groups, as well as setting new users and groups within a process, Perl can access both the original and the effective user and group information. The real group variable provides access to a list of numbers that represents the real group identifiers (GIDs). Effective group identifiers may be set using flags in the script or explicit calls to functions. This will not alter the real GIDs.
Example:
print("The Real Group ID is a list of GIDs: $(\n");
Short Name: $< Intermediate Name: $UID Scope: localize
In systems that support users and groups, as well as setting new users and groups within a process, Perl can access both the original and the effective user and group information. The real user variable provides access to a list of numbers that represents the real user identifiers (UID). Effective user ID may be set by flags on the script or explicit calls to functions. This does not alter the real user ID.
Example:
print("The Real User ID is a list of UID: $<\n");
Short Name: $; Intermediate Name: $SUBSEP Scope: localize
This variable is used in emulating multidimensional arrays. The value must be one that is not used by any element in the array. The default value is \034.
Perl 5 supports multidimensional arrays directly, so the use of $SUBSCRIPT_SEPARATOR ($;) should not be necessary.
Short Name: $^F Scope: localize
By default, Perl treats three files as system files 0, 1, and 2-normally, STDIN, STDOUT, and STDERR. The value of $^F is 2 by default. System files are treated specially; in particular, the file descriptors are passed to exec() processes.
Example:
print "The default maximum file descriptors is $^F\n";
Short Name: $^W Scope: localize
This variable is a Boolean warning flag that you normally set to true by using the command-line -w switch, although you can set it within the script, if necessary. When this variable is on, the Perl program reports more verbose warnings.
Example:
print "Boolean warning flag is set to: $^W\n";
Short Name: %ENV{<variable_name>,<variable_value>}
Scope: always global
This variable is an associative array that links the names of the environment variables to their values. This variable makes it easy to look up a value with the appropriate name.
Example:
$tmp = $ENV{SHELL};
print "The current SHELL is set to $tmp\n";
Short Name: %INC{<file-name>,<file-load-status>}
Scope: always global
This variable is an associate array that links the names of the required files to a status (whether they were successfully loaded). Normally, the Perl script itself uses this array to determine whether files have already been loaded so as to minimize the number of file loads that are carried out.
Example:
require 'another.pl';
$tmp = $INC{'another.pl'};
print "The required file did exist: $tmp\n";
Short Name: %SIG{<signal-name>,<signal-value>}
Scope: always global
This variable is an associative array that links the standard signals to values. These values dictate the way that the script processes those signals. You can assign signal-handling subroutines to certain signals or set the script to ignore certain signals.
Example:
$SIG{'HUP'} = 'IGNORE';
print "This process now ignores hangup signals.\n";
Short Name: @ARGV Scope: always global
This variable is an array of the arguments passed to the script. Unlike the situation in the C language, the first element of this array is the first argument (not the program name). As the arguments are processed, the value of this variable can alter.
Example:
$Example46String = "There were $#ARGV arguments, first argument was @ARGV[0]\n"; print $Example46String;
Short Name: @INC Scope: always global
This variable is an array of the directories to search for included files. These directories are normally specified either on the command line of the Perl invocation or in an environment variable.
Example:
print "The possible include script directories are: @INC\n";
This chapter lists only Perl special variables; you should consult other reference chapters for Perl functions and Perl operators. (You may easily confuse some variables with some operators, so check the list of operators if the symbol that you require is not covered in this chapter.)
For details on the other elements in the Perl reference, see the following chapters: