perldebug.pod

ARM上的如果你对底层感兴趣

size of strings in variables in the package.

=back

During startup options are initialized from C<$ENV{PERLDB_OPTS}>.
You can put additional initialization options C<TTY>, C<noTTY>,
C<ReadLine>, and C<NonStop> there.

Example rc file:

  &parse_options("NonStop=1 LineInfo=db.out AutoTrace");

The script will run without human intervention, putting trace information
into the file I<db.out>.  (If you interrupt it, you would better reset
C<LineInfo> to something "interactive"!)

=over 12

=item C<TTY>

The TTY to use for debugging I/O.

=item C<noTTY>

If set, goes in C<NonStop> mode, and would not connect to a TTY.  If
interrupt (or if control goes to debugger via explicit setting of
$DB::signal or $DB::single from the Perl script), connects to a TTY
specified by the C<TTY> option at startup, or to a TTY found at
runtime using C<Term::Rendezvous> module of your choice.

This module should implement a method C<new> which returns an object
with two methods: C<IN> and C<OUT>, returning two filehandles to use
for debugging input and output correspondingly.  Method C<new> may
inspect an argument which is a value of C<$ENV{PERLDB_NOTTY}> at
startup, or is C<"/tmp/perldbtty$$"> otherwise.

=item C<ReadLine>

If false, readline support in debugger is disabled, so you can debug
ReadLine applications.

=item C<NonStop>

If set, debugger goes into noninteractive mode until interrupted, or
programmatically by setting $DB::signal or $DB::single.

=back

Here's an example of using the C<$ENV{PERLDB_OPTS}> variable:

  $ PERLDB_OPTS="N f=2" perl -d myprogram

will run the script C<myprogram> without human intervention, printing
out the call tree with entry and exit points.  Note that C<N f=2> is
equivalent to C<NonStop=1 frame=2>.  Note also that at the moment when
this documentation was written all the options to the debugger could
be uniquely abbreviated by the first letter (with exception of
C<Dump*> options).

Other examples may include

  $ PERLDB_OPTS="N f A L=listing" perl -d myprogram

- runs script noninteractively, printing info on each entry into a
subroutine and each executed line into the file F<listing>. (If you
interrupt it, you would better reset C<LineInfo> to something
"interactive"!)


  $ env "PERLDB_OPTS=R=0 TTY=/dev/ttyc" perl -d myprogram

may be useful for debugging a program which uses C<Term::ReadLine>
itself.  Do not forget detach shell from the TTY in the window which
corresponds to F</dev/ttyc>, say, by issuing a command like

  $ sleep 1000000

See L<"Debugger Internals"> below for more details.

=item E<lt> [ command ]

Set an action (Perl command) to happen before every debugger prompt.
A multi-line command may be entered by backslashing the newlines.  If
C<command> is missing, resets the list of actions.

=item E<lt>E<lt> command

Add an action (Perl command) to happen before every debugger prompt.
A multi-line command may be entered by backslashing the newlines.

=item E<gt> command

Set an action (Perl command) to happen after the prompt when you've
just given a command to return to executing the script.  A multi-line
command may be entered by backslashing the newlines.  If C<command> is
missing, resets the list of actions.

=item E<gt>E<gt> command

Adds an action (Perl command) to happen after the prompt when you've
just given a command to return to executing the script.  A multi-line
command may be entered by backslashing the newlines.

