First of all, have you tried using the B<-w> switch?
+
+If you're new to the Perl debugger, you may prefer to read
+L<perldebtut>, which is a tutorial introduction to the debugger .
+
=head1 The Perl Debugger
If you invoke Perl with the B<-d> switch, your script runs under the
=item p expr
Same as C<print {$DB::OUT} expr> in the current package. In particular,
-because this is just Perl's own B<print> function, this means that nested
+because this is just Perl's own C<print> function, this means that nested
data structures and objects are not dumped, unlike with the C<x> command.
The C<DB::OUT> filehandle is opened to F</dev/tty>, regardless of
See L<Dumpvalue> if you'd like to do this yourself.
The output format is governed by multiple options described under
-L<"Options">.
+L<"Configurable Options">.
=item V [pkg [vars]]
=item /pattern/
Search forwards for pattern (a Perl regex); final / is optional.
+The search is case-insensitive by default.
=item ?pattern?
Search backwards for pattern; final ? is optional.
+The search is case-insensitive by default.
=item L
is specified, it's evaluated each time the statement is reached: a
breakpoint is taken only if the condition is true. Breakpoints may
only be set on lines that begin an executable statement. Conditions
-don't use B<if>:
+don't use C<if>:
b 237 $x > 30
b 237 ++$count237 < 11
1 only where it is safe to do so--that is, mostly for Boolean
options. It is always better to assign a specific value using C<=>.
The C<option> can be abbreviated, but for clarity probably should
-not be. Several options can be set together. See L<"Options"> for
-a list of these.
+not be. Several options can be set together. See L<"Configurable Options">
+for a list of these.
=item < ?
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 slackbashing the newlines.
+command may be entered by backslashing the newlines.
=item { ?
with proper interpretation of exit status or signal and coredump
information.
+=item @ file
+
+Read and execute debugger commands from I<file>. I<file> may itself contain
+C<@> commands.
+
=item H -number
Display last n commands. Only commands longer than one character are
=item ||dbcmd
-Same as C<|dbcmd> but DB::OUT is temporarily B<select>ed as well.
+Same as C<|dbcmd> but DB::OUT is temporarily C<select>ed as well.
=item = [alias value]
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<signalLevel>, C<warnLevel>, C<dieLevel>
-Level of verbosity. By default, the debugger prints backtraces
-upon receiving any kind of warning (this is often annoying) and
-fatal exceptions (this is often valuable). It will attempt to print
-a message when uncaught INT, BUS, or SEGV signals arrive.
-
-To disable this behaviour, set these values to 0. If C<dieLevel>
-is 2, the debugger usurps your own exception handler and prints out
-a trace of these, replacing your exceptions with its own. This may
-be useful for some tracing purposes, but tends to hopelessly destroy
-any program that takes its exception handling seriously.
+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>
Length to truncate the argument list when the C<frame> option's
bit 4 is set.
+=item C<windowSize>
+
+Change the size of code list window (default is 10 lines).
+
=back
The following options affect what happens with C<V>, C<X>, and C<x>
=back
-During startup, options are initialized from C<$ENV{PERLDB_OPTS}>.
-You may place the initialization options C<TTY>, C<noTTY>,
-C<ReadLine>, and C<NonStop> there.
+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:
marked by C<b> and those with actions by C<a>. The line that's
about to be executed is marked by C<< ==> >>.
+Please be aware that code in debugger listings may not look the same
+as your original source code. Line directives and external source
+filters can alter the code before Perl sees it, causing code to move
+from its original positions or take on entirely different forms.
+
=item Frame listing
When the C<frame> option is set, the debugger would print entered (and
=head1 Debugging regular expressions
-C<use re 'debug'> enables you to see the gory details of how the
-Perl regular expression engine works. In order to understand this
-typically voluminous output, one must not only have some idea about
-about how regular expression matching works in general, but also
-know how Perl's regular expressions are internally compiled into
-an automaton. These matters are explored in some detail in
+C<use re 'debug'> enables you to see the gory details of how the Perl
+regular expression engine works. In order to understand this typically
+voluminous output, one must not only have some idea about how regular
+expression matching works in general, but also know how Perl's regular
+expressions are internally compiled into an automaton. These matters
+are explored in some detail in
L<perldebguts/"Debugging regular expressions">.
=head1 Debugging memory usage
You did try the B<-w> switch, didn't you?
+L<perldebtut>,
L<perldebguts>,
L<re>,
L<DB>,
You cannot get stack frame information or in any fashion debug functions
that were not compiled by Perl, such as those from C or C++ extensions.
-If you alter your @_ arguments in a subroutine (such as with B<shift>
-or B<pop>, the stack backtrace will not show the original values.
+If you alter your @_ arguments in a subroutine (such as with C<shift>
+or C<pop>), the stack backtrace will not show the original values.
+
+The debugger does not currently work in conjunction with the B<-W>
+command-line switch, because it itself is not free of warnings.
+
+If you're in a slow syscall (like C<wait>ing, C<accept>ing, or C<read>ing
+from your keyboard or a socket) and haven't set up your own C<$SIG{INT}>
+handler, then you won't be able to CTRL-C your way back to the debugger,
+because the debugger's own C<$SIG{INT}> handler doesn't understand that
+it needs to raise an exception to longjmp(3) out of slow syscalls.