Debugger Commands (Perl in a Nutshell, 2nd Edition)

6.2. Debugger Commands

The debugger understands the following commands.

Returns debugger pointer to the last-executed line and prints it out.

/pattern/

Searches forward for pattern; final / is optional.

?pattern?

?pattern?

Searches backward for pattern; final ? is optional.

< [command]

Sets a Perl command to run before every debugger prompt. A multiline command may be entered by backslashing the newlines. With no command, the list of actions is reset.


<< [command]

Adds to the list of Perl commands to run before each debugger prompt.

<CR>

<CR>

Repeats last n or s command.

> [command]

Sets a Perl command to run after the prompt when you've just given a command to return to executing the script. A multiline command may be entered by backslashing the newlines.

>> [command]

Adds to the list of Perl commands to run after each debugger prompt.

{

{ [commandline]

Sets a debugger command to run before each prompt.

{{

{{ [commandline]

Adds to the list of debugger commands to run before each prompt.

! [number]

Reruns a previous command (defaults to the last command executed).

! -number

Reruns numberth-to-last command.

! pattern

Reruns last command that started with pattern. See O recallCommand.

!! cmd

Runs cmd in a subprocess (which reads from DB::IN and writes to DB::OUT). See O shellBang.

| dbcmd

Runs specified debugger command, piping DB::OUT to $ENV{PAGER}.

|| dbcmd

Same as |dbcmd, but DB::OUT is temporarily select ed as well. Often used with commands that would otherwise produce long output, such as:

|V main

= [alias value]

Defines a command alias. If alias and valueare omitted, lists all current aliases.

Deletes all installed actions.

a [line] command

Sets an action to be done before the line is executed. The following steps are taken:

Checks for a breakpoint at this line
Prints the line if necessary
Performs any actions associated with the line
Prompts the user if at a breakpoint or in single-step mode
Evaluates the line

For example, the following prints the value of $foo (and DB FOUND) every time line 53 is passed:

a 53 print "DB FOUND $foo\n"

b [line] [condition]

Sets a breakpoint at line, which must begin an executable statement. If line is omitted, sets a breakpoint on the line that is about to be executed. condition, if given, is evaluated each time the statement is reached, and a breakpoint is taken if condition is true:

b 237 $x > 30
b 33 /pattern/i

b subname [condition]

Sets a (possibly conditional) breakpoint at the first line of the named subroutine.

b load filename

Sets a breakpoint on requireing the given file.

b postpone subname [condition]

Sets a (possibly conditional) breakpoint at the first line of subroutine subname after it has been compiled.

b compile subname

Stops after the subroutine has been compiled.

c [line | sub]

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

command

command

Executes command as a Perl statement. A semicolon is not needed at the end.

Deletes all installed breakpoints

d [line]

Deletes the breakpoint at the specified line. If line is omitted, deletes the breakpoint on the line that is about to be executed..

f filename

Switches to viewing a different file.

H [-number]

Displays last number commands. If number is omitted, it lists all previous commands. Only commands longer than one character are listed.

h [command]

Prints a help message, listing the available debugger commands.

If you supply another debugger command as an argument to the h command, it prints out the description for just that command. The command h h produces a more compact help listing designed to fit on one screen.

Lists all breakpoints and actions for the current file.

l [linespec]

If linespec is omitted, lists the next few lines. Otherwise, lists the lines specified by linespec, which can be one of the following:

line: Lists the single line line
min+incr: Lists incr+1 lines starting at min
min-max: Lists lines min through max
subname: Lists the first few lines from subroutine subname.

Also see the w and - commands.

m expr

evals the expression in array context and prints methods callable on the first element of the result.

m class

Prints methods callable via the given class.

Next. Passes over subroutine calls and executes the next statement at this level.

O [opt[="val"]] [opt'val'] [opt?]

Sets or queries option values. If omitted, val defaults to 1. opt? displays the value of option opt. opt can be abbreviated to the shortest unique string, and multiple options can be specified. The possible options are:

AutoTrace: Affects printing of messages at every possible breaking point.
frame: Enables printing of messages on entry and exit from subroutines.
inhibit_exit: Enables stepping off the end of the script.
maxTraceLen: Gives the maximum length of evals/args listed in the stack trace.
ornaments: Affects the appearance of the command line on the screen.
pager: Specifies the program to use for output of pager-piped commands (those beginning with a | character). Default value is $ENV{PAGER}.
PrintRet: Enables printing of return value after r command.
recallCommand, ShellBang: Specifies the characters used to recall previous commands or spawn a shell. By default, these are both set to !.

The following options affect what happens with the V, X, and x commands:

arrayDepth, hashDepth: Prints only to depth n ("" for all).
compactDump, veryCompact: Changes style of array and hash dumps.
DumpDBFiles: Dumps arrays holding debugged files.
DumpPackages: Dumps symbol tables of packages.
globPrint: Specifies whether to print contents of globs.
quote, HighBit, undefPrint: Changes style of string dump.
signalLevel, warnLevel, dieLevel: Specifies level of verbosity.
tkRunning: Runs Tk while prompting (with ReadLine).

During startup, debugger options are initialized from $ENV{PERLDB_OPTS}. You can set the additional initialization options TTY, noTTY, ReadLine, and NonStop there. See Section 6.4, "Customizing the Debugger" later in this chapter for more information.

p expr

Same as print DB::OUT expr in the current package. In particular, does not dump nested data structures and objects, unlike the x command. The DB::OUT handle is opened to /dev/tty (or perhaps an editor window) no matter where standard output may have been redirected to.

q or ^D

Quits the debugger.

Restarts the debugger. As much of your history is maintained across the sessions as possible, but some internal settings and command-line options may be lost.

Returns from current subroutine.

S [[!]pattern]

Lists subroutine names matching (or, if ! is specified, not matching) pattern. If pattern is omitted, lists all subroutines.

s [expr]

Single steps. Executes until it reaches the beginning of another statement, descending into subroutine calls. If an expression is supplied that includes a function call, the function is also single-stepped.

Produces a stack backtrace. For example:

DB<2> T
$ = 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 lefthand character ($ or @) tells whether the function was called in a scalar or list context. The example shows three lines because it was three functions deep when the stack backtrace ran.

Toggles trace mode.

t expr

Traces through execution of expr.

Shows versions of loaded modules.

V [pkg [vars]]

Displays all (or some) variables in package pkg using a data pretty-printer (which displays keys and their values for hashes, makes control characters printable, prints nested data structures in a legible fashion, and so on). pkg defaults to the main package. Make sure you enter the identifiers without a type specifier such as $ or @, like this:

V DB filename line

In place of a variable name, you can use ~pattern or !pattern to print existing variables with names that either match or don't match the specified regular expression.

w [line]

Lists a window of a few lines around the given line, or lists the current line if line is omitted.

X [vars]

Same as V currentpackage[vars].

x expr

evals the expression in a list context and dumps out the result in a pretty-printed fashion. Unlike the print command above, prints nested data structures recursively.