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".
62
63       init_av
64           Returns the AV object (i.e. in class B::AV) representing INIT
65           blocks.
66
67       check_av
68           Returns the AV object (i.e. in class B::AV) representing CHECK
69           blocks.
70
71       unitcheck_av
72           Returns the AV object (i.e. in class B::AV) representing UNITCHECK
73           blocks.
74
75       begin_av
76           Returns the AV object (i.e. in class B::AV) representing BEGIN
77           blocks.
78
79       end_av
80           Returns the AV object (i.e. in class B::AV) representing END
81           blocks.
82
83       comppadlist
84           Returns the AV object (i.e. in class B::AV) of the global
85           comppadlist.
86
87       regex_padav
88           Only when perl was compiled with ithreads.
89
90       main_cv
91           Return the (faked) CV corresponding to the main part of the Perl
92           program.
93
94   Functions for Examining the Symbol Table
95       walksymtable(SYMREF, METHOD, RECURSE, PREFIX)
96           Walk the symbol table starting at SYMREF and call METHOD on each
97           symbol (a B::GV object) visited.  When the walk reaches package
98           symbols (such as "Foo::") it invokes RECURSE, passing in the symbol
99           name, and only recurses into the package if that sub returns true.
100
101           PREFIX is the name of the SYMREF you're walking.
102
103           For example:
104
105             # Walk CGI's symbol table calling print_subs on each symbol.
106             # Recurse only into CGI::Util::
107             walksymtable(\%CGI::, 'print_subs',
108                          sub { $_[0] eq 'CGI::Util::' }, 'CGI::');
109
110           print_subs() is a B::GV method you have declared.  Also see "B::GV
111           Methods", below.
112
113   Functions Returning "B::OP" objects or for walking op trees
114       For descriptions of the class hierarchy of these objects and the
115       methods that can be called on them, see below, "OVERVIEW OF CLASSES"
116       and "OP-RELATED CLASSES".
117
118       main_root
119           Returns the root op (i.e. an object in the appropriate
120           B::OP-derived class) of the main part of the Perl program.
121
122       main_start
123           Returns the starting op of the main part of the Perl program.
124
125       walkoptree(OP, METHOD)
126           Does a tree-walk of the syntax tree based at OP and calls METHOD on
127           each op it visits.  Each node is visited before its children.  If
128           "walkoptree_debug" (see below) has been called to turn debugging on
129           then the method "walkoptree_debug" is called on each op before
130           METHOD is called.
131
132       walkoptree_debug(DEBUG)
133           Returns the current debugging flag for "walkoptree".  If the
134           optional DEBUG argument is non-zero, it sets the debugging flag to
135           that.  See the description of "walkoptree" above for what the
136           debugging flag does.
137
138   Miscellaneous Utility Functions
139       ppname(OPNUM)
140           Return the PP function name (e.g. "pp_add") of op number OPNUM.
141
142       hash(STR)
143           Returns a string in the form "0x..." representing the value of the
144           internal hash function used by perl on string STR.
145
146       cast_I32(I)
147           Casts I to the internal I32 type used by that perl.
148
149       minus_c
150           Does the equivalent of the "-c" command-line option.  Obviously,
151           this is only useful in a BEGIN block or else the flag is set too
152           late.
153
154       cstring(STR)
155           Returns a double-quote-surrounded escaped version of STR which can
156           be used as a string in C source code.
157
158       perlstring(STR)
159           Returns a double-quote-surrounded escaped version of STR which can
160           be used as a string in Perl source code.
161
162       class(OBJ)
163           Returns the class of an object without the part of the classname
164           preceding the first "::".  This is used to turn "B::UNOP" into
165           "UNOP" for example.
166
167       threadsv_names
168           In a perl compiled for threads, this returns a list of the special
169           per-thread threadsv variables.
170
171   Exported utility variables
172       @optype
173             my $op_type = $optype[$op_type_num];
174
175           A simple mapping of the op type number to its type (like 'COP' or
176           'BINOP').
177
178       @specialsv_name
179             my $sv_name = $specialsv_name[$sv_index];
180
181           Certain SV types are considered 'special'.  They're represented by
182           B::SPECIAL and are referred to by a number from the specialsv_list.
183           This array maps that number back to the name of the SV (like
184           'Nullsv' or '&PL_sv_undef').
185

