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