NAME DESCRIPTION Debugger Internals Frame Listing Output Examples Debugging regular expressions Debugging Perl memory usage SEE ALSO


perldebguts - Guts of Perl debugging


This is not the perldebug(1) manpage, which tells you how to use the debugger. This manpage describes low-level details ranging between difficult and impossible for anyone who isn't incredibly intimate with Perl's guts to understand. Caveat lector.

Debugger Internals

Perl has special debugging hooks at compile-time and run-time used to create debugging environments. These hooks are not to be confused with the perl -Dxxx command described in perlrun, which is usable only if a special Perl is built per the instructions in the INSTALL podpage in the Perl source tree.

For example, whenever you call Perl's built-in caller function from the package DB , the arguments that the corresponding stack frame was called with are copied to the @DB::args array. The general mechanisms is enabled by calling Perl with the -d switch, the following additional features are enabled (cf. ``$^P'' in perlvar):

Perl inserts the contents of $ENV{PERL5DB} (or BEGIN {require ''} if not present) before the first line of your program.

Each array @{ holds the lines of $filename for a file compiled by Perl. The same for evaled strings that contain subroutines, or which are currently being executed. The $filename for evaled strings looks like (eval 34). Code assertions in regexes look like (re_eval 19).

Values in this array are magical in numeric context: they compare equal to zero only if the line is not breakable.

Each hash %{ contains breakpoints and actions keyed by line number. Individual entries (as opposed to the whole hash) are settable. Perl only cares about Boolean true here, although the values used by have the form .

The same holds for evaluated strings that contain subroutines, or which are currently being executed. The $filename for evaled strings looks like (eval 34) or (re_eval 19).

Each scalar ${ contains . This is also the case for evaluated strings that contain subroutines, or which are currently being executed. The $filename for evaled strings looks like (eval 34) or (re_eval 19).

After each required file is compiled, but before it is executed, DB::postponed(*{ is called if the subroutine DB::postponed exists. Here, the $filename is the expanded name of the required file, as found in the values of %INC.

After each subroutine subname is compiled, the existence of $DB::postponed{subname} is checked. If this key exists, DB::postponed(subname) is called if the DB::postponed subroutine also exists.

A hash %DB::sub is maintained, whose keys are subroutine names and whose values have the form filename:startline-endline. filename has the form (eval 34) for subroutines defined inside evals, or (re_eval 19) for those within regex code assertions.

When the execution of your program reaches a point that can hold a breakpoint, the DB::DB() subroutine is called any of the variables $DB::trace, $DB::single, or $DB::signal is true. These variables are not localizable. This feature is disabled when executing inside DB::DB(), including functions called from it unless $^D

is true.

When execution of the program reaches a subroutine call, a call to (args) is made instead, with $DB::sub holding the name of the called subroutine. This doesn't happen if the subroutine was compiled in the DB package.)

Note that if needs external data for it to work, no subroutine call is possible until this is done. For the standard debugger, the $DB::deep variable (how many levels of recursion deep into the debugger you can go before a mandatory break) gives an example of such a dependency.

Writing Your Own Debugger

The minimal working debugger consists of one line

sub DB::DB {}

which is quite handy as contents of PERL5DB environment variable
Another brief debugger, slightly more useful, could be created with only the line
sub DB::DB {print ++$i; scalar

This debugger would print the sequential number of encountered statement, and would wait for you to hit a newline before continuing.

The following debugger is quite functional

package DB; sub DB {} sub sub {print ++$i, It prints the sequential number of subroutine call and the name of the called subroutine. Note that should be compiled into the package DB.

At the start, the debugger reads your rc file (./.perldb or /.perldb under Unix), which can set important options. This file may define a subroutine

to be executed after the debugger is


After the rc file is read, the debugger reads the PERLDB_OPTS environment variable and parses this as the remainder of a O ... line as one might enter at the debugger prompt.

The debugger also maintains magical internal variables, such as @DB::dbline, %DB::dbline, which are aliases for @{ . Here current_file is the currently selected file, either explicitly chosen with the debugger's f command, or implicitly by flow of execution.

Some functions are provided to simplify customization. See ``Options'' in perldebug for description of options parsed by DB::parse_options(string). The function DB::dump_trace(skip[, count?) skips the specified number of frames and returns a list containing information about the calling frames (all of them, if count is missing). Each entry is reference to a hash with keys context (either ., $, or @), sub (subroutine name, or info about eval), args (undef or a reference to an array), file, and line.

The function DB::print_trace(FH, skip

Fatal Error:

lib/CachedMarkup.php (In template 'browse' < 'body' < 'html'):257: Error: Pure virtual

Fatal PhpWiki Error

lib/CachedMarkup.php (In template 'browse' < 'body' < 'html'):257: Error: Pure virtual