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