948 lines
31 KiB
Plaintext
948 lines
31 KiB
Plaintext
=head1 NAME
|
|
|
|
perldebug - Perl debugging
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
First of all, have you tried using the B<-w> switch?
|
|
|
|
=head1 The Perl Debugger
|
|
|
|
If you invoke Perl with the B<-d> switch, your script runs under the
|
|
Perl source debugger. This works like an interactive Perl
|
|
environment, prompting for debugger commands that let you examine
|
|
source code, set breakpoints, get stack backtraces, change the values of
|
|
variables, etc. This is so convenient that you often fire up
|
|
the debugger all by itself just to test out Perl constructs
|
|
interactively to see what they do. For example:
|
|
|
|
$ perl -d -e 42
|
|
|
|
In Perl, the debugger is not a separate program the way it usually is in the
|
|
typical compiled environment. Instead, the B<-d> flag tells the compiler
|
|
to insert source information into the parse trees it's about to hand off
|
|
to the interpreter. That means your code must first compile correctly
|
|
for the debugger to work on it. Then when the interpreter starts up, it
|
|
preloads a special Perl library file containing the debugger.
|
|
|
|
The program will halt I<right before> the first run-time executable
|
|
statement (but see below regarding compile-time statements) and ask you
|
|
to enter a debugger command. Contrary to popular expectations, whenever
|
|
the debugger halts and shows you a line of code, it always displays the
|
|
line it's I<about> to execute, rather than the one it has just executed.
|
|
|
|
Any command not recognized by the debugger is directly executed
|
|
(C<eval>'d) as Perl code in the current package. (The debugger
|
|
uses the DB package for keeping its own state information.)
|
|
|
|
For any text entered at the debugger prompt, leading and trailing whitespace
|
|
is first stripped before further processing. If a debugger command
|
|
coincides with some function in your own program, merely precede the
|
|
function with something that doesn't look like a debugger command, such
|
|
as a leading C<;> or perhaps a C<+>, or by wrapping it with parentheses
|
|
or braces.
|
|
|
|
=head2 Debugger Commands
|
|
|
|
The debugger understands the following commands:
|
|
|
|
=over 12
|
|
|
|
=item h [command]
|
|
|
|
Prints out a help message.
|
|
|
|
If you supply another debugger command as an argument to the C<h> command,
|
|
it prints out the description for just that command. The special
|
|
argument of C<h h> produces a more compact help listing, designed to fit
|
|
together on one screen.
|
|
|
|
If the output of the C<h> command (or any command, for that matter) scrolls
|
|
past your screen, precede the command with a leading pipe symbol so
|
|
that it's run through your pager, as in
|
|
|
|
DB> |h
|
|
|
|
You may change the pager which is used via C<O pager=...> command.
|
|
|
|
=item p expr
|
|
|
|
Same as C<print {$DB::OUT} expr> in the current package. In particular,
|
|
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
|
|
where STDOUT may be redirected to.
|
|
|
|
=item x expr
|
|
|
|
Evaluates its expression in list context and dumps out the result
|
|
in a pretty-printed fashion. Nested data structures are printed out
|
|
recursively, unlike the real C<print> function in Perl.
|
|
See L<Dumpvalue> if you'd like to do this yourself.
|
|
|
|
The output format is governed by multiple options described under
|
|
L<"Options">.
|
|
|
|
=item V [pkg [vars]]
|
|
|
|
Display all (or some) variables in package (defaulting to C<main>)
|
|
using a data pretty-printer (hashes show their keys and values so
|
|
you see what's what, control characters are made printable, etc.).
|
|
Make sure you don't put the type specifier (like C<$>) there, just
|
|
the symbol names, like this:
|
|
|
|
V DB filename line
|
|
|
|
Use C<~pattern> and C<!pattern> for positive and negative regexes.
|
|
|
|
This is similar to calling the C<x> command on each applicable var.
|
|
|
|
=item X [vars]
|
|
|
|
Same as C<V currentpackage [vars]>.
|
|
|
|
=item T
|
|
|
|
Produce a stack backtrace. See below for details on its output.
|
|
|
|
=item s [expr]
|
|
|
|
Single step. Executes until the beginning of another
|
|
statement, descending into subroutine calls. If an expression is
|
|
supplied that includes function calls, it too will be single-stepped.
|
|
|
|
=item n [expr]
|
|
|
|
Next. Executes over subroutine calls, until the beginning
|
|
of the next statement. If an expression is supplied that includes
|
|
function calls, those functions will be executed with stops before
|
|
each statement.
|
|
|
|
=item r
|
|
|
|
Continue until the return from the current subroutine.
|
|
Dump the return value if the C<PrintRet> option is set (default).
|
|
|
|
=item <CR>
|
|
|
|
Repeat last C<n> or C<s> command.
|
|
|
|
=item c [line|sub]
|
|
|
|
Continue, optionally inserting a one-time-only breakpoint
|
|
at the specified line or subroutine.
|
|
|
|
=item l
|
|
|
|
List next window of lines.
|
|
|
|
=item l min+incr
|
|
|
|
List C<incr+1> lines starting at C<min>.
|
|
|
|
=item l min-max
|
|
|
|
List lines C<min> through C<max>. C<l -> is synonymous to C<->.
|
|
|
|
=item l line
|
|
|
|
List a single line.
|
|
|
|
=item l subname
|
|
|
|
List first window of lines from subroutine. I<subname> may
|
|
be a variable that contains a code reference.
|
|
|
|
=item -
|
|
|
|
List previous window of lines.
|
|
|
|
=item w [line]
|
|
|
|
List window (a few lines) around the current line.
|
|
|
|
=item .
|
|
|
|
Return the internal debugger pointer to the line last
|
|
executed, and print out that line.
|
|
|
|
=item f filename
|
|
|
|
Switch to viewing a different file or C<eval> statement. If I<filename>
|
|
is not a full pathname found in the values of %INC, it is considered
|
|
a regex.
|
|
|
|
C<eval>ed strings (when accessible) are considered to be filenames:
|
|
C<f (eval 7)> and C<f eval 7\b> access the body of the 7th C<eval>ed string
|
|
(in the order of execution). The bodies of the currently executed C<eval>
|
|
and of C<eval>ed strings that define subroutines are saved and thus
|
|
accessible.
|
|
|
|
=item /pattern/
|
|
|
|
Search forwards for pattern (a Perl regex); final / is optional.
|
|
|
|
=item ?pattern?
|
|
|
|
Search backwards for pattern; final ? is optional.
|
|
|
|
=item L
|
|
|
|
List all breakpoints and actions.
|
|
|
|
=item S [[!]regex]
|
|
|
|
List subroutine names [not] matching the regex.
|
|
|
|
=item t
|
|
|
|
Toggle trace mode (see also the C<AutoTrace> option).
|
|
|
|
=item t expr
|
|
|
|
Trace through execution of C<expr>.
|
|
See L<perldebguts/"Frame Listing Output Examples"> for examples.
|
|
|
|
=item b [line] [condition]
|
|
|
|
Set a breakpoint before the given line. If I<line> is omitted, set a
|
|
breakpoint on the line about to be executed. If a condition
|
|
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 C<if>:
|
|
|
|
b 237 $x > 30
|
|
b 237 ++$count237 < 11
|
|
b 33 /pattern/i
|
|
|
|
=item b subname [condition]
|
|
|
|
Set a breakpoint before the first line of the named subroutine. I<subname> may
|
|
be a variable containing a code reference (in this case I<condition>
|
|
is not supported).
|
|
|
|
=item b postpone subname [condition]
|
|
|
|
Set a breakpoint at first line of subroutine after it is compiled.
|
|
|
|
=item b load filename
|
|
|
|
Set a breakpoint before the first executed line of the I<filename>,
|
|
which should be a full pathname found amongst the %INC values.
|
|
|
|
=item b compile subname
|
|
|
|
Sets a breakpoint before the first statement executed after the specified
|
|
subroutine is compiled.
|
|
|
|
=item d [line]
|
|
|
|
Delete a breakpoint from the specified I<line>. If I<line> is omitted, deletes
|
|
the breakpoint from the line about to be executed.
|
|
|
|
=item D
|
|
|
|
Delete all installed breakpoints.
|
|
|
|
=item a [line] command
|
|
|
|
Set an action to be done before the line is executed. If I<line> is
|
|
omitted, set an action on the line about to be executed.
|
|
The sequence of steps taken by the debugger is
|
|
|
|
1. check for a breakpoint at this line
|
|
2. print the line if necessary (tracing)
|
|
3. do any actions associated with that line
|
|
4. prompt user if at a breakpoint or in single-step
|
|
5. evaluate line
|
|
|
|
For example, this will print out $foo every time line
|
|
53 is passed:
|
|
|
|
a 53 print "DB FOUND $foo\n"
|
|
|
|
=item a [line]
|
|
|
|
Delete an action from the specified line. If I<line> is omitted, delete
|
|
the action on the line that is about to be executed.
|
|
|
|
=item A
|
|
|
|
Delete all installed actions.
|
|
|
|
=item W expr
|
|
|
|
Add a global watch-expression. We hope you know what one of these
|
|
is, because they're supposed to be obvious. B<WARNING>: It is far
|
|
too easy to destroy your watch expressions by accidentally omitting
|
|
the I<expr>.
|
|
|
|
=item W
|
|
|
|
Delete all watch-expressions.
|
|
|
|
=item O booloption ...
|
|
|
|
Set each listed Boolean option to the value C<1>.
|
|
|
|
=item O anyoption? ...
|
|
|
|
Print out the value of one or more options.
|
|
|
|
=item O option=value ...
|
|
|
|
Set the value of one or more options. If the value has internal
|
|
whitespace, it should be quoted. For example, you could set C<O
|
|
pager="less -MQeicsNfr"> to call B<less> with those specific options.
|
|
You may use either single or double quotes, but if you do, you must
|
|
escape any embedded instances of same sort of quote you began with,
|
|
as well as any escaping any escapes that immediately precede that
|
|
quote but which are not meant to escape the quote itself. In other
|
|
words, you follow single-quoting rules irrespective of the quote;
|
|
eg: C<O option='this isn\'t bad'> or C<O option="She said, \"Isn't
|
|
it?\"">.
|
|
|
|
For historical reasons, the C<=value> is optional, but defaults to
|
|
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.
|
|
|
|
=item < ?
|
|
|
|
List out all pre-prompt Perl command actions.
|
|
|
|
=item < [ command ]
|
|
|
|
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 slackbashing 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.
|
|
|
|
=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
|
|
|
|
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.
|
|
|
|
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
|
|
possible.
|
|
|
|
=item C<ReadLine>
|
|
|
|
If false, readline support in the debugger is disabled in order
|
|
to debug applications that themselves use ReadLine.
|
|
|
|
=item C<NonStop>
|
|
|
|
If set, the debugger goes into non-interactive 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="NonStop frame=2" perl -d myprogram
|
|
|
|
That will run the script B<myprogram> without human intervention,
|
|
printing out the call tree with entry and exit points. Note that
|
|
C<NonStop=1 frame=2> is equivalent to C<N f=2>, and that originally,
|
|
options could be uniquely abbreviated by the first letter (modulo
|
|
the C<Dump*> options). It is nevertheless recommended that you
|
|
always spell them out in full for legibility and future compatibility.
|
|
|
|
Other examples include
|
|
|
|
$ PERLDB_OPTS="NonStop frame=2" perl -d myprogram
|
|
|
|
which runs script non-interactively, printing info on each entry
|
|
into a subroutine and each executed line into the file named F<listing>.
|
|
(If you interrupt it, you would better reset C<LineInfo> to something
|
|
"interactive"!)
|
|
|
|
Other examples include (using standard shell syntax to show environment
|
|
variable settings):
|
|
|
|
$ ( PERLDB_OPTS="NonStop frame=1 AutoTrace LineInfo=tperl.out"
|
|
perl -d myprogram )
|
|
|
|
which may be useful for debugging a program that uses C<Term::ReadLine>
|
|
itself. Do not forget to detach your shell from the TTY in the window that
|
|
corresponds to F</dev/ttyXX>, say, by issuing a command like
|
|
|
|
$ sleep 1000000
|
|
|
|
See L<perldebguts/"Debugger Internals"> for details.
|
|
|
|
=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, and which you'd use to
|
|
access with the built-in B<csh>-like history mechanism. For example,
|
|
C<!17> would repeat command number 17. The depth of the angle
|
|
brackets indicates the nesting 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 the result of a function call that
|
|
itself 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, 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 indicates the context in which the
|
|
function was called, with C<$> and C<@> meaning scalar or list
|
|
contexts respectively, and C<.> meaning void context (which is
|
|
actually a sort of scalar context). The display above says
|
|
that you were in the function C<main::infested> when you ran the
|
|
stack dump, and that it was called in 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 list context
|
|
from the I<camel_flea> file with four arguments. The last stack
|
|
frame shows that C<main::pests> was called in scalar context,
|
|
also from I<camel_flea>, but from line 4.
|
|
|
|
If you execute the C<T> command from inside an active C<use>
|
|
statement, the backtrace will contain both a C<require> frame and
|
|
an C<eval>) frame.
|
|
|
|
=item Line Listing Format
|
|
|
|
This shows the sorts of output the C<l> command can produce:
|
|
|
|
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);
|
|
|
|
Breakable lines are marked with C<:>. Lines with breakpoints are
|
|
marked by C<b> and those with actions by C<a>. The line that's
|
|
about to be executed is marked by C<< ==> >>.
|
|
|
|
=item Frame listing
|
|
|
|
When the C<frame> option is set, the debugger would print entered (and
|
|
optionally exited) subroutines in different styles. See L<perldebguts>
|
|
for incredibly long examples of these.
|
|
|
|
=back
|
|
|
|
=head2 Debugging compile-time statements
|
|
|
|
If you have compile-time executable statements (such as code within
|
|
BEGIN and CHECK blocks or C<use> statements), these will I<not> be
|
|
stopped by debugger, although C<require>s and INIT blocks will, and
|
|
compile-time statements can be traced with C<AutoTrace> option set
|
|
in C<PERLDB_OPTS>). From your own Perl code, however, you can
|
|
transfer control back to the debugger using the following statement,
|
|
which is harmless if the debugger is not running:
|
|
|
|
$DB::single = 1;
|
|
|
|
If you set C<$DB::single> to 2, it's equivalent to having
|
|
just typed the C<n> command, whereas a value of 1 means the C<s>
|
|
command. The C<$DB::trace> variable should be set to 1 to simulate
|
|
having typed the C<t> command.
|
|
|
|
Another way to debug compile-time code is to start the debugger, set a
|
|
breakpoint on the I<load> of some module:
|
|
|
|
DB<7> b load f:/perllib/lib/Carp.pm
|
|
Will stop on load of `f:/perllib/lib/Carp.pm'.
|
|
|
|
and then restart the debugger using the C<R> command (if possible). One can use C<b
|
|
compile subname> for the same purpose.
|
|
|
|
=head2 Debugger Customization
|
|
|
|
The debugger probably contains enough configuration hooks that you
|
|
won't ever have to modify it yourself. You may change the behaviour
|
|
of debugger from within the debugger using its C<O> command, from
|
|
the command line via the C<PERLDB_OPTS> environment variable, and
|
|
from customization files.
|
|
|
|
You can do some customization by setting up a F<.perldb> file, which
|
|
contains initialization code. For instance, you could make aliases
|
|
like these (the last one is one people expect to be there):
|
|
|
|
$DB::alias{'len'} = 's/^len(.*)/p length($1)/';
|
|
$DB::alias{'stop'} = 's/^stop (at|in)/b/';
|
|
$DB::alias{'ps'} = 's/^ps\b/p scalar /';
|
|
$DB::alias{'quit'} = 's/^quit(\s*)/exit/';
|
|
|
|
You can change options from F<.perldb> by using calls like this one;
|
|
|
|
parse_options("NonStop=1 LineInfo=db.out AutoTrace=1 frame=2");
|
|
|
|
The code is executed in the package C<DB>. Note that F<.perldb> is
|
|
processed before processing C<PERLDB_OPTS>. If F<.perldb> defines the
|
|
subroutine C<afterinit>, that function is called after debugger
|
|
initialization ends. F<.perldb> may be contained in the current
|
|
directory, or in the home directory. Because this file is sourced
|
|
in by Perl and may contain arbitrary commands, for security reasons,
|
|
it must be owned by the superuser or the current user, and writable
|
|
by no one but its owner.
|
|
|
|
If you want to modify the debugger, copy F<perl5db.pl> from the
|
|
Perl library to another name and hack it to your heart's content.
|
|
You'll then want to set your C<PERL5DB> environment variable to say
|
|
something like this:
|
|
|
|
BEGIN { require "myperl5db.pl" }
|
|
|
|
As a last resort, you could also use C<PERL5DB> to customize the debugger
|
|
by directly setting internal variables or calling debugger functions.
|
|
|
|
Note that any variables and functions that are not documented in
|
|
this document (or in L<perldebguts>) are considered for internal
|
|
use only, and as such are subject to change without notice.
|
|
|
|
=head2 Readline Support
|
|
|
|
As shipped, the only command-line history supplied is a simplistic one
|
|
that checks for leading exclamation points. However, if you install
|
|
the Term::ReadKey and Term::ReadLine modules from CPAN, you will
|
|
have full editing capabilities much like GNU I<readline>(3) provides.
|
|
Look for these in the F<modules/by-module/Term> directory on CPAN.
|
|
These do not support normal B<vi> command-line editing, however.
|
|
|
|
A rudimentary command-line completion is also available.
|
|
Unfortunately, the names of lexical variables are not available for
|
|
completion.
|
|
|
|
=head2 Editor Support for Debugging
|
|
|
|
If you have the FSF's version of B<emacs> installed on your system,
|
|
it can interact with the Perl debugger to provide an integrated
|
|
software development environment reminiscent of its interactions
|
|
with C debuggers.
|
|
|
|
Perl comes with a start file for making B<emacs> act like a
|
|
syntax-directed editor that understands (some of) Perl's syntax.
|
|
Look in the I<emacs> directory of the Perl source distribution.
|
|
|
|
A similar setup by Tom Christiansen for interacting with any
|
|
vendor-shipped B<vi> and the X11 window system is also available.
|
|
This works similarly to the integrated multiwindow support that
|
|
B<emacs> provides, where the debugger drives the editor. At the
|
|
time of this writing, however, that tool's eventual location in the
|
|
Perl distribution was uncertain.
|
|
|
|
Users of B<vi> should also look into B<vim> and B<gvim>, the mousey
|
|
and windy version, for coloring of Perl keywords.
|
|
|
|
Note that only perl can truly parse Perl, so all such CASE tools
|
|
fall somewhat short of the mark, especially if you don't program
|
|
your Perl as a C programmer might.
|
|
|
|
=head2 The Perl Profiler
|
|
|
|
If you wish to supply an alternative debugger for Perl to run, just
|
|
invoke your script with a colon and a package argument given to the
|
|
B<-d> flag. The most popular alternative debuggers for Perl is the
|
|
Perl profiler. Devel::DProf is now included with the standard Perl
|
|
distribution. To profile your Perl program in the file F<mycode.pl>,
|
|
just type:
|
|
|
|
$ perl -d:DProf mycode.pl
|
|
|
|
When the script terminates the profiler will dump the profile
|
|
information to a file called F<tmon.out>. A tool like B<dprofpp>,
|
|
also supplied with the standard Perl distribution, can be used to
|
|
interpret the information in that profile.
|
|
|
|
=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
|
|
L<perldebguts/"Debugging regular expressions">.
|
|
|
|
=head1 Debugging memory usage
|
|
|
|
Perl contains internal support for reporting its own memory usage,
|
|
but this is a fairly advanced concept that requires some understanding
|
|
of how memory allocation works.
|
|
See L<perldebguts/"Debugging Perl memory usage"> for the details.
|
|
|
|
=head1 SEE ALSO
|
|
|
|
You did try the B<-w> switch, didn't you?
|
|
|
|
L<perldebguts>,
|
|
L<re>,
|
|
L<DB>,
|
|
L<Devel::Dprof>,
|
|
L<dprofpp>,
|
|
L<Dumpvalue>,
|
|
and
|
|
L<perlrun>.
|
|
|
|
=head1 BUGS
|
|
|
|
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 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.
|