[Summary view] [Print] [Text view]

   1  =head1 NAME
   2  X<debug> X<debugger>
   3  
   4  perldebug - Perl debugging
   5  
   6  =head1 DESCRIPTION
   7  
   8  First of all, have you tried using the B<-w> switch?
   9  
  10  
  11  If you're new to the Perl debugger, you may prefer to read
  12  L<perldebtut>, which is a tutorial introduction to the debugger .
  13  
  14  =head1 The Perl Debugger
  15  
  16  If you invoke Perl with the B<-d> switch, your script runs under the
  17  Perl source debugger.  This works like an interactive Perl
  18  environment, prompting for debugger commands that let you examine
  19  source code, set breakpoints, get stack backtraces, change the values of
  20  variables, etc.  This is so convenient that you often fire up
  21  the debugger all by itself just to test out Perl constructs
  22  interactively to see what they do.  For example:
  23  X<-d>
  24  
  25      $ perl -d -e 42
  26  
  27  In Perl, the debugger is not a separate program the way it usually is in the
  28  typical compiled environment.  Instead, the B<-d> flag tells the compiler
  29  to insert source information into the parse trees it's about to hand off
  30  to the interpreter.  That means your code must first compile correctly
  31  for the debugger to work on it.  Then when the interpreter starts up, it
  32  preloads a special Perl library file containing the debugger.
  33  
  34  The program will halt I<right before> the first run-time executable
  35  statement (but see below regarding compile-time statements) and ask you
  36  to enter a debugger command.  Contrary to popular expectations, whenever
  37  the debugger halts and shows you a line of code, it always displays the
  38  line it's I<about> to execute, rather than the one it has just executed.
  39  
  40  Any command not recognized by the debugger is directly executed
  41  (C<eval>'d) as Perl code in the current package.  (The debugger
  42  uses the DB package for keeping its own state information.)
  43  
  44  Note that the said C<eval> is bound by an implicit scope. As a
  45  result any newly introduced lexical variable or any modified
  46  capture buffer content is lost after the eval. The debugger is a
  47  nice environment to learn Perl, but if you interactively experiment using
  48  material which should be in the same scope, stuff it in one line.
  49  
  50  For any text entered at the debugger prompt, leading and trailing whitespace
  51  is first stripped before further processing.  If a debugger command
  52  coincides with some function in your own program, merely precede the
  53  function with something that doesn't look like a debugger command, such
  54  as a leading C<;> or perhaps a C<+>, or by wrapping it with parentheses
  55  or braces.
  56  
  57  =head2 Calling the debugger
  58  
  59  There are several ways to call the debugger:
  60  
  61  =over 4
  62  
  63  =item perl -d program_name
  64  
  65  On the given program identified by C<program_name>.
  66  
  67  =item perl -d -e 0 
  68  
  69  Interactively supply an arbitrary C<expression> using C<-e>.
  70  
  71  =item perl -d:Ptkdb program_name
  72  
  73  Debug a given program via the C<Devel::Ptkdb> GUI.
  74  
  75  =item perl -dt threaded_program_name
  76  
  77  Debug a given program using threads (experimental).
  78  
  79  =back
  80  
  81  =head2 Debugger Commands
  82  
  83  The interactive debugger understands the following commands:
  84  
  85  =over 12
  86  
  87  =item h
  88  X<debugger command, h>
  89  
  90  Prints out a summary help message
  91  
  92  =item h [command]
  93  
  94  Prints out a help message for the given debugger command.
  95  
  96  =item h h
  97  
  98  The special argument of C<h h> produces the entire help page, which is quite long.
  99  
 100  If the output of the C<h h> command (or any command, for that matter) scrolls
 101  past your screen, precede the command with a leading pipe symbol so
 102  that it's run through your pager, as in
 103  
 104      DB> |h h
 105  
 106  You may change the pager which is used via C<o pager=...> command.
 107  
 108  
 109  =item p expr
 110  X<debugger command, p>
 111  
 112  Same as C<print {$DB::OUT} expr> in the current package.  In particular,
 113  because this is just Perl's own C<print> function, this means that nested
 114  data structures and objects are not dumped, unlike with the C<x> command.
 115  
 116  The C<DB::OUT> filehandle is opened to F</dev/tty>, regardless of
 117  where STDOUT may be redirected to.
 118  
 119  =item x [maxdepth] expr
 120  X<debugger command, x>
 121  
 122  Evaluates its expression in list context and dumps out the result in a
 123  pretty-printed fashion.  Nested data structures are printed out
 124  recursively, unlike the real C<print> function in Perl.  When dumping
 125  hashes, you'll probably prefer 'x \%h' rather than 'x %h'.
 126  See L<Dumpvalue> if you'd like to do this yourself.
 127  
 128  The output format is governed by multiple options described under
 129  L<"Configurable Options">.
 130  
 131  If the C<maxdepth> is included, it must be a numeral I<N>; the value is
 132  dumped only I<N> levels deep, as if the C<dumpDepth> option had been
 133  temporarily set to I<N>.
 134  
 135  =item V [pkg [vars]]
 136  X<debugger command, V>
 137  
 138  Display all (or some) variables in package (defaulting to C<main>)
 139  using a data pretty-printer (hashes show their keys and values so
 140  you see what's what, control characters are made printable, etc.).
 141  Make sure you don't put the type specifier (like C<$>) there, just
 142  the symbol names, like this:
 143  
 144      V DB filename line
 145  
 146  Use C<~pattern> and C<!pattern> for positive and negative regexes.
 147  
 148  This is similar to calling the C<x> command on each applicable var.
 149  
 150  =item X [vars]
 151  X<debugger command, X>
 152  
 153  Same as C<V currentpackage [vars]>.
 154  
 155  =item y [level [vars]]
 156  X<debugger command, y>
 157  
 158  Display all (or some) lexical variables (mnemonic: C<mY> variables)
 159  in the current scope or I<level> scopes higher.  You can limit the
 160  variables that you see with I<vars> which works exactly as it does
 161  for the C<V> and C<X> commands.  Requires the C<PadWalker> module
 162  version 0.08 or higher; will warn if this isn't installed.  Output
 163  is pretty-printed in the same style as for C<V> and the format is
 164  controlled by the same options.
 165  
 166  =item T
 167  X<debugger command, T> X<backtrace> X<stack, backtrace>
 168  
 169  Produce a stack backtrace.  See below for details on its output.
 170  
 171  =item s [expr]
 172  X<debugger command, s> X<step>
 173  
 174  Single step.  Executes until the beginning of another
 175  statement, descending into subroutine calls.  If an expression is
 176  supplied that includes function calls, it too will be single-stepped.
 177  
 178  =item n [expr]
 179  X<debugger command, n>
 180  
 181  Next.  Executes over subroutine calls, until the beginning
 182  of the next statement.  If an expression is supplied that includes
 183  function calls, those functions will be executed with stops before
 184  each statement.
 185  
 186  =item r
 187  X<debugger command, r>
 188  
 189  Continue until the return from the current subroutine.
 190  Dump the return value if the C<PrintRet> option is set (default).
 191  
 192  =item <CR>
 193  
 194  Repeat last C<n> or C<s> command.
 195  
 196  =item c [line|sub]
 197  X<debugger command, c>
 198  
 199  Continue, optionally inserting a one-time-only breakpoint
 200  at the specified line or subroutine.
 201  
 202  =item l
 203  X<debugger command, l>
 204  
 205  List next window of lines.
 206  
 207  =item l min+incr
 208  
 209  List C<incr+1> lines starting at C<min>.
 210  
 211  =item l min-max
 212  
 213  List lines C<min> through C<max>.  C<l -> is synonymous to C<->.
 214  
 215  =item l line
 216  
 217  List a single line.
 218  
 219  =item l subname
 220  
 221  List first window of lines from subroutine.  I<subname> may
 222  be a variable that contains a code reference.
 223  
 224  =item -
 225  X<debugger command, ->
 226  
 227  List previous window of lines.
 228  
 229  =item v [line]
 230  X<debugger command, v>
 231  
 232  View a few lines of code around the current line.
 233  
 234  =item .
 235  X<debugger command, .>
 236  
 237  Return the internal debugger pointer to the line last
 238  executed, and print out that line.
 239  
 240  =item f filename
 241  X<debugger command, f>
 242  
 243  Switch to viewing a different file or C<eval> statement.  If I<filename>
 244  is not a full pathname found in the values of %INC, it is considered
 245  a regex.
 246  
 247  C<eval>ed strings (when accessible) are considered to be filenames:
 248  C<f (eval 7)> and C<f eval 7\b> access the body of the 7th C<eval>ed string
 249  (in the order of execution).  The bodies of the currently executed C<eval>
 250  and of C<eval>ed strings that define subroutines are saved and thus
 251  accessible.
 252  
 253  =item /pattern/
 254  
 255  Search forwards for pattern (a Perl regex); final / is optional.
 256  The search is case-insensitive by default.
 257  
 258  =item ?pattern?
 259  
 260  Search backwards for pattern; final ? is optional.
 261  The search is case-insensitive by default.
 262  
 263  =item L [abw]
 264  X<debugger command, L>
 265  
 266  List (default all) actions, breakpoints and watch expressions
 267  
 268  =item S [[!]regex]
 269  X<debugger command, S>
 270  
 271  List subroutine names [not] matching the regex.
 272  
 273  =item t
 274  X<debugger command, t>
 275  
 276  Toggle trace mode (see also the C<AutoTrace> option).
 277  
 278  =item t expr
 279  X<debugger command, t>
 280  
 281  Trace through execution of C<expr>.
 282  See L<perldebguts/"Frame Listing Output Examples"> for examples.
 283  
 284  =item b
 285  X<breakpoint>
 286  X<debugger command, b>
 287  
 288  Sets breakpoint on current line
 289  
 290  =item b [line] [condition]
 291  X<breakpoint>
 292  X<debugger command, b>
 293  
 294  Set a breakpoint before the given line.  If a condition
 295  is specified, it's evaluated each time the statement is reached: a
 296  breakpoint is taken only if the condition is true.  Breakpoints may
 297  only be set on lines that begin an executable statement.  Conditions
 298  don't use C<if>:
 299  
 300      b 237 $x > 30
 301      b 237 ++$count237 < 11
 302      b 33 /pattern/i
 303  
 304  =item b subname [condition]
 305  X<breakpoint>
 306  X<debugger command, b>
 307  
 308  Set a breakpoint before the first line of the named subroutine.  I<subname> may
 309  be a variable containing a code reference (in this case I<condition>
 310  is not supported).
 311  
 312  =item b postpone subname [condition]
 313  X<breakpoint>
 314  X<debugger command, b>
 315  
 316  Set a breakpoint at first line of subroutine after it is compiled.
 317  
 318  =item b load filename
 319  X<breakpoint>
 320  X<debugger command, b>
 321  
 322  Set a breakpoint before the first executed line of the I<filename>,
 323  which should be a full pathname found amongst the %INC values.
 324  
 325  =item b compile subname
 326  X<breakpoint>
 327  X<debugger command, b>
 328  
 329  Sets a breakpoint before the first statement executed after the specified
 330  subroutine is compiled.
 331  
 332  =item B line
 333  X<breakpoint>
 334  X<debugger command, B>
 335  
 336  Delete a breakpoint from the specified I<line>.
 337  
 338  =item B *
 339  X<breakpoint>
 340  X<debugger command, B>
 341  
 342  Delete all installed breakpoints.
 343  
 344  =item a [line] command
 345  X<debugger command, a>
 346  
 347  Set an action to be done before the line is executed.  If I<line> is
 348  omitted, set an action on the line about to be executed.
 349  The sequence of steps taken by the debugger is
 350  
 351    1. check for a breakpoint at this line
 352    2. print the line if necessary (tracing)
 353    3. do any actions associated with that line
 354    4. prompt user if at a breakpoint or in single-step
 355    5. evaluate line
 356  
 357  For example, this will print out $foo every time line
 358  53 is passed:
 359  
 360      a 53 print "DB FOUND $foo\n"
 361  
 362  =item A line
 363  X<debugger command, A>
 364  
 365  Delete an action from the specified line.
 366  
 367  =item A *
 368  X<debugger command, A>
 369  
 370  Delete all installed actions.
 371  
 372  =item w expr
 373  X<debugger command, w>
 374  
 375  Add a global watch-expression.  We hope you know what one of these
 376  is, because they're supposed to be obvious.
 377  
 378  =item W expr
 379  X<debugger command, W>
 380  
 381  Delete watch-expression
 382  
 383  =item W *
 384  X<debugger command, W>
 385  
 386  Delete all watch-expressions.
 387  
 388  =item o
 389  X<debugger command, o>
 390  
 391  Display all options
 392  
 393  =item o booloption ...
 394  X<debugger command, o>
 395  
 396  Set each listed Boolean option to the value C<1>.
 397  
 398  =item o anyoption? ...
 399  X<debugger command, o>
 400  
 401  Print out the value of one or more options.
 402  
 403  =item o option=value ...
 404  X<debugger command, o>
 405  
 406  Set the value of one or more options.  If the value has internal
 407  whitespace, it should be quoted.  For example, you could set C<o
 408  pager="less -MQeicsNfr"> to call B<less> with those specific options.
 409  You may use either single or double quotes, but if you do, you must
 410  escape any embedded instances of same sort of quote you began with,
 411  as well as any escaping any escapes that immediately precede that
 412  quote but which are not meant to escape the quote itself.  In other
 413  words, you follow single-quoting rules irrespective of the quote;
 414  eg: C<o option='this isn\'t bad'> or C<o option="She said, \"Isn't
 415  it?\"">.
 416  
 417  For historical reasons, the C<=value> is optional, but defaults to
 418  1 only where it is safe to do so--that is, mostly for Boolean
 419  options.  It is always better to assign a specific value using C<=>.
 420  The C<option> can be abbreviated, but for clarity probably should
 421  not be.  Several options can be set together.  See L<"Configurable Options">
 422  for a list of these.
 423  
 424  =item < ?
 425  X<< debugger command, < >>
 426  
 427  List out all pre-prompt Perl command actions.
 428  
 429  =item < [ command ]
 430  X<< debugger command, < >>
 431  
 432  Set an action (Perl command) to happen before every debugger prompt.
 433  A multi-line command may be entered by backslashing the newlines.
 434  
 435  =item < *
 436  X<< debugger command, < >>
 437  
 438  Delete all pre-prompt Perl command actions.
 439  
 440  =item << command
 441  X<< debugger command, << >>
 442  
 443  Add an action (Perl command) to happen before every debugger prompt.
 444  A multi-line command may be entered by backwhacking the newlines.
 445  
 446  =item > ?
 447  X<< debugger command, > >>
 448  
 449  List out post-prompt Perl command actions.
 450  
 451  =item > command
 452  X<< debugger command, > >>
 453  
 454  Set an action (Perl command) to happen after the prompt when you've
 455  just given a command to return to executing the script.  A multi-line
 456  command may be entered by backslashing the newlines (we bet you
 457  couldn't have guessed this by now).
 458  
 459  =item > *
 460  X<< debugger command, > >>
 461  
 462  Delete all post-prompt Perl command actions.
 463  
 464  =item >> command
 465  X<<< debugger command, >> >>>
 466  
 467  Adds an action (Perl command) to happen after the prompt when you've
 468  just given a command to return to executing the script.  A multi-line
 469  command may be entered by backslashing the newlines.
 470  
 471  =item { ?
 472  X<debugger command, {>
 473  
 474  List out pre-prompt debugger commands.
 475  
 476  =item { [ command ]
 477  
 478  Set an action (debugger command) to happen before every debugger prompt.
 479  A multi-line command may be entered in the customary fashion.
 480  
 481  Because this command is in some senses new, a warning is issued if
 482  you appear to have accidentally entered a block instead.  If that's
 483  what you mean to do, write it as with C<;{ ... }> or even
 484  C<do { ... }>.
 485  
 486  =item { *
 487  X<debugger command, {>
 488  
 489  Delete all pre-prompt debugger commands.
 490  
 491  =item {{ command
 492  X<debugger command, {{>
 493  
 494  Add an action (debugger command) to happen before every debugger prompt.
 495  A multi-line command may be entered, if you can guess how: see above.
 496  
 497  =item ! number
 498  X<debugger command, !>
 499  
 500  Redo a previous command (defaults to the previous command).
 501  
 502  =item ! -number
 503  X<debugger command, !>
 504  
 505  Redo number'th previous command.
 506  
 507  =item ! pattern
 508  X<debugger command, !>
 509  
 510  Redo last command that started with pattern.
 511  See C<o recallCommand>, too.
 512  
 513  =item !! cmd
 514  X<debugger command, !!>
 515  
 516  Run cmd in a subprocess (reads from DB::IN, writes to DB::OUT) See
 517  C<o shellBang>, also.  Note that the user's current shell (well,
 518  their C<$ENV{SHELL}> variable) will be used, which can interfere
 519  with proper interpretation of exit status or signal and coredump
 520  information.
 521  
 522  =item source file
 523  X<debugger command, source>
 524  
 525  Read and execute debugger commands from I<file>.
 526  I<file> may itself contain C<source> commands.
 527  
 528  =item H -number
 529  X<debugger command, H>
 530  
 531  Display last n commands.  Only commands longer than one character are
 532  listed.  If I<number> is omitted, list them all.
 533  
 534  =item q or ^D
 535  X<debugger command, q>
 536  X<debugger command, ^D>
 537  
 538  Quit.  ("quit" doesn't work for this, unless you've made an alias)
 539  This is the only supported way to exit the debugger, though typing
 540  C<exit> twice might work.
 541  
 542  Set the C<inhibit_exit> option to 0 if you want to be able to step
 543  off the end the script.  You may also need to set $finished to 0
 544  if you want to step through global destruction.
 545  
 546  =item R
 547  X<debugger command, R>
 548  
 549  Restart the debugger by C<exec()>ing a new session.  We try to maintain
 550  your history across this, but internal settings and command-line options
 551  may be lost.
 552  
 553  The following setting are currently preserved: history, breakpoints,
 554  actions, debugger options, and the Perl command-line
 555  options B<-w>, B<-I>, and B<-e>.
 556  
 557  =item |dbcmd
 558  X<debugger command, |>
 559  
 560  Run the debugger command, piping DB::OUT into your current pager.
 561  
 562  =item ||dbcmd
 563  X<debugger command, ||>
 564  
 565  Same as C<|dbcmd> but DB::OUT is temporarily C<select>ed as well.
 566  
 567  =item = [alias value]
 568  X<debugger command, =>
 569  
 570  Define a command alias, like
 571  
 572      = quit q
 573  
 574  or list current aliases.
 575  
 576  =item command
 577  
 578  Execute command as a Perl statement.  A trailing semicolon will be
 579  supplied.  If the Perl statement would otherwise be confused for a
 580  Perl debugger, use a leading semicolon, too.
 581  
 582  =item m expr
 583  X<debugger command, m>
 584  
 585  List which methods may be called on the result of the evaluated
 586  expression.  The expression may evaluated to a reference to a
 587  blessed object, or to a package name.
 588  
 589  =item M
 590  X<debugger command, M>
 591  
 592  Displays all loaded modules and their versions
 593  
 594  
 595  =item man [manpage]
 596  X<debugger command, man>
 597  
 598  Despite its name, this calls your system's default documentation
 599  viewer on the given page, or on the viewer itself if I<manpage> is
 600  omitted.  If that viewer is B<man>, the current C<Config> information
 601  is used to invoke B<man> using the proper MANPATH or S<B<-M>
 602  I<manpath>> option.  Failed lookups of the form C<XXX> that match
 603  known manpages of the form I<perlXXX> will be retried.  This lets
 604  you type C<man debug> or C<man op> from the debugger.
 605  
 606  On systems traditionally bereft of a usable B<man> command, the
 607  debugger invokes B<perldoc>.  Occasionally this determination is
 608  incorrect due to recalcitrant vendors or rather more felicitously,
 609  to enterprising users.  If you fall into either category, just
 610  manually set the $DB::doccmd variable to whatever viewer to view
 611  the Perl documentation on your system.  This may be set in an rc
 612  file, or through direct assignment.  We're still waiting for a
 613  working example of something along the lines of:
 614  
 615      $DB::doccmd = 'netscape -remote http://something.here/';
 616  
 617  =back
 618  
 619  =head2 Configurable Options
 620  
 621  The debugger has numerous options settable using the C<o> command,
 622  either interactively or from the environment or an rc file.
 623  (./.perldb or ~/.perldb under Unix.)
 624  
 625  
 626  =over 12
 627  
 628  =item C<recallCommand>, C<ShellBang>
 629  X<debugger option, recallCommand>
 630  X<debugger option, ShellBang>
 631  
 632  The characters used to recall command or spawn shell.  By
 633  default, both are set to C<!>, which is unfortunate.
 634  
 635  =item C<pager>
 636  X<debugger option, pager>
 637  
 638  Program to use for output of pager-piped commands (those beginning
 639  with a C<|> character.)  By default, C<$ENV{PAGER}> will be used.
 640  Because the debugger uses your current terminal characteristics
 641  for bold and underlining, if the chosen pager does not pass escape
 642  sequences through unchanged, the output of some debugger commands
 643  will not be readable when sent through the pager.
 644  
 645  =item C<tkRunning>
 646  X<debugger option, tkRunning>
 647  
 648  Run Tk while prompting (with ReadLine).
 649  
 650  =item C<signalLevel>, C<warnLevel>, C<dieLevel>
 651  X<debugger option, signalLevel> X<debugger option, warnLevel>
 652  X<debugger option, dieLevel>
 653  
 654  Level of verbosity.  By default, the debugger leaves your exceptions
 655  and warnings alone, because altering them can break correctly running
 656  programs.  It will attempt to print a message when uncaught INT, BUS, or
 657  SEGV signals arrive.  (But see the mention of signals in L<BUGS> below.)
 658  
 659  To disable this default safe mode, set these values to something higher
 660  than 0.  At a level of 1, you get backtraces upon receiving any kind
 661  of warning (this is often annoying) or exception (this is
 662  often valuable).  Unfortunately, the debugger cannot discern fatal
 663  exceptions from non-fatal ones.  If C<dieLevel> is even 1, then your
 664  non-fatal exceptions are also traced and unceremoniously altered if they
 665  came from C<eval'ed> strings or from any kind of C<eval> within modules
 666  you're attempting to load.  If C<dieLevel> is 2, the debugger doesn't
 667  care where they came from:  It usurps your exception handler and prints
 668  out a trace, then modifies all exceptions with its own embellishments.
 669  This may perhaps be useful for some tracing purposes, but tends to hopelessly
 670  destroy any program that takes its exception handling seriously.
 671  
 672  =item C<AutoTrace>
 673  X<debugger option, AutoTrace>
 674  
 675  Trace mode (similar to C<t> command, but can be put into
 676  C<PERLDB_OPTS>).
 677  
 678  =item C<LineInfo>
 679  X<debugger option, LineInfo>
 680  
 681  File or pipe to print line number info to.  If it is a pipe (say,
 682  C<|visual_perl_db>), then a short message is used.  This is the
 683  mechanism used to interact with a slave editor or visual debugger,
 684  such as the special C<vi> or C<emacs> hooks, or the C<ddd> graphical
 685  debugger.
 686  
 687  =item C<inhibit_exit>
 688  X<debugger option, inhibit_exit>
 689  
 690  If 0, allows I<stepping off> the end of the script.
 691  
 692  =item C<PrintRet>
 693  X<debugger option, PrintRet>
 694  
 695  Print return value after C<r> command if set (default).
 696  
 697  =item C<ornaments>
 698  X<debugger option, ornaments>
 699  
 700  Affects screen appearance of the command line (see L<Term::ReadLine>).
 701  There is currently no way to disable these, which can render
 702  some output illegible on some displays, or with some pagers.
 703  This is considered a bug.
 704  
 705  =item C<frame>
 706  X<debugger option, frame>
 707  
 708  Affects the printing of messages upon entry and exit from subroutines.  If
 709  C<frame & 2> is false, messages are printed on entry only. (Printing
 710  on exit might be useful if interspersed with other messages.)
 711  
 712  If C<frame & 4>, arguments to functions are printed, plus context
 713  and caller info.  If C<frame & 8>, overloaded C<stringify> and
 714  C<tie>d C<FETCH> is enabled on the printed arguments.  If C<frame
 715  & 16>, the return value from the subroutine is printed.
 716  
 717  The length at which the argument list is truncated is governed by the
 718  next option:
 719  
 720  =item C<maxTraceLen>
 721  X<debugger option, maxTraceLen>
 722  
 723  Length to truncate the argument list when the C<frame> option's
 724  bit 4 is set.
 725  
 726  =item C<windowSize>
 727  X<debugger option, windowSize>
 728  
 729  Change the size of code list window (default is 10 lines).
 730  
 731  =back
 732  
 733  The following options affect what happens with C<V>, C<X>, and C<x>
 734  commands:
 735  
 736  =over 12
 737  
 738  =item C<arrayDepth>, C<hashDepth>
 739  X<debugger option, arrayDepth> X<debugger option, hashDepth>
 740  
 741  Print only first N elements ('' for all).
 742  
 743  =item C<dumpDepth>
 744  X<debugger option, dumpDepth>
 745  
 746  Limit recursion depth to N levels when dumping structures.
 747  Negative values are interpreted as infinity.  Default: infinity.
 748  
 749  =item C<compactDump>, C<veryCompact>
 750  X<debugger option, compactDump> X<debugger option, veryCompact>
 751  
 752  Change the style of array and hash output.  If C<compactDump>, short array
 753  may be printed on one line.
 754  
 755  =item C<globPrint>
 756  X<debugger option, globPrint>
 757  
 758  Whether to print contents of globs.
 759  
 760  =item C<DumpDBFiles>
 761  X<debugger option, DumpDBFiles>
 762  
 763  Dump arrays holding debugged files.
 764  
 765  =item C<DumpPackages>
 766  X<debugger option, DumpPackages>
 767  
 768  Dump symbol tables of packages.
 769  
 770  =item C<DumpReused>
 771  X<debugger option, DumpReused>
 772  
 773  Dump contents of "reused" addresses.
 774  
 775  =item C<quote>, C<HighBit>, C<undefPrint>
 776  X<debugger option, quote> X<debugger option, HighBit>
 777  X<debugger option, undefPrint>
 778  
 779  Change the style of string dump.  The default value for C<quote>
 780  is C<auto>; one can enable double-quotish or single-quotish format
 781  by setting it to C<"> or C<'>, respectively.  By default, characters
 782  with their high bit set are printed verbatim.
 783  
 784  =item C<UsageOnly>
 785  X<debugger option, UsageOnly>
 786  
 787  Rudimentary per-package memory usage dump.  Calculates total
 788  size of strings found in variables in the package.  This does not
 789  include lexicals in a module's file scope, or lost in closures.
 790  
 791  =back
 792  
 793  After the rc file is read, the debugger reads the C<$ENV{PERLDB_OPTS}>
 794  environment variable and parses this as the remainder of a "O ..."
 795  line as one might enter at the debugger prompt.  You may place the
 796  initialization options C<TTY>, C<noTTY>, C<ReadLine>, and C<NonStop>
 797  there.
 798  
 799  If your rc file contains:
 800  
 801    parse_options("NonStop=1 LineInfo=db.out AutoTrace");
 802  
 803  then your script will run without human intervention, putting trace
 804  information into the file I<db.out>.  (If you interrupt it, you'd
 805  better reset C<LineInfo> to F</dev/tty> if you expect to see anything.)
 806  
 807  =over 12
 808  
 809  =item C<TTY>
 810  X<debugger option, TTY>
 811  
 812  The TTY to use for debugging I/O.
 813  
 814  =item C<noTTY>
 815  X<debugger option, noTTY>
 816  
 817  If set, the debugger goes into C<NonStop> mode and will not connect to a TTY.  If
 818  interrupted (or if control goes to the debugger via explicit setting of
 819  $DB::signal or $DB::single from the Perl script), it connects to a TTY
 820  specified in the C<TTY> option at startup, or to a tty found at
 821  runtime using the C<Term::Rendezvous> module of your choice.
 822  
 823  This module should implement a method named C<new> that returns an object
 824  with two methods: C<IN> and C<OUT>.  These should return filehandles to use
 825  for debugging input and output correspondingly.  The C<new> method should
 826  inspect an argument containing the value of C<$ENV{PERLDB_NOTTY}> at
 827  startup, or C<"$ENV{HOME}/.perldbtty$$"> otherwise.  This file is not
 828  inspected for proper ownership, so security hazards are theoretically
 829  possible.
 830  
 831  =item C<ReadLine>
 832  X<debugger option, ReadLine>
 833  
 834  If false, readline support in the debugger is disabled in order
 835  to debug applications that themselves use ReadLine.
 836  
 837  =item C<NonStop>
 838  X<debugger option, NonStop>
 839  
 840  If set, the debugger goes into non-interactive mode until interrupted, or
 841  programmatically by setting $DB::signal or $DB::single.
 842  
 843  =back
 844  
 845  Here's an example of using the C<$ENV{PERLDB_OPTS}> variable:
 846  
 847      $ PERLDB_OPTS="NonStop frame=2" perl -d myprogram
 848  
 849  That will run the script B<myprogram> without human intervention,
 850  printing out the call tree with entry and exit points.  Note that
 851  C<NonStop=1 frame=2> is equivalent to C<N f=2>, and that originally,
 852  options could be uniquely abbreviated by the first letter (modulo
 853  the C<Dump*> options).  It is nevertheless recommended that you
 854  always spell them out in full for legibility and future compatibility.
 855  
 856  Other examples include
 857  
 858      $ PERLDB_OPTS="NonStop LineInfo=listing frame=2" perl -d myprogram
 859  
 860  which runs script non-interactively, printing info on each entry
 861  into a subroutine and each executed line into the file named F<listing>.
 862  (If you interrupt it, you would better reset C<LineInfo> to something
 863  "interactive"!)
 864  
 865  Other examples include (using standard shell syntax to show environment
 866  variable settings):
 867  
 868    $ ( PERLDB_OPTS="NonStop frame=1 AutoTrace LineInfo=tperl.out"
 869        perl -d myprogram )
 870  
 871  which may be useful for debugging a program that uses C<Term::ReadLine>
 872  itself.  Do not forget to detach your shell from the TTY in the window that
 873  corresponds to F</dev/ttyXX>, say, by issuing a command like
 874  
 875    $ sleep 1000000
 876  
 877  See L<perldebguts/"Debugger Internals"> for details.
 878  
 879  =head2 Debugger input/output
 880  
 881  =over 8
 882  
 883  =item Prompt
 884  
 885  The debugger prompt is something like
 886  
 887      DB<8>
 888  
 889  or even
 890  
 891      DB<<17>>
 892  
 893  where that number is the command number, and which you'd use to
 894  access with the built-in B<csh>-like history mechanism.  For example,
 895  C<!17> would repeat command number 17.  The depth of the angle
 896  brackets indicates the nesting depth of the debugger.  You could
 897  get more than one set of brackets, for example, if you'd already
 898  at a breakpoint and then printed the result of a function call that
 899  itself has a breakpoint, or you step into an expression via C<s/n/t
 900  expression> command.
 901  
 902  =item Multiline commands
 903  
 904  If you want to enter a multi-line command, such as a subroutine
 905  definition with several statements or a format, escape the newline
 906  that would normally end the debugger command with a backslash.
 907  Here's an example:
 908  
 909        DB<1> for (1..4) {         \
 910        cont:     print "ok\n";   \
 911        cont: }
 912        ok
 913        ok
 914        ok
 915        ok
 916  
 917  Note that this business of escaping a newline is specific to interactive
 918  commands typed into the debugger.
 919  
 920  =item Stack backtrace
 921  X<backtrace> X<stack, backtrace>
 922  
 923  Here's an example of what a stack backtrace via C<T> command might
 924  look like:
 925  
 926      $ = main::infested called from file `Ambulation.pm' line 10
 927      @ = Ambulation::legs(1, 2, 3, 4) called from file `camel_flea' line 7
 928      $ = main::pests('bactrian', 4) called from file `camel_flea' line 4
 929  
 930  The left-hand character up there indicates the context in which the
 931  function was called, with C<$> and C<@> meaning scalar or list
 932  contexts respectively, and C<.> meaning void context (which is
 933  actually a sort of scalar context).  The display above says
 934  that you were in the function C<main::infested> when you ran the
 935  stack dump, and that it was called in scalar context from line
 936  10 of the file I<Ambulation.pm>, but without any arguments at all,
 937  meaning it was called as C<&infested>.  The next stack frame shows
 938  that the function C<Ambulation::legs> was called in list context
 939  from the I<camel_flea> file with four arguments.  The last stack
 940  frame shows that C<main::pests> was called in scalar context,
 941  also from I<camel_flea>, but from line 4.
 942  
 943  If you execute the C<T> command from inside an active C<use>
 944  statement, the backtrace will contain both a C<require> frame and
 945  an C<eval>) frame.
 946  
 947  =item Line Listing Format
 948  
 949  This shows the sorts of output the C<l> command can produce:
 950  
 951      DB<<13>> l
 952    101:                @i{@i} = ();
 953    102:b               @isa{@i,$pack} = ()
 954    103                     if(exists $i{$prevpack} || exists $isa{$pack});
 955    104             }
 956    105
 957    106             next
 958    107==>              if(exists $isa{$pack});
 959    108
 960    109:a           if ($extra-- > 0) {
 961    110:                %isa = ($pack,1);
 962  
 963  Breakable lines are marked with C<:>.  Lines with breakpoints are
 964  marked by C<b> and those with actions by C<a>.  The line that's
 965  about to be executed is marked by C<< ==> >>.
 966  
 967  Please be aware that code in debugger listings may not look the same
 968  as your original source code.  Line directives and external source
 969  filters can alter the code before Perl sees it, causing code to move
 970  from its original positions or take on entirely different forms.
 971  
 972  =item Frame listing
 973  
 974  When the C<frame> option is set, the debugger would print entered (and
 975  optionally exited) subroutines in different styles.  See L<perldebguts>
 976  for incredibly long examples of these.
 977  
 978  =back
 979  
 980  =head2 Debugging compile-time statements
 981  
 982  If you have compile-time executable statements (such as code within
 983  BEGIN, UNITCHECK and CHECK blocks or C<use> statements), these will
 984  I<not> be stopped by debugger, although C<require>s and INIT blocks
 985  will, and compile-time statements can be traced with C<AutoTrace>
 986  option set in C<PERLDB_OPTS>).  From your own Perl code, however, you
 987  can transfer control back to the debugger using the following
 988  statement, which is harmless if the debugger is not running:
 989  
 990      $DB::single = 1;
 991  
 992  If you set C<$DB::single> to 2, it's equivalent to having
 993  just typed the C<n> command, whereas a value of 1 means the C<s>
 994  command.  The C<$DB::trace>  variable should be set to 1 to simulate
 995  having typed the C<t> command.
 996  
 997  Another way to debug compile-time code is to start the debugger, set a
 998  breakpoint on the I<load> of some module:
 999  
1000      DB<7> b load f:/perllib/lib/Carp.pm
1001    Will stop on load of `f:/perllib/lib/Carp.pm'.
1002  
1003  and then restart the debugger using the C<R> command (if possible).  One can use C<b
1004  compile subname> for the same purpose.
1005  
1006  =head2 Debugger Customization
1007  
1008  The debugger probably contains enough configuration hooks that you
1009  won't ever have to modify it yourself.  You may change the behaviour
1010  of debugger from within the debugger using its C<o> command, from
1011  the command line via the C<PERLDB_OPTS> environment variable, and
1012  from customization files.
1013  
1014  You can do some customization by setting up a F<.perldb> file, which
1015  contains initialization code.  For instance, you could make aliases
1016  like these (the last one is one people expect to be there):
1017  
1018      $DB::alias{'len'}  = 's/^len(.*)/p length($1)/';
1019      $DB::alias{'stop'} = 's/^stop (at|in)/b/';
1020      $DB::alias{'ps'}   = 's/^ps\b/p scalar /';
1021      $DB::alias{'quit'} = 's/^quit(\s*)/exit/';
1022  
1023  You can change options from F<.perldb> by using calls like this one;
1024  
1025      parse_options("NonStop=1 LineInfo=db.out AutoTrace=1 frame=2");
1026  
1027  The code is executed in the package C<DB>.  Note that F<.perldb> is
1028  processed before processing C<PERLDB_OPTS>.  If F<.perldb> defines the
1029  subroutine C<afterinit>, that function is called after debugger
1030  initialization ends.  F<.perldb> may be contained in the current
1031  directory, or in the home directory.  Because this file is sourced
1032  in by Perl and may contain arbitrary commands, for security reasons,
1033  it must be owned by the superuser or the current user, and writable
1034  by no one but its owner.
1035  
1036  You can mock TTY input to debugger by adding arbitrary commands to
1037  @DB::typeahead. For example, your F<.perldb> file might contain:
1038  
1039      sub afterinit { push @DB::typeahead, "b 4", "b 6"; }
1040  
1041  Which would attempt to set breakpoints on lines 4 and 6 immediately
1042  after debugger initialization. Note that @DB::typeahead is not a supported
1043  interface and is subject to change in future releases.
1044  
1045  If you want to modify the debugger, copy F<perl5db.pl> from the
1046  Perl library to another name and hack it to your heart's content.
1047  You'll then want to set your C<PERL5DB> environment variable to say
1048  something like this:
1049  
1050      BEGIN { require "myperl5db.pl" }
1051  
1052  As a last resort, you could also use C<PERL5DB> to customize the debugger
1053  by directly setting internal variables or calling debugger functions.
1054  
1055  Note that any variables and functions that are not documented in
1056  this document (or in L<perldebguts>) are considered for internal
1057  use only, and as such are subject to change without notice.
1058  
1059  =head2 Readline Support
1060  
1061  As shipped, the only command-line history supplied is a simplistic one
1062  that checks for leading exclamation points.  However, if you install
1063  the Term::ReadKey and Term::ReadLine modules from CPAN, you will
1064  have full editing capabilities much like GNU I<readline>(3) provides.
1065  Look for these in the F<modules/by-module/Term> directory on CPAN.
1066  These do not support normal B<vi> command-line editing, however.
1067  
1068  A rudimentary command-line completion is also available.
1069  Unfortunately, the names of lexical variables are not available for
1070  completion.
1071  
1072  =head2 Editor Support for Debugging
1073  
1074  If you have the FSF's version of B<emacs> installed on your system,
1075  it can interact with the Perl debugger to provide an integrated
1076  software development environment reminiscent of its interactions
1077  with C debuggers.
1078  
1079  Perl comes with a start file for making B<emacs> act like a
1080  syntax-directed editor that understands (some of) Perl's syntax.
1081  Look in the I<emacs> directory of the Perl source distribution.
1082  
1083  A similar setup by Tom Christiansen for interacting with any
1084  vendor-shipped B<vi> and the X11 window system is also available.
1085  This works similarly to the integrated multiwindow support that
1086  B<emacs> provides, where the debugger drives the editor.  At the
1087  time of this writing, however, that tool's eventual location in the
1088  Perl distribution was uncertain.
1089  
1090  Users of B<vi> should also look into B<vim> and B<gvim>, the mousey
1091  and windy version, for coloring of Perl keywords.
1092  
1093  Note that only perl can truly parse Perl, so all such CASE tools
1094  fall somewhat short of the mark, especially if you don't program
1095  your Perl as a C programmer might.
1096  
1097  =head2 The Perl Profiler
1098  X<profile> X<profiling> X<profiler>
1099  
1100  If you wish to supply an alternative debugger for Perl to run, just
1101  invoke your script with a colon and a package argument given to the
1102  B<-d> flag.  The most popular alternative debuggers for Perl is the
1103  Perl profiler.  Devel::DProf is now included with the standard Perl
1104  distribution.  To profile your Perl program in the file F<mycode.pl>,
1105  just type:
1106  
1107      $ perl -d:DProf mycode.pl
1108  
1109  When the script terminates the profiler will dump the profile
1110  information to a file called F<tmon.out>.  A tool like B<dprofpp>,
1111  also supplied with the standard Perl distribution, can be used to
1112  interpret the information in that profile.
1113  
1114  =head1 Debugging regular expressions
1115  X<regular expression, debugging>
1116  X<regex, debugging> X<regexp, debugging>
1117  
1118  C<use re 'debug'> enables you to see the gory details of how the Perl
1119  regular expression engine works. In order to understand this typically
1120  voluminous output, one must not only have some idea about how regular
1121  expression matching works in general, but also know how Perl's regular
1122  expressions are internally compiled into an automaton. These matters
1123  are explored in some detail in
1124  L<perldebguts/"Debugging regular expressions">.
1125  
1126  =head1 Debugging memory usage
1127  X<memory usage>
1128  
1129  Perl contains internal support for reporting its own memory usage,
1130  but this is a fairly advanced concept that requires some understanding
1131  of how memory allocation works.
1132  See L<perldebguts/"Debugging Perl memory usage"> for the details.
1133  
1134  =head1 SEE ALSO
1135  
1136  You did try the B<-w> switch, didn't you?
1137  
1138  L<perldebtut>,
1139  L<perldebguts>,
1140  L<re>,
1141  L<DB>,
1142  L<Devel::DProf>,
1143  L<dprofpp>,
1144  L<Dumpvalue>,
1145  and
1146  L<perlrun>.
1147  
1148  When debugging a script that uses #! and is thus normally found in
1149  $PATH, the -S option causes perl to search $PATH for it, so you don't
1150  have to type the path or C<which $scriptname>.
1151  
1152    $ perl -Sd foo.pl
1153  
1154  =head1 BUGS
1155  
1156  You cannot get stack frame information or in any fashion debug functions
1157  that were not compiled by Perl, such as those from C or C++ extensions.
1158  
1159  If you alter your @_ arguments in a subroutine (such as with C<shift>
1160  or C<pop>), the stack backtrace will not show the original values.
1161  
1162  The debugger does not currently work in conjunction with the B<-W>
1163  command-line switch, because it itself is not free of warnings.
1164  
1165  If you're in a slow syscall (like C<wait>ing, C<accept>ing, or C<read>ing
1166  from your keyboard or a socket) and haven't set up your own C<$SIG{INT}>
1167  handler, then you won't be able to CTRL-C your way back to the debugger,
1168  because the debugger's own C<$SIG{INT}> handler doesn't understand that
1169  it needs to raise an exception to longjmp(3) out of slow syscalls.