Debugger Commands (Programming Perl)

20.2. Debugger Commands

When you type commands into the debugger, you don't need to terminate them with a semicolon. Use a backslash to continue lines (but only in the debugger).

Since the debugger uses eval to execute commands, my, our, and local settings will disappear once the command returns. If a debugger command coincides with some function in your own program, simply precede the function call with anything that doesn't look like a debugger command, such as a leading ; or a +.

If the output of a debugger built-in command scrolls past your screen, just precede the command with a leading pipe symbol so it's run through your pager:

DB<1> |h

The debugger has plenty of commands, and we divide them (somewhat arbitrarily) into stepping and running, breakpoints, tracing, display, locating code, automatic command execution, and, of course, miscellaneous.

Perhaps the most important command is h, which provides help. If you type h h at the debugger prompt, you'll get a compact help listing designed to fit on one screen. If you type hCOMMAND, you'll get help on that debugger command.

20.2.1. Stepping and Running

The debugger operates by stepping through your program line by line. The following commands let you control what you skip over and where you stop.

s
s EXPR: The s debugger command single-steps through the program. That is, the debugger will execute the next line of your program until another statement is reached, descending into subroutine calls as necessary. If the next line to execute involves a function call, then the debugger stops at the first line inside that function. If an EXPR is supplied that includes function calls, these will be single-stepped, too.
n
n EXPR: The n command executes subroutine calls, without stepping through them, until the beginning of the next statement at this same level (or higher). If an EXPR is supplied that includes function calls, those functions will be executed with stops before each statement.
<ENTER>: If you just hit enter at the debugger prompt, the previous n or s command is repeated.
.: The . command returns the internal debugger pointer to the line last executed and prints out that line.
r: This command continues until the currently executing subroutine returns. It displays the return value if the PrintRet option is set, which it is by default.

20.2.2. Breakpoints

b

b LINE

b CONDITION

b LINE CONDITION

b SUBNAME

b SUBNAME CONDITION

b postpone SUBNAME

b postpone SUBNAME CONDITION

b compile SUBNAME

b load FILENAME

The b debugger command sets a breakpoint before LINE, telling the debugger to stop the program at that point so that you can poke around. If LINE is omitted, sets a breakpoint on the line that's about to execute. If CONDITION is specified, it's evaluated each time the statement is reached: a breakpoint is triggered only if CONDITION is true. Breakpoints may only be set on lines that begin an executable statement. Note that conditions don't use if:

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

The bSUBNAME form sets a (possibly conditional) breakpoint before the first line of the named subroutine. SUBNAME may be a variable containing a code reference; if so, CONDITION is not supported.

There are several ways to set a breakpoint on code that hasn't even been compiled yet. The b postpone form sets a (possibly conditional) breakpoint at the first line of SUBNAME after it is compiled.

The b compile form sets a breakpoint on the first statement to be executed after SUBNAME is compiled. Note that unlike the postpone form, this statement is outside the subroutine in question because the subroutine hasn't been called yet, only compiled.

The b load form sets a breakpoint on the first executed line of the file. The FILENAME should be a full pathname as found in the %INC values.

d

d LINE

This command deletes the breakpoint at LINE; if omitted, it deletes the breakpoint on the line about to execute.

D

This command deletes all breakpoints.

L

This command lists all the breakpoints and actions.

c

c LINE

This command continues execution, optionally inserting a one-time-only breakpoint at the specified LINE.

20.2.3. Tracing

T: This command produces a stack backtrace.
t
t EXPR: This command toggles trace mode, which prints out every line in your program as it is evaluated. See also the AutoTrace option discussed later in this chapter. If an EXPR is provided, the debugger will trace through its execution. See also the later section Section 20.4, "Unattended Execution".
W
W EXPR: This command adds EXPR as a global watch expression. (A watch expression is an expression that will cause a breakpoint when its value changes.) If no EXPR is provided, all watch expressions are deleted.

20.2.4. Display

Perl's debugger has several commands for examining data structures while your program is stopped at a breakpoint.

p

