# B

📦 min

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`](B/svref_2object.md) Wrap a reference’s referent as a `B::*` object. #### [`opnumber`](B/opnumber.md) 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** ```perl 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`](B/main_root.md) 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** ```perl 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** ```perl 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** ```perl 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`](B/walkoptree.md) Recursively walk an optree, calling `$method` on each op. #### [`walkoptree_debug`](B/walkoptree_debug.md) Get or set the `walkoptree` debug flag. ### String and hash helpers #### [`cstring`](B/cstring.md) 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** ```perl 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`](B/cchar.md) Return the first character of `$sv` as a single-quoted C character literal. #### [`hash`](B/hash.md) Return perl’s hash of a string, formatted as `0xNNNNNNNN`. ### B::SV methods #### [`sv_refcnt`](B/sv_refcnt.md) Return the reference count of the wrapped SV. #### `sv_flags` Return the raw `SvFLAGS` word of the wrapped SV. #### [`sv_svtype`](B/sv_svtype.md) Return the SV type as a numeric `SVt_*` code. #### [`object_2svref`](B/object_2svref.md) 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`](B/pv_pv.md) 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`](B/cv_gv.md) 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** ```perl 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** ```perl 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`](B/cv_name_hek.md) 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`](B/gv_name.md) Return the GV’s unqualified name. #### [`gv_safename`](B/gv_safename.md) Return the GV’s name with control characters rendered as `^X`. #### `gv_file` Return the source file that first introduced the GV. **Synopsis** ```perl 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`](B/gv_sv.md) 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`](B/hv_name.md) 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** ```perl 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`](B/op_ppaddr.md) 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** ```perl 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_beginav` Return a `B::AV` of `BEGIN` blocks already executed. #### `intrpvar_endav` Return a `B::AV` of `END` blocks queued to run at interpreter exit.