You are here

Home

Perl Special Variables

This section 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, while others are merely useful shortcuts that can avoid the need to run external programs that extract information from the system.

 

List of Special Variables

Each variable may have three possible names:

  • Long name (or English name)
  • Intermediate name
  • Short name

Most existing Perl programs use only the short name form. This is unfortunate, as the short name is usually a cryptic symbol. The use of these symbols in Perl programs may be daunting at first, especially in complex expressions comprising multiple variables. However, with the aid of this chapter, it soon becomes easy to identify their meaning 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.

Sometimes (in particular where the same variable also exists in awk, the UNIX report processor) an intermediate name is also allowed. Again this requires the use of the English module and is not available in Perl 4. This means that those who are used the awk conventions can use them if they wish.

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:

  • always global  These variables are global but have an unambiguous context (they need not be made local in a subroutine).
  • localize  These variables are global and may need to be made local in subroutines if the value is being changed (especially to prevent unplanned subroutine side effects).
  • local  These variables are always local and do not need to be made local explicitly.

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 enables calls of the 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 the purposes of the special-variable reference. This syntax may seem 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.

$<I<digit>>

Compliance

Syntax

Short Name  $1, $2, ... $<N>
Scope  local (read-only)

Definition

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.

All subpatterns after the last one ($<N+1>, for example), are equal to undef.

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.

$[

Compliance

Syntax

Short Name  $[
Scope  localize

Definition

This variable, which is usually set to a value of 0, 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";

$ACCUMULATOR

Compliance

Syntax

Short Name  $^A
Scope  always global

Definition

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 = "";

$ARG

Compliance

Syntax

Short Name  $_
Scope  localize

Definition

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;

$ARGV

Compliance

Syntax

Short Name  $ARGV
Scope  always global

Definition

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 a i/p file:_
 while (<>){
      print "$ARGV\n";
      };

$BASETIME

Compliance

Syntax

Short Name  $^T
Scope  localize

Definition

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";

$CHILD_ERROR

Compliance

Syntax

Short Name  $?
Scope  localize

Definition

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";

$DEBUGGING

Compliance

Syntax

Short Name  $^D
Scope  localize

Definition

Perl can be run in debugging mode. This variable allows the value of this flag to be accessed and altered.
 

 

Note
Debugging is only allowed if the version of Perl you are using was compiled with DEBUGGING specifically set.

 

Example

print "The debug flags are: $^D\n";

$EFFECTIVE_GROUP_ID

Compliance

Syntax

Short Name  $)
Intermediate Name  $EGID
Scope  localize

Definition

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 represent the effective group identifiers (GIDs).

Example

print("Effective Group ID is a list of GIDs:      $)\n");

$EFFECTIVE_USER_ID

Compliance

Syntax

Short Name  $>
Intermediate Name  $EUID
Scope  localize

Definition

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");

$EVAL_ERROR

Compliance

Syntax

Short Name  $@
Scope  localize

Definition

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";

$EXECUTABLE_NAME

Compliance

Syntax

Short Name  $^X
Scope  localize

Definition

This variable provides access to the name of the Perl executable used by the script.

Example

print "Executable name of Perl is: $^X\n";

$FORMAT_FORMFEED

Compliance

Syntax

Short Name  $^L
Scope  always global
File Handle Call  format_formfeed FILEHANDLE EXPR

Definition

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 can be changed.

Example

if ($^L = '\f')
{
  print "The formfeed character is the default break between pages.\n";
}

$FORMAT_LINES_LEFT

Compliance

Syntax

Short Name  $-
Scope  always global
File Handle Call  format_lines_left FILEHANDLE EXPR

Definition

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

$FORMAT_LINES_PER_PAGE

Compliance

Syntax

Short Name  $=
Scope  always global
File Handle Call  format_lines_per_page FILEHANDLE               EXPR

Definition

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

$FORMAT_LINE_BREAK_CHARACTERS

Compliance

Syntax

Short Name  $:
Scope  localize
File Handle Call  format_line_break_characters               FILEHANDLE EXPR

Definition

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

$FORMAT_NAME

Compliance

Syntax

Short Name  $~
Scope  always global
File Handle Call  format_name FILEHANDLE EXPR

Definition

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

$FORMAT_PAGE_NUMBER

Compliance

Syntax

Short Name  $%
Scope  always global
File Handle Call  format_page_number FILEHANDLE EXPR

Definition

Because each format can produce multiple pages of output, this counter simply counts them.

Example

select(EG_FORMAT);
$one = $%;
$two = $%;
$three = $%;
write;
select(STDOUT);

$FORMAT_TOP_NAME

Compliance

Syntax

Short Name  $^
Scope  always global
File Handle Call  format_top_name FILEHANDLE EXPR

Definition

Each format can have an associated format that is reproduced each 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);

$INPLACE_EDIT

Compliance

Syntax

Short Name  $^I
Scope  localize

Definition

Perl is often 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";

$INPUT_LINE_NUMBER

Compliance

Syntax

Short Name  $.
Intermediate Name  $NR
Scope  localize (read-only)
File Handle Call  input_line_number FILEHANDLE EXPR

Definition

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";

$INPUT_RECORD_SEPARATOR

Compliance

Syntax

Short Name  $/
Intermediate Name  $RS
Scope  localize
File Handle Call  input_record_separator FILEHANDLE                EXPR

