=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]]
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 { ?
=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>
=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
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.
projects / p5sagit/p5-mst-13.2.git / blobdiff