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 ta‐
19 ble 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 meth‐
36 ods that can be called on them, see below, "OVERVIEW OF CLASSES" and
37 "SV-RELATED CLASSES".
38 sv_undef
40 Returns the SV object corresponding to the C variable "sv_undef".
41 sv_yes
43 Returns the SV object corresponding to the C variable "sv_yes".
44 sv_no
46 Returns the SV object corresponding to the C variable "sv_no".
47 svref_2object(SVREF)
49 Takes a reference to any Perl value, and turns the referred-to
50 value into an object in the appropriate B::OP-derived or
51 B::SV-derived class. Apart from functions such as "main_root", this
52 is the primary way to get an initial "handle" on an internal perl
53 data structure which can then be followed with the other access
54 methods.
55 The returned object will only be valid as long as the underlying
57 OPs and SVs continue to exist. Do not attempt to use the object
58 after the underlying structures are freed.
59 amagic_generation
61 Returns the SV object corresponding to the C variable "amagic_gen‐
62 eration".
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 begin_av
73 Returns the AV object (i.e. in class B::AV) representing BEGIN
74 blocks.
75 end_av
77 Returns the AV object (i.e. in class B::AV) representing END
78 blocks.
79 comppadlist
81 Returns the AV object (i.e. in class B::AV) of the global comp‐
82 padlist.
83 regex_padav
85 Only when perl was compiled with ithreads.
86 main_cv
88 Return the (faked) CV corresponding to the main part of the Perl
89 program.
90 Functions for Examining the Symbol Table
92 walksymtable(SYMREF, METHOD, RECURSE, PREFIX)
94 Walk the symbol table starting at SYMREF and call METHOD on each
95 symbol (a B::GV object) visited. When the walk reaches package
96 symbols (such as "Foo::") it invokes RECURSE, passing in the symbol
97 name, and only recurses into the package if that sub returns true.
98 PREFIX is the name of the SYMREF you're walking.
100 For example:
102 # Walk CGI's symbol table calling print_subs on each symbol.
104 # Recurse only into CGI::Util::
105 walksymtable(\%CGI::, 'print_subs', sub { $_[0] eq 'CGI::Util::' },
106 'CGI::');
107 print_subs() is a B::GV method you have declared. Also see "B::GV
109 Methods", below.
110 Functions Returning "B::OP" objects or for walking op trees
112 For descriptions of the class hierarchy of these objects and the meth‐
114 ods that can be called on them, see below, "OVERVIEW OF CLASSES" and
115 "OP-RELATED CLASSES".
116 main_root
118 Returns the root op (i.e. an object in the appropriate
119 B::OP-derived class) of the main part of the Perl program.
120 main_start
122 Returns the starting op of the main part of the Perl program.
123 walkoptree(OP, METHOD)
125 Does a tree-walk of the syntax tree based at OP and calls METHOD on
126 each op it visits. Each node is visited before its children. If
127 "walkoptree_debug" (see below) has been called to turn debugging on
128 then the method "walkoptree_debug" is called on each op before
129 METHOD is called.
130 walkoptree_debug(DEBUG)
132 Returns the current debugging flag for "walkoptree". If the
133 optional DEBUG argument is non-zero, it sets the debugging flag to
134 that. See the description of "walkoptree" above for what the debug‐
135 ging flag does.
136 Miscellaneous Utility Functions
138 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
172 The C structures used by Perl's internals to hold SV and OP information
173 (PVIV, AV, HV, ..., OP, SVOP, UNOP, ...) are modelled on a class hier‐
174 archy and the "B" module gives access to them via a true object hierar‐
175 chy. Structure fields which point to other objects (whether types of SV
176 or types of OP) are represented by the "B" module as Perl objects of
177 the appropriate class.
178 The bulk of the "B" module is the methods for accessing fields of these
180 structures.
181 Note that all access is read-only. You cannot modify the internals by
183 using this module. Also, note that the B::OP and B::SV objects created
184 by this module are only valid for as long as the underlying objects
185 exist; their creation doesn't increase the reference counts of the
186 underlying objects. Trying to access the fields of a freed object will
187 give incomprehensible results, or worse.
188 SV-RELATED CLASSES
190 B::IV, B::NV, B::RV, B::PV, B::PVIV, B::PVNV, B::PVMG, B::BM, B::PVLV,
192 B::AV, B::HV, B::CV, B::GV, B::FM, B::IO. These classes correspond in
193 the obvious way to the underlying C structures of similar names. The
194 inheritance hierarchy mimics the underlying C "inheritance". For 5.9.1
195 and later this is:
196 B::SV
198 ⎪
199 +--------------+----------+------------+
200 ⎪ ⎪ ⎪ ⎪
201 B::PV B::IV B::NV B::RV
202 \ / /
203 \ / /
204 B::PVIV /
205 \ /
206 \ /
207 \ /
208 B::PVNV
209 ⎪
210 ⎪
211 B::PVMG
212 ⎪
213 +-----+----+------+-----+-----+
214 ⎪ ⎪ ⎪ ⎪ ⎪ ⎪
215 B::BM B::AV B::GV B::HV B::CV B::IO
216 ⎪ ⎪
217 B::PVLV ⎪
218 B::FM
219 For 5.9.0 and earlier, PVLV is a direct subclass of PVMG, so the base
221 of this diagram is
222 ⎪
224 B::PVMG
225 ⎪
226 +------+-----+----+------+-----+-----+
227 ⎪ ⎪ ⎪ ⎪ ⎪ ⎪ ⎪
228 B::PVLV B::BM B::AV B::GV B::HV B::CV B::IO
229 ⎪
230 ⎪
231 B::FM
232 Access methods correspond to the underlying C macros for field access,
234 usually with the leading "class indication" prefix removed (Sv, Av, Hv,
235 ...). The leading prefix is only left in cases where its removal would
236 cause a clash in method name. For example, "GvREFCNT" stays as-is since
237 its abbreviation would clash with the "superclass" method "REFCNT"
238 (corresponding to the C function "SvREFCNT").
239 B::SV Methods
241 REFCNT
243 FLAGS
244 object_2svref
245 Returns a reference to the regular scalar corresponding to this
246 B::SV object. In other words, this method is the inverse operation
247 to the svref_2object() subroutine. This scalar and other data it
248 points at should be considered read-only: modifying them is neither
249 safe nor guaranteed to have a sensible effect.
250 B::IV Methods
252 IV Returns the value of the IV, interpreted as a signed integer. This
254 will be misleading if "FLAGS & SVf_IVisUV". Perhaps you want the
255 "int_value" method instead?
256 IVX
258 UVX
259 int_value
260 This method returns the value of the IV as an integer. It differs
261 from "IV" in that it returns the correct value regardless of
262 whether it's stored signed or unsigned.
263 needs64bits
265 packiv
266 B::NV Methods
268 NV
270 NVX
271 B::RV Methods
273 RV
275 B::PV Methods
277 PV This method is the one you usually want. It constructs a string
279 using the length and offset information in the struct: for ordinary
280 scalars it will return the string that you'd see from Perl, even if
281 it contains null characters.
282 RV Same as B::RV::RV, except that it will die() if the PV isn't a ref‐
284 erence.
285 PVX This method is less often useful. It assumes that the string stored
287 in the struct is null-terminated, and disregards the length infor‐
288 mation.
289 It is the appropriate method to use if you need to get the name of
291 a lexical variable from a padname array. Lexical variable names are
292 always stored with a null terminator, and the length field (SvCUR)
293 is overloaded for other purposes and can't be relied on here.
294 B::PVMG Methods
296 MAGIC
298 SvSTASH
299 B::MAGIC Methods
301 MOREMAGIC
303 precomp
304 Only valid on r-magic, returns the string that generated the reg‐
305 exp.
306 PRIVATE
308 TYPE
309 FLAGS
310 OBJ Will die() if called on r-magic.
311 PTR
313 REGEX
314 Only valid on r-magic, returns the integer value of the REGEX
315 stored in the MAGIC.
316 B::PVLV Methods
318 TARGOFF
320 TARGLEN
321 TYPE
322 TARG
323 B::BM Methods
325 USEFUL
327 PREVIOUS
328 RARE
329 TABLE
330 B::GV Methods
332 is_empty
334 This method returns TRUE if the GP field of the GV is NULL.
335 NAME
337 SAFENAME
338 This method returns the name of the glob, but if the first charac‐
339 ter of the name is a control character, then it converts it to ^X
340 first, so that *^G would return "^G" rather than "\cG".
341 It's useful if you want to print out the name of a variable. If
343 you restrict yourself to globs which exist at compile-time then the
344 result ought to be unambiguous, because code like "${"^G"} = 1" is
345 compiled as two ops - a constant string and a dereference (rv2gv) -
346 so that the glob is created at runtime.
347 If you're working with globs at runtime, and need to disambiguate
349 *^G from *{"^G"}, then you should use the raw NAME method.
350 STASH
352 SV
353 IO
354 FORM
355 AV
356 HV
357 EGV
358 CV
359 CVGEN
360 LINE
361 FILE
362 FILEGV
363 GvREFCNT
364 FLAGS
365 B::IO Methods
367 LINES
369 PAGE
370 PAGE_LEN
371 LINES_LEFT
372 TOP_NAME
373 TOP_GV
374 FMT_NAME
375 FMT_GV
376 BOTTOM_NAME
377 BOTTOM_GV
378 SUBPROCESS
379 IoTYPE
380 IoFLAGS
381 IsSTD
382 Takes one arguments ( 'stdin' ⎪ 'stdout' ⎪ 'stderr' ) and returns
383 true if the IoIFP of the object is equal to the handle whose name
384 was passed as argument ( i.e. $io->IsSTD('stderr') is true if
385 IoIFP($io) == PerlIO_stdin() ).
386 B::AV Methods
388 FILL
390 MAX
391 OFF
392 ARRAY
393 ARRAYelt
394 Like "ARRAY", but takes an index as an argument to get only one
395 element, rather than a list of all of them.
396 AvFLAGS
398 B::CV Methods
400 STASH
402 START
403 ROOT
404 GV
405 FILE
406 DEPTH
407 PADLIST
408 OUTSIDE
409 OUTSIDE_SEQ
410 XSUB
411 XSUBANY
412 For constant subroutines, returns the constant SV returned by the
413 subroutine.
414 CvFLAGS
416 const_sv
417 B::HV Methods
419 FILL
421 MAX
422 KEYS
423 RITER
424 NAME
425 PMROOT
426 ARRAY
427 OP-RELATED CLASSES
429 "B::OP", "B::UNOP", "B::BINOP", "B::LOGOP", "B::LISTOP", "B::PMOP",
431 "B::SVOP", "B::PADOP", "B::PVOP", "B::LOOP", "B::COP".
432 These classes correspond in the obvious way to the underlying C struc‐
434 tures of similar names. The inheritance hierarchy mimics the underlying
435 C "inheritance":
436 B::OP
438 ⎪
439 +---------------+--------+--------+
440 ⎪ ⎪ ⎪ ⎪
441 B::UNOP B::SVOP B::PADOP B::COP
442 ,' `-.
443 / `--.
444 B::BINOP B::LOGOP
445 ⎪
446 ⎪
447 B::LISTOP
448 ,' `.
449 / \
450 B::LOOP B::PMOP
451 Access methods correspond to the underlying C structre field names,
453 with the leading "class indication" prefix ("op_") removed.
454 B::OP Methods
456 These methods get the values of similarly named fields within the OP
458 data structure. See top of "op.h" for more info.
459 next
461 sibling
462 name
463 This returns the op name as a string (e.g. "add", "rv2av").
464 ppaddr
466 This returns the function name as a string (e.g.
467 "PL_ppaddr[OP_ADD]", "PL_ppaddr[OP_RV2AV]").
468 desc
470 This returns the op description from the global C PL_op_desc array
471 (e.g. "addition" "array deref").
472 targ
474 type
475 opt
476 static
477 flags
478 private
479 spare
480 B::UNOP METHOD
482 first
484 B::BINOP METHOD
486 last
488 B::LOGOP METHOD
490 other
492 B::LISTOP METHOD
494 children
496 B::PMOP Methods
498 pmreplroot
500 pmreplstart
501 pmnext
502 pmregexp
503 pmflags
504 pmdynflags
505 pmpermflags
506 precomp
507 pmoffset
508 Only when perl was compiled with ithreads.
509 B::SVOP METHOD
511 sv
513 gv
514 B::PADOP METHOD
516 padix
518 B::PVOP METHOD
520 pv
522 B::LOOP Methods
524 redoop
526 nextop
527 lastop
528 B::COP Methods
530 label
532 stash
533 stashpv
534 file
535 cop_seq
536 arybase
537 line
538 warnings
539 io
540
542 Malcolm Beattie, "mbeattie@sable.ox.ac.uk"
543perl v5.8.8 2001-09-21 B(3pm)