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