diff options
Diffstat (limited to 'Master/tlpkg/tlperl0/lib/pods/perldebug.pod')
| -rwxr-xr-x | Master/tlpkg/tlperl0/lib/pods/perldebug.pod | 1174 |
1 files changed, 1174 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl0/lib/pods/perldebug.pod b/Master/tlpkg/tlperl0/lib/pods/perldebug.pod new file mode 100755 index 00000000000..c37c5cfbb2c --- /dev/null +++ b/Master/tlpkg/tlperl0/lib/pods/perldebug.pod @@ -0,0 +1,1174 @@ +=head1 NAME +X<debug> X<debugger> + +perldebug - Perl debugging + +=head1 DESCRIPTION + +First of all, have you tried using the B<-w> switch? + + +If you're new to the Perl debugger, you may prefer to read +L<perldebtut>, which is a tutorial introduction to the debugger . + +=head1 The Perl Debugger + +If you invoke Perl with the B<-d> switch, your script runs under the +Perl source debugger. This works like an interactive Perl +environment, prompting for debugger commands that let you examine +source code, set breakpoints, get stack backtraces, change the values of +variables, etc. This is so convenient that you often fire up +the debugger all by itself just to test out Perl constructs +interactively to see what they do. For example: +X<-d> + + $ perl -d -e 42 + +In Perl, the debugger is not a separate program the way it usually is in the +typical compiled environment. Instead, the B<-d> flag tells the compiler +to insert source information into the parse trees it's about to hand off +to the interpreter. That means your code must first compile correctly +for the debugger to work on it. Then when the interpreter starts up, it +preloads a special Perl library file containing the debugger. + +The program will halt I<right before> the first run-time executable +statement (but see below regarding compile-time statements) and ask you +to enter a debugger command. Contrary to popular expectations, whenever +the debugger halts and shows you a line of code, it always displays the +line it's I<about> to execute, rather than the one it has just executed. + +Any command not recognized by the debugger is directly executed +(C<eval>'d) as Perl code in the current package. (The debugger +uses the DB package for keeping its own state information.) + +Note that the said C<eval> is bound by an implicit scope. As a +result any newly introduced lexical variable or any modified +capture buffer content is lost after the eval. The debugger is a +nice environment to learn Perl, but if you interactively experiment using +material which should be in the same scope, stuff it in one line. + +For any text entered at the debugger prompt, leading and trailing whitespace +is first stripped before further processing. If a debugger command +coincides with some function in your own program, merely precede the +function with something that doesn't look like a debugger command, such +as a leading C<;> or perhaps a C<+>, or by wrapping it with parentheses +or braces. + +=head2 Calling the debugger + +There are several ways to call the debugger: + +=over 4 + +=item perl -d program_name + +On the given program identified by C<program_name>. + +=item perl -d -e 0 + +Interactively supply an arbitrary C<expression> using C<-e>. + +=item perl -d:Ptkdb program_name + +Debug a given program via the C<Devel::Ptkdb> GUI. + +=item perl -dt threaded_program_name + +Debug a given program using threads (experimental). + +=back + +=head2 Debugger Commands + +The interactive debugger understands the following commands: + +=over 12 + +=item h +X<debugger command, h> + +Prints out a summary help message + +=item h [command] + +Prints out a help message for the given debugger command. + +=item h h + +The special argument of C<h h> produces the entire help page, which is quite long. + +If the output of the C<h h> command (or any command, for that matter) scrolls +past your screen, precede the command with a leading pipe symbol so +that it's run through your pager, as in + + DB> |h h + +You may change the pager which is used via C<o pager=...> command. + + +=item p expr +X<debugger command, p> + +Same as C<print {$DB::OUT} expr> in the current package. In particular, +because this is just Perl's own C<print> function, this means that nested +data structures and objects are not dumped, unlike with the C<x> command. + +The C<DB::OUT> filehandle is opened to F</dev/tty>, regardless of +where STDOUT may be redirected to. + +=item x [maxdepth] expr +X<debugger command, x> + +Evaluates its expression in list context and dumps out the result in a +pretty-printed fashion. Nested data structures are printed out +recursively, unlike the real C<print> function in Perl. When dumping +hashes, you'll probably prefer 'x \%h' rather than 'x %h'. +See L<Dumpvalue> if you'd like to do this yourself. + +The output format is governed by multiple options described under +L<"Configurable Options">. + +If the C<maxdepth> is included, it must be a numeral I<N>; the value is +dumped only I<N> levels deep, as if the C<dumpDepth> option had been +temporarily set to I<N>. + +=item V [pkg [vars]] +X<debugger command, V> + +Display all (or some) variables in package (defaulting to C<main>) +using a data pretty-printer (hashes show their keys and values so +you see what's what, control characters are made printable, etc.). +Make sure you don't put the type specifier (like C<$>) there, just +the symbol names, like this: + + V DB filename line + +Use C<~pattern> and C<!pattern> for positive and negative regexes. + +This is similar to calling the C<x> command on each applicable var. + +=item X [vars] +X<debugger command, X> + +Same as C<V currentpackage [vars]>. + +=item y [level [vars]] +X<debugger command, y> + +Display all (or some) lexical variables (mnemonic: C<mY> variables) +in the current scope or I<level> scopes higher. You can limit the +variables that you see with I<vars> which works exactly as it does +for the C<V> and C<X> commands. Requires the C<PadWalker> module +version 0.08 or higher; will warn if this isn't installed. Output +is pretty-printed in the same style as for C<V> and the format is +controlled by the same options. + +=item T +X<debugger command, T> X<backtrace> X<stack, backtrace> + +Produce a stack backtrace. See below for details on its output. + +=item s [expr] +X<debugger command, s> X<step> + +Single step. Executes until the beginning of another +statement, descending into subroutine calls. If an expression is +supplied that includes function calls, it too will be single-stepped. + +=item n [expr] +X<debugger command, n> + +Next. Executes over subroutine calls, until the beginning +of the next statement. If an expression is supplied that includes +function calls, those functions will be executed with stops before +each statement. + +=item r +X<debugger command, r> + +Continue until the return from the current subroutine. +Dump the return value if the C<PrintRet> option is set (default). + +=item <CR> + +Repeat last C<n> or C<s> command. + +=item c [line|sub] +X<debugger command, c> + +Continue, optionally inserting a one-time-only breakpoint +at the specified line or subroutine. + +=item l +X<debugger command, l> + +List next window of lines. + +=item l min+incr + +List C<incr+1> lines starting at C<min>. + +=item l min-max + +List lines C<min> through C<max>. C<l -> is synonymous to C<->. + +=item l line + +List a single line. + +=item l subname + +List first window of lines from subroutine. I<subname> may +be a variable that contains a code reference. + +=item - +X<debugger command, -> + +List previous window of lines. + +=item v [line] +X<debugger command, v> + +View a few lines of code around the current line. + +=item . +X<debugger command, .> + +Return the internal debugger pointer to the line last +executed, and print out that line. + +=item f filename +X<debugger command, f> + +Switch to viewing a different file or C<eval> statement. If I<filename> +is not a full pathname found in the values of %INC, it is considered +a regex. + +C<eval>ed strings (when accessible) are considered to be filenames: +C<f (eval 7)> and C<f eval 7\b> access the body of the 7th C<eval>ed string +(in the order of execution). The bodies of the currently executed C<eval> +and of C<eval>ed strings that define subroutines are saved and thus +accessible. + +=item /pattern/ + +Search forwards for pattern (a Perl regex); final / is optional. +The search is case-insensitive by default. + +=item ?pattern? + +Search backwards for pattern; final ? is optional. +The search is case-insensitive by default. + +=item L [abw] +X<debugger command, L> + +List (default all) actions, breakpoints and watch expressions + +=item S [[!]regex] +X<debugger command, S> + +List subroutine names [not] matching the regex. + +=item t +X<debugger command, t> + +Toggle trace mode (see also the C<AutoTrace> option). + +=item t expr +X<debugger command, t> + +Trace through execution of C<expr>. +See L<perldebguts/"Frame Listing Output Examples"> for examples. + +=item b +X<breakpoint> +X<debugger command, b> + +Sets breakpoint on current line + +=item b [line] [condition] +X<breakpoint> +X<debugger command, b> + +Set a breakpoint before the given line. If a condition +is specified, it's evaluated each time the statement is reached: a +breakpoint is taken only if the condition is true. Breakpoints may +only be set on lines that begin an executable statement. Conditions +don't use C<if>: + + b 237 $x > 30 + b 237 ++$count237 < 11 + b 33 /pattern/i + +=item b subname [condition] +X<breakpoint> +X<debugger command, b> + +Set a breakpoint before the first line of the named subroutine. I<subname> may +be a variable containing a code reference (in this case I<condition> +is not supported). + +=item b postpone subname [condition] +X<breakpoint> +X<debugger command, b> + +Set a breakpoint at first line of subroutine after it is compiled. + +=item b load filename +X<breakpoint> +X<debugger command, b> + +Set a breakpoint before the first executed line of the I<filename>, +which should be a full pathname found amongst the %INC values. + +=item b compile subname +X<breakpoint> +X<debugger command, b> + +Sets a breakpoint before the first statement executed after the specified +subroutine is compiled. + +=item B line +X<breakpoint> +X<debugger command, B> + +Delete a breakpoint from the specified I<line>. + +=item B * +X<breakpoint> +X<debugger command, B> + +Delete all installed breakpoints. + +=item a [line] command +X<debugger command, a> + +Set an action to be done before the line is executed. If I<line> is +omitted, set an action on the line about to be executed. +The sequence of steps taken by the debugger is + + 1. check for a breakpoint at this line + 2. print the line if necessary (tracing) + 3. do any actions associated with that line + 4. prompt user if at a breakpoint or in single-step + 5. evaluate line + +For example, this will print out $foo every time line +53 is passed: + + a 53 print "DB FOUND $foo\n" + +=item A line +X<debugger command, A> + +Delete an action from the specified line. + +=item A * +X<debugger command, A> + +Delete all installed actions. + +=item w expr +X<debugger command, w> + +Add a global watch-expression. Whenever a watched global changes the +debugger will stop and display the old and new values. + +=item W expr +X<debugger command, W> + +Delete watch-expression + +=item W * +X<debugger command, W> + +Delete all watch-expressions. + +=item o +X<debugger command, o> + +Display all options + +=item o booloption ... +X<debugger command, o> + +Set each listed Boolean option to the value C<1>. + +=item o anyoption? ... +X<debugger command, o> + +Print out the value of one or more options. + +=item o option=value ... +X<debugger command, o> + +Set the value of one or more options. If the value has internal +whitespace, it should be quoted. For example, you could set C<o +pager="less -MQeicsNfr"> to call B<less> with those specific options. +You may use either single or double quotes, but if you do, you must +escape any embedded instances of same sort of quote you began with, +as well as any escaping any escapes that immediately precede that +quote but which are not meant to escape the quote itself. In other +words, you follow single-quoting rules irrespective of the quote; +eg: C<o option='this isn\'t bad'> or C<o option="She said, \"Isn't +it?\"">. + +For historical reasons, the C<=value> is optional, but defaults to +1 only where it is safe to do so--that is, mostly for Boolean +options. It is always better to assign a specific value using C<=>. +The C<option> can be abbreviated, but for clarity probably should +not be. Several options can be set together. See L<"Configurable Options"> +for a list of these. + +=item < ? +X<< debugger command, < >> + +List out all pre-prompt Perl command actions. + +=item < [ command ] +X<< debugger command, < >> + +Set an action (Perl command) to happen before every debugger prompt. +A multi-line command may be entered by backslashing the newlines. + +=item < * +X<< debugger command, < >> + +Delete all pre-prompt Perl command actions. + +=item << command +X<< debugger command, << >> + +Add an action (Perl command) to happen before every debugger prompt. +A multi-line command may be entered by backwhacking the newlines. + +=item > ? +X<< debugger command, > >> + +List out post-prompt Perl command actions. + +=item > command +X<< debugger command, > >> + +Set an action (Perl command) to happen after the prompt when you've +just given a command to return to executing the script. A multi-line +command may be entered by backslashing the newlines (we bet you +couldn't have guessed this by now). + +=item > * +X<< debugger command, > >> + +Delete all post-prompt Perl command actions. + +=item >> command +X<<< debugger command, >> >>> + +Adds an action (Perl command) to happen after the prompt when you've +just given a command to return to executing the script. A multi-line +command may be entered by backslashing the newlines. + +=item { ? +X<debugger command, {> + +List out pre-prompt debugger commands. + +=item { [ command ] + +Set an action (debugger command) to happen before every debugger prompt. +A multi-line command may be entered in the customary fashion. + +Because this command is in some senses new, a warning is issued if +you appear to have accidentally entered a block instead. If that's +what you mean to do, write it as with C<;{ ... }> or even +C<do { ... }>. + +=item { * +X<debugger command, {> + +Delete all pre-prompt debugger commands. + +=item {{ command +X<debugger command, {{> + +Add an action (debugger command) to happen before every debugger prompt. +A multi-line command may be entered, if you can guess how: see above. + +=item ! number +X<debugger command, !> + +Redo a previous command (defaults to the previous command). + +=item ! -number +X<debugger command, !> + +Redo number'th previous command. + +=item ! pattern +X<debugger command, !> + +Redo last command that started with pattern. +See C<o recallCommand>, too. + +=item !! cmd +X<debugger command, !!> + +Run cmd in a subprocess (reads from DB::IN, writes to DB::OUT) See +C<o shellBang>, also. Note that the user's current shell (well, +their C<$ENV{SHELL}> variable) will be used, which can interfere +with proper interpretation of exit status or signal and coredump +information. + +=item source file +X<debugger command, source> + +Read and execute debugger commands from I<file>. +I<file> may itself contain C<source> commands. + +=item H -number +X<debugger command, H> + +Display last n commands. Only commands longer than one character are +listed. If I<number> is omitted, list them all. + +=item q or ^D +X<debugger command, q> +X<debugger command, ^D> + +Quit. ("quit" doesn't work for this, unless you've made an alias) +This is the only supported way to exit the debugger, though typing +C<exit> twice might work. + +Set the C<inhibit_exit> option to 0 if you want to be able to step +off the end the script. You may also need to set $finished to 0 +if you want to step through global destruction. + +=item R +X<debugger command, R> + +Restart the debugger by C<exec()>ing a new session. We try to maintain +your history across this, but internal settings and command-line options +may be lost. + +The following setting are currently preserved: history, breakpoints, +actions, debugger options, and the Perl command-line +options B<-w>, B<-I>, and B<-e>. + +=item |dbcmd +X<debugger command, |> + +Run the debugger command, piping DB::OUT into your current pager. + +=item ||dbcmd +X<debugger command, ||> + +Same as C<|dbcmd> but DB::OUT is temporarily C<select>ed as well. + +=item = [alias value] +X<debugger command, => + +Define a command alias, like + + = quit q + +or list current aliases. + +=item command + +Execute command as a Perl statement. A trailing semicolon will be +supplied. If the Perl statement would otherwise be confused for a +Perl debugger, use a leading semicolon, too. + +=item m expr +X<debugger command, m> + +List which methods may be called on the result of the evaluated +expression. The expression may evaluated to a reference to a +blessed object, or to a package name. + +=item M +X<debugger command, M> + +Displays all loaded modules and their versions + + +=item man [manpage] +X<debugger command, man> + +Despite its name, this calls your system's default documentation +viewer on the given page, or on the viewer itself if I<manpage> is +omitted. If that viewer is B<man>, the current C<Config> information +is used to invoke B<man> using the proper MANPATH or S<B<-M> +I<manpath>> option. Failed lookups of the form C<XXX> that match +known manpages of the form I<perlXXX> will be retried. This lets +you type C<man debug> or C<man op> from the debugger. + +On systems traditionally bereft of a usable B<man> command, the +debugger invokes B<perldoc>. Occasionally this determination is +incorrect due to recalcitrant vendors or rather more felicitously, +to enterprising users. If you fall into either category, just +manually set the $DB::doccmd variable to whatever viewer to view +the Perl documentation on your system. This may be set in an rc +file, or through direct assignment. We're still waiting for a +working example of something along the lines of: + + $DB::doccmd = 'netscape -remote http://something.here/'; + +=back + +=head2 Configurable Options + +The debugger has numerous options settable using the C<o> command, +either interactively or from the environment or an rc file. +(./.perldb or ~/.perldb under Unix.) + + +=over 12 + +=item C<recallCommand>, C<ShellBang> +X<debugger option, recallCommand> +X<debugger option, ShellBang> + +The characters used to recall command or spawn shell. By +default, both are set to C<!>, which is unfortunate. + +=item C<pager> +X<debugger option, pager> + +Program to use for output of pager-piped commands (those beginning +with a C<|> character.) By default, C<$ENV{PAGER}> will be used. +Because the debugger uses your current terminal characteristics +for bold and underlining, if the chosen pager does not pass escape +sequences through unchanged, the output of some debugger commands +will not be readable when sent through the pager. + +=item C<tkRunning> +X<debugger option, tkRunning> + +Run Tk while prompting (with ReadLine). + +=item C<signalLevel>, C<warnLevel>, C<dieLevel> +X<debugger option, signalLevel> X<debugger option, warnLevel> +X<debugger option, dieLevel> + +Level of verbosity. By default, the debugger leaves your exceptions +and warnings alone, because altering them can break correctly running +programs. It will attempt to print a message when uncaught INT, BUS, or +SEGV signals arrive. (But see the mention of signals in L<BUGS> below.) + +To disable this default safe mode, set these values to something higher +than 0. At a level of 1, you get backtraces upon receiving any kind +of warning (this is often annoying) or exception (this is +often valuable). Unfortunately, the debugger cannot discern fatal +exceptions from non-fatal ones. If C<dieLevel> is even 1, then your +non-fatal exceptions are also traced and unceremoniously altered if they +came from C<eval'ed> strings or from any kind of C<eval> within modules +you're attempting to load. If C<dieLevel> is 2, the debugger doesn't +care where they came from: It usurps your exception handler and prints +out a trace, then modifies all exceptions with its own embellishments. +This may perhaps be useful for some tracing purposes, but tends to hopelessly +destroy any program that takes its exception handling seriously. + +=item C<AutoTrace> +X<debugger option, AutoTrace> + +Trace mode (similar to C<t> command, but can be put into +C<PERLDB_OPTS>). + +=item C<LineInfo> +X<debugger option, LineInfo> + +File or pipe to print line number info to. If it is a pipe (say, +C<|visual_perl_db>), then a short message is used. This is the +mechanism used to interact with a slave editor or visual debugger, +such as the special C<vi> or C<emacs> hooks, or the C<ddd> graphical +debugger. + +=item C<inhibit_exit> +X<debugger option, inhibit_exit> + +If 0, allows I<stepping off> the end of the script. + +=item C<PrintRet> +X<debugger option, PrintRet> + +Print return value after C<r> command if set (default). + +=item C<ornaments> +X<debugger option, ornaments> + +Affects screen appearance of the command line (see L<Term::ReadLine>). +There is currently no way to disable these, which can render +some output illegible on some displays, or with some pagers. +This is considered a bug. + +=item C<frame> +X<debugger option, frame> + +Affects the printing of messages upon entry and exit from subroutines. If +C<frame & 2> is false, messages are printed on entry only. (Printing +on exit might be useful if interspersed with other messages.) + +If C<frame & 4>, arguments to functions are printed, plus context +and caller info. If C<frame & 8>, overloaded C<stringify> and +C<tie>d C<FETCH> is enabled on the printed arguments. If C<frame +& 16>, the return value from the subroutine is printed. + +The length at which the argument list is truncated is governed by the +next option: + +=item C<maxTraceLen> +X<debugger option, maxTraceLen> + +Length to truncate the argument list when the C<frame> option's +bit 4 is set. + +=item C<windowSize> +X<debugger option, windowSize> + +Change the size of code list window (default is 10 lines). + +=back + +The following options affect what happens with C<V>, C<X>, and C<x> +commands: + +=over 12 + +=item C<arrayDepth>, C<hashDepth> +X<debugger option, arrayDepth> X<debugger option, hashDepth> + +Print only first N elements ('' for all). + +=item C<dumpDepth> +X<debugger option, dumpDepth> + +Limit recursion depth to N levels when dumping structures. +Negative values are interpreted as infinity. Default: infinity. + +=item C<compactDump>, C<veryCompact> +X<debugger option, compactDump> X<debugger option, veryCompact> + +Change the style of array and hash output. If C<compactDump>, short array +may be printed on one line. + +=item C<globPrint> +X<debugger option, globPrint> + +Whether to print contents of globs. + +=item C<DumpDBFiles> +X<debugger option, DumpDBFiles> + +Dump arrays holding debugged files. + +=item C<DumpPackages> +X<debugger option, DumpPackages> + +Dump symbol tables of packages. + +=item C<DumpReused> +X<debugger option, DumpReused> + +Dump contents of "reused" addresses. + +=item C<quote>, C<HighBit>, C<undefPrint> +X<debugger option, quote> X<debugger option, HighBit> +X<debugger option, undefPrint> + +Change the style of string dump. The default value for C<quote> +is C<auto>; one can enable double-quotish or single-quotish format +by setting it to C<"> or C<'>, respectively. By default, characters +with their high bit set are printed verbatim. + +=item C<UsageOnly> +X<debugger option, UsageOnly> + +Rudimentary per-package memory usage dump. Calculates total +size of strings found in variables in the package. This does not +include lexicals in a module's file scope, or lost in closures. + +=back + +After the rc file is read, the debugger reads the C<$ENV{PERLDB_OPTS}> +environment variable and parses this as the remainder of a "O ..." +line as one might enter at the debugger prompt. You may place the +initialization options C<TTY>, C<noTTY>, C<ReadLine>, and C<NonStop> +there. + +If your rc file contains: + + parse_options("NonStop=1 LineInfo=db.out AutoTrace"); + +then your script will run without human intervention, putting trace +information into the file I<db.out>. (If you interrupt it, you'd +better reset C<LineInfo> to F</dev/tty> if you expect to see anything.) + +=over 12 + +=item C<TTY> +X<debugger option, TTY> + +The TTY to use for debugging I/O. + +=item C<noTTY> +X<debugger option, noTTY> + +If set, the debugger goes into C<NonStop> mode and will not connect to a TTY. If +interrupted (or if control goes to the debugger via explicit setting of +$DB::signal or $DB::single from the Perl script), it connects to a TTY +specified in the C<TTY> option at startup, or to a tty found at +runtime using the C<Term::Rendezvous> module of your choice. + +This module should implement a method named C<new> that returns an object +with two methods: C<IN> and C<OUT>. These should return filehandles to use +for debugging input and output correspondingly. The C<new> method should +inspect an argument containing the value of C<$ENV{PERLDB_NOTTY}> at +startup, or C<"$ENV{HOME}/.perldbtty$$"> otherwise. This file is not +inspected for proper ownership, so security hazards are theoretically +possible. + +=item C<ReadLine> +X<debugger option, ReadLine> + +If false, readline support in the debugger is disabled in order +to debug applications that themselves use ReadLine. + +=item C<NonStop> +X<debugger option, NonStop> + +If set, the debugger goes into non-interactive mode until interrupted, or +programmatically by setting $DB::signal or $DB::single. + +=back + +Here's an example of using the C<$ENV{PERLDB_OPTS}> variable: + + $ PERLDB_OPTS="NonStop frame=2" perl -d myprogram + +That will run the script B<myprogram> without human intervention, +printing out the call tree with entry and exit points. Note that +C<NonStop=1 frame=2> is equivalent to C<N f=2>, and that originally, +options could be uniquely abbreviated by the first letter (modulo +the C<Dump*> options). It is nevertheless recommended that you +always spell them out in full for legibility and future compatibility. + +Other examples include + + $ PERLDB_OPTS="NonStop LineInfo=listing frame=2" perl -d myprogram + +which runs script non-interactively, printing info on each entry +into a subroutine and each executed line into the file named F<listing>. +(If you interrupt it, you would better reset C<LineInfo> to something +"interactive"!) + +Other examples include (using standard shell syntax to show environment +variable settings): + + $ ( PERLDB_OPTS="NonStop frame=1 AutoTrace LineInfo=tperl.out" + perl -d myprogram ) + +which may be useful for debugging a program that uses C<Term::ReadLine> +itself. Do not forget to detach your shell from the TTY in the window that +corresponds to F</dev/ttyXX>, say, by issuing a command like + + $ sleep 1000000 + +See L<perldebguts/"Debugger Internals"> for details. + +=head2 Debugger input/output + +=over 8 + +=item Prompt + +The debugger prompt is something like + + DB<8> + +or even + + DB<<17>> + +where that number is the command number, and which you'd use to +access with the built-in B<csh>-like history mechanism. For example, +C<!17> would repeat command number 17. The depth of the angle +brackets indicates the nesting depth of the debugger. You could +get more than one set of brackets, for example, if you'd already +at a breakpoint and then printed the result of a function call that +itself has a breakpoint, or you step into an expression via C<s/n/t +expression> command. + +=item Multiline commands + +If you want to enter a multi-line command, such as a subroutine +definition with several statements or a format, escape the newline +that would normally end the debugger command with a backslash. +Here's an example: + + DB<1> for (1..4) { \ + cont: print "ok\n"; \ + cont: } + ok + ok + ok + ok + +Note that this business of escaping a newline is specific to interactive +commands typed into the debugger. + +=item Stack backtrace +X<backtrace> X<stack, backtrace> + +Here's an example of what a stack backtrace via C<T> command might +look like: + + $ = main::infested called from file `Ambulation.pm' line 10 + @ = Ambulation::legs(1, 2, 3, 4) called from file `camel_flea' line 7 + $ = main::pests('bactrian', 4) called from file `camel_flea' line 4 + +The left-hand character up there indicates the context in which the +function was called, with C<$> and C<@> meaning scalar or list +contexts respectively, and C<.> meaning void context (which is +actually a sort of scalar context). The display above says +that you were in the function C<main::infested> when you ran the +stack dump, and that it was called in scalar context from line +10 of the file I<Ambulation.pm>, but without any arguments at all, +meaning it was called as C<&infested>. The next stack frame shows +that the function C<Ambulation::legs> was called in list context +from the I<camel_flea> file with four arguments. The last stack +frame shows that C<main::pests> was called in scalar context, +also from I<camel_flea>, but from line 4. + +If you execute the C<T> command from inside an active C<use> +statement, the backtrace will contain both a C<require> frame and +an C<eval>) frame. + +=item Line Listing Format + +This shows the sorts of output the C<l> command can produce: + + DB<<13>> l + 101: @i{@i} = (); + 102:b @isa{@i,$pack} = () + 103 if(exists $i{$prevpack} || exists $isa{$pack}); + 104 } + 105 + 106 next + 107==> if(exists $isa{$pack}); + 108 + 109:a if ($extra-- > 0) { + 110: %isa = ($pack,1); + +Breakable lines are marked with C<:>. Lines with breakpoints are +marked by C<b> and those with actions by C<a>. The line that's +about to be executed is marked by C<< ==> >>. + +Please be aware that code in debugger listings may not look the same +as your original source code. Line directives and external source +filters can alter the code before Perl sees it, causing code to move +from its original positions or take on entirely different forms. + +=item Frame listing + +When the C<frame> option is set, the debugger would print entered (and +optionally exited) subroutines in different styles. See L<perldebguts> +for incredibly long examples of these. + +=back + +=head2 Debugging compile-time statements + +If you have compile-time executable statements (such as code within +BEGIN, UNITCHECK and CHECK blocks or C<use> statements), these will +I<not> be stopped by debugger, although C<require>s and INIT blocks +will, and compile-time statements can be traced with C<AutoTrace> +option set in C<PERLDB_OPTS>). From your own Perl code, however, you +can transfer control back to the debugger using the following +statement, which is harmless if the debugger is not running: + + $DB::single = 1; + +If you set C<$DB::single> to 2, it's equivalent to having +just typed the C<n> command, whereas a value of 1 means the C<s> +command. The C<$DB::trace> variable should be set to 1 to simulate +having typed the C<t> command. + +Another way to debug compile-time code is to start the debugger, set a +breakpoint on the I<load> of some module: + + DB<7> b load f:/perllib/lib/Carp.pm + Will stop on load of `f:/perllib/lib/Carp.pm'. + +and then restart the debugger using the C<R> command (if possible). One can use C<b +compile subname> for the same purpose. + +=head2 Debugger Customization + +The debugger probably contains enough configuration hooks that you +won't ever have to modify it yourself. You may change the behaviour +of debugger from within the debugger using its C<o> command, from +the command line via the C<PERLDB_OPTS> environment variable, and +from customization files. + +You can do some customization by setting up a F<.perldb> file, which +contains initialization code. For instance, you could make aliases +like these (the last one is one people expect to be there): + + $DB::alias{'len'} = 's/^len(.*)/p length($1)/'; + $DB::alias{'stop'} = 's/^stop (at|in)/b/'; + $DB::alias{'ps'} = 's/^ps\b/p scalar /'; + $DB::alias{'quit'} = 's/^quit(\s*)/exit/'; + +You can change options from F<.perldb> by using calls like this one; + + parse_options("NonStop=1 LineInfo=db.out AutoTrace=1 frame=2"); + +The code is executed in the package C<DB>. Note that F<.perldb> is +processed before processing C<PERLDB_OPTS>. If F<.perldb> defines the +subroutine C<afterinit>, that function is called after debugger +initialization ends. F<.perldb> may be contained in the current +directory, or in the home directory. Because this file is sourced +in by Perl and may contain arbitrary commands, for security reasons, +it must be owned by the superuser or the current user, and writable +by no one but its owner. + +You can mock TTY input to debugger by adding arbitrary commands to +@DB::typeahead. For example, your F<.perldb> file might contain: + + sub afterinit { push @DB::typeahead, "b 4", "b 6"; } + +Which would attempt to set breakpoints on lines 4 and 6 immediately +after debugger initialization. Note that @DB::typeahead is not a supported +interface and is subject to change in future releases. + +If you want to modify the debugger, copy F<perl5db.pl> from the +Perl library to another name and hack it to your heart's content. +You'll then want to set your C<PERL5DB> environment variable to say +something like this: + + BEGIN { require "myperl5db.pl" } + +As a last resort, you could also use C<PERL5DB> to customize the debugger +by directly setting internal variables or calling debugger functions. + +Note that any variables and functions that are not documented in +this document (or in L<perldebguts>) are considered for internal +use only, and as such are subject to change without notice. + +=head2 Readline Support / History in the debugger + +As shipped, the only command-line history supplied is a simplistic one +that checks for leading exclamation points. However, if you install +the Term::ReadKey and Term::ReadLine modules from CPAN (such as +Term::ReadLine::Gnu, Term::ReadLine::Perl, ...) you will +have full editing capabilities much like GNU I<readline>(3) provides. +Look for these in the F<modules/by-module/Term> directory on CPAN. +These do not support normal B<vi> command-line editing, however. + +A rudimentary command-line completion is also available. +Unfortunately, the names of lexical variables are not available for +completion. + +Without Readline support you may see the symbols "^[[A", "^[[C", "^[[B", +"^[[D"", "^H", ... when using the arrow keys and/or the backspace key. + +=head2 Editor Support for Debugging + +If you have the FSF's version of B<emacs> installed on your system, +it can interact with the Perl debugger to provide an integrated +software development environment reminiscent of its interactions +with C debuggers. + +Perl comes with a start file for making B<emacs> act like a +syntax-directed editor that understands (some of) Perl's syntax. +Look in the I<emacs> directory of the Perl source distribution. + +A similar setup by Tom Christiansen for interacting with any +vendor-shipped B<vi> and the X11 window system is also available. +This works similarly to the integrated multiwindow support that +B<emacs> provides, where the debugger drives the editor. At the +time of this writing, however, that tool's eventual location in the +Perl distribution was uncertain. + +Users of B<vi> should also look into B<vim> and B<gvim>, the mousey +and windy version, for coloring of Perl keywords. + +Note that only perl can truly parse Perl, so all such CASE tools +fall somewhat short of the mark, especially if you don't program +your Perl as a C programmer might. + +=head2 The Perl Profiler +X<profile> X<profiling> X<profiler> + +If you wish to supply an alternative debugger for Perl to run, just +invoke your script with a colon and a package argument given to the +B<-d> flag. The most popular alternative debuggers for Perl is the +Perl profiler. Devel::DProf is included with the standard Perl +distribution. To profile your Perl program in the file F<mycode.pl>, +just type: + + $ perl -d:DProf mycode.pl + +When the script terminates the profiler will dump the profile +information to a file called F<tmon.out>. A tool like B<dprofpp>, +also supplied with the standard Perl distribution, can be used to +interpret the information in that profile. More powerful profilers, +such as C<Devel::NYTProf> are available from the CPAN. + +=head1 Debugging regular expressions +X<regular expression, debugging> +X<regex, debugging> X<regexp, debugging> + +C<use re 'debug'> enables you to see the gory details of how the Perl +regular expression engine works. In order to understand this typically +voluminous output, one must not only have some idea about how regular +expression matching works in general, but also know how Perl's regular +expressions are internally compiled into an automaton. These matters +are explored in some detail in +L<perldebguts/"Debugging regular expressions">. + +=head1 Debugging memory usage +X<memory usage> + +Perl contains internal support for reporting its own memory usage, +but this is a fairly advanced concept that requires some understanding +of how memory allocation works. +See L<perldebguts/"Debugging Perl memory usage"> for the details. + +=head1 SEE ALSO + +You did try the B<-w> switch, didn't you? + +L<perldebtut>, +L<perldebguts>, +L<re>, +L<DB>, +L<Devel::DProf>, +L<dprofpp>, +L<Dumpvalue>, +and +L<perlrun>. + +When debugging a script that uses #! and is thus normally found in +$PATH, the -S option causes perl to search $PATH for it, so you don't +have to type the path or C<which $scriptname>. + + $ perl -Sd foo.pl + +=head1 BUGS + +You cannot get stack frame information or in any fashion debug functions +that were not compiled by Perl, such as those from C or C++ extensions. + +If you alter your @_ arguments in a subroutine (such as with C<shift> +or C<pop>), the stack backtrace will not show the original values. + +The debugger does not currently work in conjunction with the B<-W> +command-line switch, because it itself is not free of warnings. + +If you're in a slow syscall (like C<wait>ing, C<accept>ing, or C<read>ing +from your keyboard or a socket) and haven't set up your own C<$SIG{INT}> +handler, then you won't be able to CTRL-C your way back to the debugger, +because the debugger's own C<$SIG{INT}> handler doesn't understand that +it needs to raise an exception to longjmp(3) out of slow syscalls. |