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