3 perldebguts - Guts of Perl debugging
7 This is not L<perldebug>, which tells you how to use
8 the debugger. This manpage describes low-level details concerning
9 the debugger's internals, which range from difficult to impossible
10 to understand for anyone who isn't incredibly intimate with Perl's guts.
13 =head1 Debugger Internals
15 Perl has special debugging hooks at compile-time and run-time used
16 to create debugging environments. These hooks are not to be confused
17 with the I<perl -Dxxx> command described in L<perlrun>, which is
18 usable only if a special Perl is built per the instructions in the
19 F<INSTALL> podpage in the Perl source tree.
21 For example, whenever you call Perl's built-in C<caller> function
22 from the package C<DB>, the arguments that the corresponding stack
23 frame was called with are copied to the C<@DB::args> array. These
24 mechanisms are enabled by calling Perl with the B<-d> switch.
25 Specifically, the following additional features are enabled
32 Perl inserts the contents of C<$ENV{PERL5DB}> (or C<BEGIN {require
33 'perl5db.pl'}> if not present) before the first line of your program.
37 Each array C<@{"_<$filename"}> holds the lines of $filename for a
38 file compiled by Perl. The same is also true for C<eval>ed strings
39 that contain subroutines, or which are currently being executed.
40 The $filename for C<eval>ed strings looks like C<(eval 34)>.
42 Values in this array are magical in numeric context: they compare
43 equal to zero only if the line is not breakable.
47 Each hash C<%{"_<$filename"}> contains breakpoints and actions keyed
48 by line number. Individual entries (as opposed to the whole hash)
49 are settable. Perl only cares about Boolean true here, although
50 the values used by F<perl5db.pl> have the form
51 C<"$break_condition\0$action">.
53 The same holds for evaluated strings that contain subroutines, or
54 which are currently being executed. The $filename for C<eval>ed strings
55 looks like C<(eval 34)>.
59 Each scalar C<${"_<$filename"}> contains C<"_<$filename">. This is
60 also the case for evaluated strings that contain subroutines, or
61 which are currently being executed. The $filename for C<eval>ed
62 strings looks like C<(eval 34)>.
66 After each C<require>d file is compiled, but before it is executed,
67 C<DB::postponed(*{"_<$filename"})> is called if the subroutine
68 C<DB::postponed> exists. Here, the $filename is the expanded name of
69 the C<require>d file, as found in the values of %INC.
73 After each subroutine C<subname> is compiled, the existence of
74 C<$DB::postponed{subname}> is checked. If this key exists,
75 C<DB::postponed(subname)> is called if the C<DB::postponed> subroutine
80 A hash C<%DB::sub> is maintained, whose keys are subroutine names
81 and whose values have the form C<filename:startline-endline>.
82 C<filename> has the form C<(eval 34)> for subroutines defined inside
87 When the execution of your program reaches a point that can hold a
88 breakpoint, the C<DB::DB()> subroutine is called if any of the variables
89 C<$DB::trace>, C<$DB::single>, or C<$DB::signal> is true. These variables
90 are not C<local>izable. This feature is disabled when executing
91 inside C<DB::DB()>, including functions called from it
92 unless C<< $^D & (1<<30) >> is true.
96 When execution of the program reaches a subroutine call, a call to
97 C<&DB::sub>(I<args>) is made instead, with C<$DB::sub> holding the
98 name of the called subroutine. (This doesn't happen if the subroutine
99 was compiled in the C<DB> package.)
103 Note that if C<&DB::sub> needs external data for it to work, no
104 subroutine call is possible without it. As an example, the standard
105 debugger's C<&DB::sub> depends on the C<$DB::deep> variable
106 (it defines how many levels of recursion deep into the debugger you can go
107 before a mandatory break). If C<$DB::deep> is not defined, subroutine
108 calls are not possible, even though C<&DB::sub> exists.
110 =head2 Writing Your Own Debugger
112 =head3 Environment Variables
114 The C<PERL5DB> environment variable can be used to define a debugger.
115 For example, the minimal "working" debugger (it actually doesn't do anything)
116 consists of one line:
120 It can easily be defined like this:
122 $ PERL5DB="sub DB::DB {}" perl -d your-script
124 Another brief debugger, slightly more useful, can be created
127 sub DB::DB {print ++$i; scalar <STDIN>}
129 This debugger prints a number which increments for each statement
130 encountered and waits for you to hit a newline before continuing
131 to the next statement.
133 The following debugger is actually useful:
138 sub sub {print ++$i, " $sub\n"; &$sub}
141 It prints the sequence number of each subroutine call and the name of the
142 called subroutine. Note that C<&DB::sub> is being compiled into the
143 package C<DB> through the use of the C<package> directive.
145 When it starts, the debugger reads your rc file (F<./.perldb> or
146 F<~/.perldb> under Unix), which can set important options.
147 (A subroutine (C<&afterinit>) can be defined here as well; it is executed
148 after the debugger completes its own initialization.)
150 After the rc file is read, the debugger reads the PERLDB_OPTS
151 environment variable and uses it to set debugger options. The
152 contents of this variable are treated as if they were the argument
153 of an C<o ...> debugger command (q.v. in L<perldebug/"Configurable Options">).
155 =head3 Debugger Internal Variables
157 In addition to the file and subroutine-related variables mentioned above,
158 the debugger also maintains various magical internal variables.
164 C<@DB::dbline> is an alias for C<@{"::_<current_file"}>, which
165 holds the lines of the currently-selected file (compiled by Perl), either
166 explicitly chosen with the debugger's C<f> command, or implicitly by flow
169 Values in this array are magical in numeric context: they compare
170 equal to zero only if the line is not breakable.
174 C<%DB::dbline> is an alias for C<%{"::_<current_file"}>, which
175 contains breakpoints and actions keyed by line number in
176 the currently-selected file, either explicitly chosen with the
177 debugger's C<f> command, or implicitly by flow of execution.
179 As previously noted, individual entries (as opposed to the whole hash)
180 are settable. Perl only cares about Boolean true here, although
181 the values used by F<perl5db.pl> have the form
182 C<"$break_condition\0$action">.
186 =head3 Debugger Customization Functions
188 Some functions are provided to simplify customization.
194 See L<perldebug/"Configurable Options"> for a description of options parsed by
195 C<DB::parse_options(string)>.
199 C<DB::dump_trace(skip[,count])> skips the specified number of frames
200 and returns a list containing information about the calling frames (all
201 of them, if C<count> is missing). Each entry is reference to a hash
202 with keys C<context> (either C<.>, C<$>, or C<@>), C<sub> (subroutine
203 name, or info about C<eval>), C<args> (C<undef> or a reference to
204 an array), C<file>, and C<line>.
208 C<DB::print_trace(FH, skip[, count[, short]])> prints
209 formatted info about caller frames. The last two functions may be
210 convenient as arguments to C<< < >>, C<< << >> commands.
214 Note that any variables and functions that are not documented in
215 this manpages (or in L<perldebug>) are considered for internal
216 use only, and as such are subject to change without notice.
218 =head1 Frame Listing Output Examples
220 The C<frame> option can be used to control the output of frame
221 information. For example, contrast this expression trace:
224 Stack dump during die enabled outside of evals.
226 Loading DB routines from perl5db.pl patch level 0.94
227 Emacs support available.
229 Enter h or 'h h' for help.
236 DB<3> t print foo() * bar()
237 main::((eval 172):3): print foo() + bar();
238 main::foo((eval 168):2):
239 main::bar((eval 170):2):
242 with this one, once the C<o>ption C<frame=2> has been set:
246 DB<5> t print foo() * bar()
256 By way of demonstration, we present below a laborious listing
257 resulting from setting your C<PERLDB_OPTS> environment variable to
258 the value C<f=n N>, and running I<perl -d -V> from the command line.
259 Examples using various values of C<n> are shown to give you a feel
260 for the difference between settings. Long though it may be, this
261 is not a complete listing, but only excerpts.
268 entering Config::BEGIN
269 Package lib/Exporter.pm.
271 Package lib/Config.pm.
272 entering Config::TIEHASH
273 entering Exporter::import
274 entering Exporter::export
275 entering Config::myconfig
276 entering Config::FETCH
277 entering Config::FETCH
278 entering Config::FETCH
279 entering Config::FETCH
284 entering Config::BEGIN
285 Package lib/Exporter.pm.
288 Package lib/Config.pm.
289 entering Config::TIEHASH
290 exited Config::TIEHASH
291 entering Exporter::import
292 entering Exporter::export
293 exited Exporter::export
294 exited Exporter::import
296 entering Config::myconfig
297 entering Config::FETCH
299 entering Config::FETCH
301 entering Config::FETCH
305 in $=main::BEGIN() from /dev/null:0
306 in $=Config::BEGIN() from lib/Config.pm:2
307 Package lib/Exporter.pm.
309 Package lib/Config.pm.
310 in $=Config::TIEHASH('Config') from lib/Config.pm:644
311 in $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
312 in $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from li
313 in @=Config::myconfig() from /dev/null:0
314 in $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574
315 in $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574
316 in $=Config::FETCH(ref(Config), 'PERL_VERSION') from lib/Config.pm:574
317 in $=Config::FETCH(ref(Config), 'PERL_SUBVERSION') from lib/Config.pm:574
318 in $=Config::FETCH(ref(Config), 'osname') from lib/Config.pm:574
319 in $=Config::FETCH(ref(Config), 'osvers') from lib/Config.pm:574
323 in $=main::BEGIN() from /dev/null:0
324 in $=Config::BEGIN() from lib/Config.pm:2
325 Package lib/Exporter.pm.
327 out $=Config::BEGIN() from lib/Config.pm:0
328 Package lib/Config.pm.
329 in $=Config::TIEHASH('Config') from lib/Config.pm:644
330 out $=Config::TIEHASH('Config') from lib/Config.pm:644
331 in $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
332 in $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/
333 out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/
334 out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
335 out $=main::BEGIN() from /dev/null:0
336 in @=Config::myconfig() from /dev/null:0
337 in $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574
338 out $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574
339 in $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574
340 out $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574
341 in $=Config::FETCH(ref(Config), 'PERL_VERSION') from lib/Config.pm:574
342 out $=Config::FETCH(ref(Config), 'PERL_VERSION') from lib/Config.pm:574
343 in $=Config::FETCH(ref(Config), 'PERL_SUBVERSION') from lib/Config.pm:574
347 in $=main::BEGIN() from /dev/null:0
348 in $=Config::BEGIN() from lib/Config.pm:2
349 Package lib/Exporter.pm.
351 out $=Config::BEGIN() from lib/Config.pm:0
352 Package lib/Config.pm.
353 in $=Config::TIEHASH('Config') from lib/Config.pm:644
354 out $=Config::TIEHASH('Config') from lib/Config.pm:644
355 in $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
356 in $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/E
357 out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/E
358 out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
359 out $=main::BEGIN() from /dev/null:0
360 in @=Config::myconfig() from /dev/null:0
361 in $=Config::FETCH('Config=HASH(0x1aa444)', 'package') from lib/Config.pm:574
362 out $=Config::FETCH('Config=HASH(0x1aa444)', 'package') from lib/Config.pm:574
363 in $=Config::FETCH('Config=HASH(0x1aa444)', 'baserev') from lib/Config.pm:574
364 out $=Config::FETCH('Config=HASH(0x1aa444)', 'baserev') from lib/Config.pm:574
368 in $=CODE(0x15eca4)() from /dev/null:0
369 in $=CODE(0x182528)() from lib/Config.pm:2
370 Package lib/Exporter.pm.
371 out $=CODE(0x182528)() from lib/Config.pm:0
372 scalar context return from CODE(0x182528): undef
373 Package lib/Config.pm.
374 in $=Config::TIEHASH('Config') from lib/Config.pm:628
375 out $=Config::TIEHASH('Config') from lib/Config.pm:628
376 scalar context return from Config::TIEHASH: empty hash
377 in $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
378 in $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/Exporter.pm:171
379 out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/Exporter.pm:171
380 scalar context return from Exporter::export: ''
381 out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
382 scalar context return from Exporter::import: ''
386 In all cases shown above, the line indentation shows the call tree.
387 If bit 2 of C<frame> is set, a line is printed on exit from a
388 subroutine as well. If bit 4 is set, the arguments are printed
389 along with the caller info. If bit 8 is set, the arguments are
390 printed even if they are tied or references. If bit 16 is set, the
391 return value is printed, too.
393 When a package is compiled, a line like this
397 is printed with proper indentation.
399 =head1 Debugging Regular Expressions
401 There are two ways to enable debugging output for regular expressions.
403 If your perl is compiled with C<-DDEBUGGING>, you may use the
404 B<-Dr> flag on the command line.
406 Otherwise, one can C<use re 'debug'>, which has effects at
407 compile time and run time. Since Perl 5.9.5, this pragma is lexically
410 =head2 Compile-time Output
412 The debugging output at compile time looks like this:
414 Compiling REx '[bc]d(ef*g)+h[ij]k$'
415 size 45 Got 364 bytes for offset annotations.
421 14: CURLYX[0] {1,32767}(28)
435 anchored 'de' at 1 floating 'gh' at 3..2147483647 (checking floating)
436 stclass 'ANYOF[bc]' minlen 7
438 1[4] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 5[1]
439 0[0] 12[1] 0[0] 6[1] 0[0] 7[1] 0[0] 9[1] 8[1] 0[0] 10[1] 0[0]
440 11[1] 0[0] 12[0] 12[0] 13[1] 0[0] 14[4] 0[0] 0[0] 0[0] 0[0]
441 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 18[1] 0[0] 19[1] 20[0]
442 Omitting $` $& $' support.
444 The first line shows the pre-compiled form of the regex. The second
445 shows the size of the compiled form (in arbitrary units, usually
446 4-byte words) and the total number of bytes allocated for the
447 offset/length table, usually 4+C<size>*8. The next line shows the
448 label I<id> of the first node that does a match.
452 anchored 'de' at 1 floating 'gh' at 3..2147483647 (checking floating)
453 stclass 'ANYOF[bc]' minlen 7
455 line (split into two lines above) contains optimizer
456 information. In the example shown, the optimizer found that the match
457 should contain a substring C<de> at offset 1, plus substring C<gh>
458 at some offset between 3 and infinity. Moreover, when checking for
459 these substrings (to abandon impossible matches quickly), Perl will check
460 for the substring C<gh> before checking for the substring C<de>. The
461 optimizer may also use the knowledge that the match starts (at the
462 C<first> I<id>) with a character class, and no string
463 shorter than 7 characters can possibly match.
465 The fields of interest which may appear in this line are
469 =item C<anchored> I<STRING> C<at> I<POS>
471 =item C<floating> I<STRING> C<at> I<POS1..POS2>
475 =item C<matching floating/anchored>
477 Which substring to check first.
481 The minimal length of the match.
483 =item C<stclass> I<TYPE>
485 Type of first matching node.
489 Don't scan for the found substrings.
493 Means that the optimizer information is all that the regular
494 expression contains, and thus one does not need to enter the regex engine at
499 Set if the pattern contains C<\G>.
503 Set if the pattern starts with a repeated char (as in C<x+y>).
507 Set if the pattern starts with C<.*>.
511 Set if the pattern contain eval-groups, such as C<(?{ code })> and
514 =item C<anchored(TYPE)>
516 If the pattern may match only at a handful of places, with C<TYPE>
517 being C<BOL>, C<MBOL>, or C<GPOS>. See the table below.
521 If a substring is known to match at end-of-line only, it may be
522 followed by C<$>, as in C<floating 'k'$>.
524 The optimizer-specific information is used to avoid entering (a slow) regex
525 engine on strings that will not definitely match. If the C<isall> flag
526 is set, a call to the regex engine may be avoided even when the optimizer
527 found an appropriate place for the match.
529 Above the optimizer section is the list of I<nodes> of the compiled
530 form of the regex. Each line has format
532 C< >I<id>: I<TYPE> I<OPTIONAL-INFO> (I<next-id>)
534 =head2 Types of Nodes
536 Here are the possible types, with short descriptions:
539 This table is generated by regen/regcomp.pl. Any changes made here
542 =for regcomp.pl begin
544 # TYPE arg-description [num-args] [longjump-len] DESCRIPTION
548 END no End of program.
549 SUCCEED no Return from a subroutine, basically.
553 BOL no Match "" at beginning of line.
554 MBOL no Same, assuming multiline.
555 SBOL no Same, assuming singleline.
556 EOS no Match "" at end of string.
557 EOL no Match "" at end of line.
558 MEOL no Same, assuming multiline.
559 SEOL no Same, assuming singleline.
560 BOUND no Match "" at any word boundary using
561 native charset semantics for non-utf8
562 BOUNDL no Match "" at any locale word boundary
563 BOUNDU no Match "" at any word boundary using
565 BOUNDA no Match "" at any word boundary using ASCII
567 NBOUND no Match "" at any word non-boundary using
568 native charset semantics for non-utf8
569 NBOUNDL no Match "" at any locale word non-boundary
570 NBOUNDU no Match "" at any word non-boundary using
572 NBOUNDA no Match "" at any word non-boundary using
574 GPOS no Matches where last m//g left off.
576 # [Special] alternatives:
578 REG_ANY no Match any one character (except newline).
579 SANY no Match any one character.
580 CANY no Match any one byte.
581 ANYOF sv Match character in (or not in) this
582 class, single char match only
583 ANYOF_WARN_SUPER sv Match character in (or not in) this
584 class, warn (if enabled) upon matching a
585 char above Unicode max;
586 ANYOF_SYNTHETIC sv Synthetic start class
588 POSIXD none Some [[:class:]] under /d; the FLAGS
589 field gives which one
590 POSIXL none Some [[:class:]] under /l; the FLAGS
591 field gives which one
592 POSIXU none Some [[:class:]] under /u; the FLAGS
593 field gives which one
594 POSIXA none Some [[:class:]] under /a; the FLAGS
595 field gives which one
596 NPOSIXD none complement of POSIXD, [[:^class:]]
597 NPOSIXL none complement of POSIXL, [[:^class:]]
598 NPOSIXU none complement of POSIXU, [[:^class:]]
599 NPOSIXA none complement of POSIXA, [[:^class:]]
601 CLUMP no Match any extended grapheme cluster
606 # BRANCH The set of branches constituting a single choice are
607 # hooked together with their "next" pointers, since
608 # precedence prevents anything being concatenated to
609 # any individual branch. The "next" pointer of the last
610 # BRANCH in a choice points to the thing following the
611 # whole choice. This is also where the final "next"
612 # pointer of each individual branch points; each branch
613 # starts with the operand node of a BRANCH node.
615 BRANCH node Match this alternative, or the next...
619 # BACK Normal "next" pointers all implicitly point forward;
620 # BACK exists to make loop structures possible.
622 BACK no Match "", "next" ptr points backward.
626 EXACT str Match this string (preceded by length).
627 EXACTF str Match this non-UTF-8 string (not
628 guaranteed to be folded) using /id rules
630 EXACTFL str Match this string (not guaranteed to be
631 folded) using /il rules (w/len).
632 EXACTFU str Match this string (folded iff in UTF-8,
633 length in folding doesn't change if not
634 in UTF-8) using /iu rules (w/len).
635 EXACTFA str Match this string (not guaranteed to be
636 folded) using /iaa rules (w/len).
637 EXACTFU_SS str Match this string (folded iff in UTF-8,
638 length in folding may change even if not
639 in UTF-8) using /iu rules (w/len).
640 EXACTFU_TRICKYFOLD str Match this folded UTF-8 string using /iu
645 NOTHING no Match empty string.
646 # A variant of above which delimits a group, thus stops optimizations
647 TAIL no Match empty string. Can jump here from
652 # STAR,PLUS '?', and complex '*' and '+', are implemented as
653 # circular BRANCH structures using BACK. Simple cases
654 # (one character per match) are implemented with STAR
655 # and PLUS for speed and to minimize recursive plunges.
657 STAR node Match this (simple) thing 0 or more
659 PLUS node Match this (simple) thing 1 or more
662 CURLY sv 2 Match this simple thing {n,m} times.
663 CURLYN no 2 Capture next-after-this simple thing
664 CURLYM no 2 Capture this medium-complex thing {n,m}
666 CURLYX sv 2 Match this complex thing {n,m} times.
668 # This terminator creates a loop structure for CURLYX
669 WHILEM no Do curly processing and see if rest
674 # OPEN,CLOSE,GROUPP ...are numbered at compile time.
675 OPEN num 1 Mark this point in input as start of #n.
676 CLOSE num 1 Analogous to OPEN.
678 REF num 1 Match some already matched string
679 REFF num 1 Match already matched string, folded
680 using native charset semantics for non-
682 REFFL num 1 Match already matched string, folded in
684 REFFU num 1 Match already matched string, folded
685 using unicode semantics for non-utf8
686 REFFA num 1 Match already matched string, folded
687 using unicode semantics for non-utf8, no
688 mixing ASCII, non-ASCII
690 # Named references. Code in regcomp.c assumes that these all are after
691 # the numbered references
692 NREF no-sv 1 Match some already matched string
693 NREFF no-sv 1 Match already matched string, folded
694 using native charset semantics for non-
696 NREFFL no-sv 1 Match already matched string, folded in
698 NREFFU num 1 Match already matched string, folded
699 using unicode semantics for non-utf8
700 NREFFA num 1 Match already matched string, folded
701 using unicode semantics for non-utf8, no
702 mixing ASCII, non-ASCII
704 IFMATCH off 1 2 Succeeds if the following matches.
705 UNLESSM off 1 2 Fails if the following matches.
706 SUSPEND off 1 1 "Independent" sub-RE.
707 IFTHEN off 1 1 Switch, should be preceded by switcher.
708 GROUPP num 1 Whether the group matched.
710 # Support for long RE
712 LONGJMP off 1 1 Jump far away.
713 BRANCHJ off 1 1 BRANCH with long offset.
717 EVAL evl 1 Execute some Perl code.
721 MINMOD no Next operator is not greedy.
722 LOGICAL no Next opcode should set the flag only.
724 # This is not used yet
725 RENUM off 1 1 Group with independently numbered parens.
729 # Behave the same as A|LIST|OF|WORDS would. The '..C' variants
730 # have inline charclass data (ascii only), the 'C' store it in the
733 TRIE trie 1 Match many EXACT(F[ALU]?)? at once.
735 TRIEC trie Same as TRIE, but with embedded charclass
738 AHOCORASICK trie 1 Aho Corasick stclass. flags==type
739 AHOCORASICKC trie Same as AHOCORASICK, but with embedded
740 charclass charclass data
743 GOSUB num/ofs 2L recurse to paren arg1 at (signed) ofs
745 GOSTART no recurse to start of pattern
747 # Special conditionals
748 NGROUPP no-sv 1 Whether the group matched.
749 INSUBP num 1 Whether we are in a specific recurse.
750 DEFINEP none 1 Never execute directly.
753 ENDLIKE none Used only for the type field of verbs
754 OPFAIL none Same as (?!)
755 ACCEPT parno 1 Accepts the current matched string.
757 # Verbs With Arguments
758 VERB no-sv 1 Used only for the type field of verbs
759 PRUNE no-sv 1 Pattern fails at this startpoint if no-
760 backtracking through this
761 MARKPOINT no-sv 1 Push the current location for rollback by
763 SKIP no-sv 1 On failure skip forward (to the mark)
765 COMMIT no-sv 1 Pattern fails outright if backtracking
767 CUTGROUP no-sv 1 On failure go to the next alternation in
770 # Control what to keep in $&.
771 KEEPS no $& begins here.
773 # New charclass like patterns
774 LNBREAK none generic newline pattern
778 # This is not really a node, but an optimized away piece of a "long"
779 # node. To simplify debugging output, we mark it as if it were a node
780 OPTIMIZED off Placeholder for dump.
782 # Special opcode with the property that no opcode in a compiled program
783 # will ever be of this type. Thus it can be used as a flag value that
784 # no other opcode has been seen. END is used similarly, in that an END
785 # node cant be optimized. So END implies "unoptimizable" and PSEUDO
786 # mean "not seen anything to optimize yet".
787 PSEUDO off Pseudo opcode for internal use.
791 =for unprinted-credits
792 Next section M-J. Dominus (mjd-perl-patch+@plover.com) 20010421
794 Following the optimizer information is a dump of the offset/length
795 table, here split across several lines:
798 1[4] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 5[1]
799 0[0] 12[1] 0[0] 6[1] 0[0] 7[1] 0[0] 9[1] 8[1] 0[0] 10[1] 0[0]
800 11[1] 0[0] 12[0] 12[0] 13[1] 0[0] 14[4] 0[0] 0[0] 0[0] 0[0]
801 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 18[1] 0[0] 19[1] 20[0]
803 The first line here indicates that the offset/length table contains 45
804 entries. Each entry is a pair of integers, denoted by C<offset[length]>.
805 Entries are numbered starting with 1, so entry #1 here is C<1[4]> and
806 entry #12 is C<5[1]>. C<1[4]> indicates that the node labeled C<1:>
807 (the C<1: ANYOF[bc]>) begins at character position 1 in the
808 pre-compiled form of the regex, and has a length of 4 characters.
809 C<5[1]> in position 12
810 indicates that the node labeled C<12:>
811 (the C<< 12: EXACT <d> >>) begins at character position 5 in the
812 pre-compiled form of the regex, and has a length of 1 character.
813 C<12[1]> in position 14
814 indicates that the node labeled C<14:>
815 (the C<< 14: CURLYX[0] {1,32767} >>) begins at character position 12 in the
816 pre-compiled form of the regex, and has a length of 1 character---that
817 is, it corresponds to the C<+> symbol in the precompiled regex.
819 C<0[0]> items indicate that there is no corresponding node.
821 =head2 Run-time Output
823 First of all, when doing a match, one may get no run-time output even
824 if debugging is enabled. This means that the regex engine was never
825 entered and that all of the job was therefore done by the optimizer.
827 If the regex engine was entered, the output may look like this:
829 Matching '[bc]d(ef*g)+h[ij]k$' against 'abcdefg__gh__'
830 Setting an EVAL scope, savestack=3
831 2 <ab> <cdefg__gh_> | 1: ANYOF
832 3 <abc> <defg__gh_> | 11: EXACT <d>
833 4 <abcd> <efg__gh_> | 13: CURLYX {1,32767}
834 4 <abcd> <efg__gh_> | 26: WHILEM
835 0 out of 1..32767 cc=effff31c
836 4 <abcd> <efg__gh_> | 15: OPEN1
837 4 <abcd> <efg__gh_> | 17: EXACT <e>
838 5 <abcde> <fg__gh_> | 19: STAR
839 EXACT <f> can match 1 times out of 32767...
840 Setting an EVAL scope, savestack=3
841 6 <bcdef> <g__gh__> | 22: EXACT <g>
842 7 <bcdefg> <__gh__> | 24: CLOSE1
843 7 <bcdefg> <__gh__> | 26: WHILEM
844 1 out of 1..32767 cc=effff31c
845 Setting an EVAL scope, savestack=12
846 7 <bcdefg> <__gh__> | 15: OPEN1
847 7 <bcdefg> <__gh__> | 17: EXACT <e>
848 restoring \1 to 4(4)..7
849 failed, try continuation...
850 7 <bcdefg> <__gh__> | 27: NOTHING
851 7 <bcdefg> <__gh__> | 28: EXACT <h>
855 The most significant information in the output is about the particular I<node>
856 of the compiled regex that is currently being tested against the target string.
857 The format of these lines is
859 C< >I<STRING-OFFSET> <I<PRE-STRING>> <I<POST-STRING>> |I<ID>: I<TYPE>
861 The I<TYPE> info is indented with respect to the backtracking level.
862 Other incidental information appears interspersed within.
864 =head1 Debugging Perl Memory Usage
866 Perl is a profligate wastrel when it comes to memory use. There
867 is a saying that to estimate memory usage of Perl, assume a reasonable
868 algorithm for memory allocation, multiply that estimate by 10, and
869 while you still may miss the mark, at least you won't be quite so
870 astonished. This is not absolutely true, but may provide a good
871 grasp of what happens.
873 Assume that an integer cannot take less than 20 bytes of memory, a
874 float cannot take less than 24 bytes, a string cannot take less
875 than 32 bytes (all these examples assume 32-bit architectures, the
876 result are quite a bit worse on 64-bit architectures). If a variable
877 is accessed in two of three different ways (which require an integer,
878 a float, or a string), the memory footprint may increase yet another
879 20 bytes. A sloppy malloc(3) implementation can inflate these
880 numbers dramatically.
882 On the opposite end of the scale, a declaration like
886 may take up to 500 bytes of memory, depending on which release of Perl
889 Anecdotal estimates of source-to-compiled code bloat suggest an
890 eightfold increase. This means that the compiled form of reasonable
891 (normally commented, properly indented etc.) code will take
892 about eight times more space in memory than the code took
895 The B<-DL> command-line switch is obsolete since circa Perl 5.6.0
896 (it was available only if Perl was built with C<-DDEBUGGING>).
897 The switch was used to track Perl's memory allocations and possible
898 memory leaks. These days the use of malloc debugging tools like
899 F<Purify> or F<valgrind> is suggested instead. See also
900 L<perlhacktips/PERL_MEM_LOG>.
902 One way to find out how much memory is being used by Perl data
903 structures is to install the Devel::Size module from CPAN: it gives
904 you the minimum number of bytes required to store a particular data
905 structure. Please be mindful of the difference between the size()
908 If Perl has been compiled using Perl's malloc you can analyze Perl
909 memory usage by setting $ENV{PERL_DEBUG_MSTATS}.
911 =head2 Using C<$ENV{PERL_DEBUG_MSTATS}>
913 If your perl is using Perl's malloc() and was compiled with the
914 necessary switches (this is the default), then it will print memory
915 usage statistics after compiling your code when C<< $ENV{PERL_DEBUG_MSTATS}
916 > 1 >>, and before termination of the program when C<<
917 $ENV{PERL_DEBUG_MSTATS} >= 1 >>. The report format is similar to
918 the following example:
920 $ PERL_DEBUG_MSTATS=2 perl -e "require Carp"
921 Memory allocation statistics after compilation: (buckets 4(4)..8188(8192)
922 14216 free: 130 117 28 7 9 0 2 2 1 0 0
924 60924 used: 125 137 161 55 7 8 6 16 2 0 1
926 Total sbrk(): 77824/21:119. Odd ends: pad+heads+chain+tail: 0+636+0+2048.
927 Memory allocation statistics after execution: (buckets 4(4)..8188(8192)
928 30888 free: 245 78 85 13 6 2 1 3 2 0 1
930 175816 used: 265 176 1112 111 26 22 11 27 2 1 1
932 Total sbrk(): 215040/47:145. Odd ends: pad+heads+chain+tail: 0+2192+0+6144.
934 It is possible to ask for such a statistic at arbitrary points in
935 your execution using the mstat() function out of the standard
938 Here is some explanation of that format:
942 =item C<buckets SMALLEST(APPROX)..GREATEST(APPROX)>
944 Perl's malloc() uses bucketed allocations. Every request is rounded
945 up to the closest bucket size available, and a bucket is taken from
946 the pool of buckets of that size.
948 The line above describes the limits of buckets currently in use.
949 Each bucket has two sizes: memory footprint and the maximal size
950 of user data that can fit into this bucket. Suppose in the above
951 example that the smallest bucket were size 4. The biggest bucket
952 would have usable size 8188, and the memory footprint would be 8192.
954 In a Perl built for debugging, some buckets may have negative usable
955 size. This means that these buckets cannot (and will not) be used.
956 For larger buckets, the memory footprint may be one page greater
957 than a power of 2. If so, the corresponding power of two is
958 printed in the C<APPROX> field above.
962 The 1 or 2 rows of numbers following that correspond to the number
963 of buckets of each size between C<SMALLEST> and C<GREATEST>. In
964 the first row, the sizes (memory footprints) of buckets are powers
965 of two--or possibly one page greater. In the second row, if present,
966 the memory footprints of the buckets are between the memory footprints
967 of two buckets "above".
969 For example, suppose under the previous example, the memory footprints
972 free: 8 16 32 64 128 256 512 1024 2048 4096 8192
975 With a non-C<DEBUGGING> perl, the buckets starting from C<128> have
976 a 4-byte overhead, and thus an 8192-long bucket may take up to
977 8188-byte allocations.
979 =item C<Total sbrk(): SBRKed/SBRKs:CONTINUOUS>
981 The first two fields give the total amount of memory perl sbrk(2)ed
982 (ess-broken? :-) and number of sbrk(2)s used. The third number is
983 what perl thinks about continuity of returned chunks. So long as
984 this number is positive, malloc() will assume that it is probable
985 that sbrk(2) will provide continuous memory.
987 Memory allocated by external libraries is not counted.
991 The amount of sbrk(2)ed memory needed to keep buckets aligned.
995 Although memory overhead of bigger buckets is kept inside the bucket, for
996 smaller buckets, it is kept in separate areas. This field gives the
997 total size of these areas.
1001 malloc() may want to subdivide a bigger bucket into smaller buckets.
1002 If only a part of the deceased bucket is left unsubdivided, the rest
1003 is kept as an element of a linked list. This field gives the total
1004 size of these chunks.
1008 To minimize the number of sbrk(2)s, malloc() asks for more memory. This
1009 field gives the size of the yet unused part, which is sbrk(2)ed, but