perlvar - Perl predefined variables
Variable names in Perl can have several formats. Usually, they must begin with a letter or underscore, in which case they can be arbitrarily long (up to an internal limit of 251 characters) and may contain letters, digits, underscores, or the special sequence :: or '. In this case, the part before the last :: or ' is taken to be a package qualifier; see perlmod. A Unicode letter that is not ASCII is not considered to be a letter unless "use utf8" is in effect, and somewhat more complicated rules apply; see "Identifier parsing" in perldata for details.
Perl variable names may also be a sequence of digits, a single punctuation character, or the two-character sequence: ^ (caret or CIRCUMFLEX ACCENT) followed by any one of the characters [][A-Z^_?\]. These names are all reserved for special uses by Perl; for example, the all-digits names are used to hold data captured by backreferences after a regular expression match.
Since Perl v5.6.0, Perl variable names may also be alphanumeric strings preceded by a caret. These must all be written using the demarcated variable form using curly braces such as ${^Foo}; the braces are not optional. ${^Foo} denotes the scalar variable whose name is considered to be a control-F followed by two o's. (See "Demarcated variable names using braces" in perldata for more information on this form of spelling a variable name or specifying access to an element of an array or a hash). These variables are reserved for future special uses by Perl, except for the ones that begin with ^_ (caret-underscore). No name that begins with ^_ will acquire a special meaning in any future version of Perl; such names may therefore be used safely in programs. $^_ itself, however, is reserved.
Note that you also must use the demarcated form to access subscripts of variables of this type when interpolating, for instance to access the first element of the @{^CAPTURE} variable inside of a double quoted string you would write "${^CAPTURE[0]}" and NOT "${^CAPTURE}[0]" which would mean to reference a scalar variable named ${^CAPTURE} and not index 0 of the magic @{^CAPTURE} array which is populated by the regex engine.
Perl identifiers that begin with digits or punctuation characters are exempt from the effects of the package declaration and are always forced to be in package main; they are also exempt from strict 'vars' errors. A few other names are also exempt in these ways:
ENV STDIN
INC STDOUT
ARGV STDERR
ARGVOUT
SIGIn particular, the special ${^_XYZ} variables are always taken to be in package main, regardless of any package declarations presently in scope.
The following names have special meaning to Perl. Most punctuation names have reasonable mnemonics, or analogs in the shells. Nevertheless, if you wish to use long variable names, you need only say:
use English;at the top of your program. This aliases all the short names to the long names in the current package. Some even have medium names, generally borrowed from awk. For more info, please see English.
Before you continue, note the sort order for variables. In general, we first list the variables in case-insensitive, almost-lexigraphical order (ignoring the { or ^ preceding words, as in ${^UNICODE} or $^T), although $_ and @_ move up to the top of the pile. For variables with the same identifier, we list it in order of scalar, array, hash, and bareword.
The default input and pattern-searching space. The following pairs are equivalent:
while (<>) {...} # equivalent only in while!
while (defined($_ = <>)) {...}
/^Subject:/
$_ =~ /^Subject:/
tr/a-z/A-Z/
$_ =~ tr/a-z/A-Z/
chomp
chomp($_)Here are the places where Perl will assume $_ even if you don't use it:
The following functions use $_ as a default argument:
abs, alarm, chomp, chop, chr, chroot, cos, defined, eval, evalbytes, exp, fc, glob, hex, int, lc, lcfirst, length, log, lstat, mkdir, oct, ord, pos, print, printf, quotemeta, readlink, readpipe, ref, require, reverse (in scalar context only), rmdir, say, sin, split (for its second argument), sqrt, stat, study, uc, ucfirst, unlink, unpack.
All file tests (-f, -d) except for -t, which defaults to STDIN. See "-X" in perlfunc
The pattern matching operations m//, s/// and tr/// (aka y///) when used without an =~ operator.
The default iterator variable in a foreach loop if no other variable is supplied.
The implicit iterator variable in the grep() and map() functions.
The implicit variable of given().
The default place to put the next value or input record when a <FH>, readline, readdir or each operation's result is tested by itself as the sole criterion of a while test. Outside a while test, this will not happen.
$_ is a global variable.
However, between perl v5.10.0 and v5.24.0, it could be used lexically by writing my $_. Making $_ refer to the global $_ in the same scope was then possible with our $_. This experimental feature was removed and is now a fatal error, but you may encounter it in older code.
Mnemonic: underline is understood in certain operations.
Within a subroutine the array @_ contains the parameters passed to that subroutine. Inside a subroutine, @_ is the default array for the array operators pop and shift.
See perlsub.
When an array or an array slice is interpolated into a double-quoted string or a similar context such as /.../, its elements are separated by this value. Default is a space. For example, this:
print "The array is: @array\n";is equivalent to this:
print "The array is: " . join($", @array) . "\n";Mnemonic: works in double-quoted context.
The process number of the Perl running this script. Though you can set this variable, doing so is generally discouraged, although it can be invaluable for some testing purposes. It will be reset automatically across fork() calls.
Note for Linux and Debian GNU/kFreeBSD users: Before Perl v5.16.0 perl would emulate POSIX semantics on Linux systems using LinuxThreads, a partial implementation of POSIX Threads that has since been superseded by the Native POSIX Thread Library (NPTL).
LinuxThreads is now obsolete on Linux, and caching getpid() like this made embedding perl unnecessarily complex (since you'd have to manually update the value of $$), so now $$ and getppid() will always return the same values as the underlying C library.
Debian GNU/kFreeBSD systems also used LinuxThreads up until and including the 6.0 release, but after that moved to FreeBSD thread semantics, which are POSIX-like.
To see if your system is affected by this discrepancy check if getconf GNU_LIBPTHREAD_VERSION | grep -q NPTL returns a false value. NTPL threads preserve the POSIX semantics.
Mnemonic: same as shells.
Contains the name of the program being executed.
On some (but not all) operating systems assigning to $0 modifies the argument area that the ps program sees. On some platforms you may have to use special ps options or a different ps to see the changes. Modifying the $0 is more useful as a way of indicating the current program state than it is for hiding the program you're running.
Note that there are platform-specific limitations on the maximum length of $0. In the most extreme case it may be limited to the space occupied by the original $0.
In some platforms there may be arbitrary amount of padding, for example space characters, after the modified name as shown by ps. In some platforms this padding may extend all the way to the original length of the argument area, no matter what you do (this is the case for example with Linux 2.2).
Note for BSD users: setting $0 does not completely remove "perl" from the ps(1) output. For example, setting $0 to "foobar" may result in "perl: foobar (perl)" (whether both the "perl: " prefix and the " (perl)" suffix are shown depends on your exact BSD variant and version). This is an operating system feature, Perl cannot help it.
In multithreaded scripts Perl coordinates the threads so that any thread may modify its copy of the $0 and the change becomes visible to ps(1) (assuming the operating system plays along). Note that the view of $0 the other threads have will not change since they have their own copies of it.
If the program has been given to perl via the switches -e or -E, $0 will contain the string "-e".
On Linux as of perl v5.14.0 the legacy process name will be set with prctl(2), in addition to altering the POSIX name via argv[0] as perl has done since version 4.000. Now system utilities that read the legacy process name such as ps, top and killall will recognize the name you set when assigning to $0. The string you supply will be cut off at 16 bytes, this is a limitation imposed by Linux.
Wide characters are invalid in $0 values. For historical reasons, though, Perl accepts them and encodes them to UTF-8. When this happens a wide-character warning is triggered.
Mnemonic: same as sh and ksh.
The real gid of this process. If you are on a machine that supports membership in multiple groups simultaneously, gives a space separated list of groups you are in. The first number is the one returned by getgid(), and the subsequent ones by getgroups(), one of which may be the same as the first number.
However, a value assigned to $( 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 numeric, such as by adding zero. Note that this is different to the effective gid ($)) which does take a list.
You can change both the real gid and the effective gid at the same time by using POSIX::setgid(). Changes to $( require a check to $! to detect any possible errors after an attempted change.
Mnemonic: parentheses are used to group things. The real gid is the group you left, if you're running setgid.
The effective gid of this process. If you are on a machine that supports membership in multiple groups simultaneously, gives a space separated list of groups you are in. The first number is the one returned by getegid(), and the subsequent ones by getgroups(), one of which may be the same as the first number.
Similarly, a value assigned to $) must also be a space-separated list of numbers. The first number sets the effective gid, and the rest (if any) are passed to setgroups(). To get the effect of an empty list for setgroups(), just repeat the new effective gid; that is, to force an effective gid of 5 and an effectively empty setgroups() list, say $) = "5 5" .
You can change both the effective gid and the real gid at the same time by using POSIX::setgid() (use only a single numeric argument). Changes to $) require a check to $! to detect any possible errors after an attempted change.
$<, $>, $( and $) can be set only on machines that support the corresponding set[re][ug]id() routine. $( and $) can be swapped only on machines supporting setregid().
Mnemonic: parentheses are used to group things. The effective gid is the group that's right for you, if you're running setgid.
The real uid of this process. You can change both the real uid and the effective uid at the same time by using POSIX::setuid(). Since changes to $< require a system call, check $! after a change attempt to detect any possible errors.
Mnemonic: it's the uid you came from, if you're running setuid.
The effective uid of this process. For example:
$< = $>; # set real to effective uid
($<,$>) = ($>,$<); # swap real and effective uidsYou can change both the effective uid and the real uid at the same time by using POSIX::setuid(). Changes to $> require a check to $! to detect any possible errors after an attempted change.
$< and $> can be swapped only on machines supporting setreuid().
Mnemonic: it's the uid you went to, if you're running setuid.
The subscript separator for multidimensional array emulation. If you refer to a hash element as
$foo{$x,$y,$z}it really means
$foo{join($;, $x, $y, $z)}But don't put
@foo{$x,$y,$z} # a slice--note the @which means
($foo{$x},$foo{$y},$foo{$z})Default is "\034", the same as SUBSEP in awk. If your keys contain binary data there might not be any safe value for $;.
Consider using "real" multidimensional arrays as described in perllol.
Mnemonic: comma (the syntactic subscript separator) is a semi-semicolon.
Special package variables when using sort(), see "sort" in perlfunc. Because of this specialness $a and $b don't need to be declared (using use vars, or our()) even when using the strict 'vars' pragma. Don't lexicalize them with my $a or my $b if you want to be able to use them in the sort() comparison block or function.
The hash %ENV contains your current environment. Setting a value in ENV changes the environment for any child processes you subsequently fork() off.
As of v5.18.0, both keys and values stored in %ENV are stringified.
my $foo = 1;
$ENV{'bar'} = \$foo;
if( ref $ENV{'bar'} ) {
say "Pre 5.18.0 Behaviour";
} else {
say "Post 5.18.0 Behaviour";
}Previously, only child processes received stringified values:
my $foo = 1;
$ENV{'bar'} = \$foo;
# Always printed 'non ref'
system($^X, '-e',
q/print ( ref $ENV{'bar'} ? 'ref' : 'non ref' ) /);This happens because you can't really share arbitrary data structures with foreign processes.
The revision, version, and subversion of the Perl interpreter, represented as a decimal of the form 5.XXXYYY, where XXX is the version / 1e3 and YYY is the subversion / 1e6. For example, Perl v5.10.1 would be "5.010001".
This variable can be used to determine whether the Perl interpreter executing a script is in the right range of versions:
warn "No PerlIO!\n" if "$]" < 5.008;When comparing $], numeric comparison operators should be used, but the variable should be stringified first to avoid issues where its original numeric value is inaccurate.
See also the documentation of use VERSION and require VERSION for a convenient way to fail if the running Perl interpreter is too old.
See "$^V" for a representation of the Perl version as a version object, which allows more flexible string comparisons.
The main advantage of $] over $^V is that it works the same on any version of Perl. The disadvantages are that it can't easily be compared to versions in other formats (e.g. literal v-strings, "v1.2.3" or version objects) and numeric comparisons are subject to the binary floating point representation; it's good for numeric literal version checks and bad for comparing to a variable that hasn't been sanity-checked.
The $OLD_PERL_VERSION form was added in Perl v5.20.0 for historical reasons but its use is discouraged. (If your reason to use $] is to run code on old perls then referring to it as $OLD_PERL_VERSION would be self-defeating.)
Mnemonic: Is this version of perl in the right bracket?
The maximum system file descriptor, ordinarily 2. System file descriptors are passed to exec()ed processes, while higher file descriptors are not. Also, during an open(), system file descriptors are preserved even if the open() fails (ordinary file descriptors are closed before the open() is attempted). The close-on-exec status of a file descriptor will be decided according to the value of $^F when the corresponding file, pipe, or socket was opened, not the time of the exec().
The array @F contains the fields of each line read in when autosplit mode is turned on. See perlrun for the -a switch. This array is package-specific, and must be declared or given a full package name if not in package main when running under strict 'vars'.
The array @INC contains the list of places that the do EXPR, require, or use constructs look for their library files. It initially consists of the arguments to any -I command-line switches, followed by the default Perl library, probably /usr/local/lib/perl. Prior to Perl 5.26, . -which represents the current directory, was included in @INC; it has been removed. This change in behavior is documented in PERL_USE_UNSAFE_INC and it is not recommended that . be re-added to @INC. If you need to modify @INC at runtime, you should use the use lib pragma to get the machine-dependent library properly loaded as well:
use lib '/mypath/libdir/';
use SomeMod;You can also insert hooks into the file inclusion system by putting Perl code directly into @INC. Those hooks may be subroutine references, array references or blessed objects. See "require" in perlfunc for details.
The hash %INC contains entries for each filename included via the do, require, or use operators. The key is the filename you specified (with module names converted to pathnames), and the value is the location of the file found. The require operator uses this hash to determine whether a particular file has already been included.
If the file was loaded via a hook (e.g. a subroutine reference, see "require" in perlfunc for a description of these hooks), this hook is by default inserted into %INC in place of a filename. Note, however, that the hook may have set the %INC entry by itself to provide some more specific info.
As of 5.37.7 when an @INC hook is executed the index of the @INC array that holds the hook will be localized into the $INC variable. When the hook returns the integer successor of its value will be used to determine the next index in @INC that will be checked, thus if it is set to -1 (or undef) the traversal over the @INC array will be restarted from its beginning.
Normally traversal through the @INC array is from beginning to end (0 .. $#INC), and if the @INC array is modified by the hook the iterator may be left in a state where newly added entries are skipped. Changing this value allows an @INC hook to rewrite the @INC array and tell Perl where to continue afterwards. See "require" in perlfunc for details on @INC hooks.
The current value of the inplace-edit extension. Use undef to disable inplace editing.
Mnemonic: value of -i switch.
Each package contains a special array called @ISA which contains a list of that class's parent classes, if any. This array is simply a list of scalars, each of which is a string that corresponds to a package name. The array is examined when Perl does method resolution, which is covered in perlobj.
To load packages while adding them to @ISA, see the parent pragma. The discouraged base pragma does this as well, but should not be used except when compatibility with the discouraged fields pragma is required.
By default, running out of memory is an untrappable, fatal error. However, if suitably built, Perl can use the contents of $^M as an emergency memory pool after die()ing. Suppose that your Perl were compiled with -DPERL_EMERGENCY_SBRK and used Perl's malloc. Then
$^M = 'a' x (1 << 16);would allocate a 64K buffer for use in an emergency. See the INSTALL file in the Perl distribution for information on how to add custom C compilation flags when compiling perl. To discourage casual use of this advanced feature, there is no