perlhack.pod

MSYS在windows下模拟了一个类unix的终端

     SETi(-TOPi);

Just set the integer value of the top stack entry to its negation.

Argument stack manipulation in the core is exactly the same as it is in
XSUBs - see L<perlxstut>, L<perlxs> and L<perlguts> for a longer
description of the macros used in stack manipulation.

=item Mark stack

I say `your portion of the stack' above because PP code doesn't
necessarily get the whole stack to itself: if your function calls
another function, you'll only want to expose the arguments aimed for the
called function, and not (necessarily) let it get at your own data. The
way we do this is to have a `virtual' bottom-of-stack, exposed to each
function. The mark stack keeps bookmarks to locations in the argument
stack usable by each function. For instance, when dealing with a tied
variable, (internally, something with `P' magic) Perl has to call
methods for accesses to the tied variables. However, we need to separate
the arguments exposed to the method to the argument exposed to the
original function - the store or fetch or whatever it may be. Here's how
the tied C<push> is implemented; see C<av_push> in F<av.c>:

     1	PUSHMARK(SP);
     2	EXTEND(SP,2);
     3	PUSHs(SvTIED_obj((SV*)av, mg));
     4	PUSHs(val);
     5	PUTBACK;
     6	ENTER;
     7	call_method("PUSH", G_SCALAR|G_DISCARD);
     8	LEAVE;
     9	POPSTACK;

The lines which concern the mark stack are the first, fifth and last
lines: they save away, restore and remove the current position of the
argument stack. 

Let's examine the whole implementation, for practice:

     1	PUSHMARK(SP);

Push the current state of the stack pointer onto the mark stack. This is
so that when we've finished adding items to the argument stack, Perl
knows how many things we've added recently.

     2	EXTEND(SP,2);
     3	PUSHs(SvTIED_obj((SV*)av, mg));
     4	PUSHs(val);

We're going to add two more items onto the argument stack: when you have
a tied array, the C<PUSH> subroutine receives the object and the value
to be pushed, and that's exactly what we have here - the tied object,
retrieved with C<SvTIED_obj>, and the value, the SV C<val>.

     5	PUTBACK;

Next we tell Perl to make the change to the global stack pointer: C<dSP>
only gave us a local copy, not a reference to the global.

     6	ENTER;
     7	call_method("PUSH", G_SCALAR|G_DISCARD);
     8	LEAVE;

C<ENTER> and C<LEAVE> localise a block of code - they make sure that all
variables are tidied up, everything that has been localised gets
its previous value returned, and so on. Think of them as the C<{> and
C<}> of a Perl block.

To actually do the magic method call, we have to call a subroutine in
Perl space: C<call_method> takes care of that, and it's described in
L<perlcall>. We call the C<PUSH> method in scalar context, and we're
going to discard its return value.

     9	POPSTACK;

Finally, we remove the value we placed on the mark stack, since we
don't need it any more.

=item Save stack

C doesn't have a concept of local scope, so perl provides one. We've
seen that C<ENTER> and C<LEAVE> are used as scoping braces; the save
stack implements the C equivalent of, for example:

    {
        local $foo = 42;
        ...
    }

See L<perlguts/Localising Changes> for how to use the save stack.

=back

=head2 Millions of Macros

One thing you'll notice about the Perl source is that it's full of
macros. Some have called the pervasive use of macros the hardest thing
to understand, others find it adds to clarity. Let's take an example,
the code which implements the addition operator:

   1  PP(pp_add)
   2  {
   3      dSP; dATARGET; tryAMAGICbin(add,opASSIGN);
   4      {
   5        dPOPTOPnnrl_ul;
   6        SETn( left + right );
   7        RETURN;
   8      }
   9  }

Every line here (apart from the braces, of course) contains a macro. The
first line sets up the function declaration as Perl expects for PP code;
line 3 sets up variable declarations for the argument stack and the
target, the return value of the operation. Finally, it tries to see if
the addition operation is overloaded; if so, the appropriate subroutine
is called.

Line 5 is another variable declaration - all variable declarations start
with C<d> - which pops from the top of the argument stack two NVs (hence
C<nn>) and puts them into the variables C<right> and C<left>, hence the
C<rl>. These are the two operands to the addition operator. Next, we
call C<SETn> to set the NV of the return value to the result of adding
the two values. This done, we return - the C<RETURN> macro makes sure
that our return value is properly handled, and we pass the next operator
to run back to the main run loop.

Most of these macros are explained in L<perlapi>, and some of the more
important ones are explained in L<perlxs> as well. Pay special attention
to L<perlguts/Background and PERL_IMPLICIT_CONTEXT> for information on
the C<[pad]THX_?> macros.


=head2 Poking at Perl

To really poke around with Perl, you'll probably want to build Perl for
debugging, like this:

    ./Configure -d -D optimize=-g
    make

C<-g> is a flag to the C compiler to have it produce debugging
information which will allow us to step through a running program.
F<Configure> will also turn on the C<DEBUGGING> compilation symbol which
enables all the internal debugging code in Perl. There are a whole bunch
of things you can debug with this: L<perlrun> lists them all, and the
best way to find out about them is to play about with them. The most
useful options are probably

    l  Context (loop) stack processing
    t  Trace execution
    o  Method and overloading resolution
    c  String/numeric conversions

Some of the functionality of the debugging code can be achieved using XS
modules.

    -Dr => use re 'debug'
    -Dx => use O 'Debug'

=head2 Using a source-level debugger

If the debugging output of C<-D> doesn't help you, it's time to step
through perl's execution with a source-level debugger.

=over 3

=item *

We'll use C<gdb> for our examples here; the principles will apply to any
debugger, but check the manual of the one you're using.

=back

To fire up the debugger, type

    gdb ./perl

You'll want to do that in your Perl source tree so the debugger can read
the source code. You should see the copyright message, followed by the
prompt.

    (gdb)

C<help> will get you into the documentation, but here are the most
useful commands:

=over 3

=item run [args]

Run the program with the given arguments.

=item break function_name

=item break source.c:xxx

Tells the debugger that we'll want to pause execution when we reach
either the named function (but see L<perlguts/Internal Functions>!) or the given
line in the named source file.

=item step

Steps through the program a line at a time.

=item next

Steps through the program a line at a time, without descending into
functions.

=item continue

Run until the next breakpoint.

=item finish

Run until the end of the current function, then stop again.

=item 'enter'

Just pressing Enter will do the most recent operation again - it's a
blessing when stepping through miles of source code.

=item print

Execute the given C code and print its results. B<WARNING>: Perl makes
heavy use of macros, and F<gdb> is not aware of macros. You'll have to
substitute them yourself. So, for instance, you can't say

    print SvPV_nolen(sv)

but you have to say

    print Perl_sv_2pv_nolen(sv)

You may find it helpful to have a "macro dictionary", which you can
produce by saying C<cpp -dM perl.c | sort>. Even then, F<cpp> won't
recursively apply the macros for you. 

=back

=head2 Dumping Perl Data Structures

One way to get around this macro hell is to use the dumping functions in
F<dump.c>; these work a little like an internal
L<Devel::Peek|Devel::Peek>, but they also cover OPs and other structures
that you can't get at from Perl. Let's take an example. We'll use the
C<$a = $b + $c> we used before, but give it a bit of context: 
C<$b = "6XXXX"; $c = 2.3;>. Where's a good place to stop and poke around?

What about C<pp_add>, the function we examined earlier to implement the
C<+> operator:

    (gdb) break Perl_pp_add
    Breakpoint 1 at 0x46249f: file pp_hot.c, line 309.

Notice we use C<Perl_pp_add> and not C<pp_add> - see L<perlguts/Internal Functions>.
With the breakpoint in place, we can run our program:

    (gdb) run -e '$b = "6XXXX"; $c = 2.3; $a = $b + $c'

Lots of junk will go past as gdb reads in the relevant source files and
libraries, and then:

    Breakpoint 1, Perl_pp_add () at pp_hot.c:309
    309         dSP; dATARGET; tryAMAGICbin(add,opASSIGN);
    (gdb) step
    311           dPOPTOPnnrl_ul;
    (gdb)

We looked at this bit of code before, and we said that C<dPOPTOPnnrl_ul>
arranges for two C<NV>s to be placed into C<left> and C<right> - let's
slightly expand it:

    #define dPOPTOPnnrl_ul  NV right = POPn; \
                            SV *leftsv = TOPs; \
                            NV left = USE_LEFT(leftsv) ? SvNV(leftsv) : 0.0

C<POPn> takes the SV from the top of the stack and obtains its NV either
directly (if C<SvNOK> is set) or by calling the C<sv_2nv> function.
C<TOPs> takes the next SV from the top of the stack - yes, C<POPn> uses
C<TOPs> - but doesn't remove it. We then use C<SvNV> to get the NV from
C<leftsv> in the same way as before - yes, C<POPn> uses C<SvNV>. 

Since we don't have an NV for C<$b>, we'll have to use C<sv_2nv> to
convert it. If we step again, we'll find ourselves there:

    Perl_sv_2nv (sv=0xa0675d0) at sv.c:1669
    1669        if (!sv)
    (gdb)

We can now use C<Perl_sv_dump> to investigate the SV:

    SV = PV(0xa057cc0) at 0xa0675d0
    REFCNT = 1
    FLAGS = (POK,pPOK)
    PV = 0xa06a510 "6XXXX"\0
    CUR = 5
    LEN = 6
    $1 = void

We know we're going to get C<6> from this, so let's finish the
subroutine:

    (gdb) finish
    Run till exit from #0  Perl_sv_2nv (sv=0xa0675d0) at sv.c:1671
    0x462669 in Perl_pp_add () at pp_hot.c:311
    311           dPOPTOPnnrl_ul;

We can also dump out this op: the current op is always stored in
C<PL_op>, and we can dump it with C<Perl_op_dump>. This'll give us
similar output to L<B::Debug|B::Debug>.

    {
    13  TYPE = add  ===> 14
        TARG = 1
        FLAGS = (SCALAR,KIDS)
        {
            TYPE = null  ===> (12)
              (was rv2sv)
            FLAGS = (SCALAR,KIDS)
            {
    11          TYPE = gvsv  ===> 12
                FLAGS = (SCALAR)
                GV = main::b
            }
        }

< finish this later >

=head2 Patching

All right, we've now had a look at how to navigate the Perl sources and
some things you'll need to know when fiddling with them. Let's now get
on and create a simple patch. Here's something Larry suggested: if a
C<U> is the first active format during a C<pack>, (for example, 
C<pack "U3C8", @stuff>) then the resulting string should be treated as
UTF8 encoded.

How do we prepare to fix this up? First we locate the code in question -
the C<pack> happens at runtime, so it's going to be in one of the F<pp>
files. Sure enough, C<pp_pack> is in F<pp.c>. Since we're going to be
altering this file, let's copy it to F<pp.c~>.

Now let's look over C<pp_pack>: we take a pattern into C<pat>, and then
loop over the pattern, taking each format character in turn into