OVERVIEW OF CLASSES

187       The C structures used by Perl's internals to hold SV and OP information
188       (PVIV, AV, HV, ..., OP, SVOP, UNOP, ...) are modelled on a class
189       hierarchy and the "B" module gives access to them via a true object
190       hierarchy.  Structure fields which point to other objects (whether
191       types of SV or types of OP) are represented by the "B" module as Perl
192       objects of the appropriate class.
193
194       The bulk of the "B" module is the methods for accessing fields of these
195       structures.
196
197       Note that all access is read-only.  You cannot modify the internals by
198       using this module.  Also, note that the B::OP and B::SV objects created
199       by this module are only valid for as long as the underlying objects
200       exist; their creation doesn't increase the reference counts of the
201       underlying objects.  Trying to access the fields of a freed object will
202       give incomprehensible results, or worse.
203
204   SV-RELATED CLASSES
205       B::IV, B::NV, B::RV, B::PV, B::PVIV, B::PVNV, B::PVMG, B::BM (5.9.5 and
206       earlier), B::PVLV, B::AV, B::HV, B::CV, B::GV, B::FM, B::IO.  These
207       classes correspond in the obvious way to the underlying C structures of
208       similar names.  The inheritance hierarchy mimics the underlying C
209       "inheritance".  For the 5.10.x branch, (ie 5.10.0, 5.10.1 etc) this is:
210
211                                  B::SV
212                                    |
213                       +------------+------------+------------+
214                       |            |            |            |
215                     B::PV        B::IV        B::NV        B::RV
216                         \         /           /
217                          \       /           /
218                           B::PVIV           /
219                                \           /
220                                 \         /
221                                  \       /
222                                   B::PVNV
223                                      |
224                                      |
225                                   B::PVMG
226                                      |
227                          +-----+-----+-----+-----+
228                          |     |     |     |     |
229                        B::AV B::GV B::HV B::CV B::IO
230                                |           |
231                                |           |
232                             B::PVLV      B::FM
233
234       For 5.9.0 and earlier, PVLV is a direct subclass of PVMG, and BM is
235       still present as a distinct type, so the base of this diagram is
236
237                                      |
238                                      |
239                                   B::PVMG
240                                      |
241                   +------+-----+-----+-----+-----+-----+
242                   |      |     |     |     |     |     |
243                B::PVLV B::BM B::AV B::GV B::HV B::CV B::IO
244                                                  |
245                                                  |
246                                                B::FM
247
248       For 5.11.0 and later, B::RV is abolished, and IVs can be used to store
249       references, and a new type B::REGEXP is introduced, giving this
250       structure:
251
252                                  B::SV
253                                    |
254                       +------------+------------+
255                       |            |            |
256                     B::PV        B::IV        B::NV
257                         \         /           /
258                          \       /           /
259                           B::PVIV           /
260                                \           /
261                                 \         /
262                                  \       /
263                                   B::PVNV
264                                      |
265                                      |
266                                   B::PVMG
267                                      |
268                  +-------+-------+---+---+-------+-------+
269                  |       |       |       |       |       |
270                B::AV   B::GV   B::HV   B::CV   B::IO B::REGEXP
271                          |               |
272                          |               |
273                       B::PVLV          B::FM
274
275       Access methods correspond to the underlying C macros for field access,
276       usually with the leading "class indication" prefix removed (Sv, Av, Hv,
277       ...).  The leading prefix is only left in cases where its removal would
278       cause a clash in method name.  For example, "GvREFCNT" stays as-is
279       since its abbreviation would clash with the "superclass" method
280       "REFCNT" (corresponding to the C function "SvREFCNT").
281
282   B::SV Methods
283       REFCNT
284       FLAGS
285       object_2svref
286           Returns a reference to the regular scalar corresponding to this
287           B::SV object.  In other words, this method is the inverse operation
288           to the svref_2object() subroutine.  This scalar and other data it
289           points at should be considered read-only: modifying them is neither
290           safe nor guaranteed to have a sensible effect.
291
292   B::IV Methods
293       IV  Returns the value of the IV, interpreted as a signed integer.  This
294           will be misleading if "FLAGS & SVf_IVisUV".  Perhaps you want the
295           "int_value" method instead?
296
297       IVX
298       UVX
299       int_value
300           This method returns the value of the IV as an integer.  It differs
301           from "IV" in that it returns the correct value regardless of
302           whether it's stored signed or unsigned.
303
304       needs64bits
305       packiv
306
307   B::NV Methods
308       NV
309       NVX
310
311   B::RV Methods
312       RV
313
314   B::PV Methods
315       PV  This method is the one you usually want.  It constructs a string
316           using the length and offset information in the struct: for ordinary
317           scalars it will return the string that you'd see from Perl, even if
318           it contains null characters.
319
320       RV  Same as B::RV::RV, except that it will die() if the PV isn't a
321           reference.
322
323       PVX This method is less often useful.  It assumes that the string
324           stored in the struct is null-terminated, and disregards the length
325           information.
326
327           It is the appropriate method to use if you need to get the name of
328           a lexical variable from a padname array.  Lexical variable names
329           are always stored with a null terminator, and the length field
330           (CUR) is overloaded for other purposes and can't be relied on here.
331
332       CUR This method returns the internal length field, which consists of
333           the number of internal bytes, not necessarily the number of logical
334           characters.
335
336       LEN This method returns the number of bytes allocated (via malloc) for
337           storing the string.  This is 0 if the scalar does not "own" the
338           string.
339
340   B::PVMG Methods
341       MAGIC
342       SvSTASH
343
344   B::MAGIC Methods
345       MOREMAGIC
346       precomp
347           Only valid on r-magic, returns the string that generated the
348           regexp.
349
350       PRIVATE
351       TYPE
352       FLAGS
353       OBJ Will die() if called on r-magic.
354
355       PTR
356       REGEX
357           Only valid on r-magic, returns the integer value of the REGEX
358           stored in the MAGIC.
359
360   B::PVLV Methods
361       TARGOFF
362       TARGLEN
363       TYPE
364       TARG
365
366   B::BM Methods
367       USEFUL
368       PREVIOUS
369       RARE
370       TABLE
371
372   B::GV Methods
373       is_empty
374           This method returns TRUE if the GP field of the GV is NULL.
375
376       NAME
377       SAFENAME
378           This method returns the name of the glob, but if the first
379           character of the name is a control character, then it converts it
380           to ^X first, so that *^G would return "^G" rather than "\cG".
381
382           It's useful if you want to print out the name of a variable.  If
383           you restrict yourself to globs which exist at compile-time then the
384           result ought to be unambiguous, because code like "${"^G"} = 1" is
385           compiled as two ops - a constant string and a dereference (rv2gv) -
386           so that the glob is created at runtime.
387
388           If you're working with globs at runtime, and need to disambiguate
389           *^G from *{"^G"}, then you should use the raw NAME method.
390
391       STASH
392       SV
393       IO
394       FORM
395       AV
396       HV
397       EGV
398       CV
399       CVGEN
400       LINE
401       FILE
402       FILEGV
403       GvREFCNT
404       FLAGS
405
406   B::IO Methods
407       B::IO objects derive from IO objects and you will get more information
408       from the IO object itself.
409
410       For example:
411
412         $gvio = B::svref_2object(\*main::stdin)->IO;
413         $IO = $gvio->object_2svref();
414         $fd = $IO->fileno();
415
416       LINES
417       PAGE
418       PAGE_LEN
419       LINES_LEFT
420       TOP_NAME
421       TOP_GV
422       FMT_NAME
423       FMT_GV
424       BOTTOM_NAME
425       BOTTOM_GV
426       SUBPROCESS
427       IoTYPE
428           A character symbolizing the type of IO Handle.
429
430             -     STDIN/OUT
431             I     STDIN/OUT/ERR
432             <     read-only
433             >     write-only
434             a     append
435             +     read and write
436             s     socket
437             |     pipe
438             I     IMPLICIT
439             #     NUMERIC
440             space closed handle
441             \0    closed internal handle
442
443       IoFLAGS
444       IsSTD
445           Takes one argument ( 'stdin' | 'stdout' | 'stderr' ) and returns
446           true if the IoIFP of the object is equal to the handle whose name
447           was passed as argument; i.e., $io->IsSTD('stderr') is true if
448           IoIFP($io) == PerlIO_stderr().
449
450   B::AV Methods
451       FILL
452       MAX
453       ARRAY
454       ARRAYelt
455           Like "ARRAY", but takes an index as an argument to get only one
456           element, rather than a list of all of them.
457
458       OFF This method is deprecated if running under Perl 5.8, and is no
459           longer present if running under Perl 5.9
460
461       AvFLAGS
462           This method returns the AV specific flags.  In Perl 5.9 these are
463           now stored in with the main SV flags, so this method is no longer
464           present.
465
466   B::CV Methods
467       STASH
468       START
469       ROOT
470       GV
471       FILE
472       DEPTH
473       PADLIST
474       OUTSIDE
475       OUTSIDE_SEQ
476       XSUB
477       XSUBANY
478           For constant subroutines, returns the constant SV returned by the
479           subroutine.
480
481       CvFLAGS
482       const_sv
483
484   B::HV Methods
485       FILL
486       MAX
487       KEYS
488       RITER
489       NAME
490       ARRAY
491       PMROOT
492           This method is not present if running under Perl 5.9, as the PMROOT
493           information is no longer stored directly in the hash.
494
495   OP-RELATED CLASSES
496       "B::OP", "B::UNOP", "B::BINOP", "B::LOGOP", "B::LISTOP", "B::PMOP",
497       "B::SVOP", "B::PADOP", "B::PVOP", "B::LOOP", "B::COP".
498
499       These classes correspond in the obvious way to the underlying C
500       structures of similar names.  The inheritance hierarchy mimics the
501       underlying C "inheritance":
502
503                                        B::OP
504                                          |
505                          +---------------+--------+--------+-------+
506                          |               |        |        |       |
507                       B::UNOP          B::SVOP B::PADOP  B::COP  B::PVOP
508                        ,'  `-.
509                       /       `--.
510                  B::BINOP     B::LOGOP
511                      |
512                      |
513                  B::LISTOP
514                    ,' `.
515                   /     \
516               B::LOOP B::PMOP
517
518       Access methods correspond to the underlying C structre field names,
519       with the leading "class indication" prefix ("op_") removed.
520
521   B::OP Methods
522       These methods get the values of similarly named fields within the OP
523       data structure.  See top of "op.h" for more info.
524
525       next
526       sibling
527       name
528           This returns the op name as a string (e.g. "add", "rv2av").
529
530       ppaddr
531           This returns the function name as a string (e.g.
532           "PL_ppaddr[OP_ADD]", "PL_ppaddr[OP_RV2AV]").
533
534       desc
535           This returns the op description from the global C PL_op_desc array
536           (e.g. "addition" "array deref").
537
538       targ
539       type
540       opt
541       flags
542       private
543       spare
544
545   B::UNOP METHOD
546       first
547
548   B::BINOP METHOD
549       last
550
551   B::LOGOP METHOD
552       other
553
554   B::LISTOP METHOD
555       children
556
557   B::PMOP Methods
558       pmreplroot
559       pmreplstart
560       pmnext
561           Only up to Perl 5.9.4
562
563       pmflags
564       extflags
565           Since Perl 5.9.5
566
567       precomp
568       pmoffset
569           Only when perl was compiled with ithreads.
570
571   B::SVOP METHOD
572       sv
573       gv
574
575   B::PADOP METHOD
576       padix
577
578   B::PVOP METHOD
579       pv
580
581   B::LOOP Methods
582       redoop
583       nextop
584       lastop
585
586   B::COP Methods
587       label
588       stash
589       stashpv
590       stashlen
591       file
592       cop_seq
593       arybase
594       line
595       warnings
596       io
597       hints
598       hints_hash
599

AUTHOR

601       Malcolm Beattie, "mbeattie@sable.ox.ac.uk"
602
603
604
605perl v5.16.3                      2013-03-04                            B(3pm)
Impressum