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