4 perldebug - Perl debugging
8 First of all, have you tried using L<C<use strict;>|strict> and
9 L<C<use warnings;>|warnings>?
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.
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>.
17 For in-depth technical usage details, see L<perl5db.pl>, the documentation
18 of the debugger itself.
20 =head1 The Perl Debugger
22 If you invoke Perl with the B<-d> switch, your script runs under the
23 Perl source debugger. This works like an interactive Perl
24 environment, prompting for debugger commands that let you examine
25 source code, set breakpoints, get stack backtraces, change the values of
26 variables, etc. This is so convenient that you often fire up
27 the debugger all by itself just to test out Perl constructs
28 interactively to see what they do. For example:
33 In Perl, the debugger is not a separate program the way it usually is in the
34 typical compiled environment. Instead, the B<-d> flag tells the compiler
35 to insert source information into the parse trees it's about to hand off
36 to the interpreter. That means your code must first compile correctly
37 for the debugger to work on it. Then when the interpreter starts up, it
38 preloads a special Perl library file containing the debugger.
40 The program will halt I<right before> the first run-time executable
41 statement (but see below regarding compile-time statements) and ask you
42 to enter a debugger command. Contrary to popular expectations, whenever
43 the debugger halts and shows you a line of code, it always displays the
44 line it's I<about> to execute, rather than the one it has just executed.
46 Any command not recognized by the debugger is directly executed
47 (C<eval>'d) as Perl code in the current package. (The debugger
48 uses the DB package for keeping its own state information.)
50 Note that the said C<eval> is bound by an implicit scope. As a
51 result any newly introduced lexical variable or any modified
52 capture buffer content is lost after the eval. The debugger is a
53 nice environment to learn Perl, but if you interactively experiment using
54 material which should be in the same scope, stuff it in one line.
56 For any text entered at the debugger prompt, leading and trailing whitespace
57 is first stripped before further processing. If a debugger command
58 coincides with some function in your own program, merely precede the
59 function with something that doesn't look like a debugger command, such
60 as a leading C<;> or perhaps a C<+>, or by wrapping it with parentheses
63 =head2 Calling the Debugger
65 There are several ways to call the debugger:
69 =item perl -d program_name
71 On the given program identified by C<program_name>.
75 Interactively supply an arbitrary C<expression> using C<-e>.
77 =item perl -d:ptkdb program_name
79 Debug a given program via the C<Devel::ptkdb> GUI.
81 =item perl -dt threaded_program_name
83 Debug a given program using threads (experimental).
87 =head2 Debugger Commands
89 The interactive debugger understands the following commands:
94 X<debugger command, h>
96 Prints out a summary help message
100 Prints out a help message for the given debugger command.
104 The special argument of C<h h> produces the entire help page, which is quite long.
106 If the output of the C<h h> command (or any command, for that matter) scrolls
107 past your screen, precede the command with a leading pipe symbol so
108 that it's run through your pager, as in
112 You may change the pager which is used via C<o pager=...> command.
115 X<debugger command, p>
117 Same as C<print {$DB::OUT} expr> in the current package. In particular,
118 because this is just Perl's own C<print> function, this means that nested
119 data structures and objects are not dumped, unlike with the C<x> command.
121 The C<DB::OUT> filehandle is opened to F</dev/tty>, regardless of
122 where STDOUT may be redirected to.
124 =item x [maxdepth] expr
125 X<debugger command, x>
127 Evaluates its expression in list context and dumps out the result in a
128 pretty-printed fashion. Nested data structures are printed out
129 recursively, unlike the real C<print> function in Perl. When dumping
130 hashes, you'll probably prefer 'x \%h' rather than 'x %h'.
131 See L<Dumpvalue> if you'd like to do this yourself.
133 The output format is governed by multiple options described under
134 L</"Configurable Options">.
136 If the C<maxdepth> is included, it must be a numeral I<N>; the value is
137 dumped only I<N> levels deep, as if the C<dumpDepth> option had been
138 temporarily set to I<N>.
141 X<debugger command, V>
143 Display all (or some) variables in package (defaulting to C<main>)
144 using a data pretty-printer (hashes show their keys and values so
145 you see what's what, control characters are made printable, etc.).
146 Make sure you don't put the type specifier (like C<$>) there, just
147 the symbol names, like this:
151 Use C<~pattern> and C<!pattern> for positive and negative regexes.
153 This is similar to calling the C<x> command on each applicable var.
156 X<debugger command, X>
158 Same as C<V currentpackage [vars]>.
160 =item y [level [vars]]
161 X<debugger command, y>
163 Display all (or some) lexical variables (mnemonic: C<mY> variables)
164 in the current scope or I<level> scopes higher. You can limit the
165 variables that you see with I<vars> which works exactly as it does
166 for the C<V> and C<X> commands. Requires the C<PadWalker> module
167 version 0.08 or higher; will warn if this isn't installed. Output
168 is pretty-printed in the same style as for C<V> and the format is
169 controlled by the same options.
172 X<debugger command, T> X<backtrace> X<stack, backtrace>
174 Produce a stack backtrace. See below for details on its output.
177 X<debugger command, s> X<step>
179 Single step. Executes until the beginning of another
180 statement, descending into subroutine calls. If an expression is
181 supplied that includes function calls, it too will be single-stepped.
184 X<debugger command, n>
186 Next. Executes over subroutine calls, until the beginning
187 of the next statement. If an expression is supplied that includes
188 function calls, those functions will be executed with stops before
192 X<debugger command, r>
194 Continue until the return from the current subroutine.
195 Dump the return value if the C<PrintRet> option is set (default).
199 Repeat last C<n> or C<s> command.
202 X<debugger command, c>
204 Continue, optionally inserting a one-time-only breakpoint
205 at the specified line or subroutine.
208 X<debugger command, l>
210 List next window of lines.
214 List C<incr+1> lines starting at C<min>.
218 List lines C<min> through C<max>. C<l -> is synonymous to C<->.
226 List first window of lines from subroutine. I<subname> may
227 be a variable that contains a code reference.
230 X<debugger command, ->
232 List previous window of lines.
235 X<debugger command, v>
237 View a few lines of code around the current line.
240 X<debugger command, .>
242 Return the internal debugger pointer to the line last
243 executed, and print out that line.
246 X<debugger command, f>
248 Switch to viewing a different file or C<eval> statement. If I<filename>
249 is not a full pathname found in the values of %INC, it is considered
252 C<eval>ed strings (when accessible) are considered to be filenames:
253 C<f (eval 7)> and C<f eval 7\b> access the body of the 7th C<eval>ed string
254 (in the order of execution). The bodies of the currently executed C<eval>
255 and of C<eval>ed strings that define subroutines are saved and thus
260 Search forwards for pattern (a Perl regex); final / is optional.
261 The search is case-insensitive by default.
265 Search backwards for pattern; final ? is optional.
266 The search is case-insensitive by default.
269 X<debugger command, L>
271 List (default all) actions, breakpoints and watch expressions
274 X<debugger command, S>
276 List subroutine names [not] matching the regex.
279 X<debugger command, t>
281 Toggle trace mode (see also the C<AutoTrace> option).
282 Optional argument is the maximum number of levels to trace below
283 the current one; anything deeper than that will be silent.
286 X<debugger command, t>
288 Trace through execution of C<expr>.
289 Optional first argument is the maximum number of levels to trace below
290 the current one; anything deeper than that will be silent.
291 See L<perldebguts/"Frame Listing Output Examples"> for examples.
295 X<debugger command, b>
297 Sets breakpoint on current line
299 =item b [line] [condition]
301 X<debugger command, b>
303 Set a breakpoint before the given line. If a condition
304 is specified, it's evaluated each time the statement is reached: a
305 breakpoint is taken only if the condition is true. Breakpoints may
306 only be set on lines that begin an executable statement. Conditions
310 b 237 ++$count237 < 11
313 If the line number is C<.>, sets a breakpoint on the current line:
317 =item b [file]:[line] [condition]
319 X<debugger command, b>
321 Set a breakpoint before the given line in a (possibly different) file. If a
322 condition is specified, it's evaluated each time the statement is reached: a
323 breakpoint is taken only if the condition is true. Breakpoints may only be set
324 on lines that begin an executable statement. Conditions don't use C<if>:
326 b lib/MyModule.pm:237 $x > 30
327 b /usr/lib/perl5/site_perl/CGI.pm:100 ++$count100 < 11
329 =item b subname [condition]
331 X<debugger command, b>
333 Set a breakpoint before the first line of the named subroutine. I<subname> may
334 be a variable containing a code reference (in this case I<condition>
337 =item b postpone subname [condition]
339 X<debugger command, b>
341 Set a breakpoint at first line of subroutine after it is compiled.
343 =item b load filename
345 X<debugger command, b>
347 Set a breakpoint before the first executed line of the I<filename>,
348 which should be a full pathname found amongst the %INC values.
350 =item b compile subname
352 X<debugger command, b>
354 Sets a breakpoint before the first statement executed after the specified
355 subroutine is compiled.
359 X<debugger command, B>
361 Delete a breakpoint from the specified I<line>.
365 X<debugger command, B>
367 Delete all installed breakpoints.
369 =item disable [file]:[line]
371 X<debugger command, disable>
374 Disable the breakpoint so it won't stop the execution of the program.
375 Breakpoints are enabled by default and can be re-enabled using the C<enable>
380 X<debugger command, disable>
383 Disable the breakpoint so it won't stop the execution of the program.
384 Breakpoints are enabled by default and can be re-enabled using the C<enable>
387 This is done for a breakpoint in the current file.
389 =item enable [file]:[line]
391 X<debugger command, disable>
394 Enable the breakpoint so it will stop the execution of the program.
398 X<debugger command, disable>
401 Enable the breakpoint so it will stop the execution of the program.
403 This is done for a breakpoint in the current file.
405 =item a [line] command
406 X<debugger command, a>
408 Set an action to be done before the line is executed. If I<line> is
409 omitted, set an action on the line about to be executed.
410 The sequence of steps taken by the debugger is
412 1. check for a breakpoint at this line
413 2. print the line if necessary (tracing)
414 3. do any actions associated with that line
415 4. prompt user if at a breakpoint or in single-step
418 For example, this will print out $foo every time line
421 a 53 print "DB FOUND $foo\n"
424 X<debugger command, A>
426 Delete an action from the specified line.
429 X<debugger command, A>
431 Delete all installed actions.
434 X<debugger command, w>
436 Add a global watch-expression. Whenever a watched global changes the
437 debugger will stop and display the old and new values.
440 X<debugger command, W>
442 Delete watch-expression
445 X<debugger command, W>
447 Delete all watch-expressions.
450 X<debugger command, o>
454 =item o booloption ...
455 X<debugger command, o>
457 Set each listed Boolean option to the value C<1>.
459 =item o anyoption? ...
460 X<debugger command, o>
462 Print out the value of one or more options.
464 =item o option=value ...
465 X<debugger command, o>
467 Set the value of one or more options. If the value has internal
468 whitespace, it should be quoted. For example, you could set C<o
469 pager="less -MQeicsNfr"> to call B<less> with those specific options.
470 You may use either single or double quotes, but if you do, you must
471 escape any embedded instances of same sort of quote you began with,
472 as well as any escaping any escapes that immediately precede that
473 quote but which are not meant to escape the quote itself. In other
474 words, you follow single-quoting rules irrespective of the quote;
475 eg: C<o option='this isn\'t bad'> or C<o option="She said, \"Isn't
478 For historical reasons, the C<=value> is optional, but defaults to
479 1 only where it is safe to do so--that is, mostly for Boolean
480 options. It is always better to assign a specific value using C<=>.
481 The C<option> can be abbreviated, but for clarity probably should
482 not be. Several options can be set together. See L</"Configurable Options">
486 X<< debugger command, < >>
488 List out all pre-prompt Perl command actions.
491 X<< debugger command, < >>
493 Set an action (Perl command) to happen before every debugger prompt.
494 A multi-line command may be entered by backslashing the newlines.
497 X<< debugger command, < >>
499 Delete all pre-prompt Perl command actions.
502 X<< debugger command, << >>
504 Add an action (Perl command) to happen before every debugger prompt.
505 A multi-line command may be entered by backwhacking the newlines.
508 X<< debugger command, > >>
510 List out post-prompt Perl command actions.
513 X<< debugger command, > >>
515 Set an action (Perl command) to happen after the prompt when you've
516 just given a command to return to executing the script. A multi-line
517 command may be entered by backslashing the newlines (we bet you
518 couldn't have guessed this by now).
521 X<< debugger command, > >>
523 Delete all post-prompt Perl command actions.
526 X<<< debugger command, >> >>>
528 Adds an action (Perl command) to happen after the prompt when you've
529 just given a command to return to executing the script. A multi-line
530 command may be entered by backslashing the newlines.
533 X<debugger command, {>
535 List out pre-prompt debugger commands.
539 Set an action (debugger command) to happen before every debugger prompt.
540 A multi-line command may be entered in the customary fashion.
542 Because this command is in some senses new, a warning is issued if
543 you appear to have accidentally entered a block instead. If that's
544 what you mean to do, write it as with C<;{ ... }> or even
548 X<debugger command, {>
550 Delete all pre-prompt debugger commands.
553 X<debugger command, {{>
555 Add an action (debugger command) to happen before every debugger prompt.
556 A multi-line command may be entered, if you can guess how: see above.
559 X<debugger command, !>
561 Redo a previous command (defaults to the previous command).
564 X<debugger command, !>
566 Redo number'th previous command.
569 X<debugger command, !>
571 Redo last command that started with pattern.
572 See C<o recallCommand>, too.
575 X<debugger command, !!>
577 Run cmd in a subprocess (reads from DB::IN, writes to DB::OUT) See
578 C<o shellBang>, also. Note that the user's current shell (well,
579 their C<$ENV{SHELL}> variable) will be used, which can interfere
580 with proper interpretation of exit status or signal and coredump
584 X<debugger command, source>
586 Read and execute debugger commands from I<file>.
587 I<file> may itself contain C<source> commands.
590 X<debugger command, H>
592 Display last n commands. Only commands longer than one character are
593 listed. If I<number> is omitted, list them all.
596 X<debugger command, q>
597 X<debugger command, ^D>
599 Quit. ("quit" doesn't work for this, unless you've made an alias)
600 This is the only supported way to exit the debugger, though typing
601 C<exit> twice might work.
603 Set the C<inhibit_exit> option to 0 if you want to be able to step
604 off the end the script. You may also need to set $finished to 0
605 if you want to step through global destruction.
608 X<debugger command, R>
610 Restart the debugger by C<exec()>ing a new session. We try to maintain
611 your history across this, but internal settings and command-line options
614 The following setting are currently preserved: history, breakpoints,
615 actions, debugger options, and the Perl command-line
616 options B<-w>, B<-I>, and B<-e>.
619 X<debugger command, |>
621 Run the debugger command, piping DB::OUT into your current pager.
624 X<debugger command, ||>
626 Same as C<|dbcmd> but DB::OUT is temporarily C<select>ed as well.
628 =item = [alias value]
629 X<debugger command, =>
631 Define a command alias, like
635 or list current aliases.
639 Execute command as a Perl statement. A trailing semicolon will be
640 supplied. If the Perl statement would otherwise be confused for a
641 Perl debugger, use a leading semicolon, too.
644 X<debugger command, m>
646 List which methods may be called on the result of the evaluated
647 expression. The expression may evaluated to a reference to a
648 blessed object, or to a package name.
651 X<debugger command, M>
653 Display all loaded modules and their versions.
656 X<debugger command, man>
658 Despite its name, this calls your system's default documentation
659 viewer on the given page, or on the viewer itself if I<manpage> is
660 omitted. If that viewer is B<man>, the current C<Config> information
661 is used to invoke B<man> using the proper MANPATH or S<B<-M>
662 I<manpath>> option. Failed lookups of the form C<XXX> that match
663 known manpages of the form I<perlXXX> will be retried. This lets
664 you type C<man debug> or C<man op> from the debugger.
666 On systems traditionally bereft of a usable B<man> command, the
667 debugger invokes B<perldoc>. Occasionally this determination is
668 incorrect due to recalcitrant vendors or rather more felicitously,
669 to enterprising users. If you fall into either category, just
670 manually set the $DB::doccmd variable to whatever viewer to view
671 the Perl documentation on your system. This may be set in an rc
672 file, or through direct assignment. We're still waiting for a
673 working example of something along the lines of:
675 $DB::doccmd = 'netscape -remote http://something.here/';
679 =head2 Configurable Options
681 The debugger has numerous options settable using the C<o> command,
682 either interactively or from the environment or an rc file. The file
683 is named F<./.perldb> or F<~/.perldb> under Unix with F</dev/tty>,
684 F<perldb.ini> otherwise.
688 =item C<recallCommand>, C<ShellBang>
689 X<debugger option, recallCommand>
690 X<debugger option, ShellBang>
692 The characters used to recall a command or spawn a shell. By
693 default, both are set to C<!>, which is unfortunate.
696 X<debugger option, pager>
698 Program to use for output of pager-piped commands (those beginning
699 with a C<|> character.) By default, C<$ENV{PAGER}> will be used.
700 Because the debugger uses your current terminal characteristics
701 for bold and underlining, if the chosen pager does not pass escape
702 sequences through unchanged, the output of some debugger commands
703 will not be readable when sent through the pager.
706 X<debugger option, tkRunning>
708 Run Tk while prompting (with ReadLine).
710 =item C<signalLevel>, C<warnLevel>, C<dieLevel>
711 X<debugger option, signalLevel> X<debugger option, warnLevel>
712 X<debugger option, dieLevel>
714 Level of verbosity. By default, the debugger leaves your exceptions
715 and warnings alone, because altering them can break correctly running
716 programs. It will attempt to print a message when uncaught INT, BUS, or
717 SEGV signals arrive. (But see the mention of signals in L</BUGS> below.)
719 To disable this default safe mode, set these values to something higher
720 than 0. At a level of 1, you get backtraces upon receiving any kind
721 of warning (this is often annoying) or exception (this is
722 often valuable). Unfortunately, the debugger cannot discern fatal
723 exceptions from non-fatal ones. If C<dieLevel> is even 1, then your
724 non-fatal exceptions are also traced and unceremoniously altered if they
725 came from C<eval'ed> strings or from any kind of C<eval> within modules
726 you're attempting to load. If C<dieLevel> is 2, the debugger doesn't
727 care where they came from: It usurps your exception handler and prints
728 out a trace, then modifies all exceptions with its own embellishments.
729 This may perhaps be useful for some tracing purposes, but tends to hopelessly
730 destroy any program that takes its exception handling seriously.
733 X<debugger option, AutoTrace>
735 Trace mode (similar to C<t> command, but can be put into
739 X<debugger option, LineInfo>
741 File or pipe to print line number info to. If it is a pipe (say,
742 C<|visual_perl_db>), then a short message is used. This is the
743 mechanism used to interact with a slave editor or visual debugger,
744 such as the special C<vi> or C<emacs> hooks, or the C<ddd> graphical
747 =item C<inhibit_exit>
748 X<debugger option, inhibit_exit>
750 If 0, allows I<stepping off> the end of the script.
753 X<debugger option, PrintRet>
755 Print return value after C<r> command if set (default).
758 X<debugger option, ornaments>
760 Affects screen appearance of the command line (see L<Term::ReadLine>).
761 There is currently no way to disable these, which can render
762 some output illegible on some displays, or with some pagers.
763 This is considered a bug.
766 X<debugger option, frame>
768 Affects the printing of messages upon entry and exit from subroutines. If
769 C<frame & 2> is false, messages are printed on entry only. (Printing
770 on exit might be useful if interspersed with other messages.)
772 If C<frame & 4>, arguments to functions are printed, plus context
773 and caller info. If C<frame & 8>, overloaded C<stringify> and
774 C<tie>d C<FETCH> is enabled on the printed arguments. If C<frame
775 & 16>, the return value from the subroutine is printed.
777 The length at which the argument list is truncated is governed by the
781 X<debugger option, maxTraceLen>
783 Length to truncate the argument list when the C<frame> option's
787 X<debugger option, windowSize>
789 Change the size of code list window (default is 10 lines).
793 The following options affect what happens with C<V>, C<X>, and C<x>
798 =item C<arrayDepth>, C<hashDepth>
799 X<debugger option, arrayDepth> X<debugger option, hashDepth>
801 Print only first N elements ('' for all).
804 X<debugger option, dumpDepth>
806 Limit recursion depth to N levels when dumping structures.
807 Negative values are interpreted as infinity. Default: infinity.
809 =item C<compactDump>, C<veryCompact>
810 X<debugger option, compactDump> X<debugger option, veryCompact>
812 Change the style of array and hash output. If C<compactDump>, short array
813 may be printed on one line.
816 X<debugger option, globPrint>
818 Whether to print contents of globs.
821 X<debugger option, DumpDBFiles>
823 Dump arrays holding debugged files.
825 =item C<DumpPackages>
826 X<debugger option, DumpPackages>
828 Dump symbol tables of packages.
831 X<debugger option, DumpReused>
833 Dump contents of "reused" addresses.
835 =item C<quote>, C<HighBit>, C<undefPrint>
836 X<debugger option, quote> X<debugger option, HighBit>
837 X<debugger option, undefPrint>
839 Change the style of string dump. The default value for C<quote>
840 is C<auto>; one can enable double-quotish or single-quotish format
841 by setting it to C<"> or C<'>, respectively. By default, characters
842 with their high bit set are printed verbatim.
845 X<debugger option, UsageOnly>
847 Rudimentary per-package memory usage dump. Calculates total
848 size of strings found in variables in the package. This does not
849 include lexicals in a module's file scope, or lost in closures.
852 X<debugger option, history, HistFile>
854 The path of the file from which the history (assuming a usable
855 Term::ReadLine backend) will be read on the debugger's startup, and to which
856 it will be saved on shutdown (for persistence across sessions). Similar in
857 concept to Bash's C<.bash_history> file.
860 X<debugger option, history, HistSize>
862 The count of the saved lines in the history (assuming C<HistFile> above).
866 After the rc file is read, the debugger reads the C<$ENV{PERLDB_OPTS}>
867 environment variable and parses this as the remainder of a "O ..."
868 line as one might enter at the debugger prompt. You may place the
869 initialization options C<TTY>, C<noTTY>, C<ReadLine>, and C<NonStop>
872 If your rc file contains:
874 parse_options("NonStop=1 LineInfo=db.out AutoTrace");
876 then your script will run without human intervention, putting trace
877 information into the file I<db.out>. (If you interrupt it, you'd
878 better reset C<LineInfo> to F</dev/tty> if you expect to see anything.)
883 X<debugger option, TTY>
885 The TTY to use for debugging I/O.
888 X<debugger option, noTTY>
890 If set, the debugger goes into C<NonStop> mode and will not connect to a TTY. If
891 interrupted (or if control goes to the debugger via explicit setting of
892 $DB::signal or $DB::single from the Perl script), it connects to a TTY
893 specified in the C<TTY> option at startup, or to a tty found at
894 runtime using the C<Term::Rendezvous> module of your choice.
896 This module should implement a method named C<new> that returns an object
897 with two methods: C<IN> and C<OUT>. These should return filehandles to use
898 for debugging input and output correspondingly. The C<new> method should
899 inspect an argument containing the value of C<$ENV{PERLDB_NOTTY}> at
900 startup, or C<"$ENV{HOME}/.perldbtty$$"> otherwise. This file is not
901 inspected for proper ownership, so security hazards are theoretically
905 X<debugger option, ReadLine>
907 If false, readline support in the debugger is disabled in order
908 to debug applications that themselves use ReadLine.
911 X<debugger option, NonStop>
913 If set, the debugger goes into non-interactive mode until interrupted, or
914 programmatically by setting $DB::signal or $DB::single.
918 Here's an example of using the C<$ENV{PERLDB_OPTS}> variable:
920 $ PERLDB_OPTS="NonStop frame=2" perl -d myprogram
922 That will run the script B<myprogram> without human intervention,
923 printing out the call tree with entry and exit points. Note that
924 C<NonStop=1 frame=2> is equivalent to C<N f=2>, and that originally,
925 options could be uniquely abbreviated by the first letter (modulo
926 the C<Dump*> options). It is nevertheless recommended that you
927 always spell them out in full for legibility and future compatibility.
929 Other examples include
931 $ PERLDB_OPTS="NonStop LineInfo=listing frame=2" perl -d myprogram
933 which runs script non-interactively, printing info on each entry
934 into a subroutine and each executed line into the file named F<listing>.
935 (If you interrupt it, you would better reset C<LineInfo> to something
938 Other examples include (using standard shell syntax to show environment
941 $ ( PERLDB_OPTS="NonStop frame=1 AutoTrace LineInfo=tperl.out"
944 which may be useful for debugging a program that uses C<Term::ReadLine>
945 itself. Do not forget to detach your shell from the TTY in the window that
946 corresponds to F</dev/ttyXX>, say, by issuing a command like
950 See L<perldebguts/"Debugger Internals"> for details.
952 =head2 Debugger Input/Output
958 The debugger prompt is something like
966 where that number is the command number, and which you'd use to
967 access with the built-in B<csh>-like history mechanism. For example,
968 C<!17> would repeat command number 17. The depth of the angle
969 brackets indicates the nesting depth of the debugger. You could
970 get more than one set of brackets, for example, if you'd already
971 at a breakpoint and then printed the result of a function call that
972 itself has a breakpoint, or you step into an expression via C<s/n/t
975 =item Multiline commands
977 If you want to enter a multi-line command, such as a subroutine
978 definition with several statements or a format, escape the newline
979 that would normally end the debugger command with a backslash.
983 cont: print "ok\n"; \
990 Note that this business of escaping a newline is specific to interactive
991 commands typed into the debugger.
993 =item Stack backtrace
994 X<backtrace> X<stack, backtrace>
996 Here's an example of what a stack backtrace via C<T> command might
999 $ = main::infested called from file 'Ambulation.pm' line 10
1000 @ = Ambulation::legs(1, 2, 3, 4) called from file 'camel_flea'
1002 $ = main::pests('bactrian', 4) called from file 'camel_flea'
1005 The left-hand character up there indicates the context in which the
1006 function was called, with C<$> and C<@> meaning scalar or list
1007 contexts respectively, and C<.> meaning void context (which is
1008 actually a sort of scalar context). The display above says
1009 that you were in the function C<main::infested> when you ran the
1010 stack dump, and that it was called in scalar context from line
1011 10 of the file I<Ambulation.pm>, but without any arguments at all,
1012 meaning it was called as C<&infested>. The next stack frame shows
1013 that the function C<Ambulation::legs> was called in list context
1014 from the I<camel_flea> file with four arguments. The last stack
1015 frame shows that C<main::pests> was called in scalar context,
1016 also from I<camel_flea>, but from line 4.
1018 If you execute the C<T> command from inside an active C<use>
1019 statement, the backtrace will contain both a C<require> frame and
1022 =item Line Listing Format
1024 This shows the sorts of output the C<l> command can produce:
1028 102:b @isa{@i,$pack} = ()
1029 103 if(exists $i{$prevpack} || exists $isa{$pack});
1033 107==> if(exists $isa{$pack});
1035 109:a if ($extra-- > 0) {
1036 110: %isa = ($pack,1);
1038 Breakable lines are marked with C<:>. Lines with breakpoints are
1039 marked by C<b> and those with actions by C<a>. The line that's
1040 about to be executed is marked by C<< ==> >>.
1042 Please be aware that code in debugger listings may not look the same
1043 as your original source code. Line directives and external source
1044 filters can alter the code before Perl sees it, causing code to move
1045 from its original positions or take on entirely different forms.
1049 When the C<frame> option is set, the debugger would print entered (and
1050 optionally exited) subroutines in different styles. See L<perldebguts>
1051 for incredibly long examples of these.
1055 =head2 Debugging Compile-Time Statements
1057 If you have compile-time executable statements (such as code within
1058 BEGIN, UNITCHECK and CHECK blocks or C<use> statements), these will
1059 I<not> be stopped by debugger, although C<require>s and INIT blocks
1060 will, and compile-time statements can be traced with the C<AutoTrace>
1061 option set in C<PERLDB_OPTS>). From your own Perl code, however, you
1062 can transfer control back to the debugger using the following
1063 statement, which is harmless if the debugger is not running:
1067 If you set C<$DB::single> to 2, it's equivalent to having
1068 just typed the C<n> command, whereas a value of 1 means the C<s>
1069 command. The C<$DB::trace> variable should be set to 1 to simulate
1070 having typed the C<t> command.
1072 Another way to debug compile-time code is to start the debugger, set a
1073 breakpoint on the I<load> of some module:
1075 DB<7> b load f:/perllib/lib/Carp.pm
1076 Will stop on load of 'f:/perllib/lib/Carp.pm'.
1078 and then restart the debugger using the C<R> command (if possible). One can use C<b
1079 compile subname> for the same purpose.
1081 =head2 Debugger Customization
1083 The debugger probably contains enough configuration hooks that you
1084 won't ever have to modify it yourself. You may change the behaviour
1085 of the debugger from within the debugger using its C<o> command, from
1086 the command line via the C<PERLDB_OPTS> environment variable, and
1087 from customization files.
1089 You can do some customization by setting up a F<.perldb> file, which
1090 contains initialization code. For instance, you could make aliases
1091 like these (the last one is one people expect to be there):
1093 $DB::alias{'len'} = 's/^len(.*)/p length($1)/';
1094 $DB::alias{'stop'} = 's/^stop (at|in)/b/';
1095 $DB::alias{'ps'} = 's/^ps\b/p scalar /';
1096 $DB::alias{'quit'} = 's/^quit(\s*)/exit/';
1098 You can change options from F<.perldb> by using calls like this one;
1100 parse_options("NonStop=1 LineInfo=db.out AutoTrace=1 frame=2");
1102 The code is executed in the package C<DB>. Note that F<.perldb> is
1103 processed before processing C<PERLDB_OPTS>. If F<.perldb> defines the
1104 subroutine C<afterinit>, that function is called after debugger
1105 initialization ends. F<.perldb> may be contained in the current
1106 directory, or in the home directory. Because this file is sourced
1107 in by Perl and may contain arbitrary commands, for security reasons,
1108 it must be owned by the superuser or the current user, and writable
1109 by no one but its owner.
1111 You can mock TTY input to debugger by adding arbitrary commands to
1112 @DB::typeahead. For example, your F<.perldb> file might contain:
1114 sub afterinit { push @DB::typeahead, "b 4", "b 6"; }
1116 Which would attempt to set breakpoints on lines 4 and 6 immediately
1117 after debugger initialization. Note that @DB::typeahead is not a supported
1118 interface and is subject to change in future releases.
1120 If you want to modify the debugger, copy F<perl5db.pl> from the
1121 Perl library to another name and hack it to your heart's content.
1122 You'll then want to set your C<PERL5DB> environment variable to say
1123 something like this:
1125 BEGIN { require "myperl5db.pl" }
1127 As a last resort, you could also use C<PERL5DB> to customize the debugger
1128 by directly setting internal variables or calling debugger functions.
1130 Note that any variables and functions that are not documented in
1131 this document (or in L<perldebguts>) are considered for internal
1132 use only, and as such are subject to change without notice.
1134 =head2 Readline Support / History in the Debugger
1136 As shipped, the only command-line history supplied is a simplistic one
1137 that checks for leading exclamation points. However, if you install
1138 the Term::ReadKey and Term::ReadLine modules from CPAN (such as
1139 Term::ReadLine::Gnu, Term::ReadLine::Perl, ...) you will
1140 have full editing capabilities much like those GNU I<readline>(3) provides.
1141 Look for these in the F<modules/by-module/Term> directory on CPAN.
1142 These do not support normal B<vi> command-line editing, however.
1144 A rudimentary command-line completion is also available, including
1145 lexical variables in the current scope if the C<PadWalker> module
1148 Without Readline support you may see the symbols "^[[A", "^[[C", "^[[B",
1149 "^[[D"", "^H", ... when using the arrow keys and/or the backspace key.
1151 =head2 Editor Support for Debugging
1153 If you have the GNU's version of B<emacs> installed on your system,
1154 it can interact with the Perl debugger to provide an integrated
1155 software development environment reminiscent of its interactions
1158 Recent versions of Emacs come with a
1159 start file for making B<emacs> act like a
1160 syntax-directed editor that understands (some of) Perl's syntax.
1163 Users of B<vi> should also look into B<vim> and B<gvim>, the mousey
1164 and windy version, for coloring of Perl keywords.
1166 Note that only perl can truly parse Perl, so all such CASE tools
1167 fall somewhat short of the mark, especially if you don't program
1168 your Perl as a C programmer might.
1170 =head2 The Perl Profiler
1171 X<profile> X<profiling> X<profiler>
1173 If you wish to supply an alternative debugger for Perl to run,
1174 invoke your script with a colon and a package argument given to the
1175 B<-d> flag. Perl's alternative debuggers include a Perl profiler,
1176 L<Devel::NYTProf>, which is available separately as a CPAN
1177 distribution. To profile your Perl program in the file F<mycode.pl>,
1180 $ perl -d:NYTProf mycode.pl
1182 When the script terminates the profiler will create a database of the
1183 profile information that you can turn into reports using the profiler's
1184 tools. See <perlperf> for details.
1186 =head1 Debugging Regular Expressions
1187 X<regular expression, debugging>
1188 X<regex, debugging> X<regexp, debugging>
1190 C<use re 'debug'> enables you to see the gory details of how the Perl
1191 regular expression engine works. In order to understand this typically
1192 voluminous output, one must not only have some idea about how regular
1193 expression matching works in general, but also know how Perl's regular
1194 expressions are internally compiled into an automaton. These matters
1195 are explored in some detail in
1196 L<perldebguts/"Debugging Regular Expressions">.
1198 =head1 Debugging Memory Usage
1201 Perl contains internal support for reporting its own memory usage,
1202 but this is a fairly advanced concept that requires some understanding
1203 of how memory allocation works.
1204 See L<perldebguts/"Debugging Perl Memory Usage"> for the details.
1208 You do have C<use strict> and C<use warnings> enabled, don't you?
1220 When debugging a script that uses #! and is thus normally found in
1221 $PATH, the -S option causes perl to search $PATH for it, so you don't
1222 have to type the path or C<which $scriptname>.
1228 You cannot get stack frame information or in any fashion debug functions
1229 that were not compiled by Perl, such as those from C or C++ extensions.
1231 If you alter your @_ arguments in a subroutine (such as with C<shift>
1232 or C<pop>), the stack backtrace will not show the original values.
1234 The debugger does not currently work in conjunction with the B<-W>
1235 command-line switch, because it itself is not free of warnings.
1237 If you're in a slow syscall (like C<wait>ing, C<accept>ing, or C<read>ing
1238 from your keyboard or a socket) and haven't set up your own C<$SIG{INT}>
1239 handler, then you won't be able to CTRL-C your way back to the debugger,
1240 because the debugger's own C<$SIG{INT}> handler doesn't understand that
1241 it needs to raise an exception to longjmp(3) out of slow syscalls.