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 "backends"
14       of the Perl compiler. Usage of the compiler does not require knowledge
15       of this module: see the O module for the user-visible part. The "B"
16       module is of use to those who want to write new compiler backends. This
17       documentation assumes that the reader knows a fair amount about perl's
18       internals including such things as SVs, OPs and the internal symbol
19       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", this
51           is the primary way to get an initial "handle" on an internal perl
52           data structure which can then be followed with the other access
53           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', sub { $_[0] eq 'CGI::Util::' },
108                          '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 variabiles
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 types
191       of SV or types of OP) are represented by the "B" module as Perl objects
192       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 since
279       its abbreviation would clash with the "superclass" method "REFCNT"
280       (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 stored
324           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 are
329           always stored with a null terminator, and the length field (SvCUR)
330           is overloaded for other purposes and can't be relied on here.
331
332   B::PVMG Methods
333       MAGIC
334       SvSTASH
335
336   B::MAGIC Methods
337       MOREMAGIC
338       precomp
339           Only valid on r-magic, returns the string that generated the
340           regexp.
341
342       PRIVATE
343       TYPE
344       FLAGS
345       OBJ Will die() if called on r-magic.
346
347       PTR
348       REGEX
349           Only valid on r-magic, returns the integer value of the REGEX
350           stored in the MAGIC.
351
352   B::PVLV Methods
353       TARGOFF
354       TARGLEN
355       TYPE
356       TARG
357
358   B::BM Methods
359       USEFUL
360       PREVIOUS
361       RARE
362       TABLE
363
364   B::GV Methods
365       is_empty
366           This method returns TRUE if the GP field of the GV is NULL.
367
368       NAME
369       SAFENAME
370           This method returns the name of the glob, but if the first
371           character of the name is a control character, then it converts it
372           to ^X first, so that *^G would return "^G" rather than "\cG".
373
374           It's useful if you want to print out the name of a variable.  If
375           you restrict yourself to globs which exist at compile-time then the
376           result ought to be unambiguous, because code like "${"^G"} = 1" is
377           compiled as two ops - a constant string and a dereference (rv2gv) -
378           so that the glob is created at runtime.
379
380           If you're working with globs at runtime, and need to disambiguate
381           *^G from *{"^G"}, then you should use the raw NAME method.
382
383       STASH
384       SV
385       IO
386       FORM
387       AV
388       HV
389       EGV
390       CV
391       CVGEN
392       LINE
393       FILE
394       FILEGV
395       GvREFCNT
396       FLAGS
397
398   B::IO Methods
399       LINES
400       PAGE
401       PAGE_LEN
402       LINES_LEFT
403       TOP_NAME
404       TOP_GV
405       FMT_NAME
406       FMT_GV
407       BOTTOM_NAME
408       BOTTOM_GV
409       SUBPROCESS
410       IoTYPE
411       IoFLAGS
412       IsSTD
413           Takes one arguments ( 'stdin' | 'stdout' | 'stderr' ) and returns
414           true if the IoIFP of the object is equal to the handle whose name
415           was passed as argument ( i.e. $io->IsSTD('stderr') is true if
416           IoIFP($io) == PerlIO_stdin() ).
417
418   B::AV Methods
419       FILL
420       MAX
421       ARRAY
422       ARRAYelt
423           Like "ARRAY", but takes an index as an argument to get only one
424           element, rather than a list of all of them.
425
426       OFF This method is deprecated if running under Perl 5.8, and is no
427           longer present if running under Perl 5.9
428
429       AvFLAGS
430           This method returns the AV specific flags. In Perl 5.9 these are
431           now stored in with the main SV flags, so this method is no longer
432           present.
433
434   B::CV Methods
435       STASH
436       START
437       ROOT
438       GV
439       FILE
440       DEPTH
441       PADLIST
442       OUTSIDE
443       OUTSIDE_SEQ
444       XSUB
445       XSUBANY
446           For constant subroutines, returns the constant SV returned by the
447           subroutine.
448
449       CvFLAGS
450       const_sv
451
452   B::HV Methods
453       FILL
454       MAX
455       KEYS
456       RITER
457       NAME
458       ARRAY
459       PMROOT
460           This method is not present if running under Perl 5.9, as the PMROOT
461           information is no longer stored directly in the hash.
462
463   OP-RELATED CLASSES
464       "B::OP", "B::UNOP", "B::BINOP", "B::LOGOP", "B::LISTOP", "B::PMOP",
465       "B::SVOP", "B::PADOP", "B::PVOP", "B::LOOP", "B::COP".
466
467       These classes correspond in the obvious way to the underlying C
468       structures of similar names. The inheritance hierarchy mimics the
469       underlying C "inheritance":
470
471                                        B::OP
472                                          |
473                          +---------------+--------+--------+-------+
474                          |               |        |        |       |
475                       B::UNOP          B::SVOP B::PADOP  B::COP  B::PVOP
476                        ,'  `-.
477                       /       `--.
478                  B::BINOP     B::LOGOP
479                      |
480                      |
481                  B::LISTOP
482                    ,' `.
483                   /     \
484               B::LOOP B::PMOP
485
486       Access methods correspond to the underlying C structre field names,
487       with the leading "class indication" prefix ("op_") removed.
488
489   B::OP Methods
490       These methods get the values of similarly named fields within the OP
491       data structure.  See top of "op.h" for more info.
492
493       next
494       sibling
495       name
496           This returns the op name as a string (e.g. "add", "rv2av").
497
498       ppaddr
499           This returns the function name as a string (e.g.
500           "PL_ppaddr[OP_ADD]", "PL_ppaddr[OP_RV2AV]").
501
502       desc
503           This returns the op description from the global C PL_op_desc array
504           (e.g. "addition" "array deref").
505
506       targ
507       type
508       opt
509       flags
510       private
511       spare
512
513   B::UNOP METHOD
514       first
515
516   B::BINOP METHOD
517       last
518
519   B::LOGOP METHOD
520       other
521
522   B::LISTOP METHOD
523       children
524
525   B::PMOP Methods
526       pmreplroot
527       pmreplstart
528       pmnext
529           Only up to Perl 5.9.4
530
531       pmregexp
532       pmflags
533       extflags
534           Since Perl 5.9.5
535
536       precomp
537       pmoffset
538           Only when perl was compiled with ithreads.
539
540   B::SVOP METHOD
541       sv
542       gv
543
544   B::PADOP METHOD
545       padix
546
547   B::PVOP METHOD
548       pv
549
550   B::LOOP Methods
551       redoop
552       nextop
553       lastop
554
555   B::COP Methods
556       label
557       stash
558       stashpv
559       file
560       cop_seq
561       arybase
562       line
563       warnings
564       io
565       hints
566       hints_hash
567

AUTHOR

569       Malcolm Beattie, "mbeattie@sable.ox.ac.uk"
570
571
572
573perl v5.12.4                      2011-06-07                            B(3pm)
Impressum