B#
Inspect a running Perl program’s own optree, symbol table, and compiled subs.
B is the compiler back-end interface. It hands a script introspective access to the data structures the interpreter already holds: the root of the main optree, every compiled sub’s CV, the symbol table (stash) graph, and the SV/AV/HV/GV objects those structures point at. Subclasses such as B::OP, B::CV, B::GV, B::SV (and its type-specific children) wrap those pointers as blessed Perl objects with accessor methods.
Common callers are back-end modules like B::Deparse, B::Concise, and B::Xref; debugging tooling that walks the optree; and scripts that introspect the symbol table to generate code or diagnostics.
Functions#
Entry points#
svref_2object#
Wrap a reference’s referent as a B::* object.
opnumber#
Return the numeric op-type for an op name, or -1 if unknown.
ppname#
Return the pp_-prefixed name for a numeric op-type.
Synopsis
my $name = B::ppname($op->type); # e.g. "pp_print"
Inverse of B::opnumber. Returns undef if the number is out of range.
sv_undef#
Return a B::SPECIAL wrapping perl’s shared PL_sv_undef.
sv_yes#
Return a B::SPECIAL wrapping perl’s shared PL_sv_yes.
sv_no#
Return a B::SPECIAL wrapping perl’s shared PL_sv_no.
main_root#
Return a B::OP for the root of the program’s main optree.
main_start#
Return a B::OP for the first op executed in the main program.
Synopsis
my $start = B::main_start;
Where B::main_root gives the syntactic root, B::main_start gives the head of the linked list perl follows at run time via op_next.
cast_I32#
Truncate $i to a signed 32-bit integer.
Synopsis
B::cast_I32(0x1_0000_0001); # 1 (low 32 bits, sign-extended)
Exists so Perl back-ends can reproduce perl’s own I32 truncation when they need to emit exact values for an op field typed I32 in C.
amagic_generation#
Return the overload-magic generation counter (always 0 in modern perl).
address#
Return the memory address of an SV as an integer.
Synopsis
my $addr = B::address(\$x);
Mostly useful as an identity key: two B::* objects wrapping the same underlying SV will report the same address.
threadsv_names#
Return the list of thread-local special-variable names (empty).
minus_c#
Request that compilation stop after the compile phase (-c).
save_begins#
Request that BEGIN blocks be saved rather than freed (save_BEGINs).
Walking the optree#
walkoptree#
Recursively walk an optree, calling $method on each op.
walkoptree_debug#
Get or set the walkoptree debug flag.
String and hash helpers#
cstring#
Return $sv’s contents as a double-quoted C-style string literal.
perlstring#
Return $sv’s contents as a double-quoted Perl string literal.
Synopsis
B::perlstring('say $x@y'); # "say \$x\@y"
Like B::cstring, but also escapes $ and @ so the result can be pasted back into Perl source without interpolation surprises.
cchar#
Return the first character of $sv as a single-quoted C character literal.
hash#
Return perl’s hash of a string, formatted as 0xNNNNNNNN.
B::SV methods#
sv_refcnt#
Return the reference count of the wrapped SV.
sv_flags#
Return the raw SvFLAGS word of the wrapped SV.
sv_svtype#
Return the SV type as a numeric SVt_* code.
object_2svref#
Return a Perl reference back to the SV wrapped by a B::* object.
B::IV methods#
rhe_hash#
Return the integer value of the wrapped SV, stringifying if necessary.
iv_ivx#
Return the IV slot of the wrapped SV without coercion.
iv_uvx#
Return the UV slot of the wrapped SV without coercion.
iv_iv#
Return the SV’s IV slot without coercion (B::IV::IV).
B::NV methods#
nv_svnv#
Return the floating-point value of the wrapped SV, coercing if needed.
nv_nvx#
Return the NV slot of the wrapped SV without coercion.
B::PV methods#
pv_pv#
Return the string contents of a PV SV, preserving SVf_UTF8.
pv_pvx#
Return the PV buffer contents as a C-style NUL-terminated string.
pv_cur#
Return the current length in bytes of the PV buffer (SvCUR).
pv_len#
Return the allocated buffer size in bytes (SvLEN).
pv_rv#
Return the referent of a reference SV as a B:: object (B::PV::RV).
B::CV methods#
cv_gv#
Return the B::GV that a named CV belongs to.
cv_stash#
Return the B::HV for the package the CV was compiled in.
cv_file#
Return the source filename the CV was compiled from.
Synopsis
print $cv->FILE; # e.g. "MyModule.pm"
Returns an empty string for XSUBs that do not carry a file record.
cv_root#
Return the root op of the CV’s optree, or B::NULL for an XSUB.
Synopsis
my $root = $cv->ROOT;
XSUBs carry compiled C code and have no optree, so ROOT returns a B::NULL. Test with $cv->CvFLAGS & B::CVf_ISXSUB first if it matters.
cv_xsub#
Return the CV’s C function pointer as an integer, or 0 for a Perl sub.
Synopsis
my $addr = $cv->XSUB; # non-zero iff the sub is an XSUB
cv_xsubany#
Return CvXSUBANY - per-XSUB private data.
Synopsis
my $any = $cv->XSUBANY; # any_iv; 0 for Perl subs
my $sv = $const_cv->XSUBANY; # B object of the constant for CvCONST subs
cv_start#
Return the first op executed in the CV’s body, or B::NULL for an XSUB.
cv_depth#
Return the current recursion depth of the sub.
cv_cvflags#
Return the raw CvFLAGS word of the CV.
cv_name_hek#
Return the CV’s name when it was stored as a HEK rather than via a GV.
cv_outside#
Return the lexically enclosing CV (CvOUTSIDE).
cv_padlist#
Return the CV’s padlist as a B::PADLIST, or B::NULL for an XSUB.
cv_outside_seq#
Return the COP sequence number at which the CV was closed over.
cv_cvconst#
Return true if the CV is a constant (inlinable) sub (CvCONST).
cv_const_sv#
Return the SV a constant sub yields, as a B:: object (const_sv).
B::GV methods#
gv_name#
Return the GV’s unqualified name.
gv_safename#
Return the GV’s name with control characters rendered as ^X.
gv_file#
Return the source file that first introduced the GV.
Synopsis
print $gv->FILE; # e.g. "MyModule.pm"
The filename perl recorded when the glob was created or first accessed as an lvalue. An empty string for globs with no recorded origin.
gv_stash#
Return the B::HV for the stash that owns the GV.
gv_sv#
Return the scalar slot of the GV as a B::SV.
gv_form#
Return the format slot of the GV as a B::CV (stash walking via O=Deparse visits every GP slot).
gv_io#
Return the IO slot of the GV as a B::IO.
gv_cvgen#
Return the GV’s method-cache generation number.
gv_av#
Return the array slot of the GV as a B::AV.
gv_hv#
Return the hash slot of the GV as a B::HV.
gv_cv#
Return the code slot of the GV as a B::CV.
gv_egv#
Return the “effective” GV (GvEGV) - for aliased globs, the canonical one.
gv_refcnt#
Return the refcount of the GV’s GP (slot-bundle) record.
gv_line#
Return the source line where the GV was first introduced.
gv_isgv_with_gp#
Return true if the SV is a GV that has a GP slot-bundle attached.
gv_is_empty#
Return true if the GV has no slot-bundle (GP) at all.
gv_flags_wrapper#
Return the raw SvFLAGS word of the GV (same as B::SV::FLAGS).
gv_gvflags#
Return the GV-specific flag bits.
gv_svtype#
Return the SV type code (same as B::SV::SvTYPE).
B::HV methods#
hv_name#
Return the package name of a stash HV.
hv_keys#
Return the number of keys in the hash (HvKEYS).
hv_array#
Return the hash’s contents as a key/B-object list (stash walking: B::Deparse’s stash_subs via O=Deparse is the main consumer).
hv_max#
Return the hash’s bucket-array size (HvMAX).
hv_fill#
Return the number of used buckets (HvFILL).
hv_riter#
Return the hash’s iterator position (HvRITER).
Interpreter globals#
intrpvar_main_cv#
Return a B::CV for the implicit CV of the main program.
intrpvar_inc_gv#
Return a B::GV for *INC, the module-loading search list.
intrpvar_defstash#
Return a B::HV for %main::, the default stash.
intrpvar_curstash#
Return a B::HV for the currently active compile-time stash.
intrpvar_warnhook#
Return a B::SV for the current $SIG{__WARN__} handler.
intrpvar_diehook#
Return a B::SV for the current $SIG{__DIE__} handler.
intrpvar_initav#
Return a B::AV of the INIT blocks queued for execution.
intrpvar_checkav#
Return a B::AV of CHECK blocks queued for execution.
intrpvar_unitcheckav#
Return a B::AV of UNITCHECK blocks queued for execution.
intrpvar_endav#
Return a B::AV of END blocks queued to run at interpreter exit.
Other Functions#
unop_aux_string#
Return a string representation of op_aux where possible.
unop_aux_aux_list#
Return the contents of the op_aux array as a list of IV/GV/etc.
op_next#
Return the next op in execution order (op_next). @category B::OP methods
op_sibling#
Return the next syntactic sibling. @category B::OP methods
op_targ#
Return the op’s pad target index (op_targ). @category B::OP methods
op_flags#
Return the op’s shared flag byte (op_flags). @category B::OP methods
op_private#
Return the op’s private flag byte (op_private). @category B::OP methods
op_first#
Return the first child of a UNOP (op_first). @category B::OP methods
op_last#
Return the last child of a BINOP/LISTOP (op_last). @category B::OP methods
op_other#
Return a LOGOP’s alternate branch target (op_other). @category B::OP methods
op_redoop#
Return a LOOP’s redo target (op_redoop). @category B::OP methods
op_nextop#
Return a LOOP’s next target (op_nextop). @category B::OP methods
op_lastop#
Return a LOOP’s last target (op_lastop). @category B::OP methods
op_pmflags#
Return a PMOP’s compiled-pattern flags (op_pmflags). @category B::OP methods
op_sv#
Return an SVOP’s SV payload (op_sv). @category B::OP methods
op_gv#
Return an SVOP’s GV payload (op_sv, GV-typed). @category B::OP methods
op_padix#
Return a PADOP’s pad index (op_padix). @category B::OP methods
op_cop_seq#
Return a COP’s compile sequence number (cop_seq). @category B::OP methods
op_line#
Return a COP’s source line number (cop_line). @category B::OP methods
op_hints#
Return a COP’s hint bits (cop_hints). @category B::OP methods
op_file#
Return a COP’s source filename (CopFILE). @category B::OP methods
op_stash#
Return a COP’s package stash as a B::HV (cop_stash). @category B::OP methods
op_stashpv#
Return a COP’s package name (CopSTASHPV). @category B::OP methods
op_name#
Return the short op name (e.g. “print”). @category B::OP methods
op_desc#
Return the human-readable op description. @category B::OP methods
op_ppaddr#
Return a C-source reference to the op’s pp function. @category B::OP methods
op_type#
Return the numeric op-type code (op_type). @category B::OP methods
op_opt#
Return the op_opt bit (peephole-optimised flag). @category B::OP methods
op_children#
Return the number of children in a LISTOP. @category B::OP methods
op_pmreplroot#
Return a PMOP’s replacement-optree root (pmreplroot). @category B::OP methods
op_precomp#
Return a PMOP’s precompiled pattern source (RX_PRECOMP). @category B::OP methods
op_label#
Return a COP’s statement label, or undef (CopLABEL). @category B::OP methods
op_moresib#
Return the op_moresib bit. @category B::OP methods
op_parent#
Return the syntactic parent of the op. @category B::OP methods
op_methop_first#
Return a METHOP’s first child for dynamic method calls. @category B::OP methods
op_meth_sv#
Return a METHOP’s method-name SV (meth_sv). @category B::OP methods
op_pmregexp#
Return a PMOP’s compiled regexp as a B::REGEXP. @category B::OP methods
op_rclass#
Return a METHOP’s redirect class SV (rclass). @category B::OP methods
av_fill#
Return the logical last index of the array (AvFILL, i.e. $#a).
av_max#
Return the allocated capacity of the array (AvMAX).
av_array#
Return the array’s elements as a list of B:: objects (AvARRAY).
av_arrayelt#
Return the Nth element as a B:: object (AvARRAYelt).
padlist_max#
Return the highest index in the padlist (PadlistMAX).
padlist_names#
Return the padlist’s PADNAMELIST (PadlistNAMES).
padlist_array#
Return (NAMES, pad, pad, …) as a list (PadlistARRAY).
padlist_arrayelt#
Return the Nth padlist element (PadlistARRAYelt).
padnamelist_max#
Return the highest index in the padname list (PadnamelistMAX).
padnamelist_array#
Return the padnames as a list of B::PADNAME objects (PadnamelistARRAY).
padnamelist_arrayelt#
Return the Nth padname as a B::PADNAME (PadnamelistARRAYelt).
padname_pv#
Return the pad name PV with its sigil (e.g. “$x”, “@arr”) (PadnamePV).
padname_len#
Return the pad name length in bytes (PadnameLEN).
padname_flags#
Return the pad name flags (PadnameFLAGS), with SVf_FAKE OR’d for OUTER.
padname_type#
Return the padname’s type stash as a B:: object (PadnameTYPE).
padname_ourstash#
Return the ‘our’ stash for the padname (PadnameOURSTASH).