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