=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
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
=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]
=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>
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
+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
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