1B(3pm)                 Perl Programmers Reference Guide                 B(3pm)
2
3
4

NAME

6       B - The Perl Compiler Backend
7

SYNOPSIS

9               use B;
10

DESCRIPTION

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

OVERVIEW

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

Utility Functions

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
33   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
38       sv_undef
39           Returns the SV object corresponding to the C variable "sv_undef".
40
41       sv_yes
42           Returns the SV object corresponding to the C variable "sv_yes".
43
44       sv_no
45           Returns the SV object corresponding to the C variable "sv_no".
46
47       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
55           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
59       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
64       init_av
65           Returns the AV object (i.e. in class B::AV) representing INIT
66           blocks.
67
68       check_av
69           Returns the AV object (i.e. in class B::AV) representing CHECK
70           blocks.
71
72       unitcheck_av
73           Returns the AV object (i.e. in class B::AV) representing UNITCHECK
74           blocks.
75
76       begin_av
77           Returns the AV object (i.e. in class B::AV) representing BEGIN
78           blocks.
79
80       end_av
81           Returns the AV object (i.e. in class B::AV) representing END
82           blocks.
83
84       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
89       regex_padav
90           Only when perl was compiled with ithreads.
91
92       main_cv
93           Return the (faked) CV corresponding to the main part of the Perl
94           program.
95
96   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
103           PREFIX is the name of the SYMREF you're walking.
104
105           For example:
106
107             # 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
112           print_subs() is a B::GV method you have declared.  Also see "B::GV
113           Methods", below.
114
115   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
120       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
124       main_start
125           Returns the starting op of the main part of the Perl program.
126
127       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
134       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
140   Miscellaneous Utility Functions
141       ppname(OPNUM)
142           Return the PP function name (e.g. "pp_add") of op number OPNUM.
143
144       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
148       cast_I32(I)
149           Casts I to the internal I32 type used by that perl.
150
151       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
156       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
160       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
164       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
170       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
175       threadsv_names
176           This used to provide support for the old 5.005 threading module. It
177           now does nothing.
178
179   Exported utility variables
180       @optype
181             my $op_type = $optype[$op_type_num];
182
183           A simple mapping of the op type number to its type (like 'COP' or
184           'BINOP').
185
186       @specialsv_name
187             my $sv_name = $specialsv_name[$sv_index];
188
189           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

