1B(3pm) Perl Programmers Reference Guide B(3pm)
2
6 B - The Perl Compiler Backend
7
9 use B;
10
12 The "B" module supplies classes which allow a Perl program to delve
13 into its own innards. It is the module used to implement the
14 "backends" of the Perl compiler. Usage of the compiler does not
15 require knowledge of this module: see the O module for the user-visible
16 part. The "B" module is of use to those who want to write new compiler
17 backends. This documentation assumes that the reader knows a fair
18 amount about perl's internals including such things as SVs, OPs and the
19 internal symbol table and syntax tree of a program.
20
22 The "B" module contains a set of utility functions for querying the
23 current state of the Perl interpreter; typically these functions return
24 objects from the B::SV and B::OP classes, or their derived classes.
25 These classes in turn define methods for querying the resulting objects
26 about their own internal state.
27
29 The "B" module exports a variety of functions: some are simple utility
30 functions, others provide a Perl program with a way to get an initial
31 "handle" on an internal object.
32 Functions Returning "B::SV", "B::AV", "B::HV", and "B::CV" objects
34 For descriptions of the class hierarchy of these objects and the
35 methods that can be called on them, see below, "OVERVIEW OF CLASSES"
36 and "SV-RELATED CLASSES".
37 sv_undef
39 Returns the SV object corresponding to the C variable "sv_undef".
40 sv_yes
42 Returns the SV object corresponding to the C variable "sv_yes".
43 sv_no
45 Returns the SV object corresponding to the C variable "sv_no".
46 svref_2object(SVREF)
48 Takes a reference to any Perl value, and turns the referred-to
49 value into an object in the appropriate B::OP-derived or
50 B::SV-derived class. Apart from functions such as "main_root",
51 this is the primary way to get an initial "handle" on an internal
52 perl data structure which can then be followed with the other
53 access methods.
54 The returned object will only be valid as long as the underlying
56 OPs and SVs continue to exist. Do not attempt to use the object
57 after the underlying structures are freed.
58 amagic_generation
60 Returns the SV object corresponding to the C variable
61 "amagic_generation". As of Perl 5.18, this is just an alias to
62 "PL_na", so its value is meaningless.
63 init_av
65 Returns the AV object (i.e. in class B::AV) representing INIT
66 blocks.
67 check_av
69 Returns the AV object (i.e. in class B::AV) representing CHECK
70 blocks.
71 unitcheck_av
73 Returns the AV object (i.e. in class B::AV) representing UNITCHECK
74 blocks.
75 begin_av
77 Returns the AV object (i.e. in class B::AV) representing BEGIN
78 blocks.
79 end_av
81 Returns the AV object (i.e. in class B::AV) representing END
82 blocks.
83 comppadlist
85 Returns the PADLIST object (i.e. in class B::PADLIST) of the global
86 comppadlist. In Perl 5.16 and earlier it returns an AV object
87 (class B::AV).
88 regex_padav
90 Only when perl was compiled with ithreads.
91 main_cv
93 Return the (faked) CV corresponding to the main part of the Perl
94 program.
95 Functions for Examining the Symbol Table
97 walksymtable(SYMREF, METHOD, RECURSE, PREFIX)
98 Walk the symbol table starting at SYMREF and call METHOD on each
99 symbol (a B::GV object) visited. When the walk reaches package
100 symbols (such as "Foo::") it invokes RECURSE, passing in the symbol
101 name, and only recurses into the package if that sub returns true.
102 PREFIX is the name of the SYMREF you're walking.
104 For example:
106 # Walk CGI's symbol table calling print_subs on each symbol.
108 # Recurse only into CGI::Util::
109 walksymtable(\%CGI::, 'print_subs',
110 sub { $_[0] eq 'CGI::Util::' }, 'CGI::');
111 print_subs() is a B::GV method you have declared. Also see "B::GV
113 Methods", below.
114 Functions Returning "B::OP" objects or for walking op trees
116 For descriptions of the class hierarchy of these objects and the
117 methods that can be called on them, see below, "OVERVIEW OF CLASSES"
118 and "OP-RELATED CLASSES".
119 main_root
121 Returns the root op (i.e. an object in the appropriate
122 B::OP-derived class) of the main part of the Perl program.
123 main_start
125 Returns the starting op of the main part of the Perl program.
126 walkoptree(OP, METHOD)
128 Does a tree-walk of the syntax tree based at OP and calls METHOD on
129 each op it visits. Each node is visited before its children. If
130 "walkoptree_debug" (see below) has been called to turn debugging on
131 then the method "walkoptree_debug" is called on each op before
132 METHOD is called.
133 walkoptree_debug(DEBUG)
135 Returns the current debugging flag for "walkoptree". If the
136 optional DEBUG argument is non-zero, it sets the debugging flag to
137 that. See the description of "walkoptree" above for what the
138 debugging flag does.
139 Miscellaneous Utility Functions
141 ppname(OPNUM)
142 Return the PP function name (e.g. "pp_add") of op number OPNUM.
143 hash(STR)
145 Returns a string in the form "0x..." representing the value of the
146 internal hash function used by perl on string STR.
147 cast_I32(I)
149 Casts I to the internal I32 type used by that perl.
150 minus_c
152 Does the equivalent of the "-c" command-line option. Obviously,
153 this is only useful in a BEGIN block or else the flag is set too
154 late.
155 cstring(STR)
157 Returns a double-quote-surrounded escaped version of STR which can
158 be used as a string in C source code.
159 perlstring(STR)
161 Returns a double-quote-surrounded escaped version of STR which can
162 be used as a string in Perl source code.
163 safename(STR)
165 This function returns the string with the first character modified
166 if it is a control character. It converts it to ^X format first,
167 so that "\cG" becomes "^G". This is used internally by
168 B::GV::SAFENAME, but you can call it directly.
169 class(OBJ)
171 Returns the class of an object without the part of the classname
172 preceding the first "::". This is used to turn "B::UNOP" into
173 "UNOP" for example.
174 threadsv_names
176 This used to provide support for the old 5.005 threading module. It
177 now does nothing.
178 Exported utility variables
180 @optype
181 my $op_type = $optype[$op_type_num];
182 A simple mapping of the op type number to its type (like 'COP' or
184 'BINOP').
185 @specialsv_name
187 my $sv_name = $specialsv_name[$sv_index];
188 Certain SV types are considered 'special'. They're represented by
190 B::SPECIAL and are referred to by a number from the specialsv_list.
191 This array maps that number back to the name of the SV (like
192 'Nullsv' or '&PL_sv_undef').
193
195 The C structures used by Perl's internals to hold SV and OP information
196 (PVIV, AV, HV, ..., OP, SVOP, UNOP, ...) are modelled on a class
197 hierarchy and the "B" module gives access to them via a true object
198 hierarchy. Structure fields which point to other objects (whether
199 types of SV or types of OP) are represented by the "B" module as Perl
200 objects of the appropriate class.
201 The bulk of the "B" module is the methods for accessing fields of these
203 structures.
204 Note that all access is read-only. You cannot modify the internals by
206 using this module. Also, note that the B::OP and B::SV objects created
207 by this module are only valid for as long as the underlying objects
208 exist; their creation doesn't increase the reference counts of the
209 underlying objects. Trying to access the fields of a freed object will
210 give incomprehensible results, or worse.
211 SV-RELATED CLASSES
213 B::IV, B::NV, B::PV, B::PVIV, B::PVNV, B::PVMG, B::PVLV, B::AV, B::HV,
214 B::CV, B::GV, B::FM, B::IO. These classes correspond in the obvious
215 way to the underlying C structures of similar names. The inheritance
216 hierarchy mimics the underlying C "inheritance":
217 B::SV
219 |
220 +------------+------------+
221 | | |
222 B::PV B::IV B::NV
223 / \ / /
224 / \ / /
225 B::INVLIST B::PVIV /
226 \ /
227 \ /
228 \ /
229 B::PVNV
230 |
231 |
232 B::PVMG
233 |
234 +-------+-------+---+---+-------+-------+
235 | | | | | |
236 B::AV B::GV B::HV B::CV B::IO B::REGEXP
237 | |
238 | |
239 B::PVLV B::FM
240 Access methods correspond to the underlying C macros for field access,
242 usually with the leading "class indication" prefix removed (Sv, Av, Hv,
243 ...). The leading prefix is only left in cases where its removal would
244 cause a clash in method name. For example, "GvREFCNT" stays as-is
245 since its abbreviation would clash with the "superclass" method
246 "REFCNT" (corresponding to the C function "SvREFCNT").
247 B::SV Methods
249 REFCNT
250 FLAGS
251 object_2svref
252 Returns a reference to the regular scalar corresponding to this
253 B::SV object. In other words, this method is the inverse operation
254 to the svref_2object() subroutine. This scalar and other data it
255 points at should be considered read-only: modifying them is neither
256 safe nor guaranteed to have a sensible effect.
257 B::IV Methods
259 IV Returns the value of the IV, interpreted as a signed integer. This
260 will be misleading if "FLAGS & SVf_IVisUV". Perhaps you want the
261 "int_value" method instead?
262 IVX
264 UVX
265 int_value
266 This method returns the value of the IV as an integer. It differs
267 from "IV" in that it returns the correct value regardless of
268 whether it's stored signed or unsigned.
269 needs64bits
271 packiv
272 B::NV Methods
274 NV
275 NVX
276 COP_SEQ_RANGE_LOW
277 COP_SEQ_RANGE_HIGH
278 These last two are only valid for pad name SVs. They only existed
279 in the B::NV class before Perl 5.22. In 5.22 they were moved to
280 the B::PADNAME class.
281 B::RV Methods
283 RV
284 B::PV Methods
286 PV This method is the one you usually want. It constructs a string
287 using the length and offset information in the struct: for ordinary
288 scalars it will return the string that you'd see from Perl, even if
289 it contains null characters.
290 RV Same as B::RV::RV, except that it will die() if the PV isn't a
292 reference.
293 PVX This method is less often useful. It assumes that the string
295 stored in the struct is null-terminated, and disregards the length
296 information.
297 It is the appropriate method to use if you need to get the name of
299 a lexical variable from a padname array. Lexical variable names
300 are always stored with a null terminator, and the length field
301 (CUR) is overloaded for other purposes and can't be relied on here.
302 CUR This method returns the internal length field, which consists of
304 the number of internal bytes, not necessarily the number of logical
305 characters.
306 LEN This method returns the number of bytes allocated (via malloc) for
308 storing the string. This is 0 if the scalar does not "own" the
309 string.
310 B::PVMG Methods
312 MAGIC
313 SvSTASH
314 B::MAGIC Methods
316 MOREMAGIC
317 precomp
318 Only valid on r-magic, returns the string that generated the
319 regexp.
320 PRIVATE
322 TYPE
323 FLAGS
324 OBJ Will die() if called on r-magic.
325 PTR
327 REGEX
328 Only valid on r-magic, returns the integer value of the REGEX
329 stored in the MAGIC.
330 B::INVLIST Methods
332 prev_index
333 Returns the cache result of previous invlist_search() (internal
334 usage)
335 is_offset
337 Returns a boolean value (0 or 1) to know if the invlist is using an
338 offset. When false the list begins with the code point U+0000.
339 When true the list begins with the following elements.
340 array_len
342 Returns an integer with the size of the array used to define the
343 invlist.
344 get_invlist_array
346 This method returns a list of integers representing the array used
347 by the invlist. Note: this cannot be used while in middle of
348 iterating on an invlist and croaks.
349 B::PVLV Methods
351 TARGOFF
352 TARGLEN
353 TYPE
354 TARG
355 B::BM Methods
357 USEFUL
358 PREVIOUS
359 RARE
360 TABLE
361 B::REGEXP Methods
363 REGEX
364 precomp
365 qr_anoncv
366 compflags
367 The last two were added in Perl 5.22.
368 B::GV Methods
370 is_empty
371 This method returns TRUE if the GP field of the GV is NULL.
372 NAME
374 SAFENAME
375 This method returns the name of the glob, but if the first
376 character of the name is a control character, then it converts it
377 to ^X first, so that *^G would return "^G" rather than "\cG".
378 It's useful if you want to print out the name of a variable. If
380 you restrict yourself to globs which exist at compile-time then the
381 result ought to be unambiguous, because code like "${"^G"} = 1" is
382 compiled as two ops - a constant string and a dereference (rv2gv) -
383 so that the glob is created at runtime.
384 If you're working with globs at runtime, and need to disambiguate
386 *^G from *{"^G"}, then you should use the raw NAME method.
387 STASH
389 SV
390 IO
391 FORM
392 AV
393 HV
394 EGV
395 CV
396 CVGEN
397 LINE
398 FILE
399 FILEGV
400 GvREFCNT
401 FLAGS
402 GPFLAGS
403 This last one is present only in perl 5.22.0 and higher.
404 B::IO Methods
406 B::IO objects derive from IO objects and you will get more information
407 from the IO object itself.
408 For example:
410 $gvio = B::svref_2object(\*main::stdin)->IO;
412 $IO = $gvio->object_2svref();
413 $fd = $IO->fileno();
414 LINES
416 PAGE
417 PAGE_LEN
418 LINES_LEFT
419 TOP_NAME
420 TOP_GV
421 FMT_NAME
422 FMT_GV
423 BOTTOM_NAME
424 BOTTOM_GV
425 SUBPROCESS
426 IoTYPE
427 A character symbolizing the type of IO Handle.
428 - STDIN/OUT
430 I STDIN/OUT/ERR
431 < read-only
432 > write-only
433 a append
434 + read and write
435 s socket
436 | pipe
437 I IMPLICIT
438 # NUMERIC
439 space closed handle
440 \0 closed internal handle
441 IoFLAGS
443 IsSTD
444 Takes one argument ( 'stdin' | 'stdout' | 'stderr' ) and returns
445 true if the IoIFP of the object is equal to the handle whose name
446 was passed as argument; i.e., $io->IsSTD('stderr') is true if
447 IoIFP($io) == PerlIO_stderr().
448 B::AV Methods
450 FILL
451 MAX
452 ARRAY
453 ARRAYelt
454 Like "ARRAY", but takes an index as an argument to get only one
455 element, rather than a list of all of them.
456 B::CV Methods
458 STASH
459 START
460 ROOT
461 GV
462 FILE
463 DEPTH
464 PADLIST
465 Returns a B::PADLIST object.
466 OUTSIDE
468 OUTSIDE_SEQ
469 XSUB
470 XSUBANY
471 For constant subroutines, returns the constant SV returned by the
472 subroutine.
473 CvFLAGS
475 const_sv
476 NAME_HEK
477 Returns the name of a lexical sub, otherwise "undef".
478 B::HV Methods
480 FILL
481 MAX
482 KEYS
483 RITER
484 NAME
485 ARRAY
486 OP-RELATED CLASSES
488 "B::OP", "B::UNOP", "B::UNOP_AUX", "B::BINOP", "B::LOGOP", "B::LISTOP",
489 "B::PMOP", "B::SVOP", "B::PADOP", "B::PVOP", "B::LOOP", "B::COP",
490 "B::METHOP".
491 These classes correspond in the obvious way to the underlying C
493 structures of similar names. The inheritance hierarchy mimics the
494 underlying C "inheritance":
495 B::OP
497 |
498 +----------+---------+--------+-------+---------+
499 | | | | | |
500 B::UNOP B::SVOP B::PADOP B::COP B::PVOP B::METHOP
501 |
502 +---+---+---------+
503 | | |
504 B::BINOP B::LOGOP B::UNOP_AUX
505 |
506 |
507 B::LISTOP
508 |
509 +---+---+
510 | |
511 B::LOOP B::PMOP
512 Access methods correspond to the underlying C structure field names,
514 with the leading "class indication" prefix ("op_") removed.
515 B::OP Methods
517 These methods get the values of similarly named fields within the OP
518 data structure. See top of "op.h" for more info.
519 next
521 sibling
522 parent
523 Returns the OP's parent. If it has no parent, or if your perl
524 wasn't built with "-DPERL_OP_PARENT", returns NULL.
525 Note that the global variable $B::OP::does_parent is undefined on
527 older perls that don't support the "parent" method, is defined but
528 false on perls that support the method but were built without
529 "-DPERL_OP_PARENT", and is true otherwise.
530 name
532 This returns the op name as a string (e.g. "add", "rv2av").
533 ppaddr
535 This returns the function name as a string (e.g.
536 "PL_ppaddr[OP_ADD]", "PL_ppaddr[OP_RV2AV]").
537 desc
539 This returns the op description from the global C PL_op_desc array
540 (e.g. "addition" "array deref").
541 targ
543 type
544 opt
545 flags
546 private
547 spare
548 B::UNOP Method
550 first
551 B::UNOP_AUX Methods (since 5.22)
553 aux_list(cv)
554 This returns a list of the elements of the op's aux data structure,
555 or a null list if there is no aux. What will be returned depends on
556 the object's type, but will typically be a collection of "B::IV",
557 "B::GV", etc. objects. "cv" is the "B::CV" object representing the
558 sub that the op is contained within.
559 string(cv)
561 This returns a textual representation of the object (likely to b
562 useful for deparsing and debugging), or an empty string if the op
563 type doesn't support this. "cv" is the "B::CV" object representing
564 the sub that the op is contained within.
565 B::BINOP Method
567 last
568 B::LOGOP Method
570 other
571 B::LISTOP Method
573 children
574 B::PMOP Methods
576 pmreplroot
577 pmreplstart
578 pmflags
579 precomp
580 pmoffset
581 Only when perl was compiled with ithreads.
582 code_list
584 Since perl 5.17.1
585 pmregexp
587 Added in perl 5.22, this method returns the B::REGEXP associated
588 with the op. While PMOPs do not actually have "pmregexp" fields
589 under threaded builds, this method returns the regexp under threads
590 nonetheless, for convenience.
591 B::SVOP Methods
593 sv
594 gv
595 B::PADOP Method
597 padix
598 B::PVOP Method
600 pv
601 B::LOOP Methods
603 redoop
604 nextop
605 lastop
606 B::COP Methods
608 The "B::COP" class is used for "nextstate" and "dbstate" ops. As of
609 Perl 5.22, it is also used for "null" ops that started out as COPs.
610 label
612 stash
613 stashpv
614 stashoff (threaded only)
615 file
616 cop_seq
617 line
618 warnings
619 io
620 hints
621 hints_hash
622 B::METHOP Methods (Since Perl 5.22)
624 first
625 meth_sv
626 PAD-RELATED CLASSES
628 Perl 5.18 introduced a new class, B::PADLIST, returned by B::CV's
629 "PADLIST" method.
630 Perl 5.22 introduced the B::PADNAMELIST and B::PADNAME classes.
632 B::PADLIST Methods
634 MAX
635 ARRAY
636 A list of pads. The first one is a B::PADNAMELIST containing the
637 names. The rest are currently B::AV objects, but that could change
638 in future versions.
639 ARRAYelt
641 Like "ARRAY", but takes an index as an argument to get only one
642 element, rather than a list of all of them.
643 NAMES
645 This method, introduced in 5.22, returns the B::PADNAMELIST. It is
646 equivalent to "ARRAYelt" with a 0 argument.
647 REFCNT
649 id This method, introduced in 5.22, returns an ID shared by clones of
650 the same padlist.
651 outid
653 This method, also added in 5.22, returns the ID of the outer
654 padlist.
655 B::PADNAMELIST Methods
657 MAX
658 ARRAY
659 ARRAYelt
660 These two methods return the pad names, using B::SPECIAL objects
661 for null pointers and B::PADNAME objects otherwise.
662 REFCNT
664 B::PADNAME Methods
666 PV
667 PVX
668 LEN
669 REFCNT
670 FLAGS
671 For backward-compatibility, if the PADNAMEt_OUTER flag is set, the
672 FLAGS method adds the SVf_FAKE flag, too.
673 TYPE
675 A B::HV object representing the stash for a typed lexical.
676 SvSTASH
678 A backward-compatibility alias for TYPE.
679 OURSTASH
681 A B::HV object representing the stash for 'our' variables.
682 PROTOCV
684 The prototype CV for a 'my' sub.
685 COP_SEQ_RANGE_LOW
687 COP_SEQ_RANGE_HIGH
688 Sequence numbers representing the scope within which a lexical is
689 visible. Meaningless if PADNAMEt_OUTER is set.
690 PARENT_PAD_INDEX
692 Only meaningful if PADNAMEt_OUTER is set.
693 PARENT_FAKELEX_FLAGS
695 Only meaningful if PADNAMEt_OUTER is set.
696 $B::overlay
698 Although the optree is read-only, there is an overlay facility that
699 allows you to override what values the various B::*OP methods return
700 for a particular op. $B::overlay should be set to reference a two-deep
701 hash: indexed by OP address, then method name. Whenever a an op method
702 is called, the value in the hash is returned if it exists. This
703 facility is used by B::Deparse to "undo" some optimisations. For
704 example:
705 local $B::overlay = {};
707 ...
708 if ($op->name eq "foo") {
709 $B::overlay->{$$op} = {
710 name => 'bar',
711 next => $op->next->next,
712 };
713 }
714 ...
715 $op->name # returns "bar"
716 $op->next # returns the next op but one
717
719 Malcolm Beattie, "mbeattie@sable.ox.ac.uk"
720perl v5.34.0 2021-10-18 B(3pm)