=head1 NAME
+X<debug> X<debugger>
perldebug - Perl debugging
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:
+X<-d>
$ perl -d -e 42
as a leading C<;> or perhaps a C<+>, or by wrapping it with parentheses
or braces.
+=head2 Calling the debugger
+
+There are several ways to call the debugger:
+
+=over 4
+
+=item perl -d program_name
+
+On the given program identified by C<program_name>.
+
+=item perl -d -e 0
+
+Interactively supply an arbitrary C<expression> using C<-e>.
+
+=item perl -d:Ptkdb program_name
+
+Debug a given program via the C<Devel::Ptkdb> GUI.
+
+=item perl -dt threaded_program_name
+
+Debug a given program using threads (experimental).
+
+=back
+
=head2 Debugger Commands
-The debugger understands the following commands:
+The interactive debugger understands the following commands:
=over 12
=item h
+X<debugger command, h>
Prints out a summary help message
=item p expr
+X<debugger command, p>
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
where STDOUT may be redirected to.
=item x [maxdepth] expr
+X<debugger command, x>
Evaluates its expression in list context and dumps out the result in a
pretty-printed fashion. Nested data structures are printed out
temporarily set to I<N>.
=item V [pkg [vars]]
+X<debugger command, V>
Display all (or some) variables in package (defaulting to C<main>)
using a data pretty-printer (hashes show their keys and values so
This is similar to calling the C<x> command on each applicable var.
=item X [vars]
+X<debugger command, X>
Same as C<V currentpackage [vars]>.
=item y [level [vars]]
+X<debugger command, y>
Display all (or some) lexical variables (mnemonic: C<mY> variables)
in the current scope or I<level> scopes higher. You can limit the
controlled by the same options.
=item T
+X<debugger command, T> X<backtrace> X<stack, backtrace>
Produce a stack backtrace. See below for details on its output.
=item s [expr]
+X<debugger command, s> X<step>
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]
+X<debugger command, n>
Next. Executes over subroutine calls, until the beginning
of the next statement. If an expression is supplied that includes
each statement.
=item r
+X<debugger command, r>
Continue until the return from the current subroutine.
Dump the return value if the C<PrintRet> option is set (default).
Repeat last C<n> or C<s> command.
=item c [line|sub]
+X<debugger command, c>
Continue, optionally inserting a one-time-only breakpoint
at the specified line or subroutine.
=item l
+X<debugger command, l>
List next window of lines.
be a variable that contains a code reference.
=item -
+X<debugger command, ->
List previous window of lines.
=item v [line]
+X<debugger command, v>
View a few lines of code around the current line.
=item .
+X<debugger command, .>
Return the internal debugger pointer to the line last
executed, and print out that line.
=item f filename
+X<debugger command, f>
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
The search is case-insensitive by default.
=item L [abw]
+X<debugger command, L>
List (default all) actions, breakpoints and watch expressions
=item S [[!]regex]
+X<debugger command, S>
List subroutine names [not] matching the regex.
=item t
+X<debugger command, t>
Toggle trace mode (see also the C<AutoTrace> option).
=item t expr
+X<debugger command, t>
Trace through execution of C<expr>.
See L<perldebguts/"Frame Listing Output Examples"> for examples.
=item b
+X<breakpoint>
+X<debugger command, b>
Sets breakpoint on current line
=item b [line] [condition]
+X<breakpoint>
+X<debugger command, b>
Set a breakpoint before the given line. If a condition
is specified, it's evaluated each time the statement is reached: a
b 33 /pattern/i
=item b subname [condition]
+X<breakpoint>
+X<debugger command, b>
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]
+X<breakpoint>
+X<debugger command, b>
Set a breakpoint at first line of subroutine after it is compiled.
=item b load filename
+X<breakpoint>
+X<debugger command, b>
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
+X<breakpoint>
+X<debugger command, b>
Sets a breakpoint before the first statement executed after the specified
subroutine is compiled.
=item B line
+X<breakpoint>
+X<debugger command, B>
Delete a breakpoint from the specified I<line>.
=item B *
+X<breakpoint>
+X<debugger command, B>
Delete all installed breakpoints.
=item a [line] command
+X<debugger command, a>
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.
a 53 print "DB FOUND $foo\n"
=item A line
+X<debugger command, A>
Delete an action from the specified line.
=item A *
+X<debugger command, A>
Delete all installed actions.
=item w expr
+X<debugger command, w>
Add a global watch-expression. We hope you know what one of these
is, because they're supposed to be obvious.
=item W expr
+X<debugger command, W>
Delete watch-expression
=item W *
+X<debugger command, W>
Delete all watch-expressions.
=item o
+X<debugger command, o>
Display all options
=item o booloption ...
+X<debugger command, o>
Set each listed Boolean option to the value C<1>.
=item o anyoption? ...
+X<debugger command, o>
Print out the value of one or more options.
=item o option=value ...
+X<debugger command, o>
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
for a list of these.
=item < ?
+X<< debugger command, < >>
List out all pre-prompt Perl command actions.
=item < [ command ]
+X<< debugger command, < >>
Set an action (Perl command) to happen before every debugger prompt.
A multi-line command may be entered by backslashing the newlines.
=item < *
+X<< debugger command, < >>
Delete all pre-prompt Perl command actions.
=item << command
+X<< debugger command, << >>
Add an action (Perl command) to happen before every debugger prompt.
A multi-line command may be entered by backwhacking the newlines.
=item > ?
+X<< debugger command, > >>
List out post-prompt Perl command actions.
=item > command
+X<< debugger 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).
+couldn't have guessed this by now).
=item > *
+X<< debugger command, > >>
Delete all post-prompt Perl command actions.
=item >> command
+X<<< debugger 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 { ?
+X<debugger command, {>
List out pre-prompt debugger commands.
C<do { ... }>.
=item { *
+X<debugger command, {>
Delete all pre-prompt debugger commands.
=item {{ command
+X<debugger 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
+X<debugger command, !>
Redo a previous command (defaults to the previous command).
=item ! -number
+X<debugger command, !>
Redo number'th previous command.
=item ! pattern
+X<debugger command, !>
Redo last command that started with pattern.
See C<o recallCommand>, too.
=item !! cmd
+X<debugger command, !!>
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,
information.
=item source file
+X<debugger command, source>
Read and execute debugger commands from I<file>.
I<file> may itself contain C<source> commands.
=item H -number
+X<debugger command, H>
Display last n commands. Only commands longer than one character are
listed. If I<number> is omitted, list them all.
=item q or ^D
+X<debugger command, q>
+X<debugger command, ^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
if you want to step through global destruction.
=item R
+X<debugger command, 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
options B<-w>, B<-I>, and B<-e>.
=item |dbcmd
+X<debugger command, |>
Run the debugger command, piping DB::OUT into your current pager.
=item ||dbcmd
+X<debugger command, ||>
Same as C<|dbcmd> but DB::OUT is temporarily C<select>ed as well.
=item = [alias value]
+X<debugger command, =>
Define a command alias, like
Perl debugger, use a leading semicolon, too.
=item m expr
+X<debugger command, m>
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 M
+X<debugger command, M>
Displays all loaded modules and their versions
=item man [manpage]
+X<debugger command, man>
Despite its name, this calls your system's default documentation
viewer on the given page, or on the viewer itself if I<manpage> is
=over 12
=item C<recallCommand>, C<ShellBang>
+X<debugger option, recallCommand>
+X<debugger option, ShellBang>
The characters used to recall command or spawn shell. By
default, both are set to C<!>, which is unfortunate.
=item C<pager>
+X<debugger option, pager>
Program to use for output of pager-piped commands (those beginning
with a C<|> character.) By default, C<$ENV{PAGER}> will be used.
will not be readable when sent through the pager.
=item C<tkRunning>
+X<debugger option, tkRunning>
Run Tk while prompting (with ReadLine).
=item C<signalLevel>, C<warnLevel>, C<dieLevel>
+X<debugger option, signalLevel> X<debugger option, warnLevel>
+X<debugger option, dieLevel>
Level of verbosity. By default, the debugger leaves your exceptions
and warnings alone, because altering them can break correctly running
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
+came from C<eval'ed> 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.
destroy any program that takes its exception handling seriously.
=item C<AutoTrace>
+X<debugger option, AutoTrace>
Trace mode (similar to C<t> command, but can be put into
C<PERLDB_OPTS>).
=item C<LineInfo>
+X<debugger option, 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
debugger.
=item C<inhibit_exit>
+X<debugger option, inhibit_exit>
If 0, allows I<stepping off> the end of the script.
=item C<PrintRet>
+X<debugger option, PrintRet>
Print return value after C<r> command if set (default).
=item C<ornaments>
+X<debugger option, ornaments>
Affects screen appearance of the command line (see L<Term::ReadLine>).
There is currently no way to disable these, which can render
This is considered a bug.
=item C<frame>
+X<debugger option, 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
next option:
=item C<maxTraceLen>
+X<debugger option, maxTraceLen>
Length to truncate the argument list when the C<frame> option's
bit 4 is set.
=item C<windowSize>
+X<debugger option, windowSize>
Change the size of code list window (default is 10 lines).
=over 12
=item C<arrayDepth>, C<hashDepth>
+X<debugger option, arrayDepth> X<debugger option, hashDepth>
Print only first N elements ('' for all).
=item C<dumpDepth>
+X<debugger option, dumpDepth>
Limit recursion depth to N levels when dumping structures.
Negative values are interpreted as infinity. Default: infinity.
=item C<compactDump>, C<veryCompact>
+X<debugger option, compactDump> X<debugger option, veryCompact>
Change the style of array and hash output. If C<compactDump>, short array
may be printed on one line.
=item C<globPrint>
+X<debugger option, globPrint>
Whether to print contents of globs.
=item C<DumpDBFiles>
+X<debugger option, DumpDBFiles>
Dump arrays holding debugged files.
=item C<DumpPackages>
+X<debugger option, DumpPackages>
Dump symbol tables of packages.
=item C<DumpReused>
+X<debugger option, DumpReused>
Dump contents of "reused" addresses.
=item C<quote>, C<HighBit>, C<undefPrint>
+X<debugger option, quote> X<debugger option, HighBit>
+X<debugger option, 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
with their high bit set are printed verbatim.
=item C<UsageOnly>
+X<debugger option, UsageOnly>
Rudimentary per-package memory usage dump. Calculates total
size of strings found in variables in the package. This does not
=over 12
=item C<TTY>
+X<debugger option, TTY>
The TTY to use for debugging I/O.
=item C<noTTY>
+X<debugger option, 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
possible.
=item C<ReadLine>
+X<debugger option, ReadLine>
If false, readline support in the debugger is disabled in order
to debug applications that themselves use ReadLine.
=item C<NonStop>
+X<debugger option, NonStop>
If set, the debugger goes into non-interactive mode until interrupted, or
programmatically by setting $DB::signal or $DB::single.
commands typed into the debugger.
=item Stack backtrace
+X<backtrace> X<stack, backtrace>
Here's an example of what a stack backtrace via C<T> command might
look like:
=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:
+BEGIN, UNITCHECK 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;
your Perl as a C programmer might.
=head2 The Perl Profiler
+X<profile> X<profiling> X<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
interpret the information in that profile.
=head1 Debugging regular expressions
+X<regular expression, debugging>
+X<regex, debugging> X<regexp, debugging>
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
L<perldebguts/"Debugging regular expressions">.
=head1 Debugging memory usage
+X<memory usage>
Perl contains internal support for reporting its own memory usage,
but this is a fairly advanced concept that requires some understanding