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::RV, B::PV, B::PVIV, B::PVNV, B::PVMG, B::BM (5.9.5 and
214 earlier), B::PVLV, B::AV, B::HV, B::CV, B::GV, B::FM, B::IO. These
215 classes correspond in the obvious way to the underlying C structures of
216 similar names. The inheritance hierarchy mimics the underlying C
217 "inheritance". For the 5.10.x branch, (ie 5.10.0, 5.10.1 etc) this is:
218 B::SV
220 |
221 +------------+------------+------------+
222 | | | |
223 B::PV B::IV B::NV B::RV
224 \ / /
225 \ / /
226 B::PVIV /
227 \ /
228 \ /
229 \ /
230 B::PVNV
231 |
232 |
233 B::PVMG
234 |
235 +-----+-----+-----+-----+
236 | | | | |
237 B::AV B::GV B::HV B::CV B::IO
238 | |
239 | |
240 B::PVLV B::FM
241 For 5.9.0 and earlier, PVLV is a direct subclass of PVMG, and BM is
243 still present as a distinct type, so the base of this diagram is
244 |
246 |
247 B::PVMG
248 |
249 +------+-----+-----+-----+-----+-----+
250 | | | | | | |
251 B::PVLV B::BM B::AV B::GV B::HV B::CV B::IO
252 |
253 |
254 B::FM
255 For 5.11.0 and later, B::RV is abolished, and IVs can be used to store
257 references, and a new type B::REGEXP is introduced, giving this
258 structure:
259 B::SV
261 |
262 +------------+------------+
263 | | |
264 B::PV B::IV B::NV
265 \ / /
266 \ / /
267 B::PVIV /
268 \ /
269 \ /
270 \ /
271 B::PVNV
272 |
273 |
274 B::PVMG
275 |
276 +-------+-------+---+---+-------+-------+
277 | | | | | |
278 B::AV B::GV B::HV B::CV B::IO B::REGEXP
279 | |
280 | |
281 B::PVLV B::FM
282 Access methods correspond to the underlying C macros for field access,
284 usually with the leading "class indication" prefix removed (Sv, Av, Hv,
285 ...). The leading prefix is only left in cases where its removal would
286 cause a clash in method name. For example, "GvREFCNT" stays as-is
287 since its abbreviation would clash with the "superclass" method
288 "REFCNT" (corresponding to the C function "SvREFCNT").
289 B::SV Methods
291 REFCNT
292 FLAGS
293 object_2svref
294 Returns a reference to the regular scalar corresponding to this
295 B::SV object. In other words, this method is the inverse operation
296 to the svref_2object() subroutine. This scalar and other data it
297 points at should be considered read-only: modifying them is neither
298 safe nor guaranteed to have a sensible effect.
299 B::IV Methods
301 IV Returns the value of the IV, interpreted as a signed integer. This
302 will be misleading if "FLAGS & SVf_IVisUV". Perhaps you want the
303 "int_value" method instead?
304 IVX
306 UVX
307 int_value
308 This method returns the value of the IV as an integer. It differs
309 from "IV" in that it returns the correct value regardless of
310 whether it's stored signed or unsigned.
311 needs64bits
313 packiv
314 B::NV Methods
316 NV
317 NVX
318 COP_SEQ_RANGE_LOW
319 COP_SEQ_RANGE_HIGH
320 These last two are only valid for pad name SVs. They only existed
321 in the B::NV class before Perl 5.22. In 5.22 they were moved to
322 the B::PADNAME class.
323 B::RV Methods
325 RV
326 B::PV Methods
328 PV This method is the one you usually want. It constructs a string
329 using the length and offset information in the struct: for ordinary
330 scalars it will return the string that you'd see from Perl, even if
331 it contains null characters.
332 RV Same as B::RV::RV, except that it will die() if the PV isn't a
334 reference.
335 PVX This method is less often useful. It assumes that the string
337 stored in the struct is null-terminated, and disregards the length
338 information.
339 It is the appropriate method to use if you need to get the name of
341 a lexical variable from a padname array. Lexical variable names
342 are always stored with a null terminator, and the length field
343 (CUR) is overloaded for other purposes and can't be relied on here.
344 CUR This method returns the internal length field, which consists of
346 the number of internal bytes, not necessarily the number of logical
347 characters.
348 LEN This method returns the number of bytes allocated (via malloc) for
350 storing the string. This is 0 if the scalar does not "own" the
351 string.
352 B::PVMG Methods
354 MAGIC
355 SvSTASH
356 B::MAGIC Methods
358 MOREMAGIC
359 precomp
360 Only valid on r-magic, returns the string that generated the
361 regexp.
362 PRIVATE
364 TYPE
365 FLAGS
366 OBJ Will die() if called on r-magic.
367 PTR
369 REGEX
370 Only valid on r-magic, returns the integer value of the REGEX
371 stored in the MAGIC.
372 B::PVLV Methods
374 TARGOFF
375 TARGLEN
376 TYPE
377 TARG
378 B::BM Methods
380 USEFUL
381 PREVIOUS
382 RARE
383 TABLE
384 B::REGEXP Methods
386 REGEX
387 precomp
388 qr_anoncv
389 compflags
390 The last two were added in Perl 5.22.
391 B::GV Methods
393 is_empty
394 This method returns TRUE if the GP field of the GV is NULL.
395 NAME
397 SAFENAME
398 This method returns the name of the glob, but if the first
399 character of the name is a control character, then it converts it
400 to ^X first, so that *^G would return "^G" rather than "\cG".
401 It's useful if you want to print out the name of a variable. If
403 you restrict yourself to globs which exist at compile-time then the
404 result ought to be unambiguous, because code like "${"^G"} = 1" is
405 compiled as two ops - a constant string and a dereference (rv2gv) -
406 so that the glob is created at runtime.
407 If you're working with globs at runtime, and need to disambiguate
409 *^G from *{"^G"}, then you should use the raw NAME method.
410 STASH
412 SV
413 IO
414 FORM
415 AV
416 HV
417 EGV
418 CV
419 CVGEN
420 LINE
421 FILE
422 FILEGV
423 GvREFCNT
424 FLAGS
425 GPFLAGS
426 This last one is present only in perl 5.22.0 and higher.
427 B::IO Methods
429 B::IO objects derive from IO objects and you will get more information
430 from the IO object itself.
431 For example:
433 $gvio = B::svref_2object(\*main::stdin)->IO;
435 $IO = $gvio->object_2svref();
436 $fd = $IO->fileno();
437 LINES
439 PAGE
440 PAGE_LEN
441 LINES_LEFT
442 TOP_NAME
443 TOP_GV
444 FMT_NAME
445 FMT_GV
446 BOTTOM_NAME
447 BOTTOM_GV
448 SUBPROCESS
449 IoTYPE
450 A character symbolizing the type of IO Handle.
451 - STDIN/OUT
453 I STDIN/OUT/ERR
454 < read-only
455 > write-only
456 a append
457 + read and write
458 s socket
459 | pipe
460 I IMPLICIT
461 # NUMERIC
462 space closed handle
463 \0 closed internal handle
464 IoFLAGS
466 IsSTD
467 Takes one argument ( 'stdin' | 'stdout' | 'stderr' ) and returns
468 true if the IoIFP of the object is equal to the handle whose name
469 was passed as argument; i.e., $io->IsSTD('stderr') is true if
470 IoIFP($io) == PerlIO_stderr().
471 B::AV Methods
473 FILL
474 MAX
475 ARRAY
476 ARRAYelt
477 Like "ARRAY", but takes an index as an argument to get only one
478 element, rather than a list of all of them.
479 OFF This method is deprecated if running under Perl 5.8, and is no
481 longer present if running under Perl 5.9
482 AvFLAGS
484 This method returns the AV specific flags. In Perl 5.9 these are
485 now stored in with the main SV flags, so this method is no longer
486 present.
487 B::CV Methods
489 STASH
490 START
491 ROOT
492 GV
493 FILE
494 DEPTH
495 PADLIST
496 Returns a B::PADLIST object under Perl 5.18 or higher, or a B::AV
497 in earlier versions.
498 OUTSIDE
500 OUTSIDE_SEQ
501 XSUB
502 XSUBANY
503 For constant subroutines, returns the constant SV returned by the
504 subroutine.
505 CvFLAGS
507 const_sv
508 NAME_HEK
509 Returns the name of a lexical sub, otherwise "undef".
510 B::HV Methods
512 FILL
513 MAX
514 KEYS
515 RITER
516 NAME
517 ARRAY
518 PMROOT
519 This method is not present if running under Perl 5.9, as the PMROOT
520 information is no longer stored directly in the hash.
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 pmnext
614 Only up to Perl 5.9.4
615 pmflags
617 extflags
618 Since Perl 5.9.5
619 precomp
621 pmoffset
622 Only when perl was compiled with ithreads.
623 code_list
625 Since perl 5.17.1
626 pmregexp
628 Added in perl 5.22, this method returns the B::REGEXP associated
629 with the op. While PMOPs do not actually have "pmregexp" fields
630 under threaded builds, this method returns the regexp under threads
631 nonetheless, for convenience.
632 B::SVOP Methods
634 sv
635 gv
636 B::PADOP Method
638 padix
639 B::PVOP Method
641 pv
642 B::LOOP Methods
644 redoop
645 nextop
646 lastop
647 B::COP Methods
649 The "B::COP" class is used for "nextstate" and "dbstate" ops. As of
650 Perl 5.22, it is also used for "null" ops that started out as COPs.
651 label
653 stash
654 stashpv
655 stashoff (threaded only)
656 file
657 cop_seq
658 arybase
659 line
660 warnings
661 io
662 hints
663 hints_hash
664 B::METHOP Methods (Since Perl 5.22)
666 first
667 meth_sv
668 PAD-RELATED CLASSES
670 Perl 5.18 introduced a new class, B::PADLIST, returned by B::CV's
671 "PADLIST" method.
672 Perl 5.22 introduced the B::PADNAMELIST and B::PADNAME classes.
674 B::PADLIST Methods
676 MAX
677 ARRAY
678 A list of pads. The first one contains the names.
679 The first one is a B::PADNAMELIST under Perl 5.22, and a B::AV
681 under earlier versions. The rest are currently B::AV objects, but
682 that could change in future versions.
683 ARRAYelt
685 Like "ARRAY", but takes an index as an argument to get only one
686 element, rather than a list of all of them.
687 NAMES
689 This method, introduced in 5.22, returns the B::PADNAMELIST. It is
690 equivalent to "ARRAYelt" with a 0 argument.
691 REFCNT
693 id This method, introduced in 5.22, returns an ID shared by clones of
694 the same padlist.
695 outid
697 This method, also added in 5.22, returns the ID of the outer
698 padlist.
699 B::PADNAMELIST Methods
701 MAX
702 ARRAY
703 ARRAYelt
704 These two methods return the pad names, using B::SPECIAL objects
705 for null pointers and B::PADNAME objects otherwise.
706 REFCNT
708 B::PADNAME Methods
710 PV
711 PVX
712 LEN
713 REFCNT
714 FLAGS
715 For backward-compatibility, if the PADNAMEt_OUTER flag is set, the
716 FLAGS method adds the SVf_FAKE flag, too.
717 TYPE
719 A B::HV object representing the stash for a typed lexical.
720 SvSTASH
722 A backward-compatibility alias for TYPE.
723 OURSTASH
725 A B::HV object representing the stash for 'our' variables.
726 PROTOCV
728 The prototype CV for a 'my' sub.
729 COP_SEQ_RANGE_LOW
731 COP_SEQ_RANGE_HIGH
732 Sequence numbers representing the scope within which a lexical is
733 visible. Meaningless if PADNAMEt_OUTER is set.
734 PARENT_PAD_INDEX
736 Only meaningful if PADNAMEt_OUTER is set.
737 PARENT_FAKELEX_FLAGS
739 Only meaningful if PADNAMEt_OUTER is set.
740 $B::overlay
742 Although the optree is read-only, there is an overlay facility that
743 allows you to override what values the various B::*OP methods return
744 for a particular op. $B::overlay should be set to reference a two-deep
745 hash: indexed by OP address, then method name. Whenever a an op method
746 is called, the value in the hash is returned if it exists. This
747 facility is used by B::Deparse to "undo" some optimisations. For
748 example:
749 local $B::overlay = {};
751 ...
752 if ($op->name eq "foo") {
753 $B::overlay->{$$op} = {
754 name => 'bar',
755 next => $op->next->next,
756 };
757 }
758 ...
759 $op->name # returns "bar"
760 $op->next # returns the next op but one
761
763 Malcolm Beattie, "mbeattie@sable.ox.ac.uk"
764perl v5.26.3 2018-03-23 B(3pm)