Commit | Line | Data |
a0d0e21e |
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 | |
4e1d3b43 |
9 | =head1 The Perl Debugger |
10 | |
11 | If you invoke Perl with the B<-d> switch, your script runs under the |
12 | Perl source debugger. This works like an interactive Perl |
13 | environment, prompting for debugger commands that let you examine |
14 | source code, set breakpoints, get stack backtraces, change the values of |
15 | variables, etc. This is so convenient that you often fire up |
16 | the debugger all by itself just to test out Perl constructs |
17 | interactively to see what they do. For example: |
18 | |
19 | perl -d -e 42 |
20 | |
21 | In Perl, the debugger is not a separate program as it usually is in the |
22 | typical compiled environment. Instead, the B<-d> flag tells the compiler |
23 | to insert source information into the parse trees it's about to hand off |
24 | to the interpreter. That means your code must first compile correctly |
25 | for the debugger to work on it. Then when the interpreter starts up, it |
26 | pre-loads a Perl library file containing the debugger itself. |
27 | |
28 | The program will halt I<right before> the first run-time executable |
29 | statement (but see below regarding compile-time statements) and ask you |
30 | to enter a debugger command. Contrary to popular expectations, whenever |
31 | the debugger halts and shows you a line of code, it always displays the |
32 | line it's I<about> to execute, rather than the one it has just executed. |
33 | |
34 | Any command not recognized by the debugger is directly executed |
35 | (C<eval>'d) as Perl code in the current package. (The debugger uses the |
36 | DB package for its own state information.) |
37 | |
38 | Leading white space before a command would cause the debugger to think |
39 | it's I<NOT> a debugger command but for Perl, so be careful not to do |
40 | that. |
41 | |
42 | =head2 Debugger Commands |
43 | |
44 | The debugger understands the following commands: |
a0d0e21e |
45 | |
46 | =over 12 |
47 | |
4e1d3b43 |
48 | =item h [command] |
49 | |
50 | Prints out a help message. |
51 | |
52 | If you supply another debugger command as an argument to the C<h> command, |
53 | it prints out the description for just that command. The special |
54 | argument of C<h h> produces a more compact help listing, designed to fit |
55 | together on one screen. |
56 | |
57 | If the output the C<h> command (or any command, for that matter) scrolls |
58 | past your screen, either precede the command with a leading pipe symbol so |
59 | it's run through your pager, as in |
60 | |
61 | DB> |h |
62 | |
63 | =item p expr |
64 | |
65 | Same as C<print DB::OUT expr> in the current package. In particular, |
66 | since this is just Perl's own B<print> function, this means that nested |
67 | data structures and objects are not dumped, unlike with the C<x> command. |
68 | |
69 | =item x expr |
70 | |
71 | Evals its expression in list context and dumps out the result |
72 | in a pretty-printed fashion. Nested data structures are printed out |
73 | recursively, unlike the C<print> function. |
74 | |
75 | =item V [pkg [vars]] |
76 | |
77 | Display all (or some) variables in package (defaulting to the C<main> |
78 | package) using a data pretty-printer (hashes show their keys and values so |
79 | you see what's what, control characters are made printable, etc.). Make |
80 | sure you don't put the type specifier (like C<$>) there, just the symbol |
81 | names, like this: |
82 | |
83 | V DB filename line |
84 | |
85 | Use C<~pattern> and C<!pattern> for positive and negative regexps. |
a0d0e21e |
86 | |
4e1d3b43 |
87 | Nested data structures are printed out in a legible fashion, unlike |
88 | the C<print> function. |
89 | |
90 | =item X [vars] |
91 | |
92 | Same as C<V currentpackage [vars]>. |
a0d0e21e |
93 | |
94 | =item T |
95 | |
4e1d3b43 |
96 | Produce a stack backtrace. See below for details on its output. |
a0d0e21e |
97 | |
4e1d3b43 |
98 | =item s [expr] |
a0d0e21e |
99 | |
100 | Single step. Executes until it reaches the beginning of another |
4e1d3b43 |
101 | statement, descending into subroutine calls. If an expression is |
102 | supplied that includes function calls, it too will be single-stepped. |
a0d0e21e |
103 | |
104 | =item n |
105 | |
106 | Next. Executes over subroutine calls, until it reaches the beginning |
107 | of the next statement. |
108 | |
4e1d3b43 |
109 | =item <CR> |
a0d0e21e |
110 | |
4e1d3b43 |
111 | Repeat last C<n> or C<s> command. |
a0d0e21e |
112 | |
4e1d3b43 |
113 | =item c [line] |
a0d0e21e |
114 | |
4e1d3b43 |
115 | Continue, optionally inserting a one-time-only breakpoint |
116 | at the specified line. |
a0d0e21e |
117 | |
4e1d3b43 |
118 | =item l |
a0d0e21e |
119 | |
4e1d3b43 |
120 | List next window of lines. |
a0d0e21e |
121 | |
122 | =item l min+incr |
123 | |
4e1d3b43 |
124 | List C<incr+1> lines starting at C<min>. |
a0d0e21e |
125 | |
126 | =item l min-max |
127 | |
4e1d3b43 |
128 | List lines C<min> through C<max>. |
a0d0e21e |
129 | |
130 | =item l line |
131 | |
4e1d3b43 |
132 | List a single line. |
a0d0e21e |
133 | |
4e1d3b43 |
134 | =item l subname |
a0d0e21e |
135 | |
4e1d3b43 |
136 | List first window of lines from subroutine. |
a0d0e21e |
137 | |
138 | =item - |
139 | |
4e1d3b43 |
140 | List previous window of lines. |
a0d0e21e |
141 | |
4e1d3b43 |
142 | =item w [line] |
a0d0e21e |
143 | |
4e1d3b43 |
144 | List window (a few lines) around the current line. |
a0d0e21e |
145 | |
4e1d3b43 |
146 | =item . |
a0d0e21e |
147 | |
4e1d3b43 |
148 | Return debugger pointer to the last-executed line and |
149 | print it out. |
150 | |
151 | =item f filename |
152 | |
153 | Switch to viewing a different file. |
a0d0e21e |
154 | |
155 | =item /pattern/ |
156 | |
4e1d3b43 |
157 | Search forwards for pattern; final / is optional. |
a0d0e21e |
158 | |
159 | =item ?pattern? |
160 | |
4e1d3b43 |
161 | Search backwards for pattern; final ? is optional. |
a0d0e21e |
162 | |
163 | =item L |
164 | |
4e1d3b43 |
165 | List all breakpoints and actions for the current file. |
a0d0e21e |
166 | |
4e1d3b43 |
167 | =item S [[!]pattern] |
a0d0e21e |
168 | |
4e1d3b43 |
169 | List subroutine names [not] matching pattern. |
a0d0e21e |
170 | |
171 | =item t |
172 | |
4e1d3b43 |
173 | Toggle trace mode. |
174 | |
175 | =item t expr |
176 | |
177 | Trace through execution of expr. For example: |
178 | |
179 | $ perl -de 42 |
180 | Stack dump during die enabled outside of evals. |
a0d0e21e |
181 | |
4e1d3b43 |
182 | Loading DB routines from perl5db.pl patch level 0.94 |
183 | Emacs support available. |
184 | |
185 | Enter h or `h h' for help. |
186 | |
187 | main::(-e:1): 0 |
188 | DB<1> sub foo { 14 } |
189 | |
190 | DB<2> sub bar { 3 } |
191 | |
192 | DB<3> t print foo() * bar() |
193 | main::((eval 172):3): print foo() + bar(); |
194 | main::foo((eval 168):2): |
195 | main::bar((eval 170):2): |
196 | 42 |
197 | DB<4> q |
198 | |
199 | =item b [line] [condition] |
a0d0e21e |
200 | |
201 | Set a breakpoint. If line is omitted, sets a breakpoint on the line |
4e1d3b43 |
202 | that is about to be executed. If a condition is specified, it's |
a0d0e21e |
203 | evaluated each time the statement is reached and a breakpoint is taken |
204 | only if the condition is true. Breakpoints may only be set on lines |
4e1d3b43 |
205 | that begin an executable statement. Conditions don't use B<if>: |
a0d0e21e |
206 | |
207 | b 237 $x > 30 |
208 | b 33 /pattern/i |
209 | |
4e1d3b43 |
210 | =item b subname [condition] |
a0d0e21e |
211 | |
4e1d3b43 |
212 | Set a breakpoint at the first line of the named subroutine. |
a0d0e21e |
213 | |
4e1d3b43 |
214 | =item d [line] |
a0d0e21e |
215 | |
4e1d3b43 |
216 | Delete a breakpoint at the specified line. If line is omitted, deletes |
217 | the breakpoint on the line that is about to be executed. |
a0d0e21e |
218 | |
219 | =item D |
220 | |
4e1d3b43 |
221 | Delete all installed breakpoints. |
222 | |
223 | =item a [line] command |
224 | |
225 | Set an action to be done before the line is executed. |
226 | The sequence of steps taken by the debugger is |
227 | |
228 | =over 3 |
229 | |
230 | =item 1 |
231 | |
232 | check for a breakpoint at this line |
233 | |
234 | =item 2 |
235 | |
236 | print the line if necessary (tracing) |
237 | |
238 | =item 3 |
239 | |
240 | do any actions associated with that line |
241 | |
242 | =item 4 |
243 | |
244 | prompt user if at a breakpoint or in single-step |
245 | |
246 | =item 5 |
247 | |
248 | evaluate line |
249 | |
250 | =back |
a0d0e21e |
251 | |
4e1d3b43 |
252 | For example, this will print out C<$foo> every time line |
253 | 53 is passed: |
a0d0e21e |
254 | |
4e1d3b43 |
255 | a 53 print "DB FOUND $foo\n" |
a0d0e21e |
256 | |
257 | =item A |
258 | |
4e1d3b43 |
259 | Delete all installed actions. |
260 | |
261 | =item O [opt[=val]] [opt"val"] [opt?]... |
262 | |
263 | Set or query values of options. val defaults to 1. opt can |
264 | be abbreviated. Several options can be listed. |
265 | |
266 | =over 12 |
267 | |
268 | =item recallCommand, ShellBang |
269 | |
270 | The characters used to recall command or spawn shell. By |
271 | default, these are both set to C<!>. |
272 | |
273 | =item pager |
274 | |
275 | Program to use for output of pager-piped commands (those |
276 | beginning with a C<|> character.) By default, |
277 | C<$ENV{PAGER}> will be used. |
278 | |
279 | =back |
280 | |
281 | The following options affect what happens with C<V>, C<X>, and C<x> |
282 | commands: |
283 | |
284 | =over 12 |
285 | |
286 | =item arrayDepth, hashDepth |
287 | |
288 | Print only first N elements ('' for all). |
289 | |
290 | =item compactDump, veryCompact |
291 | |
292 | Change style of array and hash dump. |
293 | |
294 | =item globPrint |
295 | |
296 | Whether to print contents of globs. |
297 | |
298 | =item DumpDBFiles |
299 | |
300 | Dump arrays holding debugged files. |
301 | |
302 | =item DumpPackages |
303 | |
304 | Dump symbol tables of packages. |
305 | |
306 | =item quote, HighBit, undefPrint |
307 | |
308 | Change style of string dump. |
309 | |
310 | =item tkRunning |
311 | |
312 | Run Tk while prompting (with ReadLine). |
313 | |
314 | =item signalLevel, warnLevel. dieLevel |
315 | |
316 | Level of verbosity. |
317 | |
318 | =back |
319 | |
320 | The option C<PrintRet> affects printing of return value after C<r> |
321 | command, The option C<frame> affects printing messages on entry and exit |
322 | from subroutines. If C<frame> is 1, messages are printed on entry only; |
323 | if it's set to more than that, they'll will be printed on exit as well, |
324 | which may be useful if interdispersed with other messages. |
325 | |
326 | During startup options are initialized from $ENV{PERLDB_OPTS}. |
327 | You can put additional initialization options C<TTY>, C<noTTY>, |
328 | C<ReadLine>, and C<NonStop> there. Here's an example of using |
329 | the C<$ENV{PERLDB_OPTS}> variable: |
330 | |
331 | $ PERLDB_OPTS="N f=2" perl -d myprogram |
332 | |
333 | will run the script C<myprogram> without human intervention, printing |
334 | out the call tree with entry and exit points. Note that C<N f=2> is |
335 | equivalent to C<NonStop=1 frame=2>. Note also that at the moment when |
336 | this documentation was written all the options to the debugger could |
337 | be uniquely abbreviated by the first letter. |
338 | |
339 | See "Debugger Internals" below for more details. |
a0d0e21e |
340 | |
341 | =item < command |
342 | |
343 | Set an action to happen before every debugger prompt. A multiline |
344 | command may be entered by backslashing the newlines. |
345 | |
346 | =item > command |
347 | |
348 | Set an action to happen after the prompt when you've just given a |
349 | command to return to executing the script. A multiline command may be |
350 | entered by backslashing the newlines. |
351 | |
4e1d3b43 |
352 | =item ! number |
a0d0e21e |
353 | |
4e1d3b43 |
354 | Redo a previous command (default previous command). |
a0d0e21e |
355 | |
4e1d3b43 |
356 | =item ! -number |
a0d0e21e |
357 | |
4e1d3b43 |
358 | Redo number'th-to-last command. |
a0d0e21e |
359 | |
4e1d3b43 |
360 | =item ! pattern |
a0d0e21e |
361 | |
4e1d3b43 |
362 | Redo last command that started with pattern. |
363 | See C<O recallCommand>, too. |
a0d0e21e |
364 | |
4e1d3b43 |
365 | =item !! cmd |
a0d0e21e |
366 | |
4e1d3b43 |
367 | Run cmd in a subprocess (reads from DB::IN, writes to DB::OUT) |
368 | See C<O shellBang> too. |
a0d0e21e |
369 | |
370 | =item H -number |
371 | |
372 | Display last n commands. Only commands longer than one character are |
373 | listed. If number is omitted, lists them all. |
374 | |
375 | =item q or ^D |
376 | |
377 | Quit. ("quit" doesn't work for this.) |
378 | |
4e1d3b43 |
379 | =item R |
380 | |
381 | Restart the debugger by B<exec>ing a new session. It tries to maintain |
382 | your history across this, but internal settings and command line options |
383 | may be lost. |
384 | |
385 | =item |dbcmd |
386 | |
387 | Run debugger command, piping DB::OUT to current pager. |
388 | |
389 | =item ||dbcmd |
390 | |
391 | Same as C<|dbcmd> but DB::OUT is temporarily B<select>ed as well. |
392 | Often used with commands that would otherwise produce long |
393 | output, such as |
394 | |
395 | |V main |
396 | |
397 | =item = [alias value] |
398 | |
399 | Define a command alias, or list current aliases. |
400 | |
a0d0e21e |
401 | =item command |
402 | |
403 | Execute command as a Perl statement. A missing semicolon will be |
404 | supplied. |
405 | |
406 | =item p expr |
407 | |
408 | Same as C<print DB::OUT expr>. The DB::OUT filehandle is opened to |
409 | /dev/tty, regardless of where STDOUT may be redirected to. |
410 | |
411 | =back |
412 | |
4e1d3b43 |
413 | The debugger prompt is something like |
414 | |
415 | DB<8> |
416 | |
417 | or even |
418 | |
419 | DB<<17>> |
420 | |
421 | where that number is the command number, which you'd use to access with |
422 | the built-in B<csh>-like history mechanism, e.g. C<!17> would repeat |
423 | command number 17. The number of angle brackets indicates the depth of |
424 | the debugger. You could get more than one set of brackets, for example, if |
425 | you'd already at a breakpoint and then printed out the result of a |
426 | function call that itself also has a breakpoint. |
427 | |
428 | If you want to enter a multi-line command, such as a subroutine |
429 | definition with several statements, you may escape the newline that would |
430 | normally end the debugger command with a backslash. Here's an example: |
a0d0e21e |
431 | |
4e1d3b43 |
432 | DB<1> for (1..4) { \ |
433 | cont: print "ok\n"; \ |
434 | cont: } |
435 | ok |
436 | ok |
437 | ok |
438 | ok |
439 | |
440 | Note that this business of escaping a newline is specific to interactive |
441 | commands typed into the debugger. |
442 | |
443 | Here's an example of what a stack backtrace might look like: |
444 | |
445 | $ = main::infested called from file `Ambulation.pm' line 10 |
446 | @ = Ambulation::legs(1, 2, 3, 4) called from file `camel_flea' line 7 |
447 | $ = main::pests('bactrian', 4) called from file `camel_flea' line 4 |
448 | |
449 | The left-hand character up there tells whether the function was called |
450 | in a scalar or list context (we bet you can tell which is which). What |
451 | that says is that you were in the function C<main::infested> when you ran |
452 | the stack dump, and that it was called in a scalar context from line 10 |
453 | of the file I<Ambulation.pm>, but without any arguments at all, meaning |
454 | it was called as C<&infested>. The next stack frame shows that the |
455 | function C<Ambulation::legs> was called in a list context from the |
456 | I<camel_flea> file with four arguments. The last stack frame shows that |
457 | C<main::pests> was called in a scalar context, also from I<camel_flea>, |
458 | but from line 4. |
459 | |
460 | If you have any compile-time executable statements (code within a BEGIN |
461 | block or a C<use> statement), these will C<NOT> be stopped by debugger, |
462 | although C<require>s will. From your own Perl code, however, you can |
463 | transfer control back to the debugger using the following statement, |
464 | which is harmless if the debugger is not running: |
a0d0e21e |
465 | |
466 | $DB::single = 1; |
467 | |
4e1d3b43 |
468 | If you set C<$DB::single> to the value 2, it's equivalent to having |
469 | just typed the C<n> command, whereas a value of 1 means the C<s> |
470 | command. The C<$DB::trace> variable should be set to 1 to simulate |
471 | having typed the C<t> command. |
472 | |
473 | =head2 Debugger Customization |
a0d0e21e |
474 | |
475 | If you want to modify the debugger, copy F<perl5db.pl> from the Perl |
476 | library to another name and modify it as necessary. You'll also want |
4e1d3b43 |
477 | to set your PERL5DB environment variable to say something like this: |
a0d0e21e |
478 | |
479 | BEGIN { require "myperl5db.pl" } |
480 | |
481 | You can do some customization by setting up a F<.perldb> file which |
482 | contains initialization code. For instance, you could make aliases |
4e1d3b43 |
483 | like these (the last one is one people expect to be there): |
a0d0e21e |
484 | |
4e1d3b43 |
485 | $DB::alias{'len'} = 's/^len(.*)/p length($1)/'; |
a0d0e21e |
486 | $DB::alias{'stop'} = 's/^stop (at|in)/b/'; |
4e1d3b43 |
487 | $DB::alias{'ps'} = 's/^ps\b/p scalar /'; |
488 | $DB::alias{'quit'} = 's/^quit(\s*)/exit\$/'; |
489 | |
490 | =head2 Readline Support |
491 | |
492 | As shipped, the only command line history supplied is a simplistic one |
493 | that checks for leading exclamation points. However, if you install |
494 | the Term::ReadKey and Term::ReadLine modules from CPAN, you will |
495 | have full editing capabilities much like GNU I<readline>(3) provides. |
496 | Look for these in the F<modules/by-module/Term> directory on CPAN. |
497 | |
498 | =head2 Editor Support for Debugging |
499 | |
500 | If you have GNU B<emacs> installed on your system, it can interact with |
501 | the Perl debugger to provide an integrated software development |
502 | environment reminiscent of its interactions with C debuggers. |
503 | |
504 | Perl is also delivered with a start file for making B<emacs> act like a |
505 | syntax-directed editor that understands (some of) Perl's syntax. Look in |
506 | the I<emacs> directory of the Perl source distribution. |
507 | |
508 | (Historically, a similar setup for interacting with B<vi> and the |
509 | X11 window system had also been available, but at the time of this |
510 | writing, no debugger support for B<vi> currently exists.) |
511 | |
512 | =head2 The Perl Profiler |
513 | |
514 | If you wish to supply an alternative debugger for Perl to run, just |
515 | invoke your script with a colon and a package argument given to the B<-d> |
516 | flag. One of the most popular alternative debuggers for Perl is |
517 | B<DProf>, the Perl profiler. As of this writing, B<DProf> is not |
518 | included with the standard Perl distribution, but it is expected to |
519 | be included soon, for certain values of "soon". |
520 | |
521 | Meanwhile, you can fetch the Devel::Dprof module from CPAN. Assuming |
522 | it's properly installed on your system, to profile your Perl program in |
523 | the file F<mycode.pl>, just type: |
524 | |
525 | perl -d:DProf mycode.pl |
526 | |
527 | When the script terminates the profiler will dump the profile information |
528 | to a file called F<tmon.out>. A tool like B<dprofpp> (also supplied with |
529 | the Devel::DProf package) can be used to interpret the information which is |
530 | in that profile. |
531 | |
532 | =head2 Debugger Internals |
533 | |
534 | When you call the B<caller> function from package DB, Perl sets the |
535 | C<@DB::args> array to contain the arguments that stack frame was called |
536 | with. It also maintains other magical internal variables, such as |
537 | C<@DB::dbline>, an array of the source code lines for the currently |
538 | selected (with the debugger's C<f> command) file. Perl effectively |
539 | inserts a call to the function C<DB::DB>(I<linenum>) in front of every |
540 | place that can have a breakpoint. Instead of a subroutine call it calls |
541 | C<DB::sub> setting C<$DB::sub> being the called subroutine. It also |
542 | inserts a C<BEGIN {require 'perl5db.pl'}> before the first line. |
543 | |
544 | Note that no subroutine call is possible until C<&DB::sub> is defined |
545 | (for subroutines defined outside this file). In fact, the same is |
546 | true if C<$DB::deep> (how many levels of recursion deep into the |
547 | debugger you are) is not defined. |
a0d0e21e |
548 | |
4e1d3b43 |
549 | At the start, the debugger reads your rc file (F<./.perldb> or |
550 | F<~/.perldb> under UNIX), which can set important options. This file may |
551 | define a subroutine C<&afterinit> to be executed after the debugger is |
552 | initialized. |
553 | |
554 | After the rc file is read, the debugger reads environment variable |
555 | PERLDB_OPTS and parses it as a rest of C<O ...> line in debugger prompt. |
556 | |
557 | The following options can only be specified at startup. To set them in |
558 | your rc file, call C<&parse_options("optionName=new_value")>. |
559 | |
560 | =over 12 |
561 | |
562 | =item TTY |
563 | |
564 | The TTY to use for debugging I/O. |
565 | |
566 | =item noTTY |
567 | |
568 | If set, goes in C<NonStop> mode. On interrupt if TTY is not set uses the |
569 | value of C<noTTY> or "/tmp/perldbtty$$" to find TTY using |
570 | C<Term::Rendezvous>. Current variant is to have the name of TTY in this |
571 | file. |
572 | |
573 | =item ReadLine |
574 | |
575 | If false, dummy ReadLine is used, so you can debug |
576 | ReadLine applications. |
577 | |
578 | =item NonStop |
579 | |
580 | If true, no I/O is performed until an interrupt. |
581 | |
582 | =item LineInfo |
583 | |
584 | File or pipe to print line number info to. If it'sis a |
585 | pipe, then a short, "emacs like" message is used. |
586 | |
587 | Example rc file: |
588 | |
589 | &parse_options("NonStop=1 LineInfo=db.out"); |
590 | sub afterinit { $trace = 1; } |
591 | |
592 | The script will run without human intervention, putting trace information |
593 | into the file I<db.out>. (If you interrupt it, you would better reset |
594 | C<LineInfo> to something "interactive"!) |
595 | |
596 | =back |
a0d0e21e |
597 | |
598 | =head2 Other resources |
599 | |
600 | You did try the B<-w> switch, didn't you? |
601 | |
602 | =head1 BUGS |
603 | |
4e1d3b43 |
604 | If your program exit()s or die()s, so too does the debugger. |
a0d0e21e |
605 | |
4e1d3b43 |
606 | You cannot get the stack frame information or otherwise debug functions |
607 | that were not compiled by Perl, such as C or C++ extensions. |
a0d0e21e |
608 | |
4e1d3b43 |
609 | If you alter your @_ arguments in a subroutine (such as with B<shift> |
610 | or B<pop>, the stack backtrace will not show the original values. |
a0d0e21e |
611 | |