Definition

By default, an input file is split into records, each of which comprises one line. The input-record separator is a newline 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";

$LAST_PAREN_MATCH

Compliance

Syntax

Short Name  $+
Scope  local

Definition

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";

$LIST_SEPARATOR

Compliance

Syntax

Short Name  $"
Scope  localize

Definition

When arrays are converted to strings, the elements are separated by spaces by default, which, for example, is what happens when arrays are printed. 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";
$" = ' ';

$MATCH

Compliance

Syntax

Short Name  $&
Scope  local (read-only)

Definition

This variable references the entire pattern that matched the most recent pattern matching operation.

Example

$_ = "AlphaBetaGamma";
/B[aet]*/;
print "Matched: $&\n";

$MULTILINE_MATCHING

Compliance

Syntax

Short Name:  $*
Scope:  localize

Definition

By default, Perl optimizes pattern matching on the assumption that each pattern does not contain embedded newlines; that is, it is optimized for single-line matching. If you are using a pattern that has embedded newlines, 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: $& ";
print "(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;

$OFMT

Compliance

Syntax

Short Name  $#
Scope  localize

Definition

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.

Example

$# = "%.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.

$OS_ERROR

Compliance

Syntax

Short Name  $!
Intermediate Name  $ERRNO
Scope  localize

Definition

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";

$OUTPUT_AUTOFLUSH

Compliance

Syntax

Short Name  $|
Scope  always global
File Handle Call  autoflush FILEHANDLE EXPR

Definition

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";

$OUTPUT_FIELD_SEPARATOR

Compliance

Syntax

Short Name  $,
Intermediate Name  $OFS
Scope  localize
File Handle Call  output_field_separator FILEHANDLE               EXPR

Definition

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";
$, = "";

$OUTPUT_RECORD_SEPARATOR

Compliance

Syntax

Short Name  $\
Intermediate Name  $ORS
Scope  localize
File Handle Call  output_record_separator FILEHANDLE               EXPR

Definition

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 newline 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 set it to the newline character to avert the need for explicit newlines.

Example

$\ = "\n";
print "No need for an explicit new line now.";
$\ = "";

$PERLDB

Compliance

Syntax

Short Name  $^P
Scope  localize

Definition

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";

$PERL_VERSION

Compliance

Syntax

Short Name  $]
Scope  localize

Definition

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";

$POSTMATCH

Compliance

Syntax

Short Name  $'
Scope  local (read-only)

Definition

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";

$PREMATCH

Compliance

Syntax

Short Name  $`
Scope  local (read-only)

Definition

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";

$PROCESS_ID

Compliance

Syntax

Short Name  $$
Intermediate Name  $PID
Scope  localize

Definition

In systems that support multiple processes, Perl can identify the process number of the Perl script current process (that is the process which is executing the Perl script itself) via this variable.

Example

print "The process ID (PID) is: $$\n";

$PROGRAM_NAME

Compliance

Syntax

Short Name  $0
Scope  localize

Definition

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";

$REAL_GROUP_ID

Compliance

Syntax

Short Name  $(
Intermediate Name  $GID
Scope  localize

Definition

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 represent the real group identifiers (GIDs). Effective GIDs 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");

$REAL_USER_ID

Compliance

Syntax

Short Name  $<
Intermediate Name  $UID
Scope  localize

Definition

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 represent the real user identifier (UID). An effective UID may be set by flags on the script or explicit calls to functions. This does not alter the real UID.

Example

print("The Real User ID is a list of UID: $<\n");

$SUBSCRIPT_SEPARATOR

Compliance

Syntax

Short Name  $;
Intermediate Name  $SUBSEP
Scope  localize

Definition

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 directly supports multidimensional arrays directly, so the use of $SUBSCRIPT_SEPARATOR ($;) is not necessary.

$SYSTEM_FD_MAX

Compliance

Syntax

Short Name  $^F
Scope  localize

Definition

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.

Thus, file descriptors that number greater than $^F are automatically closed to child processes.

Example

print "The default maximum file descriptors is $^F\n";

$WARNING

Compliance

Syntax

Short Name  $^W
Scope  localize

Definition

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";

%ENV{<variable_name>, <variable_value>}

Compliance

Syntax

Short Name  %ENV{<variable_name>,<variable_value>}
Scope  always global

Definition

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";

%INC{<file-name>,<file-load-status>}

Compliance

Syntax

Short Name  %INC{<file-name>,<file-load-status>}
Scope  always global

Definition

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";

%SIG{<signal-name>,<signal-value>}

Compliance

Syntax

Short Name  %SIG{<signal-name>,<signal-value>}
Scope  always global

Definition

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";

@ARGV[<N>]

Compliance

Syntax

Short Name  @ARGV[<N>]
Scope  always global

Definition

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. As with all arrays you can specify each element with <N> referring to the element number.

Example

$Example46String = "There were $#ARGV arguments, first argument was @ARGV[0]\n";
print $Example46String;

@INC[<N>]

Compliance

Syntax

Short Name  @INC[<N>]
Scope  always global

Definition

This variable is an array of the directories to search for included files. These directories are normally specified either at the command line when launching the Perl program or in an environment variable. As with all arrays you can specify each element with <N> referring to the element number.

Example

print "The possible include script directories are: @INC\n";