3 perldebug - Perl debugging
7 First of all, have you tried using the B<-w> switch?
10 If you're new to the Perl debugger, you may prefer to read
11 L<perldebtut>, which is a tutorial introduction to the debugger .
13 =head1 The Perl Debugger
15 If you invoke Perl with the B<-d> switch, your script runs under the
16 Perl source debugger. This works like an interactive Perl
17 environment, prompting for debugger commands that let you examine
18 source code, set breakpoints, get stack backtraces, change the values of
19 variables, etc. This is so convenient that you often fire up
20 the debugger all by itself just to test out Perl constructs
21 interactively to see what they do. For example:
25 In Perl, the debugger is not a separate program the way it usually is in the
26 typical compiled environment. Instead, the B<-d> flag tells the compiler
27 to insert source information into the parse trees it's about to hand off
28 to the interpreter. That means your code must first compile correctly
29 for the debugger to work on it. Then when the interpreter starts up, it
30 preloads a special Perl library file containing the debugger.
32 The program will halt I<right before> the first run-time executable
33 statement (but see below regarding compile-time statements) and ask you
34 to enter a debugger command. Contrary to popular expectations, whenever
35 the debugger halts and shows you a line of code, it always displays the
36 line it's I<about> to execute, rather than the one it has just executed.
38 Any command not recognized by the debugger is directly executed
39 (C<eval>'d) as Perl code in the current package. (The debugger
40 uses the DB package for keeping its own state information.)
42 For any text entered at the debugger prompt, leading and trailing whitespace
43 is first stripped before further processing. If a debugger command
44 coincides with some function in your own program, merely precede the
45 function with something that doesn't look like a debugger command, such
46 as a leading C<;> or perhaps a C<+>, or by wrapping it with parentheses
49 =head2 Debugger Commands
51 The debugger understands the following commands:
57 Prints out a help message.
59 If you supply another debugger command as an argument to the C<h> command,
60 it prints out the description for just that command. The special
61 argument of C<h h> produces a more compact help listing, designed to fit
62 together on one screen.
64 If the output of the C<h> command (or any command, for that matter) scrolls
65 past your screen, precede the command with a leading pipe symbol so
66 that it's run through your pager, as in
70 You may change the pager which is used via C<O pager=...> command.
74 Same as C<print {$DB::OUT} expr> in the current package. In particular,
75 because this is just Perl's own C<print> function, this means that nested
76 data structures and objects are not dumped, unlike with the C<x> command.
78 The C<DB::OUT> filehandle is opened to F</dev/tty>, regardless of
79 where STDOUT may be redirected to.
83 Evaluates its expression in list context and dumps out the result
84 in a pretty-printed fashion. Nested data structures are printed out
85 recursively, unlike the real C<print> function in Perl.
86 See L<Dumpvalue> if you'd like to do this yourself.
88 The output format is governed by multiple options described under
89 L<"Configurable Options">.
93 Display all (or some) variables in package (defaulting to C<main>)
94 using a data pretty-printer (hashes show their keys and values so
95 you see what's what, control characters are made printable, etc.).
96 Make sure you don't put the type specifier (like C<$>) there, just
97 the symbol names, like this:
101 Use C<~pattern> and C<!pattern> for positive and negative regexes.
103 This is similar to calling the C<x> command on each applicable var.
107 Same as C<V currentpackage [vars]>.
111 Produce a stack backtrace. See below for details on its output.
115 Single step. Executes until the beginning of another
116 statement, descending into subroutine calls. If an expression is
117 supplied that includes function calls, it too will be single-stepped.
121 Next. Executes over subroutine calls, until the beginning
122 of the next statement. If an expression is supplied that includes
123 function calls, those functions will be executed with stops before
128 Continue until the return from the current subroutine.
129 Dump the return value if the C<PrintRet> option is set (default).
133 Repeat last C<n> or C<s> command.
137 Continue, optionally inserting a one-time-only breakpoint
138 at the specified line or subroutine.
142 List next window of lines.
146 List C<incr+1> lines starting at C<min>.
150 List lines C<min> through C<max>. C<l -> is synonymous to C<->.
158 List first window of lines from subroutine. I<subname> may
159 be a variable that contains a code reference.
163 List previous window of lines.
167 List window (a few lines) around the current line.
171 Return the internal debugger pointer to the line last
172 executed, and print out that line.
176 Switch to viewing a different file or C<eval> statement. If I<filename>
177 is not a full pathname found in the values of %INC, it is considered
180 C<eval>ed strings (when accessible) are considered to be filenames:
181 C<f (eval 7)> and C<f eval 7\b> access the body of the 7th C<eval>ed string
182 (in the order of execution). The bodies of the currently executed C<eval>
183 and of C<eval>ed strings that define subroutines are saved and thus
188 Search forwards for pattern (a Perl regex); final / is optional.
189 The search is case-insensitive by default.
193 Search backwards for pattern; final ? is optional.
194 The search is case-insensitive by default.
198 List all breakpoints and actions.
202 List subroutine names [not] matching the regex.
206 Toggle trace mode (see also the C<AutoTrace> option).
210 Trace through execution of C<expr>.
211 See L<perldebguts/"Frame Listing Output Examples"> for examples.
213 =item b [line] [condition]
215 Set a breakpoint before the given line. If I<line> is omitted, set a
216 breakpoint on the line about to be executed. If a condition
217 is specified, it's evaluated each time the statement is reached: a
218 breakpoint is taken only if the condition is true. Breakpoints may
219 only be set on lines that begin an executable statement. Conditions
223 b 237 ++$count237 < 11
226 =item b subname [condition]
228 Set a breakpoint before the first line of the named subroutine. I<subname> may
229 be a variable containing a code reference (in this case I<condition>
232 =item b postpone subname [condition]
234 Set a breakpoint at first line of subroutine after it is compiled.
236 =item b load filename
238 Set a breakpoint before the first executed line of the I<filename>,
239 which should be a full pathname found amongst the %INC values.
241 =item b compile subname
243 Sets a breakpoint before the first statement executed after the specified
244 subroutine is compiled.
248 Delete a breakpoint from the specified I<line>. If I<line> is omitted, deletes
249 the breakpoint from the line about to be executed.
253 Delete all installed breakpoints.
255 =item a [line] command
257 Set an action to be done before the line is executed. If I<line> is
258 omitted, set an action on the line about to be executed.
259 The sequence of steps taken by the debugger is
261 1. check for a breakpoint at this line
262 2. print the line if necessary (tracing)
263 3. do any actions associated with that line
264 4. prompt user if at a breakpoint or in single-step
267 For example, this will print out $foo every time line
270 a 53 print "DB FOUND $foo\n"
274 Delete an action from the specified line. If I<line> is omitted, delete
275 the action on the line that is about to be executed.
279 Delete all installed actions.
283 Add a global watch-expression. We hope you know what one of these
284 is, because they're supposed to be obvious. B<WARNING>: It is far
285 too easy to destroy your watch expressions by accidentally omitting
290 Delete all watch-expressions.
292 =item O booloption ...
294 Set each listed Boolean option to the value C<1>.
296 =item O anyoption? ...
298 Print out the value of one or more options.
300 =item O option=value ...
302 Set the value of one or more options. If the value has internal
303 whitespace, it should be quoted. For example, you could set C<O
304 pager="less -MQeicsNfr"> to call B<less> with those specific options.
305 You may use either single or double quotes, but if you do, you must
306 escape any embedded instances of same sort of quote you began with,
307 as well as any escaping any escapes that immediately precede that
308 quote but which are not meant to escape the quote itself. In other
309 words, you follow single-quoting rules irrespective of the quote;
310 eg: C<O option='this isn\'t bad'> or C<O option="She said, \"Isn't
313 For historical reasons, the C<=value> is optional, but defaults to
314 1 only where it is safe to do so--that is, mostly for Boolean
315 options. It is always better to assign a specific value using C<=>.
316 The C<option> can be abbreviated, but for clarity probably should
317 not be. Several options can be set together. See L<"Configurable Options">
322 List out all pre-prompt Perl command actions.
326 Set an action (Perl command) to happen before every debugger prompt.
327 A multi-line command may be entered by backslashing the newlines.
328 B<WARNING> If C<command> is missing, all actions are wiped out!
332 Add an action (Perl command) to happen before every debugger prompt.
333 A multi-line command may be entered by backwhacking the newlines.
337 List out post-prompt Perl command actions.
341 Set an action (Perl command) to happen after the prompt when you've
342 just given a command to return to executing the script. A multi-line
343 command may be entered by backslashing the newlines (we bet you
344 couldn't've guessed this by now). B<WARNING> If C<command> is
345 missing, all actions are wiped out!
349 Adds an action (Perl command) to happen after the prompt when you've
350 just given a command to return to executing the script. A multi-line
351 command may be entered by backslashing the newlines.
355 List out pre-prompt debugger commands.
359 Set an action (debugger command) to happen before every debugger prompt.
360 A multi-line command may be entered in the customary fashion.
361 B<WARNING> If C<command> is missing, all actions are wiped out!
363 Because this command is in some senses new, a warning is issued if
364 you appear to have accidentally entered a block instead. If that's
365 what you mean to do, write it as with C<;{ ... }> or even
370 Add an action (debugger command) to happen before every debugger prompt.
371 A multi-line command may be entered, if you can guess how: see above.
375 Redo a previous command (defaults to the previous command).
379 Redo number'th previous command.
383 Redo last command that started with pattern.
384 See C<O recallCommand>, too.
388 Run cmd in a subprocess (reads from DB::IN, writes to DB::OUT) See
389 C<O shellBang>, also. Note that the user's current shell (well,
390 their C<$ENV{SHELL}> variable) will be used, which can interfere
391 with proper interpretation of exit status or signal and coredump
396 Read and execute debugger commands from I<file>. I<file> may itself contain
401 Display last n commands. Only commands longer than one character are
402 listed. If I<number> is omitted, list them all.
406 Quit. ("quit" doesn't work for this, unless you've made an alias)
407 This is the only supported way to exit the debugger, though typing
408 C<exit> twice might work.
410 Set the C<inhibit_exit> option to 0 if you want to be able to step
411 off the end the script. You may also need to set $finished to 0
412 if you want to step through global destruction.
416 Restart the debugger by C<exec()>ing a new session. We try to maintain
417 your history across this, but internal settings and command-line options
420 The following setting are currently preserved: history, breakpoints,
421 actions, debugger options, and the Perl command-line
422 options B<-w>, B<-I>, and B<-e>.
426 Run the debugger command, piping DB::OUT into your current pager.
430 Same as C<|dbcmd> but DB::OUT is temporarily C<select>ed as well.
432 =item = [alias value]
434 Define a command alias, like
438 or list current aliases.
442 Execute command as a Perl statement. A trailing semicolon will be
443 supplied. If the Perl statement would otherwise be confused for a
444 Perl debugger, use a leading semicolon, too.
448 List which methods may be called on the result of the evaluated
449 expression. The expression may evaluated to a reference to a
450 blessed object, or to a package name.
454 Despite its name, this calls your system's default documentation
455 viewer on the given page, or on the viewer itself if I<manpage> is
456 omitted. If that viewer is B<man>, the current C<Config> information
457 is used to invoke B<man> using the proper MANPATH or S<B<-M>
458 I<manpath>> option. Failed lookups of the form C<XXX> that match
459 known manpages of the form I<perlXXX> will be retried. This lets
460 you type C<man debug> or C<man op> from the debugger.
462 On systems traditionally bereft of a usable B<man> command, the
463 debugger invokes B<perldoc>. Occasionally this determination is
464 incorrect due to recalcitrant vendors or rather more felicitously,
465 to enterprising users. If you fall into either category, just
466 manually set the $DB::doccmd variable to whatever viewer to view
467 the Perl documentation on your system. This may be set in an rc
468 file, or through direct assignment. We're still waiting for a
469 working example of something along the lines of:
471 $DB::doccmd = 'netscape -remote http://something.here/';
475 =head2 Configurable Options
477 The debugger has numerous options settable using the C<O> command,
478 either interactively or from the environment or an rc file.
479 (./.perldb or ~/.perldb under Unix.)
484 =item C<recallCommand>, C<ShellBang>
486 The characters used to recall command or spawn shell. By
487 default, both are set to C<!>, which is unfortunate.
491 Program to use for output of pager-piped commands (those beginning
492 with a C<|> character.) By default, C<$ENV{PAGER}> will be used.
493 Because the debugger uses your current terminal characteristics
494 for bold and underlining, if the chosen pager does not pass escape
495 sequences through unchanged, the output of some debugger commands
496 will not be readable when sent through the pager.
500 Run Tk while prompting (with ReadLine).
502 =item C<signalLevel>, C<warnLevel>, C<dieLevel>
504 Level of verbosity. By default, the debugger leaves your exceptions
505 and warnings alone, because altering them can break correctly running
506 programs. It will attempt to print a message when uncaught INT, BUS, or
507 SEGV signals arrive. (But see the mention of signals in L<BUGS> below.)
509 To disable this default safe mode, set these values to something higher
510 than 0. At a level of 1, you get backtraces upon receiving any kind
511 of warning (this is often annoying) or exception (this is
512 often valuable). Unfortunately, the debugger cannot discern fatal
513 exceptions from non-fatal ones. If C<dieLevel> is even 1, then your
514 non-fatal exceptions are also traced and unceremoniously altered if they
515 came from C<eval'd> strings or from any kind of C<eval> within modules
516 you're attempting to load. If C<dieLevel> is 2, the debugger doesn't
517 care where they came from: It usurps your exception handler and prints
518 out a trace, then modifies all exceptions with its own embellishments.
519 This may perhaps be useful for some tracing purposes, but tends to hopelessly
520 destroy any program that takes its exception handling seriously.
524 Trace mode (similar to C<t> command, but can be put into
529 File or pipe to print line number info to. If it is a pipe (say,
530 C<|visual_perl_db>), then a short message is used. This is the
531 mechanism used to interact with a slave editor or visual debugger,
532 such as the special C<vi> or C<emacs> hooks, or the C<ddd> graphical
535 =item C<inhibit_exit>
537 If 0, allows I<stepping off> the end of the script.
541 Print return value after C<r> command if set (default).
545 Affects screen appearance of the command line (see L<Term::ReadLine>).
546 There is currently no way to disable these, which can render
547 some output illegible on some displays, or with some pagers.
548 This is considered a bug.
552 Affects the printing of messages upon entry and exit from subroutines. If
553 C<frame & 2> is false, messages are printed on entry only. (Printing
554 on exit might be useful if interspersed with other messages.)
556 If C<frame & 4>, arguments to functions are printed, plus context
557 and caller info. If C<frame & 8>, overloaded C<stringify> and
558 C<tie>d C<FETCH> is enabled on the printed arguments. If C<frame
559 & 16>, the return value from the subroutine is printed.
561 The length at which the argument list is truncated is governed by the
566 Length to truncate the argument list when the C<frame> option's
571 Change the size of code list window (default is 10 lines).
575 The following options affect what happens with C<V>, C<X>, and C<x>
580 =item C<arrayDepth>, C<hashDepth>
582 Print only first N elements ('' for all).
584 =item C<compactDump>, C<veryCompact>
586 Change the style of array and hash output. If C<compactDump>, short array
587 may be printed on one line.
591 Whether to print contents of globs.
595 Dump arrays holding debugged files.
597 =item C<DumpPackages>
599 Dump symbol tables of packages.
603 Dump contents of "reused" addresses.
605 =item C<quote>, C<HighBit>, C<undefPrint>
607 Change the style of string dump. The default value for C<quote>
608 is C<auto>; one can enable double-quotish or single-quotish format
609 by setting it to C<"> or C<'>, respectively. By default, characters
610 with their high bit set are printed verbatim.
614 Rudimentary per-package memory usage dump. Calculates total
615 size of strings found in variables in the package. This does not
616 include lexicals in a module's file scope, or lost in closures.
620 After the rc file is read, the debugger reads the C<$ENV{PERLDB_OPTS}>
621 environment variable and parses this as the remainder of a `O ...'
622 line as one might enter at the debugger prompt. You may place the
623 initialization options C<TTY>, C<noTTY>, C<ReadLine>, and C<NonStop>
626 If your rc file contains:
628 parse_options("NonStop=1 LineInfo=db.out AutoTrace");
630 then your script will run without human intervention, putting trace
631 information into the file I<db.out>. (If you interrupt it, you'd
632 better reset C<LineInfo> to F</dev/tty> if you expect to see anything.)
638 The TTY to use for debugging I/O.
642 If set, the debugger goes into C<NonStop> mode and will not connect to a TTY. If
643 interrupted (or if control goes to the debugger via explicit setting of
644 $DB::signal or $DB::single from the Perl script), it connects to a TTY
645 specified in the C<TTY> option at startup, or to a tty found at
646 runtime using the C<Term::Rendezvous> module of your choice.
648 This module should implement a method named C<new> that returns an object
649 with two methods: C<IN> and C<OUT>. These should return filehandles to use
650 for debugging input and output correspondingly. The C<new> method should
651 inspect an argument containing the value of C<$ENV{PERLDB_NOTTY}> at
652 startup, or C<"/tmp/perldbtty$$"> otherwise. This file is not
653 inspected for proper ownership, so security hazards are theoretically
658 If false, readline support in the debugger is disabled in order
659 to debug applications that themselves use ReadLine.
663 If set, the debugger goes into non-interactive mode until interrupted, or
664 programmatically by setting $DB::signal or $DB::single.
668 Here's an example of using the C<$ENV{PERLDB_OPTS}> variable:
670 $ PERLDB_OPTS="NonStop frame=2" perl -d myprogram
672 That will run the script B<myprogram> without human intervention,
673 printing out the call tree with entry and exit points. Note that
674 C<NonStop=1 frame=2> is equivalent to C<N f=2>, and that originally,
675 options could be uniquely abbreviated by the first letter (modulo
676 the C<Dump*> options). It is nevertheless recommended that you
677 always spell them out in full for legibility and future compatibility.
679 Other examples include
681 $ PERLDB_OPTS="NonStop frame=2" perl -d myprogram
683 which runs script non-interactively, printing info on each entry
684 into a subroutine and each executed line into the file named F<listing>.
685 (If you interrupt it, you would better reset C<LineInfo> to something
688 Other examples include (using standard shell syntax to show environment
691 $ ( PERLDB_OPTS="NonStop frame=1 AutoTrace LineInfo=tperl.out"
694 which may be useful for debugging a program that uses C<Term::ReadLine>
695 itself. Do not forget to detach your shell from the TTY in the window that
696 corresponds to F</dev/ttyXX>, say, by issuing a command like
700 See L<perldebguts/"Debugger Internals"> for details.
702 =head2 Debugger input/output
708 The debugger prompt is something like
716 where that number is the command number, and which you'd use to
717 access with the built-in B<csh>-like history mechanism. For example,
718 C<!17> would repeat command number 17. The depth of the angle
719 brackets indicates the nesting depth of the debugger. You could
720 get more than one set of brackets, for example, if you'd already
721 at a breakpoint and then printed the result of a function call that
722 itself has a breakpoint, or you step into an expression via C<s/n/t
725 =item Multiline commands
727 If you want to enter a multi-line command, such as a subroutine
728 definition with several statements or a format, escape the newline
729 that would normally end the debugger command with a backslash.
733 cont: print "ok\n"; \
740 Note that this business of escaping a newline is specific to interactive
741 commands typed into the debugger.
743 =item Stack backtrace
745 Here's an example of what a stack backtrace via C<T> command might
748 $ = main::infested called from file `Ambulation.pm' line 10
749 @ = Ambulation::legs(1, 2, 3, 4) called from file `camel_flea' line 7
750 $ = main::pests('bactrian', 4) called from file `camel_flea' line 4
752 The left-hand character up there indicates the context in which the
753 function was called, with C<$> and C<@> meaning scalar or list
754 contexts respectively, and C<.> meaning void context (which is
755 actually a sort of scalar context). The display above says
756 that you were in the function C<main::infested> when you ran the
757 stack dump, and that it was called in scalar context from line
758 10 of the file I<Ambulation.pm>, but without any arguments at all,
759 meaning it was called as C<&infested>. The next stack frame shows
760 that the function C<Ambulation::legs> was called in list context
761 from the I<camel_flea> file with four arguments. The last stack
762 frame shows that C<main::pests> was called in scalar context,
763 also from I<camel_flea>, but from line 4.
765 If you execute the C<T> command from inside an active C<use>
766 statement, the backtrace will contain both a C<require> frame and
769 =item Line Listing Format
771 This shows the sorts of output the C<l> command can produce:
775 102:b @isa{@i,$pack} = ()
776 103 if(exists $i{$prevpack} || exists $isa{$pack});
780 107==> if(exists $isa{$pack});
782 109:a if ($extra-- > 0) {
783 110: %isa = ($pack,1);
785 Breakable lines are marked with C<:>. Lines with breakpoints are
786 marked by C<b> and those with actions by C<a>. The line that's
787 about to be executed is marked by C<< ==> >>.
789 Please be aware that code in debugger listings may not look the same
790 as your original source code. Line directives and external source
791 filters can alter the code before Perl sees it, causing code to move
792 from its original positions or take on entirely different forms.
796 When the C<frame> option is set, the debugger would print entered (and
797 optionally exited) subroutines in different styles. See L<perldebguts>
798 for incredibly long examples of these.
802 =head2 Debugging compile-time statements
804 If you have compile-time executable statements (such as code within
805 BEGIN and CHECK blocks or C<use> statements), these will I<not> be
806 stopped by debugger, although C<require>s and INIT blocks will, and
807 compile-time statements can be traced with C<AutoTrace> option set
808 in C<PERLDB_OPTS>). From your own Perl code, however, you can
809 transfer control back to the debugger using the following statement,
810 which is harmless if the debugger is not running:
814 If you set C<$DB::single> to 2, it's equivalent to having
815 just typed the C<n> command, whereas a value of 1 means the C<s>
816 command. The C<$DB::trace> variable should be set to 1 to simulate
817 having typed the C<t> command.
819 Another way to debug compile-time code is to start the debugger, set a
820 breakpoint on the I<load> of some module:
822 DB<7> b load f:/perllib/lib/Carp.pm
823 Will stop on load of `f:/perllib/lib/Carp.pm'.
825 and then restart the debugger using the C<R> command (if possible). One can use C<b
826 compile subname> for the same purpose.
828 =head2 Debugger Customization
830 The debugger probably contains enough configuration hooks that you
831 won't ever have to modify it yourself. You may change the behaviour
832 of debugger from within the debugger using its C<O> command, from
833 the command line via the C<PERLDB_OPTS> environment variable, and
834 from customization files.
836 You can do some customization by setting up a F<.perldb> file, which
837 contains initialization code. For instance, you could make aliases
838 like these (the last one is one people expect to be there):
840 $DB::alias{'len'} = 's/^len(.*)/p length($1)/';
841 $DB::alias{'stop'} = 's/^stop (at|in)/b/';
842 $DB::alias{'ps'} = 's/^ps\b/p scalar /';
843 $DB::alias{'quit'} = 's/^quit(\s*)/exit/';
845 You can change options from F<.perldb> by using calls like this one;
847 parse_options("NonStop=1 LineInfo=db.out AutoTrace=1 frame=2");
849 The code is executed in the package C<DB>. Note that F<.perldb> is
850 processed before processing C<PERLDB_OPTS>. If F<.perldb> defines the
851 subroutine C<afterinit>, that function is called after debugger
852 initialization ends. F<.perldb> may be contained in the current
853 directory, or in the home directory. Because this file is sourced
854 in by Perl and may contain arbitrary commands, for security reasons,
855 it must be owned by the superuser or the current user, and writable
856 by no one but its owner.
858 If you want to modify the debugger, copy F<perl5db.pl> from the
859 Perl library to another name and hack it to your heart's content.
860 You'll then want to set your C<PERL5DB> environment variable to say
863 BEGIN { require "myperl5db.pl" }
865 As a last resort, you could also use C<PERL5DB> to customize the debugger
866 by directly setting internal variables or calling debugger functions.
868 Note that any variables and functions that are not documented in
869 this document (or in L<perldebguts>) are considered for internal
870 use only, and as such are subject to change without notice.
872 =head2 Readline Support
874 As shipped, the only command-line history supplied is a simplistic one
875 that checks for leading exclamation points. However, if you install
876 the Term::ReadKey and Term::ReadLine modules from CPAN, you will
877 have full editing capabilities much like GNU I<readline>(3) provides.
878 Look for these in the F<modules/by-module/Term> directory on CPAN.
879 These do not support normal B<vi> command-line editing, however.
881 A rudimentary command-line completion is also available.
882 Unfortunately, the names of lexical variables are not available for
885 =head2 Editor Support for Debugging
887 If you have the FSF's version of B<emacs> installed on your system,
888 it can interact with the Perl debugger to provide an integrated
889 software development environment reminiscent of its interactions
892 Perl comes with a start file for making B<emacs> act like a
893 syntax-directed editor that understands (some of) Perl's syntax.
894 Look in the I<emacs> directory of the Perl source distribution.
896 A similar setup by Tom Christiansen for interacting with any
897 vendor-shipped B<vi> and the X11 window system is also available.
898 This works similarly to the integrated multiwindow support that
899 B<emacs> provides, where the debugger drives the editor. At the
900 time of this writing, however, that tool's eventual location in the
901 Perl distribution was uncertain.
903 Users of B<vi> should also look into B<vim> and B<gvim>, the mousey
904 and windy version, for coloring of Perl keywords.
906 Note that only perl can truly parse Perl, so all such CASE tools
907 fall somewhat short of the mark, especially if you don't program
908 your Perl as a C programmer might.
910 =head2 The Perl Profiler
912 If you wish to supply an alternative debugger for Perl to run, just
913 invoke your script with a colon and a package argument given to the
914 B<-d> flag. The most popular alternative debuggers for Perl is the
915 Perl profiler. Devel::DProf is now included with the standard Perl
916 distribution. To profile your Perl program in the file F<mycode.pl>,
919 $ perl -d:DProf mycode.pl
921 When the script terminates the profiler will dump the profile
922 information to a file called F<tmon.out>. A tool like B<dprofpp>,
923 also supplied with the standard Perl distribution, can be used to
924 interpret the information in that profile.
926 =head1 Debugging regular expressions
928 C<use re 'debug'> enables you to see the gory details of how the Perl
929 regular expression engine works. In order to understand this typically
930 voluminous output, one must not only have some idea about how regular
931 expression matching works in general, but also know how Perl's regular
932 expressions are internally compiled into an automaton. These matters
933 are explored in some detail in
934 L<perldebguts/"Debugging regular expressions">.
936 =head1 Debugging memory usage
938 Perl contains internal support for reporting its own memory usage,
939 but this is a fairly advanced concept that requires some understanding
940 of how memory allocation works.
941 See L<perldebguts/"Debugging Perl memory usage"> for the details.
945 You did try the B<-w> switch, didn't you?
959 You cannot get stack frame information or in any fashion debug functions
960 that were not compiled by Perl, such as those from C or C++ extensions.
962 If you alter your @_ arguments in a subroutine (such as with C<shift>
963 or C<pop>), the stack backtrace will not show the original values.
965 The debugger does not currently work in conjunction with the B<-W>
966 command-line switch, because it itself is not free of warnings.
968 If you're in a slow syscall (like C<wait>ing, C<accept>ing, or C<read>ing
969 from your keyboard or a socket) and haven't set up your own C<$SIG{INT}>
970 handler, then you won't be able to CTRL-C your way back to the debugger,
971 because the debugger's own C<$SIG{INT}> handler doesn't understand that
972 it needs to raise an exception to longjmp(3) out of slow syscalls.