1PERLDEBGUTS(1)         Perl Programmers Reference Guide         PERLDEBGUTS(1)
2
3
4

NAME

6       perldebguts - Guts of Perl debugging
7

DESCRIPTION

9       This is not the perldebug(1) manpage, which tells you how to use the
10       debugger.  This manpage describes low-level details concerning the
11       debugger's internals, which range from difficult to impossible to
12       understand for anyone who isn't incredibly intimate with Perl's guts.
13       Caveat lector.
14

Debugger Internals

16       Perl has special debugging hooks at compile-time and run-time used to
17       create debugging environments.  These hooks are not to be confused with
18       the perl -Dxxx command described in perlrun, which is usable only if a
19       special Perl is built per the instructions in the INSTALL podpage in
20       the Perl source tree.
21
22       For example, whenever you call Perl's built-in "caller" function from
23       the package "DB", the arguments that the corresponding stack frame was
24       called with are copied to the @DB::args array.  These mechanisms are
25       enabled by calling Perl with the -d switch.  Specifically, the
26       following additional features are enabled (cf. "$^P" in perlvar):
27
28       ·   Perl inserts the contents of $ENV{PERL5DB} (or "BEGIN {require
29           'perl5db.pl'}" if not present) before the first line of your
30           program.
31
32       ·   Each array "@{"_<$filename"}" holds the lines of $filename for a
33           file compiled by Perl.  The same is also true for "eval"ed strings
34           that contain subroutines, or which are currently being executed.
35           The $filename for "eval"ed strings looks like "(eval 34)".  Code
36           assertions in regexes look like "(re_eval 19)".
37
38           Values in this array are magical in numeric context: they compare
39           equal to zero only if the line is not breakable.
40
41       ·   Each hash "%{"_<$filename"}" contains breakpoints and actions keyed
42           by line number.  Individual entries (as opposed to the whole hash)
43           are settable.  Perl only cares about Boolean true here, although
44           the values used by perl5db.pl have the form
45           "$break_condition\0$action".
46
47           The same holds for evaluated strings that contain subroutines, or
48           which are currently being executed.  The $filename for "eval"ed
49           strings looks like "(eval 34)" or  "(re_eval 19)".
50
51       ·   Each scalar "${"_<$filename"}" contains "_<$filename".  This is
52           also the case for evaluated strings that contain subroutines, or
53           which are currently being executed.  The $filename for "eval"ed
54           strings looks like "(eval 34)" or "(re_eval 19)".
55
56       ·   After each "require"d file is compiled, but before it is executed,
57           "DB::postponed(*{"_<$filename"})" is called if the subroutine
58           "DB::postponed" exists.  Here, the $filename is the expanded name
59           of the "require"d file, as found in the values of %INC.
60
61       ·   After each subroutine "subname" is compiled, the existence of
62           $DB::postponed{subname} is checked.  If this key exists,
63           "DB::postponed(subname)" is called if the "DB::postponed"
64           subroutine also exists.
65
66       ·   A hash %DB::sub is maintained, whose keys are subroutine names and
67           whose values have the form "filename:startline-endline".
68           "filename" has the form "(eval 34)" for subroutines defined inside
69           "eval"s, or "(re_eval 19)" for those within regex code assertions.
70
71       ·   When the execution of your program reaches a point that can hold a
72           breakpoint, the "DB::DB()" subroutine is called if any of the
73           variables $DB::trace, $DB::single, or $DB::signal is true.  These
74           variables are not "local"izable.  This feature is disabled when
75           executing inside "DB::DB()", including functions called from it
76           unless "$^D & (1<<30)" is true.
77
78       ·   When execution of the program reaches a subroutine call, a call to
79           &DB::sub(args) is made instead, with $DB::sub holding the name of
80           the called subroutine. (This doesn't happen if the subroutine was
81           compiled in the "DB" package.)
82
83       Note that if &DB::sub needs external data for it to work, no subroutine
84       call is possible without it. As an example, the standard debugger's
85       &DB::sub depends on the $DB::deep variable (it defines how many levels
86       of recursion deep into the debugger you can go before a mandatory
87       break).  If $DB::deep is not defined, subroutine calls are not
88       possible, even though &DB::sub exists.
89
90   Writing Your Own Debugger
91       Environment Variables
92
93       The "PERL5DB" environment variable can be used to define a debugger.
94       For example, the minimal "working" debugger (it actually doesn't do
95       anything) consists of one line:
96
97         sub DB::DB {}
98
99       It can easily be defined like this:
100
101         $ PERL5DB="sub DB::DB {}" perl -d your-script
102
103       Another brief debugger, slightly more useful, can be created with only
104       the line:
105
106         sub DB::DB {print ++$i; scalar <STDIN>}
107
108       This debugger prints a number which increments for each statement
109       encountered and waits for you to hit a newline before continuing to the
110       next statement.
111
112       The following debugger is actually useful:
113
114         {
115           package DB;
116           sub DB  {}
117           sub sub {print ++$i, " $sub\n"; &$sub}
118         }
119
120       It prints the sequence number of each subroutine call and the name of
121       the called subroutine.  Note that &DB::sub is being compiled into the
122       package "DB" through the use of the "package" directive.
123
124       When it starts, the debugger reads your rc file (./.perldb or ~/.perldb
125       under Unix), which can set important options.  (A subroutine
126       (&afterinit) can be defined here as well; it is executed after the
127       debugger completes its own initialization.)
128
129       After the rc file is read, the debugger reads the PERLDB_OPTS
130       environment variable and uses it to set debugger options. The contents
131       of this variable are treated as if they were the argument of an "o ..."
132       debugger command (q.v. in "Options" in perldebug).
133
134       Debugger internal variables
135
136       In addition to the file and subroutine-related variables mentioned
137       above, the debugger also maintains various magical internal variables.
138
139       ·   @DB::dbline is an alias for "@{"::_<current_file"}", which holds
140           the lines of the currently-selected file (compiled by Perl), either
141           explicitly chosen with the debugger's "f" command, or implicitly by
142           flow of execution.
143
144           Values in this array are magical in numeric context: they compare
145           equal to zero only if the line is not breakable.
146
147       ·   %DB::dbline, is an alias for "%{"::_<current_file"}", which
148           contains breakpoints and actions keyed by line number in the
149           currently-selected file, either explicitly chosen with the
150           debugger's "f" command, or implicitly by flow of execution.
151
152           As previously noted, individual entries (as opposed to the whole
153           hash) are settable.  Perl only cares about Boolean true here,
154           although the values used by perl5db.pl have the form
155           "$break_condition\0$action".
156
157       Debugger customization functions
158
159       Some functions are provided to simplify customization.
160
161       ·   See "Configurable Options" in perldebug for a description of
162           options parsed by "DB::parse_options(string)".
163
164       ·   "DB::dump_trace(skip[,count])" skips the specified number of frames
165           and returns a list containing information about the calling frames
166           (all of them, if "count" is missing).  Each entry is reference to a
167           hash with keys "context" (either ".", "$", or "@"), "sub"
168           (subroutine name, or info about "eval"), "args" ("undef" or a
169           reference to an array), "file", and "line".
170
171       ·   "DB::print_trace(FH, skip[, count[, short]])" prints formatted info
172           about caller frames.  The last two functions may be convenient as
173           arguments to "<", "<<" commands.
174
175       Note that any variables and functions that are not documented in this
176       manpages (or in perldebug) are considered for internal use only, and as
177       such are subject to change without notice.
178

