=head1 NAME
+X<debug> X<debugger>
perldebug - Perl debugging
First of all, have you tried using the B<-w> switch?
-=head2 Debugging
-If you invoke Perl with a B<-d> switch, your script will be run under the
-debugger. However, the Perl debugger is not a separate program as it is
-in a C environment. Instead, the B<-d> flag tells the compiler to insert
-source information into the pseudocode it's about to hand to the
-interpreter. (That means your code must compile correctly for the
-debugger to work on it.) Then when the interpreter starts up, it
-pre-loads a Perl library file containing the debugger itself. The program
-will halt before the first executable statement (but see below) and ask
-you for one of the following commands:
+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 help message.
+Prints out a summary help message
-=item T
+=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">.
-Stack trace.
-If you do bizarre things to your @_ arguments in a subroutine, the stack
-backtrace will not always show the original values.
+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 s
+=item V [pkg [vars]]
+X<debugger command, V>
-Single step. Executes until it reaches the beginning of another
-statement.
+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:
-=item n
+ V DB filename line
-Next. Executes over subroutine calls, until it reaches the beginning
-of the next statement.
+Use C<~pattern> and C<!pattern> for positive and negative regexes.
-=item f
+This is similar to calling the C<x> command on each applicable var.
-Finish. Executes statements until it has finished the current
-subroutine.
+=item X [vars]
+X<debugger command, X>
-=item c
+Same as C<V currentpackage [vars]>.
-Continue. Executes until the next breakpoint is reached.
+=item y [level [vars]]
+X<debugger command, y>
-=item c line
+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.
-Continue to the specified line. Inserts a one-time-only breakpoint at
-the specified line.
+=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 n or s.
+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 incr+1 lines starting at min. If min is omitted, starts where
-last listing left off. If incr is omitted, previous value of incr is
-used.
+List C<incr+1> lines starting at C<min>.
=item l min-max
-List lines in the indicated range.
+List lines C<min> through C<max>. C<l -> is synonymous to C<->.
=item l line
-List just the indicated line.
+List a single line.
-=item l
+=item l subname
-List next window.
+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.
+List previous window of lines.
-=item w line
+=item v [line]
+X<debugger command, v>
-List window (a few lines worth of code) around line.
+View a few lines of code around the current line.
-=item l subname
+=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.
-List subroutine. If it's a long subroutine it just lists the
-beginning. Use "l" to list more.
+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/
-Regular expression search forward in the source code for pattern; the
-final / is optional.
+Search forwards for pattern (a Perl regex); final / is optional.
+The search is case-insensitive by default.
=item ?pattern?
-Regular expression search backward in the source code for pattern; the
-final ? is optional.
+Search backwards for pattern; final ? is optional.
+The search is case-insensitive by default.
-=item L
+=item L [abw]
+X<debugger command, L>
-List lines that have breakpoints or actions.
+List (default all) actions, breakpoints and watch expressions
-=item S
+=item S [[!]regex]
+X<debugger command, S>
-Lists the names of all subroutines.
+List subroutine names [not] matching the regex.
-=item t
+=item t [n]
+X<debugger command, t>
-Toggle trace mode on or off.
+Toggle trace mode (see also the C<AutoTrace> option).
+Optional argument is the maximum number of levels to trace below
+the current one; anything deeper than that will be silent.
-=item b line [ condition ]
+=item t [n] expr
+X<debugger command, t>
-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 is
-evaluated each time the statement is reached and 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>:
+Trace through execution of C<expr>.
+Optional first argument is the maximum number of levels to trace below
+the current one; anything deeper than that will be silent.
+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 ]
+If the line number is C<.>, sets a breakpoint on the current line:
-Set breakpoint at first executable line of subroutine.
+ b . $n > 100
-=item d line
+=item b [file]:[line] [condition]
+X<breakpoint>
+X<debugger command, b>
-Delete breakpoint. If line is omitted, deletes the breakpoint on the
-line that is about to be executed.
+Set a breakpoint before the given line in a (possibly different) file. 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>:
-=item D
+ b lib/MyModule.pm:237 $x > 30
+ b /usr/lib/perl5/site_perl/CGI.pm:100 ++$count100 < 11
-Delete all breakpoints.
+=item b subname [condition]
+X<breakpoint>
+X<debugger command, b>
-=item a line command
+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).
-Set an action for line. A multiline command may be entered by
-backslashing the newlines. This command is Perl code, not another
-debugger command.
+=item b postpone subname [condition]
+X<breakpoint>
+X<debugger command, b>
-=item A
+Set a breakpoint at first line of subroutine after it is compiled.
-Delete all line actions.
+=item b load filename
+X<breakpoint>
+X<debugger command, b>
-=item < command
+Set a breakpoint before the first executed line of the I<filename>,
+which should be a full pathname found amongst the %INC values.
-Set an action to happen before every debugger prompt. A multiline
-command may be entered by backslashing the newlines.
+=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 disable [file]:[line]
+X<breakpoint>
+X<debugger command, disable>
+X<disable>
+
+Disable the breakpoint so it won't stop the execution of the program.
+Breakpoints are enabled by default and can be re-enabled using the C<enable>
+command.
+
+=item disable [line]
+X<breakpoint>
+X<debugger command, disable>
+X<disable>
+
+Disable the breakpoint so it won't stop the execution of the program.
+Breakpoints are enabled by default and can be re-enabled using the C<enable>
+command.
+
+This is done for a breakpoint in the current file.
+
+=item enable [file]:[line]
+X<breakpoint>
+X<debugger command, disable>
+X<disable>
+
+Enable the breakpoint so it will stop the execution of the program.
+
+=item enable [line]
+X<breakpoint>
+X<debugger command, disable>
+X<disable>
+
+Enable the breakpoint so it will stop the execution of the program.
+
+This is done for a breakpoint in the current file.
+
+=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.
-Set an action to happen after the prompt when you've just given a
-command to return to executing the script. A multiline command may be
-entered by backslashing the newlines.
+=item { [ command ]
-=item V package [symbols]
+Set an action (debugger command) to happen before every debugger prompt.
+A multi-line command may be entered in the customary fashion.
-Display all (or some) variables in package (defaulting to the C<main>
-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 $) there, just the symbol
-names, like this:
+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 { ... }>.
- V DB filename line
+=item { *
+X<debugger command, {>
-=item X [symbols]
+Delete all pre-prompt debugger commands.
-Same as as "V" command, but within the current package.
+=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 debugging command. If number is omitted, redoes the previous
-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.
-Redo the command that was that many commands ago.
+=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 number is omitted, lists them all.
+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.
-Quit. ("quit" doesn't work for this.)
+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 missing semicolon will be
-supplied.
+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 p expr
+=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>
+
+Display 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:
-Same as C<print DB::OUT expr>. The DB::OUT filehandle is opened to
-/dev/tty, regardless of where STDOUT may be redirected to.
+ $DB::doccmd = 'netscape -remote http://something.here/';
=back
-Any command you type in that isn't recognized by the debugger will be
-directly executed (C<eval>'d) as Perl code. Leading white space will
-cause the debugger to think it's C<NOT> a debugger command.
+=head2 Configurable Options
-If you have any compile-time executable statements (code within a BEGIN
-block or a C<use> statement), these will I<NOT> be stopped by debugger,
-although C<require>s will. From your own code, however, you can transfer
-control back to the debugger using the following statement, which is harmless
-if the debugger is not running:
+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 a command or spawn a 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 the 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;
-=head2 Customization
+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.
-If you want to modify the debugger, copy F<perl5db.pl> from the Perl
-library to another name and modify it as necessary. You'll also want
-to set environment variable PERL5DB to say something like this:
+Another way to debug compile-time code is to start the debugger, set a
+breakpoint on the I<load> of some module:
- BEGIN { require "myperl5db.pl" }
+ 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 the 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
+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 in particular most people seem to expect to
-be there):
+like these (the last one is one people expect to be there):
- $DB::alias{'len'} = 's/^len(.*)/p length($1)/';
+ $DB::alias{'len'} = 's/^len(.*)/p length($1)/';
$DB::alias{'stop'} = 's/^stop (at|in)/b/';
- $DB::alias{'.'} = 's/^\./p '
- . '"\$DB::sub(\$DB::filename:\$DB::line):\t"'
- . ',\$DB::dbline[\$DB::line]/' ;
+ $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 those 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, including
+lexical variables in the current scope if the C<PadWalker> module
+is installed.
-=head2 Other resources
+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.
+
+Recent versions of Emacs come with a
+start file for making B<emacs> act like a
+syntax-directed editor that understands (some of) Perl's syntax.
+See L<perlfaq3>.
+
+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,
+invoke your script with a colon and a package argument given to the
+B<-d> flag. Perl's alternative debuggers include a Perl profiler,
+L<Devel::NYTProf>, which is available separately as a CPAN
+distribution. To profile your Perl program in the file F<mycode.pl>,
+just type:
+
+ $ perl -d:NYTProf mycode.pl
+
+When the script terminates the profiler will create a database of the
+profile information that you can turn into reports using the profiler's
+tools. See <perlperf> for details.
+
+=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::NYTProf>,
+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
-If your program exit()s or die()s, so does the debugger.
+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.
-There's no builtin way to restart the debugger without exiting and coming back
-into it. You could use an alias like this:
+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.
- $DB::alias{'rerun'} = 'exec "perl -d $DB::filename"';
+The debugger does not currently work in conjunction with the B<-W>
+command-line switch, because it itself is not free of warnings.
-But you'd lose any pending breakpoint information, and that might not
-be the right path, etc.
+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.
https://perl5.git.perl.org / perl5.git / blobdiff