CONTENTS

• NAME
• DESCRIPTION
• The Perl Debugger
  • Calling the Debugger
  • Debugger Commands
  • Configurable Options
  • Debugger Input/Output
  • Debugging Compile-Time Statements
  • Debugger Customization
  • Readline Support / History in the Debugger
  • Editor Support for Debugging
  • The Perl Profiler
• Debugging Regular Expressions
• Debugging Memory Usage
• SEE ALSO
• BUGS

#NAME

perldebug - Perl debugging

#DESCRIPTION

First of all, have you tried using the -w switch?

If you're new to the Perl debugger, you may prefer to read perldebtut, which is a tutorial introduction to the debugger.

#The Perl Debugger

If you invoke Perl with the -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 -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 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 about to execute, rather than the one it has just executed.

Any command not recognized by the debugger is directly executed (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 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 ; or perhaps a +, or by wrapping it with parentheses or braces.

#Calling the Debugger

There are several ways to call the debugger:

#perl -d program_name

On the given program identified by program_name.

#perl -d -e 0

Interactively supply an arbitrary expression using -e.

#perl -d:Ptkdb program_name

Debug a given program via the Devel::Ptkdb GUI.

#perl -dt threaded_program_name

Debug a given program using threads (experimental).

#Debugger Commands

The interactive debugger understands the following commands:

#h

Prints out a summary help message

#h [command]

Prints out a help message for the given debugger command.

#h h

The special argument of h h produces the entire help page, which is quite long.

If the output of the 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 o pager=... command.

#p expr

Same as print {$DB::OUT} expr in the current package. In particular, because this is just Perl's own print function, this means that nested data structures and objects are not dumped, unlike with the x command.

The DB::OUT filehandle is opened to /dev/tty, regardless of where STDOUT may be redirected to.

#x [maxdepth] 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 print function in Perl. When dumping hashes, you'll probably prefer 'x \%h' rather than 'x %h'. See Dumpvalue if you'd like to do this yourself.

The output format is governed by multiple options described under "Configurable Options".

If the maxdepth is included, it must be a numeral N; the value is dumped only N levels deep, as if the dumpDepth option had been temporarily set to N.

#V [pkg [vars]]

Display all (or some) variables in package (defaulting to 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 $) there, just the symbol names, like this:

V DB filename line

Use ~pattern and !pattern for positive and negative regexes.

This is similar to calling the x command on each applicable var.

#X [vars]

Same as V currentpackage [vars].

#y [level [vars]]

Display all (or some) lexical variables (mnemonic: mY variables) in the current scope or level scopes higher. You can limit the variables that you see with vars which works exactly as it does for the V and X commands. Requires the PadWalker module version 0.08 or higher; will warn if this isn't installed. Output is pretty-printed in the same style as for V and the format is controlled by the same options.

#T

Produce a stack backtrace. See below for details on its output.

#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.

#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.

#r

Continue until the return from the current subroutine. Dump the return value if the PrintRet option is set (default).

#<CR>

Repeat last n or s command.

#c [line|sub]

Continue, optionally inserting a one-time-only breakpoint at the specified line or subroutine.

#l

List next window of lines.

#l min+incr

List incr+1 lines starting at min.

#l min-max

List lines min through max. l - is synonymous to -.

#l line

List a single line.

#l subname

List first window of lines from subroutine. subname may be a variable that contains a code reference.

#-

List previous window of lines.

#v [line]

View a few lines of code around the current line.

#.

Return the internal debugger pointer to the line last executed, and print out that line.

#f filename

Switch to viewing a different file or eval statement. If filename is not a full pathname found in the values of %INC, it is considered a regex.

evaled strings (when accessible) are considered to be filenames: f (eval 7) and f eval 7\b access the body of the 7th evaled string (in the order of execution). The bodies of the currently executed eval and of evaled strings that define subroutines are saved and thus accessible.

#/pattern/

Search forwards for pattern (a Perl regex); final / is optional. The search is case-insensitive by default.

#?pattern?

Search backwards for pattern; final ? is optional. The search is case-insensitive by default.

#L [abw]

List (default all) actions, breakpoints and watch expressions

#S [[!]regex]

List subroutine names [not] matching the regex.

#t

Toggle trace mode (see also the AutoTrace option).

#t expr

Trace through execution of expr. See "Frame Listing Output Examples" in perldebguts for examples.

#b

Sets breakpoint on current line

#b [line] [condition]

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 if:

b 237 $x > 30
b 237 ++$count237 < 11
b 33 /pattern/i

#b subname [condition]

Set a breakpoint before the first line of the named subroutine. subname may be a variable containing a code reference (in this case condition is not supported).

#b postpone subname [condition]

Set a breakpoint at first line of subroutine after it is compiled.

#b load filename

Set a breakpoint before the first executed line of the filename, which should be a full pathname found amongst the %INC values.

#b compile subname

Sets a breakpoint before the first statement executed after the specified subroutine is compiled.

#B line

Delete a breakpoint from the specified line.

#B *

Delete all installed breakpoints.

#a [line] command

Set an action to be done before the line is executed. If 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"

#A line

Delete an action from the specified line.

#A *

Delete all installed actions.

#w expr

Add a global watch-expression. Whenever a watched global changes the debugger will stop and display the old and new values.

#