README.vms and related updates (from Peter Prymmer <pvhp@best.com>)
[p5sagit/p5-mst-13.2.git] / pod / perldebug.pod
1 =head1 NAME
2
3 perldebug - Perl debugging
4
5 =head1 DESCRIPTION
6
7 First of all, have you tried using the B<-w> switch?
8
9 =head1 The Perl Debugger
10
11 "As soon as we started programming, we found to our
12 surprise that it wasn't as easy to get programs right
13 as we had thought.  Debugging had to be discovered.
14 I can remember the exact instant when I realized that
15 a large part of my life from then on was going to be
16 spent in finding mistakes in my own programs."
17
18 I<  --Maurice Wilkes, 1949>
19
20 If you invoke Perl with the B<-d> switch, your script runs under the
21 Perl source debugger.  This works like an interactive Perl
22 environment, prompting for debugger commands that let you examine
23 source code, set breakpoints, get stack backtraces, change the values of
24 variables, etc.  This is so convenient that you often fire up
25 the debugger all by itself just to test out Perl constructs
26 interactively to see what they do.  For example:
27
28     perl -d -e 42
29
30 In Perl, the debugger is not a separate program as it usually is in the
31 typical compiled environment.  Instead, the B<-d> flag tells the compiler
32 to insert source information into the parse trees it's about to hand off
33 to the interpreter.  That means your code must first compile correctly
34 for the debugger to work on it.  Then when the interpreter starts up, it
35 preloads a Perl library file containing the debugger itself.
36
37 The program will halt I<right before> the first run-time executable
38 statement (but see below regarding compile-time statements) and ask you
39 to enter a debugger command.  Contrary to popular expectations, whenever
40 the debugger halts and shows you a line of code, it always displays the
41 line it's I<about> to execute, rather than the one it has just executed.
42
43 Any command not recognized by the debugger is directly executed
44 (C<eval>'d) as Perl code in the current package.  (The debugger uses the
45 DB package for its own state information.)
46
47 Leading white space before a command would cause the debugger to think
48 it's I<NOT> a debugger command but for Perl, so be careful not to do
49 that.
50
51 =head2 Debugger Commands
52
53 The debugger understands the following commands:
54
55 =over 12
56
57 =item h [command]
58
59 Prints out a help message.
60
61 If you supply another debugger command as an argument to the C<h> command,
62 it prints out the description for just that command.  The special
63 argument of C<h h> produces a more compact help listing, designed to fit
64 together on one screen.
65
66 If the output of the C<h> command (or any command, for that matter) scrolls
67 past your screen, either precede the command with a leading pipe symbol so
68 it's run through your pager, as in
69
70     DB> |h
71
72 You may change the pager which is used via C<O pager=...> command.
73
74 =item p expr
75
76 Same as C<print {$DB::OUT} expr> in the current package.  In particular,
77 because this is just Perl's own B<print> function, this means that nested
78 data structures and objects are not dumped, unlike with the C<x> command.
79
80 The C<DB::OUT> filehandle is opened to F</dev/tty>, regardless of
81 where STDOUT may be redirected to.
82
83 =item x expr
84
85 Evaluates its expression in list context and dumps out the result
86 in a pretty-printed fashion.  Nested data structures are printed out
87 recursively, unlike the C<print> function.
88
89 The details of printout are governed by multiple C<O>ptions.
90
91 =item V [pkg [vars]]
92
93 Display all (or some) variables in package (defaulting to the C<main>
94 package) using a data pretty-printer (hashes show their keys and values so
95 you see what's what, control characters are made printable, etc.).  Make
96 sure you don't put the type specifier (like C<$>) there, just the symbol
97 names, like this:
98
99     V DB filename line
100
101 Use C<~pattern> and C<!pattern> for positive and negative regexps.
102
103 Nested data structures are printed out in a legible fashion, unlike
104 the C<print> function.
105
106 The details of printout are governed by multiple C<O>ptions.
107
108 =item X [vars]
109
110 Same as C<V currentpackage [vars]>.
111
112 =item T
113
114 Produce a stack backtrace.  See below for details on its output.
115
116 =item s [expr]
117
118 Single step.  Executes until it reaches the beginning of another
119 statement, descending into subroutine calls.  If an expression is
120 supplied that includes function calls, it too will be single-stepped.
121
122 =item n [expr]
123
124 Next.  Executes over subroutine calls, until it reaches the beginning
125 of the next statement.  If an expression is supplied that includes
126 function calls, those functions will be executed with stops before
127 each statement.
128
129 =item E<lt>CRE<gt>
130
131 Repeat last C<n> or C<s> command.
132
133 =item c [line|sub]
134
135 Continue, optionally inserting a one-time-only breakpoint
136 at the specified line or subroutine.
137
138 =item l
139
140 List next window of lines.
141
142 =item l min+incr
143
144 List C<incr+1> lines starting at C<min>.
145
146 =item l min-max
147
148 List lines C<min> through C<max>.  C<l E<45>> is synonymous to C<E<45>>.
149
150 =item l line
151
152 List a single line.
153
154 =item l subname
155
156 List first window of lines from subroutine.  I<subname> may
157 be a variable which contains a code reference.
158
159 =item -
160
161 List previous window of lines.
162
163 =item w [line]
164
165 List window (a few lines) around the current line.
166
167 =item .
168
169 Return debugger pointer to the last-executed line and
170 print it out.
171
172 =item f filename
173
174 Switch to viewing a different file or eval statement.  If C<filename>
175 is not a full filename as found in values of %INC, it is considered as
176 a regexp.
177
178 C<eval>ed strings (when accessible) are considered to be filenames:
179 C<f (eval 7)> and C<f eval 7\b> access the body of the 7th C<eval>ed string
180 (in the order of execution).  The bodies of currently executed C<eval>
181 and of C<eval>ed strings which define subroutines are saved, thus are
182 accessible by this mechanism.
183
184 =item /pattern/
185
186 Search forwards for pattern; final / is optional.
187
188 =item ?pattern?
189
190 Search backwards for pattern; final ? is optional.
191
192 =item L
193
194 List all breakpoints and actions.
195
196 =item S [[!]pattern]
197
198 List subroutine names [not] matching pattern.
199
200 =item t
201
202 Toggle trace mode (see also C<AutoTrace> C<O>ption).
203
204 =item t expr
205
206 Trace through execution of expr.  For example:
207
208  $ perl -de 42
209  Stack dump during die enabled outside of evals.
210
211  Loading DB routines from perl5db.pl patch level 0.94
212  Emacs support available.
213
214  Enter h or `h h' for help.
215
216  main::(-e:1):   0
217    DB<1> sub foo { 14 }
218
219    DB<2> sub bar { 3 }
220
221    DB<3> t print foo() * bar()
222  main::((eval 172):3):   print foo() + bar();
223  main::foo((eval 168):2):
224  main::bar((eval 170):2):
225  42
226
227 or, with the C<O>ption C<frame=2> set,
228
229    DB<4> O f=2
230                 frame = '2'
231    DB<5> t print foo() * bar()
232  3:      foo() * bar()
233  entering main::foo
234   2:     sub foo { 14 };
235  exited main::foo
236  entering main::bar
237   2:     sub bar { 3 };
238  exited main::bar
239  42
240
241 =item b [line] [condition]
242
243 Set a breakpoint.  If line is omitted, sets a breakpoint on the line
244 that is about to be executed.  If a condition is specified, it's
245 evaluated each time the statement is reached and a breakpoint is taken
246 only if the condition is true.  Breakpoints may be set on only lines
247 that begin an executable statement.  Conditions don't use B<if>:
248
249     b 237 $x > 30
250     b 237 ++$count237 < 11
251     b 33 /pattern/i
252
253 =item b subname [condition]
254
255 Set a breakpoint at the first line of the named subroutine.  I<subname> may
256 be a variable which contains a code reference (in this case I<condition>
257 is not supported).
258
259 =item b postpone subname [condition]
260
261 Set breakpoint at first line of subroutine after it is compiled.
262
263 =item b load filename
264
265 Set breakpoint at the first executed line of the file.  Filename should
266 be a full name as found in values of %INC.
267
268 =item b compile subname
269
270 Sets breakpoint at the first statement executed after the subroutine
271 is compiled.
272
273 =item d [line]
274
275 Delete a breakpoint at the specified line.  If line is omitted, deletes
276 the breakpoint on the line that is about to be executed.
277
278 =item D
279
280 Delete all installed breakpoints.
281
282 =item a [line] command
283
284 Set an action to be done before the line is executed.
285 The sequence of steps taken by the debugger is
286
287   1. check for a breakpoint at this line
288   2. print the line if necessary (tracing)
289   3. do any actions associated with that line
290   4. prompt user if at a breakpoint or in single-step
291   5. evaluate line
292
293 For example, this will print out $foo every time line
294 53 is passed:
295
296     a 53 print "DB FOUND $foo\n"
297
298 =item A
299
300 Delete all installed actions.
301
302 =item W [expr]
303
304 Add a global watch-expression.
305
306 =item W
307
308 Delete all watch-expressions.
309
310 =item O [opt[=val]] [opt"val"] [opt?]...
311
312 Set or query values of options.  val defaults to 1.  opt can
313 be abbreviated.  Several options can be listed.
314
315 =over 12
316
317 =item C<recallCommand>, C<ShellBang>
318
319 The characters used to recall command or spawn shell.  By
320 default, these are both set to C<!>.
321
322 =item C<pager>
323
324 Program to use for output of pager-piped commands (those
325 beginning with a C<|> character.)  By default,
326 C<$ENV{PAGER}> will be used.
327
328 =item C<tkRunning>
329
330 Run Tk while prompting (with ReadLine).
331
332 =item C<signalLevel>, C<warnLevel>, C<dieLevel>
333
334 Level of verbosity.  By default the debugger is in a sane verbose mode,
335 thus it will print backtraces on all the warnings and die-messages
336 which are going to be printed out, and will print a message when
337 interesting uncaught signals arrive.
338
339 To disable this behaviour, set these values to 0.  If C<dieLevel> is 2,
340 then the messages which will be caught by surrounding C<eval> are also
341 printed.
342
343 =item C<AutoTrace>
344
345 Trace mode (similar to C<t> command, but can be put into
346 C<PERLDB_OPTS>).
347
348 =item C<LineInfo>
349
350 File or pipe to print line number info to.  If it is a pipe (say,
351 C<|visual_perl_db>), then a short, "emacs like" message is used.
352
353 =item C<inhibit_exit>
354
355 If 0, allows I<stepping off> the end of the script.
356
357 =item C<PrintRet>
358
359 affects printing of return value after C<r> command.
360
361 =item C<ornaments>
362
363 affects screen appearance of the command line (see L<Term::ReadLine>).
364
365 =item C<frame>
366
367 affects printing messages on entry and exit from subroutines.  If
368 C<frame & 2> is false, messages are printed on entry only. (Printing
369 on exit may be useful if inter(di)spersed with other messages.)
370
371 If C<frame & 4>, arguments to functions are printed as well as the
372 context and caller info.  If C<frame & 8>, overloaded C<stringify> and
373 C<tie>d C<FETCH> are enabled on the printed arguments. If C<frame &
374 16>, the return value from the subroutine is printed as well.
375
376 The length at which the argument list is truncated is governed by the
377 next option:
378
379 =item C<maxTraceLen>
380
381 length at which the argument list is truncated when C<frame> option's
382 bit 4 is set.
383
384 =back
385
386 The following options affect what happens with C<V>, C<X>, and C<x>
387 commands:
388
389 =over 12
390
391 =item C<arrayDepth>, C<hashDepth>
392
393 Print only first N elements ('' for all).
394
395 =item C<compactDump>, C<veryCompact>
396
397 Change style of array and hash dump.  If C<compactDump>, short array
398 may be printed on one line.
399
400 =item C<globPrint>
401
402 Whether to print contents of globs.
403
404 =item C<DumpDBFiles>
405
406 Dump arrays holding debugged files.
407
408 =item C<DumpPackages>
409
410 Dump symbol tables of packages.
411
412 =item C<DumpReused>
413
414 Dump contents of "reused" addresses.
415
416 =item C<quote>, C<HighBit>, C<undefPrint>
417
418 Change style of string dump.  Default value of C<quote> is C<auto>, one
419 can enable either double-quotish dump, or single-quotish by setting it
420 to C<"> or C<'>.  By default, characters with high bit set are printed
421 I<as is>.
422
423 =item C<UsageOnly>
424
425 I<very> rudimentally per-package memory usage dump.  Calculates total
426 size of strings in variables in the package.
427
428 =back
429
430 During startup options are initialized from C<$ENV{PERLDB_OPTS}>.
431 You can put additional initialization options C<TTY>, C<noTTY>,
432 C<ReadLine>, and C<NonStop> there.
433
434 Example rc file:
435
436   &parse_options("NonStop=1 LineInfo=db.out AutoTrace");
437
438 The script will run without human intervention, putting trace information
439 into the file I<db.out>.  (If you interrupt it, you would better reset
440 C<LineInfo> to something "interactive"!)
441
442 =over 12
443
444 =item C<TTY>
445
446 The TTY to use for debugging I/O.
447
448 =item C<noTTY>
449
450 If set, goes in C<NonStop> mode, and would not connect to a TTY.  If
451 interrupt (or if control goes to debugger via explicit setting of
452 $DB::signal or $DB::single from the Perl script), connects to a TTY
453 specified by the C<TTY> option at startup, or to a TTY found at
454 runtime using C<Term::Rendezvous> module of your choice.
455
456 This module should implement a method C<new> which returns an object
457 with two methods: C<IN> and C<OUT>, returning two filehandles to use
458 for debugging input and output correspondingly.  Method C<new> may
459 inspect an argument which is a value of C<$ENV{PERLDB_NOTTY}> at
460 startup, or is C<"/tmp/perldbtty$$"> otherwise.
461
462 =item C<ReadLine>
463
464 If false, readline support in debugger is disabled, so you can debug
465 ReadLine applications.
466
467 =item C<NonStop>
468
469 If set, debugger goes into noninteractive mode until interrupted, or
470 programmatically by setting $DB::signal or $DB::single.
471
472 =back
473
474 Here's an example of using the C<$ENV{PERLDB_OPTS}> variable:
475
476   $ PERLDB_OPTS="N f=2" perl -d myprogram
477
478 will run the script C<myprogram> without human intervention, printing
479 out the call tree with entry and exit points.  Note that C<N f=2> is
480 equivalent to C<NonStop=1 frame=2>.  Note also that at the moment when
481 this documentation was written all the options to the debugger could
482 be uniquely abbreviated by the first letter (with exception of
483 C<Dump*> options).
484
485 Other examples may include
486
487   $ PERLDB_OPTS="N f A L=listing" perl -d myprogram
488
489 - runs script noninteractively, printing info on each entry into a
490 subroutine and each executed line into the file F<listing>. (If you
491 interrupt it, you would better reset C<LineInfo> to something
492 "interactive"!)
493
494
495   $ env "PERLDB_OPTS=R=0 TTY=/dev/ttyc" perl -d myprogram
496
497 may be useful for debugging a program which uses C<Term::ReadLine>
498 itself.  Do not forget detach shell from the TTY in the window which
499 corresponds to F</dev/ttyc>, say, by issuing a command like
500
501   $ sleep 1000000
502
503 See L<"Debugger Internals"> below for more details.
504
505 =item E<lt> [ command ]
506
507 Set an action (Perl command) to happen before every debugger prompt.
508 A multi-line command may be entered by backslashing the newlines.  If
509 C<command> is missing, resets the list of actions.
510
511 =item E<lt>E<lt> command
512
513 Add an action (Perl command) to happen before every debugger prompt.
514 A multi-line command may be entered by backslashing the newlines.
515
516 =item E<gt> command
517
518 Set an action (Perl command) to happen after the prompt when you've
519 just given a command to return to executing the script.  A multi-line
520 command may be entered by backslashing the newlines.  If C<command> is
521 missing, resets the list of actions.
522
523 =item E<gt>E<gt> command
524
525 Adds an action (Perl command) to happen after the prompt when you've
526 just given a command to return to executing the script.  A multi-line
527 command may be entered by backslashing the newlines.
528
529 =item { [ command ]
530
531 Set an action (debugger command) to happen before every debugger prompt.
532 A multi-line command may be entered by backslashing the newlines.  If
533 C<command> is missing, resets the list of actions.
534
535 =item {{ command
536
537 Add an action (debugger command) to happen before every debugger prompt.
538 A multi-line command may be entered by backslashing the newlines.
539
540 =item ! number
541
542 Redo a previous command (default previous command).
543
544 =item ! -number
545
546 Redo number'th-to-last command.
547
548 =item ! pattern
549
550 Redo last command that started with pattern.
551 See C<O recallCommand>, too.
552
553 =item !! cmd
554
555 Run cmd in a subprocess (reads from DB::IN, writes to DB::OUT)
556 See C<O shellBang> too.
557
558 =item H -number
559
560 Display last n commands.  Only commands longer than one character are
561 listed.  If number is omitted, lists them all.
562
563 =item q or ^D
564
565 Quit.  ("quit" doesn't work for this.)  This is the only supported way
566 to exit the debugger, though typing C<exit> twice may do it too.
567
568 Set an C<O>ption C<inhibit_exit> to 0 if you want to be able to I<step
569 off> the end the script.  You may also need to set $finished to 0 at
570 some moment if you want to step through global destruction.
571
572 =item R
573
574 Restart the debugger by B<exec>ing a new session.  It tries to maintain
575 your history across this, but internal settings and command line options
576 may be lost.
577
578 Currently the following setting are preserved: history, breakpoints,
579 actions, debugger C<O>ptions, and the following command line
580 options: B<-w>, B<-I>, and B<-e>.
581
582 =item |dbcmd
583
584 Run debugger command, piping DB::OUT to current pager.
585
586 =item ||dbcmd
587
588 Same as C<|dbcmd> but DB::OUT is temporarily B<select>ed as well.
589 Often used with commands that would otherwise produce long
590 output, such as
591
592     |V main
593
594 =item = [alias value]
595
596 Define a command alias, like
597
598     = quit q
599
600 or list current aliases.
601
602 =item command
603
604 Execute command as a Perl statement.  A missing semicolon will be
605 supplied.
606
607 =item m expr
608
609 The expression is evaluated, and the methods which may be applied to
610 the result are listed.
611
612 =item m package
613
614 The methods which may be applied to objects in the C<package> are listed.
615
616 =back
617
618 =head2 Debugger input/output
619
620 =over 8
621
622 =item Prompt
623
624 The debugger prompt is something like
625
626     DB<8>
627
628 or even
629
630     DB<<17>>
631
632 where that number is the command number, which you'd use to access with
633 the builtin B<csh>-like history mechanism, e.g., C<!17> would repeat
634 command number 17.  The number of angle brackets indicates the depth of
635 the debugger.  You could get more than one set of brackets, for example, if
636 you'd already at a breakpoint and then printed out the result of a
637 function call that itself also has a breakpoint, or you step into an
638 expression via C<s/n/t expression> command.
639
640 =item Multiline commands
641
642 If you want to enter a multi-line command, such as a subroutine
643 definition with several statements, or a format, you may escape the
644 newline that would normally end the debugger command with a backslash.
645 Here's an example:
646
647       DB<1> for (1..4) {         \
648       cont:     print "ok\n";   \
649       cont: }
650       ok
651       ok
652       ok
653       ok
654
655 Note that this business of escaping a newline is specific to interactive
656 commands typed into the debugger.
657
658 =item Stack backtrace
659
660 Here's an example of what a stack backtrace via C<T> command might
661 look like:
662
663     $ = main::infested called from file `Ambulation.pm' line 10
664     @ = Ambulation::legs(1, 2, 3, 4) called from file `camel_flea' line 7
665     $ = main::pests('bactrian', 4) called from file `camel_flea' line 4
666
667 The left-hand character up there tells whether the function was called
668 in a scalar or list context (we bet you can tell which is which).  What
669 that says is that you were in the function C<main::infested> when you ran
670 the stack dump, and that it was called in a scalar context from line 10
671 of the file I<Ambulation.pm>, but without any arguments at all, meaning
672 it was called as C<&infested>.  The next stack frame shows that the
673 function C<Ambulation::legs> was called in a list context from the
674 I<camel_flea> file with four arguments.  The last stack frame shows that
675 C<main::pests> was called in a scalar context, also from I<camel_flea>,
676 but from line 4.
677
678 Note that if you execute C<T> command from inside an active C<use>
679 statement, the backtrace will contain both C<require>
680 frame and an C<eval>) frame.
681
682 =item Listing
683
684 Listing given via different flavors of C<l> command looks like this:
685
686     DB<<13>> l
687   101:                @i{@i} = ();
688   102:b               @isa{@i,$pack} = ()
689   103                     if(exists $i{$prevpack} || exists $isa{$pack});
690   104             }
691   105
692   106             next
693   107==>              if(exists $isa{$pack});
694   108
695   109:a           if ($extra-- > 0) {
696   110:                %isa = ($pack,1);
697
698 Note that the breakable lines are marked with C<:>, lines with
699 breakpoints are marked by C<b>, with actions by C<a>, and the
700 next executed line is marked by C<==E<gt>>.
701
702 =item Frame listing
703
704 When C<frame> option is set, debugger would print entered (and
705 optionally exited) subroutines in different styles.
706
707 What follows is the start of the listing of
708
709   env "PERLDB_OPTS=f=n N" perl -d -V
710
711 for different values of C<n>:
712
713 =over 4
714
715 =item 1
716
717   entering main::BEGIN
718    entering Config::BEGIN
719     Package lib/Exporter.pm.
720     Package lib/Carp.pm.
721    Package lib/Config.pm.
722    entering Config::TIEHASH
723    entering Exporter::import
724     entering Exporter::export
725   entering Config::myconfig
726    entering Config::FETCH
727    entering Config::FETCH
728    entering Config::FETCH
729    entering Config::FETCH
730
731 =item 2
732
733   entering main::BEGIN
734    entering Config::BEGIN
735     Package lib/Exporter.pm.
736     Package lib/Carp.pm.
737    exited Config::BEGIN
738    Package lib/Config.pm.
739    entering Config::TIEHASH
740    exited Config::TIEHASH
741    entering Exporter::import
742     entering Exporter::export
743     exited Exporter::export
744    exited Exporter::import
745   exited main::BEGIN
746   entering Config::myconfig
747    entering Config::FETCH
748    exited Config::FETCH
749    entering Config::FETCH
750    exited Config::FETCH
751    entering Config::FETCH
752
753 =item 4
754
755   in  $=main::BEGIN() from /dev/nul:0
756    in  $=Config::BEGIN() from lib/Config.pm:2
757     Package lib/Exporter.pm.
758     Package lib/Carp.pm.
759    Package lib/Config.pm.
760    in  $=Config::TIEHASH('Config') from lib/Config.pm:644
761    in  $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/nul:0
762     in  $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from li
763   in  @=Config::myconfig() from /dev/nul:0
764    in  $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574
765    in  $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574
766    in  $=Config::FETCH(ref(Config), 'PERL_VERSION') from lib/Config.pm:574
767    in  $=Config::FETCH(ref(Config), 'PERL_SUBVERSION') from lib/Config.pm:574
768    in  $=Config::FETCH(ref(Config), 'osname') from lib/Config.pm:574
769    in  $=Config::FETCH(ref(Config), 'osvers') from lib/Config.pm:574
770
771 =item 6
772
773   in  $=main::BEGIN() from /dev/nul:0
774    in  $=Config::BEGIN() from lib/Config.pm:2
775     Package lib/Exporter.pm.
776     Package lib/Carp.pm.
777    out $=Config::BEGIN() from lib/Config.pm:0
778    Package lib/Config.pm.
779    in  $=Config::TIEHASH('Config') from lib/Config.pm:644
780    out $=Config::TIEHASH('Config') from lib/Config.pm:644
781    in  $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/nul:0
782     in  $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/
783     out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/
784    out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/nul:0
785   out $=main::BEGIN() from /dev/nul:0
786   in  @=Config::myconfig() from /dev/nul:0
787    in  $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574
788    out $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574
789    in  $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574
790    out $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574
791    in  $=Config::FETCH(ref(Config), 'PERL_VERSION') from lib/Config.pm:574
792    out $=Config::FETCH(ref(Config), 'PERL_VERSION') from lib/Config.pm:574
793    in  $=Config::FETCH(ref(Config), 'PERL_SUBVERSION') from lib/Config.pm:574
794
795 =item 14
796
797   in  $=main::BEGIN() from /dev/nul:0
798    in  $=Config::BEGIN() from lib/Config.pm:2
799     Package lib/Exporter.pm.
800     Package lib/Carp.pm.
801    out $=Config::BEGIN() from lib/Config.pm:0
802    Package lib/Config.pm.
803    in  $=Config::TIEHASH('Config') from lib/Config.pm:644
804    out $=Config::TIEHASH('Config') from lib/Config.pm:644
805    in  $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/nul:0
806     in  $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/E
807     out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/E
808    out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/nul:0
809   out $=main::BEGIN() from /dev/nul:0
810   in  @=Config::myconfig() from /dev/nul:0
811    in  $=Config::FETCH('Config=HASH(0x1aa444)', 'package') from lib/Config.pm:574
812    out $=Config::FETCH('Config=HASH(0x1aa444)', 'package') from lib/Config.pm:574
813    in  $=Config::FETCH('Config=HASH(0x1aa444)', 'baserev') from lib/Config.pm:574
814    out $=Config::FETCH('Config=HASH(0x1aa444)', 'baserev') from lib/Config.pm:574
815
816 =item 30
817
818   in  $=CODE(0x15eca4)() from /dev/null:0
819    in  $=CODE(0x182528)() from lib/Config.pm:2
820     Package lib/Exporter.pm.
821    out $=CODE(0x182528)() from lib/Config.pm:0
822    scalar context return from CODE(0x182528): undef
823    Package lib/Config.pm.
824    in  $=Config::TIEHASH('Config') from lib/Config.pm:628
825    out $=Config::TIEHASH('Config') from lib/Config.pm:628
826    scalar context return from Config::TIEHASH:   empty hash
827    in  $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
828     in  $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/Exporter.pm:171
829     out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/Exporter.pm:171
830     scalar context return from Exporter::export: ''
831    out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
832    scalar context return from Exporter::import: ''
833
834
835 =back
836
837 In all the cases indentation of lines shows the call tree, if bit 2 of
838 C<frame> is set, then a line is printed on exit from a subroutine as
839 well, if bit 4 is set, then the arguments are printed as well as the
840 caller info, if bit 8 is set, the arguments are printed even if they
841 are tied or references, if bit 16 is set, the return value is printed
842 as well.
843
844 When a package is compiled, a line like this
845
846     Package lib/Carp.pm.
847
848 is printed with proper indentation.
849
850 =back
851
852 =head2 Debugging compile-time statements
853
854 If you have any compile-time executable statements (code within a BEGIN
855 block or a C<use> statement), these will C<NOT> be stopped by debugger,
856 although C<require>s will (and compile-time statements can be traced
857 with C<AutoTrace> option set in C<PERLDB_OPTS>).  From your own Perl
858 code, however, you can
859 transfer control back to the debugger using the following statement,
860 which is harmless if the debugger is not running:
861
862     $DB::single = 1;
863
864 If you set C<$DB::single> to the value 2, it's equivalent to having
865 just typed the C<n> command, whereas a value of 1 means the C<s>
866 command.  The C<$DB::trace>  variable should be set to 1 to simulate
867 having typed the C<t> command.
868
869 Another way to debug compile-time code is to start debugger, set a
870 breakpoint on I<load> of some module thusly
871
872     DB<7> b load f:/perllib/lib/Carp.pm
873   Will stop on load of `f:/perllib/lib/Carp.pm'.
874
875 and restart debugger by C<R> command (if possible).  One can use C<b
876 compile subname> for the same purpose.
877
878 =head2 Debugger Customization
879
880 Most probably you do not want to modify the debugger, it contains enough
881 hooks to satisfy most needs.  You may change the behaviour of debugger
882 from the debugger itself, using C<O>ptions, from the command line via
883 C<PERLDB_OPTS> environment variable, and from I<customization files>.
884
885 You can do some customization by setting up a F<.perldb> file which
886 contains initialization code.  For instance, you could make aliases
887 like these (the last one is one people expect to be there):
888
889     $DB::alias{'len'}  = 's/^len(.*)/p length($1)/';
890     $DB::alias{'stop'} = 's/^stop (at|in)/b/';
891     $DB::alias{'ps'}   = 's/^ps\b/p scalar /';
892     $DB::alias{'quit'} = 's/^quit(\s*)/exit\$/';
893
894 One changes options from F<.perldb> file via calls like this one;
895
896     parse_options("NonStop=1 LineInfo=db.out AutoTrace=1 frame=2");
897
898 (the code is executed in the package C<DB>).  Note that F<.perldb> is
899 processed before processing C<PERLDB_OPTS>.  If F<.perldb> defines the
900 subroutine C<afterinit>, it is called after all the debugger
901 initialization ends.  F<.perldb> may be contained in the current
902 directory, or in the C<LOGDIR>/C<HOME> directory.
903
904 If you want to modify the debugger, copy F<perl5db.pl> from the Perl
905 library to another name and modify it as necessary.  You'll also want
906 to set your C<PERL5DB> environment variable to say something like this:
907
908     BEGIN { require "myperl5db.pl" }
909
910 As the last resort, one can use C<PERL5DB> to customize debugger by
911 directly setting internal variables or calling debugger functions.
912
913 =head2 Readline Support
914
915 As shipped, the only command line history supplied is a simplistic one
916 that checks for leading exclamation points.  However, if you install
917 the Term::ReadKey and Term::ReadLine modules from CPAN, you will
918 have full editing capabilities much like GNU I<readline>(3) provides.
919 Look for these in the F<modules/by-module/Term> directory on CPAN.
920
921 A rudimentary command line completion is also available.
922 Unfortunately, the names of lexical variables are not available for
923 completion.
924
925 =head2 Editor Support for Debugging
926
927 If you have GNU B<emacs> installed on your system, it can interact with
928 the Perl debugger to provide an integrated software development
929 environment reminiscent of its interactions with C debuggers.
930
931 Perl is also delivered with a start file for making B<emacs> act like a
932 syntax-directed editor that understands (some of) Perl's syntax.  Look in
933 the I<emacs> directory of the Perl source distribution.
934
935 (Historically, a similar setup for interacting with B<vi> and the
936 X11 window system had also been available, but at the time of this
937 writing, no debugger support for B<vi> currently exists.)
938
939 =head2 The Perl Profiler
940
941 If you wish to supply an alternative debugger for Perl to run, just
942 invoke your script with a colon and a package argument given to the B<-d>
943 flag.  One of the most popular alternative debuggers for Perl is
944 B<DProf>, the Perl profiler.   As of this writing, B<DProf> is not
945 included with the standard Perl distribution, but it is expected to
946 be included soon, for certain values of "soon".
947
948 Meanwhile, you can fetch the Devel::Dprof module from CPAN.  Assuming
949 it's properly installed on your system, to profile your Perl program in
950 the file F<mycode.pl>, just type:
951
952     perl -d:DProf mycode.pl
953
954 When the script terminates the profiler will dump the profile information
955 to a file called F<tmon.out>.  A tool like B<dprofpp> (also supplied with
956 the Devel::DProf package) can be used to interpret the information which is
957 in that profile.
958
959 =head2 Debugger support in perl
960
961 When you call the B<caller> function (see L<perlfunc/caller>) from the
962 package DB, Perl sets the array @DB::args to contain the arguments the
963 corresponding stack frame was called with.
964
965 If perl is run with B<-d> option, the following additional features
966 are enabled (cf. L<perlvar/$^P>):
967
968 =over
969
970 =item *
971
972 Perl inserts the contents of C<$ENV{PERL5DB}> (or C<BEGIN {require
973 'perl5db.pl'}> if not present) before the first line of the
974 application.
975
976 =item *
977
978 The array C<@{"_E<lt>$filename"}> is the line-by-line contents of
979 $filename for all the compiled files.  Same for C<eval>ed strings which
980 contain subroutines, or which are currently executed.  The $filename
981 for C<eval>ed strings looks like C<(eval 34)>.
982
983 =item *
984
985 The hash C<%{"_E<lt>$filename"}> contains breakpoints and action (it is
986 keyed by line number), and individual entries are settable (as opposed
987 to the whole hash).  Only true/false is important to Perl, though the
988 values used by F<perl5db.pl> have the form
989 C<"$break_condition\0$action">.  Values are magical in numeric context:
990 they are zeros if the line is not breakable.
991
992 Same for evaluated strings which contain subroutines, or which are
993 currently executed.  The $filename for C<eval>ed strings looks like
994 C<(eval 34)>.
995
996 =item *
997
998 The scalar C<${"_E<lt>$filename"}> contains C<"_E<lt>$filename">.  Same for
999 evaluated strings which contain subroutines, or which are currently
1000 executed.  The $filename for C<eval>ed strings looks like C<(eval
1001 34)>.
1002
1003 =item *
1004
1005 After each C<require>d file is compiled, but before it is executed,
1006 C<DB::postponed(*{"_E<lt>$filename"})> is called (if subroutine
1007 C<DB::postponed> exists).  Here the $filename is the expanded name of
1008 the C<require>d file (as found in values of %INC).
1009
1010 =item *
1011
1012 After each subroutine C<subname> is compiled existence of
1013 C<$DB::postponed{subname}> is checked.  If this key exists,
1014 C<DB::postponed(subname)> is called (if subroutine C<DB::postponed>
1015 exists).
1016
1017 =item *
1018
1019 A hash C<%DB::sub> is maintained, with keys being subroutine names,
1020 values having the form C<filename:startline-endline>.  C<filename> has
1021 the form C<(eval 31)> for subroutines defined inside C<eval>s.
1022
1023 =item *
1024
1025 When execution of the application reaches a place that can have
1026 a breakpoint, a call to C<DB::DB()> is performed if any one of
1027 variables $DB::trace, $DB::single, or $DB::signal is true. (Note that
1028 these variables are not C<local>izable.) This feature is disabled when
1029 the control is inside C<DB::DB()> or functions called from it (unless
1030 C<$^D & (1E<lt>E<lt>30)>).
1031
1032 =item *
1033
1034 When execution of the application reaches a subroutine call, a call
1035 to C<&DB::sub>(I<args>) is performed instead, with C<$DB::sub> being
1036 the name of the called subroutine. (Unless the subroutine is compiled
1037 in the package C<DB>.)
1038
1039 =back
1040
1041 Note that if C<&DB::sub> needs some external data to be setup for it
1042 to work, no subroutine call is possible until this is done.  For the
1043 standard debugger C<$DB::deep> (how many levels of recursion deep into
1044 the debugger you can go before a mandatory break) gives an example of
1045 such a dependency.
1046
1047 The minimal working debugger consists of one line
1048
1049   sub DB::DB {}
1050
1051 which is quite handy as contents of C<PERL5DB> environment
1052 variable:
1053
1054   env "PERL5DB=sub DB::DB {}" perl -d your-script
1055
1056 Another (a little bit more useful) minimal debugger can be created
1057 with the only line being
1058
1059   sub DB::DB {print ++$i; scalar <STDIN>}
1060
1061 This debugger would print the sequential number of encountered
1062 statement, and would wait for your C<CR> to continue.
1063
1064 The following debugger is quite functional:
1065
1066   {
1067     package DB;
1068     sub DB  {}
1069     sub sub {print ++$i, " $sub\n"; &$sub}
1070   }
1071
1072 It prints the sequential number of subroutine call and the name of the
1073 called subroutine.  Note that C<&DB::sub> should be compiled into the
1074 package C<DB>.
1075
1076 =head2 Debugger Internals
1077
1078 At the start, the debugger reads your rc file (F<./.perldb> or
1079 F<~/.perldb> under Unix), which can set important options.  This file may
1080 define a subroutine C<&afterinit> to be executed after the debugger is
1081 initialized.
1082
1083 After the rc file is read, the debugger reads environment variable
1084 PERLDB_OPTS and parses it as a rest of C<O ...> line in debugger prompt.
1085
1086 It also maintains magical internal variables, such as C<@DB::dbline>,
1087 C<%DB::dbline>, which are aliases for C<@{"::_<current_file"}>
1088 C<%{"::_<current_file"}>.  Here C<current_file> is the currently
1089 selected (with the debugger's C<f> command, or by flow of execution)
1090 file.
1091
1092 Some functions are provided to simplify customization.  See L<"Debugger
1093 Customization"> for description of C<DB::parse_options(string)>.  The
1094 function C<DB::dump_trace(skip[, count])> skips the specified number
1095 of frames, and returns a list containing info about the caller
1096 frames (all if C<count> is missing).  Each entry is a hash with keys
1097 C<context> (C<$> or C<@>), C<sub> (subroutine name, or info about
1098 eval), C<args> (C<undef> or a reference to an array), C<file>, and
1099 C<line>.
1100
1101 The function C<DB::print_trace(FH, skip[, count[, short]])> prints
1102 formatted info about caller frames.  The last two functions may be
1103 convenient as arguments to C<E<lt>>, C<E<lt>E<lt>> commands.
1104
1105 =head2 Other resources
1106
1107 You did try the B<-w> switch, didn't you?
1108
1109 =head2 BUGS
1110
1111 You cannot get the stack frame information or otherwise debug functions
1112 that were not compiled by Perl, such as C or C++ extensions.
1113
1114 If you alter your @_ arguments in a subroutine (such as with B<shift>
1115 or B<pop>, the stack backtrace will not show the original values.
1116
1117 =head1 Debugging Perl memory usage
1118
1119 Perl is I<very> frivolous with memory.  There is a saying that to
1120 estimate memory usage of Perl, assume a reasonable algorithm of
1121 allocation, and multiply your estimates by 10.  This is not absolutely
1122 true, but may give you a good grasp of what happens.
1123
1124 Say, an integer cannot take less than 20 bytes of memory, a float
1125 cannot take less than 24 bytes, a string cannot take less than 32
1126 bytes (all these examples assume 32-bit architectures, the result are
1127 much worse on 64-bit architectures).  If a variable is accessed in two
1128 of three different ways (which require an integer, a float, or a
1129 string), the memory footprint may increase by another 20 bytes.  A
1130 sloppy malloc() implementation will make these numbers yet more.
1131
1132 On the opposite end of the scale, a declaration like
1133
1134   sub foo;
1135
1136 may take (on some versions of perl) up to 500 bytes of memory.
1137
1138 Off-the-cuff anecdotal estimates of a code bloat give a factor around
1139 8.  This means that the compiled form of reasonable (commented
1140 indented etc.)  code will take approximately 8 times more than the
1141 disk space the code takes.
1142
1143 There are two Perl-specific ways to analyze the memory usage:
1144 $ENV{PERL_DEBUG_MSTATS} and B<-DL> switch.  First one is available
1145 only if perl is compiled with Perl's malloc(), the second one only if
1146 Perl compiled with C<-DDEBUGGING> (as with giving C<-D optimise=-g>
1147 option to F<Configure>).
1148
1149 =head2 Using C<$ENV{PERL_DEBUG_MSTATS}>
1150
1151 If your perl is using Perl's malloc(), and compiled with correct
1152 switches (this is the default), then it will print memory usage
1153 statistics after compiling your code (if C<$ENV{PERL_DEBUG_MSTATS}> >
1154 1), and before termination of the script (if
1155 C<$ENV{PERL_DEBUG_MSTATS}> >= 1).  The report format is similar to one
1156 in the following example:
1157
1158   env PERL_DEBUG_MSTATS=2 perl -e "require Carp"
1159   Memory allocation statistics after compilation: (buckets 4(4)..8188(8192)
1160      14216 free:   130   117    28     7     9   0   2     2   1 0 0
1161                 437    61    36     0     5
1162      60924 used:   125   137   161    55     7   8   6    16   2 0 1
1163                  74   109   304    84    20
1164   Total sbrk(): 77824/21:119. Odd ends: pad+heads+chain+tail: 0+636+0+2048.
1165   Memory allocation statistics after execution:   (buckets 4(4)..8188(8192)
1166      30888 free:   245    78    85    13     6   2   1     3   2 0 1
1167                 315   162    39    42    11
1168     175816 used:   265   176  1112   111    26  22  11    27   2 1 1
1169                 196   178  1066   798    39
1170   Total sbrk(): 215040/47:145. Odd ends: pad+heads+chain+tail: 0+2192+0+6144.
1171
1172 It is possible to ask for such a statistic at arbitrary moment by
1173 using Devel::Peek::mstats() (module Devel::Peek is available on CPAN).
1174
1175 Here is the explanation of different parts of the format:
1176
1177 =over
1178
1179 =item C<buckets SMALLEST(APPROX)..GREATEST(APPROX)>
1180
1181 Perl's malloc() uses bucketed allocations.  Every request is rounded
1182 up to the closest bucket size available, and a bucket of these size is
1183 taken from the pool of the buckets of this size.
1184
1185 The above line describes limits of buckets currently in use.  Each
1186 bucket has two sizes: memory footprint, and the maximal size of user
1187 data which may be put into this bucket.  Say, in the above example the
1188 smallest bucket is both sizes 4.  The biggest bucket has usable size
1189 8188, and the memory footprint 8192.  
1190
1191 With debugging Perl some buckets may have negative usable size.  This
1192 means that these buckets cannot (and will not) be used.  For greater
1193 buckets the memory footprint may be one page greater than a power of
1194 2.  In such a case the corresponding power of two is printed instead
1195 in the C<APPROX> field above.
1196
1197 =item Free/Used
1198
1199 The following 1 or 2 rows of numbers correspond to the number of
1200 buckets of each size between C<SMALLEST> and C<GREATEST>.  In the
1201 first row the sizes (memory footprints) of buckets are powers of two
1202 (or possibly one page greater).  In the second row (if present) the
1203 memory footprints of the buckets are between memory footprints of two
1204 buckets "above".  
1205
1206 Say, with the above example the memory footprints are (with current
1207 algorithm)
1208
1209      free:    8     16    32    64    128  256 512 1024 2048 4096 8192
1210            4     12    24    48    80
1211
1212 With non-C<DEBUGGING> perl the buckets starting from C<128>-long ones
1213 have 4-byte overhead, thus 8192-long bucket may take up to
1214 8188-byte-long allocations.
1215
1216 =item C<Total sbrk(): SBRKed/SBRKs:CONTINUOUS>
1217
1218 The first two fields give the total amount of memory perl sbrk()ed,
1219 and number of sbrk()s used.  The third number is what perl thinks
1220 about continuity of returned chunks.  As far as this number is
1221 positive, malloc() will assume that it is probable that sbrk() will
1222 provide continuous memory.
1223
1224 The amounts sbrk()ed by external libraries is not counted.
1225
1226 =item C<pad: 0>
1227
1228 The amount of sbrk()ed memory needed to keep buckets aligned.
1229
1230 =item C<heads: 2192>
1231
1232 While memory overhead of bigger buckets is kept inside the bucket, for
1233 smaller buckets it is kept in separate areas.  This field gives the
1234 total size of these areas.
1235
1236 =item C<chain: 0>
1237
1238 malloc() may want to subdivide a bigger bucket into smaller buckets.
1239 If only a part of the deceased-bucket is left non-subdivided, the rest
1240 is kept as an element of a linked list.  This field gives the total
1241 size of these chunks.
1242
1243 =item C<tail: 6144>
1244
1245 To minimize amount of sbrk()s malloc() asks for more memory.  This
1246 field gives the size of the yet-unused part, which is sbrk()ed, but
1247 never touched.
1248
1249 =back
1250
1251 =head2 Example of using B<-DL> switch
1252
1253 Below we show how to analyse memory usage by 
1254
1255   do 'lib/auto/POSIX/autosplit.ix';
1256
1257 The file in question contains a header and 146 lines similar to
1258
1259   sub getcwd ;
1260
1261 B<Note:> I<the discussion below supposes 32-bit architecture.  In the
1262 newer versions of perl the memory usage of the constructs discussed
1263 here is much improved, but the story discussed below is a real-life
1264 story.  This story is very terse, and assumes more than cursory
1265 knowledge of Perl internals.>
1266
1267 Here is the itemized list of Perl allocations performed during parsing
1268 of this file:
1269
1270  !!! "after" at test.pl line 3.
1271     Id  subtot   4   8  12  16  20  24  28  32  36  40  48  56  64  72  80 80+
1272   0 02   13752   .   .   .   . 294   .   .   .   .   .   .   .   .   .   .   4
1273   0 54    5545   .   .   8 124  16   .   .   .   1   1   .   .   .   .   .   3
1274   5 05      32   .   .   .   .   .   .   .   1   .   .   .   .   .   .   .   .
1275   6 02    7152   .   .   .   .   .   .   .   .   .   . 149   .   .   .   .   .
1276   7 02    3600   .   .   .   .   . 150   .   .   .   .   .   .   .   .   .   .
1277   7 03      64   .  -1   .   1   .   .   2   .   .   .   .   .   .   .   .   .
1278   7 04    7056   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   7
1279   7 17   38404   .   .   .   .   .   .   .   1   .   . 442 149   .   . 147   .
1280   9 03    2078  17 249  32   .   .   .   .   2   .   .   .   .   .   .   .   .
1281
1282
1283 To see this list insert two C<warn('!...')> statements around the call:
1284
1285   warn('!');
1286   do 'lib/auto/POSIX/autosplit.ix';
1287   warn('!!! "after"');
1288
1289 and run it with B<-DL> option.  The first warn() will print memory
1290 allocation info before the parsing of the file, and will memorize the
1291 statistics at this point (we ignore what it prints). The second warn()
1292 will print increments w.r.t. this memorized statistics.  This is the
1293 above printout.
1294
1295 Different I<Id>s on the left correspond to different subsystems of
1296 perl interpreter, they are just first argument given to perl memory
1297 allocation API New().  To find what C<9 03> means C<grep> the perl
1298 source for C<903>.  You will see that it is F<util.c>, function
1299 savepvn().  This function is used to store a copy of existing chunk of
1300 memory.  Using C debugger, one can see that it is called either
1301 directly from gv_init(), or via sv_magic(), and gv_init() is called
1302 from gv_fetchpv() - which is called from newSUB().
1303
1304 B<Note:> to reach this place in debugger and skip all the calls to
1305 savepvn during the compilation of the main script, set a C breakpoint
1306 in Perl_warn(), C<continue> this point is reached, I<then> set
1307 breakpoint in Perl_savepvn().  Note that you may need to skip a
1308 handful of Perl_savepvn() which do not correspond to mass production
1309 of CVs (there are more C<903> allocations than 146 similar lines of
1310 F<lib/auto/POSIX/autosplit.ix>).  Note also that C<Perl_> prefixes are
1311 added by macroization code in perl header files to avoid conflicts
1312 with external libraries.
1313
1314 Anyway, we see that C<903> ids correspond to creation of globs, twice
1315 per glob - for glob name, and glob stringification magic.
1316
1317 Here are explanations for other I<Id>s above: 
1318
1319 =over
1320
1321 =item C<717> 
1322
1323 is for creation of bigger C<XPV*> structures.  In the above case it
1324 creates 3 C<AV> per subroutine, one for a list of lexical variable
1325 names, one for a scratchpad (which contains lexical variables and
1326 C<targets>), and one for the array of scratchpads needed for
1327 recursion.  
1328
1329 It also creates a C<GV> and a C<CV> per subroutine (all called from
1330 start_subparse()).
1331
1332 =item C<002>
1333
1334 Creates C array corresponding to the C<AV> of scratchpads, and the
1335 scratchpad itself (the first fake entry of this scratchpad is created
1336 though the subroutine itself is not defined yet).
1337
1338 It also creates C arrays to keep data for the stash (this is one HV,
1339 but it grows, thus there are 4 big allocations: the big chunks are not
1340 freed, but are kept as additional arenas for C<SV> allocations).
1341
1342 =item C<054>
1343
1344 creates a C<HEK> for the name of the glob for the subroutine (this
1345 name is a key in a I<stash>).
1346
1347 Big allocations with this I<Id> correspond to allocations of new
1348 arenas to keep C<HE>.
1349
1350 =item C<602>
1351
1352 creates a C<GP> for the glob for the subroutine.
1353
1354 =item C<702>
1355
1356 creates the C<MAGIC> for the glob for the subroutine.
1357
1358 =item C<704>
1359
1360 creates I<arenas> which keep SVs.
1361
1362 =back
1363
1364 =head2 B<-DL> details
1365
1366 If Perl is run with B<-DL> option, then warn()s which start with `!'
1367 behave specially.  They print a list of I<categories> of memory
1368 allocations, and statistics of allocations of different sizes for
1369 these categories.
1370
1371 If warn() string starts with
1372
1373 =over
1374
1375 =item C<!!!> 
1376
1377 print changed categories only, print the differences in counts of allocations;
1378
1379 =item C<!!> 
1380
1381 print grown categories only; print the absolute values of counts, and totals;
1382
1383 =item C<!>
1384
1385 print nonempty categories, print the absolute values of counts and totals.
1386
1387 =back
1388
1389 =head2 Limitations of B<-DL> statistic
1390
1391 If an extension or an external library does not use Perl API to
1392 allocate memory, these allocations are not counted.
1393
1394 =head1 Debugging regular expressions
1395
1396 There are two ways to enable debugging output for regular expressions.
1397
1398 If your perl is compiled with C<-DDEBUGGING>, you may use the
1399 B<-Dr> flag on the command line.
1400
1401 Otherwise, one can C<use re 'debug'>, which has effects both at
1402 compile time, and at run time (and is I<not> lexically scoped).
1403
1404 =head2 Compile-time output
1405
1406 The debugging output for the compile time looks like this:
1407
1408   compiling RE `[bc]d(ef*g)+h[ij]k$'
1409   size 43 first at 1
1410      1: ANYOF(11)
1411     11: EXACT <d>(13)
1412     13: CURLYX {1,32767}(27)
1413     15:   OPEN1(17)
1414     17:     EXACT <e>(19)
1415     19:     STAR(22)
1416     20:       EXACT <f>(0)
1417     22:     EXACT <g>(24)
1418     24:   CLOSE1(26)
1419     26:   WHILEM(0)
1420     27: NOTHING(28)
1421     28: EXACT <h>(30)
1422     30: ANYOF(40)
1423     40: EXACT <k>(42)
1424     42: EOL(43)
1425     43: END(0)
1426   anchored `de' at 1 floating `gh' at 3..2147483647 (checking floating)
1427                                     stclass `ANYOF' minlen 7
1428
1429 The first line shows the pre-compiled form of the regexp, and the
1430 second shows the size of the compiled form (in arbitrary units,
1431 usually 4-byte words) and the label I<id> of the first node which
1432 does a match.
1433
1434 The last line (split into two lines in the above) contains the optimizer
1435 info.  In the example shown, the optimizer found that the match 
1436 should contain a substring C<de> at the offset 1, and substring C<gh>
1437 at some offset between 3 and infinity.  Moreover, when checking for
1438 these substrings (to abandon impossible matches quickly) it will check
1439 for the substring C<gh> before checking for the substring C<de>.  The
1440 optimizer may also use the knowledge that the match starts (at the
1441 C<first> I<id>) with a character class, and the match cannot be
1442 shorter than 7 chars.
1443
1444 The fields of interest which may appear in the last line are
1445
1446 =over
1447
1448 =item C<anchored> I<STRING> C<at> I<POS>
1449
1450 =item C<floating> I<STRING> C<at> I<POS1..POS2>
1451
1452 see above;
1453
1454 =item C<matching floating/anchored>
1455
1456 which substring to check first;
1457
1458 =item C<minlen>
1459
1460 the minimal length of the match;
1461
1462 =item C<stclass> I<TYPE>
1463
1464 The type of the first matching node.
1465
1466 =item C<noscan>
1467
1468 which advises to not scan for the found substrings;
1469
1470 =item C<isall>
1471
1472 which says that the optimizer info is in fact all that the regular
1473 expression contains (thus one does not need to enter the RE engine at
1474 all);
1475
1476 =item C<GPOS>
1477
1478 if the pattern contains C<\G>;
1479
1480 =item C<plus> 
1481
1482 if the pattern starts with a repeated char (as in C<x+y>);
1483
1484 =item C<implicit>
1485
1486 if the pattern starts with C<.*>;
1487
1488 =item C<with eval> 
1489
1490 if the pattern contain eval-groups (see L<perlre/(?{ code })>);
1491
1492 =item C<anchored(TYPE)>
1493
1494 if the pattern may
1495 match only at a handful of places  (with C<TYPE> being
1496 C<BOL>, C<MBOL>, or C<GPOS>, see the table below).
1497
1498 =back
1499
1500 If a substring is known to match at end-of-line only, it may be
1501 followed by C<$>, as in C<floating `k'$>.
1502
1503 The optimizer-specific info is used to avoid entering (a slow) RE
1504 engine on strings which will definitely not match.  If C<isall> flag
1505 is set, a call to the RE engine may be avoided even when optimizer
1506 found an appropriate place for the match.
1507
1508 The rest of the output contains the list of I<nodes> of the compiled
1509 form of the RE.  Each line has format 
1510
1511 C<   >I<id>: I<TYPE> I<OPTIONAL-INFO> (I<next-id>)
1512
1513 =head2 Types of nodes
1514
1515 Here is the list of possible types with short descriptions:
1516
1517     # TYPE arg-description [num-args] [longjump-len] DESCRIPTION
1518
1519     # Exit points
1520     END         no      End of program.
1521     SUCCEED     no      Return from a subroutine, basically.
1522
1523     # Anchors:
1524     BOL         no      Match "" at beginning of line.
1525     MBOL        no      Same, assuming multiline.
1526     SBOL        no      Same, assuming singleline.
1527     EOS         no      Match "" at end of string.
1528     EOL         no      Match "" at end of line.
1529     MEOL        no      Same, assuming multiline.
1530     SEOL        no      Same, assuming singleline.
1531     BOUND       no      Match "" at any word boundary
1532     BOUNDL      no      Match "" at any word boundary
1533     NBOUND      no      Match "" at any word non-boundary
1534     NBOUNDL     no      Match "" at any word non-boundary
1535     GPOS        no      Matches where last m//g left off.
1536
1537     # [Special] alternatives
1538     ANY         no      Match any one character (except newline).
1539     SANY        no      Match any one character.
1540     ANYOF       sv      Match character in (or not in) this class.
1541     ALNUM       no      Match any alphanumeric character
1542     ALNUML      no      Match any alphanumeric char in locale
1543     NALNUM      no      Match any non-alphanumeric character
1544     NALNUML     no      Match any non-alphanumeric char in locale
1545     SPACE       no      Match any whitespace character
1546     SPACEL      no      Match any whitespace char in locale
1547     NSPACE      no      Match any non-whitespace character
1548     NSPACEL     no      Match any non-whitespace char in locale
1549     DIGIT       no      Match any numeric character
1550     NDIGIT      no      Match any non-numeric character
1551
1552     # BRANCH    The set of branches constituting a single choice are hooked
1553     #           together with their "next" pointers, since precedence prevents
1554     #           anything being concatenated to any individual branch.  The
1555     #           "next" pointer of the last BRANCH in a choice points to the
1556     #           thing following the whole choice.  This is also where the
1557     #           final "next" pointer of each individual branch points; each
1558     #           branch starts with the operand node of a BRANCH node.
1559     #
1560     BRANCH      node    Match this alternative, or the next...
1561
1562     # BACK      Normal "next" pointers all implicitly point forward; BACK
1563     #           exists to make loop structures possible.
1564     # not used
1565     BACK        no      Match "", "next" ptr points backward.
1566
1567     # Literals
1568     EXACT       sv      Match this string (preceded by length).
1569     EXACTF      sv      Match this string, folded (prec. by length).
1570     EXACTFL     sv      Match this string, folded in locale (w/len).
1571
1572     # Do nothing
1573     NOTHING     no      Match empty string.
1574     # A variant of above which delimits a group, thus stops optimizations
1575     TAIL        no      Match empty string. Can jump here from outside.
1576
1577     # STAR,PLUS '?', and complex '*' and '+', are implemented as circular
1578     #           BRANCH structures using BACK.  Simple cases (one character
1579     #           per match) are implemented with STAR and PLUS for speed
1580     #           and to minimize recursive plunges.
1581     #
1582     STAR        node    Match this (simple) thing 0 or more times.
1583     PLUS        node    Match this (simple) thing 1 or more times.
1584
1585     CURLY       sv 2    Match this simple thing {n,m} times.
1586     CURLYN      no 2    Match next-after-this simple thing 
1587     #                   {n,m} times, set parenths.
1588     CURLYM      no 2    Match this medium-complex thing {n,m} times.
1589     CURLYX      sv 2    Match this complex thing {n,m} times.
1590
1591     # This terminator creates a loop structure for CURLYX
1592     WHILEM      no      Do curly processing and see if rest matches.
1593
1594     # OPEN,CLOSE,GROUPP ...are numbered at compile time.
1595     OPEN        num 1   Mark this point in input as start of #n.
1596     CLOSE       num 1   Analogous to OPEN.
1597
1598     REF         num 1   Match some already matched string
1599     REFF        num 1   Match already matched string, folded
1600     REFFL       num 1   Match already matched string, folded in loc.
1601
1602     # grouping assertions
1603     IFMATCH     off 1 2 Succeeds if the following matches.
1604     UNLESSM     off 1 2 Fails if the following matches.
1605     SUSPEND     off 1 1 "Independent" sub-RE.
1606     IFTHEN      off 1 1 Switch, should be preceeded by switcher .
1607     GROUPP      num 1   Whether the group matched.
1608
1609     # Support for long RE
1610     LONGJMP     off 1 1 Jump far away.
1611     BRANCHJ     off 1 1 BRANCH with long offset.
1612
1613     # The heavy worker
1614     EVAL        evl 1   Execute some Perl code.
1615
1616     # Modifiers
1617     MINMOD      no      Next operator is not greedy.
1618     LOGICAL     no      Next opcode should set the flag only.
1619
1620     # This is not used yet
1621     RENUM       off 1 1 Group with independently numbered parens.
1622
1623     # This is not really a node, but an optimized away piece of a "long" node.
1624     # To simplify debugging output, we mark it as if it were a node
1625     OPTIMIZED   off     Placeholder for dump.
1626
1627 =head2 Run-time output
1628
1629 First of all, when doing a match, one may get no run-time output even
1630 if debugging is enabled.  this means that the RE engine was never
1631 entered, all of the job was done by the optimizer.
1632
1633 If RE engine was entered, the output may look like this:
1634
1635   Matching `[bc]d(ef*g)+h[ij]k$' against `abcdefg__gh__'
1636     Setting an EVAL scope, savestack=3
1637      2 <ab> <cdefg__gh_>    |  1: ANYOF
1638      3 <abc> <defg__gh_>    | 11: EXACT <d>
1639      4 <abcd> <efg__gh_>    | 13: CURLYX {1,32767}
1640      4 <abcd> <efg__gh_>    | 26:   WHILEM
1641                                 0 out of 1..32767  cc=effff31c
1642      4 <abcd> <efg__gh_>    | 15:     OPEN1
1643      4 <abcd> <efg__gh_>    | 17:     EXACT <e>
1644      5 <abcde> <fg__gh_>    | 19:     STAR
1645                              EXACT <f> can match 1 times out of 32767...
1646     Setting an EVAL scope, savestack=3
1647      6 <bcdef> <g__gh__>    | 22:       EXACT <g>
1648      7 <bcdefg> <__gh__>    | 24:       CLOSE1
1649      7 <bcdefg> <__gh__>    | 26:       WHILEM
1650                                     1 out of 1..32767  cc=effff31c
1651     Setting an EVAL scope, savestack=12
1652      7 <bcdefg> <__gh__>    | 15:         OPEN1
1653      7 <bcdefg> <__gh__>    | 17:         EXACT <e>
1654        restoring \1 to 4(4)..7
1655                                     failed, try continuation...
1656      7 <bcdefg> <__gh__>    | 27:         NOTHING
1657      7 <bcdefg> <__gh__>    | 28:         EXACT <h>
1658                                     failed...
1659                                 failed...
1660
1661 The most significant information in the output is about the particular I<node>
1662 of the compiled RE which is currently being tested against the target string.
1663 The format of these lines is
1664
1665 C<    >I<STRING-OFFSET> <I<PRE-STRING>> <I<POST-STRING>>   |I<ID>:  I<TYPE>
1666
1667 The I<TYPE> info is indented with respect to the backtracking level.
1668 Other incidental information appears interspersed within.
1669
1670 =cut