1B(3pm) Perl Programmers Reference Guide B(3pm)
2
6 B - The Perl Compiler
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 "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
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", 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 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".
62 init_av
64 Returns the AV object (i.e. in class B::AV) representing INIT
65 blocks.
66 check_av
68 Returns the AV object (i.e. in class B::AV) representing CHECK
69 blocks.
70 unitcheck_av
72 Returns the AV object (i.e. in class B::AV) representing UNITCHECK
73 blocks.
74 begin_av
76 Returns the AV object (i.e. in class B::AV) representing BEGIN
77 blocks.
78 end_av
80 Returns the AV object (i.e. in class B::AV) representing END
81 blocks.
82 comppadlist
84 Returns the AV object (i.e. in class B::AV) of the global
85 comppadlist.
86 regex_padav
88 Only when perl was compiled with ithreads.
89 main_cv
91 Return the (faked) CV corresponding to the main part of the Perl
92 program.
93 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 PREFIX is the name of the SYMREF you're walking.
102 For example:
104 # 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 print_subs() is a B::GV method you have declared. Also see "B::GV
111 Methods", below.
112 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 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 main_start
123 Returns the starting op of the main part of the Perl program.
124 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 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 Miscellaneous Utility Functions
139 ppname(OPNUM)
140 Return the PP function name (e.g. "pp_add") of op number OPNUM.
141 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 cast_I32(I)
147 Casts I to the internal I32 type used by that perl.
148 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 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 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 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 threadsv_names
168 In a perl compiled for threads, this returns a list of the special
169 per-thread threadsv variables.
170 Exported utility variabiles
172 @optype
173 my $op_type = $optype[$op_type_num];
174 A simple mapping of the op type number to its type (like 'COP' or
176 'BINOP').
177 @specialsv_name
179 my $sv_name = $specialsv_name[$sv_index];
180 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
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 The bulk of the "B" module is the methods for accessing fields of these
195 structures.
196 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 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 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 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 |
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 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 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 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 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 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 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 needs64bits
305 packiv
306 B::NV Methods
308 NV
309 NVX
310 B::RV Methods
312 RV
313 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 RV Same as B::RV::RV, except that it will die() if the PV isn't a
321 reference.
322 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 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 B::PVMG Methods
333 MAGIC
334 SvSTASH
335 B::MAGIC Methods
337 MOREMAGIC
338 precomp
339 Only valid on r-magic, returns the string that generated the
340 regexp.
341 PRIVATE
343 TYPE
344 FLAGS
345 OBJ Will die() if called on r-magic.
346 PTR
348 REGEX
349 Only valid on r-magic, returns the integer value of the REGEX
350 stored in the MAGIC.
351 B::PVLV Methods
353 TARGOFF
354 TARGLEN
355 TYPE
356 TARG
357 B::BM Methods
359 USEFUL
360 PREVIOUS
361 RARE
362 TABLE
363 B::GV Methods
365 is_empty
366 This method returns TRUE if the GP field of the GV is NULL.
367 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 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 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 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 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 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 OFF This method is deprecated if running under Perl 5.8, and is no
427 longer present if running under Perl 5.9
428 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 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 CvFLAGS
450 const_sv
451 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 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 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 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 Access methods correspond to the underlying C structre field names,
487 with the leading "class indication" prefix ("op_") removed.
488 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 next
494 sibling
495 name
496 This returns the op name as a string (e.g. "add", "rv2av").
497 ppaddr
499 This returns the function name as a string (e.g.
500 "PL_ppaddr[OP_ADD]", "PL_ppaddr[OP_RV2AV]").
501 desc
503 This returns the op description from the global C PL_op_desc array
504 (e.g. "addition" "array deref").
505 targ
507 type
508 opt
509 flags
510 private
511 spare
512 B::UNOP METHOD
514 first
515 B::BINOP METHOD
517 last
518 B::LOGOP METHOD
520 other
521 B::LISTOP METHOD
523 children
524 B::PMOP Methods
526 pmreplroot
527 pmreplstart
528 pmnext
529 Only up to Perl 5.9.4
530 pmregexp
532 pmflags
533 extflags
534 Since Perl 5.9.5
535 precomp
537 pmoffset
538 Only when perl was compiled with ithreads.
539 B::SVOP METHOD
541 sv
542 gv
543 B::PADOP METHOD
545 padix
546 B::PVOP METHOD
548 pv
549 B::LOOP Methods
551 redoop
552 nextop
553 lastop
554 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
569 Malcolm Beattie, "mbeattie@sable.ox.ac.uk"
570perl v5.10.1 2009-02-12 B(3pm)