1238 lines
38 KiB
Plaintext
1238 lines
38 KiB
Plaintext
|
=head1 NAME
|
||
|
X<debug> X<debugger>
|
||
|
|
||
|
perldebug - Perl debugging
|
||
|
|
||
|
=head1 DESCRIPTION
|
||
|
|
||
|
First of all, have you tried using L<C<use strict;>|strict> and
|
||
|
L<C<use warnings;>|warnings>?
|
||
|
|
||
|
If you're new to the Perl debugger, you may prefer to read
|
||
|
L<perldebtut>, which is a tutorial introduction to the debugger.
|
||
|
|
||
|
If you're looking for the nitty gritty details of how the debugger is
|
||
|
I<implemented>, you may prefer to read L<perldebguts>.
|
||
|
|
||
|
=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:
|
||
|
X<-d>
|
||
|
|
||
|
$ 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.)
|
||
|
|
||
|
Note that the said C<eval> is bound by an implicit scope. As a
|
||
|
result any newly introduced lexical variable or any modified
|
||
|
capture buffer content is lost after the eval. The debugger is a
|
||
|
nice environment to learn Perl, but if you interactively experiment using
|
||
|
material which should be in the same scope, stuff it in one line.
|
||
|
|
||
|
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 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 interactive debugger understands the following commands:
|
||
|
|
||
|
=over 12
|
||
|
|
||
|
=item h
|
||
|
X<debugger command, h>
|
||
|
|
||
|
Prints out a summary help message
|
||
|
|
||
|
=item h [command]
|
||
|
|
||
|
Prints out a help message for the given debugger command.
|
||
|
|
||
|
=item h h
|
||
|
|
||
|
The special argument of C<h h> produces the entire help page, which is quite long.
|
||
|
|
||
|
If the output of the C<h 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 h
|
||
|
|
||
|
You may change the pager which is used via C<o pager=...> command.
|
||
|
|
||
|
=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
|
||
|
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 [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
|
||
|
recursively, unlike the real C<print> function in Perl. When dumping
|
||
|
hashes, you'll probably prefer 'x \%h' rather than 'x %h'.
|
||
|
See L<Dumpvalue> if you'd like to do this yourself.
|
||
|
|
||
|
The output format is governed by multiple options described under
|
||
|
L</"Configurable Options">.
|
||
|
|
||
|
If the C<maxdepth> is included, it must be a numeral I<N>; the value is
|
||
|
dumped only I<N> levels deep, as if the C<dumpDepth> option had been
|
||
|
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
|
||
|
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]
|
||
|
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
|
||
|
variables that you see with I<vars> which works exactly as it does
|
||
|
for the C<V> and C<X> commands. Requires the C<PadWalker> module
|
||
|
version 0.08 or higher; will warn if this isn't installed. Output
|
||
|
is pretty-printed in the same style as for C<V> and the format is
|
||
|
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
|
||
|
function calls, those functions will be executed with stops before
|
||
|
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).
|
||
|
|
||
|
=item <CR>
|
||
|
|
||
|
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.
|
||
|
|
||
|
=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 -
|
||
|
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
|
||
|
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.
|
||
|
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 [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 [n]
|
||
|
X<debugger command, t>
|
||
|
|
||
|
Toggle trace mode (see also the C<AutoTrace> option).
|
||
|
Optional argument is the maximum number of levels to trace below
|
||
|
the current one; anything deeper than that will be silent.
|
||
|
|
||
|
=item t [n] expr
|
||
|
X<debugger command, t>
|
||
|
|
||
|
Trace through execution of C<expr>.
|
||
|
Optional first argument is the maximum number of levels to trace below
|
||
|
the current one; anything deeper than that will be silent.
|
||
|
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
|
||
|
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
|
||
|
|
||
|
If the line number is C<.>, sets a breakpoint on the current line:
|
||
|
|
||
|
b . $n > 100
|
||
|
|
||
|
=item b [file]:[line] [condition]
|
||
|
X<breakpoint>
|
||
|
X<debugger command, b>
|
||
|
|
||
|
Set a breakpoint before the given line in a (possibly different) file. 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 lib/MyModule.pm:237 $x > 30
|
||
|
b /usr/lib/perl5/site_perl/CGI.pm:100 ++$count100 < 11
|
||
|
|
||
|
=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 disable [file]:[line]
|
||
|
X<breakpoint>
|
||
|
X<debugger command, disable>
|
||
|
X<disable>
|
||
|
|
||
|
Disable the breakpoint so it won't stop the execution of the program.
|
||
|
Breakpoints are enabled by default and can be re-enabled using the C<enable>
|
||
|
command.
|
||
|
|
||
|
=item disable [line]
|
||
|
X<breakpoint>
|
||
|
X<debugger command, disable>
|
||
|
X<disable>
|
||
|
|
||
|
Disable the breakpoint so it won't stop the execution of the program.
|
||
|
Breakpoints are enabled by default and can be re-enabled using the C<enable>
|
||
|
command.
|
||
|
|
||
|
This is done for a breakpoint in the current file.
|
||
|
|
||
|
=item enable [file]:[line]
|
||
|
X<breakpoint>
|
||
|
X<debugger command, disable>
|
||
|
X<disable>
|
||
|
|
||
|
Enable the breakpoint so it will stop the execution of the program.
|
||
|
|
||
|
=item enable [line]
|
||
|
X<breakpoint>
|
||
|
X<debugger command, disable>
|
||
|
X<disable>
|
||
|
|
||
|
Enable the breakpoint so it will stop the execution of the program.
|
||
|
|
||
|
This is done for a breakpoint in the current file.
|
||
|
|
||
|
=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.
|
||
|
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
|
||
|
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. Whenever a watched global changes the
|
||
|
debugger will stop and display the old and new values.
|
||
|
|
||
|
=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
|
||
|
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</"Configurable Options">
|
||
|
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 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.
|
||
|
|
||
|
=item { [ command ]
|
||
|
|
||
|
Set an action (debugger command) to happen before every debugger prompt.
|
||
|
A multi-line command may be entered in the customary fashion.
|
||
|
|
||
|
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 { *
|
||
|
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,
|
||
|
their C<$ENV{SHELL}> variable) will be used, which can interfere
|
||
|
with proper interpretation of exit status or signal and coredump
|
||
|
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
|
||
|
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
|
||
|
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
|
||
|
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
|
||
|
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
|
||
|
|
||
|
= 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
|
||
|
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>
|
||
|
|
||
|
Display 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
|
||
|
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.
|
||
|
(./.perldb or ~/.perldb under Unix.)
|
||
|
|
||
|
|
||
|
=over 12
|
||
|
|
||
|
=item C<recallCommand>, C<ShellBang>
|
||
|
X<debugger option, recallCommand>
|
||
|
X<debugger option, ShellBang>
|
||
|
|
||
|
The characters used to recall a command or spawn a 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.
|
||
|
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>
|
||
|
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
|
||
|
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'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.
|
||
|
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>
|
||
|
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
|
||
|
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>
|
||
|
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
|
||
|
some output illegible on some displays, or with some pagers.
|
||
|
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
|
||
|
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>
|
||
|
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).
|
||
|
|
||
|
=back
|
||
|
|
||
|
The following options affect what happens with C<V>, C<X>, and C<x>
|
||
|
commands:
|
||
|
|
||
|
=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
|
||
|
by setting it to C<"> or C<'>, respectively. By default, characters
|
||
|
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
|
||
|
include lexicals in a module's file scope, or lost in closures.
|
||
|
|
||
|
=item C<HistFile>
|
||
|
X<debugger option, history, HistFile>
|
||
|
|
||
|
The path of the file from which the history (assuming a usable
|
||
|
Term::ReadLine backend) will be read on the debugger's startup, and to which
|
||
|
it will be saved on shutdown (for persistence across sessions). Similar in
|
||
|
concept to Bash's C<.bash_history> file.
|
||
|
|
||
|
=item C<HistSize>
|
||
|
X<debugger option, history, HistSize>
|
||
|
|
||
|
The count of the saved lines in the history (assuming C<HistFile> above).
|
||
|
|
||
|
=back
|
||
|
|
||
|
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:
|
||
|
|
||
|
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>
|
||
|
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
|
||
|
$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<"$ENV{HOME}/.perldbtty$$"> otherwise. This file is not
|
||
|
inspected for proper ownership, so security hazards are theoretically
|
||
|
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.
|
||
|
|
||
|
=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 LineInfo=listing 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
|
||
|
X<backtrace> X<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<< ==> >>.
|
||
|
|
||
|
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
|
||
|
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, 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 the 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 the 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.
|
||
|
|
||
|
You can mock TTY input to debugger by adding arbitrary commands to
|
||
|
@DB::typeahead. For example, your F<.perldb> file might contain:
|
||
|
|
||
|
sub afterinit { push @DB::typeahead, "b 4", "b 6"; }
|
||
|
|
||
|
Which would attempt to set breakpoints on lines 4 and 6 immediately
|
||
|
after debugger initialization. Note that @DB::typeahead is not a supported
|
||
|
interface and is subject to change in future releases.
|
||
|
|
||
|
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 / History in the Debugger
|
||
|
|
||
|
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 (such as
|
||
|
Term::ReadLine::Gnu, Term::ReadLine::Perl, ...) you will
|
||
|
have full editing capabilities much like those 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, including
|
||
|
lexical variables in the current scope if the C<PadWalker> module
|
||
|
is installed.
|
||
|
|
||
|
Without Readline support you may see the symbols "^[[A", "^[[C", "^[[B",
|
||
|
"^[[D"", "^H", ... when using the arrow keys and/or the backspace key.
|
||
|
|
||
|
=head2 Editor Support for Debugging
|
||
|
|
||
|
If you have the GNU'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.
|
||
|
|
||
|
Recent versions of Emacs come with a
|
||
|
start file for making B<emacs> act like a
|
||
|
syntax-directed editor that understands (some of) Perl's syntax.
|
||
|
See L<perlfaq3>.
|
||
|
|
||
|
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
|
||
|
X<profile> X<profiling> X<profiler>
|
||
|
|
||
|
If you wish to supply an alternative debugger for Perl to run,
|
||
|
invoke your script with a colon and a package argument given to the
|
||
|
B<-d> flag. Perl's alternative debuggers include a Perl profiler,
|
||
|
L<Devel::NYTProf>, which is available separately as a CPAN
|
||
|
distribution. To profile your Perl program in the file F<mycode.pl>,
|
||
|
just type:
|
||
|
|
||
|
$ perl -d:NYTProf mycode.pl
|
||
|
|
||
|
When the script terminates the profiler will create a database of the
|
||
|
profile information that you can turn into reports using the profiler's
|
||
|
tools. See <perlperf> for details.
|
||
|
|
||
|
=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
|
||
|
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
|
||
|
X<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 do have C<use strict> and C<use warnings> enabled, don't you?
|
||
|
|
||
|
L<perldebtut>,
|
||
|
L<perldebguts>,
|
||
|
L<re>,
|
||
|
L<DB>,
|
||
|
L<Devel::NYTProf>,
|
||
|
L<Dumpvalue>,
|
||
|
and
|
||
|
L<perlrun>.
|
||
|
|
||
|
When debugging a script that uses #! and is thus normally found in
|
||
|
$PATH, the -S option causes perl to search $PATH for it, so you don't
|
||
|
have to type the path or C<which $scriptname>.
|
||
|
|
||
|
$ perl -Sd foo.pl
|
||
|
|
||
|
=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.
|