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::PVIV /
226 \ /
227 \ /
228 \ /
229 B::PVNV
230 |
231 |
232 B::PVMG
233 |
234 +-------+-------+---+---+-------+-------+
235 | | | | | |
236 B::AV B::GV B::HV B::CV B::IO B::REGEXP
237 | |
238 | |
239 B::PVLV B::FM
240 Access methods correspond to the underlying C macros for field access,
242 usually with the leading "class indication" prefix removed (Sv, Av, Hv,
243 ...). The leading prefix is only left in cases where its removal would
244 cause a clash in method name. For example, "GvREFCNT" stays as-is
245 since its abbreviation would clash with the "superclass" method
246 "REFCNT" (corresponding to the C function "SvREFCNT").
247 B::SV Methods
249 REFCNT
250 FLAGS
251 object_2svref
252 Returns a reference to the regular scalar corresponding to this
253 B::SV object. In other words, this method is the inverse operation
254 to the svref_2object() subroutine. This scalar and other data it
255 points at should be considered read-only: modifying them is neither
256 safe nor guaranteed to have a sensible effect.
257 B::IV Methods
259 IV Returns the value of the IV, interpreted as a signed integer. This
260 will be misleading if "FLAGS & SVf_IVisUV". Perhaps you want the
261 "int_value" method instead?
262 IVX
264 UVX
265 int_value
266 This method returns the value of the IV as an integer. It differs
267 from "IV" in that it returns the correct value regardless of
268 whether it's stored signed or unsigned.
269 needs64bits
271 packiv
272 B::NV Methods
274 NV
275 NVX
276 COP_SEQ_RANGE_LOW
277 COP_SEQ_RANGE_HIGH
278 These last two are only valid for pad name SVs. They only existed
279 in the B::NV class before Perl 5.22. In 5.22 they were moved to
280 the B::PADNAME class.
281 B::RV Methods
283 RV
284 B::PV Methods
286 PV This method is the one you usually want. It constructs a string
287 using the length and offset information in the struct: for ordinary
288 scalars it will return the string that you'd see from Perl, even if
289 it contains null characters.
290 RV Same as B::RV::RV, except that it will die() if the PV isn't a
292 reference.
293 PVX This method is less often useful. It assumes that the string
295 stored in the struct is null-terminated, and disregards the length
296 information.
297 It is the appropriate method to use if you need to get the name of
299 a lexical variable from a padname array. Lexical variable names
300 are always stored with a null terminator, and the length field
301 (CUR) is overloaded for other purposes and can't be relied on here.
302 CUR This method returns the internal length field, which consists of
304 the number of internal bytes, not necessarily the number of logical
305 characters.
306 LEN This method returns the number of bytes allocated (via malloc) for
308 storing the string. This is 0 if the scalar does not "own" the
309 string.
310 B::PVMG Methods
312 MAGIC
313 SvSTASH
314 B::MAGIC Methods
316 MOREMAGIC
317 precomp
318 Only valid on r-magic, returns the string that generated the
319 regexp.
320 PRIVATE
322 TYPE
323 FLAGS
324 OBJ Will die() if called on r-magic.
325 PTR
327 REGEX
328 Only valid on r-magic, returns the integer value of the REGEX
329 stored in the MAGIC.
330 B::PVLV Methods
332 TARGOFF
333 TARGLEN
334 TYPE
335 TARG
336 B::BM Methods
338 USEFUL
339 PREVIOUS
340 RARE
341 TABLE
342 B::REGEXP Methods
344 REGEX
345 precomp
346 qr_anoncv
347 compflags
348 The last two were added in Perl 5.22.
349 B::GV Methods
351 is_empty
352 This method returns TRUE if the GP field of the GV is NULL.
353 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 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 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 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 B::IO Methods
387 B::IO objects derive from IO objects and you will get more information
388 from the IO object itself.
389 For example:
391 $gvio = B::svref_2object(\*main::stdin)->IO;
393 $IO = $gvio->object_2svref();
394 $fd = $IO->fileno();
395 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 - 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 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 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 B::CV Methods
439 STASH
440 START
441 ROOT
442 GV
443 FILE
444 DEPTH
445 PADLIST
446 Returns a B::PADLIST object.
447 OUTSIDE
449 OUTSIDE_SEQ
450 XSUB
451 XSUBANY
452 For constant subroutines, returns the constant SV returned by the
453 subroutine.
454 CvFLAGS
456 const_sv
457 NAME_HEK
458 Returns the name of a lexical sub, otherwise "undef".
459 B::HV Methods
461 FILL
462 MAX
463 KEYS
464 RITER
465 NAME
466 ARRAY
467 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 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 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 Access methods correspond to the underlying C structure field names,
495 with the leading "class indication" prefix ("op_") removed.
496 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 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 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 name
513 This returns the op name as a string (e.g. "add", "rv2av").
514 ppaddr
516 This returns the function name as a string (e.g.
517 "PL_ppaddr[OP_ADD]", "PL_ppaddr[OP_RV2AV]").
518 desc
520 This returns the op description from the global C PL_op_desc array
521 (e.g. "addition" "array deref").
522 targ
524 type
525 opt
526 flags
527 private
528 spare
529 B::UNOP Method
531 first
532 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 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 B::BINOP Method
548 last
549 B::LOGOP Method
551 other
552 B::LISTOP Method
554 children
555 B::PMOP Methods
557 pmreplroot
558 pmreplstart
559 pmflags
560 precomp
561 pmoffset
562 Only when perl was compiled with ithreads.
563 code_list
565 Since perl 5.17.1
566 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 B::SVOP Methods
574 sv
575 gv
576 B::PADOP Method
578 padix
579 B::PVOP Method
581 pv
582 B::LOOP Methods
584 redoop
585 nextop
586 lastop
587 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 label
593 stash
594 stashpv
595 stashoff (threaded only)
596 file
597 cop_seq
598 line
599 warnings
600 io
601 hints
602 hints_hash
603 B::METHOP Methods (Since Perl 5.22)
605 first
606 meth_sv
607 PAD-RELATED CLASSES
609 Perl 5.18 introduced a new class, B::PADLIST, returned by B::CV's
610 "PADLIST" method.
611 Perl 5.22 introduced the B::PADNAMELIST and B::PADNAME classes.
613 B::PADLIST Methods
615 MAX
616 ARRAY
617 A list of pads. The first one is a B::PADNAMELIST containing the
618 names. The rest are currently B::AV objects, but that could change
619 in future versions.
620 ARRAYelt
622 Like "ARRAY", but takes an index as an argument to get only one
623 element, rather than a list of all of them.
624 NAMES
626 This method, introduced in 5.22, returns the B::PADNAMELIST. It is
627 equivalent to "ARRAYelt" with a 0 argument.
628 REFCNT
630 id This method, introduced in 5.22, returns an ID shared by clones of
631 the same padlist.
632 outid
634 This method, also added in 5.22, returns the ID of the outer
635 padlist.
636 B::PADNAMELIST Methods
638 MAX
639 ARRAY
640 ARRAYelt
641 These two methods return the pad names, using B::SPECIAL objects
642 for null pointers and B::PADNAME objects otherwise.
643 REFCNT
645 B::PADNAME Methods
647 PV
648 PVX
649 LEN
650 REFCNT
651 FLAGS
652 For backward-compatibility, if the PADNAMEt_OUTER flag is set, the
653 FLAGS method adds the SVf_FAKE flag, too.
654 TYPE
656 A B::HV object representing the stash for a typed lexical.
657 SvSTASH
659 A backward-compatibility alias for TYPE.
660 OURSTASH
662 A B::HV object representing the stash for 'our' variables.
663 PROTOCV
665 The prototype CV for a 'my' sub.
666 COP_SEQ_RANGE_LOW
668 COP_SEQ_RANGE_HIGH
669 Sequence numbers representing the scope within which a lexical is
670 visible. Meaningless if PADNAMEt_OUTER is set.
671 PARENT_PAD_INDEX
673 Only meaningful if PADNAMEt_OUTER is set.
674 PARENT_FAKELEX_FLAGS
676 Only meaningful if PADNAMEt_OUTER is set.
677 $B::overlay
679 Although the optree is read-only, there is an overlay facility that
680 allows you to override what values the various B::*OP methods return
681 for a particular op. $B::overlay should be set to reference a two-deep
682 hash: indexed by OP address, then method name. Whenever a an op method
683 is called, the value in the hash is returned if it exists. This
684 facility is used by B::Deparse to "undo" some optimisations. For
685 example:
686 local $B::overlay = {};
688 ...
689 if ($op->name eq "foo") {
690 $B::overlay->{$$op} = {
691 name => 'bar',
692 next => $op->next->next,
693 };
694 }
695 ...
696 $op->name # returns "bar"
697 $op->next # returns the next op but one
698
700 Malcolm Beattie, "mbeattie@sable.ox.ac.uk"
701perl v5.32.1 2021-03-31 B(3pm)