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 h
COMMAND
, you'll get help on that debugger
command.
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.
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 b
SUBNAME
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
c
c
LINE
This command continues execution, optionally inserting a
one-time-only breakpoint at the specified
LINE
.
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 Section
20.4.
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.
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::OUT
EXPR
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 V
CURRENTPACKAGE
, 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.
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 l
MIN+INCR
form lists
INCR
+1
lines,
starting at MIN
. The
l
MIN-MAX
form
lists lines MIN
through
MAX
.
-
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.
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 "
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
<
< ?
<
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
select
ed 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()
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
exec
ing 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 later
in this chapter. The O
OPTION
form sets each of the listed
debugger options to 1
. If a question mark
follows an OPTION
, its current
value is displayed.
The O
OPTION
=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> OOPTION
="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 Section 20.3.3 for a
list of these.