Frame Listing Output Examples

180       The "frame" option can be used to control the output of frame
181       information.  For example, contrast this expression trace:
182
183        $ perl -de 42
184        Stack dump during die enabled outside of evals.
185
186        Loading DB routines from perl5db.pl patch level 0.94
187        Emacs support available.
188
189        Enter h or `h h' for help.
190
191        main::(-e:1):   0
192          DB<1> sub foo { 14 }
193
194          DB<2> sub bar { 3 }
195
196          DB<3> t print foo() * bar()
197        main::((eval 172):3):   print foo() + bar();
198        main::foo((eval 168):2):
199        main::bar((eval 170):2):
200        42
201
202       with this one, once the "o"ption "frame=2" has been set:
203
204          DB<4> o f=2
205                       frame = '2'
206          DB<5> t print foo() * bar()
207        3:      foo() * bar()
208        entering main::foo
209         2:     sub foo { 14 };
210        exited main::foo
211        entering main::bar
212         2:     sub bar { 3 };
213        exited main::bar
214        42
215
216       By way of demonstration, we present below a laborious listing resulting
217       from setting your "PERLDB_OPTS" environment variable to the value "f=n
218       N", and running perl -d -V from the command line.  Examples use various
219       values of "n" are shown to give you a feel for the difference between
220       settings.  Long those it may be, this is not a complete listing, but
221       only excerpts.
222
223       1.
224             entering main::BEGIN
225              entering Config::BEGIN
226               Package lib/Exporter.pm.
227               Package lib/Carp.pm.
228              Package lib/Config.pm.
229              entering Config::TIEHASH
230              entering Exporter::import
231               entering Exporter::export
232             entering Config::myconfig
233              entering Config::FETCH
234              entering Config::FETCH
235              entering Config::FETCH
236              entering Config::FETCH
237
238       2.
239             entering main::BEGIN
240              entering Config::BEGIN
241               Package lib/Exporter.pm.
242               Package lib/Carp.pm.
243              exited Config::BEGIN
244              Package lib/Config.pm.
245              entering Config::TIEHASH
246              exited Config::TIEHASH
247              entering Exporter::import
248               entering Exporter::export
249               exited Exporter::export
250              exited Exporter::import
251             exited main::BEGIN
252             entering Config::myconfig
253              entering Config::FETCH
254              exited Config::FETCH
255              entering Config::FETCH
256              exited Config::FETCH
257              entering Config::FETCH
258
259       3.
260             in  $=main::BEGIN() from /dev/null:0
261              in  $=Config::BEGIN() from lib/Config.pm:2
262               Package lib/Exporter.pm.
263               Package lib/Carp.pm.
264              Package lib/Config.pm.
265              in  $=Config::TIEHASH('Config') from lib/Config.pm:644
266              in  $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
267               in  $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from li
268             in  @=Config::myconfig() from /dev/null:0
269              in  $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574
270              in  $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574
271              in  $=Config::FETCH(ref(Config), 'PERL_VERSION') from lib/Config.pm:574
272              in  $=Config::FETCH(ref(Config), 'PERL_SUBVERSION') from lib/Config.pm:574
273              in  $=Config::FETCH(ref(Config), 'osname') from lib/Config.pm:574
274              in  $=Config::FETCH(ref(Config), 'osvers') from lib/Config.pm:574
275
276       4.
277             in  $=main::BEGIN() from /dev/null:0
278              in  $=Config::BEGIN() from lib/Config.pm:2
279               Package lib/Exporter.pm.
280               Package lib/Carp.pm.
281              out $=Config::BEGIN() from lib/Config.pm:0
282              Package lib/Config.pm.
283              in  $=Config::TIEHASH('Config') from lib/Config.pm:644
284              out $=Config::TIEHASH('Config') from lib/Config.pm:644
285              in  $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
286               in  $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/
287               out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/
288              out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
289             out $=main::BEGIN() from /dev/null:0
290             in  @=Config::myconfig() from /dev/null:0
291              in  $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574
292              out $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574
293              in  $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574
294              out $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574
295              in  $=Config::FETCH(ref(Config), 'PERL_VERSION') from lib/Config.pm:574
296              out $=Config::FETCH(ref(Config), 'PERL_VERSION') from lib/Config.pm:574
297              in  $=Config::FETCH(ref(Config), 'PERL_SUBVERSION') from lib/Config.pm:574
298
299       5.
300             in  $=main::BEGIN() from /dev/null:0
301              in  $=Config::BEGIN() from lib/Config.pm:2
302               Package lib/Exporter.pm.
303               Package lib/Carp.pm.
304              out $=Config::BEGIN() from lib/Config.pm:0
305              Package lib/Config.pm.
306              in  $=Config::TIEHASH('Config') from lib/Config.pm:644
307              out $=Config::TIEHASH('Config') from lib/Config.pm:644
308              in  $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
309               in  $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/E
310               out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/E
311              out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
312             out $=main::BEGIN() from /dev/null:0
313             in  @=Config::myconfig() from /dev/null:0
314              in  $=Config::FETCH('Config=HASH(0x1aa444)', 'package') from lib/Config.pm:574
315              out $=Config::FETCH('Config=HASH(0x1aa444)', 'package') from lib/Config.pm:574
316              in  $=Config::FETCH('Config=HASH(0x1aa444)', 'baserev') from lib/Config.pm:574
317              out $=Config::FETCH('Config=HASH(0x1aa444)', 'baserev') from lib/Config.pm:574
318
319       6.
320             in  $=CODE(0x15eca4)() from /dev/null:0
321              in  $=CODE(0x182528)() from lib/Config.pm:2
322               Package lib/Exporter.pm.
323              out $=CODE(0x182528)() from lib/Config.pm:0
324              scalar context return from CODE(0x182528): undef
325              Package lib/Config.pm.
326              in  $=Config::TIEHASH('Config') from lib/Config.pm:628
327              out $=Config::TIEHASH('Config') from lib/Config.pm:628
328              scalar context return from Config::TIEHASH:   empty hash
329              in  $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
330               in  $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/Exporter.pm:171
331               out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/Exporter.pm:171
332               scalar context return from Exporter::export: ''
333              out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
334              scalar context return from Exporter::import: ''
335
336       In all cases shown above, the line indentation shows the call tree.  If
337       bit 2 of "frame" is set, a line is printed on exit from a subroutine as
338       well.  If bit 4 is set, the arguments are printed along with the caller
339       info.  If bit 8 is set, the arguments are printed even if they are tied
340       or references.  If bit 16 is set, the return value is printed, too.
341
342       When a package is compiled, a line like this
343
344           Package lib/Carp.pm.
345
346       is printed with proper indentation.
347

Debugging regular expressions

349       There are two ways to enable debugging output for regular expressions.
350
351       If your perl is compiled with "-DDEBUGGING", you may use the -Dr flag
352       on the command line.
353
354       Otherwise, one can "use re 'debug'", which has effects at compile time
355       and run time.  It is not lexically scoped.
356
357   Compile-time output
358       The debugging output at compile time looks like this:
359
360         Compiling REx `[bc]d(ef*g)+h[ij]k$'
361         size 45 Got 364 bytes for offset annotations.
362         first at 1
363         rarest char g at 0
364         rarest char d at 0
365            1: ANYOF[bc](12)
366           12: EXACT <d>(14)
367           14: CURLYX[0] {1,32767}(28)
368           16:   OPEN1(18)
369           18:     EXACT <e>(20)
370           20:     STAR(23)
371           21:       EXACT <f>(0)
372           23:     EXACT <g>(25)
373           25:   CLOSE1(27)
374           27:   WHILEM[1/1](0)
375           28: NOTHING(29)
376           29: EXACT <h>(31)
377           31: ANYOF[ij](42)
378           42: EXACT <k>(44)
379           44: EOL(45)
380           45: END(0)
381         anchored `de' at 1 floating `gh' at 3..2147483647 (checking floating)
382               stclass `ANYOF[bc]' minlen 7
383         Offsets: [45]
384               1[4] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 5[1]
385               0[0] 12[1] 0[0] 6[1] 0[0] 7[1] 0[0] 9[1] 8[1] 0[0] 10[1] 0[0]
386               11[1] 0[0] 12[0] 12[0] 13[1] 0[0] 14[4] 0[0] 0[0] 0[0] 0[0]
387               0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 18[1] 0[0] 19[1] 20[0]
388         Omitting $` $& $' support.
389
390       The first line shows the pre-compiled form of the regex.  The second
391       shows the size of the compiled form (in arbitrary units, usually 4-byte
392       words) and the total number of bytes allocated for the offset/length
393       table, usually 4+"size"*8.  The next line shows the label id of the
394       first node that does a match.
395
396       The
397
398         anchored `de' at 1 floating `gh' at 3..2147483647 (checking floating)
399               stclass `ANYOF[bc]' minlen 7
400
401       line (split into two lines above) contains optimizer information.  In
402       the example shown, the optimizer found that the match should contain a
403       substring "de" at offset 1, plus substring "gh" at some offset between
404       3 and infinity.  Moreover, when checking for these substrings (to
405       abandon impossible matches quickly), Perl will check for the substring
406       "gh" before checking for the substring "de".  The optimizer may also
407       use the knowledge that the match starts (at the "first" id) with a
408       character class, and no string shorter than 7 characters can possibly
409       match.
410
411       The fields of interest which may appear in this line are
412
413       "anchored" STRING "at" POS
414       "floating" STRING "at" POS1..POS2
415           See above.
416
417       "matching floating/anchored"
418           Which substring to check first.
419
420       "minlen"
421           The minimal length of the match.
422
423       "stclass" TYPE
424           Type of first matching node.
425
426       "noscan"
427           Don't scan for the found substrings.
428
429       "isall"
430           Means that the optimizer information is all that the regular
431           expression contains, and thus one does not need to enter the regex
432           engine at all.
433
434       "GPOS"
435           Set if the pattern contains "\G".
436
437       "plus"
438           Set if the pattern starts with a repeated char (as in "x+y").
439
440       "implicit"
441           Set if the pattern starts with ".*".
442
443       "with eval"
444           Set if the pattern contain eval-groups, such as "(?{ code })" and
445           "(??{ code })".
446
447       "anchored(TYPE)"
448           If the pattern may match only at a handful of places, (with "TYPE"
449           being "BOL", "MBOL", or "GPOS".  See the table below.
450
451       If a substring is known to match at end-of-line only, it may be
452       followed by "$", as in "floating `k'$".
453
454       The optimizer-specific information is used to avoid entering (a slow)
455       regex engine on strings that will not definitely match.  If the "isall"
456       flag is set, a call to the regex engine may be avoided even when the
457       optimizer found an appropriate place for the match.
458
459       Above the optimizer section is the list of nodes of the compiled form
460       of the regex.  Each line has format
461
462       "   "id: TYPE OPTIONAL-INFO (next-id)
463
464   Types of nodes
465       Here are the possible types, with short descriptions:
466
467           # TYPE arg-description [num-args] [longjump-len] DESCRIPTION
468
469           # Exit points
470           END         no      End of program.
471           SUCCEED     no      Return from a subroutine, basically.
472
473           # Anchors:
474           BOL         no      Match "" at beginning of line.
475           MBOL        no      Same, assuming multiline.
476           SBOL        no      Same, assuming singleline.
477           EOS         no      Match "" at end of string.
478           EOL         no      Match "" at end of line.
479           MEOL        no      Same, assuming multiline.
480           SEOL        no      Same, assuming singleline.
481           BOUND       no      Match "" at any word boundary
482           BOUNDL      no      Match "" at any word boundary
483           NBOUND      no      Match "" at any word non-boundary
484           NBOUNDL     no      Match "" at any word non-boundary
485           GPOS        no      Matches where last m//g left off.
486
487           # [Special] alternatives
488           ANY         no      Match any one character (except newline).
489           SANY        no      Match any one character.
490           ANYOF       sv      Match character in (or not in) this class.
491           ALNUM       no      Match any alphanumeric character
492           ALNUML      no      Match any alphanumeric char in locale
493           NALNUM      no      Match any non-alphanumeric character
494           NALNUML     no      Match any non-alphanumeric char in locale
495           SPACE       no      Match any whitespace character
496           SPACEL      no      Match any whitespace char in locale
497           NSPACE      no      Match any non-whitespace character
498           NSPACEL     no      Match any non-whitespace char in locale
499           DIGIT       no      Match any numeric character
500           NDIGIT      no      Match any non-numeric character
501
502           # BRANCH    The set of branches constituting a single choice are hooked
503           #           together with their "next" pointers, since precedence prevents
504           #           anything being concatenated to any individual branch.  The
505           #           "next" pointer of the last BRANCH in a choice points to the
506           #           thing following the whole choice.  This is also where the
507           #           final "next" pointer of each individual branch points; each
508           #           branch starts with the operand node of a BRANCH node.
509           #
510           BRANCH      node    Match this alternative, or the next...
511
512           # BACK      Normal "next" pointers all implicitly point forward; BACK
513           #           exists to make loop structures possible.
514           # not used
515           BACK        no      Match "", "next" ptr points backward.
516
517           # Literals
518           EXACT       sv      Match this string (preceded by length).
519           EXACTF      sv      Match this string, folded (prec. by length).
520           EXACTFL     sv      Match this string, folded in locale (w/len).
521
522           # Do nothing
523           NOTHING     no      Match empty string.
524           # A variant of above which delimits a group, thus stops optimizations
525           TAIL        no      Match empty string. Can jump here from outside.
526
527           # STAR,PLUS '?', and complex '*' and '+', are implemented as circular
528           #           BRANCH structures using BACK.  Simple cases (one character
529           #           per match) are implemented with STAR and PLUS for speed
530           #           and to minimize recursive plunges.
531           #
532           STAR        node    Match this (simple) thing 0 or more times.
533           PLUS        node    Match this (simple) thing 1 or more times.
534
535           CURLY       sv 2    Match this simple thing {n,m} times.
536           CURLYN      no 2    Match next-after-this simple thing
537           #                   {n,m} times, set parens.
538           CURLYM      no 2    Match this medium-complex thing {n,m} times.
539           CURLYX      sv 2    Match this complex thing {n,m} times.
540
541           # This terminator creates a loop structure for CURLYX
542           WHILEM      no      Do curly processing and see if rest matches.
543
544           # OPEN,CLOSE,GROUPP ...are numbered at compile time.
545           OPEN        num 1   Mark this point in input as start of #n.
546           CLOSE       num 1   Analogous to OPEN.
547
548           REF         num 1   Match some already matched string
549           REFF        num 1   Match already matched string, folded
550           REFFL       num 1   Match already matched string, folded in loc.
551
552           # grouping assertions
553           IFMATCH     off 1 2 Succeeds if the following matches.
554           UNLESSM     off 1 2 Fails if the following matches.
555           SUSPEND     off 1 1 "Independent" sub-regex.
556           IFTHEN      off 1 1 Switch, should be preceded by switcher .
557           GROUPP      num 1   Whether the group matched.
558
559           # Support for long regex
560           LONGJMP     off 1 1 Jump far away.
561           BRANCHJ     off 1 1 BRANCH with long offset.
562
563           # The heavy worker
564           EVAL        evl 1   Execute some Perl code.
565
566           # Modifiers
567           MINMOD      no      Next operator is not greedy.
568           LOGICAL     no      Next opcode should set the flag only.
569
570           # This is not used yet
571           RENUM       off 1 1 Group with independently numbered parens.
572
573           # This is not really a node, but an optimized away piece of a "long" node.
574           # To simplify debugging output, we mark it as if it were a node
575           OPTIMIZED   off     Placeholder for dump.
576
577       Following the optimizer information is a dump of the offset/length
578       table, here split across several lines:
579
580         Offsets: [45]
581               1[4] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 5[1]
582               0[0] 12[1] 0[0] 6[1] 0[0] 7[1] 0[0] 9[1] 8[1] 0[0] 10[1] 0[0]
583               11[1] 0[0] 12[0] 12[0] 13[1] 0[0] 14[4] 0[0] 0[0] 0[0] 0[0]
584               0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 18[1] 0[0] 19[1] 20[0]
585
586       The first line here indicates that the offset/length table contains 45
587       entries.  Each entry is a pair of integers, denoted by
588       "offset[length]".  Entries are numbered starting with 1, so entry #1
589       here is "1[4]" and entry #12 is "5[1]".  "1[4]" indicates that the node
590       labeled "1:" (the "1: ANYOF[bc]") begins at character position 1 in the
591       pre-compiled form of the regex, and has a length of 4 characters.
592       "5[1]" in position 12 indicates that the node labeled "12:" (the "12:
593       EXACT <d>") begins at character position 5 in the pre-compiled form of
594       the regex, and has a length of 1 character.  "12[1]" in position 14
595       indicates that the node labeled "14:" (the "14: CURLYX[0] {1,32767}")
596       begins at character position 12 in the pre-compiled form of the regex,
597       and has a length of 1 character---that is, it corresponds to the "+"
598       symbol in the precompiled regex.
599
600       "0[0]" items indicate that there is no corresponding node.
601
602   Run-time output
603       First of all, when doing a match, one may get no run-time output even
604       if debugging is enabled.  This means that the regex engine was never
605       entered and that all of the job was therefore done by the optimizer.
606
607       If the regex engine was entered, the output may look like this:
608
609         Matching `[bc]d(ef*g)+h[ij]k$' against `abcdefg__gh__'
610           Setting an EVAL scope, savestack=3
611            2 <ab> <cdefg__gh_>    |  1: ANYOF
612            3 <abc> <defg__gh_>    | 11: EXACT <d>
613            4 <abcd> <efg__gh_>    | 13: CURLYX {1,32767}
614            4 <abcd> <efg__gh_>    | 26:   WHILEM
615                                       0 out of 1..32767  cc=effff31c
616            4 <abcd> <efg__gh_>    | 15:     OPEN1
617            4 <abcd> <efg__gh_>    | 17:     EXACT <e>
618            5 <abcde> <fg__gh_>    | 19:     STAR
619                                    EXACT <f> can match 1 times out of 32767...
620           Setting an EVAL scope, savestack=3
621            6 <bcdef> <g__gh__>    | 22:       EXACT <g>
622            7 <bcdefg> <__gh__>    | 24:       CLOSE1
623            7 <bcdefg> <__gh__>    | 26:       WHILEM
624                                           1 out of 1..32767  cc=effff31c
625           Setting an EVAL scope, savestack=12
626            7 <bcdefg> <__gh__>    | 15:         OPEN1
627            7 <bcdefg> <__gh__>    | 17:         EXACT <e>
628              restoring \1 to 4(4)..7
629                                           failed, try continuation...
630            7 <bcdefg> <__gh__>    | 27:         NOTHING
631            7 <bcdefg> <__gh__>    | 28:         EXACT <h>
632                                           failed...
633                                       failed...
634
635       The most significant information in the output is about the particular
636       node of the compiled regex that is currently being tested against the
637       target string.  The format of these lines is
638
639       "    "STRING-OFFSET <PRE-STRING> <POST-STRING>   |ID:  TYPE
640
641       The TYPE info is indented with respect to the backtracking level.
642       Other incidental information appears interspersed within.
643

Debugging Perl memory usage

645       Perl is a profligate wastrel when it comes to memory use.  There is a
646       saying that to estimate memory usage of Perl, assume a reasonable
647       algorithm for memory allocation, multiply that estimate by 10, and
648       while you still may miss the mark, at least you won't be quite so
649       astonished.  This is not absolutely true, but may provide a good grasp
650       of what happens.
651
652       Assume that an integer cannot take less than 20 bytes of memory, a
653       float cannot take less than 24 bytes, a string cannot take less than 32
654       bytes (all these examples assume 32-bit architectures, the result are
655       quite a bit worse on 64-bit architectures).  If a variable is accessed
656       in two of three different ways (which require an integer, a float, or a
657       string), the memory footprint may increase yet another 20 bytes.  A
658       sloppy malloc(3) implementation can inflate these numbers dramatically.
659
660       On the opposite end of the scale, a declaration like
661
662         sub foo;
663
664       may take up to 500 bytes of memory, depending on which release of Perl
665       you're running.
666
667       Anecdotal estimates of source-to-compiled code bloat suggest an
668       eightfold increase.  This means that the compiled form of reasonable
669       (normally commented, properly indented etc.) code will take about eight
670       times more space in memory than the code took on disk.
671
672       The -DL command-line switch is obsolete since circa Perl 5.6.0 (it was
673       available only if Perl was built with "-DDEBUGGING").  The switch was
674       used to track Perl's memory allocations and possible memory leaks.
675       These days the use of malloc debugging tools like Purify or valgrind is
676       suggested instead.  See also "PERL_MEM_LOG" in perlhack.
677
678       One way to find out how much memory is being used by Perl data
679       structures is to install the Devel::Size module from CPAN: it gives you
680       the minimum number of bytes required to store a particular data
681       structure.  Please be mindful of the difference between the size() and
682       total_size().
683
684       If Perl has been compiled using Perl's malloc you can analyze Perl
685       memory usage by setting the $ENV{PERL_DEBUG_MSTATS}.
686
687   Using $ENV{PERL_DEBUG_MSTATS}
688       If your perl is using Perl's malloc() and was compiled with the
689       necessary switches (this is the default), then it will print memory
690       usage statistics after compiling your code when
691       "$ENV{PERL_DEBUG_MSTATS} > 1", and before termination of the program
692       when "$ENV{PERL_DEBUG_MSTATS} >= 1".  The report format is similar to
693       the following example:
694
695         $ PERL_DEBUG_MSTATS=2 perl -e "require Carp"
696         Memory allocation statistics after compilation: (buckets 4(4)..8188(8192)
697            14216 free:   130   117    28     7     9   0   2     2   1 0 0
698                       437    61    36     0     5
699            60924 used:   125   137   161    55     7   8   6    16   2 0 1
700                        74   109   304    84    20
701         Total sbrk(): 77824/21:119. Odd ends: pad+heads+chain+tail: 0+636+0+2048.
702         Memory allocation statistics after execution:   (buckets 4(4)..8188(8192)
703            30888 free:   245    78    85    13     6   2   1     3   2 0 1
704                       315   162    39    42    11
705           175816 used:   265   176  1112   111    26  22  11    27   2 1 1
706                       196   178  1066   798    39
707         Total sbrk(): 215040/47:145. Odd ends: pad+heads+chain+tail: 0+2192+0+6144.
708
709       It is possible to ask for such a statistic at arbitrary points in your
710       execution using the mstat() function out of the standard Devel::Peek
711       module.
712
713       Here is some explanation of that format:
714
715       "buckets SMALLEST(APPROX)..GREATEST(APPROX)"
716           Perl's malloc() uses bucketed allocations.  Every request is
717           rounded up to the closest bucket size available, and a bucket is
718           taken from the pool of buckets of that size.
719
720           The line above describes the limits of buckets currently in use.
721           Each bucket has two sizes: memory footprint and the maximal size of
722           user data that can fit into this bucket.  Suppose in the above
723           example that the smallest bucket were size 4.  The biggest bucket
724           would have usable size 8188, and the memory footprint would be
725           8192.
726
727           In a Perl built for debugging, some buckets may have negative
728           usable size.  This means that these buckets cannot (and will not)
729           be used.  For larger buckets, the memory footprint may be one page
730           greater than a power of 2.  If so, case the corresponding power of
731           two is printed in the "APPROX" field above.
732
733       Free/Used
734           The 1 or 2 rows of numbers following that correspond to the number
735           of buckets of each size between "SMALLEST" and "GREATEST".  In the
736           first row, the sizes (memory footprints) of buckets are powers of
737           two--or possibly one page greater.  In the second row, if present,
738           the memory footprints of the buckets are between the memory
739           footprints of two buckets "above".
740
741           For example, suppose under the previous example, the memory
742           footprints were
743
744                free:    8     16    32    64    128  256 512 1024 2048 4096 8192
745                      4     12    24    48    80
746
747           With non-"DEBUGGING" perl, the buckets starting from 128 have a
748           4-byte overhead, and thus an 8192-long bucket may take up to
749           8188-byte allocations.
750
751       "Total sbrk(): SBRKed/SBRKs:CONTINUOUS"
752           The first two fields give the total amount of memory perl sbrk(2)ed
753           (ess-broken? :-) and number of sbrk(2)s used.  The third number is
754           what perl thinks about continuity of returned chunks.  So long as
755           this number is positive, malloc() will assume that it is probable
756           that sbrk(2) will provide continuous memory.
757
758           Memory allocated by external libraries is not counted.
759
760       "pad: 0"
761           The amount of sbrk(2)ed memory needed to keep buckets aligned.
762
763       "heads: 2192"
764           Although memory overhead of bigger buckets is kept inside the
765           bucket, for smaller buckets, it is kept in separate areas.  This
766           field gives the total size of these areas.
767
768       "chain: 0"
769           malloc() may want to subdivide a bigger bucket into smaller
770           buckets.  If only a part of the deceased bucket is left
771           unsubdivided, the rest is kept as an element of a linked list.
772           This field gives the total size of these chunks.
773
774       "tail: 6144"
775           To minimize the number of sbrk(2)s, malloc() asks for more memory.
776           This field gives the size of the yet unused part, which is
777           sbrk(2)ed, but never touched.
778

SEE ALSO

780       perldebug, perlguts, perlrun re, and Devel::DProf.
781
782
783
784perl v5.10.1                      2009-02-12                    PERLDEBGUTS(1)
Impressum