# Special variables

Perl ships with a fixed set of built-in variables that are
populated, read, or honoured by the language itself. Some hold
state from the last operation (the regex match variables, `$!`,
`$@`); some configure how built-ins behave (`$/`, `$\`, `$,`);
some expose the running interpreter and its environment (`$^V`,
`$^O`, `%ENV`, `@INC`); a few are not really variables at all
but hooks into runtime services (`%SIG`).

PetaPerl implements every special variable that Perl 5.42
documents, with identical semantics. Where the runtime does
something noteworthy of its own — a JIT fast path that reads a
cached cell, an Arc-backed COW string for `$_` — that is an
implementation detail; user-visible behaviour matches perl5.

This reference is split into one page per family. Variables that
share context (you almost never set `$,` without thinking about
`$\` and `$|`) live on the same page; variables that don’t
(process IDs and regex captures) don’t.

## Choose a family

* [Default variables](perlvar/default.md)
* [Process identity](perlvar/process.md)
* [Error state](perlvar/error.md)
* [Filehandle and printing state](perlvar/io.md)
* [Regex match variables](perlvar/regex.md)
* [Interpreter introspection](perlvar/interpreter.md)
* [Program input — `@ARGV`, `%ENV`, `@INC`](perlvar/args-env-inc.md)
* [Signal handling — `%SIG`](perlvar/signals.md)

- [Default variables](perlvar/default.md) — `$_`, `@_`. The implicit
  operand of most built-ins; the argument array of every sub.
- [Process identity](perlvar/process.md) — `$0`, `$$`, `$<`, `$>`,
  `$(`, `$)`. Program name, PID, real and effective UIDs/GIDs.
- [Error state](perlvar/error.md) — `$!`, `$@`, `$?`, `$^E`. The
  four error variables, each reporting from a different
  layer (C library, eval/`die`, child process, OS-extended).
- [Filehandle and printing state](perlvar/io.md) — `$/`, `$\`, `$,`,
  `$"`, `$|`, `$.`, `$;`. Input record separator, output
  separators, autoflush, line counter, subscript joiner.
- [Regex match variables](perlvar/regex.md) — `$&`, `$``, `$'`,
  `$1`..`$N`, `%+`, `%-`, `@+`, `@-`. The result of the last
  successful match; the performance story behind `$&` and friends.
- [Interpreter introspection](perlvar/interpreter.md) — `$]`, `$^V`,
  `$^O`, `$^X`, `$^T`, `$^W`, `$^I`, `$^P`. Version, OS, executable
  path, basetime, warnings, in-place edit, debugger flags.
- [Program input](perlvar/args-env-inc.md) — `@ARGV`, `%ENV`, `@INC`,
  `%INC`, `$0`. How the script gets its arguments, environment,
  and module search path; the `use lib` vs `unshift @INC` story.
- [Signal handling](perlvar/signals.md) — `%SIG`, `$SIG{__WARN__}`,
  `$SIG{__DIE__}`. The signals you can catch, the safe-signals
  rule, and the standard graceful-shutdown shape.

## Variable namespaces

Each special variable lives in **one** specific namespace. Most
are in `main::`; some (`@F`, `@ISA`) are package-local. Every
variable’s documentation says which.

The naming convention is a punctuation choice and a sigil:

- `$<digit>` — regex capture variables.
- `$<symbol>` — single-character variables (`$_`, `$!`, `$@`,
  `$/`, …).
- `$^<letter>` — control-letter variables (`$^V`, `$^W`, `$^X`).
  Spelled with a literal caret followed by an uppercase letter.
- `${^NAME}` — extended-name variables (`${^GLOBAL_PHASE}`,
  `${^CAPTURE}`). The braces and caret are required.
- `$NAME` after `use English` — the named alias for almost every
  punctuation variable. `$ERRNO` is `$!`, `$EVAL_ERROR` is `$@`,
  etc.

## The `English` module

```perl
use English;            # all aliases, plus $PREMATCH/$MATCH/$POSTMATCH
use English qw( -no_match_vars );    # skip $`, $&, $' aliases
```

`English` provides readable aliases for the punctuation
variables: `$EVAL_ERROR` for `$@`, `$INPUT_RECORD_SEPARATOR` for
`$/`, and so on. The aliases are real Perl variables that share
storage with the originals — assigning to one writes the other.

The `-no_match_vars` import is recommended in code that doesn’t
explicitly need `$&`, `$``, or `$'`. See
[regex match variables](perlvar/regex.md) for the historical
performance reason and why it no longer matters on modern perls.

This page lists punctuation forms throughout because most code
in the wild is written that way. The English aliases are noted
alongside on the family pages where they are useful.

## Localising special variables

Almost every special variable that controls a built-in’s
behaviour (`$/`, `$\`, `$,`, `$"`, `$|`, `$_`) is global — set
it in one place and every other piece of code in the same
process sees the change. The standard idiom for ”I need a
different value just for this block“ is `local`:

```perl
sub slurp {
    my ($path) = @_;
    open my $fh, '<', $path or die "open $path: $!";
    local $/;                         # slurp mode, only inside this sub
    return <$fh>;
}
```

Without the `local`, the caller’s `$/` would be permanently
clobbered. `local` saves the current value, sets the new one,
and restores the old value when the enclosing scope exits — even
on an exception. This applies to every special variable on the
family pages, except the read-only ones (regex match variables,
`$0`’s formal argument, the version variables).

## See also

- [`perlop`](perlop.md) — every operator that reads or writes a
  special variable as part of its definition (regex binding,
  printing, range, comparison).
- [`perlfunc`](perlfunc.md) — built-in functions, almost all of
  which read a default from one of these variables when called
  with no argument (`chomp`, `chop`, `print`, `lc`, `length`,
  `<>`, …).
- [Regular expressions guide](../../guide/regular-expression/index.md)
  — the regex language behind the match variables.
- [Boolean Logic for Perl Programmers](../../tutorial/boolean-logic/index.md)
  — the conceptual companion for the `||`/`//` defaulting idioms
  that recur throughout this reference.