1Callsite(3)           User Contributed Perl Documentation          Callsite(3)
2
3
4

NAME

6       Devel::Callsite - Get caller return OP address and Perl interpreter
7       context
8

SYNOPSIS

10         use Devel::Callsite;
11         my $site = sub { return callsite() };
12         my $op_addr = $site->();
13         printf "OP location: 0x%x\n", $op_addr;   # prints caller OP location
14         printf "OP location: 0x%x\n", $site->(); # prints a different OP location
15
16         sub foo { return callsite(1) };
17         sub bar { foo() };
18         # print this OP location even though it is 2 levels up the call chain.
19         printf "OP location: 0x%x\n", bar();
20
21         if ($] >= 5.025) {
22           printf "OP is: %s\n", addr_to_op($addr);
23           my $get_op = sub { return caller_nextop() };
24           printf "OP is now: %s\n", $get_op->();
25         }
26
27         print context(), "\n"; # prints the interpreter context, an unsigned number
28
29       Running the above gives:
30
31         OP location: 0x5572e41f89f8
32         OP location: 0x5572e421f5b0
33         OP is: B::NULL=SCALAR(0x5572e41d0578)
34         OP location: 0x5572e421f010
35         OP is now: B::LISTOP=SCALAR(0x5572e41d0578)
36         93951941730912
37

DESCRIPTION

39   callsite
40           $callsite = callsite();
41           $callsite = callsite($level);
42
43       This function returns the the OP address of the caller, a number. It
44       can take an optional integer specifying the number of levels back to
45       get the OP address. If no parameter is given, a value of 0 is used
46       which means to go up one level in the call chain. This behavior is like
47       the built-in function "caller".
48
49       This value is useful for functions that need to uniquely know where
50       they were called, such as Every::every(); see Every. Or it can be used
51       to pinpoint a location with finer granularity than a line number
52       <http://www.perlmonks.com/?node_id=987268>. In conjunction with an OP
53       tree disassembly you can know exactly where the caller is located in
54       the Perl source.
55
56       As of version 0.08, this function will return the expected call site
57       for functions called via "DB::sub". (Previously it returned a call site
58       inside the debugger.) If "callsite" is called from package "DB" in list
59       context, it will return two numbers. The first is the ordinary return
60       value; the second is the 'true' call site of the function in question,
61       which may be different if "DB::sub" is in use.
62
63   addr_to_op
64       For now this is only in 5.026 or greater.
65
66           $op = caller_nextop();
67           $op = caller_nextop($level);
68
69   caller_nextop
70       For now this is only in 5.026 or greater.
71
72           $op = caller_nextop();
73           $op = caller_nextop($level);
74
75       This function returns the the "B::OP", not the address, of the next OP
76       to get run after the call is made. It is equivalent to:
77
78           addr_to_op(callsite($level));
79
80   context
81           $context = context()
82
83       This function returns the interpreter context as a number. Using
84       "callsite" alone to identify the call site is not reliable in programs
85       which may include multiple Perl interpreters, such as when using
86       ithreads. Combining "callsite" with "context" gives a unique location.
87

HISTORY

89       Ben Morrow conceived this and posted it to perl5-porters. Ted Zlatanov
90       then turned it into a CPAN module which he maintained for the first 3
91       revisions. Ben also added the level parameter to callsite.
92
93       ikegami provided the function to turn the address into a real "B::OP".
94
95       It is currently maintained (or not) by Rocky Bernstein.
96

SEE ALSO

98       B::Concise to disassemble the OP tree. Devel::Trepan optionally uses
99       Devel::Callsite to show you exactly where you are stopped inside the
100       debugger.
101

AUTHORS

103       Rocky Bernstein <rocky@cpan.org> (current maintainer) Ted Zlatanov
104       <tzz@lifelogs.com> Ben Morrow ikegami
105

107       Copyright (C) 2013, 2018 Rocky Bernstein <rocky@cpan.org>, Ted
108       Zlatanov, <tzz@lifelogs.com>, Ben Morrow
109
110       This program is distributed WITHOUT ANY WARRANTY, including but not
111       limited to the implied warranties of merchantability or fitness for a
112       particular purpose.
113
114       The program is free software. You may distribute it and/or modify it
115       under the terms of the GNU General Public License as published by the
116       Free Software Foundation (either version 2 or any later version) and
117       the Perl Artistic License as published by O’Reilly Media, Inc. Please
118       open the files named gpl-2.0.txt and Artistic for a copy of these
119       licenses.
120
121
122
123perl v5.38.0                      2023-07-20                       Callsite(3)
Impressum