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