1PERLDEBGUTS(1) Perl Programmers Reference Guide PERLDEBGUTS(1)
2
6 perldebguts - Guts of Perl debugging
7
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
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 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 follow‐
26 ing additional features are enabled (cf. "$^P" in perlvar):
27 · Perl inserts the contents of $ENV{PERL5DB} (or "BEGIN {require
29 'perl5db.pl'}" if not present) before the first line of your pro‐
30 gram.
31 · 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 Values in this array are magical in numeric context: they compare
39 equal to zero only if the line is not breakable.
40 · 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 "$break_condi‐
45 tion\0$action".
46 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 · 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 · 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 · After each subroutine "subname" is compiled, the existence of
62 $DB::postponed{subname} is checked. If this key exists, "DB::post‐
63 poned(subname)" is called if the "DB::postponed" subroutine also
64 exists.
65 · A hash %DB::sub is maintained, whose keys are subroutine names and
67 whose values have the form "filename:startline-endline". "file‐
68 name" has the form "(eval 34)" for subroutines defined inside
69 "eval"s, or "(re_eval 19)" for those within regex code assertions.
70 · 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 vari‐
73 ables $DB::trace, $DB::single, or $DB::signal is true. These vari‐
74 ables are not "local"izable. This feature is disabled when execut‐
75 ing inside "DB::DB()", including functions called from it unless
76 "$^D & (1<<30)" is true.
77 · 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 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 possi‐
88 ble, even though &DB::sub exists.
89 Writing Your Own Debugger
91 Environment Variables
93 The "PERL5DB" environment variable can be used to define a debugger.
95 For example, the minimal "working" debugger (it actually doesn't do
96 anything) consists of one line:
97 sub DB::DB {}
99 It can easily be defined like this:
101 $ PERL5DB="sub DB::DB {}" perl -d your-script
103 Another brief debugger, slightly more useful, can be created with only
105 the line:
106 sub DB::DB {print ++$i; scalar <STDIN>}
108 This debugger prints a number which increments for each statement
110 encountered and waits for you to hit a newline before continuing to the
111 next statement.
112 The following debugger is actually useful:
114 {
116 package DB;
117 sub DB {}
118 sub sub {print ++$i, " $sub\n"; &$sub}
119 }
120 It prints the sequence number of each subroutine call and the name of
122 the called subroutine. Note that &DB::sub is being compiled into the
123 package "DB" through the use of the "package" directive.
124 When it starts, the debugger reads your rc file (./.perldb or ~/.perldb
126 under Unix), which can set important options. (A subroutine
127 (&afterinit) can be defined here as well; it is executed after the
128 debugger completes its own initialization.)
129 After the rc file is read, the debugger reads the PERLDB_OPTS environ‐
131 ment variable and uses it to set debugger options. The contents of this
132 variable are treated as if they were the argument of an "o ..." debug‐
133 ger command (q.v. in "Options" in perldebug).
134 Debugger internal variables In addition to the file and subroutine-
136 related variables mentioned above, the debugger also maintains various
137 magical internal variables.
138 · @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 Values in this array are magical in numeric context: they compare
145 equal to zero only if the line is not breakable.
146 · %DB::dbline, is an alias for "%{"::_<current_file"}", which con‐
148 tains breakpoints and actions keyed by line number in the cur‐
149 rently-selected file, either explicitly chosen with the debugger's
150 "f" command, or implicitly by flow of execution.
151 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 "$break_condi‐
155 tion\0$action".
156 Debugger customization functions
158 Some functions are provided to simplify customization.
160 · See "Options" in perldebug for description of options parsed by
162 "DB::parse_options(string)" parses debugger options; see "Options"
163 in pperldebug for a description of options recognized.
164 · "DB::dump_trace(skip[,count])" skips the specified number of frames
166 and returns a list containing information about the calling frames
167 (all of them, if "count" is missing). Each entry is reference to a
168 hash with keys "context" (either ".", "$", or "@"), "sub" (subrou‐
169 tine name, or info about "eval"), "args" ("undef" or a reference to
170 an array), "file", and "line".
171 · "DB::print_trace(FH, skip[, count[, short]])" prints formatted info
173 about caller frames. The last two functions may be convenient as
174 arguments to "<", "<<" commands.
175 Note that any variables and functions that are not documented in this
177 manpages (or in perldebug) are considered for internal use only, and as
178 such are subject to change without notice.
179
181 The "frame" option can be used to control the output of frame informa‐
182 tion. For example, contrast this expression trace:
183 $ perl -de 42
185 Stack dump during die enabled outside of evals.
186 Loading DB routines from perl5db.pl patch level 0.94
188 Emacs support available.
189 Enter h or `h h' for help.
191 main::(-e:1): 0
193 DB<1> sub foo { 14 }
194 DB<2> sub bar { 3 }
196 DB<3> t print foo() * bar()
198 main::((eval 172):3): print foo() + bar();
199 main::foo((eval 168):2):
200 main::bar((eval 170):2):
201 42
202 with this one, once the "o"ption "frame=2" has been set:
204 DB<4> o f=2
206 frame = '2'
207 DB<5> t print foo() * bar()
208 3: foo() * bar()
209 entering main::foo
210 2: sub foo { 14 };
211 exited main::foo
212 entering main::bar
213 2: sub bar { 3 };
214 exited main::bar
215 42
216 By way of demonstration, we present below a laborious listing resulting
218 from setting your "PERLDB_OPTS" environment variable to the value "f=n
219 N", and running perl -d -V from the command line. Examples use various
220 values of "n" are shown to give you a feel for the difference between
221 settings. Long those it may be, this is not a complete listing, but
222 only excerpts.
223 1
225 entering main::BEGIN
226 entering Config::BEGIN
227 Package lib/Exporter.pm.
228 Package lib/Carp.pm.
229 Package lib/Config.pm.
230 entering Config::TIEHASH
231 entering Exporter::import
232 entering Exporter::export
233 entering Config::myconfig
234 entering Config::FETCH
235 entering Config::FETCH
236 entering Config::FETCH
237 entering Config::FETCH
238 2
240 entering main::BEGIN
241 entering Config::BEGIN
242 Package lib/Exporter.pm.
243 Package lib/Carp.pm.
244 exited Config::BEGIN
245 Package lib/Config.pm.
246 entering Config::TIEHASH
247 exited Config::TIEHASH
248 entering Exporter::import
249 entering Exporter::export
250 exited Exporter::export
251 exited Exporter::import
252 exited main::BEGIN
253 entering Config::myconfig
254 entering Config::FETCH
255 exited Config::FETCH
256 entering Config::FETCH
257 exited Config::FETCH
258 entering Config::FETCH
259 4
261 in $=main::BEGIN() from /dev/null:0
262 in $=Config::BEGIN() from lib/Config.pm:2
263 Package lib/Exporter.pm.
264 Package lib/Carp.pm.
265 Package lib/Config.pm.
266 in $=Config::TIEHASH('Config') from lib/Config.pm:644
267 in $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
268 in $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from li
269 in @=Config::myconfig() from /dev/null:0
270 in $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574
271 in $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574
272 in $=Config::FETCH(ref(Config), 'PERL_VERSION') from lib/Config.pm:574
273 in $=Config::FETCH(ref(Config), 'PERL_SUBVERSION') from lib/Config.pm:574
274 in $=Config::FETCH(ref(Config), 'osname') from lib/Config.pm:574
275 in $=Config::FETCH(ref(Config), 'osvers') from lib/Config.pm:574
276 6
278 in $=main::BEGIN() from /dev/null:0
279 in $=Config::BEGIN() from lib/Config.pm:2
280 Package lib/Exporter.pm.
281 Package lib/Carp.pm.
282 out $=Config::BEGIN() from lib/Config.pm:0
283 Package lib/Config.pm.
284 in $=Config::TIEHASH('Config') from lib/Config.pm:644
285 out $=Config::TIEHASH('Config') from lib/Config.pm:644
286 in $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
287 in $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/
288 out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/
289 out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
290 out $=main::BEGIN() from /dev/null:0
291 in @=Config::myconfig() from /dev/null:0
292 in $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574
293 out $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574
294 in $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574
295 out $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574
296 in $=Config::FETCH(ref(Config), 'PERL_VERSION') from lib/Config.pm:574
297 out $=Config::FETCH(ref(Config), 'PERL_VERSION') from lib/Config.pm:574
298 in $=Config::FETCH(ref(Config), 'PERL_SUBVERSION') from lib/Config.pm:574
299 14
301 in $=main::BEGIN() from /dev/null:0
302 in $=Config::BEGIN() from lib/Config.pm:2
303 Package lib/Exporter.pm.
304 Package lib/Carp.pm.
305 out $=Config::BEGIN() from lib/Config.pm:0
306 Package lib/Config.pm.
307 in $=Config::TIEHASH('Config') from lib/Config.pm:644
308 out $=Config::TIEHASH('Config') from lib/Config.pm:644
309 in $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
310 in $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/E
311 out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/E
312 out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
313 out $=main::BEGIN() from /dev/null:0
314 in @=Config::myconfig() from /dev/null:0
315 in $=Config::FETCH('Config=HASH(0x1aa444)', 'package') from lib/Config.pm:574
316 out $=Config::FETCH('Config=HASH(0x1aa444)', 'package') from lib/Config.pm:574
317 in $=Config::FETCH('Config=HASH(0x1aa444)', 'baserev') from lib/Config.pm:574
318 out $=Config::FETCH('Config=HASH(0x1aa444)', 'baserev') from lib/Config.pm:574
319 30
321 in $=CODE(0x15eca4)() from /dev/null:0
322 in $=CODE(0x182528)() from lib/Config.pm:2
323 Package lib/Exporter.pm.
324 out $=CODE(0x182528)() from lib/Config.pm:0
325 scalar context return from CODE(0x182528): undef
326 Package lib/Config.pm.
327 in $=Config::TIEHASH('Config') from lib/Config.pm:628
328 out $=Config::TIEHASH('Config') from lib/Config.pm:628
329 scalar context return from Config::TIEHASH: empty hash
330 in $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
331 in $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/Exporter.pm:171
332 out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/Exporter.pm:171
333 scalar context return from Exporter::export: ''
334 out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
335 scalar context return from Exporter::import: ''
336 In all cases shown above, the line indentation shows the call tree. If
338 bit 2 of "frame" is set, a line is printed on exit from a subroutine as
339 well. If bit 4 is set, the arguments are printed along with the caller
340 info. If bit 8 is set, the arguments are printed even if they are tied
341 or references. If bit 16 is set, the return value is printed, too.
342 When a package is compiled, a line like this
344 Package lib/Carp.pm.
346 is printed with proper indentation.
348
350 There are two ways to enable debugging output for regular expressions.
351 If your perl is compiled with "-DDEBUGGING", you may use the -Dr flag
353 on the command line.
354 Otherwise, one can "use re 'debug'", which has effects at compile time
356 and run time. It is not lexically scoped.
357 Compile-time output
359 The debugging output at compile time looks like this:
361 Compiling REx `[bc]d(ef*g)+h[ij]k$'
363 size 45 Got 364 bytes for offset annotations.
364 first at 1
365 rarest char g at 0
366 rarest char d at 0
367 1: ANYOF[bc](12)
368 12: EXACT <d>(14)
369 14: CURLYX[0] {1,32767}(28)
370 16: OPEN1(18)
371 18: EXACT <e>(20)
372 20: STAR(23)
373 21: EXACT <f>(0)
374 23: EXACT <g>(25)
375 25: CLOSE1(27)
376 27: WHILEM[1/1](0)
377 28: NOTHING(29)
378 29: EXACT <h>(31)
379 31: ANYOF[ij](42)
380 42: EXACT <k>(44)
381 44: EOL(45)
382 45: END(0)
383 anchored `de' at 1 floating `gh' at 3..2147483647 (checking floating)
384 stclass `ANYOF[bc]' minlen 7
385 Offsets: [45]
386 1[4] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 5[1]
387 0[0] 12[1] 0[0] 6[1] 0[0] 7[1] 0[0] 9[1] 8[1] 0[0] 10[1] 0[0]
388 11[1] 0[0] 12[0] 12[0] 13[1] 0[0] 14[4] 0[0] 0[0] 0[0] 0[0]
389 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 18[1] 0[0] 19[1] 20[0]
390 Omitting $` $& $' support.
391 The first line shows the pre-compiled form of the regex. The second
393 shows the size of the compiled form (in arbitrary units, usually 4-byte
394 words) and the total number of bytes allocated for the offset/length
395 table, usually 4+"size"*8. The next line shows the label id of the
396 first node that does a match.
397 The
399 anchored `de' at 1 floating `gh' at 3..2147483647 (checking floating)
401 stclass `ANYOF[bc]' minlen 7
402 line (split into two lines above) contains optimizer information. In
404 the example shown, the optimizer found that the match should contain a
405 substring "de" at offset 1, plus substring "gh" at some offset between
406 3 and infinity. Moreover, when checking for these substrings (to aban‐
407 don impossible matches quickly), Perl will check for the substring "gh"
408 before checking for the substring "de". The optimizer may also use the
409 knowledge that the match starts (at the "first" id) with a character
410 class, and no string shorter than 7 characters can possibly match.
411 The fields of interest which may appear in this line are
413 "anchored" STRING "at" POS
415 "floating" STRING "at" POS1..POS2
416 See above.
417 "matching floating/anchored"
419 Which substring to check first.
420 "minlen"
422 The minimal length of the match.
423 "stclass" TYPE
425 Type of first matching node.
426 "noscan"
428 Don't scan for the found substrings.
429 "isall"
431 Means that the optimizer information is all that the regular
432 expression contains, and thus one does not need to enter the regex
433 engine at all.
434 "GPOS"
436 Set if the pattern contains "\G".
437 "plus"
439 Set if the pattern starts with a repeated char (as in "x+y").
440 "implicit"
442 Set if the pattern starts with ".*".
443 "with eval"
445 Set if the pattern contain eval-groups, such as "(?{ code })" and
446 "(??{ code })".
447 "anchored(TYPE)"
449 If the pattern may match only at a handful of places, (with "TYPE"
450 being "BOL", "MBOL", or "GPOS". See the table below.
451 If a substring is known to match at end-of-line only, it may be fol‐
453 lowed by "$", as in "floating `k'$".
454 The optimizer-specific information is used to avoid entering (a slow)
456 regex engine on strings that will not definitely match. If the "isall"
457 flag is set, a call to the regex engine may be avoided even when the
458 optimizer found an appropriate place for the match.
459 Above the optimizer section is the list of nodes of the compiled form
461 of the regex. Each line has format
462 " "id: TYPE OPTIONAL-INFO (next-id)
464 Types of nodes
466 Here are the possible types, with short descriptions:
468 # TYPE arg-description [num-args] [longjump-len] DESCRIPTION
470 # Exit points
472 END no End of program.
473 SUCCEED no Return from a subroutine, basically.
474 # Anchors:
476 BOL no Match "" at beginning of line.
477 MBOL no Same, assuming multiline.
478 SBOL no Same, assuming singleline.
479 EOS no Match "" at end of string.
480 EOL no Match "" at end of line.
481 MEOL no Same, assuming multiline.
482 SEOL no Same, assuming singleline.
483 BOUND no Match "" at any word boundary
484 BOUNDL no Match "" at any word boundary
485 NBOUND no Match "" at any word non-boundary
486 NBOUNDL no Match "" at any word non-boundary
487 GPOS no Matches where last m//g left off.
488 # [Special] alternatives
490 ANY no Match any one character (except newline).
491 SANY no Match any one character.
492 ANYOF sv Match character in (or not in) this class.
493 ALNUM no Match any alphanumeric character
494 ALNUML no Match any alphanumeric char in locale
495 NALNUM no Match any non-alphanumeric character
496 NALNUML no Match any non-alphanumeric char in locale
497 SPACE no Match any whitespace character
498 SPACEL no Match any whitespace char in locale
499 NSPACE no Match any non-whitespace character
500 NSPACEL no Match any non-whitespace char in locale
501 DIGIT no Match any numeric character
502 NDIGIT no Match any non-numeric character
503 # BRANCH The set of branches constituting a single choice are hooked
505 # together with their "next" pointers, since precedence prevents
506 # anything being concatenated to any individual branch. The
507 # "next" pointer of the last BRANCH in a choice points to the
508 # thing following the whole choice. This is also where the
509 # final "next" pointer of each individual branch points; each
510 # branch starts with the operand node of a BRANCH node.
511 #
512 BRANCH node Match this alternative, or the next...
513 # BACK Normal "next" pointers all implicitly point forward; BACK
515 # exists to make loop structures possible.
516 # not used
517 BACK no Match "", "next" ptr points backward.
518 # Literals
520 EXACT sv Match this string (preceded by length).
521 EXACTF sv Match this string, folded (prec. by length).
522 EXACTFL sv Match this string, folded in locale (w/len).
523 # Do nothing
525 NOTHING no Match empty string.
526 # A variant of above which delimits a group, thus stops optimizations
527 TAIL no Match empty string. Can jump here from outside.
528 # STAR,PLUS '?', and complex '*' and '+', are implemented as circular
530 # BRANCH structures using BACK. Simple cases (one character
531 # per match) are implemented with STAR and PLUS for speed
532 # and to minimize recursive plunges.
533 #
534 STAR node Match this (simple) thing 0 or more times.
535 PLUS node Match this (simple) thing 1 or more times.
536 CURLY sv 2 Match this simple thing {n,m} times.
538 CURLYN no 2 Match next-after-this simple thing
539 # {n,m} times, set parens.
540 CURLYM no 2 Match this medium-complex thing {n,m} times.
541 CURLYX sv 2 Match this complex thing {n,m} times.
542 # This terminator creates a loop structure for CURLYX
544 WHILEM no Do curly processing and see if rest matches.
545 # OPEN,CLOSE,GROUPP ...are numbered at compile time.
547 OPEN num 1 Mark this point in input as start of #n.
548 CLOSE num 1 Analogous to OPEN.
549 REF num 1 Match some already matched string
551 REFF num 1 Match already matched string, folded
552 REFFL num 1 Match already matched string, folded in loc.
553 # grouping assertions
555 IFMATCH off 1 2 Succeeds if the following matches.
556 UNLESSM off 1 2 Fails if the following matches.
557 SUSPEND off 1 1 "Independent" sub-regex.
558 IFTHEN off 1 1 Switch, should be preceded by switcher .
559 GROUPP num 1 Whether the group matched.
560 # Support for long regex
562 LONGJMP off 1 1 Jump far away.
563 BRANCHJ off 1 1 BRANCH with long offset.
564 # The heavy worker
566 EVAL evl 1 Execute some Perl code.
567 # Modifiers
569 MINMOD no Next operator is not greedy.
570 LOGICAL no Next opcode should set the flag only.
571 # This is not used yet
573 RENUM off 1 1 Group with independently numbered parens.
574 # This is not really a node, but an optimized away piece of a "long" node.
576 # To simplify debugging output, we mark it as if it were a node
577 OPTIMIZED off Placeholder for dump.
578 Following the optimizer information is a dump of the offset/length ta‐
580 ble, here split across several lines:
581 Offsets: [45]
583 1[4] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 5[1]
584 0[0] 12[1] 0[0] 6[1] 0[0] 7[1] 0[0] 9[1] 8[1] 0[0] 10[1] 0[0]
585 11[1] 0[0] 12[0] 12[0] 13[1] 0[0] 14[4] 0[0] 0[0] 0[0] 0[0]
586 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 18[1] 0[0] 19[1] 20[0]
587 The first line here indicates that the offset/length table contains 45
589 entries. Each entry is a pair of integers, denoted by "off‐
590 set[length]". Entries are numbered starting with 1, so entry #1 here
591 is "1[4]" and entry #12 is "5[1]". "1[4]" indicates that the node
592 labeled "1:" (the "1: ANYOF[bc]") begins at character position 1 in the
593 pre-compiled form of the regex, and has a length of 4 characters.
594 "5[1]" in position 12 indicates that the node labeled "12:" (the "12:
595 EXACT <d>") begins at character position 5 in the pre-compiled form of
596 the regex, and has a length of 1 character. "12[1]" in position 14
597 indicates that the node labeled "14:" (the "14: CURLYX[0] {1,32767}")
598 begins at character position 12 in the pre-compiled form of the regex,
599 and has a length of 1 character---that is, it corresponds to the "+"
600 symbol in the precompiled regex.
601 "0[0]" items indicate that there is no corresponding node.
603 Run-time output
605 First of all, when doing a match, one may get no run-time output even
607 if debugging is enabled. This means that the regex engine was never
608 entered and that all of the job was therefore done by the optimizer.
609 If the regex engine was entered, the output may look like this:
611 Matching `[bc]d(ef*g)+h[ij]k$' against `abcdefg__gh__'
613 Setting an EVAL scope, savestack=3
614 2 <ab> <cdefg__gh_> ⎪ 1: ANYOF
615 3 <abc> <defg__gh_> ⎪ 11: EXACT <d>
616 4 <abcd> <efg__gh_> ⎪ 13: CURLYX {1,32767}
617 4 <abcd> <efg__gh_> ⎪ 26: WHILEM
618 0 out of 1..32767 cc=effff31c
619 4 <abcd> <efg__gh_> ⎪ 15: OPEN1
620 4 <abcd> <efg__gh_> ⎪ 17: EXACT <e>
621 5 <abcde> <fg__gh_> ⎪ 19: STAR
622 EXACT <f> can match 1 times out of 32767...
623 Setting an EVAL scope, savestack=3
624 6 <bcdef> <g__gh__> ⎪ 22: EXACT <g>
625 7 <bcdefg> <__gh__> ⎪ 24: CLOSE1
626 7 <bcdefg> <__gh__> ⎪ 26: WHILEM
627 1 out of 1..32767 cc=effff31c
628 Setting an EVAL scope, savestack=12
629 7 <bcdefg> <__gh__> ⎪ 15: OPEN1
630 7 <bcdefg> <__gh__> ⎪ 17: EXACT <e>
631 restoring \1 to 4(4)..7
632 failed, try continuation...
633 7 <bcdefg> <__gh__> ⎪ 27: NOTHING
634 7 <bcdefg> <__gh__> ⎪ 28: EXACT <h>
635 failed...
636 failed...
637 The most significant information in the output is about the particular
639 node of the compiled regex that is currently being tested against the
640 target string. The format of these lines is
641 " "STRING-OFFSET <PRE-STRING> <POST-STRING> ⎪ID: TYPE
643 The TYPE info is indented with respect to the backtracking level.
645 Other incidental information appears interspersed within.
646
648 Perl is a profligate wastrel when it comes to memory use. There is a
649 saying that to estimate memory usage of Perl, assume a reasonable algo‐
650 rithm for memory allocation, multiply that estimate by 10, and while
651 you still may miss the mark, at least you won't be quite so astonished.
652 This is not absolutely true, but may provide a good grasp of what hap‐
653 pens.
654 Assume that an integer cannot take less than 20 bytes of memory, a
656 float cannot take less than 24 bytes, a string cannot take less than 32
657 bytes (all these examples assume 32-bit architectures, the result are
658 quite a bit worse on 64-bit architectures). If a variable is accessed
659 in two of three different ways (which require an integer, a float, or a
660 string), the memory footprint may increase yet another 20 bytes. A
661 sloppy malloc(3) implementation can inflate these numbers dramatically.
662 On the opposite end of the scale, a declaration like
664 sub foo;
666 may take up to 500 bytes of memory, depending on which release of Perl
668 you're running.
669 Anecdotal estimates of source-to-compiled code bloat suggest an eight‐
671 fold increase. This means that the compiled form of reasonable (nor‐
672 mally commented, properly indented etc.) code will take about eight
673 times more space in memory than the code took on disk.
674 The -DL command-line switch is obsolete since circa Perl 5.6.0 (it was
676 available only if Perl was built with "-DDEBUGGING"). The switch was
677 used to track Perl's memory allocations and possible memory leaks.
678 These days the use of malloc debugging tools like Purify or valgrind is
679 suggested instead.
680 One way to find out how much memory is being used by Perl data struc‐
682 tures is to install the Devel::Size module from CPAN: it gives you the
683 minimum number of bytes required to store a particular data structure.
684 Please be mindful of the difference between the size() and
685 total_size().
686 If Perl has been compiled using Perl's malloc you can analyze Perl mem‐
688 ory usage by setting the $ENV{PERL_DEBUG_MSTATS}.
689 Using $ENV{PERL_DEBUG_MSTATS}
691 If your perl is using Perl's malloc() and was compiled with the neces‐
693 sary switches (this is the default), then it will print memory usage
694 statistics after compiling your code when "$ENV{PERL_DEBUG_MSTATS} >
695 1", and before termination of the program when "$ENV{PERL_DEBUG_MSTATS}
696 >= 1". The report format is similar to the following example:
697 $ PERL_DEBUG_MSTATS=2 perl -e "require Carp"
699 Memory allocation statistics after compilation: (buckets 4(4)..8188(8192)
700 14216 free: 130 117 28 7 9 0 2 2 1 0 0
701 437 61 36 0 5
702 60924 used: 125 137 161 55 7 8 6 16 2 0 1
703 74 109 304 84 20
704 Total sbrk(): 77824/21:119. Odd ends: pad+heads+chain+tail: 0+636+0+2048.
705 Memory allocation statistics after execution: (buckets 4(4)..8188(8192)
706 30888 free: 245 78 85 13 6 2 1 3 2 0 1
707 315 162 39 42 11
708 175816 used: 265 176 1112 111 26 22 11 27 2 1 1
709 196 178 1066 798 39
710 Total sbrk(): 215040/47:145. Odd ends: pad+heads+chain+tail: 0+2192+0+6144.
711 It is possible to ask for such a statistic at arbitrary points in your
713 execution using the mstat() function out of the standard Devel::Peek
714 module.
715 Here is some explanation of that format:
717 "buckets SMALLEST(APPROX)..GREATEST(APPROX)"
719 Perl's malloc() uses bucketed allocations. Every request is
720 rounded up to the closest bucket size available, and a bucket is
721 taken from the pool of buckets of that size.
722 The line above describes the limits of buckets currently in use.
724 Each bucket has two sizes: memory footprint and the maximal size of
725 user data that can fit into this bucket. Suppose in the above
726 example that the smallest bucket were size 4. The biggest bucket
727 would have usable size 8188, and the memory footprint would be
728 8192.
729 In a Perl built for debugging, some buckets may have negative
731 usable size. This means that these buckets cannot (and will not)
732 be used. For larger buckets, the memory footprint may be one page
733 greater than a power of 2. If so, case the corresponding power of
734 two is printed in the "APPROX" field above.
735 Free/Used
737 The 1 or 2 rows of numbers following that correspond to the number
738 of buckets of each size between "SMALLEST" and "GREATEST". In the
739 first row, the sizes (memory footprints) of buckets are powers of
740 two--or possibly one page greater. In the second row, if present,
741 the memory footprints of the buckets are between the memory foot‐
742 prints of two buckets "above".
743 For example, suppose under the previous example, the memory foot‐
745 prints were
746 free: 8 16 32 64 128 256 512 1024 2048 4096 8192
748 4 12 24 48 80
749 With non-"DEBUGGING" perl, the buckets starting from 128 have a
751 4-byte overhead, and thus an 8192-long bucket may take up to
752 8188-byte allocations.
753 "Total sbrk(): SBRKed/SBRKs:CONTINUOUS"
755 The first two fields give the total amount of memory perl sbrk(2)ed
756 (ess-broken? :-) and number of sbrk(2)s used. The third number is
757 what perl thinks about continuity of returned chunks. So long as
758 this number is positive, malloc() will assume that it is probable
759 that sbrk(2) will provide continuous memory.
760 Memory allocated by external libraries is not counted.
762 "pad: 0"
764 The amount of sbrk(2)ed memory needed to keep buckets aligned.
765 "heads: 2192"
767 Although memory overhead of bigger buckets is kept inside the
768 bucket, for smaller buckets, it is kept in separate areas. This
769 field gives the total size of these areas.
770 "chain: 0"
772 malloc() may want to subdivide a bigger bucket into smaller buck‐
773 ets. If only a part of the deceased bucket is left unsubdivided,
774 the rest is kept as an element of a linked list. This field gives
775 the total size of these chunks.
776 "tail: 6144"
778 To minimize the number of sbrk(2)s, malloc() asks for more memory.
779 This field gives the size of the yet unused part, which is
780 sbrk(2)ed, but never touched.
781
783 perldebug, perlguts, perlrun re, and Devel::DProf.
784perl v5.8.8 2006-01-07 PERLDEBGUTS(1)