=item { [ command ]

Set an action (debugger command) to happen before every debugger prompt.
A multi-line command may be entered by backslashing the newlines.  If
C<command> is missing, resets the list of actions.

=item {{ command

Add an action (debugger command) to happen before every debugger prompt.
A multi-line command may be entered by backslashing the newlines.

=item ! number

Redo a previous command (default previous command).

=item ! -number

Redo number'th-to-last command.

=item ! pattern

Redo last command that started with pattern.
See C<O recallCommand>, too.

=item !! cmd

Run cmd in a subprocess (reads from DB::IN, writes to DB::OUT)
See C<O shellBang> too.

=item H -number

Display last n commands.  Only commands longer than one character are
listed.  If number is omitted, lists them all.

=item q or ^D

Quit.  ("quit" doesn't work for this.)  This is the only supported way
to exit the debugger, though typing C<exit> twice may do it too.

Set an C<O>ption C<inhibit_exit> to 0 if you want to be able to I<step
off> the end the script.  You may also need to set C<$finished> to 0 at
some moment if you want to step through global destruction.

=item R

Restart the debugger by B<exec>ing a new session.  It tries to maintain
your history across this, but internal settings and command line options
may be lost.

Currently the following setting are preserved: history, breakpoints,
actions, debugger C<O>ptions, and the following command line
options: B<-w>, B<-I>, and B<-e>.

=item |dbcmd

Run debugger command, piping DB::OUT to current pager.

=item ||dbcmd

Same as C<|dbcmd> but DB::OUT is temporarily B<select>ed as well.
Often used with commands that would otherwise produce long
output, such as

    |V main

=item = [alias value]

Define a command alias, like

    = quit q

or list current aliases.

=item command

Execute command as a Perl statement.  A missing semicolon will be
supplied.

=item m expr

The expression is evaluated, and the methods which may be applied to
the result are listed.

=item m package

The methods which may be applied to objects in the C<package> are listed.

=back

=head2 Debugger input/output

=over 8

=item Prompt

The debugger prompt is something like

    DB<8>

or even

    DB<<17>>

where that number is the command number, which you'd use to access with
the builtin B<csh>-like history mechanism, e.g., C<!17> would repeat
command number 17.  The number of angle brackets indicates the depth of
the debugger.  You could get more than one set of brackets, for example, if
you'd already at a breakpoint and then printed out the result of a
function call that itself also has a breakpoint, or you step into an
expression via C<s/n/t expression> command.

=item Multiline commands

If you want to enter a multi-line command, such as a subroutine
definition with several statements, or a format, you may escape the
newline that would normally end the debugger command with a backslash.
Here's an example:

      DB<1> for (1..4) {         \
      cont:     print "ok\n";   \
      cont: }
      ok
      ok
      ok
      ok

Note that this business of escaping a newline is specific to interactive
commands typed into the debugger.

=item Stack backtrace

Here's an example of what a stack backtrace via C<T> command might
look like:

    $ = main::infested called from file `Ambulation.pm' line 10
    @ = Ambulation::legs(1, 2, 3, 4) called from file `camel_flea' line 7
    $ = main::pests('bactrian', 4) called from file `camel_flea' line 4

The left-hand character up there tells whether the function was called
in a scalar or list context (we bet you can tell which is which).  What
that says is that you were in the function C<main::infested> when you ran
the stack dump, and that it was called in a scalar context from line 10
of the file I<Ambulation.pm>, but without any arguments at all, meaning
it was called as C<&infested>.  The next stack frame shows that the
function C<Ambulation::legs> was called in a list context from the
I<camel_flea> file with four arguments.  The last stack frame shows that
C<main::pests> was called in a scalar context, also from I<camel_flea>,
but from line 4.

Note that if you execute C<T> command from inside an active C<use>
statement, the backtrace will contain both C<require>
frame and an C<eval>) frame.

=item Listing

Listing given via different flavors of C<l> command looks like this:

    DB<<13>> l
  101:                @i{@i} = ();
  102:b               @isa{@i,$pack} = ()
  103                     if(exists $i{$prevpack} || exists $isa{$pack});
  104             }
  105
  106             next
  107==>              if(exists $isa{$pack});
  108
  109:a           if ($extra-- > 0) {
  110:                %isa = ($pack,1);

Note that the breakable lines are marked with C<:>, lines with
breakpoints are marked by C<b>, with actions by C<a>, and the
next executed line is marked by C<==E<gt>>.

=item Frame listing

When C<frame> option is set, debugger would print entered (and
optionally exited) subroutines in different styles.

What follows is the start of the listing of

  env "PERLDB_OPTS=f=n N" perl -d -V

for different values of C<n>:

=over 4

=item 1

  entering main::BEGIN
   entering Config::BEGIN
    Package lib/Exporter.pm.
    Package lib/Carp.pm.
   Package lib/Config.pm.
   entering Config::TIEHASH
   entering Exporter::import
    entering Exporter::export
  entering Config::myconfig
   entering Config::FETCH
   entering Config::FETCH
   entering Config::FETCH
   entering Config::FETCH

=item 2

  entering main::BEGIN
   entering Config::BEGIN
    Package lib/Exporter.pm.
    Package lib/Carp.pm.
   exited Config::BEGIN
   Package lib/Config.pm.
   entering Config::TIEHASH
   exited Config::TIEHASH
   entering Exporter::import
    entering Exporter::export
    exited Exporter::export
   exited Exporter::import
  exited main::BEGIN
  entering Config::myconfig
   entering Config::FETCH
   exited Config::FETCH
   entering Config::FETCH
   exited Config::FETCH
   entering Config::FETCH

=item 4

  in  $=main::BEGIN() from /dev/nul:0
   in  $=Config::BEGIN() from lib/Config.pm:2
    Package lib/Exporter.pm.
    Package lib/Carp.pm.
   Package lib/Config.pm.
   in  $=Config::TIEHASH('Config') from lib/Config.pm:644
   in  $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/nul:0
    in  $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from li
  in  @=Config::myconfig() from /dev/nul:0
   in  $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574
   in  $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574
   in  $=Config::FETCH(ref(Config), 'PATCHLEVEL') from lib/Config.pm:574
   in  $=Config::FETCH(ref(Config), 'SUBVERSION') from lib/Config.pm:574
   in  $=Config::FETCH(ref(Config), 'osname') from lib/Config.pm:574
   in  $=Config::FETCH(ref(Config), 'osvers') from lib/Config.pm:574

=item 6

  in  $=main::BEGIN() from /dev/nul:0
   in  $=Config::BEGIN() from lib/Config.pm:2
    Package lib/Exporter.pm.
    Package lib/Carp.pm.
   out $=Config::BEGIN() from lib/Config.pm:0
   Package lib/Config.pm.
   in  $=Config::TIEHASH('Config') from lib/Config.pm:644
   out $=Config::TIEHASH('Config') from lib/Config.pm:644
   in  $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/nul:0
    in  $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/
    out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/
   out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/nul:0
  out $=main::BEGIN() from /dev/nul:0
  in  @=Config::myconfig() from /dev/nul:0
   in  $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574
   out $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574
   in  $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574
   out $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574
   in  $=Config::FETCH(ref(Config), 'PATCHLEVEL') from lib/Config.pm:574
   out $=Config::FETCH(ref(Config), 'PATCHLEVEL') from lib/Config.pm:574
   in  $=Config::FETCH(ref(Config), 'SUBVERSION') from lib/Config.pm:574

=item 14

  in  $=main::BEGIN() from /dev/nul:0
   in  $=Config::BEGIN() from lib/Config.pm:2
    Package lib/Exporter.pm.
    Package lib/Carp.pm.
   out $=Config::BEGIN() from lib/Config.pm:0
   Package lib/Config.pm.
   in  $=Config::TIEHASH('Config') from lib/Config.pm:644
   out $=Config::TIEHASH('Config') from lib/Config.pm:644
   in  $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/nul:0
    in  $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/E
    out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/E
   out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/nul:0
  out $=main::BEGIN() from /dev/nul:0
  in  @=Config::myconfig() from /dev/nul:0
   in  $=Config::FETCH('Config=HASH(0x1aa444)', 'package') from lib/Config.pm:574
   out $=Config::FETCH('Config=HASH(0x1aa444)', 'package') from lib/Config.pm:574
   in  $=Config::FETCH('Config=HASH(0x1aa444)', 'baserev') from lib/Config.pm:574
   out $=Config::FETCH('Config=HASH(0x1aa444)', 'baserev') from lib/Config.pm:574

=item 30

  in  $=CODE(0x15eca4)() from /dev/null:0
   in  $=CODE(0x182528)() from lib/Config.pm:2
    Package lib/Exporter.pm.
   out $=CODE(0x182528)() from lib/Config.pm:0
   scalar context return from CODE(0x182528): undef
   Package lib/Config.pm.
   in  $=Config::TIEHASH('Config') from lib/Config.pm:628
   out $=Config::TIEHASH('Config') from lib/Config.pm:628
   scalar context return from Config::TIEHASH:   empty hash
   in  $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
    in  $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/Exporter.pm:171
    out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/Exporter.pm:171
    scalar context return from Exporter::export: ''
   out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
   scalar context return from Exporter::import: ''


=back

In all the cases indentation of lines shows the call tree, if bit 2 of
C<frame> is set, then a line is printed on exit from a subroutine as
well, if bit 4 is set, then the arguments are printed as well as the
caller info, if bit 8 is set, the arguments are printed even if they
are tied or references, if bit 16 is set, the return value is printed