source: trunk/third/perl/pod/perldebug.pod @ 17035

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