p EXPR

This command is the same as print DB::OUTEXPR in the current package. In particular, since this is just Perl's own print function, nested data structures and objects are not shown--use the x command for that. The DB::OUT handle prints to your terminal (or perhaps an editor window) no matter where standard output may have been redirected.

x

x EXPR

The x command evaluates its expression in list context and displays the result, pretty-printed. That is, nested data structures are printed out recursively and with unviewable characters suitably encoded.

V

V PKG

V PKG VARS

This command displays all (or when you specify VARS, some) variables in the specified PKG (defaulting to the main package) using a pretty printer. Hashes show their keys and values, control characters are rendered legibly, nested data structures print out in a legible fashion, and so on. This is similar to calling the x command on each applicable variable, except that x works with lexical variables, too. Also, here you type the identifiers without a type specifier such as $ or @, like this:

V Pet::Camel SPOT FIDO

In place of a variable name in VARS, you can use ~PATTERN or !PATTERN to print existing variables whose names either match or don't match the specified pattern.

X

X VARS

This command is the same as VCURRENTPACKAGE, where CURRENTPACKAGE is the package that the current line was compiled into.

H

H -NUMBER

This command displays the last NUMBER commands. Only commands longer than one character are stored in the history. (Most of them would be s or n, otherwise.) If NUMBER is omitted, all commands are listed.

20.2.5. Locating Code

Inside the debugger, you can extract and display parts of your program with these commands.

l

l LINE

l SUBNAME

l MIN+INCR

l MIN-MAX

The l command lists next the few lines of your program, or the specified LINE if provided, or the first few lines of the SUBNAME subroutine or code reference.

The lMIN+INCR form lists INCR+1 lines, starting at MIN. The lMIN-MAX form lists lines MIN through MAX.

-

This command lists the previous few lines of your program.

w

w LINE

Lists a window (a few lines) around the given source LINE, or the current line if no LINE is supplied.

f FILENAME

This command lets you view a different program or eval statement. If the FILENAME is not a full pathname as found in the values of %INC, it is interpreted as a regular expression to find the filename you mean.

/PATTERN/

This command searches forward in the program for PATTERN; the final / is optional. The entire PATTERN is optional, too, and if omitted, repeats the previous search.

?PATTERN?

This command searches backward for PATTERN; the final ? is optional. It repeats the previous search if PATTERN is omitted.

S

S PATTERN

S !PATTERN

The S command lists those subroutine names matching (or, with !, those not matching) PATTERN. If no PATTERN is provided, all subroutines are listed.

20.2.6. Actions and Command Execution

From inside the debugger, you can specify actions to be taken at particular times. You can also launch external programs.

a

a COMMAND

a LINE

a LINE COMMAND

This command sets an action to take before LINE executes, or the current line if LINE is omitted. For example, this prints out $foo every time line 53 is reached:

a 53 print "DB FOUND $foo\n"

If no COMMAND is specified, the action on the specified LINE is deleted. With neither LINE nor COMMAND, the action on the current line is deleted.

A

The A debugger command deletes all actions.

<

< ?

< EXPR

<< EXPR

The <EXPR form specifies a Perl expression to be evaluated before every debugger prompt. You can add another expression with the <<EXPR form, list them with < ?, and delete them all with a plain <.

>

> ?

> EXPR

>> EXPR

The > commands behave just like their < cousins but are executed after the debugger prompt instead of before.

