FILE#

The name of the source file the token is compiled in.

__FILE__ is a compile-time token, not a runtime function. At the point the compiler reads it, it is replaced with a string literal holding the filename the compiler is currently reading from. It takes no arguments, is never called with parens, and has no runtime cost — by the time your program runs, __FILE__ has already become a plain string constant.

Its one job is to let code identify the file it lives in, for error messages, log lines, test diagnostics, and similar reporting.

Synopsis#

__FILE__

What you get back#

A string: the filename as the compiler knew it when it read this token. For a script invoked as perl /tmp/run.pl the value is /tmp/run.pl; for a module loaded through require or use it is the path require resolved against @INC (typically an absolute path). For code fed on standard input or through -e it is - or -e respectively.

Because substitution happens at compile time, the value is fixed for each textual occurrence of the token. Two __FILE__ tokens in different files produce different strings; two in the same file produce the same string.

Global state it touches#

None at runtime. At compile time the value is taken from the compiler’s current filename, which is the same value caller reports in list context as element [1] and which die / warn use to build their default "at FILE line LINE." suffix.

That filename can be rewritten by a #line directive embedded in the source — see Edge cases below. Once rewritten, __FILE__ tokens compiled after the directive report the new name.

Examples#

Identify the running script in a log line:

warn "started from ", __FILE__, "\n";
# started from /tmp/run.pl

Attach source location to a custom error without die’s default suffix:

sub fail {
    my ($msg) = @_;
    die sprintf("%s at %s line %d\n", $msg, __FILE__, __LINE__);
}

Build a path relative to the current module, so resource files ship alongside the code that loads them:

use File::Basename qw(dirname);
use File::Spec;
my $data = File::Spec->catfile(dirname(__FILE__), "data.txt");

Use __FILE__ inside a string passed to eval to keep error reports pointing at the original source rather than at the anonymous (eval N) buffer:

my $code = qq[\n#line ] . __LINE__ . qq[ "] . __FILE__ . qq["\n]
         . q[die "boom"];
eval $code;
# boom at <current file> line <current line>.

Distinguish “run as a script” from “loaded as a module” — the common test is whether the file was invoked directly:

__PACKAGE__->run(@ARGV) if __FILE__ eq $0;

Edge cases#

Compile-time, not runtime. __FILE__ is a token the parser replaces with a string literal. It is not a function you can take a reference to; \&__FILE__ is a syntax error. Stringify it, store it, or pass it — but you cannot defer its evaluation.
Stable per occurrence. Calling the same subroutine from two different files does not change the __FILE__ the subroutine body sees; that value was baked in when the subroutine was compiled. If you need the caller’s filename, use caller.
#line directives rewrite the value. A comment of the form # line N "NAME" at column zero resets both the line number and (optionally) the filename the compiler reports. Every __FILE__ token compiled after such a directive picks up the new name. This is the mechanism code generators and template engines use to make errors point at the original .tt / .pod / .xs source instead of the generated .pl.
```
# line 1 "config.tt"
my $x = __FILE__;       # "config.tt"
```
Full syntax of the directive is specified in perlsyn under Plain Old Comments (Not!).
Modules. Inside a module, __FILE__ is the path require used to load the file — usually absolute and under an @INC root. Do not parse it as Some/Module.pm; use dirname(__FILE__) if you need the directory, not string surgery.
Special command-line sources. Code from -e reports -e; code from -E reports -e as well; code piped on stdin reports -. String eval without a #line directive reports (eval N) where N is the eval counter.
One-argument open and its __FILE__ lookalike. There is no __FILE__ handle; the token has nothing to do with filehandles. open(__FILE__) does not open the current source file — it tries to open a file literally named after the token’s expanded string, which is rarely what you want.
Not modifiable at runtime. Assigning to __FILE__ is a syntax error. The mechanism for changing what __FILE__ reports is the #line directive at compile time; there is no runtime equivalent.

Differences from upstream#

Fully compatible with upstream Perl 5.42.