1#      B.pm
2#
3#      Copyright (c) 1996, 1997, 1998 Malcolm Beattie
4#
5#      You may distribute under the terms of either the GNU General Public
6#      License or the Artistic License, as specified in the README file.
7#
8package B;
9
10@B::ISA = qw(Exporter);
11
12# If B is loaded without imports, we do not want to unnecessarily pollute the stash with Exporter.
13sub import {
14    return unless scalar @_ > 1; # Called as a method call.
15    require Exporter;
16    B->export_to_level(1, @_);
17}
18
19# walkoptree_slow comes from B.pm (you are there),
20# walkoptree comes from B.xs
21
22BEGIN {
23    $B::VERSION = '1.76';
24    @B::EXPORT_OK = ();
25
26    # Our BOOT code needs $VERSION set, and will append to @EXPORT_OK.
27    # Want our constants loaded before the compiler meets OPf_KIDS below, as
28    # the combination of having the constant stay a Proxy Constant Subroutine
29    # and its value being inlined saves a little over .5K
30
31    require XSLoader;
32    XSLoader::load();
33}
34
35push @B::EXPORT_OK, (qw(minus_c ppname save_BEGINs
36			class peekop cast_I32 cstring cchar hash threadsv_names
37			main_root main_start main_cv svref_2object opnumber
38			sub_generation amagic_generation perlstring
39			walkoptree_slow walkoptree walkoptree_exec walksymtable
40			parents comppadlist sv_undef compile_stats timing_info
41			begin_av init_av check_av end_av regex_padav dowarn
42			defstash curstash warnhook diehook inc_gv @optype
43			@specialsv_name unitcheck_av safename));
44
45@B::SV::ISA = 'B::OBJECT';
46@B::NULL::ISA = 'B::SV';
47@B::PV::ISA = 'B::SV';
48@B::IV::ISA = 'B::SV';
49@B::NV::ISA = 'B::SV';
50# RV is eliminated with 5.11.0, but effectively is a specialisation of IV now.
51@B::RV::ISA = 'B::IV';
52@B::PVIV::ISA = qw(B::PV B::IV);
53@B::PVNV::ISA = qw(B::PVIV B::NV);
54@B::PVMG::ISA = 'B::PVNV';
55@B::REGEXP::ISA = 'B::PVMG';
56@B::INVLIST::ISA = 'B::PV';
57@B::PVLV::ISA = 'B::GV';
58@B::BM::ISA = 'B::GV';
59@B::AV::ISA = 'B::PVMG';
60@B::GV::ISA = 'B::PVMG';
61@B::HV::ISA = 'B::PVMG';
62@B::CV::ISA = 'B::PVMG';
63@B::IO::ISA = 'B::PVMG';
64@B::FM::ISA = 'B::CV';
65
66@B::OP::ISA = 'B::OBJECT';
67@B::UNOP::ISA = 'B::OP';
68@B::UNOP_AUX::ISA = 'B::UNOP';
69@B::BINOP::ISA = 'B::UNOP';
70@B::LOGOP::ISA = 'B::UNOP';
71@B::LISTOP::ISA = 'B::BINOP';
72@B::SVOP::ISA = 'B::OP';
73@B::PADOP::ISA = 'B::OP';
74@B::PVOP::ISA = 'B::OP';
75@B::LOOP::ISA = 'B::LISTOP';
76@B::PMOP::ISA = 'B::LISTOP';
77@B::COP::ISA = 'B::OP';
78@B::METHOP::ISA = 'B::OP';
79
80@B::SPECIAL::ISA = 'B::OBJECT';
81
82our @optype = qw(OP UNOP BINOP LOGOP LISTOP PMOP SVOP PADOP PVOP LOOP COP
83                METHOP UNOP_AUX);
84# bytecode.pl contained the following comment:
85# Nullsv *must* come first in the following so that the condition
86# ($$sv == 0) can continue to be used to test (sv == Nullsv).
87our @specialsv_name = qw(Nullsv &PL_sv_undef &PL_sv_yes &PL_sv_no
88			(SV*)pWARN_ALL (SV*)pWARN_NONE (SV*)pWARN_STD
89                        &PL_sv_zero);
90
91{
92    # Stop "-w" from complaining about the lack of a real B::OBJECT class
93    package B::OBJECT;
94}
95
96sub B::GV::SAFENAME {
97  safename(shift()->NAME);
98}
99
100sub safename {
101  my $name = shift;
102
103  # The regex below corresponds to the isCONTROLVAR macro
104  # from toke.c
105
106  $name =~ s/^\c?/^?/
107    or $name =~ s/^([\cA-\cZ\c\\c[\c]\c_\c^])/
108                "^" .  chr( utf8::unicode_to_native( 64 ^ ord($1) ))/e;
109
110  # When we say unicode_to_native we really mean ascii_to_native,
111  # which matters iff this is a non-ASCII platform (EBCDIC).  '\c?' would
112  # not have to be special cased, except for non-ASCII.
113
114  return $name;
115}
116
117sub B::IV::int_value {
118  my ($self) = @_;
119  return (($self->FLAGS() & SVf_IVisUV()) ? $self->UVX : $self->IV);
120}
121
122sub B::NULL::as_string() {""}
123*B::IV::as_string = *B::IV::as_string = \*B::IV::int_value;
124*B::PV::as_string = *B::PV::as_string = \*B::PV::PV;
125
126#  The input typemap checking makes no distinction between different SV types,
127#  so the XS body will generate the same C code, despite the different XS
128#  "types". So there is no change in behaviour from doing "newXS" like this,
129#  compared with the old approach of having a (near) duplicate XS body.
130#  We should fix the typemap checking.
131
132#  Since perl 5.12.0
133*B::IV::RV = *B::IV::RV = \*B::PV::RV;
134
135my $debug;
136my $op_count = 0;
137my @parents = ();
138
139sub debug {
140    my ($class, $value) = @_;
141    $debug = $value;
142    walkoptree_debug($value);
143}
144
145sub class {
146    my $obj = shift;
147    my $name = ref $obj;
148    $name =~ s/^.*:://;
149    return $name;
150}
151
152sub parents { \@parents }
153
154# For debugging
155sub peekop {
156    my $op = shift;
157    return sprintf("%s (0x%x) %s", class($op), $$op, $op->name);
158}
159
160sub walkoptree_slow {
161    my($op, $method, $level) = @_;
162    $op_count++; # just for statistics
163    $level ||= 0;
164    warn(sprintf("walkoptree: %d. %s\n", $level, peekop($op))) if $debug;
165    $op->$method($level) if $op->can($method);
166    if ($$op && ($op->flags & OPf_KIDS)) {
167	my $kid;
168	unshift(@parents, $op);
169	for ($kid = $op->first; $$kid; $kid = $kid->sibling) {
170	    walkoptree_slow($kid, $method, $level + 1);
171	}
172	shift @parents;
173    }
174    if (class($op) eq 'PMOP'
175	&& ref($op->pmreplroot)
176	&& ${$op->pmreplroot}
177	&& $op->pmreplroot->isa( 'B::OP' ))
178    {
179	unshift(@parents, $op);
180	walkoptree_slow($op->pmreplroot, $method, $level + 1);
181	shift @parents;
182    }
183}
184
185sub compile_stats {
186    return "Total number of OPs processed: $op_count\n";
187}
188
189sub timing_info {
190    my ($sec, $min, $hr) = localtime;
191    my ($user, $sys) = times;
192    sprintf("%02d:%02d:%02d user=$user sys=$sys",
193	    $hr, $min, $sec, $user, $sys);
194}
195
196my %symtable;
197
198sub clearsym {
199    %symtable = ();
200}
201
202sub savesym {
203    my ($obj, $value) = @_;
204#    warn(sprintf("savesym: sym_%x => %s\n", $$obj, $value)); # debug
205    $symtable{sprintf("sym_%x", $$obj)} = $value;
206}
207
208sub objsym {
209    my $obj = shift;
210    return $symtable{sprintf("sym_%x", $$obj)};
211}
212
213sub walkoptree_exec {
214    my ($op, $method, $level) = @_;
215    $level ||= 0;
216    my ($sym, $ppname);
217    my $prefix = "    " x $level;
218    for (; $$op; $op = $op->next) {
219	$sym = objsym($op);
220	if (defined($sym)) {
221	    print $prefix, "goto $sym\n";
222	    return;
223	}
224	savesym($op, sprintf("%s (0x%lx)", class($op), $$op));
225	$op->$method($level);
226	$ppname = $op->name;
227	if ($ppname =~
228	    /^(d?or(assign)?|and(assign)?|mapwhile|grepwhile|entertry|range|cond_expr)$/)
229	{
230	    print $prefix, uc($1), " => {\n";
231	    walkoptree_exec($op->other, $method, $level + 1);
232	    print $prefix, "}\n";
233	} elsif ($ppname eq "match" || $ppname eq "subst") {
234	    my $pmreplstart = $op->pmreplstart;
235	    if ($$pmreplstart) {
236		print $prefix, "PMREPLSTART => {\n";
237		walkoptree_exec($pmreplstart, $method, $level + 1);
238		print $prefix, "}\n";
239	    }
240	} elsif ($ppname eq "substcont") {
241	    print $prefix, "SUBSTCONT => {\n";
242	    walkoptree_exec($op->other->pmreplstart, $method, $level + 1);
243	    print $prefix, "}\n";
244	    $op = $op->other;
245	} elsif ($ppname eq "enterloop") {
246	    print $prefix, "REDO => {\n";
247	    walkoptree_exec($op->redoop, $method, $level + 1);
248	    print $prefix, "}\n", $prefix, "NEXT => {\n";
249	    walkoptree_exec($op->nextop, $method, $level + 1);
250	    print $prefix, "}\n", $prefix, "LAST => {\n";
251	    walkoptree_exec($op->lastop,  $method, $level + 1);
252	    print $prefix, "}\n";
253	} elsif ($ppname eq "subst") {
254	    my $replstart = $op->pmreplstart;
255	    if ($$replstart) {
256		print $prefix, "SUBST => {\n";
257		walkoptree_exec($replstart, $method, $level + 1);
258		print $prefix, "}\n";
259	    }
260	}
261    }
262}
263
264sub walksymtable {
265    my ($symref, $method, $recurse, $prefix) = @_;
266    my $sym;
267    my $fullname;
268    no strict 'refs';
269    $prefix = '' unless defined $prefix;
270    foreach my $sym ( sort keys %$symref ) {
271        my $dummy = $symref->{$sym}; # Copying the glob and incrementing
272                                     # the GPs refcnt clears cached methods
273        $fullname = "*main::".$prefix.$sym;
274	if ($sym =~ /::$/) {
275	    $sym = $prefix . $sym;
276	    if (svref_2object(\*$sym)->NAME ne "main::" && $sym ne "<none>::" && &$recurse($sym)) {
277               walksymtable(\%$fullname, $method, $recurse, $sym);
278	    }
279	} else {
280           svref_2object(\*$fullname)->$method();
281	}
282    }
283}
284
2851;
286
287__END__
288
289=head1 NAME
290
291B - The Perl Compiler Backend
292
293=head1 SYNOPSIS
294
295	use B;
296
297=head1 DESCRIPTION
298
299The C<B> module supplies classes which allow a Perl program to delve
300into its own innards.  It is the module used to implement the
301"backends" of the Perl compiler.  Usage of the compiler does not
302require knowledge of this module: see the F<O> module for the
303user-visible part.  The C<B> module is of use to those who want to
304write new compiler backends.  This documentation assumes that the
305reader knows a fair amount about perl's internals including such
306things as SVs, OPs and the internal symbol table and syntax tree
307of a program.
308
309=head1 OVERVIEW
310
311The C<B> module contains a set of utility functions for querying the
312current state of the Perl interpreter; typically these functions
313return objects from the B::SV and B::OP classes, or their derived
314classes.  These classes in turn define methods for querying the
315resulting objects about their own internal state.
316
317=head1 Utility Functions
318
319The C<B> module exports a variety of functions: some are simple
320utility functions, others provide a Perl program with a way to
321get an initial "handle" on an internal object.
322
323=head2 Functions Returning C<B::SV>, C<B::AV>, C<B::HV>, and C<B::CV> objects
324
325For descriptions of the class hierarchy of these objects and the
326methods that can be called on them, see below, L<"OVERVIEW OF
327CLASSES"> and L<"SV-RELATED CLASSES">.
328
329=over 4
330
331=item sv_undef
332
333Returns the SV object corresponding to the C variable C<sv_undef>.
334
335=item sv_yes
336
337Returns the SV object corresponding to the C variable C<sv_yes>.
338
339=item sv_no
340
341Returns the SV object corresponding to the C variable C<sv_no>.
342
343=item svref_2object(SVREF)
344
345Takes a reference to any Perl value, and turns the referred-to value
346into an object in the appropriate B::OP-derived or B::SV-derived
347class.  Apart from functions such as C<main_root>, this is the primary
348way to get an initial "handle" on an internal perl data structure
349which can then be followed with the other access methods.
350
351The returned object will only be valid as long as the underlying OPs
352and SVs continue to exist.  Do not attempt to use the object after the
353underlying structures are freed.
354
355=item amagic_generation
356
357Returns the SV object corresponding to the C variable C<amagic_generation>.
358As of Perl 5.18, this is just an alias to C<PL_na>, so its value is
359meaningless.
360
361=item init_av
362
363Returns the AV object (i.e. in class B::AV) representing INIT blocks.
364
365=item check_av
366
367Returns the AV object (i.e. in class B::AV) representing CHECK blocks.
368
369=item unitcheck_av
370
371Returns the AV object (i.e. in class B::AV) representing UNITCHECK blocks.
372
373=item begin_av
374
375Returns the AV object (i.e. in class B::AV) representing BEGIN blocks.
376
377=item end_av
378
379Returns the AV object (i.e. in class B::AV) representing END blocks.
380
381=item comppadlist
382
383Returns the PADLIST object (i.e. in class B::PADLIST) of the global
384comppadlist.  In Perl 5.16 and earlier it returns an AV object (class
385B::AV).
386
387=item regex_padav
388
389Only when perl was compiled with ithreads.
390
391=item main_cv
392
393Return the (faked) CV corresponding to the main part of the Perl
394program.
395
396=back
397
398=head2 Functions for Examining the Symbol Table
399
400=over 4
401
402=item walksymtable(SYMREF, METHOD, RECURSE, PREFIX)
403
404Walk the symbol table starting at SYMREF and call METHOD on each
405symbol (a B::GV object) visited.  When the walk reaches package
406symbols (such as "Foo::") it invokes RECURSE, passing in the symbol
407name, and only recurses into the package if that sub returns true.
408
409PREFIX is the name of the SYMREF you're walking.
410
411For example:
412
413  # Walk CGI's symbol table calling print_subs on each symbol.
414  # Recurse only into CGI::Util::
415  walksymtable(\%CGI::, 'print_subs',
416               sub { $_[0] eq 'CGI::Util::' }, 'CGI::');
417
418print_subs() is a B::GV method you have declared.  Also see L<"B::GV
419Methods">, below.
420
421=back
422
423=head2 Functions Returning C<B::OP> objects or for walking op trees
424
425For descriptions of the class hierarchy of these objects and the
426methods that can be called on them, see below, L<"OVERVIEW OF
427CLASSES"> and L<"OP-RELATED CLASSES">.
428
429=over 4
430
431=item main_root
432
433Returns the root op (i.e. an object in the appropriate B::OP-derived
434class) of the main part of the Perl program.
435
436=item main_start
437
438Returns the starting op of the main part of the Perl program.
439
440=item walkoptree(OP, METHOD)
441
442Does a tree-walk of the syntax tree based at OP and calls METHOD on
443each op it visits.  Each node is visited before its children.  If
444C<walkoptree_debug> (see below) has been called to turn debugging on then
445the method C<walkoptree_debug> is called on each op before METHOD is
446called.
447
448=item walkoptree_debug(DEBUG)
449
450Returns the current debugging flag for C<walkoptree>.  If the optional
451DEBUG argument is non-zero, it sets the debugging flag to that.  See
452the description of C<walkoptree> above for what the debugging flag
453does.
454
455=back
456
457=head2 Miscellaneous Utility Functions
458
459=over 4
460
461=item ppname(OPNUM)
462
463Return the PP function name (e.g. "pp_add") of op number OPNUM.
464
465=item hash(STR)
466
467Returns a string in the form "0x..." representing the value of the
468internal hash function used by perl on string STR.
469
470=item cast_I32(I)
471
472Casts I to the internal I32 type used by that perl.
473
474=item minus_c
475
476Does the equivalent of the C<-c> command-line option.  Obviously, this
477is only useful in a BEGIN block or else the flag is set too late.
478
479=item cstring(STR)
480
481Returns a double-quote-surrounded escaped version of STR which can
482be used as a string in C source code.
483
484=item perlstring(STR)
485
486Returns a double-quote-surrounded escaped version of STR which can
487be used as a string in Perl source code.
488
489=item safename(STR)
490
491This function returns the string with the first character modified if it
492is a control character.  It converts it to ^X format first, so that "\cG"
493becomes "^G".  This is used internally by L<B::GV::SAFENAME|/SAFENAME>, but
494you can call it directly.
495
496=item class(OBJ)
497
498Returns the class of an object without the part of the classname
499preceding the first C<"::">.  This is used to turn C<"B::UNOP"> into
500C<"UNOP"> for example.
501
502=item threadsv_names
503
504This used to provide support for the old 5.005 threading module. It now
505does nothing.
506
507=back
508
509=head2 Exported utility variables
510
511=over 4
512
513=item @optype
514
515  my $op_type = $optype[$op_type_num];
516
517A simple mapping of the op type number to its type (like 'COP' or 'BINOP').
518
519=item @specialsv_name
520
521  my $sv_name = $specialsv_name[$sv_index];
522
523Certain SV types are considered 'special'.  They're represented by
524B::SPECIAL and are referred to by a number from the specialsv_list.
525This array maps that number back to the name of the SV (like 'Nullsv'
526or '&PL_sv_undef').
527
528=back
529
530
531=head1 OVERVIEW OF CLASSES
532
533The C structures used by Perl's internals to hold SV and OP
534information (PVIV, AV, HV, ..., OP, SVOP, UNOP, ...) are modelled on a
535class hierarchy and the C<B> module gives access to them via a true
536object hierarchy.  Structure fields which point to other objects
537(whether types of SV or types of OP) are represented by the C<B>
538module as Perl objects of the appropriate class.
539
540The bulk of the C<B> module is the methods for accessing fields of
541these structures.
542
543Note that all access is read-only.  You cannot modify the internals by
544using this module.  Also, note that the B::OP and B::SV objects created
545by this module are only valid for as long as the underlying objects
546exist; their creation doesn't increase the reference counts of the
547underlying objects.  Trying to access the fields of a freed object will
548give incomprehensible results, or worse.
549
550=head2 SV-RELATED CLASSES
551
552B::IV, B::NV, B::PV, B::PVIV, B::PVNV, B::PVMG,
553B::PVLV, B::AV, B::HV, B::CV, B::GV, B::FM, B::IO.  These classes
554correspond in the obvious way to the underlying C structures of similar names.
555The inheritance hierarchy mimics the underlying C "inheritance":
556
557                           B::SV
558                             |
559                +------------+------------+
560                |            |            |
561              B::PV        B::IV        B::NV
562                  \         /           /
563                   \       /           /
564                    B::PVIV           /
565                         \           /
566                          \         /
567                           \       /
568                            B::PVNV
569                               |
570                               |
571                            B::PVMG
572                               |
573           +-------+-------+---+---+-------+-------+
574           |       |       |       |       |       |
575         B::AV   B::GV   B::HV   B::CV   B::IO B::REGEXP
576                   |               |
577                   |               |
578                B::PVLV          B::FM
579
580
581Access methods correspond to the underlying C macros for field access,
582usually with the leading "class indication" prefix removed (Sv, Av,
583Hv, ...).  The leading prefix is only left in cases where its removal
584would cause a clash in method name.  For example, C<GvREFCNT> stays
585as-is since its abbreviation would clash with the "superclass" method
586C<REFCNT> (corresponding to the C function C<SvREFCNT>).
587
588=head2 B::SV Methods
589
590=over 4
591
592=item REFCNT
593
594=item FLAGS
595
596=item object_2svref
597
598Returns a reference to the regular scalar corresponding to this
599B::SV object.  In other words, this method is the inverse operation
600to the svref_2object() subroutine.  This scalar and other data it points
601at should be considered read-only: modifying them is neither safe nor
602guaranteed to have a sensible effect.
603
604=back
605
606=head2 B::IV Methods
607
608=over 4
609
610=item IV
611
612Returns the value of the IV, I<interpreted as
613a signed integer>.  This will be misleading
614if C<FLAGS & SVf_IVisUV>.  Perhaps you want the
615C<int_value> method instead?
616
617=item IVX
618
619=item UVX
620
621=item int_value
622
623This method returns the value of the IV as an integer.
624It differs from C<IV> in that it returns the correct
625value regardless of whether it's stored signed or
626unsigned.
627
628=item needs64bits
629
630=item packiv
631
632=back
633
634=head2 B::NV Methods
635
636=over 4
637
638=item NV
639
640=item NVX
641
642=item COP_SEQ_RANGE_LOW
643
644=item COP_SEQ_RANGE_HIGH
645
646These last two are only valid for pad name SVs.  They only existed in the
647B::NV class before Perl 5.22.  In 5.22 they were moved to the B::PADNAME
648class.
649
650=back
651
652=head2 B::RV Methods
653
654=over 4
655
656=item RV
657
658=back
659
660=head2 B::PV Methods
661
662=over 4
663
664=item PV
665
666This method is the one you usually want.  It constructs a
667string using the length and offset information in the struct:
668for ordinary scalars it will return the string that you'd see
669from Perl, even if it contains null characters.
670
671=item RV
672
673Same as B::RV::RV, except that it will die() if the PV isn't
674a reference.
675
676=item PVX
677
678This method is less often useful.  It assumes that the string
679stored in the struct is null-terminated, and disregards the
680length information.
681
682It is the appropriate method to use if you need to get the name
683of a lexical variable from a padname array.  Lexical variable names
684are always stored with a null terminator, and the length field
685(CUR) is overloaded for other purposes and can't be relied on here.
686
687=item CUR
688
689This method returns the internal length field, which consists of the number
690of internal bytes, not necessarily the number of logical characters.
691
692=item LEN
693
694This method returns the number of bytes allocated (via malloc) for storing
695the string.  This is 0 if the scalar does not "own" the string.
696
697=back
698
699=head2 B::PVMG Methods
700
701=over 4
702
703=item MAGIC
704
705=item SvSTASH
706
707=back
708
709=head2 B::MAGIC Methods
710
711=over 4
712
713=item MOREMAGIC
714
715=item precomp
716
717Only valid on r-magic, returns the string that generated the regexp.
718
719=item PRIVATE
720
721=item TYPE
722
723=item FLAGS
724
725=item OBJ
726
727Will die() if called on r-magic.
728
729=item PTR
730
731=item REGEX
732
733Only valid on r-magic, returns the integer value of the REGEX stored
734in the MAGIC.
735
736=back
737
738=head2 B::PVLV Methods
739
740=over 4
741
742=item TARGOFF
743
744=item TARGLEN
745
746=item TYPE
747
748=item TARG
749
750=back
751
752=head2 B::BM Methods
753
754=over 4
755
756=item USEFUL
757
758=item PREVIOUS
759
760=item RARE
761
762=item TABLE
763
764=back
765
766=head2 B::REGEXP Methods
767
768=over 4
769
770=item REGEX
771
772=item precomp
773
774=item qr_anoncv
775
776=item compflags
777
778The last two were added in Perl 5.22.
779
780=back
781
782=head2 B::GV Methods
783
784=over 4
785
786=item is_empty
787
788This method returns TRUE if the GP field of the GV is NULL.
789
790=item NAME
791
792=item SAFENAME
793
794This method returns the name of the glob, but if the first
795character of the name is a control character, then it converts
796it to ^X first, so that *^G would return "^G" rather than "\cG".
797
798It's useful if you want to print out the name of a variable.
799If you restrict yourself to globs which exist at compile-time
800then the result ought to be unambiguous, because code like
801C<${"^G"} = 1> is compiled as two ops - a constant string and
802a dereference (rv2gv) - so that the glob is created at runtime.
803
804If you're working with globs at runtime, and need to disambiguate
805*^G from *{"^G"}, then you should use the raw NAME method.
806
807=item STASH
808
809=item SV
810
811=item IO
812
813=item FORM
814
815=item AV
816
817=item HV
818
819=item EGV
820
821=item CV
822
823=item CVGEN
824
825=item LINE
826
827=item FILE
828
829=item FILEGV
830
831=item GvREFCNT
832
833=item FLAGS
834
835=item GPFLAGS
836
837This last one is present only in perl 5.22.0 and higher.
838
839=back
840
841=head2 B::IO Methods
842
843B::IO objects derive from IO objects and you will get more information from
844the IO object itself.
845
846For example:
847
848  $gvio = B::svref_2object(\*main::stdin)->IO;
849  $IO = $gvio->object_2svref();
850  $fd = $IO->fileno();
851
852=over 4
853
854=item LINES
855
856=item PAGE
857
858=item PAGE_LEN
859
860=item LINES_LEFT
861
862=item TOP_NAME
863
864=item TOP_GV
865
866=item FMT_NAME
867
868=item FMT_GV
869
870=item BOTTOM_NAME
871
872=item BOTTOM_GV
873
874=item SUBPROCESS
875
876=item IoTYPE
877
878A character symbolizing the type of IO Handle.
879
880  -     STDIN/OUT
881  I     STDIN/OUT/ERR
882  <     read-only
883  >     write-only
884  a     append
885  +     read and write
886  s     socket
887  |     pipe
888  I     IMPLICIT
889  #     NUMERIC
890  space closed handle
891  \0    closed internal handle
892
893=item IoFLAGS
894
895=item IsSTD
896
897Takes one argument ( 'stdin' | 'stdout' | 'stderr' ) and returns true
898if the IoIFP of the object is equal to the handle whose name was
899passed as argument; i.e., $io->IsSTD('stderr') is true if
900IoIFP($io) == PerlIO_stderr().
901
902=back
903
904=head2 B::AV Methods
905
906=over 4
907
908=item FILL
909
910=item MAX
911
912=item ARRAY
913
914=item ARRAYelt
915
916Like C<ARRAY>, but takes an index as an argument to get only one element,
917rather than a list of all of them.
918
919=back
920
921=head2 B::CV Methods
922
923=over 4
924
925=item STASH
926
927=item START
928
929=item ROOT
930
931=item GV
932
933=item FILE
934
935=item DEPTH
936
937=item PADLIST
938
939Returns a B::PADLIST object.
940
941=item OUTSIDE
942
943=item OUTSIDE_SEQ
944
945=item XSUB
946
947=item XSUBANY
948
949For constant subroutines, returns the constant SV returned by the subroutine.
950
951=item CvFLAGS
952
953=item const_sv
954
955=item NAME_HEK
956
957Returns the name of a lexical sub, otherwise C<undef>.
958
959=back
960
961=head2 B::HV Methods
962
963=over 4
964
965=item FILL
966
967=item MAX
968
969=item KEYS
970
971=item RITER
972
973=item NAME
974
975=item ARRAY
976
977=back
978
979=head2 OP-RELATED CLASSES
980
981C<B::OP>, C<B::UNOP>, C<B::UNOP_AUX>, C<B::BINOP>, C<B::LOGOP>,
982C<B::LISTOP>, C<B::PMOP>, C<B::SVOP>, C<B::PADOP>, C<B::PVOP>, C<B::LOOP>,
983C<B::COP>, C<B::METHOP>.
984
985These classes correspond in the obvious way to the underlying C
986structures of similar names.  The inheritance hierarchy mimics the
987underlying C "inheritance":
988
989                                 B::OP
990                                   |
991                   +----------+---------+--------+-------+---------+
992                   |          |         |        |       |         |
993                B::UNOP    B::SVOP  B::PADOP  B::COP  B::PVOP  B::METHOP
994                   |
995               +---+---+---------+
996               |       |         |
997           B::BINOP  B::LOGOP  B::UNOP_AUX
998               |
999               |
1000           B::LISTOP
1001               |
1002           +---+---+
1003           |       |
1004        B::LOOP   B::PMOP
1005
1006Access methods correspond to the underlying C structure field names,
1007with the leading "class indication" prefix (C<"op_">) removed.
1008
1009=head2 B::OP Methods
1010
1011These methods get the values of similarly named fields within the OP
1012data structure.  See top of C<op.h> for more info.
1013
1014=over 4
1015
1016=item next
1017
1018=item sibling
1019
1020=item parent
1021
1022Returns the OP's parent. If it has no parent, or if your perl wasn't built
1023with C<-DPERL_OP_PARENT>, returns NULL.
1024
1025Note that the global variable C<$B::OP::does_parent> is undefined on older
1026perls that don't support the C<parent> method, is defined but false on
1027perls that support the method but were built without  C<-DPERL_OP_PARENT>,
1028and is true otherwise.
1029
1030=item name
1031
1032This returns the op name as a string (e.g. "add", "rv2av").
1033
1034=item ppaddr
1035
1036This returns the function name as a string (e.g. "PL_ppaddr[OP_ADD]",
1037"PL_ppaddr[OP_RV2AV]").
1038
1039=item desc
1040
1041This returns the op description from the global C PL_op_desc array
1042(e.g. "addition" "array deref").
1043
1044=item targ
1045
1046=item type
1047
1048=item opt
1049
1050=item flags
1051
1052=item private
1053
1054=item spare
1055
1056=back
1057
1058=head2 B::UNOP Method
1059
1060=over 4
1061
1062=item first
1063
1064=back
1065
1066=head2 B::UNOP_AUX Methods (since 5.22)
1067
1068=over 4
1069
1070=item aux_list(cv)
1071
1072This returns a list of the elements of the op's aux data structure,
1073or a null list if there is no aux. What will be returned depends on the
1074object's type, but will typically be a collection of C<B::IV>, C<B::GV>,
1075etc. objects. C<cv> is the C<B::CV> object representing the sub that the
1076op is contained within.
1077
1078=item string(cv)
1079
1080This returns a textual representation of the object (likely to b useful
1081for deparsing and debugging), or an empty string if the op type doesn't
1082support this. C<cv> is the C<B::CV> object representing the sub that the
1083op is contained within.
1084
1085=back
1086
1087=head2 B::BINOP Method
1088
1089=over 4
1090
1091=item last
1092
1093=back
1094
1095=head2 B::LOGOP Method
1096
1097=over 4
1098
1099=item other
1100
1101=back
1102
1103=head2 B::LISTOP Method
1104
1105=over 4
1106
1107=item children
1108
1109=back
1110
1111=head2 B::PMOP Methods
1112
1113=over 4
1114
1115=item pmreplroot
1116
1117=item pmreplstart
1118
1119=item pmflags
1120
1121=item precomp
1122
1123=item pmoffset
1124
1125Only when perl was compiled with ithreads.
1126
1127=item code_list
1128
1129Since perl 5.17.1
1130
1131=item pmregexp
1132
1133Added in perl 5.22, this method returns the B::REGEXP associated with the
1134op.  While PMOPs do not actually have C<pmregexp> fields under threaded
1135builds, this method returns the regexp under threads nonetheless, for
1136convenience.
1137
1138=back
1139
1140=head2 B::SVOP Methods
1141
1142=over 4
1143
1144=item sv
1145
1146=item gv
1147
1148=back
1149
1150=head2 B::PADOP Method
1151
1152=over 4
1153
1154=item padix
1155
1156=back
1157
1158=head2 B::PVOP Method
1159
1160=over 4
1161
1162=item pv
1163
1164=back
1165
1166=head2 B::LOOP Methods
1167
1168=over 4
1169
1170=item redoop
1171
1172=item nextop
1173
1174=item lastop
1175
1176=back
1177
1178=head2 B::COP Methods
1179
1180The C<B::COP> class is used for "nextstate" and "dbstate" ops.  As of Perl
11815.22, it is also used for "null" ops that started out as COPs.
1182
1183=over 4
1184
1185=item label
1186
1187=item stash
1188
1189=item stashpv
1190
1191=item stashoff (threaded only)
1192
1193=item file
1194
1195=item cop_seq
1196
1197=item line
1198
1199=item warnings
1200
1201=item io
1202
1203=item hints
1204
1205=item hints_hash
1206
1207=back
1208
1209=head2 B::METHOP Methods (Since Perl 5.22)
1210
1211=over 4
1212
1213=item first
1214
1215=item meth_sv
1216
1217=back
1218
1219=head2 PAD-RELATED CLASSES
1220
1221Perl 5.18 introduced a new class, B::PADLIST, returned by B::CV's
1222C<PADLIST> method.
1223
1224Perl 5.22 introduced the B::PADNAMELIST and B::PADNAME classes.
1225
1226=head2 B::PADLIST Methods
1227
1228=over 4
1229
1230=item MAX
1231
1232=item ARRAY
1233
1234A list of pads.  The first one is a B::PADNAMELIST containing the names.
1235The rest are currently B::AV objects, but that could
1236change in future versions.
1237
1238=item ARRAYelt
1239
1240Like C<ARRAY>, but takes an index as an argument to get only one element,
1241rather than a list of all of them.
1242
1243=item NAMES
1244
1245This method, introduced in 5.22, returns the B::PADNAMELIST.  It is
1246equivalent to C<ARRAYelt> with a 0 argument.
1247
1248=item REFCNT
1249
1250=item id
1251
1252This method, introduced in 5.22, returns an ID shared by clones of the same
1253padlist.
1254
1255=item outid
1256
1257This method, also added in 5.22, returns the ID of the outer padlist.
1258
1259=back
1260
1261=head2 B::PADNAMELIST Methods
1262
1263=over 4
1264
1265=item MAX
1266
1267=item ARRAY
1268
1269=item ARRAYelt
1270
1271These two methods return the pad names, using B::SPECIAL objects for null
1272pointers and B::PADNAME objects otherwise.
1273
1274=item REFCNT
1275
1276=back
1277
1278=head2 B::PADNAME Methods
1279
1280=over 4
1281
1282=item PV
1283
1284=item PVX
1285
1286=item LEN
1287
1288=item REFCNT
1289
1290=item FLAGS
1291
1292For backward-compatibility, if the PADNAMEt_OUTER flag is set, the FLAGS
1293method adds the SVf_FAKE flag, too.
1294
1295=item TYPE
1296
1297A B::HV object representing the stash for a typed lexical.
1298
1299=item SvSTASH
1300
1301A backward-compatibility alias for TYPE.
1302
1303=item OURSTASH
1304
1305A B::HV object representing the stash for 'our' variables.
1306
1307=item PROTOCV
1308
1309The prototype CV for a 'my' sub.
1310
1311=item COP_SEQ_RANGE_LOW
1312
1313=item COP_SEQ_RANGE_HIGH
1314
1315Sequence numbers representing the scope within which a lexical is visible.
1316Meaningless if PADNAMEt_OUTER is set.
1317
1318=item PARENT_PAD_INDEX
1319
1320Only meaningful if PADNAMEt_OUTER is set.
1321
1322=item PARENT_FAKELEX_FLAGS
1323
1324Only meaningful if PADNAMEt_OUTER is set.
1325
1326=back
1327
1328=head2 $B::overlay
1329
1330Although the optree is read-only, there is an overlay facility that allows
1331you to override what values the various B::*OP methods return for a
1332particular op. C<$B::overlay> should be set to reference a two-deep hash:
1333indexed by OP address, then method name. Whenever a an op method is
1334called, the value in the hash is returned if it exists. This facility is
1335used by B::Deparse to "undo" some optimisations. For example:
1336
1337
1338    local $B::overlay = {};
1339    ...
1340    if ($op->name eq "foo") {
1341        $B::overlay->{$$op} = {
1342                name => 'bar',
1343                next => $op->next->next,
1344        };
1345    }
1346    ...
1347    $op->name # returns "bar"
1348    $op->next # returns the next op but one
1349
1350
1351=head1 AUTHOR
1352
1353Malcolm Beattie, C<mbeattie@sable.ox.ac.uk>
1354
1355=cut
1356