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 |
68dc0745 |
14 | source code, set breakpoints, get stack backtraces, change the values of |
4e1d3b43 |
15 | variables, etc. This is so convenient that you often fire up |
54310121 |
16 | the debugger all by itself just to test out Perl constructs |
4e1d3b43 |
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 |
54310121 |
26 | preloads a Perl library file containing the debugger itself. |
4e1d3b43 |
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 | |
54310121 |
50 | Prints out a help message. |
4e1d3b43 |
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 | |
e7ea3e70 |
63 | You may change the pager which is used via C<O pager=...> command. |
64 | |
4e1d3b43 |
65 | =item p expr |
66 | |
36477c24 |
67 | Same as C<print {$DB::OUT} expr> in the current package. In particular, |
5f05dabc |
68 | because this is just Perl's own B<print> function, this means that nested |
4e1d3b43 |
69 | data structures and objects are not dumped, unlike with the C<x> command. |
70 | |
e7ea3e70 |
71 | The C<DB::OUT> filehandle is opened to F</dev/tty>, regardless of |
72 | where STDOUT may be redirected to. |
73 | |
4e1d3b43 |
74 | =item x expr |
75 | |
54310121 |
76 | Evaluates its expression in list context and dumps out the result |
4e1d3b43 |
77 | in a pretty-printed fashion. Nested data structures are printed out |
78 | recursively, unlike the C<print> function. |
79 | |
36477c24 |
80 | The details of printout are governed by multiple C<O>ptions. |
81 | |
4e1d3b43 |
82 | =item V [pkg [vars]] |
83 | |
84 | Display all (or some) variables in package (defaulting to the C<main> |
85 | package) using a data pretty-printer (hashes show their keys and values so |
86 | you see what's what, control characters are made printable, etc.). Make |
87 | sure you don't put the type specifier (like C<$>) there, just the symbol |
88 | names, like this: |
89 | |
90 | V DB filename line |
91 | |
92 | Use C<~pattern> and C<!pattern> for positive and negative regexps. |
a0d0e21e |
93 | |
4e1d3b43 |
94 | Nested data structures are printed out in a legible fashion, unlike |
95 | the C<print> function. |
96 | |
36477c24 |
97 | The details of printout are governed by multiple C<O>ptions. |
98 | |
4e1d3b43 |
99 | =item X [vars] |
100 | |
101 | Same as C<V currentpackage [vars]>. |
a0d0e21e |
102 | |
103 | =item T |
104 | |
68dc0745 |
105 | Produce a stack backtrace. See below for details on its output. |
a0d0e21e |
106 | |
4e1d3b43 |
107 | =item s [expr] |
a0d0e21e |
108 | |
109 | Single step. Executes until it reaches the beginning of another |
4e1d3b43 |
110 | statement, descending into subroutine calls. If an expression is |
111 | supplied that includes function calls, it too will be single-stepped. |
a0d0e21e |
112 | |
e7ea3e70 |
113 | =item n [expr] |
a0d0e21e |
114 | |
115 | Next. Executes over subroutine calls, until it reaches the beginning |
774d564b |
116 | of the next statement. If an expression is supplied that includes |
117 | function calls, those functions will be executed with stops before |
118 | each statement. |
a0d0e21e |
119 | |
184e9718 |
120 | =item E<lt>CRE<gt> |
a0d0e21e |
121 | |
4e1d3b43 |
122 | Repeat last C<n> or C<s> command. |
a0d0e21e |
123 | |
36477c24 |
124 | =item c [line|sub] |
a0d0e21e |
125 | |
4e1d3b43 |
126 | Continue, optionally inserting a one-time-only breakpoint |
36477c24 |
127 | at the specified line or subroutine. |
a0d0e21e |
128 | |
4e1d3b43 |
129 | =item l |
a0d0e21e |
130 | |
4e1d3b43 |
131 | List next window of lines. |
a0d0e21e |
132 | |
133 | =item l min+incr |
134 | |
4e1d3b43 |
135 | List C<incr+1> lines starting at C<min>. |
a0d0e21e |
136 | |
137 | =item l min-max |
138 | |
774d564b |
139 | List lines C<min> through C<max>. C<l -> is synonymous to C<->. |
a0d0e21e |
140 | |
141 | =item l line |
142 | |
4e1d3b43 |
143 | List a single line. |
a0d0e21e |
144 | |
4e1d3b43 |
145 | =item l subname |
a0d0e21e |
146 | |
4e1d3b43 |
147 | List first window of lines from subroutine. |
a0d0e21e |
148 | |
149 | =item - |
150 | |
4e1d3b43 |
151 | List previous window of lines. |
a0d0e21e |
152 | |
4e1d3b43 |
153 | =item w [line] |
a0d0e21e |
154 | |
4e1d3b43 |
155 | List window (a few lines) around the current line. |
a0d0e21e |
156 | |
4e1d3b43 |
157 | =item . |
a0d0e21e |
158 | |
4e1d3b43 |
159 | Return debugger pointer to the last-executed line and |
160 | print it out. |
161 | |
162 | =item f filename |
163 | |
774d564b |
164 | Switch to viewing a different file or eval statement. If C<filename> |
e7ea3e70 |
165 | is not a full filename as found in values of %INC, it is considered as |
166 | a regexp. |
a0d0e21e |
167 | |
168 | =item /pattern/ |
169 | |
4e1d3b43 |
170 | Search forwards for pattern; final / is optional. |
a0d0e21e |
171 | |
172 | =item ?pattern? |
173 | |
4e1d3b43 |
174 | Search backwards for pattern; final ? is optional. |
a0d0e21e |
175 | |
176 | =item L |
177 | |
36477c24 |
178 | List all breakpoints and actions. |
a0d0e21e |
179 | |
4e1d3b43 |
180 | =item S [[!]pattern] |
a0d0e21e |
181 | |
4e1d3b43 |
182 | List subroutine names [not] matching pattern. |
a0d0e21e |
183 | |
184 | =item t |
185 | |
36477c24 |
186 | Toggle trace mode (see also C<AutoTrace> C<O>ption). |
4e1d3b43 |
187 | |
188 | =item t expr |
189 | |
190 | Trace through execution of expr. For example: |
191 | |
192 | $ perl -de 42 |
193 | Stack dump during die enabled outside of evals. |
a0d0e21e |
194 | |
4e1d3b43 |
195 | Loading DB routines from perl5db.pl patch level 0.94 |
196 | Emacs support available. |
197 | |
198 | Enter h or `h h' for help. |
199 | |
200 | main::(-e:1): 0 |
201 | DB<1> sub foo { 14 } |
202 | |
203 | DB<2> sub bar { 3 } |
204 | |
205 | DB<3> t print foo() * bar() |
206 | main::((eval 172):3): print foo() + bar(); |
207 | main::foo((eval 168):2): |
208 | main::bar((eval 170):2): |
209 | 42 |
36477c24 |
210 | |
211 | or, with the C<O>ption C<frame=2> set, |
212 | |
213 | DB<4> O f=2 |
214 | frame = '2' |
215 | DB<5> t print foo() * bar() |
216 | 3: foo() * bar() |
217 | entering main::foo |
218 | 2: sub foo { 14 }; |
219 | exited main::foo |
220 | entering main::bar |
221 | 2: sub bar { 3 }; |
222 | exited main::bar |
223 | 42 |
4e1d3b43 |
224 | |
225 | =item b [line] [condition] |
a0d0e21e |
226 | |
227 | Set a breakpoint. If line is omitted, sets a breakpoint on the line |
4e1d3b43 |
228 | that is about to be executed. If a condition is specified, it's |
a0d0e21e |
229 | evaluated each time the statement is reached and a breakpoint is taken |
5f05dabc |
230 | only if the condition is true. Breakpoints may be set on only lines |
4e1d3b43 |
231 | that begin an executable statement. Conditions don't use B<if>: |
a0d0e21e |
232 | |
233 | b 237 $x > 30 |
36477c24 |
234 | b 237 ++$count237 < 11 |
a0d0e21e |
235 | b 33 /pattern/i |
236 | |
4e1d3b43 |
237 | =item b subname [condition] |
a0d0e21e |
238 | |
4e1d3b43 |
239 | Set a breakpoint at the first line of the named subroutine. |
a0d0e21e |
240 | |
36477c24 |
241 | =item b postpone subname [condition] |
242 | |
243 | Set breakpoint at first line of subroutine after it is compiled. |
244 | |
245 | =item b load filename |
246 | |
774d564b |
247 | Set breakpoint at the first executed line of the file. Filename should |
e7ea3e70 |
248 | be a full name as found in values of %INC. |
249 | |
250 | =item b compile subname |
251 | |
252 | Sets breakpoint at the first statement executed after the subroutine |
253 | is compiled. |
36477c24 |
254 | |
4e1d3b43 |
255 | =item d [line] |
a0d0e21e |
256 | |
4e1d3b43 |
257 | Delete a breakpoint at the specified line. If line is omitted, deletes |
258 | the breakpoint on the line that is about to be executed. |
a0d0e21e |
259 | |
260 | =item D |
261 | |
4e1d3b43 |
262 | Delete all installed breakpoints. |
263 | |
264 | =item a [line] command |
265 | |
266 | Set an action to be done before the line is executed. |
267 | The sequence of steps taken by the debugger is |
268 | |
8ebc5c01 |
269 | 1. check for a breakpoint at this line |
270 | 2. print the line if necessary (tracing) |
271 | 3. do any actions associated with that line |
272 | 4. prompt user if at a breakpoint or in single-step |
273 | 5. evaluate line |
a0d0e21e |
274 | |
4e1d3b43 |
275 | For example, this will print out C<$foo> every time line |
276 | 53 is passed: |
a0d0e21e |
277 | |
4e1d3b43 |
278 | a 53 print "DB FOUND $foo\n" |
a0d0e21e |
279 | |
280 | =item A |
281 | |
4e1d3b43 |
282 | Delete all installed actions. |
283 | |
284 | =item O [opt[=val]] [opt"val"] [opt?]... |
285 | |
286 | Set or query values of options. val defaults to 1. opt can |
287 | be abbreviated. Several options can be listed. |
288 | |
289 | =over 12 |
290 | |
e7ea3e70 |
291 | =item C<recallCommand>, C<ShellBang> |
4e1d3b43 |
292 | |
293 | The characters used to recall command or spawn shell. By |
294 | default, these are both set to C<!>. |
295 | |
e7ea3e70 |
296 | =item C<pager> |
4e1d3b43 |
297 | |
298 | Program to use for output of pager-piped commands (those |
299 | beginning with a C<|> character.) By default, |
300 | C<$ENV{PAGER}> will be used. |
301 | |
e7ea3e70 |
302 | =item C<tkRunning> |
36477c24 |
303 | |
304 | Run Tk while prompting (with ReadLine). |
305 | |
e7ea3e70 |
306 | =item C<signalLevel>, C<warnLevel>, C<dieLevel> |
307 | |
774d564b |
308 | Level of verbosity. By default the debugger is in a sane verbose mode, |
e7ea3e70 |
309 | thus it will print backtraces on all the warnings and die-messages |
310 | which are going to be printed out, and will print a message when |
54310121 |
311 | interesting uncaught signals arrive. |
36477c24 |
312 | |
774d564b |
313 | To disable this behaviour, set these values to 0. If C<dieLevel> is 2, |
e7ea3e70 |
314 | then the messages which will be caught by surrounding C<eval> are also |
315 | printed. |
36477c24 |
316 | |
e7ea3e70 |
317 | =item C<AutoTrace> |
36477c24 |
318 | |
e7ea3e70 |
319 | Trace mode (similar to C<t> command, but can be put into |
320 | C<PERLDB_OPTS>). |
36477c24 |
321 | |
e7ea3e70 |
322 | =item C<LineInfo> |
36477c24 |
323 | |
e7ea3e70 |
324 | File or pipe to print line number info to. If it is a pipe (say, |
325 | C<|visual_perl_db>), then a short, "emacs like" message is used. |
36477c24 |
326 | |
327 | =item C<inhibit_exit> |
328 | |
329 | If 0, allows I<stepping off> the end of the script. |
330 | |
54310121 |
331 | =item C<PrintRet> |
36477c24 |
332 | |
333 | affects printing of return value after C<r> command. |
334 | |
28d1fb14 |
335 | =item C<ornaments> |
336 | |
337 | affects screen appearance of the command line (see L<Term::Readline>). |
338 | |
54310121 |
339 | =item C<frame> |
36477c24 |
340 | |
341 | affects printing messages on entry and exit from subroutines. If |
342 | C<frame & 2> is false, messages are printed on entry only. (Printing |
5f05dabc |
343 | on exit may be useful if inter(di)spersed with other messages.) |
36477c24 |
344 | |
345 | If C<frame & 4>, arguments to functions are printed as well as the |
774d564b |
346 | context and caller info. If C<frame & 8>, overloaded C<stringify> and |
28d1fb14 |
347 | C<tie>d C<FETCH> are enabled on the printed arguments. If C<frame & |
348 | 16>, the return value from the subroutine is printed as well. |
349 | |
350 | The length at which the argument list is truncated is governed by the |
351 | next option: |
e7ea3e70 |
352 | |
353 | =item C<maxTraceLen> |
354 | |
355 | length at which the argument list is truncated when C<frame> option's |
356 | bit 4 is set. |
36477c24 |
357 | |
4e1d3b43 |
358 | =back |
359 | |
360 | The following options affect what happens with C<V>, C<X>, and C<x> |
361 | commands: |
362 | |
363 | =over 12 |
364 | |
e7ea3e70 |
365 | =item C<arrayDepth>, C<hashDepth> |
4e1d3b43 |
366 | |
367 | Print only first N elements ('' for all). |
368 | |
e7ea3e70 |
369 | =item C<compactDump>, C<veryCompact> |
4e1d3b43 |
370 | |
774d564b |
371 | Change style of array and hash dump. If C<compactDump>, short array |
e7ea3e70 |
372 | may be printed on one line. |
4e1d3b43 |
373 | |
e7ea3e70 |
374 | =item C<globPrint> |
4e1d3b43 |
375 | |
376 | Whether to print contents of globs. |
377 | |
e7ea3e70 |
378 | =item C<DumpDBFiles> |
4e1d3b43 |
379 | |
380 | Dump arrays holding debugged files. |
381 | |
e7ea3e70 |
382 | =item C<DumpPackages> |
4e1d3b43 |
383 | |
384 | Dump symbol tables of packages. |
385 | |
e7ea3e70 |
386 | =item C<quote>, C<HighBit>, C<undefPrint> |
387 | |
774d564b |
388 | Change style of string dump. Default value of C<quote> is C<auto>, one |
e7ea3e70 |
389 | can enable either double-quotish dump, or single-quotish by setting it |
774d564b |
390 | to C<"> or C<'>. By default, characters with high bit set are printed |
e7ea3e70 |
391 | I<as is>. |
392 | |
54310121 |
393 | =item C<UsageOnly> |
4e1d3b43 |
394 | |
774d564b |
395 | I<very> rudimentally per-package memory usage dump. Calculates total |
e7ea3e70 |
396 | size of strings in variables in the package. |
4e1d3b43 |
397 | |
36477c24 |
398 | =back |
4e1d3b43 |
399 | |
36477c24 |
400 | During startup options are initialized from C<$ENV{PERLDB_OPTS}>. |
401 | You can put additional initialization options C<TTY>, C<noTTY>, |
402 | C<ReadLine>, and C<NonStop> there. |
403 | |
404 | Example rc file: |
4e1d3b43 |
405 | |
e7ea3e70 |
406 | &parse_options("NonStop=1 LineInfo=db.out AutoTrace"); |
4e1d3b43 |
407 | |
36477c24 |
408 | The script will run without human intervention, putting trace information |
409 | into the file I<db.out>. (If you interrupt it, you would better reset |
410 | C<LineInfo> to something "interactive"!) |
4e1d3b43 |
411 | |
36477c24 |
412 | =over 12 |
4e1d3b43 |
413 | |
36477c24 |
414 | =item C<TTY> |
4e1d3b43 |
415 | |
36477c24 |
416 | The TTY to use for debugging I/O. |
417 | |
36477c24 |
418 | =item C<noTTY> |
419 | |
774d564b |
420 | If set, goes in C<NonStop> mode, and would not connect to a TTY. If |
36477c24 |
421 | interrupt (or if control goes to debugger via explicit setting of |
422 | $DB::signal or $DB::single from the Perl script), connects to a TTY |
423 | specified by the C<TTY> option at startup, or to a TTY found at |
424 | runtime using C<Term::Rendezvous> module of your choice. |
425 | |
426 | This module should implement a method C<new> which returns an object |
427 | with two methods: C<IN> and C<OUT>, returning two filehandles to use |
774d564b |
428 | for debugging input and output correspondingly. Method C<new> may |
36477c24 |
429 | inspect an argument which is a value of C<$ENV{PERLDB_NOTTY}> at |
430 | startup, or is C<"/tmp/perldbtty$$"> otherwise. |
431 | |
432 | =item C<ReadLine> |
433 | |
434 | If false, readline support in debugger is disabled, so you can debug |
435 | ReadLine applications. |
436 | |
437 | =item C<NonStop> |
438 | |
54310121 |
439 | If set, debugger goes into noninteractive mode until interrupted, or |
36477c24 |
440 | programmatically by setting $DB::signal or $DB::single. |
441 | |
442 | =back |
443 | |
444 | Here's an example of using the C<$ENV{PERLDB_OPTS}> variable: |
4e1d3b43 |
445 | |
e7ea3e70 |
446 | $ PERLDB_OPTS="N f=2" perl -d myprogram |
4e1d3b43 |
447 | |
448 | will run the script C<myprogram> without human intervention, printing |
449 | out the call tree with entry and exit points. Note that C<N f=2> is |
774d564b |
450 | equivalent to C<NonStop=1 frame=2>. Note also that at the moment when |
4e1d3b43 |
451 | this documentation was written all the options to the debugger could |
36477c24 |
452 | be uniquely abbreviated by the first letter (with exception of |
453 | C<Dump*> options). |
4e1d3b43 |
454 | |
36477c24 |
455 | Other examples may include |
a0d0e21e |
456 | |
e7ea3e70 |
457 | $ PERLDB_OPTS="N f A L=listing" perl -d myprogram |
a0d0e21e |
458 | |
54310121 |
459 | - runs script noninteractively, printing info on each entry into a |
36477c24 |
460 | subroutine and each executed line into the file F<listing>. (If you |
461 | interrupt it, you would better reset C<LineInfo> to something |
462 | "interactive"!) |
463 | |
464 | |
e7ea3e70 |
465 | $ env "PERLDB_OPTS=R=0 TTY=/dev/ttyc" perl -d myprogram |
36477c24 |
466 | |
467 | may be useful for debugging a program which uses C<Term::ReadLine> |
774d564b |
468 | itself. Do not forget detach shell from the TTY in the window which |
36477c24 |
469 | corresponds to F</dev/ttyc>, say, by issuing a command like |
470 | |
e7ea3e70 |
471 | $ sleep 1000000 |
36477c24 |
472 | |
473 | See L<"Debugger Internals"> below for more details. |
474 | |
475 | =item E<lt> [ command ] |
476 | |
477 | Set an action (Perl command) to happen before every debugger prompt. |
4a6725af |
478 | A multi-line command may be entered by backslashing the newlines. If |
36477c24 |
479 | C<command> is missing, resets the list of actions. |
480 | |
481 | =item E<lt>E<lt> command |
482 | |
483 | Add an action (Perl command) to happen before every debugger prompt. |
4a6725af |
484 | A multi-line command may be entered by backslashing the newlines. |
a0d0e21e |
485 | |
184e9718 |
486 | =item E<gt> command |
a0d0e21e |
487 | |
36477c24 |
488 | Set an action (Perl command) to happen after the prompt when you've |
4a6725af |
489 | just given a command to return to executing the script. A multi-line |
36477c24 |
490 | command may be entered by backslashing the newlines. If C<command> is |
491 | missing, resets the list of actions. |
492 | |
493 | =item E<gt>E<gt> command |
494 | |
495 | Adds an action (Perl command) to happen after the prompt when you've |
4a6725af |
496 | just given a command to return to executing the script. A multi-line |
36477c24 |
497 | command may be entered by backslashing the newlines. |
498 | |
499 | =item { [ command ] |
500 | |
501 | Set an action (debugger command) to happen before every debugger prompt. |
4a6725af |
502 | A multi-line command may be entered by backslashing the newlines. If |
36477c24 |
503 | C<command> is missing, resets the list of actions. |
504 | |
505 | =item {{ command |
506 | |
507 | Add an action (debugger command) to happen before every debugger prompt. |
4a6725af |
508 | A multi-line command may be entered by backslashing the newlines. |
a0d0e21e |
509 | |
4e1d3b43 |
510 | =item ! number |
a0d0e21e |
511 | |
4e1d3b43 |
512 | Redo a previous command (default previous command). |
a0d0e21e |
513 | |
4e1d3b43 |
514 | =item ! -number |
a0d0e21e |
515 | |
4e1d3b43 |
516 | Redo number'th-to-last command. |
a0d0e21e |
517 | |
4e1d3b43 |
518 | =item ! pattern |
a0d0e21e |
519 | |
4e1d3b43 |
520 | Redo last command that started with pattern. |
521 | See C<O recallCommand>, too. |
a0d0e21e |
522 | |
4e1d3b43 |
523 | =item !! cmd |
a0d0e21e |
524 | |
4e1d3b43 |
525 | Run cmd in a subprocess (reads from DB::IN, writes to DB::OUT) |
526 | See C<O shellBang> too. |
a0d0e21e |
527 | |
528 | =item H -number |
529 | |
530 | Display last n commands. Only commands longer than one character are |
531 | listed. If number is omitted, lists them all. |
532 | |
533 | =item q or ^D |
534 | |
36477c24 |
535 | Quit. ("quit" doesn't work for this.) This is the only supported way |
536 | to exit the debugger, though typing C<exit> twice may do it too. |
537 | |
538 | Set an C<O>ption C<inhibit_exit> to 0 if you want to be able to I<step |
774d564b |
539 | off> the end the script. You may also need to set C<$finished> to 0 at |
36477c24 |
540 | some moment if you want to step through global destruction. |
a0d0e21e |
541 | |
4e1d3b43 |
542 | =item R |
543 | |
544 | Restart the debugger by B<exec>ing a new session. It tries to maintain |
545 | your history across this, but internal settings and command line options |
546 | may be lost. |
547 | |
5f05dabc |
548 | Currently the following setting are preserved: history, breakpoints, |
54310121 |
549 | actions, debugger C<O>ptions, and the following command line |
5f05dabc |
550 | options: B<-w>, B<-I>, and B<-e>. |
36477c24 |
551 | |
4e1d3b43 |
552 | =item |dbcmd |
553 | |
554 | Run debugger command, piping DB::OUT to current pager. |
555 | |
556 | =item ||dbcmd |
557 | |
558 | Same as C<|dbcmd> but DB::OUT is temporarily B<select>ed as well. |
559 | Often used with commands that would otherwise produce long |
560 | output, such as |
561 | |
562 | |V main |
563 | |
564 | =item = [alias value] |
565 | |
e7ea3e70 |
566 | Define a command alias, like |
567 | |
568 | = quit q |
569 | |
570 | or list current aliases. |
4e1d3b43 |
571 | |
a0d0e21e |
572 | =item command |
573 | |
574 | Execute command as a Perl statement. A missing semicolon will be |
575 | supplied. |
576 | |
e7ea3e70 |
577 | =item m expr |
a0d0e21e |
578 | |
e7ea3e70 |
579 | The expression is evaluated, and the methods which may be applied to |
580 | the result are listed. |
581 | |
582 | =item m package |
583 | |
584 | The methods which may be applied to objects in the C<package> are listed. |
a0d0e21e |
585 | |
586 | =back |
587 | |
e7ea3e70 |
588 | =head2 Debugger input/output |
589 | |
590 | =over 8 |
591 | |
592 | =item Prompt |
593 | |
4e1d3b43 |
594 | The debugger prompt is something like |
595 | |
596 | DB<8> |
597 | |
598 | or even |
599 | |
600 | DB<<17>> |
601 | |
602 | where that number is the command number, which you'd use to access with |
54310121 |
603 | the builtin B<csh>-like history mechanism, e.g., C<!17> would repeat |
4e1d3b43 |
604 | command number 17. The number of angle brackets indicates the depth of |
605 | the debugger. You could get more than one set of brackets, for example, if |
606 | you'd already at a breakpoint and then printed out the result of a |
36477c24 |
607 | function call that itself also has a breakpoint, or you step into an |
608 | expression via C<s/n/t expression> command. |
4e1d3b43 |
609 | |
54310121 |
610 | =item Multiline commands |
e7ea3e70 |
611 | |
4a6725af |
612 | If you want to enter a multi-line command, such as a subroutine |
e7ea3e70 |
613 | definition with several statements, or a format, you may escape the |
614 | newline that would normally end the debugger command with a backslash. |
615 | Here's an example: |
a0d0e21e |
616 | |
4e1d3b43 |
617 | DB<1> for (1..4) { \ |
618 | cont: print "ok\n"; \ |
619 | cont: } |
620 | ok |
621 | ok |
622 | ok |
623 | ok |
624 | |
625 | Note that this business of escaping a newline is specific to interactive |
626 | commands typed into the debugger. |
627 | |
e7ea3e70 |
628 | =item Stack backtrace |
629 | |
68dc0745 |
630 | Here's an example of what a stack backtrace via C<T> command might |
e7ea3e70 |
631 | look like: |
4e1d3b43 |
632 | |
633 | $ = main::infested called from file `Ambulation.pm' line 10 |
634 | @ = Ambulation::legs(1, 2, 3, 4) called from file `camel_flea' line 7 |
635 | $ = main::pests('bactrian', 4) called from file `camel_flea' line 4 |
636 | |
637 | The left-hand character up there tells whether the function was called |
638 | in a scalar or list context (we bet you can tell which is which). What |
639 | that says is that you were in the function C<main::infested> when you ran |
640 | the stack dump, and that it was called in a scalar context from line 10 |
641 | of the file I<Ambulation.pm>, but without any arguments at all, meaning |
642 | it was called as C<&infested>. The next stack frame shows that the |
643 | function C<Ambulation::legs> was called in a list context from the |
644 | I<camel_flea> file with four arguments. The last stack frame shows that |
645 | C<main::pests> was called in a scalar context, also from I<camel_flea>, |
646 | but from line 4. |
647 | |
e7ea3e70 |
648 | Note that if you execute C<T> command from inside an active C<use> |
649 | statement, the backtrace will contain both C<L<perlfunc/require>> |
650 | frame and an C<L<perlfunc/eval EXPR>>) frame. |
651 | |
652 | =item Listing |
653 | |
654 | Listing given via different flavors of C<l> command looks like this: |
655 | |
656 | DB<<13>> l |
657 | 101: @i{@i} = (); |
658 | 102:b @isa{@i,$pack} = () |
659 | 103 if(exists $i{$prevpack} || exists $isa{$pack}); |
660 | 104 } |
661 | 105 |
662 | 106 next |
663 | 107==> if(exists $isa{$pack}); |
664 | 108 |
665 | 109:a if ($extra-- > 0) { |
666 | 110: %isa = ($pack,1); |
667 | |
668 | Note that the breakable lines are marked with C<:>, lines with |
669 | breakpoints are marked by C<b>, with actions by C<a>, and the |
670 | next executed line is marked by C<==E<gt>>. |
671 | |
672 | =item Frame listing |
673 | |
674 | When C<frame> option is set, debugger would print entered (and |
675 | optionally exited) subroutines in different styles. |
676 | |
54310121 |
677 | What follows is the start of the listing of |
e7ea3e70 |
678 | |
28d1fb14 |
679 | env "PERLDB_OPTS=f=n N" perl -d -V |
680 | |
681 | for different values of C<n>: |
e7ea3e70 |
682 | |
683 | =over 4 |
684 | |
685 | =item 1 |
686 | |
687 | entering main::BEGIN |
688 | entering Config::BEGIN |
689 | Package lib/Exporter.pm. |
690 | Package lib/Carp.pm. |
691 | Package lib/Config.pm. |
692 | entering Config::TIEHASH |
693 | entering Exporter::import |
694 | entering Exporter::export |
695 | entering Config::myconfig |
696 | entering Config::FETCH |
697 | entering Config::FETCH |
698 | entering Config::FETCH |
699 | entering Config::FETCH |
700 | |
701 | =item 2 |
702 | |
703 | entering main::BEGIN |
704 | entering Config::BEGIN |
705 | Package lib/Exporter.pm. |
706 | Package lib/Carp.pm. |
707 | exited Config::BEGIN |
708 | Package lib/Config.pm. |
709 | entering Config::TIEHASH |
710 | exited Config::TIEHASH |
711 | entering Exporter::import |
712 | entering Exporter::export |
713 | exited Exporter::export |
714 | exited Exporter::import |
715 | exited main::BEGIN |
716 | entering Config::myconfig |
717 | entering Config::FETCH |
718 | exited Config::FETCH |
719 | entering Config::FETCH |
720 | exited Config::FETCH |
721 | entering Config::FETCH |
722 | |
723 | =item 4 |
724 | |
725 | in $=main::BEGIN() from /dev/nul:0 |
726 | in $=Config::BEGIN() from lib/Config.pm:2 |
727 | Package lib/Exporter.pm. |
728 | Package lib/Carp.pm. |
729 | Package lib/Config.pm. |
730 | in $=Config::TIEHASH('Config') from lib/Config.pm:644 |
731 | in $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/nul:0 |
732 | in $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from li |
733 | in @=Config::myconfig() from /dev/nul:0 |
734 | in $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574 |
735 | in $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574 |
736 | in $=Config::FETCH(ref(Config), 'PATCHLEVEL') from lib/Config.pm:574 |
737 | in $=Config::FETCH(ref(Config), 'SUBVERSION') from lib/Config.pm:574 |
738 | in $=Config::FETCH(ref(Config), 'osname') from lib/Config.pm:574 |
739 | in $=Config::FETCH(ref(Config), 'osvers') from lib/Config.pm:574 |
740 | |
741 | =item 6 |
742 | |
743 | in $=main::BEGIN() from /dev/nul:0 |
744 | in $=Config::BEGIN() from lib/Config.pm:2 |
745 | Package lib/Exporter.pm. |
746 | Package lib/Carp.pm. |
747 | out $=Config::BEGIN() from lib/Config.pm:0 |
748 | Package lib/Config.pm. |
749 | in $=Config::TIEHASH('Config') from lib/Config.pm:644 |
750 | out $=Config::TIEHASH('Config') from lib/Config.pm:644 |
751 | in $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/nul:0 |
752 | in $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/ |
753 | out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/ |
754 | out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/nul:0 |
755 | out $=main::BEGIN() from /dev/nul:0 |
756 | in @=Config::myconfig() from /dev/nul:0 |
757 | in $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574 |
758 | out $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574 |
759 | in $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574 |
760 | out $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574 |
761 | in $=Config::FETCH(ref(Config), 'PATCHLEVEL') from lib/Config.pm:574 |
762 | out $=Config::FETCH(ref(Config), 'PATCHLEVEL') from lib/Config.pm:574 |
763 | in $=Config::FETCH(ref(Config), 'SUBVERSION') from lib/Config.pm:574 |
764 | |
765 | =item 14 |
766 | |
767 | in $=main::BEGIN() from /dev/nul:0 |
768 | in $=Config::BEGIN() from lib/Config.pm:2 |
769 | Package lib/Exporter.pm. |
770 | Package lib/Carp.pm. |
771 | out $=Config::BEGIN() from lib/Config.pm:0 |
772 | Package lib/Config.pm. |
773 | in $=Config::TIEHASH('Config') from lib/Config.pm:644 |
774 | out $=Config::TIEHASH('Config') from lib/Config.pm:644 |
775 | in $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/nul:0 |
776 | in $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/E |
777 | out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/E |
778 | out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/nul:0 |
779 | out $=main::BEGIN() from /dev/nul:0 |
780 | in @=Config::myconfig() from /dev/nul:0 |
781 | in $=Config::FETCH('Config=HASH(0x1aa444)', 'package') from lib/Config.pm:574 |
782 | out $=Config::FETCH('Config=HASH(0x1aa444)', 'package') from lib/Config.pm:574 |
783 | in $=Config::FETCH('Config=HASH(0x1aa444)', 'baserev') from lib/Config.pm:574 |
784 | out $=Config::FETCH('Config=HASH(0x1aa444)', 'baserev') from lib/Config.pm:574 |
785 | |
28d1fb14 |
786 | =item 30 |
787 | |
788 | in $=CODE(0x15eca4)() from /dev/null:0 |
789 | in $=CODE(0x182528)() from lib/Config.pm:2 |
790 | Package lib/Exporter.pm. |
791 | out $=CODE(0x182528)() from lib/Config.pm:0 |
792 | scalar context return from CODE(0x182528): undef |
793 | Package lib/Config.pm. |
794 | in $=Config::TIEHASH('Config') from lib/Config.pm:628 |
795 | out $=Config::TIEHASH('Config') from lib/Config.pm:628 |
796 | scalar context return from Config::TIEHASH: empty hash |
797 | in $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0 |
798 | in $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/Exporter.pm:171 |
799 | out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/Exporter.pm:171 |
800 | scalar context return from Exporter::export: '' |
801 | out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0 |
802 | scalar context return from Exporter::import: '' |
803 | |
804 | |
e7ea3e70 |
805 | =back |
806 | |
807 | In all the cases indentation of lines shows the call tree, if bit 2 of |
808 | C<frame> is set, then a line is printed on exit from a subroutine as |
809 | well, if bit 4 is set, then the arguments are printed as well as the |
810 | caller info, if bit 8 is set, the arguments are printed even if they |
28d1fb14 |
811 | are tied or references, if bit 16 is set, the return value is printed |
812 | as well. |
e7ea3e70 |
813 | |
814 | When a package is compiled, a line like this |
815 | |
816 | Package lib/Carp.pm. |
817 | |
818 | is printed with proper indentation. |
819 | |
820 | =back |
821 | |
822 | =head2 Debugging compile-time statements |
823 | |
4e1d3b43 |
824 | If you have any compile-time executable statements (code within a BEGIN |
825 | block or a C<use> statement), these will C<NOT> be stopped by debugger, |
36477c24 |
826 | although C<require>s will (and compile-time statements can be traced |
54310121 |
827 | with C<AutoTrace> option set in C<PERLDB_OPTS>). From your own Perl |
36477c24 |
828 | code, however, you can |
4e1d3b43 |
829 | transfer control back to the debugger using the following statement, |
830 | which is harmless if the debugger is not running: |
a0d0e21e |
831 | |
832 | $DB::single = 1; |
833 | |
4e1d3b43 |
834 | If you set C<$DB::single> to the value 2, it's equivalent to having |
835 | just typed the C<n> command, whereas a value of 1 means the C<s> |
836 | command. The C<$DB::trace> variable should be set to 1 to simulate |
837 | having typed the C<t> command. |
838 | |
e7ea3e70 |
839 | Another way to debug compile-time code is to start debugger, set a |
840 | breakpoint on I<load> of some module thusly |
841 | |
842 | DB<7> b load f:/perllib/lib/Carp.pm |
843 | Will stop on load of `f:/perllib/lib/Carp.pm'. |
844 | |
774d564b |
845 | and restart debugger by C<R> command (if possible). One can use C<b |
e7ea3e70 |
846 | compile subname> for the same purpose. |
847 | |
4e1d3b43 |
848 | =head2 Debugger Customization |
a0d0e21e |
849 | |
36477c24 |
850 | Most probably you not want to modify the debugger, it contains enough |
774d564b |
851 | hooks to satisfy most needs. You may change the behaviour of debugger |
36477c24 |
852 | from the debugger itself, using C<O>ptions, from the command line via |
853 | C<PERLDB_OPTS> environment variable, and from I<customization files>. |
a0d0e21e |
854 | |
855 | You can do some customization by setting up a F<.perldb> file which |
856 | contains initialization code. For instance, you could make aliases |
4e1d3b43 |
857 | like these (the last one is one people expect to be there): |
a0d0e21e |
858 | |
4e1d3b43 |
859 | $DB::alias{'len'} = 's/^len(.*)/p length($1)/'; |
a0d0e21e |
860 | $DB::alias{'stop'} = 's/^stop (at|in)/b/'; |
4e1d3b43 |
861 | $DB::alias{'ps'} = 's/^ps\b/p scalar /'; |
862 | $DB::alias{'quit'} = 's/^quit(\s*)/exit\$/'; |
863 | |
36477c24 |
864 | One changes options from F<.perldb> file via calls like this one; |
865 | |
866 | parse_options("NonStop=1 LineInfo=db.out AutoTrace=1 frame=2"); |
867 | |
774d564b |
868 | (the code is executed in the package C<DB>). Note that F<.perldb> is |
869 | processed before processing C<PERLDB_OPTS>. If F<.perldb> defines the |
36477c24 |
870 | subroutine C<afterinit>, it is called after all the debugger |
774d564b |
871 | initialization ends. F<.perldb> may be contained in the current |
36477c24 |
872 | directory, or in the C<LOGDIR>/C<HOME> directory. |
873 | |
874 | If you want to modify the debugger, copy F<perl5db.pl> from the Perl |
875 | library to another name and modify it as necessary. You'll also want |
876 | to set your C<PERL5DB> environment variable to say something like this: |
877 | |
878 | BEGIN { require "myperl5db.pl" } |
879 | |
880 | As the last resort, one can use C<PERL5DB> to customize debugger by |
881 | directly setting internal variables or calling debugger functions. |
882 | |
4e1d3b43 |
883 | =head2 Readline Support |
884 | |
885 | As shipped, the only command line history supplied is a simplistic one |
886 | that checks for leading exclamation points. However, if you install |
887 | the Term::ReadKey and Term::ReadLine modules from CPAN, you will |
888 | have full editing capabilities much like GNU I<readline>(3) provides. |
889 | Look for these in the F<modules/by-module/Term> directory on CPAN. |
890 | |
54310121 |
891 | A rudimentary command line completion is also available. |
e7ea3e70 |
892 | Unfortunately, the names of lexical variables are not available for |
893 | completion. |
894 | |
4e1d3b43 |
895 | =head2 Editor Support for Debugging |
896 | |
897 | If you have GNU B<emacs> installed on your system, it can interact with |
898 | the Perl debugger to provide an integrated software development |
899 | environment reminiscent of its interactions with C debuggers. |
900 | |
901 | Perl is also delivered with a start file for making B<emacs> act like a |
902 | syntax-directed editor that understands (some of) Perl's syntax. Look in |
903 | the I<emacs> directory of the Perl source distribution. |
904 | |
905 | (Historically, a similar setup for interacting with B<vi> and the |
906 | X11 window system had also been available, but at the time of this |
907 | writing, no debugger support for B<vi> currently exists.) |
908 | |
909 | =head2 The Perl Profiler |
910 | |
911 | If you wish to supply an alternative debugger for Perl to run, just |
912 | invoke your script with a colon and a package argument given to the B<-d> |
913 | flag. One of the most popular alternative debuggers for Perl is |
914 | B<DProf>, the Perl profiler. As of this writing, B<DProf> is not |
915 | included with the standard Perl distribution, but it is expected to |
916 | be included soon, for certain values of "soon". |
917 | |
918 | Meanwhile, you can fetch the Devel::Dprof module from CPAN. Assuming |
919 | it's properly installed on your system, to profile your Perl program in |
920 | the file F<mycode.pl>, just type: |
921 | |
922 | perl -d:DProf mycode.pl |
923 | |
924 | When the script terminates the profiler will dump the profile information |
925 | to a file called F<tmon.out>. A tool like B<dprofpp> (also supplied with |
926 | the Devel::DProf package) can be used to interpret the information which is |
927 | in that profile. |
928 | |
36477c24 |
929 | =head2 Debugger support in perl |
4e1d3b43 |
930 | |
e7ea3e70 |
931 | When you call the B<caller> function (see L<perlfunc/caller>) from the |
932 | package DB, Perl sets the array @DB::args to contain the arguments the |
54310121 |
933 | corresponding stack frame was called with. |
4e1d3b43 |
934 | |
36477c24 |
935 | If perl is run with B<-d> option, the following additional features |
936 | are enabled: |
a0d0e21e |
937 | |
36477c24 |
938 | =over |
4e1d3b43 |
939 | |
36477c24 |
940 | =item * |
4e1d3b43 |
941 | |
36477c24 |
942 | Perl inserts the contents of C<$ENV{PERL5DB}> (or C<BEGIN {require |
943 | 'perl5db.pl'}> if not present) before the first line of the |
944 | application. |
4e1d3b43 |
945 | |
36477c24 |
946 | =item * |
4e1d3b43 |
947 | |
36477c24 |
948 | The array C<@{"_<$filename"}> is the line-by-line contents of |
774d564b |
949 | $filename for all the compiled files. Same for C<eval>ed strings which |
950 | contain subroutines, or which are currently executed. The C<$filename> |
36477c24 |
951 | for C<eval>ed strings looks like C<(eval 34)>. |
4e1d3b43 |
952 | |
36477c24 |
953 | =item * |
4e1d3b43 |
954 | |
36477c24 |
955 | The hash C<%{"_<$filename"}> contains breakpoints and action (it is |
956 | keyed by line number), and individual entries are settable (as opposed |
774d564b |
957 | to the whole hash). Only true/false is important to Perl, though the |
36477c24 |
958 | values used by F<perl5db.pl> have the form |
774d564b |
959 | C<"$break_condition\0$action">. Values are magical in numeric context: |
36477c24 |
960 | they are zeros if the line is not breakable. |
4e1d3b43 |
961 | |
36477c24 |
962 | Same for evaluated strings which contain subroutines, or which are |
774d564b |
963 | currently executed. The C<$filename> for C<eval>ed strings looks like |
36477c24 |
964 | C<(eval 34)>. |
4e1d3b43 |
965 | |
36477c24 |
966 | =item * |
4e1d3b43 |
967 | |
774d564b |
968 | The scalar C<${"_<$filename"}> contains C<"_<$filename">. Same for |
36477c24 |
969 | evaluated strings which contain subroutines, or which are currently |
774d564b |
970 | executed. The C<$filename> for C<eval>ed strings looks like C<(eval |
36477c24 |
971 | 34)>. |
4e1d3b43 |
972 | |
36477c24 |
973 | =item * |
4e1d3b43 |
974 | |
36477c24 |
975 | After each C<require>d file is compiled, but before it is executed, |
976 | C<DB::postponed(*{"_<$filename"})> is called (if subroutine |
774d564b |
977 | C<DB::postponed> exists). Here the $filename is the expanded name of |
36477c24 |
978 | the C<require>d file (as found in values of C<%INC>). |
4e1d3b43 |
979 | |
36477c24 |
980 | =item * |
4e1d3b43 |
981 | |
36477c24 |
982 | After each subroutine C<subname> is compiled existence of |
774d564b |
983 | C<$DB::postponed{subname}> is checked. If this key exists, |
36477c24 |
984 | C<DB::postponed(subname)> is called (if subroutine C<DB::postponed> |
985 | exists). |
4e1d3b43 |
986 | |
36477c24 |
987 | =item * |
4e1d3b43 |
988 | |
36477c24 |
989 | A hash C<%DB::sub> is maintained, with keys being subroutine names, |
774d564b |
990 | values having the form C<filename:startline-endline>. C<filename> has |
36477c24 |
991 | the form C<(eval 31)> for subroutines defined inside C<eval>s. |
4e1d3b43 |
992 | |
36477c24 |
993 | =item * |
994 | |
5f05dabc |
995 | When execution of the application reaches a place that can have |
996 | a breakpoint, a call to C<DB::DB()> is performed if any one of |
997 | variables $DB::trace, $DB::single, or $DB::signal is true. (Note that |
36477c24 |
998 | these variables are not C<local>izable.) This feature is disabled when |
999 | the control is inside C<DB::DB()> or functions called from it (unless |
e7ea3e70 |
1000 | C<$^D & (1E<lt>E<lt>30)>). |
36477c24 |
1001 | |
1002 | =item * |
1003 | |
5f05dabc |
1004 | When execution of the application reaches a subroutine call, a call |
36477c24 |
1005 | to C<&DB::sub>(I<args>) is performed instead, with C<$DB::sub> being |
1006 | the name of the called subroutine. (Unless the subroutine is compiled |
1007 | in the package C<DB>.) |
4e1d3b43 |
1008 | |
1009 | =back |
a0d0e21e |
1010 | |
36477c24 |
1011 | Note that no subroutine call is possible until C<&DB::sub> is defined |
e7ea3e70 |
1012 | (for subroutines outside of package C<DB>). (This restriction is |
1013 | recently lifted.) |
1014 | |
1015 | (In fact, for the standard debugger the same is true if C<$DB::deep> |
1016 | (how many levels of recursion deep into the debugger you can go before |
1017 | a mandatory break) is not defined.) |
1018 | |
1019 | With the recent updates the minimal possible debugger consists of one |
1020 | line |
1021 | |
1022 | sub DB::DB {} |
1023 | |
1024 | which is quite handy as contents of C<PERL5DB> environment |
1025 | variable: |
1026 | |
1027 | env "PERL5DB=sub DB::DB {}" perl -d your-script |
1028 | |
1029 | Another (a little bit more useful) minimal debugger can be created |
1030 | with the only line being |
1031 | |
1032 | sub DB::DB {print ++$i; scalar <STDIN>} |
1033 | |
1034 | This debugger would print the sequential number of encountered |
1035 | statement, and would wait for your C<CR> to continue. |
1036 | |
1037 | The following debugger is quite functional: |
1038 | |
54310121 |
1039 | { |
1040 | package DB; |
1041 | sub DB {} |
e7ea3e70 |
1042 | sub sub {print ++$i, " $sub\n"; &$sub} |
1043 | } |
1044 | |
1045 | It prints the sequential number of subroutine call and the name of the |
774d564b |
1046 | called subroutine. Note that C<&DB::sub> should be compiled into the |
e7ea3e70 |
1047 | package C<DB>. |
36477c24 |
1048 | |
1049 | =head2 Debugger Internals |
1050 | |
1051 | At the start, the debugger reads your rc file (F<./.perldb> or |
54310121 |
1052 | F<~/.perldb> under Unix), which can set important options. This file may |
36477c24 |
1053 | define a subroutine C<&afterinit> to be executed after the debugger is |
1054 | initialized. |
1055 | |
5f05dabc |
1056 | After the rc file is read, the debugger reads environment variable |
36477c24 |
1057 | PERLDB_OPTS and parses it as a rest of C<O ...> line in debugger prompt. |
1058 | |
1059 | It also maintains magical internal variables, such as C<@DB::dbline>, |
1060 | C<%DB::dbline>, which are aliases for C<@{"::_<current_file"}> |
774d564b |
1061 | C<%{"::_<current_file"}>. Here C<current_file> is the currently |
36477c24 |
1062 | selected (with the debugger's C<f> command, or by flow of execution) |
1063 | file. |
1064 | |
774d564b |
1065 | Some functions are provided to simplify customization. See L<"Debugger |
1066 | Customization"> for description of C<DB::parse_options(string)>. The |
36477c24 |
1067 | function C<DB::dump_trace(skip[, count])> skips the specified number |
1068 | of frames, and returns an array containing info about the caller |
774d564b |
1069 | frames (all if C<count> is missing). Each entry is a hash with keys |
36477c24 |
1070 | C<context> (C<$> or C<@>), C<sub> (subroutine name, or info about |
5f05dabc |
1071 | eval), C<args> (C<undef> or a reference to an array), C<file>, and |
36477c24 |
1072 | C<line>. |
1073 | |
54310121 |
1074 | The function C<DB::print_trace(FH, skip[, count[, short]])> prints |
774d564b |
1075 | formatted info about caller frames. The last two functions may be |
36477c24 |
1076 | convenient as arguments to C<E<lt>>, C<E<lt>E<lt>> commands. |
1077 | |
a0d0e21e |
1078 | =head2 Other resources |
1079 | |
1080 | You did try the B<-w> switch, didn't you? |
1081 | |
1082 | =head1 BUGS |
1083 | |
4e1d3b43 |
1084 | You cannot get the stack frame information or otherwise debug functions |
1085 | that were not compiled by Perl, such as C or C++ extensions. |
a0d0e21e |
1086 | |
4e1d3b43 |
1087 | If you alter your @_ arguments in a subroutine (such as with B<shift> |
68dc0745 |
1088 | or B<pop>, the stack backtrace will not show the original values. |