This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
pod/perlipc.pod patch
[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
14source code, set breakpoints, get stack backtraces, change the values of
15variables, etc. This is so convenient that you often fire up
16the debugger all by itself just to test out Perl constructs
17interactively to see what they do. For example:
18
19 perl -d -e 42
20
21In Perl, the debugger is not a separate program as it usually is in the
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
26pre-loads a Perl library file containing the debugger itself.
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
35(C<eval>'d) as Perl code in the current package. (The debugger uses the
36DB package for its own state information.)
37
38Leading white space before a command would cause the debugger to think
39it's I<NOT> a debugger command but for Perl, so be careful not to do
40that.
41
42=head2 Debugger Commands
43
44The debugger understands the following commands:
a0d0e21e
LW
45
46=over 12
47
4e1d3b43
PP
48=item h [command]
49
50Prints out a help message.
51
52If you supply another debugger command as an argument to the C<h> command,
53it prints out the description for just that command. The special
54argument of C<h h> produces a more compact help listing, designed to fit
55together on one screen.
56
57If the output the C<h> command (or any command, for that matter) scrolls
58past your screen, either precede the command with a leading pipe symbol so
59it's run through your pager, as in
60
61 DB> |h
62
63=item p expr
64
36477c24 65Same as C<print {$DB::OUT} expr> in the current package. In particular,
4e1d3b43
PP
66since this is just Perl's own B<print> function, this means that nested
67data structures and objects are not dumped, unlike with the C<x> command.
68
69=item x expr
70
71Evals its expression in list context and dumps out the result
72in a pretty-printed fashion. Nested data structures are printed out
73recursively, unlike the C<print> function.
74
36477c24
PP
75The details of printout are governed by multiple C<O>ptions.
76
4e1d3b43
PP
77=item V [pkg [vars]]
78
79Display all (or some) variables in package (defaulting to the C<main>
80package) using a data pretty-printer (hashes show their keys and values so
81you see what's what, control characters are made printable, etc.). Make
82sure you don't put the type specifier (like C<$>) there, just the symbol
83names, like this:
84
85 V DB filename line
86
87Use C<~pattern> and C<!pattern> for positive and negative regexps.
a0d0e21e 88
4e1d3b43
PP
89Nested data structures are printed out in a legible fashion, unlike
90the C<print> function.
91
36477c24
PP
92The details of printout are governed by multiple C<O>ptions.
93
4e1d3b43
PP
94=item X [vars]
95
96Same as C<V currentpackage [vars]>.
a0d0e21e
LW
97
98=item T
99
4e1d3b43 100Produce a stack backtrace. See below for details on its output.
a0d0e21e 101
4e1d3b43 102=item s [expr]
a0d0e21e
LW
103
104Single step. Executes until it reaches the beginning of another
4e1d3b43
PP
105statement, descending into subroutine calls. If an expression is
106supplied that includes function calls, it too will be single-stepped.
a0d0e21e
LW
107
108=item n
109
110Next. Executes over subroutine calls, until it reaches the beginning
111of the next statement.
112
184e9718 113=item E<lt>CRE<gt>
a0d0e21e 114
4e1d3b43 115Repeat last C<n> or C<s> command.
a0d0e21e 116
36477c24 117=item c [line|sub]
a0d0e21e 118
4e1d3b43 119Continue, optionally inserting a one-time-only breakpoint
36477c24 120at the specified line or subroutine.
a0d0e21e 121
4e1d3b43 122=item l
a0d0e21e 123
4e1d3b43 124List next window of lines.
a0d0e21e
LW
125
126=item l min+incr
127
4e1d3b43 128List C<incr+1> lines starting at C<min>.
a0d0e21e
LW
129
130=item l min-max
131
4e1d3b43 132List lines C<min> through C<max>.
a0d0e21e
LW
133
134=item l line
135
4e1d3b43 136List a single line.
a0d0e21e 137
4e1d3b43 138=item l subname
a0d0e21e 139
4e1d3b43 140List first window of lines from subroutine.
a0d0e21e
LW
141
142=item -
143
4e1d3b43 144List previous window of lines.
a0d0e21e 145
4e1d3b43 146=item w [line]
a0d0e21e 147
4e1d3b43 148List window (a few lines) around the current line.
a0d0e21e 149
4e1d3b43 150=item .
a0d0e21e 151
4e1d3b43
PP
152Return debugger pointer to the last-executed line and
153print it out.
154
155=item f filename
156
157Switch to viewing a different file.
a0d0e21e
LW
158
159=item /pattern/
160
4e1d3b43 161Search forwards for pattern; final / is optional.
a0d0e21e
LW
162
163=item ?pattern?
164
4e1d3b43 165Search backwards for pattern; final ? is optional.
a0d0e21e
LW
166
167=item L
168
36477c24 169List all breakpoints and actions.
a0d0e21e 170
4e1d3b43 171=item S [[!]pattern]
a0d0e21e 172
4e1d3b43 173List subroutine names [not] matching pattern.
a0d0e21e
LW
174
175=item t
176
36477c24 177Toggle trace mode (see also C<AutoTrace> C<O>ption).
4e1d3b43
PP
178
179=item t expr
180
181Trace through execution of expr. For example:
182
183 $ perl -de 42
184 Stack dump during die enabled outside of evals.
a0d0e21e 185
4e1d3b43
PP
186 Loading DB routines from perl5db.pl patch level 0.94
187 Emacs support available.
188
189 Enter h or `h h' for help.
190
191 main::(-e:1): 0
192 DB<1> sub foo { 14 }
193
194 DB<2> sub bar { 3 }
195
196 DB<3> t print foo() * bar()
197 main::((eval 172):3): print foo() + bar();
198 main::foo((eval 168):2):
199 main::bar((eval 170):2):
200 42
36477c24
PP
201
202or, with the C<O>ption C<frame=2> set,
203
204 DB<4> O f=2
205 frame = '2'
206 DB<5> t print foo() * bar()
207 3: foo() * bar()
208 entering main::foo
209 2: sub foo { 14 };
210 exited main::foo
211 entering main::bar
212 2: sub bar { 3 };
213 exited main::bar
214 42
4e1d3b43
PP
215
216=item b [line] [condition]
a0d0e21e
LW
217
218Set a breakpoint. If line is omitted, sets a breakpoint on the line
4e1d3b43 219that is about to be executed. If a condition is specified, it's
a0d0e21e
LW
220evaluated each time the statement is reached and a breakpoint is taken
221only if the condition is true. Breakpoints may only be set on lines
4e1d3b43 222that begin an executable statement. Conditions don't use B<if>:
a0d0e21e
LW
223
224 b 237 $x > 30
36477c24 225 b 237 ++$count237 < 11
a0d0e21e
LW
226 b 33 /pattern/i
227
4e1d3b43 228=item b subname [condition]
a0d0e21e 229
4e1d3b43 230Set a breakpoint at the first line of the named subroutine.
a0d0e21e 231
36477c24
PP
232=item b postpone subname [condition]
233
234Set breakpoint at first line of subroutine after it is compiled.
235
236=item b load filename
237
238Set breakpoint at the first executed line of the file.
239
4e1d3b43 240=item d [line]
a0d0e21e 241
4e1d3b43
PP
242Delete a breakpoint at the specified line. If line is omitted, deletes
243the breakpoint on the line that is about to be executed.
a0d0e21e
LW
244
245=item D
246
4e1d3b43
PP
247Delete all installed breakpoints.
248
249=item a [line] command
250
251Set an action to be done before the line is executed.
252The sequence of steps taken by the debugger is
253
254=over 3
255
256=item 1
257
258check for a breakpoint at this line
259
260=item 2
261
262print the line if necessary (tracing)
263
264=item 3
265
266do any actions associated with that line
267
268=item 4
269
270prompt user if at a breakpoint or in single-step
271
272=item 5
273
274evaluate line
275
276=back
a0d0e21e 277
4e1d3b43
PP
278For example, this will print out C<$foo> every time line
27953 is passed:
a0d0e21e 280
4e1d3b43 281 a 53 print "DB FOUND $foo\n"
a0d0e21e
LW
282
283=item A
284
4e1d3b43
PP
285Delete all installed actions.
286
287=item O [opt[=val]] [opt"val"] [opt?]...
288
289Set or query values of options. val defaults to 1. opt can
290be abbreviated. Several options can be listed.
291
292=over 12
293
294=item recallCommand, ShellBang
295
296The characters used to recall command or spawn shell. By
297default, these are both set to C<!>.
298
299=item pager
300
301Program to use for output of pager-piped commands (those
302beginning with a C<|> character.) By default,
303C<$ENV{PAGER}> will be used.
304
36477c24
PP
305=item tkRunning
306
307Run Tk while prompting (with ReadLine).
308
309=item signalLevel, warnLevel, dieLevel
310
311Level of verbosity.
312
313=item AutoTrace
314
315Where to print all the breakable points in the executed program
316(similar to C<t> command, but can be put into C<PERLDB_OPTS>).
317
318=item LineInfo
319
320File or pipe to print line number info to. If it is a
321pipe, then a short, "emacs like" message is used.
322
323=item C<inhibit_exit>
324
325If 0, allows I<stepping off> the end of the script.
326
327=item C<PrintRet>
328
329affects printing of return value after C<r> command.
330
331=item C<frame>
332
333affects printing messages on entry and exit from subroutines. If
334C<frame & 2> is false, messages are printed on entry only. (Printing
335on exit may be useful if interdispersed with other messages.)
336
337If C<frame & 4>, arguments to functions are printed as well as the
338context and caller info.
339
4e1d3b43
PP
340=back
341
342The following options affect what happens with C<V>, C<X>, and C<x>
343commands:
344
345=over 12
346
347=item arrayDepth, hashDepth
348
349Print only first N elements ('' for all).
350
351=item compactDump, veryCompact
352
353Change style of array and hash dump.
354
355=item globPrint
356
357Whether to print contents of globs.
358
359=item DumpDBFiles
360
361Dump arrays holding debugged files.
362
363=item DumpPackages
364
365Dump symbol tables of packages.
366
367=item quote, HighBit, undefPrint
368
369Change style of string dump.
370
36477c24 371=back
4e1d3b43 372
36477c24
PP
373During startup options are initialized from C<$ENV{PERLDB_OPTS}>.
374You can put additional initialization options C<TTY>, C<noTTY>,
375C<ReadLine>, and C<NonStop> there.
376
377Example rc file:
4e1d3b43 378
36477c24 379 &parse_options("NonStop=1 LineInfo=db.out AutoTrace");
4e1d3b43 380
36477c24
PP
381The script will run without human intervention, putting trace information
382into the file I<db.out>. (If you interrupt it, you would better reset
383C<LineInfo> to something "interactive"!)
4e1d3b43 384
36477c24 385=over 12
4e1d3b43 386
36477c24 387=item C<TTY>
4e1d3b43 388
36477c24
PP
389The TTY to use for debugging I/O.
390
391=item noTTY
392
393If set, goes in C<NonStop> mode. On interrupt if TTY is not set uses the
394value of C<noTTY> or "/tmp/perldbtty$$" to find TTY using
395C<Term::Rendezvous>. Current variant is to have the name of TTY in this
396file.
397
398=item C<noTTY>
399
400If set, goes in C<NonStop> mode, and would not connect to a TTY. If
401interrupt (or if control goes to debugger via explicit setting of
402$DB::signal or $DB::single from the Perl script), connects to a TTY
403specified by the C<TTY> option at startup, or to a TTY found at
404runtime using C<Term::Rendezvous> module of your choice.
405
406This module should implement a method C<new> which returns an object
407with two methods: C<IN> and C<OUT>, returning two filehandles to use
408for debugging input and output correspondingly. Method C<new> may
409inspect an argument which is a value of C<$ENV{PERLDB_NOTTY}> at
410startup, or is C<"/tmp/perldbtty$$"> otherwise.
411
412=item C<ReadLine>
413
414If false, readline support in debugger is disabled, so you can debug
415ReadLine applications.
416
417=item C<NonStop>
418
419If set, debugger goes into non-interactive mode until interrupted, or
420programmatically by setting $DB::signal or $DB::single.
421
422=back
423
424Here's an example of using the C<$ENV{PERLDB_OPTS}> variable:
4e1d3b43
PP
425
426 $ PERLDB_OPTS="N f=2" perl -d myprogram
427
428will run the script C<myprogram> without human intervention, printing
429out the call tree with entry and exit points. Note that C<N f=2> is
430equivalent to C<NonStop=1 frame=2>. Note also that at the moment when
431this documentation was written all the options to the debugger could
36477c24
PP
432be uniquely abbreviated by the first letter (with exception of
433C<Dump*> options).
4e1d3b43 434
36477c24 435Other examples may include
a0d0e21e 436
36477c24 437 $ PERLDB_OPTS="N f A L=listing" perl -d myprogram
a0d0e21e 438
36477c24
PP
439- runs script non-interactively, printing info on each entry into a
440subroutine and each executed line into the file F<listing>. (If you
441interrupt it, you would better reset C<LineInfo> to something
442"interactive"!)
443
444
445 $ env "PERLDB_OPTS=R=0 TTY=/dev/ttyc" perl -d myprogram
446
447may be useful for debugging a program which uses C<Term::ReadLine>
448itself. Do not forget detach shell from the TTY in the window which
449corresponds to F</dev/ttyc>, say, by issuing a command like
450
451 $ sleep 1000000
452
453See L<"Debugger Internals"> below for more details.
454
455=item E<lt> [ command ]
456
457Set an action (Perl command) to happen before every debugger prompt.
458A multiline command may be entered by backslashing the newlines. If
459C<command> is missing, resets the list of actions.
460
461=item E<lt>E<lt> command
462
463Add an action (Perl command) to happen before every debugger prompt.
464A multiline command may be entered by backslashing the newlines.
a0d0e21e 465
184e9718 466=item E<gt> command
a0d0e21e 467
36477c24
PP
468Set an action (Perl command) to happen after the prompt when you've
469just given a command to return to executing the script. A multiline
470command may be entered by backslashing the newlines. If C<command> is
471missing, resets the list of actions.
472
473=item E<gt>E<gt> command
474
475Adds an action (Perl command) to happen after the prompt when you've
476just given a command to return to executing the script. A multiline
477command may be entered by backslashing the newlines.
478
479=item { [ command ]
480
481Set an action (debugger command) to happen before every debugger prompt.
482A multiline command may be entered by backslashing the newlines. If
483C<command> is missing, resets the list of actions.
484
485=item {{ command
486
487Add an action (debugger command) to happen before every debugger prompt.
488A multiline command may be entered by backslashing the newlines.
a0d0e21e 489
4e1d3b43 490=item ! number
a0d0e21e 491
4e1d3b43 492Redo a previous command (default previous command).
a0d0e21e 493
4e1d3b43 494=item ! -number
a0d0e21e 495
4e1d3b43 496Redo number'th-to-last command.
a0d0e21e 497
4e1d3b43 498=item ! pattern
a0d0e21e 499
4e1d3b43
PP
500Redo last command that started with pattern.
501See C<O recallCommand>, too.
a0d0e21e 502
4e1d3b43 503=item !! cmd
a0d0e21e 504
4e1d3b43
PP
505Run cmd in a subprocess (reads from DB::IN, writes to DB::OUT)
506See C<O shellBang> too.
a0d0e21e
LW
507
508=item H -number
509
510Display last n commands. Only commands longer than one character are
511listed. If number is omitted, lists them all.
512
513=item q or ^D
514
36477c24
PP
515Quit. ("quit" doesn't work for this.) This is the only supported way
516to exit the debugger, though typing C<exit> twice may do it too.
517
518Set an C<O>ption C<inhibit_exit> to 0 if you want to be able to I<step
519off> the end the script. You may also need to set C<$finished> to 0 at
520some moment if you want to step through global destruction.
a0d0e21e 521
4e1d3b43
PP
522=item R
523
524Restart the debugger by B<exec>ing a new session. It tries to maintain
525your history across this, but internal settings and command line options
526may be lost.
527
36477c24
PP
528Currently the following setting are preserved: history, breakpoints
529and actions, debugger C<O>ptions and the following command-line
530options: B<-w>, B<-I>, B<-e>.
531
4e1d3b43
PP
532=item |dbcmd
533
534Run debugger command, piping DB::OUT to current pager.
535
536=item ||dbcmd
537
538Same as C<|dbcmd> but DB::OUT is temporarily B<select>ed as well.
539Often used with commands that would otherwise produce long
540output, such as
541
542 |V main
543
544=item = [alias value]
545
546Define a command alias, or list current aliases.
547
a0d0e21e
LW
548=item command
549
550Execute command as a Perl statement. A missing semicolon will be
551supplied.
552
553=item p expr
554
555Same as C<print DB::OUT expr>. The DB::OUT filehandle is opened to
556/dev/tty, regardless of where STDOUT may be redirected to.
557
558=back
559
4e1d3b43
PP
560The debugger prompt is something like
561
562 DB<8>
563
564or even
565
566 DB<<17>>
567
568where that number is the command number, which you'd use to access with
569the built-in B<csh>-like history mechanism, e.g. C<!17> would repeat
570command number 17. The number of angle brackets indicates the depth of
571the debugger. You could get more than one set of brackets, for example, if
572you'd already at a breakpoint and then printed out the result of a
36477c24
PP
573function call that itself also has a breakpoint, or you step into an
574expression via C<s/n/t expression> command.
4e1d3b43
PP
575
576If you want to enter a multi-line command, such as a subroutine
577definition with several statements, you may escape the newline that would
578normally end the debugger command with a backslash. Here's an example:
a0d0e21e 579
4e1d3b43
PP
580 DB<1> for (1..4) { \
581 cont: print "ok\n"; \
582 cont: }
583 ok
584 ok
585 ok
586 ok
587
588Note that this business of escaping a newline is specific to interactive
589commands typed into the debugger.
590
591Here's an example of what a stack backtrace might look like:
592
593 $ = main::infested called from file `Ambulation.pm' line 10
594 @ = Ambulation::legs(1, 2, 3, 4) called from file `camel_flea' line 7
595 $ = main::pests('bactrian', 4) called from file `camel_flea' line 4
596
597The left-hand character up there tells whether the function was called
598in a scalar or list context (we bet you can tell which is which). What
599that says is that you were in the function C<main::infested> when you ran
600the stack dump, and that it was called in a scalar context from line 10
601of the file I<Ambulation.pm>, but without any arguments at all, meaning
602it was called as C<&infested>. The next stack frame shows that the
603function C<Ambulation::legs> was called in a list context from the
604I<camel_flea> file with four arguments. The last stack frame shows that
605C<main::pests> was called in a scalar context, also from I<camel_flea>,
606but from line 4.
607
608If you have any compile-time executable statements (code within a BEGIN
609block or a C<use> statement), these will C<NOT> be stopped by debugger,
36477c24
PP
610although C<require>s will (and compile-time statements can be traced
611with C<AutoTrace> option set in C<PERLDB_OPTS>). From your own Perl
612code, however, you can
4e1d3b43
PP
613transfer control back to the debugger using the following statement,
614which is harmless if the debugger is not running:
a0d0e21e
LW
615
616 $DB::single = 1;
617
4e1d3b43
PP
618If you set C<$DB::single> to the value 2, it's equivalent to having
619just typed the C<n> command, whereas a value of 1 means the C<s>
620command. The C<$DB::trace> variable should be set to 1 to simulate
621having typed the C<t> command.
622
623=head2 Debugger Customization
a0d0e21e 624
36477c24
PP
625Most probably you not want to modify the debugger, it contains enough
626hooks to satisfy most needs. You may change the behaviour of debugger
627from the debugger itself, using C<O>ptions, from the command line via
628C<PERLDB_OPTS> environment variable, and from I<customization files>.
a0d0e21e
LW
629
630You can do some customization by setting up a F<.perldb> file which
631contains initialization code. For instance, you could make aliases
4e1d3b43 632like these (the last one is one people expect to be there):
a0d0e21e 633
4e1d3b43 634 $DB::alias{'len'} = 's/^len(.*)/p length($1)/';
a0d0e21e 635 $DB::alias{'stop'} = 's/^stop (at|in)/b/';
4e1d3b43
PP
636 $DB::alias{'ps'} = 's/^ps\b/p scalar /';
637 $DB::alias{'quit'} = 's/^quit(\s*)/exit\$/';
638
36477c24
PP
639One changes options from F<.perldb> file via calls like this one;
640
641 parse_options("NonStop=1 LineInfo=db.out AutoTrace=1 frame=2");
642
643(the code is executed in the package C<DB>). Note that F<.perldb> is
644processed before processing C<PERLDB_OPTS>. If F<.perldb> defines the
645subroutine C<afterinit>, it is called after all the debugger
646initialization ends. F<.perldb> may be contained in the current
647directory, or in the C<LOGDIR>/C<HOME> directory.
648
649If you want to modify the debugger, copy F<perl5db.pl> from the Perl
650library to another name and modify it as necessary. You'll also want
651to set your C<PERL5DB> environment variable to say something like this:
652
653 BEGIN { require "myperl5db.pl" }
654
655As the last resort, one can use C<PERL5DB> to customize debugger by
656directly setting internal variables or calling debugger functions.
657
4e1d3b43
PP
658=head2 Readline Support
659
660As shipped, the only command line history supplied is a simplistic one
661that checks for leading exclamation points. However, if you install
662the Term::ReadKey and Term::ReadLine modules from CPAN, you will
663have full editing capabilities much like GNU I<readline>(3) provides.
664Look for these in the F<modules/by-module/Term> directory on CPAN.
665
666=head2 Editor Support for Debugging
667
668If you have GNU B<emacs> installed on your system, it can interact with
669the Perl debugger to provide an integrated software development
670environment reminiscent of its interactions with C debuggers.
671
672Perl is also delivered with a start file for making B<emacs> act like a
673syntax-directed editor that understands (some of) Perl's syntax. Look in
674the I<emacs> directory of the Perl source distribution.
675
676(Historically, a similar setup for interacting with B<vi> and the
677X11 window system had also been available, but at the time of this
678writing, no debugger support for B<vi> currently exists.)
679
680=head2 The Perl Profiler
681
682If you wish to supply an alternative debugger for Perl to run, just
683invoke your script with a colon and a package argument given to the B<-d>
684flag. One of the most popular alternative debuggers for Perl is
685B<DProf>, the Perl profiler. As of this writing, B<DProf> is not
686included with the standard Perl distribution, but it is expected to
687be included soon, for certain values of "soon".
688
689Meanwhile, you can fetch the Devel::Dprof module from CPAN. Assuming
690it's properly installed on your system, to profile your Perl program in
691the file F<mycode.pl>, just type:
692
693 perl -d:DProf mycode.pl
694
695When the script terminates the profiler will dump the profile information
696to a file called F<tmon.out>. A tool like B<dprofpp> (also supplied with
697the Devel::DProf package) can be used to interpret the information which is
698in that profile.
699
36477c24 700=head2 Debugger support in perl
4e1d3b43
PP
701
702When you call the B<caller> function from package DB, Perl sets the
703C<@DB::args> array to contain the arguments that stack frame was called
36477c24 704with.
4e1d3b43 705
36477c24
PP
706If perl is run with B<-d> option, the following additional features
707are enabled:
a0d0e21e 708
36477c24 709=over
4e1d3b43 710
36477c24 711=item *
4e1d3b43 712
36477c24
PP
713Perl inserts the contents of C<$ENV{PERL5DB}> (or C<BEGIN {require
714'perl5db.pl'}> if not present) before the first line of the
715application.
4e1d3b43 716
36477c24 717=item *
4e1d3b43 718
36477c24
PP
719The array C<@{"_<$filename"}> is the line-by-line contents of
720$filename for all the compiled files. Same for C<eval>ed strings which
721contain subroutines, or which are currently executed. The C<$filename>
722for C<eval>ed strings looks like C<(eval 34)>.
4e1d3b43 723
36477c24 724=item *
4e1d3b43 725
36477c24
PP
726The hash C<%{"_<$filename"}> contains breakpoints and action (it is
727keyed by line number), and individual entries are settable (as opposed
728to the whole hash). Only true/false is important to Perl, though the
729values used by F<perl5db.pl> have the form
730C<"$break_condition\0$action">. Values are magical in numeric context:
731they are zeros if the line is not breakable.
4e1d3b43 732
36477c24
PP
733Same for evaluated strings which contain subroutines, or which are
734currently executed. The C<$filename> for C<eval>ed strings looks like
735C<(eval 34)>.
4e1d3b43 736
36477c24 737=item *
4e1d3b43 738
36477c24
PP
739The scalar C<${"_<$filename"}> contains C<"_<$filename">. Same for
740evaluated strings which contain subroutines, or which are currently
741executed. The C<$filename> for C<eval>ed strings looks like C<(eval
74234)>.
4e1d3b43 743
36477c24 744=item *
4e1d3b43 745
36477c24
PP
746After each C<require>d file is compiled, but before it is executed,
747C<DB::postponed(*{"_<$filename"})> is called (if subroutine
748C<DB::postponed> exists). Here the $filename is the expanded name of
749the C<require>d file (as found in values of C<%INC>).
4e1d3b43 750
36477c24 751=item *
4e1d3b43 752
36477c24
PP
753After each subroutine C<subname> is compiled existence of
754C<$DB::postponed{subname}> is checked. If this key exists,
755C<DB::postponed(subname)> is called (if subroutine C<DB::postponed>
756exists).
4e1d3b43 757
36477c24 758=item *
4e1d3b43 759
36477c24
PP
760A hash C<%DB::sub> is maintained, with keys being subroutine names,
761values having the form C<filename:startline-endline>. C<filename> has
762the form C<(eval 31)> for subroutines defined inside C<eval>s.
4e1d3b43 763
36477c24
PP
764=item *
765
766When an exection of the application reaches a place that can have a
767breakpoint, a call to C<DB::DB()> is performed if any one of
768variables $DB::trace, $DB::single, $DB::signal is true. (Note that
769these variables are not C<local>izable.) This feature is disabled when
770the control is inside C<DB::DB()> or functions called from it (unless
771C<$^D & 1 E<lt>E<lt> 30>).
772
773=item *
774
775When an exection of the application reaches a subroutine call, a call
776to C<&DB::sub>(I<args>) is performed instead, with C<$DB::sub> being
777the name of the called subroutine. (Unless the subroutine is compiled
778in the package C<DB>.)
4e1d3b43
PP
779
780=back
a0d0e21e 781
36477c24
PP
782Note that no subroutine call is possible until C<&DB::sub> is defined
783(for subroutines outside of package C<DB>). (In fact, for the
784standard debugger the same is true if C<$DB::deep> (how many levels of
785recursion deep into the debugger you can go before a mandatory break)
786is not defined.)
787
788=head2 Debugger Internals
789
790At the start, the debugger reads your rc file (F<./.perldb> or
791F<~/.perldb> under UNIX), which can set important options. This file may
792define a subroutine C<&afterinit> to be executed after the debugger is
793initialized.
794
795After the rc file is read, the debugger reads environment variable
796PERLDB_OPTS and parses it as a rest of C<O ...> line in debugger prompt.
797
798It also maintains magical internal variables, such as C<@DB::dbline>,
799C<%DB::dbline>, which are aliases for C<@{"::_<current_file"}>
800C<%{"::_<current_file"}>. Here C<current_file> is the currently
801selected (with the debugger's C<f> command, or by flow of execution)
802file.
803
804Some functions are provided to simplify customization. See L<"Debugger
805Customization"> for description of C<DB::parse_options(string)>. The
806function C<DB::dump_trace(skip[, count])> skips the specified number
807of frames, and returns an array containing info about the caller
808frames (all if C<count> is missing). Each entry is a hash with keys
809C<context> (C<$> or C<@>), C<sub> (subroutine name, or info about
810eval), C<args> (C<undef> or a reference to an array), C<file> and
811C<line>.
812
813The function C<DB::print_trace(FH, skip[, count[, short]])> prints
814formatted info about caller frames. The last two functions may be
815convenient as arguments to C<E<lt>>, C<E<lt>E<lt>> commands.
816
a0d0e21e
LW
817=head2 Other resources
818
819You did try the B<-w> switch, didn't you?
820
821=head1 BUGS
822
4e1d3b43
PP
823You cannot get the stack frame information or otherwise debug functions
824that were not compiled by Perl, such as C or C++ extensions.
a0d0e21e 825
4e1d3b43
PP
826If you alter your @_ arguments in a subroutine (such as with B<shift>
827or B<pop>, the stack backtrace will not show the original values.
a0d0e21e 828
36477c24
PP
829Some subroutines are called without creating a call frame. This may
830confuse backtrace C<T> and output of C<fE<gt>=4>.