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