This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Remove bad advice from perllocale.pod
[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
5f05dabc 14source code, set breakpoints, get stack back-traces, change the values of
4e1d3b43
PP
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,
5f05dabc 66because this is just Perl's own B<print> function, this means that nested
4e1d3b43
PP
67data structures and objects are not dumped, unlike with the C<x> command.
68
69=item x expr
70
5f05dabc 71Evaluates its expression in list context and dumps out the result
4e1d3b43
PP
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
5f05dabc 100Produce a stack back-trace. 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 220evaluated each time the statement is reached and a breakpoint is taken
5f05dabc 221only if the condition is true. Breakpoints may be set on only 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
8ebc5c01
PP
254 1. check for a breakpoint at this line
255 2. print the line if necessary (tracing)
256 3. do any actions associated with that line
257 4. prompt user if at a breakpoint or in single-step
258 5. evaluate line
a0d0e21e 259
4e1d3b43
PP
260For example, this will print out C<$foo> every time line
26153 is passed:
a0d0e21e 262
4e1d3b43 263 a 53 print "DB FOUND $foo\n"
a0d0e21e
LW
264
265=item A
266
4e1d3b43
PP
267Delete all installed actions.
268
269=item O [opt[=val]] [opt"val"] [opt?]...
270
271Set or query values of options. val defaults to 1. opt can
272be abbreviated. Several options can be listed.
273
274=over 12
275
276=item recallCommand, ShellBang
277
278The characters used to recall command or spawn shell. By
279default, these are both set to C<!>.
280
281=item pager
282
283Program to use for output of pager-piped commands (those
284beginning with a C<|> character.) By default,
285C<$ENV{PAGER}> will be used.
286
36477c24
PP
287=item tkRunning
288
289Run Tk while prompting (with ReadLine).
290
291=item signalLevel, warnLevel, dieLevel
292
293Level of verbosity.
294
295=item AutoTrace
296
297Where to print all the breakable points in the executed program
298(similar to C<t> command, but can be put into C<PERLDB_OPTS>).
299
300=item LineInfo
301
302File or pipe to print line number info to. If it is a
303pipe, then a short, "emacs like" message is used.
304
305=item C<inhibit_exit>
306
307If 0, allows I<stepping off> the end of the script.
308
309=item C<PrintRet>
310
311affects printing of return value after C<r> command.
312
313=item C<frame>
314
315affects printing messages on entry and exit from subroutines. If
316C<frame & 2> is false, messages are printed on entry only. (Printing
5f05dabc 317on exit may be useful if inter(di)spersed with other messages.)
36477c24
PP
318
319If C<frame & 4>, arguments to functions are printed as well as the
320context and caller info.
321
4e1d3b43
PP
322=back
323
324The following options affect what happens with C<V>, C<X>, and C<x>
325commands:
326
327=over 12
328
329=item arrayDepth, hashDepth
330
331Print only first N elements ('' for all).
332
333=item compactDump, veryCompact
334
335Change style of array and hash dump.
336
337=item globPrint
338
339Whether to print contents of globs.
340
341=item DumpDBFiles
342
343Dump arrays holding debugged files.
344
345=item DumpPackages
346
347Dump symbol tables of packages.
348
349=item quote, HighBit, undefPrint
350
351Change style of string dump.
352
36477c24 353=back
4e1d3b43 354
36477c24
PP
355During startup options are initialized from C<$ENV{PERLDB_OPTS}>.
356You can put additional initialization options C<TTY>, C<noTTY>,
357C<ReadLine>, and C<NonStop> there.
358
359Example rc file:
4e1d3b43 360
36477c24 361 &parse_options("NonStop=1 LineInfo=db.out AutoTrace");
4e1d3b43 362
36477c24
PP
363The script will run without human intervention, putting trace information
364into the file I<db.out>. (If you interrupt it, you would better reset
365C<LineInfo> to something "interactive"!)
4e1d3b43 366
36477c24 367=over 12
4e1d3b43 368
36477c24 369=item C<TTY>
4e1d3b43 370
36477c24
PP
371The TTY to use for debugging I/O.
372
373=item noTTY
374
375If set, goes in C<NonStop> mode. On interrupt if TTY is not set uses the
376value of C<noTTY> or "/tmp/perldbtty$$" to find TTY using
377C<Term::Rendezvous>. Current variant is to have the name of TTY in this
378file.
379
380=item C<noTTY>
381
382If set, goes in C<NonStop> mode, and would not connect to a TTY. If
383interrupt (or if control goes to debugger via explicit setting of
384$DB::signal or $DB::single from the Perl script), connects to a TTY
385specified by the C<TTY> option at startup, or to a TTY found at
386runtime using C<Term::Rendezvous> module of your choice.
387
388This module should implement a method C<new> which returns an object
389with two methods: C<IN> and C<OUT>, returning two filehandles to use
390for debugging input and output correspondingly. Method C<new> may
391inspect an argument which is a value of C<$ENV{PERLDB_NOTTY}> at
392startup, or is C<"/tmp/perldbtty$$"> otherwise.
393
394=item C<ReadLine>
395
396If false, readline support in debugger is disabled, so you can debug
397ReadLine applications.
398
399=item C<NonStop>
400
401If set, debugger goes into non-interactive mode until interrupted, or
402programmatically by setting $DB::signal or $DB::single.
403
404=back
405
406Here's an example of using the C<$ENV{PERLDB_OPTS}> variable:
4e1d3b43
PP
407
408 $ PERLDB_OPTS="N f=2" perl -d myprogram
409
410will run the script C<myprogram> without human intervention, printing
411out the call tree with entry and exit points. Note that C<N f=2> is
412equivalent to C<NonStop=1 frame=2>. Note also that at the moment when
413this documentation was written all the options to the debugger could
36477c24
PP
414be uniquely abbreviated by the first letter (with exception of
415C<Dump*> options).
4e1d3b43 416
36477c24 417Other examples may include
a0d0e21e 418
36477c24 419 $ PERLDB_OPTS="N f A L=listing" perl -d myprogram
a0d0e21e 420
36477c24
PP
421- runs script non-interactively, printing info on each entry into a
422subroutine and each executed line into the file F<listing>. (If you
423interrupt it, you would better reset C<LineInfo> to something
424"interactive"!)
425
426
427 $ env "PERLDB_OPTS=R=0 TTY=/dev/ttyc" perl -d myprogram
428
429may be useful for debugging a program which uses C<Term::ReadLine>
430itself. Do not forget detach shell from the TTY in the window which
431corresponds to F</dev/ttyc>, say, by issuing a command like
432
433 $ sleep 1000000
434
435See L<"Debugger Internals"> below for more details.
436
8ebc5c01
PP
437=over 12
438
36477c24
PP
439=item E<lt> [ command ]
440
441Set an action (Perl command) to happen before every debugger prompt.
5f05dabc 442A multi-line command may be entered by backslashing the newlines. If
36477c24
PP
443C<command> is missing, resets the list of actions.
444
445=item E<lt>E<lt> command
446
447Add an action (Perl command) to happen before every debugger prompt.
5f05dabc 448A multi-line command may be entered by backslashing the newlines.
a0d0e21e 449
184e9718 450=item E<gt> command
a0d0e21e 451
36477c24 452Set an action (Perl command) to happen after the prompt when you've
5f05dabc 453just given a command to return to executing the script. A multi-line
36477c24
PP
454command may be entered by backslashing the newlines. If C<command> is
455missing, resets the list of actions.
456
457=item E<gt>E<gt> command
458
459Adds an action (Perl command) to happen after the prompt when you've
5f05dabc 460just given a command to return to executing the script. A multi-line
36477c24
PP
461command may be entered by backslashing the newlines.
462
463=item { [ command ]
464
465Set an action (debugger command) to happen before every debugger prompt.
5f05dabc 466A multi-line command may be entered by backslashing the newlines. If
36477c24
PP
467C<command> is missing, resets the list of actions.
468
469=item {{ command
470
471Add an action (debugger command) to happen before every debugger prompt.
5f05dabc 472A multi-line command may be entered by backslashing the newlines.
a0d0e21e 473
4e1d3b43 474=item ! number
a0d0e21e 475
4e1d3b43 476Redo a previous command (default previous command).
a0d0e21e 477
4e1d3b43 478=item ! -number
a0d0e21e 479
4e1d3b43 480Redo number'th-to-last command.
a0d0e21e 481
4e1d3b43 482=item ! pattern
a0d0e21e 483
4e1d3b43
PP
484Redo last command that started with pattern.
485See C<O recallCommand>, too.
a0d0e21e 486
4e1d3b43 487=item !! cmd
a0d0e21e 488
4e1d3b43
PP
489Run cmd in a subprocess (reads from DB::IN, writes to DB::OUT)
490See C<O shellBang> too.
a0d0e21e
LW
491
492=item H -number
493
494Display last n commands. Only commands longer than one character are
495listed. If number is omitted, lists them all.
496
497=item q or ^D
498
36477c24
PP
499Quit. ("quit" doesn't work for this.) This is the only supported way
500to exit the debugger, though typing C<exit> twice may do it too.
501
502Set an C<O>ption C<inhibit_exit> to 0 if you want to be able to I<step
503off> the end the script. You may also need to set C<$finished> to 0 at
504some moment if you want to step through global destruction.
a0d0e21e 505
4e1d3b43
PP
506=item R
507
508Restart the debugger by B<exec>ing a new session. It tries to maintain
509your history across this, but internal settings and command line options
510may be lost.
511
5f05dabc
PP
512Currently the following setting are preserved: history, breakpoints,
513actions, debugger C<O>ptions, and the following command-line
514options: B<-w>, B<-I>, and B<-e>.
36477c24 515
4e1d3b43
PP
516=item |dbcmd
517
518Run debugger command, piping DB::OUT to current pager.
519
520=item ||dbcmd
521
522Same as C<|dbcmd> but DB::OUT is temporarily B<select>ed as well.
523Often used with commands that would otherwise produce long
524output, such as
525
526 |V main
527
528=item = [alias value]
529
530Define a command alias, or list current aliases.
531
a0d0e21e
LW
532=item command
533
534Execute command as a Perl statement. A missing semicolon will be
535supplied.
536
537=item p expr
538
539Same as C<print DB::OUT expr>. The DB::OUT filehandle is opened to
540/dev/tty, regardless of where STDOUT may be redirected to.
541
542=back
543
4e1d3b43
PP
544The debugger prompt is something like
545
546 DB<8>
547
548or even
549
550 DB<<17>>
551
552where that number is the command number, which you'd use to access with
5f05dabc 553the built-in B<csh>-like history mechanism, e.g., C<!17> would repeat
4e1d3b43
PP
554command number 17. The number of angle brackets indicates the depth of
555the debugger. You could get more than one set of brackets, for example, if
556you'd already at a breakpoint and then printed out the result of a
36477c24
PP
557function call that itself also has a breakpoint, or you step into an
558expression via C<s/n/t expression> command.
4e1d3b43
PP
559
560If you want to enter a multi-line command, such as a subroutine
561definition with several statements, you may escape the newline that would
562normally end the debugger command with a backslash. Here's an example:
a0d0e21e 563
4e1d3b43
PP
564 DB<1> for (1..4) { \
565 cont: print "ok\n"; \
566 cont: }
567 ok
568 ok
569 ok
570 ok
571
572Note that this business of escaping a newline is specific to interactive
573commands typed into the debugger.
574
5f05dabc 575Here's an example of what a stack back-trace might look like:
4e1d3b43
PP
576
577 $ = main::infested called from file `Ambulation.pm' line 10
578 @ = Ambulation::legs(1, 2, 3, 4) called from file `camel_flea' line 7
579 $ = main::pests('bactrian', 4) called from file `camel_flea' line 4
580
581The left-hand character up there tells whether the function was called
582in a scalar or list context (we bet you can tell which is which). What
583that says is that you were in the function C<main::infested> when you ran
584the stack dump, and that it was called in a scalar context from line 10
585of the file I<Ambulation.pm>, but without any arguments at all, meaning
586it was called as C<&infested>. The next stack frame shows that the
587function C<Ambulation::legs> was called in a list context from the
588I<camel_flea> file with four arguments. The last stack frame shows that
589C<main::pests> was called in a scalar context, also from I<camel_flea>,
590but from line 4.
591
592If you have any compile-time executable statements (code within a BEGIN
593block or a C<use> statement), these will C<NOT> be stopped by debugger,
36477c24
PP
594although C<require>s will (and compile-time statements can be traced
595with C<AutoTrace> option set in C<PERLDB_OPTS>). From your own Perl
596code, however, you can
4e1d3b43
PP
597transfer control back to the debugger using the following statement,
598which is harmless if the debugger is not running:
a0d0e21e
LW
599
600 $DB::single = 1;
601
4e1d3b43
PP
602If you set C<$DB::single> to the value 2, it's equivalent to having
603just typed the C<n> command, whereas a value of 1 means the C<s>
604command. The C<$DB::trace> variable should be set to 1 to simulate
605having typed the C<t> command.
606
607=head2 Debugger Customization
a0d0e21e 608
36477c24
PP
609Most probably you not want to modify the debugger, it contains enough
610hooks to satisfy most needs. You may change the behaviour of debugger
611from the debugger itself, using C<O>ptions, from the command line via
612C<PERLDB_OPTS> environment variable, and from I<customization files>.
a0d0e21e
LW
613
614You can do some customization by setting up a F<.perldb> file which
615contains initialization code. For instance, you could make aliases
4e1d3b43 616like these (the last one is one people expect to be there):
a0d0e21e 617
4e1d3b43 618 $DB::alias{'len'} = 's/^len(.*)/p length($1)/';
a0d0e21e 619 $DB::alias{'stop'} = 's/^stop (at|in)/b/';
4e1d3b43
PP
620 $DB::alias{'ps'} = 's/^ps\b/p scalar /';
621 $DB::alias{'quit'} = 's/^quit(\s*)/exit\$/';
622
36477c24
PP
623One changes options from F<.perldb> file via calls like this one;
624
625 parse_options("NonStop=1 LineInfo=db.out AutoTrace=1 frame=2");
626
627(the code is executed in the package C<DB>). Note that F<.perldb> is
628processed before processing C<PERLDB_OPTS>. If F<.perldb> defines the
629subroutine C<afterinit>, it is called after all the debugger
630initialization ends. F<.perldb> may be contained in the current
631directory, or in the C<LOGDIR>/C<HOME> directory.
632
633If you want to modify the debugger, copy F<perl5db.pl> from the Perl
634library to another name and modify it as necessary. You'll also want
635to set your C<PERL5DB> environment variable to say something like this:
636
637 BEGIN { require "myperl5db.pl" }
638
639As the last resort, one can use C<PERL5DB> to customize debugger by
640directly setting internal variables or calling debugger functions.
641
4e1d3b43
PP
642=head2 Readline Support
643
644As shipped, the only command line history supplied is a simplistic one
645that checks for leading exclamation points. However, if you install
646the Term::ReadKey and Term::ReadLine modules from CPAN, you will
647have full editing capabilities much like GNU I<readline>(3) provides.
648Look for these in the F<modules/by-module/Term> directory on CPAN.
649
650=head2 Editor Support for Debugging
651
652If you have GNU B<emacs> installed on your system, it can interact with
653the Perl debugger to provide an integrated software development
654environment reminiscent of its interactions with C debuggers.
655
656Perl is also delivered with a start file for making B<emacs> act like a
657syntax-directed editor that understands (some of) Perl's syntax. Look in
658the I<emacs> directory of the Perl source distribution.
659
660(Historically, a similar setup for interacting with B<vi> and the
661X11 window system had also been available, but at the time of this
662writing, no debugger support for B<vi> currently exists.)
663
664=head2 The Perl Profiler
665
666If you wish to supply an alternative debugger for Perl to run, just
667invoke your script with a colon and a package argument given to the B<-d>
668flag. One of the most popular alternative debuggers for Perl is
669B<DProf>, the Perl profiler. As of this writing, B<DProf> is not
670included with the standard Perl distribution, but it is expected to
671be included soon, for certain values of "soon".
672
673Meanwhile, you can fetch the Devel::Dprof module from CPAN. Assuming
674it's properly installed on your system, to profile your Perl program in
675the file F<mycode.pl>, just type:
676
677 perl -d:DProf mycode.pl
678
679When the script terminates the profiler will dump the profile information
680to a file called F<tmon.out>. A tool like B<dprofpp> (also supplied with
681the Devel::DProf package) can be used to interpret the information which is
682in that profile.
683
36477c24 684=head2 Debugger support in perl
4e1d3b43
PP
685
686When you call the B<caller> function from package DB, Perl sets the
687C<@DB::args> array to contain the arguments that stack frame was called
36477c24 688with.
4e1d3b43 689
36477c24
PP
690If perl is run with B<-d> option, the following additional features
691are enabled:
a0d0e21e 692
36477c24 693=over
4e1d3b43 694
36477c24 695=item *
4e1d3b43 696
36477c24
PP
697Perl inserts the contents of C<$ENV{PERL5DB}> (or C<BEGIN {require
698'perl5db.pl'}> if not present) before the first line of the
699application.
4e1d3b43 700
36477c24 701=item *
4e1d3b43 702
36477c24
PP
703The array C<@{"_<$filename"}> is the line-by-line contents of
704$filename for all the compiled files. Same for C<eval>ed strings which
705contain subroutines, or which are currently executed. The C<$filename>
706for C<eval>ed strings looks like C<(eval 34)>.
4e1d3b43 707
36477c24 708=item *
4e1d3b43 709
36477c24
PP
710The hash C<%{"_<$filename"}> contains breakpoints and action (it is
711keyed by line number), and individual entries are settable (as opposed
712to the whole hash). Only true/false is important to Perl, though the
713values used by F<perl5db.pl> have the form
714C<"$break_condition\0$action">. Values are magical in numeric context:
715they are zeros if the line is not breakable.
4e1d3b43 716
36477c24
PP
717Same for evaluated strings which contain subroutines, or which are
718currently executed. The C<$filename> for C<eval>ed strings looks like
719C<(eval 34)>.
4e1d3b43 720
36477c24 721=item *
4e1d3b43 722
36477c24
PP
723The scalar C<${"_<$filename"}> contains C<"_<$filename">. Same for
724evaluated strings which contain subroutines, or which are currently
725executed. The C<$filename> for C<eval>ed strings looks like C<(eval
72634)>.
4e1d3b43 727
36477c24 728=item *
4e1d3b43 729
36477c24
PP
730After each C<require>d file is compiled, but before it is executed,
731C<DB::postponed(*{"_<$filename"})> is called (if subroutine
732C<DB::postponed> exists). Here the $filename is the expanded name of
733the C<require>d file (as found in values of C<%INC>).
4e1d3b43 734
36477c24 735=item *
4e1d3b43 736
36477c24
PP
737After each subroutine C<subname> is compiled existence of
738C<$DB::postponed{subname}> is checked. If this key exists,
739C<DB::postponed(subname)> is called (if subroutine C<DB::postponed>
740exists).
4e1d3b43 741
36477c24 742=item *
4e1d3b43 743
36477c24
PP
744A hash C<%DB::sub> is maintained, with keys being subroutine names,
745values having the form C<filename:startline-endline>. C<filename> has
746the form C<(eval 31)> for subroutines defined inside C<eval>s.
4e1d3b43 747
36477c24
PP
748=item *
749
5f05dabc
PP
750When execution of the application reaches a place that can have
751a breakpoint, a call to C<DB::DB()> is performed if any one of
752variables $DB::trace, $DB::single, or $DB::signal is true. (Note that
36477c24
PP
753these variables are not C<local>izable.) This feature is disabled when
754the control is inside C<DB::DB()> or functions called from it (unless
755C<$^D & 1 E<lt>E<lt> 30>).
756
757=item *
758
5f05dabc 759When execution of the application reaches a subroutine call, a call
36477c24
PP
760to C<&DB::sub>(I<args>) is performed instead, with C<$DB::sub> being
761the name of the called subroutine. (Unless the subroutine is compiled
762in the package C<DB>.)
4e1d3b43
PP
763
764=back
a0d0e21e 765
36477c24
PP
766Note that no subroutine call is possible until C<&DB::sub> is defined
767(for subroutines outside of package C<DB>). (In fact, for the
768standard debugger the same is true if C<$DB::deep> (how many levels of
769recursion deep into the debugger you can go before a mandatory break)
770is not defined.)
771
772=head2 Debugger Internals
773
774At the start, the debugger reads your rc file (F<./.perldb> or
775F<~/.perldb> under UNIX), which can set important options. This file may
776define a subroutine C<&afterinit> to be executed after the debugger is
777initialized.
778
5f05dabc 779After the rc file is read, the debugger reads environment variable
36477c24
PP
780PERLDB_OPTS and parses it as a rest of C<O ...> line in debugger prompt.
781
782It also maintains magical internal variables, such as C<@DB::dbline>,
783C<%DB::dbline>, which are aliases for C<@{"::_<current_file"}>
784C<%{"::_<current_file"}>. Here C<current_file> is the currently
785selected (with the debugger's C<f> command, or by flow of execution)
786file.
787
788Some functions are provided to simplify customization. See L<"Debugger
789Customization"> for description of C<DB::parse_options(string)>. The
790function C<DB::dump_trace(skip[, count])> skips the specified number
791of frames, and returns an array containing info about the caller
792frames (all if C<count> is missing). Each entry is a hash with keys
793C<context> (C<$> or C<@>), C<sub> (subroutine name, or info about
5f05dabc 794eval), C<args> (C<undef> or a reference to an array), C<file>, and
36477c24
PP
795C<line>.
796
797The function C<DB::print_trace(FH, skip[, count[, short]])> prints
798formatted info about caller frames. The last two functions may be
799convenient as arguments to C<E<lt>>, C<E<lt>E<lt>> commands.
800
a0d0e21e
LW
801=head2 Other resources
802
803You did try the B<-w> switch, didn't you?
804
805=head1 BUGS
806
4e1d3b43
PP
807You cannot get the stack frame information or otherwise debug functions
808that were not compiled by Perl, such as C or C++ extensions.
a0d0e21e 809
4e1d3b43 810If you alter your @_ arguments in a subroutine (such as with B<shift>
5f05dabc 811or B<pop>, the stack back-trace will not show the original values.