1N/Aperldebug - Perl debugging
1N/AFirst of all, have you tried using the B<-w> switch?
1N/AIf you're new to the Perl debugger, you may prefer to read
1N/AL<perldebtut>, which is a tutorial introduction to the debugger .
1N/A=head1 The Perl Debugger
1N/AIf you invoke Perl with the B<-d> switch, your script runs under the
1N/APerl source debugger. This works like an interactive Perl
1N/Aenvironment, prompting for debugger commands that let you examine
1N/Asource code, set breakpoints, get stack backtraces, change the values of
1N/Avariables, etc. This is so convenient that you often fire up
1N/Athe debugger all by itself just to test out Perl constructs
1N/Ainteractively to see what they do. For example:
1N/AIn Perl, the debugger is not a separate program the way it usually is in the
1N/Atypical compiled environment. Instead, the B<-d> flag tells the compiler
1N/Ato insert source information into the parse trees it's about to hand off
1N/Ato the interpreter. That means your code must first compile correctly
1N/Afor the debugger to work on it. Then when the interpreter starts up, it
1N/Apreloads a special Perl library file containing the debugger.
1N/AThe program will halt I<right before> the first run-time executable
1N/Astatement (but see below regarding compile-time statements) and ask you
1N/Ato enter a debugger command. Contrary to popular expectations, whenever
1N/Athe debugger halts and shows you a line of code, it always displays the
1N/Aline it's I<about> to execute, rather than the one it has just executed.
1N/AAny command not recognized by the debugger is directly executed
1N/A(C<eval>'d) as Perl code in the current package. (The debugger
1N/Auses the DB package for keeping its own state information.)
1N/ANote that the said C<eval> is bound by an implicit scope. As a
1N/Aresult any newly introduced lexical variable or any modified
1N/Acapture buffer content is lost after the eval. The debugger is a
1N/Anice environment to learn Perl, but if you interactively experiment using
1N/Amaterial which should be in the same scope, stuff it in one line.
1N/AFor any text entered at the debugger prompt, leading and trailing whitespace
1N/Ais first stripped before further processing. If a debugger command
1N/Acoincides with some function in your own program, merely precede the
1N/Afunction with something that doesn't look like a debugger command, such
1N/Aas a leading C<;> or perhaps a C<+>, or by wrapping it with parentheses
1N/A=head2 Debugger Commands
1N/AThe debugger understands the following commands:
1N/APrints out a summary help message
1N/APrints out a help message for the given debugger command.
1N/AThe special argument of C<h h> produces the entire help page, which is quite long.
1N/AIf the output of the C<h h> command (or any command, for that matter) scrolls
1N/Apast your screen, precede the command with a leading pipe symbol so
1N/Athat it's run through your pager, as in
1N/AYou may change the pager which is used via C<o pager=...> command.
1N/ASame as C<print {$DB::OUT} expr> in the current package. In particular,
1N/Abecause this is just Perl's own C<print> function, this means that nested
1N/Adata structures and objects are not dumped, unlike with the C<x> command.
1N/AThe C<DB::OUT> filehandle is opened to F<
/dev/tty>, regardless of
1N/Awhere STDOUT may be redirected to.
1N/A=item x [maxdepth] expr
1N/AEvaluates its expression in list context and dumps out the result in a
1N/Apretty-printed fashion. Nested data structures are printed out
1N/Arecursively, unlike the real C<print> function in Perl. When dumping
1N/Ahashes, you'll probably prefer 'x \%h' rather than 'x %h'.
1N/ASee L<Dumpvalue> if you'd like to do this yourself.
1N/AThe output format is governed by multiple options described under
1N/AL<"Configurable Options">.
1N/AIf the C<maxdepth> is included, it must be a numeral I<N>; the value is
1N/Adumped only I<N> levels deep, as if the C<dumpDepth> option had been
1N/Atemporarily set to I<N>.
1N/ADisplay all (or some) variables in package (defaulting to C<main>)
1N/Ausing a data pretty-printer (hashes show their keys and values so
1N/Ayou see what's what, control characters are made printable, etc.).
1N/AMake sure you don't put the type specifier (like C<$>) there, just
1N/Athe symbol names, like this:
1N/AUse C<~pattern> and C<!pattern> for positive and negative regexes.
1N/AThis is similar to calling the C<x> command on each applicable var.
1N/ASame as C<V currentpackage [vars]>.
1N/A=item y [level [vars]]
1N/ADisplay all (or some) lexical variables (mnemonic: C<mY> variables)
1N/Ain the current scope or I<level> scopes higher. You can limit the
1N/Avariables that you see with I<vars> which works exactly as it does
1N/Afor the C<V> and C<X> commands. Requires the C<PadWalker> module
1N/Aversion 0.08 or higher; will warn if this isn't installed. Output
1N/Ais pretty-printed in the same style as for C<V> and the format is
1N/Acontrolled by the same options.
1N/AProduce a stack backtrace. See below for details on its output.
1N/ASingle step. Executes until the beginning of another
1N/Astatement, descending into subroutine calls. If an expression is
1N/Asupplied that includes function calls, it too will be single-stepped.
1N/ANext. Executes over subroutine calls, until the beginning
1N/Aof the next statement. If an expression is supplied that includes
1N/Afunction calls, those functions will be executed with stops before
1N/AContinue until the return from the current subroutine.
1N/ADump the return value if the C<PrintRet> option is set (default).
1N/ARepeat last C<n> or C<s> command.
1N/AContinue, optionally inserting a one-time-only breakpoint
1N/Aat the specified line or subroutine.
1N/AList next window of lines.
1N/AList C<incr+1> lines starting at C<min>.
1N/AList lines C<min> through C<max>. C<l -> is synonymous to C<->.
1N/AList first window of lines from subroutine. I<subname> may
1N/Abe a variable that contains a code reference.
1N/AList previous window of lines.
1N/AView a few lines of code around the current line.
1N/AReturn the internal debugger pointer to the line last
1N/Aexecuted, and print out that line.
1N/ASwitch to viewing a different file or C<eval> statement. If I<filename>
1N/Ais not a full pathname found in the values of %INC, it is considered
1N/AC<eval>ed strings (when accessible) are considered to be filenames:
1N/AC<f (eval 7)> and C<f eval 7\b> access the body of the 7th C<eval>ed string
1N/A(in the order of execution). The bodies of the currently executed C<eval>
1N/Aand of C<eval>ed strings that define subroutines are saved and thus
1N/ASearch forwards for pattern (a Perl regex); final / is optional.
1N/AThe search is case-insensitive by default.
1N/ASearch backwards for pattern; final ? is optional.
1N/AThe search is case-insensitive by default.
1N/AList (default all) actions, breakpoints and watch expressions
1N/AList subroutine names [not] matching the regex.
1N/AToggle trace mode (see also the C<AutoTrace> option).
1N/ATrace through execution of C<expr>.
1N/ASee L<perldebguts/"Frame Listing Output Examples"> for examples.
1N/ASets breakpoint on current line
1N/A=item b [line] [condition]
1N/ASet a breakpoint before the given line. If a condition
1N/Ais specified, it's evaluated each time the statement is reached: a
1N/Abreakpoint is taken only if the condition is true. Breakpoints may
1N/Aonly be set on lines that begin an executable statement. Conditions
1N/A b 237 ++$count237 < 11
1N/A=item b subname [condition]
1N/ASet a breakpoint before the first line of the named subroutine. I<subname> may
1N/Abe a variable containing a code reference (in this case I<condition>
1N/A=item b postpone subname [condition]
1N/ASet a breakpoint at first line of subroutine after it is compiled.
1N/A=item b load filename
1N/ASet a breakpoint before the first executed line of the I<filename>,
1N/Awhich should be a full pathname found amongst the %INC values.
1N/A=item b compile subname
1N/ASets a breakpoint before the first statement executed after the specified
1N/Asubroutine is compiled.
1N/ADelete a breakpoint from the specified I<line>.
1N/ADelete all installed breakpoints.
1N/A=item a [line] command
1N/ASet an action to be done before the line is executed. If I<line> is
1N/Aomitted, set an action on the line about to be executed.
1N/AThe sequence of steps taken by the debugger is
1N/A 1. check for a breakpoint at this line
1N/A 2. print the line if necessary (tracing)
1N/A 3. do any actions associated with that line
1N/A 4. prompt user if at a breakpoint or in single-step
1N/AFor example, this will print out $foo every time line
1N/A a 53 print "DB FOUND $foo\n"
1N/ADelete an action from the specified line.
1N/ADelete all installed actions.
1N/AAdd a global watch-expression. We hope you know what one of these
1N/Ais, because they're supposed to be obvious.
1N/ADelete watch-expression
1N/ADelete all watch-expressions.
1N/A=item o booloption ...
1N/ASet each listed Boolean option to the value C<1>.
1N/A=item o anyoption? ...
1N/APrint out the value of one or more options.
1N/A=item o option=value ...
1N/ASet the value of one or more options. If the value has internal
1N/Awhitespace, it should be quoted. For example, you could set C<o
1N/Apager="less -MQeicsNfr"> to call B<less> with those specific options.
1N/AYou may use either single or double quotes, but if you do, you must
1N/Aescape any embedded instances of same sort of quote you began with,
1N/Aas well as any escaping any escapes that immediately precede that
1N/Aquote but which are not meant to escape the quote itself. In other
1N/Awords, you follow single-quoting rules irrespective of the quote;
1N/Aeg: C<o option='this isn\'t bad'> or C<o option="She said, \"Isn't
1N/AFor historical reasons, the C<=value> is optional, but defaults to
1N/A1 only where it is safe to do so--that is, mostly for Boolean
1N/Aoptions. It is always better to assign a specific value using C<=>.
1N/AThe C<option> can be abbreviated, but for clarity probably should
1N/Anot be. Several options can be set together. See L<"Configurable Options">
1N/AList out all pre-prompt Perl command actions.
1N/ASet an action (Perl command) to happen before every debugger prompt.
1N/AA multi-line command may be entered by backslashing the newlines.
1N/ADelete all pre-prompt Perl command actions.
1N/AAdd an action (Perl command) to happen before every debugger prompt.
1N/AA multi-line command may be entered by backwhacking the newlines.
1N/AList out post-prompt Perl command actions.
1N/ASet an action (Perl command) to happen after the prompt when you've
1N/Ajust given a command to return to executing the script. A multi-line
1N/Acommand may be entered by backslashing the newlines (we bet you
1N/Acouldn't've guessed this by now).
1N/ADelete all post-prompt Perl command actions.
1N/AAdds an action (Perl command) to happen after the prompt when you've
1N/Ajust given a command to return to executing the script. A multi-line
1N/Acommand may be entered by backslashing the newlines.
1N/AList out pre-prompt debugger commands.
1N/ASet an action (debugger command) to happen before every debugger prompt.
1N/AA multi-line command may be entered in the customary fashion.
1N/ABecause this command is in some senses new, a warning is issued if
1N/Ayou appear to have accidentally entered a block instead. If that's
1N/Awhat you mean to do, write it as with C<;{ ... }> or even
1N/ADelete all pre-prompt debugger commands.
1N/AAdd an action (debugger command) to happen before every debugger prompt.
1N/AA multi-line command may be entered, if you can guess how: see above.
1N/ARedo a previous command (defaults to the previous command).
1N/ARedo number'th previous command.
1N/ARedo last command that started with pattern.
1N/ASee C<o recallCommand>, too.
1N/ARun cmd in a subprocess (reads from DB::IN, writes to DB::OUT) See
1N/AC<o shellBang>, also. Note that the user's current shell (well,
1N/Atheir C<$ENV{SHELL}> variable) will be used, which can interfere
1N/Awith proper interpretation of exit status or signal and coredump
1N/ARead and execute debugger commands from I<file>.
1N/AI<file> may itself contain C<source> commands.
1N/ADisplay last n commands. Only commands longer than one character are
1N/Alisted. If I<number> is omitted, list them all.
1N/AQuit. ("quit" doesn't work for this, unless you've made an alias)
1N/AThis is the only supported way to exit the debugger, though typing
1N/AC<exit> twice might work.
1N/ASet the C<inhibit_exit> option to 0 if you want to be able to step
1N/Aoff the end the script. You may also need to set $finished to 0
1N/Aif you want to step through global destruction.
1N/ARestart the debugger by C<exec()>ing a new session. We try to maintain
1N/Ayour history across this, but internal settings and command-line options
1N/AThe following setting are currently preserved: history, breakpoints,
1N/Aactions, debugger options, and the Perl command-line
1N/Aoptions B<-w>, B<-I>, and B<-e>.
1N/ARun the debugger command, piping DB::OUT into your current pager.
1N/ASame as C<|dbcmd> but DB::OUT is temporarily C<select>ed as well.
1N/A=item = [alias value]
1N/ADefine a command alias, like
1N/Aor list current aliases.
1N/AExecute command as a Perl statement. A trailing semicolon will be
1N/Asupplied. If the Perl statement would otherwise be confused for a
1N/APerl debugger, use a leading semicolon, too.
1N/AList which methods may be called on the result of the evaluated
1N/Aexpression. The expression may evaluated to a reference to a
1N/Ablessed object, or to a package name.
1N/ADisplays all loaded modules and their versions
1N/ADespite its name, this calls your system's default documentation
1N/Aviewer on the given page, or on the viewer itself if I<manpage> is
1N/Aomitted. If that viewer is B<man>, the current C<Config> information
1N/Ais used to invoke B<man> using the proper MANPATH or S<B<-M>
1N/AI<manpath>> option. Failed lookups of the form C<XXX> that match
1N/Aknown manpages of the form I<perlXXX> will be retried. This lets
1N/Ayou type C<man debug> or C<man op> from the debugger.
1N/AOn systems traditionally bereft of a usable B<man> command, the
1N/Adebugger invokes B<perldoc>. Occasionally this determination is
1N/Aincorrect due to recalcitrant vendors or rather more felicitously,
1N/Ato enterprising users. If you fall into either category, just
1N/Amanually set the $DB::doccmd variable to whatever viewer to view
1N/Athe Perl documentation on your system. This may be set in an rc
1N/Afile, or through direct assignment. We're still waiting for a
1N/Aworking example of something along the lines of:
1N/A=head2 Configurable Options
1N/AThe debugger has numerous options settable using the C<o> command,
1N/Aeither interactively or from the environment or an rc file.
1N/A(./.perldb or ~/.perldb under Unix.)
1N/A=item C<recallCommand>, C<ShellBang>
1N/AThe characters used to recall command or spawn shell. By
1N/Adefault, both are set to C<!>, which is unfortunate.
1N/AProgram to use for output of pager-piped commands (those beginning
1N/Awith a C<|> character.) By default, C<$ENV{PAGER}> will be used.
1N/ABecause the debugger uses your current terminal characteristics
1N/Afor bold and underlining, if the chosen pager does not pass escape
1N/Asequences through unchanged, the output of some debugger commands
1N/Awill not be readable when sent through the pager.
1N/ARun Tk while prompting (with ReadLine).
1N/A=item C<signalLevel>, C<warnLevel>, C<dieLevel>
1N/ALevel of verbosity. By default, the debugger leaves your exceptions
1N/Aand warnings alone, because altering them can break correctly running
1N/Aprograms. It will attempt to print a message when uncaught INT, BUS, or
1N/ASEGV signals arrive. (But see the mention of signals in L<BUGS> below.)
1N/ATo disable this default safe mode, set these values to something higher
1N/Athan 0. At a level of 1, you get backtraces upon receiving any kind
1N/Aof warning (this is often annoying) or exception (this is
1N/Aoften valuable). Unfortunately, the debugger cannot discern fatal
1N/Aexceptions from non-fatal ones. If C<dieLevel> is even 1, then your
1N/Anon-fatal exceptions are also traced and unceremoniously altered if they
1N/Acame from C<eval'd> strings or from any kind of C<eval> within modules
1N/Ayou're attempting to load. If C<dieLevel> is 2, the debugger doesn't
1N/Acare where they came from: It usurps your exception handler and prints
1N/Aout a trace, then modifies all exceptions with its own embellishments.
1N/AThis may perhaps be useful for some tracing purposes, but tends to hopelessly
1N/Adestroy any program that takes its exception handling seriously.
1N/ATrace mode (similar to C<t> command, but can be put into
1N/AFile or pipe to print line number info to. If it is a pipe (say,
1N/AC<|visual_perl_db>), then a short message is used. This is the
1N/Amechanism used to interact with a slave editor or visual debugger,
1N/Asuch as the special C<vi> or C<emacs> hooks, or the C<ddd> graphical
1N/A=item C<inhibit_exit>
1N/AIf 0, allows I<stepping off> the end of the script.
1N/APrint return value after C<r> command if set (default).
1N/AAffects screen appearance of the command line (see L<Term::ReadLine>).
1N/AThere is currently no way to disable these, which can render
1N/Asome output illegible on some displays, or with some pagers.
1N/AThis is considered a bug.
1N/AAffects the printing of messages upon entry and exit from subroutines. If
1N/AC<frame & 2> is false, messages are printed on entry only. (Printing
1N/Aon exit might be useful if interspersed with other messages.)
1N/AIf C<frame & 4>, arguments to functions are printed, plus context
1N/Aand caller info. If C<frame & 8>, overloaded C<stringify> and
1N/AC<tie>d C<FETCH> is enabled on the printed arguments. If C<frame
1N/A& 16>, the return value from the subroutine is printed.
1N/AThe length at which the argument list is truncated is governed by the
1N/ALength to truncate the argument list when the C<frame> option's
1N/AChange the size of code list window (default is 10 lines).
1N/AThe following options affect what happens with C<V>, C<X>, and C<x>
1N/A=item C<arrayDepth>, C<hashDepth>
1N/APrint only first N elements ('' for all).
1N/ALimit recursion depth to N levels when dumping structures.
1N/ANegative values are interpreted as infinity. Default: infinity.
1N/A=item C<compactDump>, C<veryCompact>
1N/AChange the style of array and hash output. If C<compactDump>, short array
1N/Amay be printed on one line.
1N/AWhether to print contents of globs.
1N/ADump arrays holding debugged files.
1N/A=item C<DumpPackages>
1N/ADump symbol tables of packages.
1N/ADump contents of "reused" addresses.
1N/A=item C<quote>, C<HighBit>, C<undefPrint>
1N/AChange the style of string dump. The default value for C<quote>
1N/Ais C<auto>; one can enable double-quotish or single-quotish format
1N/Aby setting it to C<"> or C<'>, respectively. By default, characters
1N/Awith their high bit set are printed verbatim.
1N/ARudimentary per-package memory usage dump. Calculates total
1N/Asize of strings found in variables in the package. This does not
1N/Ainclude lexicals in a module's file scope, or lost in closures.
1N/AAfter the rc file is read, the debugger reads the C<$ENV{PERLDB_OPTS}>
1N/Aenvironment variable and parses this as the remainder of a `O ...'
1N/Aline as one might enter at the debugger prompt. You may place the
1N/Ainitialization options C<TTY>, C<noTTY>, C<ReadLine>, and C<NonStop>
1N/AIf your rc file contains:
1N/A parse_options("NonStop=1 LineInfo=
db.out AutoTrace");
1N/Athen your script will run without human intervention, putting trace
1N/Ainformation into the file I<
db.out>. (If you interrupt it, you'd
1N/Abetter reset C<LineInfo> to F<
/dev/tty> if you expect to see anything.)
1N/AThe TTY to use for debugging I/O.
1N/AIf set, the debugger goes into C<NonStop> mode and will not connect to a TTY. If
1N/Ainterrupted (or if control goes to the debugger via explicit setting of
1N/A$DB::signal or $DB::single from the Perl script), it connects to a TTY
1N/Aspecified in the C<TTY> option at startup, or to a tty found at
1N/Aruntime using the C<Term::Rendezvous> module of your choice.
1N/AThis module should implement a method named C<new> that returns an object
1N/Awith two methods: C<IN> and C<OUT>. These should return filehandles to use
1N/Afor debugging input and output correspondingly. The C<new> method should
1N/Ainspect an argument containing the value of C<$ENV{PERLDB_NOTTY}> at
1N/Astartup, or C<".perldbtty$$"> otherwise. This file is not
1N/Ainspected for proper ownership, so security hazards are theoretically
1N/AIf false, readline support in the debugger is disabled in order
1N/Ato debug applications that themselves use ReadLine.
1N/AIf set, the debugger goes into non-interactive mode until interrupted, or
1N/Aprogrammatically by setting $DB::signal or $DB::single.
1N/AHere's an example of using the C<$ENV{PERLDB_OPTS}> variable:
1N/A $ PERLDB_OPTS="NonStop frame=2" perl -d myprogram
1N/AThat will run the script B<myprogram> without human intervention,
1N/Aprinting out the call tree with entry and exit points. Note that
1N/AC<NonStop=1 frame=2> is equivalent to C<N f=2>, and that originally,
1N/Aoptions could be uniquely abbreviated by the first letter (modulo
1N/Athe C<Dump*> options). It is nevertheless recommended that you
1N/Aalways spell them out in full for legibility and future compatibility.
1N/AOther examples include
1N/A $ PERLDB_OPTS="NonStop LineInfo=listing frame=2" perl -d myprogram
1N/Awhich runs script non-interactively, printing info on each entry
1N/Ainto a subroutine and each executed line into the file named F<listing>.
1N/A(If you interrupt it, you would better reset C<LineInfo> to something
1N/AOther examples include (using standard shell syntax to show environment
1N/A $ ( PERLDB_OPTS="NonStop frame=1 AutoTrace LineInfo=
tperl.out"
1N/Awhich may be useful for debugging a program that uses C<Term::ReadLine>
1N/Aitself. Do not forget to detach your shell from the TTY in the window that
1N/ASee L<perldebguts/"Debugger Internals"> for details.
1N/AThe debugger prompt is something like
1N/Awhere that number is the command number, and which you'd use to
1N/Aaccess with the built-in B<csh>-like history mechanism. For example,
1N/AC<!17> would repeat command number 17. The depth of the angle
1N/Abrackets indicates the nesting depth of the debugger. You could
1N/Aget more than one set of brackets, for example, if you'd already
1N/Aat a breakpoint and then printed the result of a function call that
1N/Aitself has a breakpoint, or you step into an expression via C<s/n/t
1N/A=item Multiline commands
1N/AIf you want to enter a multi-line command, such as a subroutine
1N/Adefinition with several statements or a format, escape the newline
1N/Athat would normally end the debugger command with a backslash.
1N/A DB<1> for (1..4) { \
1N/A cont: print "ok\n"; \
1N/ANote that this business of escaping a newline is specific to interactive
1N/Acommands typed into the debugger.
1N/A=item Stack backtrace
1N/AHere's an example of what a stack backtrace via C<T> command might
1N/A @ = Ambulation::legs(1, 2, 3, 4) called from file `camel_flea' line 7
1N/A $ = main::pests('bactrian', 4) called from file `camel_flea' line 4
1N/AThe left-hand character up there indicates the context in which the
1N/Afunction was called, with C<$> and C<@> meaning scalar or list
1N/Acontexts respectively, and C<.> meaning void context (which is
1N/Aactually a sort of scalar context). The display above says
1N/Athat you were in the function C<main::infested> when you ran the
1N/Astack dump, and that it was called in scalar context from line
1N/Ameaning it was called as C<&infested>. The next stack frame shows
1N/Athat the function C<Ambulation::legs> was called in list context
1N/Afrom the I<camel_flea> file with four arguments. The last stack
1N/Aframe shows that C<main::pests> was called in scalar context,
1N/Aalso from I<camel_flea>, but from line 4.
1N/AIf you execute the C<T> command from inside an active C<use>
1N/Astatement, the backtrace will contain both a C<require> frame and
1N/A=item Line Listing Format
1N/AThis shows the sorts of output the C<l> command can produce:
1N/A 102:b @isa{@i,$pack} = ()
1N/A 103 if(exists $i{$prevpack} || exists $isa{$pack});
1N/A 107==> if(exists $isa{$pack});
1N/A 109:a if ($extra-- > 0) {
1N/A 110: %isa = ($pack,1);
1N/ABreakable lines are marked with C<:>. Lines with breakpoints are
1N/Amarked by C<b> and those with actions by C<a>. The line that's
1N/Aabout to be executed is marked by C<< ==> >>.
1N/APlease be aware that code in debugger listings may not look the same
1N/Aas your original source code. Line directives and external source
1N/Afilters can alter the code before Perl sees it, causing code to move
1N/Afrom its original positions or take on entirely different forms.
1N/AWhen the C<frame> option is set, the debugger would print entered (and
1N/Aoptionally exited) subroutines in different styles. See L<perldebguts>
1N/Afor incredibly long examples of these.
1N/A=head2 Debugging compile-time statements
1N/AIf you have compile-time executable statements (such as code within
1N/ABEGIN and CHECK blocks or C<use> statements), these will I<not> be
1N/Astopped by debugger, although C<require>s and INIT blocks will, and
1N/Acompile-time statements can be traced with C<AutoTrace> option set
1N/Ain C<PERLDB_OPTS>). From your own Perl code, however, you can
1N/Atransfer control back to the debugger using the following statement,
1N/Awhich is harmless if the debugger is not running:
1N/AIf you set C<$DB::single> to 2, it's equivalent to having
1N/Ajust typed the C<n> command, whereas a value of 1 means the C<s>
1N/Acommand. The C<$DB::trace> variable should be set to 1 to simulate
1N/Ahaving typed the C<t> command.
1N/AAnother way to debug compile-time code is to start the debugger, set a
1N/Abreakpoint on the I<load> of some module:
1N/Aand then restart the debugger using the C<R> command (if possible). One can use C<b
1N/Acompile subname> for the same purpose.
1N/A=head2 Debugger Customization
1N/AThe debugger probably contains enough configuration hooks that you
1N/Awon't ever have to modify it yourself. You may change the behaviour
1N/Aof debugger from within the debugger using its C<o> command, from
1N/Athe command line via the C<PERLDB_OPTS> environment variable, and
1N/Afrom customization files.
1N/AYou can do some customization by setting up a F<.perldb> file, which
1N/Acontains initialization code. For instance, you could make aliases
1N/Alike these (the last one is one people expect to be there):
1N/A $DB::alias{'len'} = 's/^len(.*)/p length($1)/';
1N/A $DB::alias{'stop'} = 's/^stop (at|in)/b/';
1N/A $DB::alias{'ps'} = 's/^ps\b/p scalar /';
1N/A $DB::alias{'quit'} = 's/^quit(\s*)/exit/';
1N/AYou can change options from F<.perldb> by using calls like this one;
1N/A parse_options("NonStop=1 LineInfo=
db.out AutoTrace=1 frame=2");
1N/AThe code is executed in the package C<DB>. Note that F<.perldb> is
1N/Aprocessed before processing C<PERLDB_OPTS>. If F<.perldb> defines the
1N/Asubroutine C<afterinit>, that function is called after debugger
1N/Ainitialization ends. F<.perldb> may be contained in the current
1N/Adirectory, or in the home directory. Because this file is sourced
1N/Ain by Perl and may contain arbitrary commands, for security reasons,
1N/Ait must be owned by the superuser or the current user, and writable
1N/Aby no one but its owner.
1N/AYou can mock TTY input to debugger by adding arbitrary commands to
1N/A@DB::typeahead. For example, your F<.perldb> file might contain:
1N/A sub afterinit { push @DB::typeahead, "b 4", "b 6"; }
1N/AWhich would attempt to set breakpoints on lines 4 and 6 immediately
1N/Aafter debugger initilization. Note that @DB::typeahead is not a supported
1N/Ainterface and is subject to change in future releases.
1N/APerl library to another name and hack it to your heart's content.
1N/AYou'll then want to set your C<PERL5DB> environment variable to say
1N/AAs a last resort, you could also use C<PERL5DB> to customize the debugger
1N/Aby directly setting internal variables or calling debugger functions.
1N/ANote that any variables and functions that are not documented in
1N/Athis document (or in L<perldebguts>) are considered for internal
1N/Ause only, and as such are subject to change without notice.
1N/A=head2 Readline Support
1N/AAs shipped, the only command-line history supplied is a simplistic one
1N/Athat checks for leading exclamation points. However, if you install
1N/Athe Term::ReadKey and Term::ReadLine modules from CPAN, you will
1N/Ahave full editing capabilities much like GNU I<readline>(3) provides.
1N/AThese do not support normal B<vi> command-line editing, however.
1N/AA rudimentary command-line completion is also available.
1N/AUnfortunately, the names of lexical variables are not available for
1N/A=head2 Editor Support for Debugging
1N/AIf you have the FSF's version of B<emacs> installed on your system,
1N/Ait can interact with the Perl debugger to provide an integrated
1N/Asoftware development environment reminiscent of its interactions
1N/APerl comes with a start file for making B<emacs> act like a
1N/Asyntax-directed editor that understands (some of) Perl's syntax.
1N/ALook in the I<emacs> directory of the Perl source distribution.
1N/AA similar setup by Tom Christiansen for interacting with any
1N/Avendor-shipped B<vi> and the X11 window system is also available.
1N/AThis works similarly to the integrated multiwindow support that
1N/AB<emacs> provides, where the debugger drives the editor. At the
1N/Atime of this writing, however, that tool's eventual location in the
1N/APerl distribution was uncertain.
1N/AUsers of B<vi> should also look into B<vim> and B<gvim>, the mousey
1N/Aand windy version, for coloring of Perl keywords.
1N/ANote that only perl can truly parse Perl, so all such CASE tools
1N/Afall somewhat short of the mark, especially if you don't program
1N/Ayour Perl as a C programmer might.
1N/A=head2 The Perl Profiler
1N/AIf you wish to supply an alternative debugger for Perl to run, just
1N/Ainvoke your script with a colon and a package argument given to the
1N/AB<-d> flag. The most popular alternative debuggers for Perl is the
1N/APerl profiler. Devel::DProf is now included with the standard Perl
1N/Adistribution. To profile your Perl program in the file F<
mycode.pl>,
1N/AWhen the script terminates the profiler will dump the profile
1N/Ainformation to a file called F<
tmon.out>. A tool like B<dprofpp>,
1N/Aalso supplied with the standard Perl distribution, can be used to
1N/Ainterpret the information in that profile.
1N/A=head1 Debugging regular expressions
1N/AC<use re 'debug'> enables you to see the gory details of how the Perl
1N/Aregular expression engine works. In order to understand this typically
1N/Avoluminous output, one must not only have some idea about how regular
1N/Aexpression matching works in general, but also know how Perl's regular
1N/Aexpressions are internally compiled into an automaton. These matters
1N/Aare explored in some detail in
1N/AL<perldebguts/"Debugging regular expressions">.
1N/A=head1 Debugging memory usage
1N/APerl contains internal support for reporting its own memory usage,
1N/Abut this is a fairly advanced concept that requires some understanding
1N/Aof how memory allocation works.
1N/ASee L<perldebguts/"Debugging Perl memory usage"> for the details.
1N/AYou did try the B<-w> switch, didn't you?
1N/AYou cannot get stack frame information or in any fashion debug functions
1N/Athat were not compiled by Perl, such as those from C or C++ extensions.
1N/AIf you alter your @_ arguments in a subroutine (such as with C<shift>
1N/Aor C<pop>), the stack backtrace will not show the original values.
1N/AThe debugger does not currently work in conjunction with the B<-W>
1N/Acommand-line switch, because it itself is not free of warnings.
1N/AIf you're in a slow syscall (like C<wait>ing, C<accept>ing, or C<read>ing
1N/Afrom your keyboard or a socket) and haven't set up your own C<$SIG{INT}>
1N/Ahandler, then you won't be able to CTRL-C your way back to the debugger,
1N/Abecause the debugger's own C<$SIG{INT}> handler doesn't understand that
1N/Ait needs to raise an exception to longjmp(3) out of slow syscalls.