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).
parents#
Return a reference to @B::parents.
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#
iv_sviv#
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.
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).
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_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.
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_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.
B::OP methods#
op_next#
Return the next op in execution order (op_next).
op_sibling#
Return the next syntactic sibling under the same parent.
op_targ#
Return the op’s pad target index (op_targ).
op_flags#
Return the op’s shared flag byte (op_flags).
op_private#
Return the op’s private flag byte (op_private).
op_first#
Return the first child of a UNOP (or any op with OPf_KIDS).
op_name#
Return the short name for the op type (e.g. "print", "aelem").
op_desc#
Return the human-readable description of the op type.
Synopsis
print $op->desc; # e.g. "array element"
Longer and more natural than B::OP::name. Used in diagnostic messages
such as “Can’t modify X in Y”.
op_ppaddr#
Return a C-source-style reference to the op’s pp function.
op_type#
Return the numeric op-type code.
op_opt#
Return the op_opt bit: non-zero once the peephole optimiser has run.
op_moresib#
Return the op_moresib bit: true if the op has another sibling after it.
op_parent#
Return the syntactic parent of the op.
op_children#
Return the number of children in a LISTOP.
Synopsis
print $listop->children; # integer count
Counted by walking from first through sibling. Trivially 0 for a
LISTOP with no kids; most real LISTOPs have at least one.
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.