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".
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',
108 sub { $_[0] eq 'CGI::Util::' }, '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 variables
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
191 types of SV or types of OP) are represented by the "B" module as Perl
192 objects 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
279 since its abbreviation would clash with the "superclass" method
280 "REFCNT" (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
324 stored 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
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 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 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 B::PVMG Methods
341 MAGIC
342 SvSTASH
343 B::MAGIC Methods
345 MOREMAGIC
346 precomp
347 Only valid on r-magic, returns the string that generated the
348 regexp.
349 PRIVATE
351 TYPE
352 FLAGS
353 OBJ Will die() if called on r-magic.
354 PTR
356 REGEX
357 Only valid on r-magic, returns the integer value of the REGEX
358 stored in the MAGIC.
359 B::PVLV Methods
361 TARGOFF
362 TARGLEN
363 TYPE
364 TARG
365 B::BM Methods
367 USEFUL
368 PREVIOUS
369 RARE
370 TABLE
371 B::GV Methods
373 is_empty
374 This method returns TRUE if the GP field of the GV is NULL.
375 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 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 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 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 B::IO Methods
407 B::IO objects derive from IO objects and you will get more information
408 from the IO object itself.
409 For example:
411 $gvio = B::svref_2object(\*main::stdin)->IO;
413 $IO = $gvio->object_2svref();
414 $fd = $IO->fileno();
415 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 - 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 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 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 OFF This method is deprecated if running under Perl 5.8, and is no
459 longer present if running under Perl 5.9
460 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 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 CvFLAGS
482 const_sv
483 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 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 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 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 Access methods correspond to the underlying C structre field names,
519 with the leading "class indication" prefix ("op_") removed.
520 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 next
526 sibling
527 name
528 This returns the op name as a string (e.g. "add", "rv2av").
529 ppaddr
531 This returns the function name as a string (e.g.
532 "PL_ppaddr[OP_ADD]", "PL_ppaddr[OP_RV2AV]").
533 desc
535 This returns the op description from the global C PL_op_desc array
536 (e.g. "addition" "array deref").
537 targ
539 type
540 opt
541 flags
542 private
543 spare
544 B::UNOP METHOD
546 first
547 B::BINOP METHOD
549 last
550 B::LOGOP METHOD
552 other
553 B::LISTOP METHOD
555 children
556 B::PMOP Methods
558 pmreplroot
559 pmreplstart
560 pmnext
561 Only up to Perl 5.9.4
562 pmflags
564 extflags
565 Since Perl 5.9.5
566 precomp
568 pmoffset
569 Only when perl was compiled with ithreads.
570 B::SVOP METHOD
572 sv
573 gv
574 B::PADOP METHOD
576 padix
577 B::PVOP METHOD
579 pv
580 B::LOOP Methods
582 redoop
583 nextop
584 lastop
585 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
601 Malcolm Beattie, "mbeattie@sable.ox.ac.uk"
602perl v5.16.3 2013-03-04 B(3pm)