.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" ======================================================================== .\" .IX Title "Callsite 3pm" .TH Callsite 3pm "2014-03-11" "perl v5.24.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Devel::Callsite \- Get caller return OP address and Perl interpreter context .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 4 \& use Devel::Callsite; \& my $site = sub { return callsite() }; \& printf "OP location: 0x%x\en", $site\->(); # prints caller OP location \& printf "OP location: 0x%x\en", $site\->(); # prints a different OP location \& \& \& sub foo { return callsite(1) }; \& sub bar { foo() }; \& # print this OP location even though it is 2 levels up the call chain. \& printf "OP location: 0x%x\en", bar(); \& \& print context(), "\en"; # prints the interpreter context, an unsigned number .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" .SS "callsite" .IX Subsection "callsite" .Vb 2 \& $callsite = callsite() \& $callsite = callsite($level) .Ve .PP This function returns the the \s-1OP\s0 address of the caller, a number. It can take an optional integer specifying the number of levels back to get the \s-1OP\s0 address. If no parameter is given, a value of 0 is used which means to go up one level in the call chain. This behavior is like the built-in function \f(CW\*(C`caller\*(C'\fR. .PP This value is useful for functions that need to uniquely know where they were called, such as \f(CW\*(C`Every::every()\*(C'\fR; see Every. Or it can be used to pinpoint a location with finer granularity than a line number . In conjunction with an \s-1OP\s0 tree disassembly you can know exactly where the caller is located in the Perl source. .PP As of version 0.08, this function will return the expected call site for functions called via \f(CW\*(C`DB::sub\*(C'\fR. (Previously it returned a call site inside the debugger.) If \f(CW\*(C`callsite\*(C'\fR is called from package \f(CW\*(C`DB\*(C'\fR in list context, it will return two numbers. The first is the ordinary return value; the second is the 'true' call site of the function in question, which may be different if \f(CW\*(C`DB::sub\*(C'\fR is in use. .SS "context" .IX Subsection "context" .Vb 1 \& $context = context() .Ve .PP This function returns the interpreter context as a number. Using \&\f(CW\*(C`callsite\*(C'\fR alone to identify the call site is not reliable in programs which may include multiple Perl interpreters, such as when using ithreads. Combining \f(CW\*(C`callsite\*(C'\fR with \f(CW\*(C`context\*(C'\fR gives a unique location. .SH "HISTORY" .IX Header "HISTORY" Ben Morrow conceived this and posted it to perl5\-porters. Ted Zlatanov then turned it into a \s-1CPAN\s0 module which he maintained for the first 3 revisions. Ben also added the level parameter to callsite. .PP It is currently maintained (or not) by Rocky Bernstein. .SH "SEE ALSO" .IX Header "SEE ALSO" B::Concise to disassemble the \s-1OP\s0 tree. Devel::Trepan optionally uses \fIDevel::Callsite\fR to show you exactly where you are stopped inside the debugger. .SH "AUTHORS" .IX Header "AUTHORS" Rocky Bernstein (current maintainer) Ted Zlatanov Ben Morrow .SH "LICENSE AND COPYRIGHT" .IX Header "LICENSE AND COPYRIGHT" Copyright (C) 2013 Rocky Bernstein , Ted Zlatanov, , Ben Morrow .PP This program is distributed \s-1WITHOUT ANY WARRANTY,\s0 including but not limited to the implied warranties of merchantability or fitness for a particular purpose. .PP The program is free software. You may distribute it and/or modify it under the terms of the \s-1GNU\s0 General Public License as published by the Free Software Foundation (either version 2 or any later version) and the Perl Artistic License as published by O’Reilly Media, Inc. Please open the files named gpl\-2.0.txt and Artistic for a copy of these licenses.