| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" ======================================================================== |
| 56 |
.\" |
| 57 |
.IX Title "PERLDEBUG 1" |
| 58 |
.TH PERLDEBUG 1 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide" |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
perldebug \- Perl debugging |
| 65 |
.IX Xref "debug debugger" |
| 66 |
.SH DESCRIPTION |
| 67 |
.IX Header "DESCRIPTION" |
| 68 |
First of all, have you tried using \f(CW\*(C`use strict;\*(C'\fR and |
| 69 |
\&\f(CW\*(C`use warnings;\*(C'\fR? |
| 70 |
.PP |
| 71 |
If you're new to the Perl debugger, you may prefer to read |
| 72 |
perldebtut, which is a tutorial introduction to the debugger. |
| 73 |
.PP |
| 74 |
If you're looking for the nitty gritty details of how the debugger is |
| 75 |
\&\fIimplemented\fR, you may prefer to read perldebguts. |
| 76 |
.PP |
| 77 |
For in-depth technical usage details, see perl5db.pl, the documentation |
| 78 |
of the debugger itself. |
| 79 |
.SH "The Perl Debugger" |
| 80 |
.IX Header "The Perl Debugger" |
| 81 |
If you invoke Perl with the \fB\-d\fR switch, your script runs under the |
| 82 |
Perl source debugger. This works like an interactive Perl |
| 83 |
environment, prompting for debugger commands that let you examine |
| 84 |
source code, set breakpoints, get stack backtraces, change the values of |
| 85 |
variables, etc. This is so convenient that you often fire up |
| 86 |
the debugger all by itself just to test out Perl constructs |
| 87 |
interactively to see what they do. For example: |
| 88 |
.IX Xref "-d" |
| 89 |
.PP |
| 90 |
.Vb 1 |
| 91 |
\& $ perl \-d \-e 42 |
| 92 |
.Ve |
| 93 |
.PP |
| 94 |
In Perl, the debugger is not a separate program the way it usually is in the |
| 95 |
typical compiled environment. Instead, the \fB\-d\fR flag tells the compiler |
| 96 |
to insert source information into the parse trees it's about to hand off |
| 97 |
to the interpreter. That means your code must first compile correctly |
| 98 |
for the debugger to work on it. Then when the interpreter starts up, it |
| 99 |
preloads a special Perl library file containing the debugger. |
| 100 |
.PP |
| 101 |
The program will halt \fIright before\fR the first run-time executable |
| 102 |
statement (but see below regarding compile-time statements) and ask you |
| 103 |
to enter a debugger command. Contrary to popular expectations, whenever |
| 104 |
the debugger halts and shows you a line of code, it always displays the |
| 105 |
line it's \fIabout\fR to execute, rather than the one it has just executed. |
| 106 |
.PP |
| 107 |
Any command not recognized by the debugger is directly executed |
| 108 |
(\f(CW\*(C`eval\*(C'\fR'd) as Perl code in the current package. (The debugger |
| 109 |
uses the DB package for keeping its own state information.) |
| 110 |
.PP |
| 111 |
Note that the said \f(CW\*(C`eval\*(C'\fR is bound by an implicit scope. As a |
| 112 |
result any newly introduced lexical variable or any modified |
| 113 |
capture buffer content is lost after the eval. The debugger is a |
| 114 |
nice environment to learn Perl, but if you interactively experiment using |
| 115 |
material which should be in the same scope, stuff it in one line. |
| 116 |
.PP |
| 117 |
For any text entered at the debugger prompt, leading and trailing whitespace |
| 118 |
is first stripped before further processing. If a debugger command |
| 119 |
coincides with some function in your own program, merely precede the |
| 120 |
function with something that doesn't look like a debugger command, such |
| 121 |
as a leading \f(CW\*(C`;\*(C'\fR or perhaps a \f(CW\*(C`+\*(C'\fR, or by wrapping it with parentheses |
| 122 |
or braces. |
| 123 |
.SS "Calling the Debugger" |
| 124 |
.IX Subsection "Calling the Debugger" |
| 125 |
There are several ways to call the debugger: |
| 126 |
.IP "perl \-d program_name" 4 |
| 127 |
.IX Item "perl -d program_name" |
| 128 |
On the given program identified by \f(CW\*(C`program_name\*(C'\fR. |
| 129 |
.IP "perl \-d \-e 0" 4 |
| 130 |
.IX Item "perl -d -e 0" |
| 131 |
Interactively supply an arbitrary \f(CW\*(C`expression\*(C'\fR using \f(CW\*(C`\-e\*(C'\fR. |
| 132 |
.IP "perl \-d:ptkdb program_name" 4 |
| 133 |
.IX Item "perl -d:ptkdb program_name" |
| 134 |
Debug a given program via the Devel::ptkdb GUI. |
| 135 |
.IP "perl \-dt threaded_program_name" 4 |
| 136 |
.IX Item "perl -dt threaded_program_name" |
| 137 |
Debug a given program using threads (experimental). |
| 138 |
.PP |
| 139 |
If Perl is called with the \f(CW\*(C`\-d\*(C'\fR switch, the variable \f(CW$^P\fR will hold a true |
| 140 |
value. This is useful if you need to know if your code is running under the |
| 141 |
debugger: |
| 142 |
.PP |
| 143 |
.Vb 3 |
| 144 |
\& if ( $^P ) { |
| 145 |
\& # running under the debugger |
| 146 |
\& } |
| 147 |
.Ve |
| 148 |
.PP |
| 149 |
See "$^P" in perlvar for more information on the variable. |
| 150 |
.SS "Debugger Commands" |
| 151 |
.IX Subsection "Debugger Commands" |
| 152 |
The interactive debugger understands the following commands: |
| 153 |
.IP h 12 |
| 154 |
.IX Xref "debugger command, h" |
| 155 |
.IX Item "h" |
| 156 |
Prints out a summary help message |
| 157 |
.IP "h [command]" 12 |
| 158 |
.IX Item "h [command]" |
| 159 |
Prints out a help message for the given debugger command. |
| 160 |
.IP "h h" 12 |
| 161 |
.IX Item "h h" |
| 162 |
The special argument of \f(CW\*(C`h h\*(C'\fR produces the entire help page, which is quite long. |
| 163 |
.Sp |
| 164 |
If the output of the \f(CW\*(C`h h\*(C'\fR command (or any command, for that matter) scrolls |
| 165 |
past your screen, precede the command with a leading pipe symbol so |
| 166 |
that it's run through your pager, as in |
| 167 |
.Sp |
| 168 |
.Vb 1 |
| 169 |
\& DB> |h h |
| 170 |
.Ve |
| 171 |
.Sp |
| 172 |
You may change the pager which is used via \f(CW\*(C`o pager=...\*(C'\fR command. |
| 173 |
.IP "p expr" 12 |
| 174 |
.IX Xref "debugger command, p" |
| 175 |
.IX Item "p expr" |
| 176 |
Same as \f(CW\*(C`print {$DB::OUT} expr\*(C'\fR in the current package. In particular, |
| 177 |
because this is just Perl's own \f(CW\*(C`print\*(C'\fR function, this means that nested |
| 178 |
data structures and objects are not dumped, unlike with the \f(CW\*(C`x\*(C'\fR command. |
| 179 |
.Sp |
| 180 |
The \f(CW\*(C`DB::OUT\*(C'\fR filehandle is opened to \fI/dev/tty\fR, regardless of |
| 181 |
where STDOUT may be redirected to. |
| 182 |
.IP "x [maxdepth] expr" 12 |
| 183 |
.IX Xref "debugger command, x" |
| 184 |
.IX Item "x [maxdepth] expr" |
| 185 |
Evaluates its expression in list context and dumps out the result in a |
| 186 |
pretty-printed fashion. Nested data structures are printed out |
| 187 |
recursively, unlike the real \f(CW\*(C`print\*(C'\fR function in Perl. When dumping |
| 188 |
hashes, you'll probably prefer 'x \e%h' rather than 'x \f(CW%h\fR'. |
| 189 |
See Dumpvalue if you'd like to do this yourself. |
| 190 |
.Sp |
| 191 |
The output format is governed by multiple options described under |
| 192 |
"Configurable Options". |
| 193 |
.Sp |
| 194 |
If the \f(CW\*(C`maxdepth\*(C'\fR is included, it must be a numeral \fIN\fR; the value is |
| 195 |
dumped only \fIN\fR levels deep, as if the \f(CW\*(C`dumpDepth\*(C'\fR option had been |
| 196 |
temporarily set to \fIN\fR. |
| 197 |
.IP "V [pkg [vars]]" 12 |
| 198 |
.IX Xref "debugger command, V" |
| 199 |
.IX Item "V [pkg [vars]]" |
| 200 |
Display all (or some) variables in package (defaulting to \f(CW\*(C`main\*(C'\fR) |
| 201 |
using a data pretty-printer (hashes show their keys and values so |
| 202 |
you see what's what, control characters are made printable, etc.). |
| 203 |
Make sure you don't put the type specifier (like \f(CW\*(C`$\*(C'\fR) there, just |
| 204 |
the symbol names, like this: |
| 205 |
.Sp |
| 206 |
.Vb 1 |
| 207 |
\& V DB filename line |
| 208 |
.Ve |
| 209 |
.Sp |
| 210 |
Use \f(CW\*(C`~pattern\*(C'\fR and \f(CW\*(C`!pattern\*(C'\fR for positive and negative regexes. |
| 211 |
.Sp |
| 212 |
This is similar to calling the \f(CW\*(C`x\*(C'\fR command on each applicable var. |
| 213 |
.IP "X [vars]" 12 |
| 214 |
.IX Xref "debugger command, X" |
| 215 |
.IX Item "X [vars]" |
| 216 |
Same as \f(CW\*(C`V currentpackage [vars]\*(C'\fR. |
| 217 |
.IP "y [level [vars]]" 12 |
| 218 |
.IX Xref "debugger command, y" |
| 219 |
.IX Item "y [level [vars]]" |
| 220 |
Display all (or some) lexical variables (mnemonic: \f(CW\*(C`mY\*(C'\fR variables) |
| 221 |
in the current scope or \fIlevel\fR scopes higher. You can limit the |
| 222 |
variables that you see with \fIvars\fR which works exactly as it does |
| 223 |
for the \f(CW\*(C`V\*(C'\fR and \f(CW\*(C`X\*(C'\fR commands. Requires the PadWalker module |
| 224 |
version 0.08 or higher; will warn if this isn't installed. Output |
| 225 |
is pretty-printed in the same style as for \f(CW\*(C`V\*(C'\fR and the format is |
| 226 |
controlled by the same options. |
| 227 |
.IP T 12 |
| 228 |
.IX Xref "debugger command, T backtrace stack, backtrace" |
| 229 |
.IX Item "T" |
| 230 |
Produce a stack backtrace. See below for details on its output. |
| 231 |
.IP "s [expr]" 12 |
| 232 |
.IX Xref "debugger command, s step" |
| 233 |
.IX Item "s [expr]" |
| 234 |
Single step. Executes until the beginning of another |
| 235 |
statement, descending into subroutine calls. If an expression is |
| 236 |
supplied that includes function calls, it too will be single-stepped. |
| 237 |
.IP "n [expr]" 12 |
| 238 |
.IX Xref "debugger command, n" |
| 239 |
.IX Item "n [expr]" |
| 240 |
Next. Executes over subroutine calls, until the beginning |
| 241 |
of the next statement. If an expression is supplied that includes |
| 242 |
function calls, those functions will be executed with stops before |
| 243 |
each statement. |
| 244 |
.IP r 12 |
| 245 |
.IX Xref "debugger command, r" |
| 246 |
.IX Item "r" |
| 247 |
Continue until the return from the current subroutine. |
| 248 |
Dump the return value if the \f(CW\*(C`PrintRet\*(C'\fR option is set (default). |
| 249 |
.IP <CR> 12 |
| 250 |
.IX Item "<CR>" |
| 251 |
Repeat last \f(CW\*(C`n\*(C'\fR or \f(CW\*(C`s\*(C'\fR command. |
| 252 |
.IP "c [line|sub]" 12 |
| 253 |
.IX Xref "debugger command, c" |
| 254 |
.IX Item "c [line|sub]" |
| 255 |
Continue, optionally inserting a one-time-only breakpoint |
| 256 |
at the specified line or subroutine. |
| 257 |
.IP l 12 |
| 258 |
.IX Xref "debugger command, l" |
| 259 |
.IX Item "l" |
| 260 |
List next window of lines. |
| 261 |
.IP "l min+incr" 12 |
| 262 |
.IX Item "l min+incr" |
| 263 |
List \f(CW\*(C`incr+1\*(C'\fR lines starting at \f(CW\*(C`min\*(C'\fR. |
| 264 |
.IP "l min-max" 12 |
| 265 |
.IX Item "l min-max" |
| 266 |
List lines \f(CW\*(C`min\*(C'\fR through \f(CW\*(C`max\*(C'\fR. \f(CW\*(C`l \-\*(C'\fR is synonymous to \f(CW\*(C`\-\*(C'\fR. |
| 267 |
.IP "l line" 12 |
| 268 |
.IX Item "l line" |
| 269 |
List a single line. |
| 270 |
.IP "l subname" 12 |
| 271 |
.IX Item "l subname" |
| 272 |
List first window of lines from subroutine. \fIsubname\fR may |
| 273 |
be a variable that contains a code reference. |
| 274 |
.IP \- 12 |
| 275 |
.IX Xref "debugger command, -" |
| 276 |
List previous window of lines. |
| 277 |
.IP "v [line]" 12 |
| 278 |
.IX Xref "debugger command, v" |
| 279 |
.IX Item "v [line]" |
| 280 |
View a few lines of code around the current line. |
| 281 |
.IP . 12 |
| 282 |
.IX Xref "debugger command, ." |
| 283 |
Return the internal debugger pointer to the line last |
| 284 |
executed, and print out that line. |
| 285 |
.IP "f filename" 12 |
| 286 |
.IX Xref "debugger command, f" |
| 287 |
.IX Item "f filename" |
| 288 |
Switch to viewing a different file or \f(CW\*(C`eval\*(C'\fR statement. If \fIfilename\fR |
| 289 |
is not a full pathname found in the values of \f(CW%INC\fR, it is considered |
| 290 |
a regex. |
| 291 |
.Sp |
| 292 |
\&\f(CW\*(C`eval\*(C'\fRed strings (when accessible) are considered to be filenames: |
| 293 |
\&\f(CW\*(C`f (eval 7)\*(C'\fR and \f(CW\*(C`f eval 7\eb\*(C'\fR access the body of the 7th \f(CW\*(C`eval\*(C'\fRed string |
| 294 |
(in the order of execution). The bodies of the currently executed \f(CW\*(C`eval\*(C'\fR |
| 295 |
and of \f(CW\*(C`eval\*(C'\fRed strings that define subroutines are saved and thus |
| 296 |
accessible. |
| 297 |
.IP /pattern/ 12 |
| 298 |
.IX Item "/pattern/" |
| 299 |
Search forwards for pattern (a Perl regex); final / is optional. |
| 300 |
The search is case-insensitive by default. |
| 301 |
.IP ?pattern? 12 |
| 302 |
.IX Item "?pattern?" |
| 303 |
Search backwards for pattern; final ? is optional. |
| 304 |
The search is case-insensitive by default. |
| 305 |
.IP "L [abw]" 12 |
| 306 |
.IX Xref "debugger command, L" |
| 307 |
.IX Item "L [abw]" |
| 308 |
List (default all) actions, breakpoints and watch expressions |
| 309 |
.IP "S [[!]regex]" 12 |
| 310 |
.IX Xref "debugger command, S" |
| 311 |
.IX Item "S [[!]regex]" |
| 312 |
List subroutine names [not] matching the regex. |
| 313 |
.IP "t [n]" 12 |
| 314 |
.IX Xref "debugger command, t" |
| 315 |
.IX Item "t [n]" |
| 316 |
Toggle trace mode (see also the \f(CW\*(C`AutoTrace\*(C'\fR option). |
| 317 |
Optional argument is the maximum number of levels to trace below |
| 318 |
the current one; anything deeper than that will be silent. |
| 319 |
.IP "t [n] expr" 12 |
| 320 |
.IX Xref "debugger command, t" |
| 321 |
.IX Item "t [n] expr" |
| 322 |
Trace through execution of \f(CW\*(C`expr\*(C'\fR. |
| 323 |
Optional first argument is the maximum number of levels to trace below |
| 324 |
the current one; anything deeper than that will be silent. |
| 325 |
See "Frame Listing Output Examples" in perldebguts for examples. |
| 326 |
.IP b 12 |
| 327 |
.IX Xref "breakpoint debugger command, b" |
| 328 |
.IX Item "b" |
| 329 |
Sets breakpoint on current line |
| 330 |
.IP "b [line] [condition]" 12 |
| 331 |
.IX Xref "breakpoint debugger command, b" |
| 332 |
.IX Item "b [line] [condition]" |
| 333 |
Set a breakpoint before the given line. If a condition |
| 334 |
is specified, it's evaluated each time the statement is reached: a |
| 335 |
breakpoint is taken only if the condition is true. Breakpoints may |
| 336 |
only be set on lines that begin an executable statement. Conditions |
| 337 |
don't use \f(CW\*(C`if\*(C'\fR: |
| 338 |
.Sp |
| 339 |
.Vb 3 |
| 340 |
\& b 237 $x > 30 |
| 341 |
\& b 237 ++$count237 < 11 |
| 342 |
\& b 33 /pattern/i |
| 343 |
.Ve |
| 344 |
.Sp |
| 345 |
If the line number is \f(CW\*(C`.\*(C'\fR, sets a breakpoint on the current line: |
| 346 |
.Sp |
| 347 |
.Vb 1 |
| 348 |
\& b . $n > 100 |
| 349 |
.Ve |
| 350 |
.IP "b [file]:[line] [condition]" 12 |
| 351 |
.IX Xref "breakpoint debugger command, b" |
| 352 |
.IX Item "b [file]:[line] [condition]" |
| 353 |
Set a breakpoint before the given line in a (possibly different) file. If a |
| 354 |
condition is specified, it's evaluated each time the statement is reached: a |
| 355 |
breakpoint is taken only if the condition is true. Breakpoints may only be set |
| 356 |
on lines that begin an executable statement. Conditions don't use \f(CW\*(C`if\*(C'\fR: |
| 357 |
.Sp |
| 358 |
.Vb 2 |
| 359 |
\& b lib/MyModule.pm:237 $x > 30 |
| 360 |
\& b /usr/lib/perl5/site_perl/CGI.pm:100 ++$count100 < 11 |
| 361 |
.Ve |
| 362 |
.IP "b subname [condition]" 12 |
| 363 |
.IX Xref "breakpoint debugger command, b" |
| 364 |
.IX Item "b subname [condition]" |
| 365 |
Set a breakpoint before the first line of the named subroutine. \fIsubname\fR may |
| 366 |
be a variable containing a code reference (in this case \fIcondition\fR |
| 367 |
is not supported). |
| 368 |
.IP "b postpone subname [condition]" 12 |
| 369 |
.IX Xref "breakpoint debugger command, b" |
| 370 |
.IX Item "b postpone subname [condition]" |
| 371 |
Set a breakpoint at first line of subroutine after it is compiled. |
| 372 |
.IP "b load filename" 12 |
| 373 |
.IX Xref "breakpoint debugger command, b" |
| 374 |
.IX Item "b load filename" |
| 375 |
Set a breakpoint before the first executed line of the \fIfilename\fR, |
| 376 |
which should be a full pathname found amongst the \f(CW%INC\fR values. |
| 377 |
.IP "b compile subname" 12 |
| 378 |
.IX Xref "breakpoint debugger command, b" |
| 379 |
.IX Item "b compile subname" |
| 380 |
Sets a breakpoint before the first statement executed after the specified |
| 381 |
subroutine is compiled. |
| 382 |
.IP "B line" 12 |
| 383 |
.IX Xref "breakpoint debugger command, B" |
| 384 |
.IX Item "B line" |
| 385 |
Delete a breakpoint from the specified \fIline\fR. |
| 386 |
.IP "B *" 12 |
| 387 |
.IX Xref "breakpoint debugger command, B" |
| 388 |
.IX Item "B *" |
| 389 |
Delete all installed breakpoints. |
| 390 |
.IP "disable [file]:[line]" 12 |
| 391 |
.IX Xref "breakpoint debugger command, disable disable" |
| 392 |
.IX Item "disable [file]:[line]" |
| 393 |
Disable the breakpoint so it won't stop the execution of the program. |
| 394 |
Breakpoints are enabled by default and can be re-enabled using the \f(CW\*(C`enable\*(C'\fR |
| 395 |
command. |
| 396 |
.IP "disable [line]" 12 |
| 397 |
.IX Xref "breakpoint debugger command, disable disable" |
| 398 |
.IX Item "disable [line]" |
| 399 |
Disable the breakpoint so it won't stop the execution of the program. |
| 400 |
Breakpoints are enabled by default and can be re-enabled using the \f(CW\*(C`enable\*(C'\fR |
| 401 |
command. |
| 402 |
.Sp |
| 403 |
This is done for a breakpoint in the current file. |
| 404 |
.IP "enable [file]:[line]" 12 |
| 405 |
.IX Xref "breakpoint debugger command, disable disable" |
| 406 |
.IX Item "enable [file]:[line]" |
| 407 |
Enable the breakpoint so it will stop the execution of the program. |
| 408 |
.IP "enable [line]" 12 |
| 409 |
.IX Xref "breakpoint debugger command, disable disable" |
| 410 |
.IX Item "enable [line]" |
| 411 |
Enable the breakpoint so it will stop the execution of the program. |
| 412 |
.Sp |
| 413 |
This is done for a breakpoint in the current file. |
| 414 |
.IP "a [line] command" 12 |
| 415 |
.IX Xref "debugger command, a" |
| 416 |
.IX Item "a [line] command" |
| 417 |
Set an action to be done before the line is executed. If \fIline\fR is |
| 418 |
omitted, set an action on the line about to be executed. |
| 419 |
The sequence of steps taken by the debugger is |
| 420 |
.Sp |
| 421 |
.Vb 5 |
| 422 |
\& 1. check for a breakpoint at this line |
| 423 |
\& 2. print the line if necessary (tracing) |
| 424 |
\& 3. do any actions associated with that line |
| 425 |
\& 4. prompt user if at a breakpoint or in single\-step |
| 426 |
\& 5. evaluate line |
| 427 |
.Ve |
| 428 |
.Sp |
| 429 |
For example, this will print out \f(CW$foo\fR every time line |
| 430 |
53 is passed: |
| 431 |
.Sp |
| 432 |
.Vb 1 |
| 433 |
\& a 53 print "DB FOUND $foo\en" |
| 434 |
.Ve |
| 435 |
.IP "A line" 12 |
| 436 |
.IX Xref "debugger command, A" |
| 437 |
.IX Item "A line" |
| 438 |
Delete an action from the specified line. |
| 439 |
.IP "A *" 12 |
| 440 |
.IX Xref "debugger command, A" |
| 441 |
.IX Item "A *" |
| 442 |
Delete all installed actions. |
| 443 |
.IP "w expr" 12 |
| 444 |
.IX Xref "debugger command, w" |
| 445 |
.IX Item "w expr" |
| 446 |
Add a global watch-expression. Whenever a watched global changes the |
| 447 |
debugger will stop and display the old and new values. |
| 448 |
.IP "W expr" 12 |
| 449 |
.IX Xref "debugger command, W" |
| 450 |
.IX Item "W expr" |
| 451 |
Delete watch-expression |
| 452 |
.IP "W *" 12 |
| 453 |
.IX Xref "debugger command, W" |
| 454 |
.IX Item "W *" |
| 455 |
Delete all watch-expressions. |
| 456 |
.IP o 12 |
| 457 |
.IX Xref "debugger command, o" |
| 458 |
.IX Item "o" |
| 459 |
Display all options. |
| 460 |
.IP "o booloption ..." 12 |
| 461 |
.IX Xref "debugger command, o" |
| 462 |
.IX Item "o booloption ..." |
| 463 |
Set each listed Boolean option to the value \f(CW1\fR. |
| 464 |
.IP "o anyoption? ..." 12 |
| 465 |
.IX Xref "debugger command, o" |
| 466 |
.IX Item "o anyoption? ..." |
| 467 |
Print out the value of one or more options. |
| 468 |
.IP "o option=value ..." 12 |
| 469 |
.IX Xref "debugger command, o" |
| 470 |
.IX Item "o option=value ..." |
| 471 |
Set the value of one or more options. If the value has internal |
| 472 |
whitespace, it should be quoted. For example, you could set \f(CW\*(C`o |
| 473 |
pager="less \-MQeicsNfr"\*(C'\fR to call \fBless\fR with those specific options. |
| 474 |
You may use either single or double quotes, but if you do, you must |
| 475 |
escape any embedded instances of same sort of quote you began with, |
| 476 |
as well as any escaping any escapes that immediately precede that |
| 477 |
quote but which are not meant to escape the quote itself. In other |
| 478 |
words, you follow single-quoting rules irrespective of the quote; |
| 479 |
eg: \f(CW\*(C`o option=\*(Aqthis isn\e\*(Aqt bad\*(Aq\*(C'\fR or \f(CW\*(C`o option="She said, \e"Isn\*(Aqt |
| 480 |
it?\e""\*(C'\fR. |
| 481 |
.Sp |
| 482 |
For historical reasons, the \f(CW\*(C`=value\*(C'\fR is optional, but defaults to |
| 483 |
1 only where it is safe to do so\-\-that is, mostly for Boolean |
| 484 |
options. It is always better to assign a specific value using \f(CW\*(C`=\*(C'\fR. |
| 485 |
The \f(CW\*(C`option\*(C'\fR can be abbreviated, but for clarity probably should |
| 486 |
not be. Several options can be set together. See "Configurable Options" |
| 487 |
for a list of these. |
| 488 |
.IP "< ?" 12 |
| 489 |
.IX Xref "debugger command, <" |
| 490 |
List out all pre-prompt Perl command actions. |
| 491 |
.IP "< [ command ]" 12 |
| 492 |
.IX Xref "debugger command, <" |
| 493 |
.IX Item "< [ command ]" |
| 494 |
Set an action (Perl command) to happen before every debugger prompt. |
| 495 |
A multi-line command may be entered by backslashing the newlines. |
| 496 |
.IP "< *" 12 |
| 497 |
.IX Xref "debugger command, <" |
| 498 |
Delete all pre-prompt Perl command actions. |
| 499 |
.IP "<< command" 12 |
| 500 |
.IX Xref "debugger command, <<" |
| 501 |
.IX Item "<< command" |
| 502 |
Add an action (Perl command) to happen before every debugger prompt. |
| 503 |
A multi-line command may be entered by backwhacking the newlines. |
| 504 |
.IP "> ?" 12 |
| 505 |
.IX Xref "debugger command, >" |
| 506 |
List out post-prompt Perl command actions. |
| 507 |
.IP "> command" 12 |
| 508 |
.IX Xref "debugger command, >" |
| 509 |
.IX Item "> command" |
| 510 |
Set an action (Perl command) to happen after the prompt when you've |
| 511 |
just given a command to return to executing the script. A multi-line |
| 512 |
command may be entered by backslashing the newlines (we bet you |
| 513 |
couldn't have guessed this by now). |
| 514 |
.IP "> *" 12 |
| 515 |
.IX Xref "debugger command, >" |
| 516 |
Delete all post-prompt Perl command actions. |
| 517 |
.IP ">> command" 12 |
| 518 |
.IX Xref "debugger command, >>" |
| 519 |
.IX Item ">> command" |
| 520 |
Adds an action (Perl command) to happen after the prompt when you've |
| 521 |
just given a command to return to executing the script. A multi-line |
| 522 |
command may be entered by backslashing the newlines. |
| 523 |
.IP "{ ?" 12 |
| 524 |
.IX Xref "debugger command, {" |
| 525 |
List out pre-prompt debugger commands. |
| 526 |
.IP "{ [ command ]" 12 |
| 527 |
.IX Item "{ [ command ]" |
| 528 |
Set an action (debugger command) to happen before every debugger prompt. |
| 529 |
A multi-line command may be entered in the customary fashion. |
| 530 |
.Sp |
| 531 |
Because this command is in some senses new, a warning is issued if |
| 532 |
you appear to have accidentally entered a block instead. If that's |
| 533 |
what you mean to do, write it as with \f(CW\*(C`;{ ... }\*(C'\fR or even |
| 534 |
\&\f(CW\*(C`do { ... }\*(C'\fR. |
| 535 |
.IP "{ *" 12 |
| 536 |
.IX Xref "debugger command, {" |
| 537 |
Delete all pre-prompt debugger commands. |
| 538 |
.IP "{{ command" 12 |
| 539 |
.IX Xref "debugger command, {{" |
| 540 |
.IX Item "{{ command" |
| 541 |
Add an action (debugger command) to happen before every debugger prompt. |
| 542 |
A multi-line command may be entered, if you can guess how: see above. |
| 543 |
.IP "! number" 12 |
| 544 |
.IX Xref "debugger command, !" |
| 545 |
.IX Item "! number" |
| 546 |
Redo a previous command (defaults to the previous command). |
| 547 |
.IP "! \-number" 12 |
| 548 |
.IX Xref "debugger command, !" |
| 549 |
.IX Item "! -number" |
| 550 |
Redo number'th previous command. |
| 551 |
.IP "! pattern" 12 |
| 552 |
.IX Xref "debugger command, !" |
| 553 |
.IX Item "! pattern" |
| 554 |
Redo last command that started with pattern. |
| 555 |
See \f(CW\*(C`o\ recallCommand\*(C'\fR, too. |
| 556 |
.IP "!! cmd" 12 |
| 557 |
.IX Xref "debugger command, !!" |
| 558 |
.IX Item "!! cmd" |
| 559 |
Run cmd in a subprocess (reads from DB::IN, writes to DB::OUT) See |
| 560 |
\&\f(CW\*(C`o\ shellBang\*(C'\fR, also. Note that the user's current shell (well, |
| 561 |
their \f(CW$ENV{SHELL}\fR variable) will be used, which can interfere |
| 562 |
with proper interpretation of exit status or signal and coredump |
| 563 |
information. |
| 564 |
.IP "source file" 12 |
| 565 |
.IX Xref "debugger command, source" |
| 566 |
.IX Item "source file" |
| 567 |
Read and execute debugger commands from \fIfile\fR. |
| 568 |
\&\fIfile\fR may itself contain \f(CW\*(C`source\*(C'\fR commands. |
| 569 |
.IP "H \-number" 12 |
| 570 |
.IX Xref "debugger command, H" |
| 571 |
.IX Item "H -number" |
| 572 |
Display last n commands. Only commands longer than one character are |
| 573 |
listed. If \fInumber\fR is omitted, list them all. |
| 574 |
.IP "q or ^D" 12 |
| 575 |
.IX Xref "debugger command, q debugger command, ^D" |
| 576 |
.IX Item "q or ^D" |
| 577 |
Quit. ("quit" doesn't work for this, unless you've made an alias) |
| 578 |
This is the only supported way to exit the debugger, though typing |
| 579 |
\&\f(CW\*(C`exit\*(C'\fR twice might work. |
| 580 |
.Sp |
| 581 |
Set the \f(CW\*(C`inhibit_exit\*(C'\fR option to 0 if you want to be able to step |
| 582 |
off the end the script. You may also need to set \f(CW$finished\fR to 0 |
| 583 |
if you want to step through global destruction. |
| 584 |
.IP R 12 |
| 585 |
.IX Xref "debugger command, R" |
| 586 |
.IX Item "R" |
| 587 |
Restart the debugger by \f(CWexec()\fRing a new session. We try to maintain |
| 588 |
your history across this, but internal settings and command-line options |
| 589 |
may be lost. |
| 590 |
.Sp |
| 591 |
The following setting are currently preserved: history, breakpoints, |
| 592 |
actions, debugger options, and the Perl command-line |
| 593 |
options \fB\-w\fR, \fB\-I\fR, and \fB\-e\fR. |
| 594 |
.IP |dbcmd 12 |
| 595 |
.IX Xref "debugger command, |" |
| 596 |
.IX Item "|dbcmd" |
| 597 |
Run the debugger command, piping DB::OUT into your current pager. |
| 598 |
.IP ||dbcmd 12 |
| 599 |
.IX Xref "debugger command, ||" |
| 600 |
.IX Item "||dbcmd" |
| 601 |
Same as \f(CW\*(C`|dbcmd\*(C'\fR but DB::OUT is temporarily \f(CW\*(C`select\*(C'\fRed as well. |
| 602 |
.IP "= [alias value]" 12 |
| 603 |
.IX Xref "debugger command, =" |
| 604 |
.IX Item "= [alias value]" |
| 605 |
Define a command alias, like |
| 606 |
.Sp |
| 607 |
.Vb 1 |
| 608 |
\& = quit q |
| 609 |
.Ve |
| 610 |
.Sp |
| 611 |
or list current aliases. |
| 612 |
.IP command 12 |
| 613 |
.IX Item "command" |
| 614 |
Execute command as a Perl statement. A trailing semicolon will be |
| 615 |
supplied. If the Perl statement would otherwise be confused for a |
| 616 |
Perl debugger, use a leading semicolon, too. |
| 617 |
.IP "m expr" 12 |
| 618 |
.IX Xref "debugger command, m" |
| 619 |
.IX Item "m expr" |
| 620 |
List which methods may be called on the result of the evaluated |
| 621 |
expression. The expression may evaluated to a reference to a |
| 622 |
blessed object, or to a package name. |
| 623 |
.IP M 12 |
| 624 |
.IX Xref "debugger command, M" |
| 625 |
.IX Item "M" |
| 626 |
Display all loaded modules and their versions. |
| 627 |
.IP "man [manpage]" 12 |
| 628 |
.IX Xref "debugger command, man" |
| 629 |
.IX Item "man [manpage]" |
| 630 |
Despite its name, this calls your system's default documentation |
| 631 |
viewer on the given page, or on the viewer itself if \fImanpage\fR is |
| 632 |
omitted. If that viewer is \fBman\fR, the current \f(CW\*(C`Config\*(C'\fR information |
| 633 |
is used to invoke \fBman\fR using the proper MANPATH or \fB\-M\fR\ \fImanpath\fR option. Failed lookups of the form \f(CW\*(C`XXX\*(C'\fR that match |
| 634 |
known manpages of the form \fIperlXXX\fR will be retried. This lets |
| 635 |
you type \f(CW\*(C`man debug\*(C'\fR or \f(CW\*(C`man op\*(C'\fR from the debugger. |
| 636 |
.Sp |
| 637 |
On systems traditionally bereft of a usable \fBman\fR command, the |
| 638 |
debugger invokes \fBperldoc\fR. Occasionally this determination is |
| 639 |
incorrect due to recalcitrant vendors or rather more felicitously, |
| 640 |
to enterprising users. If you fall into either category, just |
| 641 |
manually set the \f(CW$DB::doccmd\fR variable to whatever viewer to view |
| 642 |
the Perl documentation on your system. This may be set in an rc |
| 643 |
file, or through direct assignment. We're still waiting for a |
| 644 |
working example of something along the lines of: |
| 645 |
.Sp |
| 646 |
.Vb 1 |
| 647 |
\& $DB::doccmd = \*(Aqnetscape \-remote http://something.here/\*(Aq; |
| 648 |
.Ve |
| 649 |
.SS "Configurable Options" |
| 650 |
.IX Subsection "Configurable Options" |
| 651 |
The debugger has numerous options settable using the \f(CW\*(C`o\*(C'\fR command, |
| 652 |
either interactively or from the environment or an rc file. The file |
| 653 |
is named \fI./.perldb\fR or \fI~/.perldb\fR under Unix with \fI/dev/tty\fR, |
| 654 |
\&\fIperldb.ini\fR otherwise. |
| 655 |
.ie n .IP """recallCommand"", ""ShellBang""" 12 |
| 656 |
.el .IP "\f(CWrecallCommand\fR, \f(CWShellBang\fR" 12 |
| 657 |
.IX Xref "debugger option, recallCommand debugger option, ShellBang" |
| 658 |
.IX Item "recallCommand, ShellBang" |
| 659 |
The characters used to recall a command or spawn a shell. By |
| 660 |
default, both are set to \f(CW\*(C`!\*(C'\fR, which is unfortunate. |
| 661 |
.ie n .IP """pager""" 12 |
| 662 |
.el .IP \f(CWpager\fR 12 |
| 663 |
.IX Xref "debugger option, pager" |
| 664 |
.IX Item "pager" |
| 665 |
Program to use for output of pager-piped commands (those beginning |
| 666 |
with a \f(CW\*(C`|\*(C'\fR character.) By default, \f(CW$ENV{PAGER}\fR will be used. |
| 667 |
Because the debugger uses your current terminal characteristics |
| 668 |
for bold and underlining, if the chosen pager does not pass escape |
| 669 |
sequences through unchanged, the output of some debugger commands |
| 670 |
will not be readable when sent through the pager. |
| 671 |
.ie n .IP """tkRunning""" 12 |
| 672 |
.el .IP \f(CWtkRunning\fR 12 |
| 673 |
.IX Xref "debugger option, tkRunning" |
| 674 |
.IX Item "tkRunning" |
| 675 |
Run Tk while prompting (with ReadLine). |
| 676 |
.ie n .IP """signalLevel"", ""warnLevel"", ""dieLevel""" 12 |
| 677 |
.el .IP "\f(CWsignalLevel\fR, \f(CWwarnLevel\fR, \f(CWdieLevel\fR" 12 |
| 678 |
.IX Xref "debugger option, signalLevel debugger option, warnLevel debugger option, dieLevel" |
| 679 |
.IX Item "signalLevel, warnLevel, dieLevel" |
| 680 |
Level of verbosity. By default, the debugger leaves your exceptions |
| 681 |
and warnings alone, because altering them can break correctly running |
| 682 |
programs. It will attempt to print a message when uncaught INT, BUS, or |
| 683 |
SEGV signals arrive. (But see the mention of signals in "BUGS" below.) |
| 684 |
.Sp |
| 685 |
To disable this default safe mode, set these values to something higher |
| 686 |
than 0. At a level of 1, you get backtraces upon receiving any kind |
| 687 |
of warning (this is often annoying) or exception (this is |
| 688 |
often valuable). Unfortunately, the debugger cannot discern fatal |
| 689 |
exceptions from non-fatal ones. If \f(CW\*(C`dieLevel\*(C'\fR is even 1, then your |
| 690 |
non-fatal exceptions are also traced and unceremoniously altered if they |
| 691 |
came from \f(CW\*(C`eval\*(Aqed\*(C'\fR strings or from any kind of \f(CW\*(C`eval\*(C'\fR within modules |
| 692 |
you're attempting to load. If \f(CW\*(C`dieLevel\*(C'\fR is 2, the debugger doesn't |
| 693 |
care where they came from: It usurps your exception handler and prints |
| 694 |
out a trace, then modifies all exceptions with its own embellishments. |
| 695 |
This may perhaps be useful for some tracing purposes, but tends to hopelessly |
| 696 |
destroy any program that takes its exception handling seriously. |
| 697 |
.ie n .IP """AutoTrace""" 12 |
| 698 |
.el .IP \f(CWAutoTrace\fR 12 |
| 699 |
.IX Xref "debugger option, AutoTrace" |
| 700 |
.IX Item "AutoTrace" |
| 701 |
Trace mode (similar to \f(CW\*(C`t\*(C'\fR command, but can be put into |
| 702 |
\&\f(CW\*(C`PERLDB_OPTS\*(C'\fR). |
| 703 |
.ie n .IP """LineInfo""" 12 |
| 704 |
.el .IP \f(CWLineInfo\fR 12 |
| 705 |
.IX Xref "debugger option, LineInfo" |
| 706 |
.IX Item "LineInfo" |
| 707 |
File or pipe to print line number info to. If it is a pipe (say, |
| 708 |
\&\f(CW\*(C`|visual_perl_db\*(C'\fR), then a short message is used. This is the |
| 709 |
mechanism used to interact with a client editor or visual debugger, |
| 710 |
such as the special \f(CW\*(C`vi\*(C'\fR or \f(CW\*(C`emacs\*(C'\fR hooks, or the \f(CW\*(C`ddd\*(C'\fR graphical |
| 711 |
debugger. |
| 712 |
.ie n .IP """inhibit_exit""" 12 |
| 713 |
.el .IP \f(CWinhibit_exit\fR 12 |
| 714 |
.IX Xref "debugger option, inhibit_exit" |
| 715 |
.IX Item "inhibit_exit" |
| 716 |
If 0, allows \fIstepping off\fR the end of the script. |
| 717 |
.ie n .IP """PrintRet""" 12 |
| 718 |
.el .IP \f(CWPrintRet\fR 12 |
| 719 |
.IX Xref "debugger option, PrintRet" |
| 720 |
.IX Item "PrintRet" |
| 721 |
Print return value after \f(CW\*(C`r\*(C'\fR command if set (default). |
| 722 |
.ie n .IP """ornaments""" 12 |
| 723 |
.el .IP \f(CWornaments\fR 12 |
| 724 |
.IX Xref "debugger option, ornaments" |
| 725 |
.IX Item "ornaments" |
| 726 |
Affects screen appearance of the command line (see Term::ReadLine). |
| 727 |
There is currently no way to disable these, which can render |
| 728 |
some output illegible on some displays, or with some pagers. |
| 729 |
This is considered a bug. |
| 730 |
.ie n .IP """frame""" 12 |
| 731 |
.el .IP \f(CWframe\fR 12 |
| 732 |
.IX Xref "debugger option, frame" |
| 733 |
.IX Item "frame" |
| 734 |
Affects the printing of messages upon entry and exit from subroutines. If |
| 735 |
\&\f(CW\*(C`frame & 2\*(C'\fR is false, messages are printed on entry only. (Printing |
| 736 |
on exit might be useful if interspersed with other messages.) |
| 737 |
.Sp |
| 738 |
If \f(CW\*(C`frame & 4\*(C'\fR, arguments to functions are printed, plus context |
| 739 |
and caller info. If \f(CW\*(C`frame & 8\*(C'\fR, overloaded \f(CW\*(C`stringify\*(C'\fR and |
| 740 |
\&\f(CW\*(C`tie\*(C'\fRd \f(CW\*(C`FETCH\*(C'\fR is enabled on the printed arguments. If \f(CW\*(C`frame |
| 741 |
& 16\*(C'\fR, the return value from the subroutine is printed. |
| 742 |
.Sp |
| 743 |
The length at which the argument list is truncated is governed by the |
| 744 |
next option: |
| 745 |
.ie n .IP """maxTraceLen""" 12 |
| 746 |
.el .IP \f(CWmaxTraceLen\fR 12 |
| 747 |
.IX Xref "debugger option, maxTraceLen" |
| 748 |
.IX Item "maxTraceLen" |
| 749 |
Length to truncate the argument list when the \f(CW\*(C`frame\*(C'\fR option's |
| 750 |
bit 4 is set. |
| 751 |
.ie n .IP """windowSize""" 12 |
| 752 |
.el .IP \f(CWwindowSize\fR 12 |
| 753 |
.IX Xref "debugger option, windowSize" |
| 754 |
.IX Item "windowSize" |
| 755 |
Change the size of code list window (default is 10 lines). |
| 756 |
.PP |
| 757 |
The following options affect what happens with \f(CW\*(C`V\*(C'\fR, \f(CW\*(C`X\*(C'\fR, and \f(CW\*(C`x\*(C'\fR |
| 758 |
commands: |
| 759 |
.ie n .IP """arrayDepth"", ""hashDepth""" 12 |
| 760 |
.el .IP "\f(CWarrayDepth\fR, \f(CWhashDepth\fR" 12 |
| 761 |
.IX Xref "debugger option, arrayDepth debugger option, hashDepth" |
| 762 |
.IX Item "arrayDepth, hashDepth" |
| 763 |
Print only first N elements ('' for all). |
| 764 |
.ie n .IP """dumpDepth""" 12 |
| 765 |
.el .IP \f(CWdumpDepth\fR 12 |
| 766 |
.IX Xref "debugger option, dumpDepth" |
| 767 |
.IX Item "dumpDepth" |
| 768 |
Limit recursion depth to N levels when dumping structures. |
| 769 |
Negative values are interpreted as infinity. Default: infinity. |
| 770 |
.ie n .IP """compactDump"", ""veryCompact""" 12 |
| 771 |
.el .IP "\f(CWcompactDump\fR, \f(CWveryCompact\fR" 12 |
| 772 |
.IX Xref "debugger option, compactDump debugger option, veryCompact" |
| 773 |
.IX Item "compactDump, veryCompact" |
| 774 |
Change the style of array and hash output. If \f(CW\*(C`compactDump\*(C'\fR, short array |
| 775 |
may be printed on one line. |
| 776 |
.ie n .IP """globPrint""" 12 |
| 777 |
.el .IP \f(CWglobPrint\fR 12 |
| 778 |
.IX Xref "debugger option, globPrint" |
| 779 |
.IX Item "globPrint" |
| 780 |
Whether to print contents of globs. |
| 781 |
.ie n .IP """DumpDBFiles""" 12 |
| 782 |
.el .IP \f(CWDumpDBFiles\fR 12 |
| 783 |
.IX Xref "debugger option, DumpDBFiles" |
| 784 |
.IX Item "DumpDBFiles" |
| 785 |
Dump arrays holding debugged files. |
| 786 |
.ie n .IP """DumpPackages""" 12 |
| 787 |
.el .IP \f(CWDumpPackages\fR 12 |
| 788 |
.IX Xref "debugger option, DumpPackages" |
| 789 |
.IX Item "DumpPackages" |
| 790 |
Dump symbol tables of packages. |
| 791 |
.ie n .IP """DumpReused""" 12 |
| 792 |
.el .IP \f(CWDumpReused\fR 12 |
| 793 |
.IX Xref "debugger option, DumpReused" |
| 794 |
.IX Item "DumpReused" |
| 795 |
Dump contents of "reused" addresses. |
| 796 |
.ie n .IP """quote"", ""HighBit"", ""undefPrint""" 12 |
| 797 |
.el .IP "\f(CWquote\fR, \f(CWHighBit\fR, \f(CWundefPrint\fR" 12 |
| 798 |
.IX Xref "debugger option, quote debugger option, HighBit debugger option, undefPrint" |
| 799 |
.IX Item "quote, HighBit, undefPrint" |
| 800 |
Change the style of string dump. The default value for \f(CW\*(C`quote\*(C'\fR |
| 801 |
is \f(CW\*(C`auto\*(C'\fR; one can enable double-quotish or single-quotish format |
| 802 |
by setting it to \f(CW\*(C`"\*(C'\fR or \f(CW\*(C`\*(Aq\*(C'\fR, respectively. By default, characters |
| 803 |
with their high bit set are printed verbatim. |
| 804 |
.ie n .IP """UsageOnly""" 12 |
| 805 |
.el .IP \f(CWUsageOnly\fR 12 |
| 806 |
.IX Xref "debugger option, UsageOnly" |
| 807 |
.IX Item "UsageOnly" |
| 808 |
Rudimentary per-package memory usage dump. Calculates total |
| 809 |
size of strings found in variables in the package. This does not |
| 810 |
include lexicals in a module's file scope, or lost in closures. |
| 811 |
.ie n .IP """HistFile""" 12 |
| 812 |
.el .IP \f(CWHistFile\fR 12 |
| 813 |
.IX Xref "debugger option, history, HistFile" |
| 814 |
.IX Item "HistFile" |
| 815 |
The path of the file from which the history (assuming a usable |
| 816 |
Term::ReadLine backend) will be read on the debugger's startup, and to which |
| 817 |
it will be saved on shutdown (for persistence across sessions). Similar in |
| 818 |
concept to Bash's \f(CW\*(C`.bash_history\*(C'\fR file. |
| 819 |
.ie n .IP """HistSize""" 12 |
| 820 |
.el .IP \f(CWHistSize\fR 12 |
| 821 |
.IX Xref "debugger option, history, HistSize" |
| 822 |
.IX Item "HistSize" |
| 823 |
The count of the saved lines in the history (assuming \f(CW\*(C`HistFile\*(C'\fR above). |
| 824 |
.PP |
| 825 |
After the rc file is read, the debugger reads the \f(CW$ENV{PERLDB_OPTS}\fR |
| 826 |
environment variable and parses this as the remainder of a "O ..." |
| 827 |
line as one might enter at the debugger prompt. You may place the |
| 828 |
initialization options \f(CW\*(C`TTY\*(C'\fR, \f(CW\*(C`noTTY\*(C'\fR, \f(CW\*(C`ReadLine\*(C'\fR, and \f(CW\*(C`NonStop\*(C'\fR |
| 829 |
there. |
| 830 |
.PP |
| 831 |
If your rc file contains: |
| 832 |
.PP |
| 833 |
.Vb 1 |
| 834 |
\& parse_options("NonStop=1 LineInfo=db.out AutoTrace"); |
| 835 |
.Ve |
| 836 |
.PP |
| 837 |
then your script will run without human intervention, putting trace |
| 838 |
information into the file \fIdb.out\fR. (If you interrupt it, you'd |
| 839 |
better reset \f(CW\*(C`LineInfo\*(C'\fR to \fI/dev/tty\fR if you expect to see anything.) |
| 840 |
.ie n .IP """TTY""" 12 |
| 841 |
.el .IP \f(CWTTY\fR 12 |
| 842 |
.IX Xref "debugger option, TTY" |
| 843 |
.IX Item "TTY" |
| 844 |
The TTY to use for debugging I/O. |
| 845 |
.ie n .IP """noTTY""" 12 |
| 846 |
.el .IP \f(CWnoTTY\fR 12 |
| 847 |
.IX Xref "debugger option, noTTY" |
| 848 |
.IX Item "noTTY" |
| 849 |
If set, the debugger goes into \f(CW\*(C`NonStop\*(C'\fR mode and will not connect to a TTY. If |
| 850 |
interrupted (or if control goes to the debugger via explicit setting of |
| 851 |
\&\f(CW$DB::signal\fR or \f(CW$DB::single\fR from the Perl script), it connects to a TTY |
| 852 |
specified in the \f(CW\*(C`TTY\*(C'\fR option at startup, or to a tty found at |
| 853 |
runtime using the \f(CW\*(C`Term::Rendezvous\*(C'\fR module of your choice. |
| 854 |
.Sp |
| 855 |
This module should implement a method named \f(CW\*(C`new\*(C'\fR that returns an object |
| 856 |
with two methods: \f(CW\*(C`IN\*(C'\fR and \f(CW\*(C`OUT\*(C'\fR. These should return filehandles to use |
| 857 |
for debugging input and output correspondingly. The \f(CW\*(C`new\*(C'\fR method should |
| 858 |
inspect an argument containing the value of \f(CW$ENV{PERLDB_NOTTY}\fR at |
| 859 |
startup, or \f(CW"$ENV{HOME}/.perldbtty$$"\fR otherwise. This file is not |
| 860 |
inspected for proper ownership, so security hazards are theoretically |
| 861 |
possible. |
| 862 |
.ie n .IP """ReadLine""" 12 |
| 863 |
.el .IP \f(CWReadLine\fR 12 |
| 864 |
.IX Xref "debugger option, ReadLine" |
| 865 |
.IX Item "ReadLine" |
| 866 |
If false, readline support in the debugger is disabled in order |
| 867 |
to debug applications that themselves use ReadLine. |
| 868 |
.ie n .IP """NonStop""" 12 |
| 869 |
.el .IP \f(CWNonStop\fR 12 |
| 870 |
.IX Xref "debugger option, NonStop" |
| 871 |
.IX Item "NonStop" |
| 872 |
If set, the debugger goes into non-interactive mode until interrupted, or |
| 873 |
programmatically by setting \f(CW$DB::signal\fR or \f(CW$DB::single\fR. |
| 874 |
.PP |
| 875 |
Here's an example of using the \f(CW$ENV{PERLDB_OPTS}\fR variable: |
| 876 |
.PP |
| 877 |
.Vb 1 |
| 878 |
\& $ PERLDB_OPTS="NonStop frame=2" perl \-d myprogram |
| 879 |
.Ve |
| 880 |
.PP |
| 881 |
That will run the script \fBmyprogram\fR without human intervention, |
| 882 |
printing out the call tree with entry and exit points. Note that |
| 883 |
\&\f(CW\*(C`NonStop=1 frame=2\*(C'\fR is equivalent to \f(CW\*(C`N f=2\*(C'\fR, and that originally, |
| 884 |
options could be uniquely abbreviated by the first letter (modulo |
| 885 |
the \f(CW\*(C`Dump*\*(C'\fR options). It is nevertheless recommended that you |
| 886 |
always spell them out in full for legibility and future compatibility. |
| 887 |
.PP |
| 888 |
Other examples include |
| 889 |
.PP |
| 890 |
.Vb 1 |
| 891 |
\& $ PERLDB_OPTS="NonStop LineInfo=listing frame=2" perl \-d myprogram |
| 892 |
.Ve |
| 893 |
.PP |
| 894 |
which runs script non-interactively, printing info on each entry |
| 895 |
into a subroutine and each executed line into the file named \fIlisting\fR. |
| 896 |
(If you interrupt it, you would better reset \f(CW\*(C`LineInfo\*(C'\fR to something |
| 897 |
"interactive"!) |
| 898 |
.PP |
| 899 |
Other examples include (using standard shell syntax to show environment |
| 900 |
variable settings): |
| 901 |
.PP |
| 902 |
.Vb 2 |
| 903 |
\& $ ( PERLDB_OPTS="NonStop frame=1 AutoTrace LineInfo=tperl.out" |
| 904 |
\& perl \-d myprogram ) |
| 905 |
.Ve |
| 906 |
.PP |
| 907 |
which may be useful for debugging a program that uses Term::ReadLine |
| 908 |
itself. Do not forget to detach your shell from the TTY in the window that |
| 909 |
corresponds to \fI/dev/ttyXX\fR, say, by issuing a command like |
| 910 |
.PP |
| 911 |
.Vb 1 |
| 912 |
\& $ sleep 1000000 |
| 913 |
.Ve |
| 914 |
.PP |
| 915 |
See "Debugger Internals" in perldebguts for details. |
| 916 |
.SS "Debugger Input/Output" |
| 917 |
.IX Subsection "Debugger Input/Output" |
| 918 |
.IP Prompt 8 |
| 919 |
.IX Item "Prompt" |
| 920 |
The debugger prompt is something like |
| 921 |
.Sp |
| 922 |
.Vb 1 |
| 923 |
\& DB<8> |
| 924 |
.Ve |
| 925 |
.Sp |
| 926 |
or even |
| 927 |
.Sp |
| 928 |
.Vb 1 |
| 929 |
\& DB<<17>> |
| 930 |
.Ve |
| 931 |
.Sp |
| 932 |
where that number is the command number, and which you'd use to |
| 933 |
access with the built-in \fBcsh\fR\-like history mechanism. For example, |
| 934 |
\&\f(CW\*(C`!17\*(C'\fR would repeat command number 17. The depth of the angle |
| 935 |
brackets indicates the nesting depth of the debugger. You could |
| 936 |
get more than one set of brackets, for example, if you'd already |
| 937 |
at a breakpoint and then printed the result of a function call that |
| 938 |
itself has a breakpoint, or you step into an expression via \f(CW\*(C`s/n/t |
| 939 |
expression\*(C'\fR command. |
| 940 |
.IP "Multiline commands" 8 |
| 941 |
.IX Item "Multiline commands" |
| 942 |
If you want to enter a multi-line command, such as a subroutine |
| 943 |
definition with several statements or a format, escape the newline |
| 944 |
that would normally end the debugger command with a backslash. |
| 945 |
Here's an example: |
| 946 |
.Sp |
| 947 |
.Vb 7 |
| 948 |
\& DB<1> for (1..4) { \e |
| 949 |
\& cont: print "ok\en"; \e |
| 950 |
\& cont: } |
| 951 |
\& ok |
| 952 |
\& ok |
| 953 |
\& ok |
| 954 |
\& ok |
| 955 |
.Ve |
| 956 |
.Sp |
| 957 |
Note that this business of escaping a newline is specific to interactive |
| 958 |
commands typed into the debugger. |
| 959 |
.IP "Stack backtrace" 8 |
| 960 |
.IX Xref "backtrace stack, backtrace" |
| 961 |
.IX Item "Stack backtrace" |
| 962 |
Here's an example of what a stack backtrace via \f(CW\*(C`T\*(C'\fR command might |
| 963 |
look like: |
| 964 |
.Sp |
| 965 |
.Vb 5 |
| 966 |
\& $ = main::infested called from file \*(AqAmbulation.pm\*(Aq line 10 |
| 967 |
\& @ = Ambulation::legs(1, 2, 3, 4) called from file \*(Aqcamel_flea\*(Aq |
| 968 |
\& line 7 |
| 969 |
\& $ = main::pests(\*(Aqbactrian\*(Aq, 4) called from file \*(Aqcamel_flea\*(Aq |
| 970 |
\& line 4 |
| 971 |
.Ve |
| 972 |
.Sp |
| 973 |
The left-hand character up there indicates the context in which the |
| 974 |
function was called, with \f(CW\*(C`$\*(C'\fR and \f(CW\*(C`@\*(C'\fR meaning scalar or list |
| 975 |
contexts respectively, and \f(CW\*(C`.\*(C'\fR meaning void context (which is |
| 976 |
actually a sort of scalar context). The display above says |
| 977 |
that you were in the function \f(CW\*(C`main::infested\*(C'\fR when you ran the |
| 978 |
stack dump, and that it was called in scalar context from line |
| 979 |
10 of the file \fIAmbulation.pm\fR, but without any arguments at all, |
| 980 |
meaning it was called as \f(CW&infested\fR. The next stack frame shows |
| 981 |
that the function \f(CW\*(C`Ambulation::legs\*(C'\fR was called in list context |
| 982 |
from the \fIcamel_flea\fR file with four arguments. The last stack |
| 983 |
frame shows that \f(CW\*(C`main::pests\*(C'\fR was called in scalar context, |
| 984 |
also from \fIcamel_flea\fR, but from line 4. |
| 985 |
.Sp |
| 986 |
If you execute the \f(CW\*(C`T\*(C'\fR command from inside an active \f(CW\*(C`use\*(C'\fR |
| 987 |
statement, the backtrace will contain both a \f(CW\*(C`require\*(C'\fR frame and |
| 988 |
an \f(CW\*(C`eval\*(C'\fR frame. |
| 989 |
.IP "Line Listing Format" 8 |
| 990 |
.IX Item "Line Listing Format" |
| 991 |
This shows the sorts of output the \f(CW\*(C`l\*(C'\fR command can produce: |
| 992 |
.Sp |
| 993 |
.Vb 11 |
| 994 |
\& DB<<13>> l |
| 995 |
\& 101: @i{@i} = (); |
| 996 |
\& 102:b @isa{@i,$pack} = () |
| 997 |
\& 103 if(exists $i{$prevpack} || exists $isa{$pack}); |
| 998 |
\& 104 } |
| 999 |
\& 105 |
| 1000 |
\& 106 next |
| 1001 |
\& 107==> if(exists $isa{$pack}); |
| 1002 |
\& 108 |
| 1003 |
\& 109:a if ($extra\-\- > 0) { |
| 1004 |
\& 110: %isa = ($pack,1); |
| 1005 |
.Ve |
| 1006 |
.Sp |
| 1007 |
Breakable lines are marked with \f(CW\*(C`:\*(C'\fR. Lines with breakpoints are |
| 1008 |
marked by \f(CW\*(C`b\*(C'\fR and those with actions by \f(CW\*(C`a\*(C'\fR. The line that's |
| 1009 |
about to be executed is marked by \f(CW\*(C`==>\*(C'\fR. |
| 1010 |
.Sp |
| 1011 |
Please be aware that code in debugger listings may not look the same |
| 1012 |
as your original source code. Line directives and external source |
| 1013 |
filters can alter the code before Perl sees it, causing code to move |
| 1014 |
from its original positions or take on entirely different forms. |
| 1015 |
.IP "Frame listing" 8 |
| 1016 |
.IX Item "Frame listing" |
| 1017 |
When the \f(CW\*(C`frame\*(C'\fR option is set, the debugger would print entered (and |
| 1018 |
optionally exited) subroutines in different styles. See perldebguts |
| 1019 |
for incredibly long examples of these. |
| 1020 |
.SS "Debugging Compile-Time Statements" |
| 1021 |
.IX Subsection "Debugging Compile-Time Statements" |
| 1022 |
If you have compile-time executable statements (such as code within |
| 1023 |
BEGIN, UNITCHECK and CHECK blocks or \f(CW\*(C`use\*(C'\fR statements), these will |
| 1024 |
\&\fInot\fR be stopped by debugger, although \f(CW\*(C`require\*(C'\fRs and INIT blocks |
| 1025 |
will, and compile-time statements can be traced with the \f(CW\*(C`AutoTrace\*(C'\fR |
| 1026 |
option set in \f(CW\*(C`PERLDB_OPTS\*(C'\fR). From your own Perl code, however, you |
| 1027 |
can transfer control back to the debugger using the following |
| 1028 |
statement, which is harmless if the debugger is not running: |
| 1029 |
.PP |
| 1030 |
.Vb 1 |
| 1031 |
\& $DB::single = 1; |
| 1032 |
.Ve |
| 1033 |
.PP |
| 1034 |
If you set \f(CW$DB::single\fR to 2, it's equivalent to having |
| 1035 |
just typed the \f(CW\*(C`n\*(C'\fR command, whereas a value of 1 means the \f(CW\*(C`s\*(C'\fR |
| 1036 |
command. The \f(CW$DB::trace\fR variable should be set to 1 to simulate |
| 1037 |
having typed the \f(CW\*(C`t\*(C'\fR command. |
| 1038 |
.PP |
| 1039 |
Another way to debug compile-time code is to start the debugger, set a |
| 1040 |
breakpoint on the \fIload\fR of some module: |
| 1041 |
.PP |
| 1042 |
.Vb 2 |
| 1043 |
\& DB<7> b load f:/perllib/lib/Carp.pm |
| 1044 |
\& Will stop on load of \*(Aqf:/perllib/lib/Carp.pm\*(Aq. |
| 1045 |
.Ve |
| 1046 |
.PP |
| 1047 |
and then restart the debugger using the \f(CW\*(C`R\*(C'\fR command (if possible). One can use \f(CW\*(C`b |
| 1048 |
compile subname\*(C'\fR for the same purpose. |
| 1049 |
.SS "Debugger Customization" |
| 1050 |
.IX Subsection "Debugger Customization" |
| 1051 |
The debugger probably contains enough configuration hooks that you |
| 1052 |
won't ever have to modify it yourself. You may change the behaviour |
| 1053 |
of the debugger from within the debugger using its \f(CW\*(C`o\*(C'\fR command, from |
| 1054 |
the command line via the \f(CW\*(C`PERLDB_OPTS\*(C'\fR environment variable, and |
| 1055 |
from customization files. |
| 1056 |
.PP |
| 1057 |
You can do some customization by setting up a \fI.perldb\fR file, which |
| 1058 |
contains initialization code. For instance, you could make aliases |
| 1059 |
like these (the last one is one people expect to be there): |
| 1060 |
.PP |
| 1061 |
.Vb 4 |
| 1062 |
\& $DB::alias{\*(Aqlen\*(Aq} = \*(Aqs/^len(.*)/p length($1)/\*(Aq; |
| 1063 |
\& $DB::alias{\*(Aqstop\*(Aq} = \*(Aqs/^stop (at|in)/b/\*(Aq; |
| 1064 |
\& $DB::alias{\*(Aqps\*(Aq} = \*(Aqs/^ps\eb/p scalar /\*(Aq; |
| 1065 |
\& $DB::alias{\*(Aqquit\*(Aq} = \*(Aqs/^quit(\es*)/exit/\*(Aq; |
| 1066 |
.Ve |
| 1067 |
.PP |
| 1068 |
You can change options from \fI.perldb\fR by using calls like this one; |
| 1069 |
.PP |
| 1070 |
.Vb 1 |
| 1071 |
\& parse_options("NonStop=1 LineInfo=db.out AutoTrace=1 frame=2"); |
| 1072 |
.Ve |
| 1073 |
.PP |
| 1074 |
The code is executed in the package \f(CW\*(C`DB\*(C'\fR. Note that \fI.perldb\fR is |
| 1075 |
processed before processing \f(CW\*(C`PERLDB_OPTS\*(C'\fR. If \fI.perldb\fR defines the |
| 1076 |
subroutine \f(CW\*(C`afterinit\*(C'\fR, that function is called after debugger |
| 1077 |
initialization ends. \fI.perldb\fR may be contained in the current |
| 1078 |
directory, or in the home directory. Because this file is sourced |
| 1079 |
in by Perl and may contain arbitrary commands, for security reasons, |
| 1080 |
it must be owned by the superuser or the current user, and writable |
| 1081 |
by no one but its owner. |
| 1082 |
.PP |
| 1083 |
You can mock TTY input to debugger by adding arbitrary commands to |
| 1084 |
\&\f(CW@DB::typeahead\fR. For example, your \fI.perldb\fR file might contain: |
| 1085 |
.PP |
| 1086 |
.Vb 1 |
| 1087 |
\& sub afterinit { push @DB::typeahead, "b 4", "b 6"; } |
| 1088 |
.Ve |
| 1089 |
.PP |
| 1090 |
Which would attempt to set breakpoints on lines 4 and 6 immediately |
| 1091 |
after debugger initialization. Note that \f(CW@DB::typeahead\fR is not a supported |
| 1092 |
interface and is subject to change in future releases. |
| 1093 |
.PP |
| 1094 |
If you want to modify the debugger, copy \fIperl5db.pl\fR from the |
| 1095 |
Perl library to another name and hack it to your heart's content. |
| 1096 |
You'll then want to set your \f(CW\*(C`PERL5DB\*(C'\fR environment variable to say |
| 1097 |
something like this: |
| 1098 |
.PP |
| 1099 |
.Vb 1 |
| 1100 |
\& BEGIN { require "myperl5db.pl" } |
| 1101 |
.Ve |
| 1102 |
.PP |
| 1103 |
As a last resort, you could also use \f(CW\*(C`PERL5DB\*(C'\fR to customize the debugger |
| 1104 |
by directly setting internal variables or calling debugger functions. |
| 1105 |
.PP |
| 1106 |
Note that any variables and functions that are not documented in |
| 1107 |
this document (or in perldebguts) are considered for internal |
| 1108 |
use only, and as such are subject to change without notice. |
| 1109 |
.SS "Readline Support / History in the Debugger" |
| 1110 |
.IX Subsection "Readline Support / History in the Debugger" |
| 1111 |
As shipped, the only command-line history supplied is a simplistic one |
| 1112 |
that checks for leading exclamation points. However, if you install |
| 1113 |
the Term::ReadKey and one of the \f(CW\*(C`Term::ReadLine::*\*(C'\fR modules from CPAN (such as |
| 1114 |
Term::ReadLine::Gnu, Term::ReadLine::Perl, ...) you will |
| 1115 |
have full editing capabilities much like those GNU \fIreadline\fR(3) provides. |
| 1116 |
Look for these in the \fImodules/by\-module/Term\fR directory on CPAN. |
| 1117 |
These do not support normal \fBvi\fR command-line editing, however. |
| 1118 |
.PP |
| 1119 |
A rudimentary command-line completion is also available, including |
| 1120 |
lexical variables in the current scope if the PadWalker module |
| 1121 |
is installed. |
| 1122 |
.PP |
| 1123 |
Without Readline support you may see the symbols "^[[A", "^[[C", "^[[B", |
| 1124 |
"^[[D"", "^H", ... when using the arrow keys and/or the backspace key. |
| 1125 |
.SS "Editor Support for Debugging" |
| 1126 |
.IX Subsection "Editor Support for Debugging" |
| 1127 |
If you have the GNU's version of \fBemacs\fR installed on your system, |
| 1128 |
it can interact with the Perl debugger to provide an integrated |
| 1129 |
software development environment reminiscent of its interactions |
| 1130 |
with C debuggers. |
| 1131 |
.PP |
| 1132 |
Recent versions of Emacs come with a |
| 1133 |
start file for making \fBemacs\fR act like a |
| 1134 |
syntax-directed editor that understands (some of) Perl's syntax. |
| 1135 |
See perlfaq3. |
| 1136 |
.PP |
| 1137 |
Users of \fBvi\fR should also look into \fBvim\fR and \fBgvim\fR, the mousey |
| 1138 |
and windy version, for coloring of Perl keywords. |
| 1139 |
.PP |
| 1140 |
Note that only perl can truly parse Perl, so all such CASE tools |
| 1141 |
fall somewhat short of the mark, especially if you don't program |
| 1142 |
your Perl as a C programmer might. |
| 1143 |
.SS "The Perl Profiler" |
| 1144 |
.IX Xref "profile profiling profiler" |
| 1145 |
.IX Subsection "The Perl Profiler" |
| 1146 |
If you wish to supply an alternative debugger for Perl to run, |
| 1147 |
invoke your script with a colon and a package argument given to the |
| 1148 |
\&\fB\-d\fR flag. Perl's alternative debuggers include a Perl profiler, |
| 1149 |
Devel::NYTProf, which is available separately as a CPAN |
| 1150 |
distribution. To profile your Perl program in the file \fImycode.pl\fR, |
| 1151 |
just type: |
| 1152 |
.PP |
| 1153 |
.Vb 1 |
| 1154 |
\& $ perl \-d:NYTProf mycode.pl |
| 1155 |
.Ve |
| 1156 |
.PP |
| 1157 |
When the script terminates the profiler will create a database of the |
| 1158 |
profile information that you can turn into reports using the profiler's |
| 1159 |
tools. See <perlperf> for details. |
| 1160 |
.SH "Debugging Regular Expressions" |
| 1161 |
.IX Xref "regular expression, debugging regex, debugging regexp, debugging" |
| 1162 |
.IX Header "Debugging Regular Expressions" |
| 1163 |
\&\f(CW\*(C`use re \*(Aqdebug\*(Aq\*(C'\fR enables you to see the gory details of how the Perl |
| 1164 |
regular expression engine works. In order to understand this typically |
| 1165 |
voluminous output, one must not only have some idea about how regular |
| 1166 |
expression matching works in general, but also know how Perl's regular |
| 1167 |
expressions are internally compiled into an automaton. These matters |
| 1168 |
are explored in some detail in |
| 1169 |
"Debugging Regular Expressions" in perldebguts. |
| 1170 |
.SH "Debugging Memory Usage" |
| 1171 |
.IX Xref "memory usage" |
| 1172 |
.IX Header "Debugging Memory Usage" |
| 1173 |
Perl contains internal support for reporting its own memory usage, |
| 1174 |
but this is a fairly advanced concept that requires some understanding |
| 1175 |
of how memory allocation works. |
| 1176 |
See "Debugging Perl Memory Usage" in perldebguts for the details. |
| 1177 |
.SH "SEE ALSO" |
| 1178 |
.IX Header "SEE ALSO" |
| 1179 |
You do have \f(CW\*(C`use strict\*(C'\fR and \f(CW\*(C`use warnings\*(C'\fR enabled, don't you? |
| 1180 |
.PP |
| 1181 |
perldebtut, |
| 1182 |
perldebguts, |
| 1183 |
perl5db.pl, |
| 1184 |
re, |
| 1185 |
DB, |
| 1186 |
Devel::NYTProf, |
| 1187 |
Dumpvalue, |
| 1188 |
and |
| 1189 |
perlrun. |
| 1190 |
.PP |
| 1191 |
When debugging a script that uses #! and is thus normally found in |
| 1192 |
\&\f(CW$PATH\fR, the \-S option causes perl to search \f(CW$PATH\fR for it, so you don't |
| 1193 |
have to type the path or \f(CW\*(C`which $scriptname\*(C'\fR. |
| 1194 |
.PP |
| 1195 |
.Vb 1 |
| 1196 |
\& $ perl \-Sd foo.pl |
| 1197 |
.Ve |
| 1198 |
.SH BUGS |
| 1199 |
.IX Header "BUGS" |
| 1200 |
You cannot get stack frame information or in any fashion debug functions |
| 1201 |
that were not compiled by Perl, such as those from C or C++ extensions. |
| 1202 |
.PP |
| 1203 |
If you alter your \f(CW@_\fR arguments in a subroutine (such as with \f(CW\*(C`shift\*(C'\fR |
| 1204 |
or \f(CW\*(C`pop\*(C'\fR), the stack backtrace will not show the original values. |
| 1205 |
.PP |
| 1206 |
The debugger does not currently work in conjunction with the \fB\-W\fR |
| 1207 |
command-line switch, because it itself is not free of warnings. |
| 1208 |
.PP |
| 1209 |
If you're in a slow syscall (like \f(CW\*(C`wait\*(C'\fRing, \f(CW\*(C`accept\*(C'\fRing, or \f(CW\*(C`read\*(C'\fRing |
| 1210 |
from your keyboard or a socket) and haven't set up your own \f(CW$SIG{INT}\fR |
| 1211 |
handler, then you won't be able to CTRL-C your way back to the debugger, |
| 1212 |
because the debugger's own \f(CW$SIG{INT}\fR handler doesn't understand that |
| 1213 |
it needs to raise an exception to \fBlongjmp\fR\|(3) out of slow syscalls. |