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 | ||
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 | |
5f05dabc | 14 | source code, set breakpoints, get stack back-traces, change the values of |
4e1d3b43 | 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 LW |
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 | ||
36477c24 | 65 | Same as C<print {$DB::OUT} expr> in the current package. In particular, |
5f05dabc | 66 | because this is just Perl's own B<print> function, this means that nested |
4e1d3b43 | 67 | data structures and objects are not dumped, unlike with the C<x> command. |
68 | ||
69 | =item x expr | |
70 | ||
5f05dabc | 71 | Evaluates its expression in list context and dumps out the result |
4e1d3b43 | 72 | in a pretty-printed fashion. Nested data structures are printed out |
73 | recursively, unlike the C<print> function. | |
74 | ||
36477c24 | 75 | The details of printout are governed by multiple C<O>ptions. |
76 | ||
4e1d3b43 | 77 | =item V [pkg [vars]] |
78 | ||
79 | Display all (or some) variables in package (defaulting to the C<main> | |
80 | package) using a data pretty-printer (hashes show their keys and values so | |
81 | you see what's what, control characters are made printable, etc.). Make | |
82 | sure you don't put the type specifier (like C<$>) there, just the symbol | |
83 | names, like this: | |
84 | ||
85 | V DB filename line | |
86 | ||
87 | Use C<~pattern> and C<!pattern> for positive and negative regexps. | |
a0d0e21e | 88 | |
4e1d3b43 | 89 | Nested data structures are printed out in a legible fashion, unlike |
90 | the C<print> function. | |
91 | ||
36477c24 | 92 | The details of printout are governed by multiple C<O>ptions. |
93 | ||
4e1d3b43 | 94 | =item X [vars] |
95 | ||
96 | Same as C<V currentpackage [vars]>. | |
a0d0e21e LW |
97 | |
98 | =item T | |
99 | ||
5f05dabc | 100 | Produce a stack back-trace. See below for details on its output. |
a0d0e21e | 101 | |
4e1d3b43 | 102 | =item s [expr] |
a0d0e21e LW |
103 | |
104 | Single step. Executes until it reaches the beginning of another | |
4e1d3b43 | 105 | statement, descending into subroutine calls. If an expression is |
106 | supplied that includes function calls, it too will be single-stepped. | |
a0d0e21e LW |
107 | |
108 | =item n | |
109 | ||
110 | Next. Executes over subroutine calls, until it reaches the beginning | |
111 | of the next statement. | |
112 | ||
184e9718 | 113 | =item E<lt>CRE<gt> |
a0d0e21e | 114 | |
4e1d3b43 | 115 | Repeat last C<n> or C<s> command. |
a0d0e21e | 116 | |
36477c24 | 117 | =item c [line|sub] |
a0d0e21e | 118 | |
4e1d3b43 | 119 | Continue, optionally inserting a one-time-only breakpoint |
36477c24 | 120 | at the specified line or subroutine. |
a0d0e21e | 121 | |
4e1d3b43 | 122 | =item l |
a0d0e21e | 123 | |
4e1d3b43 | 124 | List next window of lines. |
a0d0e21e LW |
125 | |
126 | =item l min+incr | |
127 | ||
4e1d3b43 | 128 | List C<incr+1> lines starting at C<min>. |
a0d0e21e LW |
129 | |
130 | =item l min-max | |
131 | ||
4e1d3b43 | 132 | List lines C<min> through C<max>. |
a0d0e21e LW |
133 | |
134 | =item l line | |
135 | ||
4e1d3b43 | 136 | List a single line. |
a0d0e21e | 137 | |
4e1d3b43 | 138 | =item l subname |
a0d0e21e | 139 | |
4e1d3b43 | 140 | List first window of lines from subroutine. |
a0d0e21e LW |
141 | |
142 | =item - | |
143 | ||
4e1d3b43 | 144 | List previous window of lines. |
a0d0e21e | 145 | |
4e1d3b43 | 146 | =item w [line] |
a0d0e21e | 147 | |
4e1d3b43 | 148 | List window (a few lines) around the current line. |
a0d0e21e | 149 | |
4e1d3b43 | 150 | =item . |
a0d0e21e | 151 | |
4e1d3b43 | 152 | Return debugger pointer to the last-executed line and |
153 | print it out. | |
154 | ||
155 | =item f filename | |
156 | ||
157 | Switch to viewing a different file. | |
a0d0e21e LW |
158 | |
159 | =item /pattern/ | |
160 | ||
4e1d3b43 | 161 | Search forwards for pattern; final / is optional. |
a0d0e21e LW |
162 | |
163 | =item ?pattern? | |
164 | ||
4e1d3b43 | 165 | Search backwards for pattern; final ? is optional. |
a0d0e21e LW |
166 | |
167 | =item L | |
168 | ||
36477c24 | 169 | List all breakpoints and actions. |
a0d0e21e | 170 | |
4e1d3b43 | 171 | =item S [[!]pattern] |
a0d0e21e | 172 | |
4e1d3b43 | 173 | List subroutine names [not] matching pattern. |
a0d0e21e LW |
174 | |
175 | =item t | |
176 | ||
36477c24 | 177 | Toggle trace mode (see also C<AutoTrace> C<O>ption). |
4e1d3b43 | 178 | |
179 | =item t expr | |
180 | ||
181 | Trace through execution of expr. For example: | |
182 | ||
183 | $ perl -de 42 | |
184 | Stack dump during die enabled outside of evals. | |
a0d0e21e | 185 | |
4e1d3b43 | 186 | Loading DB routines from perl5db.pl patch level 0.94 |
187 | Emacs support available. | |
188 | ||
189 | Enter h or `h h' for help. | |
190 | ||
191 | main::(-e:1): 0 | |
192 | DB<1> sub foo { 14 } | |
193 | ||
194 | DB<2> sub bar { 3 } | |
195 | ||
196 | DB<3> t print foo() * bar() | |
197 | main::((eval 172):3): print foo() + bar(); | |
198 | main::foo((eval 168):2): | |
199 | main::bar((eval 170):2): | |
200 | 42 | |
36477c24 | 201 | |
202 | or, with the C<O>ption C<frame=2> set, | |
203 | ||
204 | DB<4> O f=2 | |
205 | frame = '2' | |
206 | DB<5> t print foo() * bar() | |
207 | 3: foo() * bar() | |
208 | entering main::foo | |
209 | 2: sub foo { 14 }; | |
210 | exited main::foo | |
211 | entering main::bar | |
212 | 2: sub bar { 3 }; | |
213 | exited main::bar | |
214 | 42 | |
4e1d3b43 | 215 | |
216 | =item b [line] [condition] | |
a0d0e21e LW |
217 | |
218 | Set a breakpoint. If line is omitted, sets a breakpoint on the line | |
4e1d3b43 | 219 | that is about to be executed. If a condition is specified, it's |
a0d0e21e | 220 | evaluated each time the statement is reached and a breakpoint is taken |
5f05dabc | 221 | only if the condition is true. Breakpoints may be set on only lines |
4e1d3b43 | 222 | that begin an executable statement. Conditions don't use B<if>: |
a0d0e21e LW |
223 | |
224 | b 237 $x > 30 | |
36477c24 | 225 | b 237 ++$count237 < 11 |
a0d0e21e LW |
226 | b 33 /pattern/i |
227 | ||
4e1d3b43 | 228 | =item b subname [condition] |
a0d0e21e | 229 | |
4e1d3b43 | 230 | Set a breakpoint at the first line of the named subroutine. |
a0d0e21e | 231 | |
36477c24 | 232 | =item b postpone subname [condition] |
233 | ||
234 | Set breakpoint at first line of subroutine after it is compiled. | |
235 | ||
236 | =item b load filename | |
237 | ||
238 | Set breakpoint at the first executed line of the file. | |
239 | ||
4e1d3b43 | 240 | =item d [line] |
a0d0e21e | 241 | |
4e1d3b43 | 242 | Delete a breakpoint at the specified line. If line is omitted, deletes |
243 | the breakpoint on the line that is about to be executed. | |
a0d0e21e LW |
244 | |
245 | =item D | |
246 | ||
4e1d3b43 | 247 | Delete all installed breakpoints. |
248 | ||
249 | =item a [line] command | |
250 | ||
251 | Set an action to be done before the line is executed. | |
252 | The sequence of steps taken by the debugger is | |
253 | ||
8ebc5c01 | 254 | 1. check for a breakpoint at this line |
255 | 2. print the line if necessary (tracing) | |
256 | 3. do any actions associated with that line | |
257 | 4. prompt user if at a breakpoint or in single-step | |
258 | 5. evaluate line | |
a0d0e21e | 259 | |
4e1d3b43 | 260 | For example, this will print out C<$foo> every time line |
261 | 53 is passed: | |
a0d0e21e | 262 | |
4e1d3b43 | 263 | a 53 print "DB FOUND $foo\n" |
a0d0e21e LW |
264 | |
265 | =item A | |
266 | ||
4e1d3b43 | 267 | Delete all installed actions. |
268 | ||
269 | =item O [opt[=val]] [opt"val"] [opt?]... | |
270 | ||
271 | Set or query values of options. val defaults to 1. opt can | |
272 | be abbreviated. Several options can be listed. | |
273 | ||
274 | =over 12 | |
275 | ||
276 | =item recallCommand, ShellBang | |
277 | ||
278 | The characters used to recall command or spawn shell. By | |
279 | default, these are both set to C<!>. | |
280 | ||
281 | =item pager | |
282 | ||
283 | Program to use for output of pager-piped commands (those | |
284 | beginning with a C<|> character.) By default, | |
285 | C<$ENV{PAGER}> will be used. | |
286 | ||
36477c24 | 287 | =item tkRunning |
288 | ||
289 | Run Tk while prompting (with ReadLine). | |
290 | ||
291 | =item signalLevel, warnLevel, dieLevel | |
292 | ||
293 | Level of verbosity. | |
294 | ||
295 | =item AutoTrace | |
296 | ||
297 | Where to print all the breakable points in the executed program | |
298 | (similar to C<t> command, but can be put into C<PERLDB_OPTS>). | |
299 | ||
300 | =item LineInfo | |
301 | ||
302 | File or pipe to print line number info to. If it is a | |
303 | pipe, then a short, "emacs like" message is used. | |
304 | ||
305 | =item C<inhibit_exit> | |
306 | ||
307 | If 0, allows I<stepping off> the end of the script. | |
308 | ||
309 | =item C<PrintRet> | |
310 | ||
311 | affects printing of return value after C<r> command. | |
312 | ||
313 | =item C<frame> | |
314 | ||
315 | affects printing messages on entry and exit from subroutines. If | |
316 | C<frame & 2> is false, messages are printed on entry only. (Printing | |
5f05dabc | 317 | on exit may be useful if inter(di)spersed with other messages.) |
36477c24 | 318 | |
319 | If C<frame & 4>, arguments to functions are printed as well as the | |
320 | context and caller info. | |
321 | ||
4e1d3b43 | 322 | =back |
323 | ||
324 | The following options affect what happens with C<V>, C<X>, and C<x> | |
325 | commands: | |
326 | ||
327 | =over 12 | |
328 | ||
329 | =item arrayDepth, hashDepth | |
330 | ||
331 | Print only first N elements ('' for all). | |
332 | ||
333 | =item compactDump, veryCompact | |
334 | ||
335 | Change style of array and hash dump. | |
336 | ||
337 | =item globPrint | |
338 | ||
339 | Whether to print contents of globs. | |
340 | ||
341 | =item DumpDBFiles | |
342 | ||
343 | Dump arrays holding debugged files. | |
344 | ||
345 | =item DumpPackages | |
346 | ||
347 | Dump symbol tables of packages. | |
348 | ||
349 | =item quote, HighBit, undefPrint | |
350 | ||
351 | Change style of string dump. | |
352 | ||
36477c24 | 353 | =back |
4e1d3b43 | 354 | |
36477c24 | 355 | During startup options are initialized from C<$ENV{PERLDB_OPTS}>. |
356 | You can put additional initialization options C<TTY>, C<noTTY>, | |
357 | C<ReadLine>, and C<NonStop> there. | |
358 | ||
359 | Example rc file: | |
4e1d3b43 | 360 | |
36477c24 | 361 | &parse_options("NonStop=1 LineInfo=db.out AutoTrace"); |
4e1d3b43 | 362 | |
36477c24 | 363 | The script will run without human intervention, putting trace information |
364 | into the file I<db.out>. (If you interrupt it, you would better reset | |
365 | C<LineInfo> to something "interactive"!) | |
4e1d3b43 | 366 | |
36477c24 | 367 | =over 12 |
4e1d3b43 | 368 | |
36477c24 | 369 | =item C<TTY> |
4e1d3b43 | 370 | |
36477c24 | 371 | The TTY to use for debugging I/O. |
372 | ||
373 | =item noTTY | |
374 | ||
375 | If set, goes in C<NonStop> mode. On interrupt if TTY is not set uses the | |
376 | value of C<noTTY> or "/tmp/perldbtty$$" to find TTY using | |
377 | C<Term::Rendezvous>. Current variant is to have the name of TTY in this | |
378 | file. | |
379 | ||
380 | =item C<noTTY> | |
381 | ||
382 | If set, goes in C<NonStop> mode, and would not connect to a TTY. If | |
383 | interrupt (or if control goes to debugger via explicit setting of | |
384 | $DB::signal or $DB::single from the Perl script), connects to a TTY | |
385 | specified by the C<TTY> option at startup, or to a TTY found at | |
386 | runtime using C<Term::Rendezvous> module of your choice. | |
387 | ||
388 | This module should implement a method C<new> which returns an object | |
389 | with two methods: C<IN> and C<OUT>, returning two filehandles to use | |
390 | for debugging input and output correspondingly. Method C<new> may | |
391 | inspect an argument which is a value of C<$ENV{PERLDB_NOTTY}> at | |
392 | startup, or is C<"/tmp/perldbtty$$"> otherwise. | |
393 | ||
394 | =item C<ReadLine> | |
395 | ||
396 | If false, readline support in debugger is disabled, so you can debug | |
397 | ReadLine applications. | |
398 | ||
399 | =item C<NonStop> | |
400 | ||
401 | If set, debugger goes into non-interactive mode until interrupted, or | |
402 | programmatically by setting $DB::signal or $DB::single. | |
403 | ||
404 | =back | |
405 | ||
406 | Here's an example of using the C<$ENV{PERLDB_OPTS}> variable: | |
4e1d3b43 | 407 | |
408 | $ PERLDB_OPTS="N f=2" perl -d myprogram | |
409 | ||
410 | will run the script C<myprogram> without human intervention, printing | |
411 | out the call tree with entry and exit points. Note that C<N f=2> is | |
412 | equivalent to C<NonStop=1 frame=2>. Note also that at the moment when | |
413 | this documentation was written all the options to the debugger could | |
36477c24 | 414 | be uniquely abbreviated by the first letter (with exception of |
415 | C<Dump*> options). | |
4e1d3b43 | 416 | |
36477c24 | 417 | Other examples may include |
a0d0e21e | 418 | |
36477c24 | 419 | $ PERLDB_OPTS="N f A L=listing" perl -d myprogram |
a0d0e21e | 420 | |
36477c24 | 421 | - runs script non-interactively, printing info on each entry into a |
422 | subroutine and each executed line into the file F<listing>. (If you | |
423 | interrupt it, you would better reset C<LineInfo> to something | |
424 | "interactive"!) | |
425 | ||
426 | ||
427 | $ env "PERLDB_OPTS=R=0 TTY=/dev/ttyc" perl -d myprogram | |
428 | ||
429 | may be useful for debugging a program which uses C<Term::ReadLine> | |
430 | itself. Do not forget detach shell from the TTY in the window which | |
431 | corresponds to F</dev/ttyc>, say, by issuing a command like | |
432 | ||
433 | $ sleep 1000000 | |
434 | ||
435 | See L<"Debugger Internals"> below for more details. | |
436 | ||
8ebc5c01 | 437 | =over 12 |
438 | ||
36477c24 | 439 | =item E<lt> [ command ] |
440 | ||
441 | Set an action (Perl command) to happen before every debugger prompt. | |
5f05dabc | 442 | A multi-line command may be entered by backslashing the newlines. If |
36477c24 | 443 | C<command> is missing, resets the list of actions. |
444 | ||
445 | =item E<lt>E<lt> command | |
446 | ||
447 | Add an action (Perl command) to happen before every debugger prompt. | |
5f05dabc | 448 | A multi-line command may be entered by backslashing the newlines. |
a0d0e21e | 449 | |
184e9718 | 450 | =item E<gt> command |
a0d0e21e | 451 | |
36477c24 | 452 | Set an action (Perl command) to happen after the prompt when you've |
5f05dabc | 453 | just given a command to return to executing the script. A multi-line |
36477c24 | 454 | command may be entered by backslashing the newlines. If C<command> is |
455 | missing, resets the list of actions. | |
456 | ||
457 | =item E<gt>E<gt> command | |
458 | ||
459 | Adds an action (Perl command) to happen after the prompt when you've | |
5f05dabc | 460 | just given a command to return to executing the script. A multi-line |
36477c24 | 461 | command may be entered by backslashing the newlines. |
462 | ||
463 | =item { [ command ] | |
464 | ||
465 | Set an action (debugger command) to happen before every debugger prompt. | |
5f05dabc | 466 | A multi-line command may be entered by backslashing the newlines. If |
36477c24 | 467 | C<command> is missing, resets the list of actions. |
468 | ||
469 | =item {{ command | |
470 | ||
471 | Add an action (debugger command) to happen before every debugger prompt. | |
5f05dabc | 472 | A multi-line command may be entered by backslashing the newlines. |
a0d0e21e | 473 | |
4e1d3b43 | 474 | =item ! number |
a0d0e21e | 475 | |
4e1d3b43 | 476 | Redo a previous command (default previous command). |
a0d0e21e | 477 | |
4e1d3b43 | 478 | =item ! -number |
a0d0e21e | 479 | |
4e1d3b43 | 480 | Redo number'th-to-last command. |
a0d0e21e | 481 | |
4e1d3b43 | 482 | =item ! pattern |
a0d0e21e | 483 | |
4e1d3b43 | 484 | Redo last command that started with pattern. |
485 | See C<O recallCommand>, too. | |
a0d0e21e | 486 | |
4e1d3b43 | 487 | =item !! cmd |
a0d0e21e | 488 | |
4e1d3b43 | 489 | Run cmd in a subprocess (reads from DB::IN, writes to DB::OUT) |
490 | See C<O shellBang> too. | |
a0d0e21e LW |
491 | |
492 | =item H -number | |
493 | ||
494 | Display last n commands. Only commands longer than one character are | |
495 | listed. If number is omitted, lists them all. | |
496 | ||
497 | =item q or ^D | |
498 | ||
36477c24 | 499 | Quit. ("quit" doesn't work for this.) This is the only supported way |
500 | to exit the debugger, though typing C<exit> twice may do it too. | |
501 | ||
502 | Set an C<O>ption C<inhibit_exit> to 0 if you want to be able to I<step | |
503 | off> the end the script. You may also need to set C<$finished> to 0 at | |
504 | some moment if you want to step through global destruction. | |
a0d0e21e | 505 | |
4e1d3b43 | 506 | =item R |
507 | ||
508 | Restart the debugger by B<exec>ing a new session. It tries to maintain | |
509 | your history across this, but internal settings and command line options | |
510 | may be lost. | |
511 | ||
5f05dabc | 512 | Currently the following setting are preserved: history, breakpoints, |
513 | actions, debugger C<O>ptions, and the following command-line | |
514 | options: B<-w>, B<-I>, and B<-e>. | |
36477c24 | 515 | |
4e1d3b43 | 516 | =item |dbcmd |
517 | ||
518 | Run debugger command, piping DB::OUT to current pager. | |
519 | ||
520 | =item ||dbcmd | |
521 | ||
522 | Same as C<|dbcmd> but DB::OUT is temporarily B<select>ed as well. | |
523 | Often used with commands that would otherwise produce long | |
524 | output, such as | |
525 | ||
526 | |V main | |
527 | ||
528 | =item = [alias value] | |
529 | ||
530 | Define a command alias, or list current aliases. | |
531 | ||
a0d0e21e LW |
532 | =item command |
533 | ||
534 | Execute command as a Perl statement. A missing semicolon will be | |
535 | supplied. | |
536 | ||
537 | =item p expr | |
538 | ||
539 | Same as C<print DB::OUT expr>. The DB::OUT filehandle is opened to | |
540 | /dev/tty, regardless of where STDOUT may be redirected to. | |
541 | ||
542 | =back | |
543 | ||
4e1d3b43 | 544 | The debugger prompt is something like |
545 | ||
546 | DB<8> | |
547 | ||
548 | or even | |
549 | ||
550 | DB<<17>> | |
551 | ||
552 | where that number is the command number, which you'd use to access with | |
5f05dabc | 553 | the built-in B<csh>-like history mechanism, e.g., C<!17> would repeat |
4e1d3b43 | 554 | command number 17. The number of angle brackets indicates the depth of |
555 | the debugger. You could get more than one set of brackets, for example, if | |
556 | you'd already at a breakpoint and then printed out the result of a | |
36477c24 | 557 | function call that itself also has a breakpoint, or you step into an |
558 | expression via C<s/n/t expression> command. | |
4e1d3b43 | 559 | |
560 | If you want to enter a multi-line command, such as a subroutine | |
561 | definition with several statements, you may escape the newline that would | |
562 | normally end the debugger command with a backslash. Here's an example: | |
a0d0e21e | 563 | |
4e1d3b43 | 564 | DB<1> for (1..4) { \ |
565 | cont: print "ok\n"; \ | |
566 | cont: } | |
567 | ok | |
568 | ok | |
569 | ok | |
570 | ok | |
571 | ||
572 | Note that this business of escaping a newline is specific to interactive | |
573 | commands typed into the debugger. | |
574 | ||
5f05dabc | 575 | Here's an example of what a stack back-trace might look like: |
4e1d3b43 | 576 | |
577 | $ = main::infested called from file `Ambulation.pm' line 10 | |
578 | @ = Ambulation::legs(1, 2, 3, 4) called from file `camel_flea' line 7 | |
579 | $ = main::pests('bactrian', 4) called from file `camel_flea' line 4 | |
580 | ||
581 | The left-hand character up there tells whether the function was called | |
582 | in a scalar or list context (we bet you can tell which is which). What | |
583 | that says is that you were in the function C<main::infested> when you ran | |
584 | the stack dump, and that it was called in a scalar context from line 10 | |
585 | of the file I<Ambulation.pm>, but without any arguments at all, meaning | |
586 | it was called as C<&infested>. The next stack frame shows that the | |
587 | function C<Ambulation::legs> was called in a list context from the | |
588 | I<camel_flea> file with four arguments. The last stack frame shows that | |
589 | C<main::pests> was called in a scalar context, also from I<camel_flea>, | |
590 | but from line 4. | |
591 | ||
592 | If you have any compile-time executable statements (code within a BEGIN | |
593 | block or a C<use> statement), these will C<NOT> be stopped by debugger, | |
36477c24 | 594 | although C<require>s will (and compile-time statements can be traced |
595 | with C<AutoTrace> option set in C<PERLDB_OPTS>). From your own Perl | |
596 | code, however, you can | |
4e1d3b43 | 597 | transfer control back to the debugger using the following statement, |
598 | which is harmless if the debugger is not running: | |
a0d0e21e LW |
599 | |
600 | $DB::single = 1; | |
601 | ||
4e1d3b43 | 602 | If you set C<$DB::single> to the value 2, it's equivalent to having |
603 | just typed the C<n> command, whereas a value of 1 means the C<s> | |
604 | command. The C<$DB::trace> variable should be set to 1 to simulate | |
605 | having typed the C<t> command. | |
606 | ||
607 | =head2 Debugger Customization | |
a0d0e21e | 608 | |
36477c24 | 609 | Most probably you not want to modify the debugger, it contains enough |
610 | hooks to satisfy most needs. You may change the behaviour of debugger | |
611 | from the debugger itself, using C<O>ptions, from the command line via | |
612 | C<PERLDB_OPTS> environment variable, and from I<customization files>. | |
a0d0e21e LW |
613 | |
614 | You can do some customization by setting up a F<.perldb> file which | |
615 | contains initialization code. For instance, you could make aliases | |
4e1d3b43 | 616 | like these (the last one is one people expect to be there): |
a0d0e21e | 617 | |
4e1d3b43 | 618 | $DB::alias{'len'} = 's/^len(.*)/p length($1)/'; |
a0d0e21e | 619 | $DB::alias{'stop'} = 's/^stop (at|in)/b/'; |
4e1d3b43 | 620 | $DB::alias{'ps'} = 's/^ps\b/p scalar /'; |
621 | $DB::alias{'quit'} = 's/^quit(\s*)/exit\$/'; | |
622 | ||
36477c24 | 623 | One changes options from F<.perldb> file via calls like this one; |
624 | ||
625 | parse_options("NonStop=1 LineInfo=db.out AutoTrace=1 frame=2"); | |
626 | ||
627 | (the code is executed in the package C<DB>). Note that F<.perldb> is | |
628 | processed before processing C<PERLDB_OPTS>. If F<.perldb> defines the | |
629 | subroutine C<afterinit>, it is called after all the debugger | |
630 | initialization ends. F<.perldb> may be contained in the current | |
631 | directory, or in the C<LOGDIR>/C<HOME> directory. | |
632 | ||
633 | If you want to modify the debugger, copy F<perl5db.pl> from the Perl | |
634 | library to another name and modify it as necessary. You'll also want | |
635 | to set your C<PERL5DB> environment variable to say something like this: | |
636 | ||
637 | BEGIN { require "myperl5db.pl" } | |
638 | ||
639 | As the last resort, one can use C<PERL5DB> to customize debugger by | |
640 | directly setting internal variables or calling debugger functions. | |
641 | ||
4e1d3b43 | 642 | =head2 Readline Support |
643 | ||
644 | As shipped, the only command line history supplied is a simplistic one | |
645 | that checks for leading exclamation points. However, if you install | |
646 | the Term::ReadKey and Term::ReadLine modules from CPAN, you will | |
647 | have full editing capabilities much like GNU I<readline>(3) provides. | |
648 | Look for these in the F<modules/by-module/Term> directory on CPAN. | |
649 | ||
650 | =head2 Editor Support for Debugging | |
651 | ||
652 | If you have GNU B<emacs> installed on your system, it can interact with | |
653 | the Perl debugger to provide an integrated software development | |
654 | environment reminiscent of its interactions with C debuggers. | |
655 | ||
656 | Perl is also delivered with a start file for making B<emacs> act like a | |
657 | syntax-directed editor that understands (some of) Perl's syntax. Look in | |
658 | the I<emacs> directory of the Perl source distribution. | |
659 | ||
660 | (Historically, a similar setup for interacting with B<vi> and the | |
661 | X11 window system had also been available, but at the time of this | |
662 | writing, no debugger support for B<vi> currently exists.) | |
663 | ||
664 | =head2 The Perl Profiler | |
665 | ||
666 | If you wish to supply an alternative debugger for Perl to run, just | |
667 | invoke your script with a colon and a package argument given to the B<-d> | |
668 | flag. One of the most popular alternative debuggers for Perl is | |
669 | B<DProf>, the Perl profiler. As of this writing, B<DProf> is not | |
670 | included with the standard Perl distribution, but it is expected to | |
671 | be included soon, for certain values of "soon". | |
672 | ||
673 | Meanwhile, you can fetch the Devel::Dprof module from CPAN. Assuming | |
674 | it's properly installed on your system, to profile your Perl program in | |
675 | the file F<mycode.pl>, just type: | |
676 | ||
677 | perl -d:DProf mycode.pl | |
678 | ||
679 | When the script terminates the profiler will dump the profile information | |
680 | to a file called F<tmon.out>. A tool like B<dprofpp> (also supplied with | |
681 | the Devel::DProf package) can be used to interpret the information which is | |
682 | in that profile. | |
683 | ||
36477c24 | 684 | =head2 Debugger support in perl |
4e1d3b43 | 685 | |
686 | When you call the B<caller> function from package DB, Perl sets the | |
687 | C<@DB::args> array to contain the arguments that stack frame was called | |
36477c24 | 688 | with. |
4e1d3b43 | 689 | |
36477c24 | 690 | If perl is run with B<-d> option, the following additional features |
691 | are enabled: | |
a0d0e21e | 692 | |
36477c24 | 693 | =over |
4e1d3b43 | 694 | |
36477c24 | 695 | =item * |
4e1d3b43 | 696 | |
36477c24 | 697 | Perl inserts the contents of C<$ENV{PERL5DB}> (or C<BEGIN {require |
698 | 'perl5db.pl'}> if not present) before the first line of the | |
699 | application. | |
4e1d3b43 | 700 | |
36477c24 | 701 | =item * |
4e1d3b43 | 702 | |
36477c24 | 703 | The array C<@{"_<$filename"}> is the line-by-line contents of |
704 | $filename for all the compiled files. Same for C<eval>ed strings which | |
705 | contain subroutines, or which are currently executed. The C<$filename> | |
706 | for C<eval>ed strings looks like C<(eval 34)>. | |
4e1d3b43 | 707 | |
36477c24 | 708 | =item * |
4e1d3b43 | 709 | |
36477c24 | 710 | The hash C<%{"_<$filename"}> contains breakpoints and action (it is |
711 | keyed by line number), and individual entries are settable (as opposed | |
712 | to the whole hash). Only true/false is important to Perl, though the | |
713 | values used by F<perl5db.pl> have the form | |
714 | C<"$break_condition\0$action">. Values are magical in numeric context: | |
715 | they are zeros if the line is not breakable. | |
4e1d3b43 | 716 | |
36477c24 | 717 | Same for evaluated strings which contain subroutines, or which are |
718 | currently executed. The C<$filename> for C<eval>ed strings looks like | |
719 | C<(eval 34)>. | |
4e1d3b43 | 720 | |
36477c24 | 721 | =item * |
4e1d3b43 | 722 | |
36477c24 | 723 | The scalar C<${"_<$filename"}> contains C<"_<$filename">. Same for |
724 | evaluated strings which contain subroutines, or which are currently | |
725 | executed. The C<$filename> for C<eval>ed strings looks like C<(eval | |
726 | 34)>. | |
4e1d3b43 | 727 | |
36477c24 | 728 | =item * |
4e1d3b43 | 729 | |
36477c24 | 730 | After each C<require>d file is compiled, but before it is executed, |
731 | C<DB::postponed(*{"_<$filename"})> is called (if subroutine | |
732 | C<DB::postponed> exists). Here the $filename is the expanded name of | |
733 | the C<require>d file (as found in values of C<%INC>). | |
4e1d3b43 | 734 | |
36477c24 | 735 | =item * |
4e1d3b43 | 736 | |
36477c24 | 737 | After each subroutine C<subname> is compiled existence of |
738 | C<$DB::postponed{subname}> is checked. If this key exists, | |
739 | C<DB::postponed(subname)> is called (if subroutine C<DB::postponed> | |
740 | exists). | |
4e1d3b43 | 741 | |
36477c24 | 742 | =item * |
4e1d3b43 | 743 | |
36477c24 | 744 | A hash C<%DB::sub> is maintained, with keys being subroutine names, |
745 | values having the form C<filename:startline-endline>. C<filename> has | |
746 | the form C<(eval 31)> for subroutines defined inside C<eval>s. | |
4e1d3b43 | 747 | |
36477c24 | 748 | =item * |
749 | ||
5f05dabc | 750 | When execution of the application reaches a place that can have |
751 | a breakpoint, a call to C<DB::DB()> is performed if any one of | |
752 | variables $DB::trace, $DB::single, or $DB::signal is true. (Note that | |
36477c24 | 753 | these variables are not C<local>izable.) This feature is disabled when |
754 | the control is inside C<DB::DB()> or functions called from it (unless | |
755 | C<$^D & 1 E<lt>E<lt> 30>). | |
756 | ||
757 | =item * | |
758 | ||
5f05dabc | 759 | When execution of the application reaches a subroutine call, a call |
36477c24 | 760 | to C<&DB::sub>(I<args>) is performed instead, with C<$DB::sub> being |
761 | the name of the called subroutine. (Unless the subroutine is compiled | |
762 | in the package C<DB>.) | |
4e1d3b43 | 763 | |
764 | =back | |
a0d0e21e | 765 | |
36477c24 | 766 | Note that no subroutine call is possible until C<&DB::sub> is defined |
767 | (for subroutines outside of package C<DB>). (In fact, for the | |
768 | standard debugger the same is true if C<$DB::deep> (how many levels of | |
769 | recursion deep into the debugger you can go before a mandatory break) | |
770 | is not defined.) | |
771 | ||
772 | =head2 Debugger Internals | |
773 | ||
774 | At the start, the debugger reads your rc file (F<./.perldb> or | |
775 | F<~/.perldb> under UNIX), which can set important options. This file may | |
776 | define a subroutine C<&afterinit> to be executed after the debugger is | |
777 | initialized. | |
778 | ||
5f05dabc | 779 | After the rc file is read, the debugger reads environment variable |
36477c24 | 780 | PERLDB_OPTS and parses it as a rest of C<O ...> line in debugger prompt. |
781 | ||
782 | It also maintains magical internal variables, such as C<@DB::dbline>, | |
783 | C<%DB::dbline>, which are aliases for C<@{"::_<current_file"}> | |
784 | C<%{"::_<current_file"}>. Here C<current_file> is the currently | |
785 | selected (with the debugger's C<f> command, or by flow of execution) | |
786 | file. | |
787 | ||
788 | Some functions are provided to simplify customization. See L<"Debugger | |
789 | Customization"> for description of C<DB::parse_options(string)>. The | |
790 | function C<DB::dump_trace(skip[, count])> skips the specified number | |
791 | of frames, and returns an array containing info about the caller | |
792 | frames (all if C<count> is missing). Each entry is a hash with keys | |
793 | C<context> (C<$> or C<@>), C<sub> (subroutine name, or info about | |
5f05dabc | 794 | eval), C<args> (C<undef> or a reference to an array), C<file>, and |
36477c24 | 795 | C<line>. |
796 | ||
797 | The function C<DB::print_trace(FH, skip[, count[, short]])> prints | |
798 | formatted info about caller frames. The last two functions may be | |
799 | convenient as arguments to C<E<lt>>, C<E<lt>E<lt>> commands. | |
800 | ||
a0d0e21e LW |
801 | =head2 Other resources |
802 | ||
803 | You did try the B<-w> switch, didn't you? | |
804 | ||
805 | =head1 BUGS | |
806 | ||
4e1d3b43 | 807 | You cannot get the stack frame information or otherwise debug functions |
808 | that were not compiled by Perl, such as C or C++ extensions. | |
a0d0e21e | 809 | |
4e1d3b43 | 810 | If you alter your @_ arguments in a subroutine (such as with B<shift> |
5f05dabc | 811 | or B<pop>, the stack back-trace will not show the original values. |