# Interpreter introspection

Variables that expose the running Perl interpreter and its
configuration. Most code never touches them; the cases where they
matter are version checks, OS-conditional logic, profiler hooks,
and in-place editing.

| Variable           | Holds                                                |
|--------------------|------------------------------------------------------|
| `$]`               | Perl version as a numeric string (`5.042000`)        |
| `$^V`              | Perl version as a `version` object (`v5.42.0`)       |
| `$^O`              | Operating system name (`linux`, `darwin`, …)         |
| `$^X`              | Path to the running Perl/PetaPerl executable         |
| `$^T`              | Process basetime (Unix epoch seconds)                |
| `$^W`              | Warnings master switch (boolean)                     |
| `$^I`              | In-place edit extension (set by `-i`)                |
| `$^P`              | Debugger flag bitmask                                |
| `$^R`              | Last regex code-block result                         |
| `${^GLOBAL_PHASE}` | Current interpreter phase (`START`, `RUN`, `END`, …) |

## `$]` — numeric version

A floating-point representation of the interpreter version.
Format: `5.PPPSSS` where `PPP` is the major and `SSS` the
patch:

```perl
print "$]\n";                    # e.g. "5.042000"
warn "old perl"  if "$]" < 5.038;
warn "new perl"  if "$]" >= 5.040;
```

The `"$]"` stringification before comparison is recommended —
it sidesteps subtle floating-point representation issues that can
make `$] == 5.042` mysteriously fail.

The English alias `$OLD_PERL_VERSION` is documented but
discouraged; `$]` itself is fine.

## `$^V` — version object

The interpreter version as a [`version`](../../version.md) object,
suitable for reading and for richer comparison:

```perl
print "$^V\n";                   # "v5.42.0"
warn "need 5.40+" if $^V lt v5.40.0;
```

The literal `v5.40.0` is a v-string — Perl’s native syntax for
version constants. Use `$^V` when comparing to v-string
literals; use `$]` when comparing to bare numerics.

In PetaPerl, `$^V` reports the underlying Perl-compatibility
level (5.42), not the PetaPerl release version.

## `$^O` — operating system name

```perl
print "$^O\n";                   # "linux"
if ($^O eq 'MSWin32') {
    use_windows_path_separator();
}
```

PetaPerl is Linux-only; `$^O` is always `"linux"`. The variable
exists for source-compatibility with portable code that branches
on it. The full list of values upstream Perl can produce includes
`linux`, `darwin`, `freebsd`, `openbsd`, `MSWin32`, `cygwin`,
`solaris`, and several historical entries.

## `$^X` — executable path

The path to the interpreter currently running, suitable for
re-invoking:

```perl
print "$^X\n";                   # e.g. "/usr/local/bin/pperl"

# Rerun the script under the same interpreter, with extra args:
exec $^X, $0, @ARGV, '--debug';
```

`$^X` is what makes `exec $^X, $0, ...` portable — you do not
need to know whether the script was started via `pperl`,
`/usr/bin/env perl`, or an absolute path.

## `$^T` — basetime

The Unix epoch second at which the program started running:

```perl
my $uptime = time() - $^T;
print "running for $uptime seconds\n";
```

The classic use is the `-M` and `-A` filetests, which by default
report file ages *relative to* `$^T` rather than to `time()`. If you set
`$^T = time()` periodically, those filetests recompute against
the new reference point — useful in long-running daemons that
need to ignore files older than ”since I started this batch“.

## `$^W` — the warnings switch

The master warnings flag, set by the `-w` command-line switch:

```perl
$^W = 1;                          # all warnings on
$^W = 0;                          # all warnings off
```

`$^W` is the Perl-1-era global flag. The modern lexical
[`use warnings`](../perlfunc/use.md) pragma is the recommended
way to control warnings, and operates independently — a `use warnings` block stays on regardless of `$^W`, and a `no warnings`
block stays off regardless of `$^W`. The variable mostly matters
in code that pre-dates the lexical pragma or that wants to
toggle the global default at runtime.

`${^WARNING_BITS}` is the lexical bitmap that
[`use warnings`](../perlfunc/use.md) reads and writes. Its format
is internal; do not rely on specific bit positions.

## `$^I` — in-place edit extension

Set by the [`-i`](../../../guide/oneliner/switches.md) command-line
switch. When `$^I` is defined, reading from `<>` (the
`while (<>)` form) re-opens each file for both read and write
and redirects subsequent `print` to the rewritten file:

```perl
# perl -i.bak -ne 's/\bold\b/new/g; print' *.txt
# Equivalent in script form:
local $^I = '.bak';
while (<>) {
    s/\bold\b/new/g;
    print;
}
```

`$^I = ''` (empty string) means ”rewrite in place without a
backup“. `$^I = '.bak'` saves the original as `<filename>.bak`.
Setting `$^I = undef` turns in-place editing off.

## `$^P` — debugger flag bitmask

Read by the Perl debugger; if non-zero, `DB::DB` is
called before every statement. Manipulated by `perl -d` and the
[`Devel::*`](../../Devel.md) family of debugger and profiler modules.

User code rarely sets `$^P`. The flag bits are documented in
upstream perlvar; the most commonly seen value is `0x73f` (full
debugging).

## `$^R` — regex code-block result

The result of the last `(?{...})` or `(?(N)...)` regex code
assertion. Lives only as long as the surrounding match:

```perl
"abc123" =~ /(?<word>\w+?)(\d+)(?{ length($1) + length($2) })/;
print "$^R\n";                   # 6 — the code block's last expression
```

PetaPerl supports `(?{ })` regex code blocks; see the
[performance chapter](../../../guide/regular-expression/performance.md)
of the regex guide for the language details.

## `${^GLOBAL_PHASE}` — current interpreter phase

The current life-cycle phase of the Perl interpreter:

| Phase       | When                                                |
|-------------|-----------------------------------------------------|
| `CONSTRUCT` | Inside the C-level interpreter constructor          |
| `START`     | `BEGIN` blocks, `use`, `require`, top-level compile |
| `CHECK`     | After compilation, before `INIT`                    |
| `INIT`      | `INIT` blocks                                       |
| `RUN`       | Main program execution                              |
| `END`       | `END` blocks                                        |
| `DESTRUCT`  | Global destruction                                  |
```perl
END {
    if (${^GLOBAL_PHASE} eq 'END') {
        log_shutdown();           # we are still in user END
    }
}

# Inside a destructor, distinguish "object cleanup during normal
# scope exit" from "object cleanup during interpreter shutdown":
sub DESTROY {
    my $self = shift;
    if (${^GLOBAL_PHASE} eq 'DESTRUCT') {
        # global destruction — order is undefined, file handles
        # may already be torn down — be conservative
        return;
    }
    $self->{handle}->flush;
}
```

The ”don’t run during global destruction“ guard inside `DESTROY`
is the variable’s classic use case. During `DESTRUCT`, the order
of object teardown is not defined; an object’s references may
already be invalid.

## See also

- [`use VERSION`](../perlfunc/use.md) — the conventional way to
  require a minimum Perl version, replacing `if "$]" < ...`.
- [`require VERSION`](../perlfunc/require.md) — same as `use VERSION` but at runtime.
- [`Config`](../../Config.md) — the full Perl build configuration,
  much richer than `$^O` and `$]`.
- [`use warnings`](../perlfunc/use.md) — the lexical pragma that
  supersedes `$^W` for new code.
- [Command-line switches](../../../guide/oneliner/switches.md) —
  documents `-i` (`$^I`), `-w` (`$^W`), `-d` (`$^P`).