Returns the context of the current pure perl subroutine call.  In scalar
context, returns the caller's package name if there is a caller (that is, if
we're in a subroutine or eval or require) and the undefined value
otherwise.  caller never returns XS subs and they are skipped.  The next pure
perl sub will appear instead of the XS
sub in caller's return values.  In list
context, caller returns
- # 0 1 2
- ($package, $filename, $line) = caller;
With EXPR, it returns some extra information that the debugger uses to print a stack trace. The value of EXPR indicates how many call frames to go back before the current one.
- # 0 1 2 3 4
- ($package, $filename, $line, $subroutine, $hasargs,
- # 5 6 7 8 9 10
- $wantarray, $evaltext, $is_require, $hints, $bitmask, $hinthash)
- = caller($i);
Here, $subroutine is the function that the caller called (rather than the
function containing the caller).  Note that $subroutine may be (eval)
 if
the frame is not a subroutine call, but an eval.  In such a case
additional elements $evaltext and
$is_require
 are set: $is_require
 is true if the frame is created by a
require or use statement, $evaltext contains the text of the
eval EXPR
 statement.  In particular, for an eval BLOCK
 statement,
$subroutine is (eval)
, but $evaltext is undefined.  (Note also that
each use statement creates a require frame inside an eval EXPR
frame.)  $subroutine may also be (unknown)
 if this particular
subroutine happens to have been deleted from the symbol table.
$hasargs
 is true if a new instance of @_
 was set up for the frame.
$hints
 and $bitmask
 contain pragmatic hints that the caller was
compiled with.  $hints
 corresponds to $^H
, and $bitmask
corresponds to ${^WARNING_BITS}
.  The
$hints
 and $bitmask
 values are subject
to change between versions of Perl, and are not meant for external use.
$hinthash
 is a reference to a hash containing the value of %^H
 when the
caller was compiled, or undef if %^H
 was empty.  Do not modify the values
of this hash, as they are the actual values stored in the optree.
Furthermore, when called from within the DB package in
list context, and with an argument, caller returns more
detailed information: it sets the list variable @DB::args
 to be the
arguments with which the subroutine was invoked.
Be aware that the optimizer might have optimized call frames away before
caller had a chance to get the information.  That means that caller(N)
might not return information about the call frame you expect it to, for
N > 1
.  In particular, @DB::args
 might have information from the
previous time caller was called.
Be aware that setting @DB::args
 is best effort, intended for
debugging or generating backtraces, and should not be relied upon.  In
particular, as @_
 contains aliases to the caller's arguments, Perl does
not take a copy of @_
, so @DB::args
 will contain modifications the
subroutine makes to @_
 or its contents, not the original values at call
time.  @DB::args
, like @_
, does not hold explicit references to its
elements, so under certain cases its elements may have become freed and
reallocated for other variables or temporary values.  Finally, a side effect
of the current implementation is that the effects of shift @_
 can
normally be undone (but not pop @_
 or other splicing, and not if a
reference to @_
 has been taken, and subject to the caveat about reallocated
elements), so @DB::args
 is actually a hybrid of the current state and
initial state of @_
.  Buyer beware.