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 use strict; and use warnings;?

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

If you're looking for the nitty gritty details of how the debugger is implemented, you may prefer to read perldebguts.

For in-depth technical usage details, see perl5db.pl, the documentation of the debugger itself.

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

If Perl is called with the -d switch, the variable $^P will hold a true value. This is useful if you need to know if your code is running under the debugger:

if ( $^P ) {
    # running under the debugger
}

See "$^P" in perlvar for more information on the variable.

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