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