How to use caller() to get subroutine call information in Perl?

Using caller() to Get Subroutine Call Information in Perl

The caller() function in Perl is a powerful introspection tool that lets you retrieve information about the calling subroutine or the call stack. This is especially useful for debugging, logging, or creating complex control flows based on who invoked a subroutine.

At its simplest, caller returns the calling package, filename, and line number. But you can get far more detailed information, such as the subroutine name, context, and even warnings flags, by calling it in list context and supplying an optional call frame number.

How caller() Works

• caller() with no arguments returns info about the immediate caller (the subroutine or code that called the current subroutine).
• caller($level) returns info from the call stack $level frames above the current one; caller(0) is the immediate caller, caller(1) is the caller’s caller, and so on.
• In scalar context, caller() returns the caller’s package name (or undef if there is no caller).
• In list context, caller() returns a list including package, filename, line, subroutine, hasargs, wantarray, evaltext, and more (Perl 5.10+).

Typical Return Values of caller($level) in List Context

my ($package, $filename, $line, $subroutine, $hasargs, $wantarray, 
    $evaltext, $is_require, $hints, $bitmask) = caller($level);

• $package: Name of the calling package.
• $filename: The file where the caller is located.
• $line: Line number in the file where call happened.
• $subroutine: Fully qualified subroutine name of the caller.
• $hasargs: Boolean, whether caller was called with arguments.
• $wantarray: Context in which caller was invoked (true = list, false = scalar, undef = void).
• $evaltext: Source code of string eval if caller is eval.
• $is_require: Boolean, if caller is from require or use.
• $hints: Compile time hints.
• $bitmask: Deprecated internal bitmask.

Example: Printing Caller Information inside a Subroutine

The following example demonstrates how to use caller() to get call information at different call stack levels.

use strict;
use warnings;

sub print_caller_info {
    my ($level) = @_;
    $level //= 0;

    # In list context, get caller info for $level frames up
    my (
        $package, $filename, $line, $subroutine, $hasargs,
        $wantarray, $evaltext, $is_require
    ) = caller($level);

    if (defined $package) {
        print "Caller info at level $level:\n";
        print "  Package:   $package\n";
        print "  File:      $filename\n";
        print "  Line:      $line\n";
        print "  Subroutine: ", ($subroutine // 'MAIN:: (main script)'), "\n";
        print "  Called with args? ", ($hasargs ? "Yes" : "No"), "\n";
        print "  Context:    ";
        print defined $wantarray ? ($wantarray ? "List" : "Scalar") : "Void";
        print "\n";
        print "  From eval?  ", ($evaltext ? "Yes" : "No"), "\n";
        print "  Require/use? ", ($is_require ? "Yes" : "No"), "\n";
    } else {
        print "No caller found at level $level!\n";
    }
    print "\n";
}

sub foo {
    print_caller_info(0);   # immediate caller of print_caller_info (foo)
    print_caller_info(1);   # caller of foo
}

sub bar {
    foo();
}

print "Starting from main...\n";
foo();

print "Calling bar...\n";
bar();

# Directly calling print_caller_info from main
print_caller_info();

Output Example

This will print detailed information on the subroutine call stack, such as:

Starting from main...
Caller info at level 0:
  Package:   main
  File:      your_script.pl
  Line:      27
  Subroutine: main::foo
  Called with args? No
  Context:    Void
  From eval?  No
  Require/use? No

Caller info at level 1:
  Package:   main
  File:      your_script.pl
  Line:      33
  Subroutine: main::(main script)
  ...
Calling bar...
Caller info at level 0:
  Package:   main
  ...

Important Notes & Gotchas

• Context matters: caller() behaves differently in scalar vs list context. Use list context to get detailed info.
• Frame level: The call stack level passed to caller() can result in undef if you request a frame beyond the bottom of the stack.
• Subroutine name may be missing: When the caller is the main script or eval code, the subroutine name might be missing or look like main::(main script).
• Perl versions: Info beyond the first three items (package, filename, line) were added in Perl 5.10+. Ensure your Perl version supports them.
• Use in CPAN modules: Many CPAN modules use caller() for advanced debugging, error reporting, or method dispatch.

Summary

The caller() function is essential for advanced Perl coding tasks where you need to introspect the call stack. Its flexibility allows you to trace calls from any level, inspect calling contexts, and glean detailed subroutine call metadata to build robust diagnostics or dynamic behaviors.