perldebug.pod

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

Set an action (Perl command) to happen before every debugger prompt.
A multi-line command may be entered by backslashing the newlines.  
B<WARNING> If C<command> is missing, all actions are wiped out!

=item << command

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

=item > ?

List out post-prompt Perl command actions.

=item > 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 (we bet you
couldn't've guessed this by now).  B<WARNING> If C<command> is
missing, all actions are wiped out!

=item >> 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 { ?

List out pre-prompt debugger commands.

=item { [ command ]

Set an action (debugger command) to happen before every debugger prompt.
A multi-line command may be entered in the customary fashion.  
B<WARNING> If C<command> is missing, all actions are wiped out!

Because this command is in some senses new, a warning is issued if
you appear to have accidentally entered a block instead.  If that's
what you mean to do, write it as with C<;{ ... }> or even 
C<do { ... }>.

=item {{ command

Add an action (debugger command) to happen before every debugger prompt.
A multi-line command may be entered, if you can guess how: see above.

=item ! number

Redo a previous command (defaults to the previous command).

=item ! -number

Redo number'th previous 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>, also.  Note that the user's current shell (well,
their C<$ENV{SHELL}> variable) will be used, which can interfere
with proper interpretation of exit status or signal and coredump
information.

=item H -number

Display last n commands.  Only commands longer than one character are
listed.  If I<number> is omitted, list them all.

=item q or ^D

Quit.  ("quit" doesn't work for this, unless you've made an alias)
This is the only supported way to exit the debugger, though typing
C<exit> twice might work.

Set the C<inhibit_exit> option to 0 if you want to be able to step
off the end the script.  You may also need to set $finished to 0 
if you want to step through global destruction.

=item R

Restart the debugger by C<exec()>ing a new session.  We try to maintain
your history across this, but internal settings and command-line options
may be lost.

The following setting are currently preserved: history, breakpoints,
actions, debugger options, and the Perl command-line
options B<-w>, B<-I>, and B<-e>.

=item |dbcmd

Run the debugger command, piping DB::OUT into your current pager.

=item ||dbcmd

Same as C<|dbcmd> but DB::OUT is temporarily C<select>ed as well.

=item = [alias value]

Define a command alias, like

    = quit q

or list current aliases.

=item command

Execute command as a Perl statement.  A trailing semicolon will be
supplied.  If the Perl statement would otherwise be confused for a
Perl debugger, use a leading semicolon, too.

=item m expr

List which methods may be called on the result of the evaluated
expression.  The expression may evaluated to a reference to a 
blessed object, or to a package name.

=item man [manpage]

Despite its name, this calls your system's default documentation
viewer on the given page, or on the viewer itself if I<manpage> is
omitted.  If that viewer is B<man>, the current C<Config> information
is used to invoke B<man> using the proper MANPATH or S<B<-M>
I<manpath>> option.  Failed lookups of the form C<XXX> that match
known manpages of the form I<perlXXX> will be retried.  This lets
you type C<man debug> or C<man op> from the debugger.

On systems traditionally bereft of a usable B<man> command, the
debugger invokes B<perldoc>.  Occasionally this determination is
incorrect due to recalcitrant vendors or rather more felicitously,
to enterprising users.  If you fall into either category, just
manually set the $DB::doccmd variable to whatever viewer to view
the Perl documentation on your system.  This may be set in an rc
file, or through direct assignment.  We're still waiting for a
working example of something along the lines of:

    $DB::doccmd = 'netscape -remote http://something.here/';

=back

=head2 Configurable Options

The debugger has numerous options settable using the C<O> command,
either interactively or from the environment or an rc file.
(./.perldb or ~/.perldb under Unix.)


=over 12

=item C<recallCommand>, C<ShellBang>

The characters used to recall command or spawn shell.  By
default, both are set to C<!>, which is unfortunate.

=item C<pager>

Program to use for output of pager-piped commands (those beginning
with a C<|> character.)  By default, C<$ENV{PAGER}> will be used.
Because the debugger uses your current terminal characteristics
for bold and underlining, if the chosen pager does not pass escape
sequences through unchanged, the output of some debugger commands
will not be readable when sent through the pager.

=item C<tkRunning>

Run Tk while prompting (with ReadLine).

=item C<signalLevel>, C<warnLevel>, C<dieLevel>

Level of verbosity.  By default, the debugger leaves your exceptions
and warnings alone, because altering them can break correctly running
programs.  It will attempt to print a message when uncaught INT, BUS, or
SEGV signals arrive.  (But see the mention of signals in L<BUGS> below.)

To disable this default safe mode, set these values to something higher
than 0.  At a level of 1, you get backtraces upon receiving any kind
of warning (this is often annoying) or exception (this is
often valuable).  Unfortunately, the debugger cannot discern fatal
exceptions from non-fatal ones.  If C<dieLevel> is even 1, then your
non-fatal exceptions are also traced and unceremoniously altered if they
came from C<eval'd> strings or from any kind of C<eval> within modules
you're attempting to load.  If C<dieLevel> is 2, the debugger doesn't
care where they came from:  It usurps your exception handler and prints
out a trace, then modifies all exceptions with its own embellishments.
This may perhaps be useful for some tracing purposes, but tends to hopelessly
destroy any program that takes its exception handling seriously.

=item C<AutoTrace>

Trace mode (similar to C<t> command, but can be put into
C<PERLDB_OPTS>).

=item C<LineInfo>

File or pipe to print line number info to.  If it is a pipe (say,
C<|visual_perl_db>), then a short message is used.  This is the
mechanism used to interact with a slave editor or visual debugger,
such as the special C<vi> or C<emacs> hooks, or the C<ddd> graphical
debugger.

=item C<inhibit_exit>

If 0, allows I<stepping off> the end of the script.

=item C<PrintRet>

Print return value after C<r> command if set (default).

=item C<ornaments>

Affects screen appearance of the command line (see L<Term::ReadLine>).
There is currently no way to disable these, which can render
some output illegible on some displays, or with some pagers.
This is considered a bug.

=item C<frame>

Affects the printing of messages upon entry and exit from subroutines.  If
C<frame & 2> is false, messages are printed on entry only. (Printing
on exit might be useful if interspersed with other messages.)

If C<frame & 4>, arguments to functions are printed, plus context
and caller info.  If C<frame & 8>, overloaded C<stringify> and
C<tie>d C<FETCH> is enabled on the printed arguments.  If C<frame
& 16>, the return value from the subroutine is printed.

The length at which the argument list is truncated is governed by the
next option:

=item C<maxTraceLen>

Length to truncate the argument list when the C<frame> option's
bit 4 is set.

=back

The following options affect what happens with C<V>, C<X>, and C<x>
commands:

=over 12

=item C<arrayDepth>, C<hashDepth>

Print only first N elements ('' for all).

=item C<compactDump>, C<veryCompact>

Change the style of array and hash output.  If C<compactDump>, short array
may be printed on one line.

=item C<globPrint>

Whether to print contents of globs.

=item C<DumpDBFiles>

Dump arrays holding debugged files.

=item C<DumpPackages>

Dump symbol tables of packages.

=item C<DumpReused>

Dump contents of "reused" addresses.

=item C<quote>, C<HighBit>, C<undefPrint>

Change the style of string dump.  The default value for C<quote>
is C<auto>; one can enable double-quotish or single-quotish format
by setting it to C<"> or C<'>, respectively.  By default, characters
with their high bit set are printed verbatim.

=item C<UsageOnly>

Rudimentary per-package memory usage dump.  Calculates total
size of strings found in variables in the package.  This does not
include lexicals in a module's file scope, or lost in closures.

=back

After the rc file is read, the debugger reads the C<$ENV{PERLDB_OPTS}>
environment variable and parses this as the remainder of a `O ...'
line as one might enter at the debugger prompt.  You may place the
initialization options C<TTY>, C<noTTY>, C<ReadLine>, and C<NonStop>
there.

If your rc file contains:

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

then your script will run without human intervention, putting trace
information into the file I<db.out>.  (If you interrupt it, you'd
better reset C<LineInfo> to F</dev/tty> if you expect to see anything.)

=over 12

=item C<TTY>

The TTY to use for debugging I/O.

=item C<noTTY>

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

This module should implement a method named C<new> that returns an object
with two methods: C<IN> and C<OUT>.  These should return filehandles to use
for debugging input and output correspondingly.  The C<new> method should
inspect an argument containing the value of C<$ENV{PERLDB_NOTTY}> at
startup, or C<"/tmp/perldbtty$$"> otherwise.  This file is not 
inspected for proper ownership, so security hazards are theoretically