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