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