{

{ ?

{ COMMAND

{{ COMMAND

The { debugger commands behave just like < but specify a debugger command to be executed before the debugger prompt instead of a Perl expression. A warning is issued if you appear to have accidentally entered a block of code instead. If that's what you really mean to do, write it with ;{ ... } or even do { ... }.

!

! NUMBER

! -NUMBER

!PATTERN

A lone ! repeats the previous command. The NUMBER specifies which command from the history to execute; for instance, ! 3 executes the third command typed into the debugger. If a minus sign precedes the NUMBER, the commands are counted backward: ! -3 executes the third-to-last command. If a PATTERN (no slashes) is provided instead of a NUMBER, the last command that began with PATTERN is executed. See also the recallCommand debugger option.)

!! CMD

This debugger command runs the external command CMD in a subprocess, which will read from DB::IN and write to DB::OUT. See also the shellBang debugger option. This command uses whatever shell is named in $ENV{SHELL}, which can sometimes interfere with proper interpretation of status, signal, and core dump information. If you want a consistent exit value from the command, set $ENV{SHELL} to /bin/sh.

|

|DBCMD

||PERLCMD

The |DBCMD command runs the debugger command DBCMD, piping DB::OUT to $ENV{PAGER}. This is often used with commands that would otherwise produce long output, such as:

DB<1> |V main

Note that this is for debugger commands, not commands you'd type from your shell. If you wanted to pipe the external command who through your pager, you could do something like this:

DB<1> !!who | more

The ||PERLCMD command is like |DBCMD, but DB::OUT is temporarily selected as well, so any commands that call print, printf, or write without a filehandle will also be sent down the pipe. For example, if you had a function that generated loads of output by calling print, you'd use this command instead of the previous one to page through that output:

DB<1> sub saywho { print "Users: ", `who` }
DB<2> ||sawwho()

20.2.7. Miscellaneous Commands

q and ^D

These commands quit the debugger. This is the recommended way to exit, although typing exit twice sometimes works. Set the inhibit_exit option to 0 if you want to be able to step off the end of the program and remain in the debugger anyway. You may also need to set $DB::finished to 0 if you want to step through global destruction.

R

Restart the debugger by execing a new session. The debugger tries to maintain your history across sessions, but some internal settings and command-line options may be lost. The following settings are currently preserved: history, breakpoints, actions, debugger options, and the Perl command-line options -w, -I, and -e.

=

= ALIAS

= ALIAS VALUE

This command prints out the current value of ALIAS if no VALUE is given. With a VALUE, it defines a new debugger command with the name ALIAS. If both ALIAS and VALUE are omitted, all current aliases are listed. For example:

= quit q

An ALIAS should be a simple identifier, and should translate to a simple identifier as well. You can do more sophisticated aliasing by adding your own entries to %DB::aliases directly. See "Debugger Customization" later in this chapter.

man

man MANPAGE

This command calls your system's default documentation viewer on the given page or on the viewer itself if MANPAGE is omitted. If that viewer is man, the current %Config information is used to invoke it. The "perl" prefix will be automatically supplied for you when necessary; this lets you type man debug and man op from the debugger.

On systems that do not normally have the man utility, the debugger invokes perldoc; if you want to change that behavior, set $DB::doccmd to whatever viewer you like. This may be set in an rc file or through direct assignment.

O

O OPTION ...

O OPTION? ...

O OPTION=VALUE...

The O command lets you manipulate debugger options, which are listed in Section 20.3.3, "Debugger Options" later in this chapter. The OOPTION form sets each of the listed debugger options to 1. If a question mark follows an OPTION, its current value is displayed.

The OOPTION=VALUE form sets the values; if VALUE has internal whitespace, it should be quoted. For example, you could set O pager="less -MQeicsNfr" to use less with those specific flags. You may use either single or double quotes, but if you do, you must escape embedded instances of the same sort of quote that you began with. You must also escape any backslash that immediately precedes the quote but is not meant to escape the quote itself. In other words, just follow single-quoting rules irrespective of the quote actually used. The debugger responds by showing you the value of the option just set, always using single-quoted notation for its output:

DB<1> O OPTION='this isn\'t bad'
               OPTION = 'this isn\'t bad'

DB<2> O OPTION="She said, \" Isn't it?\""
               OPTION = 'She said, "Isn\'t it?"'

For historical reasons, the =VALUE is optional, but defaults to 1 only where safe to do so--that is, mostly for Boolean options. It is better to assign a specific VALUE using =. The OPTION can be abbreviated, but unless you're trying to be intentionally cryptic, it probably should not be. Several options can be set together. See the section Section 20.3.3, "Debugger Options" for a list of these.