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