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::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::PVLV Methods
332       TARGOFF
333       TARGLEN
334       TYPE
335       TARG
336
337   B::BM Methods
338       USEFUL
339       PREVIOUS
340       RARE
341       TABLE
342
343   B::REGEXP Methods
344       REGEX
345       precomp
346       qr_anoncv
347       compflags
348           The last two were added in Perl 5.22.
349
350   B::GV Methods
351       is_empty
352           This method returns TRUE if the GP field of the GV is NULL.
353
354       NAME
355       SAFENAME
356           This method returns the name of the glob, but if the first
357           character of the name is a control character, then it converts it
358           to ^X first, so that *^G would return "^G" rather than "\cG".
359
360           It's useful if you want to print out the name of a variable.  If
361           you restrict yourself to globs which exist at compile-time then the
362           result ought to be unambiguous, because code like "${"^G"} = 1" is
363           compiled as two ops - a constant string and a dereference (rv2gv) -
364           so that the glob is created at runtime.
365
366           If you're working with globs at runtime, and need to disambiguate
367           *^G from *{"^G"}, then you should use the raw NAME method.
368
369       STASH
370       SV
371       IO
372       FORM
373       AV
374       HV
375       EGV
376       CV
377       CVGEN
378       LINE
379       FILE
380       FILEGV
381       GvREFCNT
382       FLAGS
383       GPFLAGS
384           This last one is present only in perl 5.22.0 and higher.
385
386   B::IO Methods
387       B::IO objects derive from IO objects and you will get more information
388       from the IO object itself.
389
390       For example:
391
392         $gvio = B::svref_2object(\*main::stdin)->IO;
393         $IO = $gvio->object_2svref();
394         $fd = $IO->fileno();
395
396       LINES
397       PAGE
398       PAGE_LEN
399       LINES_LEFT
400       TOP_NAME
401       TOP_GV
402       FMT_NAME
403       FMT_GV
404       BOTTOM_NAME
405       BOTTOM_GV
406       SUBPROCESS
407       IoTYPE
408           A character symbolizing the type of IO Handle.
409
410             -     STDIN/OUT
411             I     STDIN/OUT/ERR
412             <     read-only
413             >     write-only
414             a     append
415             +     read and write
416             s     socket
417             |     pipe
418             I     IMPLICIT
419             #     NUMERIC
420             space closed handle
421             \0    closed internal handle
422
423       IoFLAGS
424       IsSTD
425           Takes one argument ( 'stdin' | 'stdout' | 'stderr' ) and returns
426           true if the IoIFP of the object is equal to the handle whose name
427           was passed as argument; i.e., $io->IsSTD('stderr') is true if
428           IoIFP($io) == PerlIO_stderr().
429
430   B::AV Methods
431       FILL
432       MAX
433       ARRAY
434       ARRAYelt
435           Like "ARRAY", but takes an index as an argument to get only one
436           element, rather than a list of all of them.
437
438   B::CV Methods
439       STASH
440       START
441       ROOT
442       GV
443       FILE
444       DEPTH
445       PADLIST
446           Returns a B::PADLIST object.
447
448       OUTSIDE
449       OUTSIDE_SEQ
450       XSUB
451       XSUBANY
452           For constant subroutines, returns the constant SV returned by the
453           subroutine.
454
455       CvFLAGS
456       const_sv
457       NAME_HEK
458           Returns the name of a lexical sub, otherwise "undef".
459
460   B::HV Methods
461       FILL
462       MAX
463       KEYS
464       RITER
465       NAME
466       ARRAY
467
468   OP-RELATED CLASSES
469       "B::OP", "B::UNOP", "B::UNOP_AUX", "B::BINOP", "B::LOGOP", "B::LISTOP",
470       "B::PMOP", "B::SVOP", "B::PADOP", "B::PVOP", "B::LOOP", "B::COP",
471       "B::METHOP".
472
473       These classes correspond in the obvious way to the underlying C
474       structures of similar names.  The inheritance hierarchy mimics the
475       underlying C "inheritance":
476
477                                        B::OP
478                                          |
479                          +----------+---------+--------+-------+---------+
480                          |          |         |        |       |         |
481                       B::UNOP    B::SVOP  B::PADOP  B::COP  B::PVOP  B::METHOP
482                          |
483                      +---+---+---------+
484                      |       |         |
485                  B::BINOP  B::LOGOP  B::UNOP_AUX
486                      |
487                      |
488                  B::LISTOP
489                      |
490                  +---+---+
491                  |       |
492               B::LOOP   B::PMOP
493
494       Access methods correspond to the underlying C structure field names,
495       with the leading "class indication" prefix ("op_") removed.
496
497   B::OP Methods
498       These methods get the values of similarly named fields within the OP
499       data structure.  See top of "op.h" for more info.
500
501       next
502       sibling
503       parent
504           Returns the OP's parent. If it has no parent, or if your perl
505           wasn't built with "-DPERL_OP_PARENT", returns NULL.
506
507           Note that the global variable $B::OP::does_parent is undefined on
508           older perls that don't support the "parent" method, is defined but
509           false on perls that support the method but were built without
510           "-DPERL_OP_PARENT", and is true otherwise.
511
512       name
513           This returns the op name as a string (e.g. "add", "rv2av").
514
515       ppaddr
516           This returns the function name as a string (e.g.
517           "PL_ppaddr[OP_ADD]", "PL_ppaddr[OP_RV2AV]").
518
519       desc
520           This returns the op description from the global C PL_op_desc array
521           (e.g. "addition" "array deref").
522
523       targ
524       type
525       opt
526       flags
527       private
528       spare
529
530   B::UNOP Method
531       first
532
533   B::UNOP_AUX Methods (since 5.22)
534       aux_list(cv)
535           This returns a list of the elements of the op's aux data structure,
536           or a null list if there is no aux. What will be returned depends on
537           the object's type, but will typically be a collection of "B::IV",
538           "B::GV", etc. objects. "cv" is the "B::CV" object representing the
539           sub that the op is contained within.
540
541       string(cv)
542           This returns a textual representation of the object (likely to b
543           useful for deparsing and debugging), or an empty string if the op
544           type doesn't support this. "cv" is the "B::CV" object representing
545           the sub that the op is contained within.
546
547   B::BINOP Method
548       last
549
550   B::LOGOP Method
551       other
552
553   B::LISTOP Method
554       children
555
556   B::PMOP Methods
557       pmreplroot
558       pmreplstart
559       pmflags
560       precomp
561       pmoffset
562           Only when perl was compiled with ithreads.
563
564       code_list
565           Since perl 5.17.1
566
567       pmregexp
568           Added in perl 5.22, this method returns the B::REGEXP associated
569           with the op.  While PMOPs do not actually have "pmregexp" fields
570           under threaded builds, this method returns the regexp under threads
571           nonetheless, for convenience.
572
573   B::SVOP Methods
574       sv
575       gv
576
577   B::PADOP Method
578       padix
579
580   B::PVOP Method
581       pv
582
583   B::LOOP Methods
584       redoop
585       nextop
586       lastop
587
588   B::COP Methods
589       The "B::COP" class is used for "nextstate" and "dbstate" ops.  As of
590       Perl 5.22, it is also used for "null" ops that started out as COPs.
591
592       label
593       stash
594       stashpv
595       stashoff (threaded only)
596       file
597       cop_seq
598       arybase
599       line
600       warnings
601       io
602       hints
603       hints_hash
604
605   B::METHOP Methods (Since Perl 5.22)
606       first
607       meth_sv
608
609   PAD-RELATED CLASSES
610       Perl 5.18 introduced a new class, B::PADLIST, returned by B::CV's
611       "PADLIST" method.
612
613       Perl 5.22 introduced the B::PADNAMELIST and B::PADNAME classes.
614
615   B::PADLIST Methods
616       MAX
617       ARRAY
618           A list of pads.  The first one is a B::PADNAMELIST containing the
619           names.  The rest are currently B::AV objects, but that could change
620           in future versions.
621
622       ARRAYelt
623           Like "ARRAY", but takes an index as an argument to get only one
624           element, rather than a list of all of them.
625
626       NAMES
627           This method, introduced in 5.22, returns the B::PADNAMELIST.  It is
628           equivalent to "ARRAYelt" with a 0 argument.
629
630       REFCNT
631       id  This method, introduced in 5.22, returns an ID shared by clones of
632           the same padlist.
633
634       outid
635           This method, also added in 5.22, returns the ID of the outer
636           padlist.
637
638   B::PADNAMELIST Methods
639       MAX
640       ARRAY
641       ARRAYelt
642           These two methods return the pad names, using B::SPECIAL objects
643           for null pointers and B::PADNAME objects otherwise.
644
645       REFCNT
646
647   B::PADNAME Methods
648       PV
649       PVX
650       LEN
651       REFCNT
652       FLAGS
653           For backward-compatibility, if the PADNAMEt_OUTER flag is set, the
654           FLAGS method adds the SVf_FAKE flag, too.
655
656       TYPE
657           A B::HV object representing the stash for a typed lexical.
658
659       SvSTASH
660           A backward-compatibility alias for TYPE.
661
662       OURSTASH
663           A B::HV object representing the stash for 'our' variables.
664
665       PROTOCV
666           The prototype CV for a 'my' sub.
667
668       COP_SEQ_RANGE_LOW
669       COP_SEQ_RANGE_HIGH
670           Sequence numbers representing the scope within which a lexical is
671           visible.  Meaningless if PADNAMEt_OUTER is set.
672
673       PARENT_PAD_INDEX
674           Only meaningful if PADNAMEt_OUTER is set.
675
676       PARENT_FAKELEX_FLAGS
677           Only meaningful if PADNAMEt_OUTER is set.
678
679   $B::overlay
680       Although the optree is read-only, there is an overlay facility that
681       allows you to override what values the various B::*OP methods return
682       for a particular op. $B::overlay should be set to reference a two-deep
683       hash: indexed by OP address, then method name. Whenever a an op method
684       is called, the value in the hash is returned if it exists. This
685       facility is used by B::Deparse to "undo" some optimisations. For
686       example:
687
688           local $B::overlay = {};
689           ...
690           if ($op->name eq "foo") {
691               $B::overlay->{$$op} = {
692                       name => 'bar',
693                       next => $op->next->next,
694               };
695           }
696           ...
697           $op->name # returns "bar"
698           $op->next # returns the next op but one
699

AUTHOR

701       Malcolm Beattie, "mbeattie@sable.ox.ac.uk"
702
703
704
705perl v5.28.2                      2018-11-01                            B(3pm)
Impressum