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.
81 =item x [maxdepth] expr
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">.
91 If the C<maxdepth> is included, it must be a numeral I<N>; the value is
92 dumped only I<N> levels deep, as if the C<dumpDepth> option had been
93 deporarily set to I<N>.
97 Display all (or some) variables in package (defaulting to C<main>)
98 using a data pretty-printer (hashes show their keys and values so
99 you see what's what, control characters are made printable, etc.).
100 Make sure you don't put the type specifier (like C<$>) there, just
101 the symbol names, like this:
105 Use C<~pattern> and C<!pattern> for positive and negative regexes.
107 This is similar to calling the C<x> command on each applicable var.
111 Same as C<V currentpackage [vars]>.
115 Produce a stack backtrace. See below for details on its output.
119 Single step. Executes until the beginning of another
120 statement, descending into subroutine calls. If an expression is
121 supplied that includes function calls, it too will be single-stepped.
125 Next. Executes over subroutine calls, until the beginning
126 of the next statement. If an expression is supplied that includes
127 function calls, those functions will be executed with stops before
132 Continue until the return from the current subroutine.
133 Dump the return value if the C<PrintRet> option is set (default).
137 Repeat last C<n> or C<s> command.
141 Continue, optionally inserting a one-time-only breakpoint
142 at the specified line or subroutine.
146 List next window of lines.
150 List C<incr+1> lines starting at C<min>.
154 List lines C<min> through C<max>. C<l -> is synonymous to C<->.
162 List first window of lines from subroutine. I<subname> may
163 be a variable that contains a code reference.
167 List previous window of lines.
171 List window (a few lines) around the current line.
175 Return the internal debugger pointer to the line last
176 executed, and print out that line.
180 Switch to viewing a different file or C<eval> statement. If I<filename>
181 is not a full pathname found in the values of %INC, it is considered
184 C<eval>ed strings (when accessible) are considered to be filenames:
185 C<f (eval 7)> and C<f eval 7\b> access the body of the 7th C<eval>ed string
186 (in the order of execution). The bodies of the currently executed C<eval>
187 and of C<eval>ed strings that define subroutines are saved and thus
192 Search forwards for pattern (a Perl regex); final / is optional.
193 The search is case-insensitive by default.
197 Search backwards for pattern; final ? is optional.
198 The search is case-insensitive by default.
202 List all breakpoints and actions.
206 List subroutine names [not] matching the regex.
210 Toggle trace mode (see also the C<AutoTrace> option).
214 Trace through execution of C<expr>.
215 See L<perldebguts/"Frame Listing Output Examples"> for examples.
217 =item b [line] [condition]
219 Set a breakpoint before the given line. If I<line> is omitted, set a
220 breakpoint on the line about to be executed. If a condition
221 is specified, it's evaluated each time the statement is reached: a
222 breakpoint is taken only if the condition is true. Breakpoints may
223 only be set on lines that begin an executable statement. Conditions
227 b 237 ++$count237 < 11
230 =item b subname [condition]
232 Set a breakpoint before the first line of the named subroutine. I<subname> may
233 be a variable containing a code reference (in this case I<condition>
236 =item b postpone subname [condition]
238 Set a breakpoint at first line of subroutine after it is compiled.
240 =item b load filename
242 Set a breakpoint before the first executed line of the I<filename>,
243 which should be a full pathname found amongst the %INC values.
245 =item b compile subname
247 Sets a breakpoint before the first statement executed after the specified
248 subroutine is compiled.
252 Delete a breakpoint from the specified I<line>. If I<line> is omitted, deletes
253 the breakpoint from the line about to be executed.
257 Delete all installed breakpoints.
259 =item a [line] command
261 Set an action to be done before the line is executed. If I<line> is
262 omitted, set an action on the line about to be executed.
263 The sequence of steps taken by the debugger is
265 1. check for a breakpoint at this line
266 2. print the line if necessary (tracing)
267 3. do any actions associated with that line
268 4. prompt user if at a breakpoint or in single-step
271 For example, this will print out $foo every time line
274 a 53 print "DB FOUND $foo\n"
278 Delete an action from the specified line. If I<line> is omitted, delete
279 the action on the line that is about to be executed.
283 Delete all installed actions.
287 Add a global watch-expression. We hope you know what one of these
288 is, because they're supposed to be obvious. B<WARNING>: It is far
289 too easy to destroy your watch expressions by accidentally omitting
294 Delete all watch-expressions.
296 =item O booloption ...
298 Set each listed Boolean option to the value C<1>.
300 =item O anyoption? ...
302 Print out the value of one or more options.
304 =item O option=value ...
306 Set the value of one or more options. If the value has internal
307 whitespace, it should be quoted. For example, you could set C<O
308 pager="less -MQeicsNfr"> to call B<less> with those specific options.
309 You may use either single or double quotes, but if you do, you must
310 escape any embedded instances of same sort of quote you began with,
311 as well as any escaping any escapes that immediately precede that
312 quote but which are not meant to escape the quote itself. In other
313 words, you follow single-quoting rules irrespective of the quote;
314 eg: C<O option='this isn\'t bad'> or C<O option="She said, \"Isn't
317 For historical reasons, the C<=value> is optional, but defaults to
318 1 only where it is safe to do so--that is, mostly for Boolean
319 options. It is always better to assign a specific value using C<=>.
320 The C<option> can be abbreviated, but for clarity probably should
321 not be. Several options can be set together. See L<"Configurable Options">
326 List out all pre-prompt Perl command actions.
330 Set an action (Perl command) to happen before every debugger prompt.
331 A multi-line command may be entered by backslashing the newlines.
332 B<WARNING> If C<command> is missing, all actions are wiped out!
336 Add an action (Perl command) to happen before every debugger prompt.
337 A multi-line command may be entered by backwhacking the newlines.
341 List out post-prompt Perl command actions.
345 Set an action (Perl command) to happen after the prompt when you've
346 just given a command to return to executing the script. A multi-line
347 command may be entered by backslashing the newlines (we bet you
348 couldn't've guessed this by now). B<WARNING> If C<command> is
349 missing, all actions are wiped out!
353 Adds an action (Perl command) to happen after the prompt when you've
354 just given a command to return to executing the script. A multi-line
355 command may be entered by backslashing the newlines.
359 List out pre-prompt debugger commands.
363 Set an action (debugger command) to happen before every debugger prompt.
364 A multi-line command may be entered in the customary fashion.
365 B<WARNING> If C<command> is missing, all actions are wiped out!
367 Because this command is in some senses new, a warning is issued if
368 you appear to have accidentally entered a block instead. If that's
369 what you mean to do, write it as with C<;{ ... }> or even
374 Add an action (debugger command) to happen before every debugger prompt.
375 A multi-line command may be entered, if you can guess how: see above.
379 Redo a previous command (defaults to the previous command).
383 Redo number'th previous command.
387 Redo last command that started with pattern.
388 See C<O recallCommand>, too.
392 Run cmd in a subprocess (reads from DB::IN, writes to DB::OUT) See
393 C<O shellBang>, also. Note that the user's current shell (well,
394 their C<$ENV{SHELL}> variable) will be used, which can interfere
395 with proper interpretation of exit status or signal and coredump
400 Read and execute debugger commands from I<file>. I<file> may itself contain
405 Display last n commands. Only commands longer than one character are
406 listed. If I<number> is omitted, list them all.
410 Quit. ("quit" doesn't work for this, unless you've made an alias)
411 This is the only supported way to exit the debugger, though typing
412 C<exit> twice might work.
414 Set the C<inhibit_exit> option to 0 if you want to be able to step
415 off the end the script. You may also need to set $finished to 0
416 if you want to step through global destruction.
420 Restart the debugger by C<exec()>ing a new session. We try to maintain
421 your history across this, but internal settings and command-line options
424 The following setting are currently preserved: history, breakpoints,
425 actions, debugger options, and the Perl command-line
426 options B<-w>, B<-I>, and B<-e>.
430 Run the debugger command, piping DB::OUT into your current pager.
434 Same as C<|dbcmd> but DB::OUT is temporarily C<select>ed as well.
436 =item = [alias value]
438 Define a command alias, like
442 or list current aliases.
446 Execute command as a Perl statement. A trailing semicolon will be
447 supplied. If the Perl statement would otherwise be confused for a
448 Perl debugger, use a leading semicolon, too.
452 List which methods may be called on the result of the evaluated
453 expression. The expression may evaluated to a reference to a
454 blessed object, or to a package name.
458 Despite its name, this calls your system's default documentation
459 viewer on the given page, or on the viewer itself if I<manpage> is
460 omitted. If that viewer is B<man>, the current C<Config> information
461 is used to invoke B<man> using the proper MANPATH or S<B<-M>
462 I<manpath>> option. Failed lookups of the form C<XXX> that match
463 known manpages of the form I<perlXXX> will be retried. This lets
464 you type C<man debug> or C<man op> from the debugger.
466 On systems traditionally bereft of a usable B<man> command, the
467 debugger invokes B<perldoc>. Occasionally this determination is
468 incorrect due to recalcitrant vendors or rather more felicitously,
469 to enterprising users. If you fall into either category, just
470 manually set the $DB::doccmd variable to whatever viewer to view
471 the Perl documentation on your system. This may be set in an rc
472 file, or through direct assignment. We're still waiting for a
473 working example of something along the lines of:
475 $DB::doccmd = 'netscape -remote http://something.here/';
479 =head2 Configurable Options
481 The debugger has numerous options settable using the C<O> command,
482 either interactively or from the environment or an rc file.
483 (./.perldb or ~/.perldb under Unix.)
488 =item C<recallCommand>, C<ShellBang>
490 The characters used to recall command or spawn shell. By
491 default, both are set to C<!>, which is unfortunate.
495 Program to use for output of pager-piped commands (those beginning
496 with a C<|> character.) By default, C<$ENV{PAGER}> will be used.
497 Because the debugger uses your current terminal characteristics
498 for bold and underlining, if the chosen pager does not pass escape
499 sequences through unchanged, the output of some debugger commands
500 will not be readable when sent through the pager.
504 Run Tk while prompting (with ReadLine).
506 =item C<signalLevel>, C<warnLevel>, C<dieLevel>
508 Level of verbosity. By default, the debugger leaves your exceptions
509 and warnings alone, because altering them can break correctly running
510 programs. It will attempt to print a message when uncaught INT, BUS, or
511 SEGV signals arrive. (But see the mention of signals in L<BUGS> below.)
513 To disable this default safe mode, set these values to something higher
514 than 0. At a level of 1, you get backtraces upon receiving any kind
515 of warning (this is often annoying) or exception (this is
516 often valuable). Unfortunately, the debugger cannot discern fatal
517 exceptions from non-fatal ones. If C<dieLevel> is even 1, then your
518 non-fatal exceptions are also traced and unceremoniously altered if they
519 came from C<eval'd> strings or from any kind of C<eval> within modules
520 you're attempting to load. If C<dieLevel> is 2, the debugger doesn't
521 care where they came from: It usurps your exception handler and prints
522 out a trace, then modifies all exceptions with its own embellishments.
523 This may perhaps be useful for some tracing purposes, but tends to hopelessly
524 destroy any program that takes its exception handling seriously.
528 Trace mode (similar to C<t> command, but can be put into
533 File or pipe to print line number info to. If it is a pipe (say,
534 C<|visual_perl_db>), then a short message is used. This is the
535 mechanism used to interact with a slave editor or visual debugger,
536 such as the special C<vi> or C<emacs> hooks, or the C<ddd> graphical
539 =item C<inhibit_exit>
541 If 0, allows I<stepping off> the end of the script.
545 Print return value after C<r> command if set (default).
549 Affects screen appearance of the command line (see L<Term::ReadLine>).
550 There is currently no way to disable these, which can render
551 some output illegible on some displays, or with some pagers.
552 This is considered a bug.
556 Affects the printing of messages upon entry and exit from subroutines. If
557 C<frame & 2> is false, messages are printed on entry only. (Printing
558 on exit might be useful if interspersed with other messages.)
560 If C<frame & 4>, arguments to functions are printed, plus context
561 and caller info. If C<frame & 8>, overloaded C<stringify> and
562 C<tie>d C<FETCH> is enabled on the printed arguments. If C<frame
563 & 16>, the return value from the subroutine is printed.
565 The length at which the argument list is truncated is governed by the
570 Length to truncate the argument list when the C<frame> option's
575 Change the size of code list window (default is 10 lines).
579 The following options affect what happens with C<V>, C<X>, and C<x>
584 =item C<arrayDepth>, C<hashDepth>
586 Print only first N elements ('' for all).
590 Limit recursion depth to N levels when dumping structures.
591 Negative values are interpreted as infinity. Default: infinity.
593 =item C<compactDump>, C<veryCompact>
595 Change the style of array and hash output. If C<compactDump>, short array
596 may be printed on one line.
600 Whether to print contents of globs.
604 Dump arrays holding debugged files.
606 =item C<DumpPackages>
608 Dump symbol tables of packages.
612 Dump contents of "reused" addresses.
614 =item C<quote>, C<HighBit>, C<undefPrint>
616 Change the style of string dump. The default value for C<quote>
617 is C<auto>; one can enable double-quotish or single-quotish format
618 by setting it to C<"> or C<'>, respectively. By default, characters
619 with their high bit set are printed verbatim.
623 Rudimentary per-package memory usage dump. Calculates total
624 size of strings found in variables in the package. This does not
625 include lexicals in a module's file scope, or lost in closures.
629 After the rc file is read, the debugger reads the C<$ENV{PERLDB_OPTS}>
630 environment variable and parses this as the remainder of a `O ...'
631 line as one might enter at the debugger prompt. You may place the
632 initialization options C<TTY>, C<noTTY>, C<ReadLine>, and C<NonStop>
635 If your rc file contains:
637 parse_options("NonStop=1 LineInfo=db.out AutoTrace");
639 then your script will run without human intervention, putting trace
640 information into the file I<db.out>. (If you interrupt it, you'd
641 better reset C<LineInfo> to F</dev/tty> if you expect to see anything.)
647 The TTY to use for debugging I/O.
651 If set, the debugger goes into C<NonStop> mode and will not connect to a TTY. If
652 interrupted (or if control goes to the debugger via explicit setting of
653 $DB::signal or $DB::single from the Perl script), it connects to a TTY
654 specified in the C<TTY> option at startup, or to a tty found at
655 runtime using the C<Term::Rendezvous> module of your choice.
657 This module should implement a method named C<new> that returns an object
658 with two methods: C<IN> and C<OUT>. These should return filehandles to use
659 for debugging input and output correspondingly. The C<new> method should
660 inspect an argument containing the value of C<$ENV{PERLDB_NOTTY}> at
661 startup, or C<"/tmp/perldbtty$$"> otherwise. This file is not
662 inspected for proper ownership, so security hazards are theoretically
667 If false, readline support in the debugger is disabled in order
668 to debug applications that themselves use ReadLine.
672 If set, the debugger goes into non-interactive mode until interrupted, or
673 programmatically by setting $DB::signal or $DB::single.
677 Here's an example of using the C<$ENV{PERLDB_OPTS}> variable:
679 $ PERLDB_OPTS="NonStop frame=2" perl -d myprogram
681 That will run the script B<myprogram> without human intervention,
682 printing out the call tree with entry and exit points. Note that
683 C<NonStop=1 frame=2> is equivalent to C<N f=2>, and that originally,
684 options could be uniquely abbreviated by the first letter (modulo
685 the C<Dump*> options). It is nevertheless recommended that you
686 always spell them out in full for legibility and future compatibility.
688 Other examples include
690 $ PERLDB_OPTS="NonStop LineInfo=listing frame=2" perl -d myprogram
692 which runs script non-interactively, printing info on each entry
693 into a subroutine and each executed line into the file named F<listing>.
694 (If you interrupt it, you would better reset C<LineInfo> to something
697 Other examples include (using standard shell syntax to show environment
700 $ ( PERLDB_OPTS="NonStop frame=1 AutoTrace LineInfo=tperl.out"
703 which may be useful for debugging a program that uses C<Term::ReadLine>
704 itself. Do not forget to detach your shell from the TTY in the window that
705 corresponds to F</dev/ttyXX>, say, by issuing a command like
709 See L<perldebguts/"Debugger Internals"> for details.
711 =head2 Debugger input/output
717 The debugger prompt is something like
725 where that number is the command number, and which you'd use to
726 access with the built-in B<csh>-like history mechanism. For example,
727 C<!17> would repeat command number 17. The depth of the angle
728 brackets indicates the nesting depth of the debugger. You could
729 get more than one set of brackets, for example, if you'd already
730 at a breakpoint and then printed the result of a function call that
731 itself has a breakpoint, or you step into an expression via C<s/n/t
734 =item Multiline commands
736 If you want to enter a multi-line command, such as a subroutine
737 definition with several statements or a format, escape the newline
738 that would normally end the debugger command with a backslash.
742 cont: print "ok\n"; \
749 Note that this business of escaping a newline is specific to interactive
750 commands typed into the debugger.
752 =item Stack backtrace
754 Here's an example of what a stack backtrace via C<T> command might
757 $ = main::infested called from file `Ambulation.pm' line 10
758 @ = Ambulation::legs(1, 2, 3, 4) called from file `camel_flea' line 7
759 $ = main::pests('bactrian', 4) called from file `camel_flea' line 4
761 The left-hand character up there indicates the context in which the
762 function was called, with C<$> and C<@> meaning scalar or list
763 contexts respectively, and C<.> meaning void context (which is
764 actually a sort of scalar context). The display above says
765 that you were in the function C<main::infested> when you ran the
766 stack dump, and that it was called in scalar context from line
767 10 of the file I<Ambulation.pm>, but without any arguments at all,
768 meaning it was called as C<&infested>. The next stack frame shows
769 that the function C<Ambulation::legs> was called in list context
770 from the I<camel_flea> file with four arguments. The last stack
771 frame shows that C<main::pests> was called in scalar context,
772 also from I<camel_flea>, but from line 4.
774 If you execute the C<T> command from inside an active C<use>
775 statement, the backtrace will contain both a C<require> frame and
778 =item Line Listing Format
780 This shows the sorts of output the C<l> command can produce:
784 102:b @isa{@i,$pack} = ()
785 103 if(exists $i{$prevpack} || exists $isa{$pack});
789 107==> if(exists $isa{$pack});
791 109:a if ($extra-- > 0) {
792 110: %isa = ($pack,1);
794 Breakable lines are marked with C<:>. Lines with breakpoints are
795 marked by C<b> and those with actions by C<a>. The line that's
796 about to be executed is marked by C<< ==> >>.
798 Please be aware that code in debugger listings may not look the same
799 as your original source code. Line directives and external source
800 filters can alter the code before Perl sees it, causing code to move
801 from its original positions or take on entirely different forms.
805 When the C<frame> option is set, the debugger would print entered (and
806 optionally exited) subroutines in different styles. See L<perldebguts>
807 for incredibly long examples of these.
811 =head2 Debugging compile-time statements
813 If you have compile-time executable statements (such as code within
814 BEGIN and CHECK blocks or C<use> statements), these will I<not> be
815 stopped by debugger, although C<require>s and INIT blocks will, and
816 compile-time statements can be traced with C<AutoTrace> option set
817 in C<PERLDB_OPTS>). From your own Perl code, however, you can
818 transfer control back to the debugger using the following statement,
819 which is harmless if the debugger is not running:
823 If you set C<$DB::single> to 2, it's equivalent to having
824 just typed the C<n> command, whereas a value of 1 means the C<s>
825 command. The C<$DB::trace> variable should be set to 1 to simulate
826 having typed the C<t> command.
828 Another way to debug compile-time code is to start the debugger, set a
829 breakpoint on the I<load> of some module:
831 DB<7> b load f:/perllib/lib/Carp.pm
832 Will stop on load of `f:/perllib/lib/Carp.pm'.
834 and then restart the debugger using the C<R> command (if possible). One can use C<b
835 compile subname> for the same purpose.
837 =head2 Debugger Customization
839 The debugger probably contains enough configuration hooks that you
840 won't ever have to modify it yourself. You may change the behaviour
841 of debugger from within the debugger using its C<O> command, from
842 the command line via the C<PERLDB_OPTS> environment variable, and
843 from customization files.
845 You can do some customization by setting up a F<.perldb> file, which
846 contains initialization code. For instance, you could make aliases
847 like these (the last one is one people expect to be there):
849 $DB::alias{'len'} = 's/^len(.*)/p length($1)/';
850 $DB::alias{'stop'} = 's/^stop (at|in)/b/';
851 $DB::alias{'ps'} = 's/^ps\b/p scalar /';
852 $DB::alias{'quit'} = 's/^quit(\s*)/exit/';
854 You can change options from F<.perldb> by using calls like this one;
856 parse_options("NonStop=1 LineInfo=db.out AutoTrace=1 frame=2");
858 The code is executed in the package C<DB>. Note that F<.perldb> is
859 processed before processing C<PERLDB_OPTS>. If F<.perldb> defines the
860 subroutine C<afterinit>, that function is called after debugger
861 initialization ends. F<.perldb> may be contained in the current
862 directory, or in the home directory. Because this file is sourced
863 in by Perl and may contain arbitrary commands, for security reasons,
864 it must be owned by the superuser or the current user, and writable
865 by no one but its owner.
867 If you want to modify the debugger, copy F<perl5db.pl> from the
868 Perl library to another name and hack it to your heart's content.
869 You'll then want to set your C<PERL5DB> environment variable to say
872 BEGIN { require "myperl5db.pl" }
874 As a last resort, you could also use C<PERL5DB> to customize the debugger
875 by directly setting internal variables or calling debugger functions.
877 Note that any variables and functions that are not documented in
878 this document (or in L<perldebguts>) are considered for internal
879 use only, and as such are subject to change without notice.
881 =head2 Readline Support
883 As shipped, the only command-line history supplied is a simplistic one
884 that checks for leading exclamation points. However, if you install
885 the Term::ReadKey and Term::ReadLine modules from CPAN, you will
886 have full editing capabilities much like GNU I<readline>(3) provides.
887 Look for these in the F<modules/by-module/Term> directory on CPAN.
888 These do not support normal B<vi> command-line editing, however.
890 A rudimentary command-line completion is also available.
891 Unfortunately, the names of lexical variables are not available for
894 =head2 Editor Support for Debugging
896 If you have the FSF's version of B<emacs> installed on your system,
897 it can interact with the Perl debugger to provide an integrated
898 software development environment reminiscent of its interactions
901 Perl comes with a start file for making B<emacs> act like a
902 syntax-directed editor that understands (some of) Perl's syntax.
903 Look in the I<emacs> directory of the Perl source distribution.
905 A similar setup by Tom Christiansen for interacting with any
906 vendor-shipped B<vi> and the X11 window system is also available.
907 This works similarly to the integrated multiwindow support that
908 B<emacs> provides, where the debugger drives the editor. At the
909 time of this writing, however, that tool's eventual location in the
910 Perl distribution was uncertain.
912 Users of B<vi> should also look into B<vim> and B<gvim>, the mousey
913 and windy version, for coloring of Perl keywords.
915 Note that only perl can truly parse Perl, so all such CASE tools
916 fall somewhat short of the mark, especially if you don't program
917 your Perl as a C programmer might.
919 =head2 The Perl Profiler
921 If you wish to supply an alternative debugger for Perl to run, just
922 invoke your script with a colon and a package argument given to the
923 B<-d> flag. The most popular alternative debuggers for Perl is the
924 Perl profiler. Devel::DProf is now included with the standard Perl
925 distribution. To profile your Perl program in the file F<mycode.pl>,
928 $ perl -d:DProf mycode.pl
930 When the script terminates the profiler will dump the profile
931 information to a file called F<tmon.out>. A tool like B<dprofpp>,
932 also supplied with the standard Perl distribution, can be used to
933 interpret the information in that profile.
935 =head1 Debugging regular expressions
937 C<use re 'debug'> enables you to see the gory details of how the Perl
938 regular expression engine works. In order to understand this typically
939 voluminous output, one must not only have some idea about how regular
940 expression matching works in general, but also know how Perl's regular
941 expressions are internally compiled into an automaton. These matters
942 are explored in some detail in
943 L<perldebguts/"Debugging regular expressions">.
945 =head1 Debugging memory usage
947 Perl contains internal support for reporting its own memory usage,
948 but this is a fairly advanced concept that requires some understanding
949 of how memory allocation works.
950 See L<perldebguts/"Debugging Perl memory usage"> for the details.
954 You did try the B<-w> switch, didn't you?
968 You cannot get stack frame information or in any fashion debug functions
969 that were not compiled by Perl, such as those from C or C++ extensions.
971 If you alter your @_ arguments in a subroutine (such as with C<shift>
972 or C<pop>), the stack backtrace will not show the original values.
974 The debugger does not currently work in conjunction with the B<-W>
975 command-line switch, because it itself is not free of warnings.
977 If you're in a slow syscall (like C<wait>ing, C<accept>ing, or C<read>ing
978 from your keyboard or a socket) and haven't set up your own C<$SIG{INT}>
979 handler, then you won't be able to CTRL-C your way back to the debugger,
980 because the debugger's own C<$SIG{INT}> handler doesn't understand that
981 it needs to raise an exception to longjmp(3) out of slow syscalls.