Debugger Commands

The debugger understands the following commands.

- 
-

Lists the previous few lines.

. 
.

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

/pattern/ 
/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.

A 
A

Deletes all installed actions.

a 
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 
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 
b subname [condition]

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

b 
b load filename

Sets a breakpoint on requireing the given file.

b 
b postpone subname [condition]

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

b 
b compile subname

Stops after the subroutine has been compiled.

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

D 
D

Deletes all installed breakpoints

d 
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 
f filename

Switches to viewing a different file.

H 
H [-number]

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

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

L 
L

Lists all breakpoints and actions for the current file.

l 
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 
m expr

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

m 
m class

Prints methods callable via the given class.

n 
n

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

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

Sets or queries option values. If omitted, val defaults to . 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 "Customizing the Debugger" later in this chapter for more information.

p 
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 
q or ^D

Quits the debugger.

R 
R

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.

r 
r

Returns from current subroutine.

S 
S [[!]pattern]

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

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

T 
T

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.

t 
t

Toggles trace mode.

t 
t expr

Traces through execution of expr.

v 
v

Shows versions of loaded modules.

V 
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 
w [line]

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

X 
X [vars]

Same as V currentpackage[vars].

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