OVERVIEW OF CLASSES

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
202       The bulk of the "B" module is the methods for accessing fields of these
203       structures.
204
205       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
212   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
218                                  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
241       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
248   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
258   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
263       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
270       needs64bits
271       packiv
272
273   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
282   B::RV Methods
283       RV
284
285   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
291       RV  Same as B::RV::RV, except that it will die() if the PV isn't a
292           reference.
293
294       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
298           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
303       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
307       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
311   B::PVMG Methods
312       MAGIC
313       SvSTASH
314
315   B::MAGIC Methods
316       MOREMAGIC
317       precomp
318           Only valid on r-magic, returns the string that generated the
319           regexp.
320
321       PRIVATE
322       TYPE
323       FLAGS
324       OBJ Will die() if called on r-magic.
325
326       PTR
327       REGEX
328           Only valid on r-magic, returns the integer value of the REGEX
329           stored in the MAGIC.
330
331   B::INVLIST Methods
332       prev_index
333           Returns the cache result of previous invlist_search() (internal
334           usage)
335
336       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
341       array_len
342           Returns an integer with the size of the array used to define the
343           invlist.
344
345       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
350   B::PVLV Methods
351       TARGOFF
352       TARGLEN
353       TYPE
354       TARG
355
356   B::BM Methods
357       USEFUL
358       PREVIOUS
359       RARE
360       TABLE
361
362   B::REGEXP Methods
363       REGEX
364       precomp
365       qr_anoncv
366       compflags
367           The last two were added in Perl 5.22.
368
369   B::GV Methods
370       is_empty
371           This method returns TRUE if the GP field of the GV is NULL.
372
373       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
379           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
385           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
388       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
405   B::IO Methods
406       B::IO objects derive from IO objects and you will get more information
407       from the IO object itself.
408
409       For example:
410
411         $gvio = B::svref_2object(\*main::stdin)->IO;
412         $IO = $gvio->object_2svref();
413         $fd = $IO->fileno();
414
415       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
429             -     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
442       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
449   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
457   B::CV Methods
458       STASH
459       START
460       ROOT
461       GV
462       FILE
463       DEPTH
464       PADLIST
465           Returns a B::PADLIST object.
466
467       OUTSIDE
468       OUTSIDE_SEQ
469       XSUB
470       XSUBANY
471           For constant subroutines, returns the constant SV returned by the
472           subroutine.
473
474       CvFLAGS
475       const_sv
476       NAME_HEK
477           Returns the name of a lexical sub, otherwise "undef".
478
479   B::HV Methods
480       FILL
481       MAX
482       KEYS
483       RITER
484       NAME
485       ARRAY
486
487   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
492       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
496                                        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
513       Access methods correspond to the underlying C structure field names,
514       with the leading "class indication" prefix ("op_") removed.
515
516   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
520       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
526           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
531       name
532           This returns the op name as a string (e.g. "add", "rv2av").
533
534       ppaddr
535           This returns the function name as a string (e.g.
536           "PL_ppaddr[OP_ADD]", "PL_ppaddr[OP_RV2AV]").
537
538       desc
539           This returns the op description from the global C PL_op_desc array
540           (e.g. "addition" "array deref").
541
542       targ
543       type
544       opt
545       flags
546       private
547       spare
548
549   B::UNOP Method
550       first
551
552   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
560       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
566   B::BINOP Method
567       last
568
569   B::LOGOP Method
570       other
571
572   B::LISTOP Method
573       children
574
575   B::PMOP Methods
576       pmreplroot
577       pmreplstart
578       pmflags
579       precomp
580       pmoffset
581           Only when perl was compiled with ithreads.
582
583       code_list
584           Since perl 5.17.1
585
586       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
592   B::SVOP Methods
593       sv
594       gv
595
596   B::PADOP Method
597       padix
598
599   B::PVOP Method
600       pv
601
602   B::LOOP Methods
603       redoop
604       nextop
605       lastop
606
607   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
611       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
623   B::METHOP Methods (Since Perl 5.22)
624       first
625       meth_sv
626
627   PAD-RELATED CLASSES
628       Perl 5.18 introduced a new class, B::PADLIST, returned by B::CV's
629       "PADLIST" method.
630
631       Perl 5.22 introduced the B::PADNAMELIST and B::PADNAME classes.
632
633   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
640       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
644       NAMES
645           This method, introduced in 5.22, returns the B::PADNAMELIST.  It is
646           equivalent to "ARRAYelt" with a 0 argument.
647
648       REFCNT
649       id  This method, introduced in 5.22, returns an ID shared by clones of
650           the same padlist.
651
652       outid
653           This method, also added in 5.22, returns the ID of the outer
654           padlist.
655
656   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
663       REFCNT
664
665   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
674       TYPE
675           A B::HV object representing the stash for a typed lexical.
676
677       SvSTASH
678           A backward-compatibility alias for TYPE.
679
680       OURSTASH
681           A B::HV object representing the stash for 'our' variables.
682
683       PROTOCV
684           The prototype CV for a 'my' sub.
685
686       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
691       PARENT_PAD_INDEX
692           Only meaningful if PADNAMEt_OUTER is set.
693
694       PARENT_FAKELEX_FLAGS
695           Only meaningful if PADNAMEt_OUTER is set.
696
697   $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
706           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

AUTHOR

719       Malcolm Beattie, "mbeattie@sable.ox.ac.uk"
720
721
722
723perl v5.34.0                      2021-10-18                            B(3pm)
Impressum