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 IsBOOL
252 Returns true if the SV is a boolean (true or false). You can then
253 use "TRUE" to check if the value is true or false.
254 my $something = ( 1 == 1 ) # boolean true
256 || ( 1 == 0 ) # boolean false
257 || 42 # IV true
258 || 0; # IV false
259 my $sv = B::svref_2object(\$something);
260 say q[Not a boolean value]
262 if ! $sv->IsBOOL;
263 say q[This is a boolean with value: true]
265 if $sv->IsBOOL && $sv->TRUE_nomg;
266 say q[This is a boolean with value: false]
268 if $sv->IsBOOL && ! $sv->TRUE_nomg;
269 object_2svref
271 Returns a reference to the regular scalar corresponding to this
272 B::SV object. In other words, this method is the inverse operation
273 to the svref_2object() subroutine. This scalar and other data it
274 points at should be considered read-only: modifying them is neither
275 safe nor guaranteed to have a sensible effect.
276 TRUE
278 Returns a boolean indicating hether Perl would evaluate the SV as
279 true or false.
280 Warning this call performs 'get' magic. If you only want to check
282 the nature of this SV use "TRUE_nomg" helper.
283 This is an alias for SvTRUE($sv).
285 TRUE_nomg
287 Check if the value is true (do not perform 'get' magic). Returns a
288 boolean indicating whether Perl would evaluate the SV as true or
289 false.
290 This is an alias for SvTRUE_nomg($sv).
292 B::IV Methods
294 IV Returns the value of the IV, interpreted as a signed integer. This
295 will be misleading if "FLAGS & SVf_IVisUV". Perhaps you want the
296 "int_value" method instead?
297 IVX
299 UVX
300 int_value
301 This method returns the value of the IV as an integer. It differs
302 from "IV" in that it returns the correct value regardless of
303 whether it's stored signed or unsigned.
304 needs64bits
306 packiv
307 B::NV Methods
309 NV
310 NVX
311 COP_SEQ_RANGE_LOW
312 COP_SEQ_RANGE_HIGH
313 These last two are only valid for pad name SVs. They only existed
314 in the B::NV class before Perl 5.22. In 5.22 they were moved to
315 the B::PADNAME class.
316 B::RV Methods
318 RV
319 B::PV Methods
321 PV This method is the one you usually want. It constructs a string
322 using the length and offset information in the struct: for ordinary
323 scalars it will return the string that you'd see from Perl, even if
324 it contains null characters.
325 RV Same as B::RV::RV, except that it will die() if the PV isn't a
327 reference.
328 PVX This method is less often useful. It assumes that the string
330 stored in the struct is null-terminated, and disregards the length
331 information.
332 It is the appropriate method to use if you need to get the name of
334 a lexical variable from a padname array. Lexical variable names
335 are always stored with a null terminator, and the length field
336 (CUR) is overloaded for other purposes and can't be relied on here.
337 CUR This method returns the internal length field, which consists of
339 the number of internal bytes, not necessarily the number of logical
340 characters.
341 LEN This method returns the number of bytes allocated (via malloc) for
343 storing the string. This is 0 if the scalar does not "own" the
344 string.
345 B::PVMG Methods
347 MAGIC
348 SvSTASH
349 B::MAGIC Methods
351 MOREMAGIC
352 precomp
353 Only valid on r-magic, returns the string that generated the
354 regexp.
355 PRIVATE
357 TYPE
358 FLAGS
359 OBJ Will die() if called on r-magic.
360 PTR
362 REGEX
363 Only valid on r-magic, returns the integer value of the REGEX
364 stored in the MAGIC.
365 B::INVLIST Methods
367 prev_index
368 Returns the cache result of previous invlist_search() (internal
369 usage)
370 is_offset
372 Returns a boolean value (0 or 1) to know if the invlist is using an
373 offset. When false the list begins with the code point U+0000.
374 When true the list begins with the following elements.
375 array_len
377 Returns an integer with the size of the array used to define the
378 invlist.
379 get_invlist_array
381 This method returns a list of integers representing the array used
382 by the invlist. Note: this cannot be used while in middle of
383 iterating on an invlist and croaks.
384 B::PVLV Methods
386 TARGOFF
387 TARGLEN
388 TYPE
389 TARG
390 B::BM Methods
392 USEFUL
393 PREVIOUS
394 RARE
395 TABLE
396 B::REGEXP Methods
398 REGEX
399 precomp
400 qr_anoncv
401 compflags
402 The last two were added in Perl 5.22.
403 B::GV Methods
405 is_empty
406 This method returns TRUE if the GP field of the GV is NULL.
407 NAME
409 SAFENAME
410 This method returns the name of the glob, but if the first
411 character of the name is a control character, then it converts it
412 to ^X first, so that *^G would return "^G" rather than "\cG".
413 It's useful if you want to print out the name of a variable. If
415 you restrict yourself to globs which exist at compile-time then the
416 result ought to be unambiguous, because code like "${"^G"} = 1" is
417 compiled as two ops - a constant string and a dereference (rv2gv) -
418 so that the glob is created at runtime.
419 If you're working with globs at runtime, and need to disambiguate
421 *^G from *{"^G"}, then you should use the raw NAME method.
422 STASH
424 SV
425 IO
426 FORM
427 AV
428 HV
429 EGV
430 CV
431 CVGEN
432 LINE
433 FILE
434 FILEGV
435 GvREFCNT
436 FLAGS
437 GPFLAGS
438 This last one is present only in perl 5.22.0 and higher.
439 B::IO Methods
441 B::IO objects derive from IO objects and you will get more information
442 from the IO object itself.
443 For example:
445 $gvio = B::svref_2object(\*main::stdin)->IO;
447 $IO = $gvio->object_2svref();
448 $fd = $IO->fileno();
449 LINES
451 PAGE
452 PAGE_LEN
453 LINES_LEFT
454 TOP_NAME
455 TOP_GV
456 FMT_NAME
457 FMT_GV
458 BOTTOM_NAME
459 BOTTOM_GV
460 SUBPROCESS
461 IoTYPE
462 A character symbolizing the type of IO Handle.
463 - STDIN/OUT
465 I STDIN/OUT/ERR
466 < read-only
467 > write-only
468 a append
469 + read and write
470 s socket
471 | pipe
472 I IMPLICIT
473 # NUMERIC
474 space closed handle
475 \0 closed internal handle
476 IoFLAGS
478 IsSTD
479 Takes one argument ( 'stdin' | 'stdout' | 'stderr' ) and returns
480 true if the IoIFP of the object is equal to the handle whose name
481 was passed as argument; i.e., $io->IsSTD('stderr') is true if
482 IoIFP($io) == PerlIO_stderr().
483 B::AV Methods
485 FILL
486 MAX
487 ARRAY
488 ARRAYelt
489 Like "ARRAY", but takes an index as an argument to get only one
490 element, rather than a list of all of them.
491 B::CV Methods
493 STASH
494 START
495 ROOT
496 GV
497 FILE
498 DEPTH
499 PADLIST
500 Returns a B::PADLIST object.
501 OUTSIDE
503 OUTSIDE_SEQ
504 XSUB
505 XSUBANY
506 For constant subroutines, returns the constant SV returned by the
507 subroutine.
508 CvFLAGS
510 const_sv
511 NAME_HEK
512 Returns the name of a lexical sub, otherwise "undef".
513 B::HV Methods
515 FILL
516 MAX
517 KEYS
518 RITER
519 NAME
520 ARRAY
521 OP-RELATED CLASSES
523 "B::OP", "B::UNOP", "B::UNOP_AUX", "B::BINOP", "B::LOGOP", "B::LISTOP",
524 "B::PMOP", "B::SVOP", "B::PADOP", "B::PVOP", "B::LOOP", "B::COP",
525 "B::METHOP".
526 These classes correspond in the obvious way to the underlying C
528 structures of similar names. The inheritance hierarchy mimics the
529 underlying C "inheritance":
530 B::OP
532 |
533 +----------+---------+--------+-------+---------+
534 | | | | | |
535 B::UNOP B::SVOP B::PADOP B::COP B::PVOP B::METHOP
536 |
537 +---+---+---------+
538 | | |
539 B::BINOP B::LOGOP B::UNOP_AUX
540 |
541 |
542 B::LISTOP
543 |
544 +---+---+
545 | |
546 B::LOOP B::PMOP
547 Access methods correspond to the underlying C structure field names,
549 with the leading "class indication" prefix ("op_") removed.
550 B::OP Methods
552 These methods get the values of similarly named fields within the OP
553 data structure. See top of "op.h" for more info.
554 next
556 sibling
557 parent
558 Returns the OP's parent. If it has no parent, or if your perl
559 wasn't built with "-DPERL_OP_PARENT", returns NULL.
560 Note that the global variable $B::OP::does_parent is undefined on
562 older perls that don't support the "parent" method, is defined but
563 false on perls that support the method but were built without
564 "-DPERL_OP_PARENT", and is true otherwise.
565 name
567 This returns the op name as a string (e.g. "add", "rv2av").
568 ppaddr
570 This returns the function name as a string (e.g.
571 "PL_ppaddr[OP_ADD]", "PL_ppaddr[OP_RV2AV]").
572 desc
574 This returns the op description from the global C PL_op_desc array
575 (e.g. "addition" "array deref").
576 targ
578 type
579 opt
580 flags
581 private
582 spare
583 B::UNOP Method
585 first
586 B::UNOP_AUX Methods (since 5.22)
588 aux_list(cv)
589 This returns a list of the elements of the op's aux data structure,
590 or a null list if there is no aux. What will be returned depends on
591 the object's type, but will typically be a collection of "B::IV",
592 "B::GV", etc. objects. "cv" is the "B::CV" object representing the
593 sub that the op is contained within.
594 string(cv)
596 This returns a textual representation of the object (likely to b
597 useful for deparsing and debugging), or an empty string if the op
598 type doesn't support this. "cv" is the "B::CV" object representing
599 the sub that the op is contained within.
600 B::BINOP Method
602 last
603 B::LOGOP Method
605 other
606 B::LISTOP Method
608 children
609 B::PMOP Methods
611 pmreplroot
612 pmreplstart
613 pmflags
614 precomp
615 pmoffset
616 Only when perl was compiled with ithreads.
617 code_list
619 Since perl 5.17.1
620 pmregexp
622 Added in perl 5.22, this method returns the B::REGEXP associated
623 with the op. While PMOPs do not actually have "pmregexp" fields
624 under threaded builds, this method returns the regexp under threads
625 nonetheless, for convenience.
626 B::SVOP Methods
628 sv
629 gv
630 B::PADOP Method
632 padix
633 B::PVOP Method
635 pv
636 B::LOOP Methods
638 redoop
639 nextop
640 lastop
641 B::COP Methods
643 The "B::COP" class is used for "nextstate" and "dbstate" ops. As of
644 Perl 5.22, it is also used for "null" ops that started out as COPs.
645 label
647 stash
648 stashpv
649 stashoff (threaded only)
650 file
651 cop_seq
652 line
653 warnings
654 io
655 hints
656 hints_hash
657 B::METHOP Methods (Since Perl 5.22)
659 first
660 meth_sv
661 PAD-RELATED CLASSES
663 Perl 5.18 introduced a new class, B::PADLIST, returned by B::CV's
664 "PADLIST" method.
665 Perl 5.22 introduced the B::PADNAMELIST and B::PADNAME classes.
667 B::PADLIST Methods
669 MAX
670 ARRAY
671 A list of pads. The first one is a B::PADNAMELIST containing the
672 names. The rest are currently B::AV objects, but that could change
673 in future versions.
674 ARRAYelt
676 Like "ARRAY", but takes an index as an argument to get only one
677 element, rather than a list of all of them.
678 NAMES
680 This method, introduced in 5.22, returns the B::PADNAMELIST. It is
681 equivalent to "ARRAYelt" with a 0 argument.
682 REFCNT
684 id This method, introduced in 5.22, returns an ID shared by clones of
685 the same padlist.
686 outid
688 This method, also added in 5.22, returns the ID of the outer
689 padlist.
690 B::PADNAMELIST Methods
692 MAX
693 ARRAY
694 ARRAYelt
695 These two methods return the pad names, using B::SPECIAL objects
696 for null pointers and B::PADNAME objects otherwise.
697 REFCNT
699 B::PADNAME Methods
701 PV
702 PVX
703 LEN
704 REFCNT
705 GEN
706 FLAGS
707 For backward-compatibility, if the PADNAMEt_OUTER flag is set, the
708 FLAGS method adds the SVf_FAKE flag, too.
709 TYPE
711 A B::HV object representing the stash for a typed lexical.
712 SvSTASH
714 A backward-compatibility alias for TYPE.
715 OURSTASH
717 A B::HV object representing the stash for 'our' variables.
718 PROTOCV
720 The prototype CV for a 'my' sub.
721 COP_SEQ_RANGE_LOW
723 COP_SEQ_RANGE_HIGH
724 Sequence numbers representing the scope within which a lexical is
725 visible. Meaningless if PADNAMEt_OUTER is set.
726 PARENT_PAD_INDEX
728 Only meaningful if PADNAMEt_OUTER is set.
729 PARENT_FAKELEX_FLAGS
731 Only meaningful if PADNAMEt_OUTER is set.
732 IsUndef
734 Returns a boolean value to check if the padname is
735 PL_padname_undef.
736 $B::overlay
738 Although the optree is read-only, there is an overlay facility that
739 allows you to override what values the various B::*OP methods return
740 for a particular op. $B::overlay should be set to reference a two-deep
741 hash: indexed by OP address, then method name. Whenever a an op method
742 is called, the value in the hash is returned if it exists. This
743 facility is used by B::Deparse to "undo" some optimisations. For
744 example:
745 local $B::overlay = {};
747 ...
748 if ($op->name eq "foo") {
749 $B::overlay->{$$op} = {
750 name => 'bar',
751 next => $op->next->next,
752 };
753 }
754 ...
755 $op->name # returns "bar"
756 $op->next # returns the next op but one
757
759 Malcolm Beattie, "mbeattie@sable.ox.ac.uk"
760perl v5.38.2 2023-11-30 B(3pm)