diff options
Diffstat (limited to 'Master/tlpkg/tlperl.straw/lib/pods/perldebug.pod')
| -rwxr-xr-x | Master/tlpkg/tlperl.straw/lib/pods/perldebug.pod | 1174 |
1 files changed, 0 insertions, 1174 deletions
diff --git a/Master/tlpkg/tlperl.straw/lib/pods/perldebug.pod b/Master/tlpkg/tlperl.straw/lib/pods/perldebug.pod deleted file mode 100755 index c37c5cfbb2c..00000000000 --- a/Master/tlpkg/tlperl.straw/lib/pods/perldebug.pod +++ /dev/null @@ -1,1174 +0,0 @@ -=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. |