=head1 NAME perldebug - Perl debugging =head1 DESCRIPTION First of all, have you tried using the B<-w> switch? =head1 The Perl Debugger "As soon as we started programming, we found to our surprise that it wasn't as easy to get programs right as we had thought. Debugging had to be discovered. I can remember the exact instant when I realized that a large part of my life from then on was going to be spent in finding mistakes in my own programs." I< --Maurice Wilkes, 1949> 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: perl -d -e 42 In Perl, the debugger is not a separate program as 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 Perl library file containing the debugger itself. The program will halt I 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 to execute, rather than the one it has just executed. Any command not recognized by the debugger is directly executed (C'd) as Perl code in the current package. (The debugger uses the DB package for its own state information.) Leading white space before a command would cause the debugger to think it's I a debugger command but for Perl, so be careful not to do that. =head2 Debugger Commands The debugger understands the following commands: =over 12 =item h [command] Prints out a help message. If you supply another debugger command as an argument to the C command, it prints out the description for just that command. The special argument of C produces a more compact help listing, designed to fit together on one screen. If the output of the C command (or any command, for that matter) scrolls past your screen, either precede the command with a leading pipe symbol so it's run through your pager, as in DB> |h You may change the pager which is used via C command. =item p expr Same as C in the current package. In particular, because this is just Perl's own B function, this means that nested data structures and objects are not dumped, unlike with the C command. The C filehandle is opened to F, regardless of where STDOUT may be redirected to. =item x expr 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 C function. The details of printout are governed by multiple Cptions. =item V [pkg [vars]] Display all (or some) variables in package (defaulting to the C
package) 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 for positive and negative regexps. Nested data structures are printed out in a legible fashion, unlike the C function. The details of printout are governed by multiple Cptions. =item X [vars] Same as C. =item T Produce a stack backtrace. See below for details on its output. =item s [expr] Single step. Executes until it reaches 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] Next. Executes over subroutine calls, until it reaches 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 ECRE Repeat last C or C command. =item c [line|sub] Continue, optionally inserting a one-time-only breakpoint at the specified line or subroutine. =item l List next window of lines. =item l min+incr List C lines starting at C. =item l min-max List lines C through C. C is synonymous to C<->. =item l line List a single line. =item l subname List first window of lines from subroutine. =item - List previous window of lines. =item w [line] List window (a few lines) around the current line. =item . Return debugger pointer to the last-executed line and print it out. =item f filename Switch to viewing a different file or eval statement. If C is not a full filename as found in values of %INC, it is considered as a regexp. =item /pattern/ Search forwards for pattern; final / is optional. =item ?pattern? Search backwards for pattern; final ? is optional. =item L List all breakpoints and actions. =item S [[!]pattern] List subroutine names [not] matching pattern. =item t Toggle trace mode (see also C Cption). =item t expr Trace through execution of expr. For example: $ perl -de 42 Stack dump during die enabled outside of evals. Loading DB routines from perl5db.pl patch level 0.94 Emacs support available. Enter h or `h h' for help. main::(-e:1): 0 DB<1> sub foo { 14 } DB<2> sub bar { 3 } DB<3> t print foo() * bar() main::((eval 172):3): print foo() + bar(); main::foo((eval 168):2): main::bar((eval 170):2): 42 or, with the Cption C set, DB<4> O f=2 frame = '2' DB<5> t print foo() * bar() 3: foo() * bar() entering main::foo 2: sub foo { 14 }; exited main::foo entering main::bar 2: sub bar { 3 }; exited main::bar 42 =item b [line] [condition] Set a breakpoint. If line is omitted, sets a breakpoint on the line that is about to be executed. If a condition is specified, it's evaluated each time the statement is reached and a breakpoint is taken only if the condition is true. Breakpoints may be set on only lines that begin an executable statement. Conditions don't use B: b 237 $x > 30 b 237 ++$count237 < 11 b 33 /pattern/i =item b subname [condition] Set a breakpoint at the first line of the named subroutine. =item b postpone subname [condition] Set breakpoint at first line of subroutine after it is compiled. =item b load filename Set breakpoint at the first executed line of the file. Filename should be a full name as found in values of %INC. =item b compile subname Sets breakpoint at the first statement executed after the subroutine is compiled. =item d [line] Delete a breakpoint at the specified line. If line is omitted, deletes the breakpoint on the line that is about to be executed. =item D Delete all installed breakpoints. =item a [line] command Set an action to be done before the line is 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 Delete all installed actions. =item W [expr] Add a global watch-expression. =item W Delete all watch-expressions. =item O [opt[=val]] [opt"val"] [opt?]... Set or query values of options. val defaults to 1. opt can be abbreviated. Several options can be listed. =over 12 =item C, C The characters used to recall command or spawn shell. By default, these are both set to C. =item C Program to use for output of pager-piped commands (those beginning with a C<|> character.) By default, C<$ENV{PAGER}> will be used. =item C Run Tk while prompting (with ReadLine). =item C, C, C Level of verbosity. By default the debugger is in a sane verbose mode, thus it will print backtraces on all the warnings and die-messages which are going to be printed out, and will print a message when interesting uncaught signals arrive. To disable this behaviour, set these values to 0. If C is 2, then the messages which will be caught by surrounding C are also printed. =item C Trace mode (similar to C command, but can be put into C). =item C File or pipe to print line number info to. If it is a pipe (say, C<|visual_perl_db>), then a short, "emacs like" message is used. =item C If 0, allows I the end of the script. =item C affects printing of return value after C command. =item C affects screen appearance of the command line (see L). =item C affects printing messages on entry and exit from subroutines. If C is false, messages are printed on entry only. (Printing on exit may be useful if inter(di)spersed with other messages.) If C, arguments to functions are printed as well as the context and caller info. If C, overloaded C and Cd C are enabled on the printed arguments. If C, the return value from the subroutine is printed as well. The length at which the argument list is truncated is governed by the next option: =item C length at which the argument list is truncated when C option's bit 4 is set. =back The following options affect what happens with C, C, and C commands: =over 12 =item C, C Print only first N elements ('' for all). =item C, C Change style of array and hash dump. If C, short array may be printed on one line. =item C Whether to print contents of globs. =item C Dump arrays holding debugged files. =item C Dump symbol tables of packages. =item C Dump contents of "reused" addresses. =item C, C, C Change style of string dump. Default value of C is C, one can enable either double-quotish dump, or single-quotish by setting it to C<"> or C<'>. By default, characters with high bit set are printed I. =item C I rudimentally per-package memory usage dump. Calculates total size of strings in variables in the package. =back During startup options are initialized from C<$ENV{PERLDB_OPTS}>. You can put additional initialization options C, C, C, and C there. Example rc file: &parse_options("NonStop=1 LineInfo=db.out AutoTrace"); The script will run without human intervention, putting trace information into the file I. (If you interrupt it, you would better reset C to something "interactive"!) =over 12 =item C The TTY to use for debugging I/O. =item C If set, goes in C mode, and would not connect to a TTY. If interrupt (or if control goes to debugger via explicit setting of $DB::signal or $DB::single from the Perl script), connects to a TTY specified by the C option at startup, or to a TTY found at runtime using C module of your choice. This module should implement a method C which returns an object with two methods: C and C, returning two filehandles to use for debugging input and output correspondingly. Method C may inspect an argument which is a value of C<$ENV{PERLDB_NOTTY}> at startup, or is C<"/tmp/perldbtty$$"> otherwise. =item C If false, readline support in debugger is disabled, so you can debug ReadLine applications. =item C If set, debugger goes into noninteractive 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="N f=2" perl -d myprogram will run the script C without human intervention, printing out the call tree with entry and exit points. Note that C is equivalent to C. Note also that at the moment when this documentation was written all the options to the debugger could be uniquely abbreviated by the first letter (with exception of C options). Other examples may include $ PERLDB_OPTS="N f A L=listing" perl -d myprogram - runs script noninteractively, printing info on each entry into a subroutine and each executed line into the file F. (If you interrupt it, you would better reset C to something "interactive"!) $ env "PERLDB_OPTS=R=0 TTY=/dev/ttyc" perl -d myprogram may be useful for debugging a program which uses C itself. Do not forget detach shell from the TTY in the window which corresponds to F, say, by issuing a command like $ sleep 1000000 See L<"Debugger Internals"> below for more details. =item E [ command ] Set an action (Perl command) to happen before every debugger prompt. A multi-line command may be entered by backslashing the newlines. If C is missing, resets the list of actions. =item EE command Add an action (Perl command) to happen before every debugger prompt. A multi-line command may be entered by backslashing the newlines. =item E 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. If C is missing, resets the list of actions. =item EE 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 { [ command ] Set an action (debugger command) to happen before every debugger prompt. A multi-line command may be entered by backslashing the newlines. If C is missing, resets the list of actions. =item {{ command Add an action (debugger command) to happen before every debugger prompt. A multi-line command may be entered by backslashing the newlines. =item ! number Redo a previous command (default previous command). =item ! -number Redo number'th-to-last command. =item ! pattern Redo last command that started with pattern. See C, too. =item !! cmd Run cmd in a subprocess (reads from DB::IN, writes to DB::OUT) See C too. =item H -number Display last n commands. Only commands longer than one character are listed. If number is omitted, lists them all. =item q or ^D Quit. ("quit" doesn't work for this.) This is the only supported way to exit the debugger, though typing C twice may do it too. Set an Cption C to 0 if you want to be able to I the end the script. You may also need to set C<$finished> to 0 at some moment if you want to step through global destruction. =item R Restart the debugger by Bing a new session. It tries to maintain your history across this, but internal settings and command line options may be lost. Currently the following setting are preserved: history, breakpoints, actions, debugger Cptions, and the following command line options: B<-w>, B<-I>, and B<-e>. =item |dbcmd Run debugger command, piping DB::OUT to current pager. =item ||dbcmd Same as C<|dbcmd> but DB::OUT is temporarily B