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