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