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:
538 # TYPE arg-description [num-args] [longjump-len] DESCRIPTION
541 END no End of program.
542 SUCCEED no Return from a subroutine, basically.
546 BOL no Match "" at beginning of line.
547 MBOL no Same, assuming multiline.
548 SBOL no Same, assuming singleline.
549 EOS no Match "" at end of string.
550 EOL no Match "" at end of line.
551 MEOL no Same, assuming multiline.
552 SEOL no Same, assuming singleline.
553 BOUND no Match "" at any word boundary using native charset
554 semantics for non-utf8
555 BOUNDL no Match "" at any locale word boundary
556 BOUNDU no Match "" at any word boundary using Unicode semantics
557 BOUNDA no Match "" at any word boundary using ASCII semantics
558 NBOUND no Match "" at any word non-boundary using native charset
559 semantics for non-utf8
560 NBOUNDL no Match "" at any locale word non-boundary
561 NBOUNDU no Match "" at any word non-boundary using Unicode semantics
562 NBOUNDA no Match "" at any word non-boundary using ASCII semantics
563 GPOS no Matches where last m//g left off.
565 # [Special] alternatives:
567 REG_ANY no Match any one character (except newline).
568 SANY no Match any one character.
569 CANY no Match any one byte.
570 ANYOF sv Match character in (or not in) this class, single char
572 ANYOFV sv Match character in (or not in) this class, can
574 ALNUM no Match any alphanumeric character using native charset
575 semantics for non-utf8
576 ALNUML no Match any alphanumeric char in locale
577 ALNUMU no Match any alphanumeric char using Unicode semantics
578 ALNUMA no Match [A-Za-z_0-9]
579 NALNUM no Match any non-alphanumeric character using native charset
580 semantics for non-utf8
581 NALNUML no Match any non-alphanumeric char in locale
582 NALNUMU no Match any non-alphanumeric char using Unicode semantics
583 NALNUMA no Match [^A-Za-z_0-9]
584 SPACE no Match any whitespace character using native charset
585 semantics for non-utf8
586 SPACEL no Match any whitespace char in locale
587 SPACEU no Match any whitespace char using Unicode semantics
588 SPACEA no Match [ \t\n\f\r]
589 NSPACE no Match any non-whitespace character using native charset
590 semantics for non-utf8
591 NSPACEL no Match any non-whitespace char in locale
592 NSPACEU no Match any non-whitespace char using Unicode semantics
593 NSPACEA no Match [^ \t\n\f\r]
594 DIGIT no Match any numeric character using native charset semantics
596 DIGITL no Match any numeric character in locale
597 DIGITA no Match [0-9]
598 NDIGIT no Match any non-numeric character using native charset
599 i semantics for non-utf8
600 NDIGITL no Match any non-numeric character in locale
601 NDIGITA no Match [^0-9]
602 CLUMP no Match any extended grapheme cluster sequence
606 # BRANCH The set of branches constituting a single choice are hooked
607 # together with their "next" pointers, since precedence prevents
608 # anything being concatenated to any individual branch. The
609 # "next" pointer of the last BRANCH in a choice points to the
610 # thing following the whole choice. This is also where the
611 # final "next" pointer of each individual branch points; each
612 # branch starts with the operand node of a BRANCH node.
614 BRANCH node Match this alternative, or the next...
618 # BACK Normal "next" pointers all implicitly point forward; BACK
619 # exists to make loop structures possible.
621 BACK no Match "", "next" ptr points backward.
625 EXACT str Match this string (preceded by length).
626 EXACTF str Match this string, folded, native charset semantics for
627 non-utf8 (prec. by length).
628 EXACTFL str Match this string, folded in locale (w/len).
629 EXACTFU str Match this string, folded, Unicode semantics for non-utf8
631 EXACTFA str Match this string, folded, Unicode semantics for non-utf8,
632 but no ASCII-range character matches outside ASCII (prec.
637 NOTHING no Match empty string.
638 # A variant of above which delimits a group, thus stops optimizations
639 TAIL no Match empty string. Can jump here from outside.
643 # STAR,PLUS '?', and complex '*' and '+', are implemented as circular
644 # BRANCH structures using BACK. Simple cases (one character
645 # per match) are implemented with STAR and PLUS for speed
646 # and to minimize recursive plunges.
648 STAR node Match this (simple) thing 0 or more times.
649 PLUS node Match this (simple) thing 1 or more times.
651 CURLY sv 2 Match this simple thing {n,m} times.
652 CURLYN no 2 Capture next-after-this simple thing
653 CURLYM no 2 Capture this medium-complex thing {n,m} times.
654 CURLYX sv 2 Match this complex thing {n,m} times.
656 # This terminator creates a loop structure for CURLYX
657 WHILEM no Do curly processing and see if rest matches.
661 # OPEN,CLOSE,GROUPP ...are numbered at compile time.
662 OPEN num 1 Mark this point in input as start of #n.
663 CLOSE num 1 Analogous to OPEN.
665 REF num 1 Match some already matched string
666 REFF num 1 Match already matched string, folded using native charset
667 semantics for non-utf8
668 REFFL num 1 Match already matched string, folded in loc.
669 REFFU num 1 Match already matched string, folded using unicode
670 semantics for non-utf8
671 REFFA num 1 Match already matched string, folded using unicode
672 semantics for non-utf8, no mixing ASCII, non-ASCII
674 # Named references. Code in regcomp.c assumes that these all are after the
675 # numbered references
676 NREF no-sv 1 Match some already matched string
677 NREFF no-sv 1 Match already matched string, folded using native charset
678 semantics for non-utf8
679 NREFFL no-sv 1 Match already matched string, folded in loc.
680 NREFFU num 1 Match already matched string, folded using unicode
681 semantics for non-utf8
682 NREFFA num 1 Match already matched string, folded using unicode
683 semantics for non-utf8, no mixing ASCII, non-ASCII
685 IFMATCH off 1 2 Succeeds if the following matches.
686 UNLESSM off 1 2 Fails if the following matches.
687 SUSPEND off 1 1 "Independent" sub-RE.
688 IFTHEN off 1 1 Switch, should be preceded by switcher.
689 GROUPP num 1 Whether the group matched.
691 # Support for long RE
693 LONGJMP off 1 1 Jump far away.
694 BRANCHJ off 1 1 BRANCH with long offset.
698 EVAL evl 1 Execute some Perl code.
702 MINMOD no Next operator is not greedy.
703 LOGICAL no Next opcode should set the flag only.
705 # This is not used yet
706 RENUM off 1 1 Group with independently numbered parens.
710 # Behave the same as A|LIST|OF|WORDS would. The '..C' variants have
711 # inline charclass data (ascii only), the 'C' store it in the structure.
712 # NOTE: the relative order of the TRIE-like regops is significant
714 TRIE trie 1 Match many EXACT(F[ALU]?)? at once. flags==type
715 TRIEC charclass Same as TRIE, but with embedded charclass data
717 # For start classes, contains an added fail table.
718 AHOCORASICK trie 1 Aho Corasick stclass. flags==type
719 AHOCORASICKC charclass Same as AHOCORASICK, but with embedded charclass data
722 GOSUB num/ofs 2L recurse to paren arg1 at (signed) ofs arg2
723 GOSTART no recurse to start of pattern
725 # Special conditionals
726 NGROUPP no-sv 1 Whether the group matched.
727 INSUBP num 1 Whether we are in a specific recurse.
728 DEFINEP none 1 Never execute directly.
731 ENDLIKE none Used only for the type field of verbs
732 OPFAIL none Same as (?!)
733 ACCEPT parno 1 Accepts the current matched string.
736 # Verbs With Arguments
737 VERB no-sv 1 Used only for the type field of verbs
738 PRUNE no-sv 1 Pattern fails at this startpoint if no-backtracking through this
739 MARKPOINT no-sv 1 Push the current location for rollback by cut.
740 SKIP no-sv 1 On failure skip forward (to the mark) before retrying
741 COMMIT no-sv 1 Pattern fails outright if backtracking through this
742 CUTGROUP no-sv 1 On failure go to the next alternation in the group
744 # Control what to keep in $&.
745 KEEPS no $& begins here.
747 # New charclass like patterns
748 LNBREAK none generic newline pattern
749 VERTWS none vertical whitespace (Perl 6)
750 NVERTWS none not vertical whitespace (Perl 6)
751 HORIZWS none horizontal whitespace (Perl 6)
752 NHORIZWS none not horizontal whitespace (Perl 6)
754 FOLDCHAR codepoint 1 codepoint with tricky case folding properties.
758 # This is not really a node, but an optimized away piece of a "long" node.
759 # To simplify debugging output, we mark it as if it were a node
760 OPTIMIZED off Placeholder for dump.
762 # Special opcode with the property that no opcode in a compiled program
763 # will ever be of this type. Thus it can be used as a flag value that
764 # no other opcode has been seen. END is used similarly, in that an END
765 # node cant be optimized. So END implies "unoptimizable" and PSEUDO mean
766 # "not seen anything to optimize yet".
767 PSEUDO off Pseudo opcode for internal use.
769 =for unprinted-credits
770 Next section M-J. Dominus (mjd-perl-patch+@plover.com) 20010421
772 Following the optimizer information is a dump of the offset/length
773 table, here split across several lines:
776 1[4] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 5[1]
777 0[0] 12[1] 0[0] 6[1] 0[0] 7[1] 0[0] 9[1] 8[1] 0[0] 10[1] 0[0]
778 11[1] 0[0] 12[0] 12[0] 13[1] 0[0] 14[4] 0[0] 0[0] 0[0] 0[0]
779 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 18[1] 0[0] 19[1] 20[0]
781 The first line here indicates that the offset/length table contains 45
782 entries. Each entry is a pair of integers, denoted by C<offset[length]>.
783 Entries are numbered starting with 1, so entry #1 here is C<1[4]> and
784 entry #12 is C<5[1]>. C<1[4]> indicates that the node labeled C<1:>
785 (the C<1: ANYOF[bc]>) begins at character position 1 in the
786 pre-compiled form of the regex, and has a length of 4 characters.
787 C<5[1]> in position 12
788 indicates that the node labeled C<12:>
789 (the C<< 12: EXACT <d> >>) begins at character position 5 in the
790 pre-compiled form of the regex, and has a length of 1 character.
791 C<12[1]> in position 14
792 indicates that the node labeled C<14:>
793 (the C<< 14: CURLYX[0] {1,32767} >>) begins at character position 12 in the
794 pre-compiled form of the regex, and has a length of 1 character---that
795 is, it corresponds to the C<+> symbol in the precompiled regex.
797 C<0[0]> items indicate that there is no corresponding node.
799 =head2 Run-time Output
801 First of all, when doing a match, one may get no run-time output even
802 if debugging is enabled. This means that the regex engine was never
803 entered and that all of the job was therefore done by the optimizer.
805 If the regex engine was entered, the output may look like this:
807 Matching '[bc]d(ef*g)+h[ij]k$' against 'abcdefg__gh__'
808 Setting an EVAL scope, savestack=3
809 2 <ab> <cdefg__gh_> | 1: ANYOF
810 3 <abc> <defg__gh_> | 11: EXACT <d>
811 4 <abcd> <efg__gh_> | 13: CURLYX {1,32767}
812 4 <abcd> <efg__gh_> | 26: WHILEM
813 0 out of 1..32767 cc=effff31c
814 4 <abcd> <efg__gh_> | 15: OPEN1
815 4 <abcd> <efg__gh_> | 17: EXACT <e>
816 5 <abcde> <fg__gh_> | 19: STAR
817 EXACT <f> can match 1 times out of 32767...
818 Setting an EVAL scope, savestack=3
819 6 <bcdef> <g__gh__> | 22: EXACT <g>
820 7 <bcdefg> <__gh__> | 24: CLOSE1
821 7 <bcdefg> <__gh__> | 26: WHILEM
822 1 out of 1..32767 cc=effff31c
823 Setting an EVAL scope, savestack=12
824 7 <bcdefg> <__gh__> | 15: OPEN1
825 7 <bcdefg> <__gh__> | 17: EXACT <e>
826 restoring \1 to 4(4)..7
827 failed, try continuation...
828 7 <bcdefg> <__gh__> | 27: NOTHING
829 7 <bcdefg> <__gh__> | 28: EXACT <h>
833 The most significant information in the output is about the particular I<node>
834 of the compiled regex that is currently being tested against the target string.
835 The format of these lines is
837 C< >I<STRING-OFFSET> <I<PRE-STRING>> <I<POST-STRING>> |I<ID>: I<TYPE>
839 The I<TYPE> info is indented with respect to the backtracking level.
840 Other incidental information appears interspersed within.
842 =head1 Debugging Perl Memory Usage
844 Perl is a profligate wastrel when it comes to memory use. There
845 is a saying that to estimate memory usage of Perl, assume a reasonable
846 algorithm for memory allocation, multiply that estimate by 10, and
847 while you still may miss the mark, at least you won't be quite so
848 astonished. This is not absolutely true, but may provide a good
849 grasp of what happens.
851 Assume that an integer cannot take less than 20 bytes of memory, a
852 float cannot take less than 24 bytes, a string cannot take less
853 than 32 bytes (all these examples assume 32-bit architectures, the
854 result are quite a bit worse on 64-bit architectures). If a variable
855 is accessed in two of three different ways (which require an integer,
856 a float, or a string), the memory footprint may increase yet another
857 20 bytes. A sloppy malloc(3) implementation can inflate these
858 numbers dramatically.
860 On the opposite end of the scale, a declaration like
864 may take up to 500 bytes of memory, depending on which release of Perl
867 Anecdotal estimates of source-to-compiled code bloat suggest an
868 eightfold increase. This means that the compiled form of reasonable
869 (normally commented, properly indented etc.) code will take
870 about eight times more space in memory than the code took
873 The B<-DL> command-line switch is obsolete since circa Perl 5.6.0
874 (it was available only if Perl was built with C<-DDEBUGGING>).
875 The switch was used to track Perl's memory allocations and possible
876 memory leaks. These days the use of malloc debugging tools like
877 F<Purify> or F<valgrind> is suggested instead. See also
878 L<perlhacktips/PERL_MEM_LOG>.
880 One way to find out how much memory is being used by Perl data
881 structures is to install the Devel::Size module from CPAN: it gives
882 you the minimum number of bytes required to store a particular data
883 structure. Please be mindful of the difference between the size()
886 If Perl has been compiled using Perl's malloc you can analyze Perl
887 memory usage by setting $ENV{PERL_DEBUG_MSTATS}.
889 =head2 Using C<$ENV{PERL_DEBUG_MSTATS}>
891 If your perl is using Perl's malloc() and was compiled with the
892 necessary switches (this is the default), then it will print memory
893 usage statistics after compiling your code when C<< $ENV{PERL_DEBUG_MSTATS}
894 > 1 >>, and before termination of the program when C<<
895 $ENV{PERL_DEBUG_MSTATS} >= 1 >>. The report format is similar to
896 the following example:
898 $ PERL_DEBUG_MSTATS=2 perl -e "require Carp"
899 Memory allocation statistics after compilation: (buckets 4(4)..8188(8192)
900 14216 free: 130 117 28 7 9 0 2 2 1 0 0
902 60924 used: 125 137 161 55 7 8 6 16 2 0 1
904 Total sbrk(): 77824/21:119. Odd ends: pad+heads+chain+tail: 0+636+0+2048.
905 Memory allocation statistics after execution: (buckets 4(4)..8188(8192)
906 30888 free: 245 78 85 13 6 2 1 3 2 0 1
908 175816 used: 265 176 1112 111 26 22 11 27 2 1 1
910 Total sbrk(): 215040/47:145. Odd ends: pad+heads+chain+tail: 0+2192+0+6144.
912 It is possible to ask for such a statistic at arbitrary points in
913 your execution using the mstat() function out of the standard
916 Here is some explanation of that format:
920 =item C<buckets SMALLEST(APPROX)..GREATEST(APPROX)>
922 Perl's malloc() uses bucketed allocations. Every request is rounded
923 up to the closest bucket size available, and a bucket is taken from
924 the pool of buckets of that size.
926 The line above describes the limits of buckets currently in use.
927 Each bucket has two sizes: memory footprint and the maximal size
928 of user data that can fit into this bucket. Suppose in the above
929 example that the smallest bucket were size 4. The biggest bucket
930 would have usable size 8188, and the memory footprint would be 8192.
932 In a Perl built for debugging, some buckets may have negative usable
933 size. This means that these buckets cannot (and will not) be used.
934 For larger buckets, the memory footprint may be one page greater
935 than a power of 2. If so, the corresponding power of two is
936 printed in the C<APPROX> field above.
940 The 1 or 2 rows of numbers following that correspond to the number
941 of buckets of each size between C<SMALLEST> and C<GREATEST>. In
942 the first row, the sizes (memory footprints) of buckets are powers
943 of two--or possibly one page greater. In the second row, if present,
944 the memory footprints of the buckets are between the memory footprints
945 of two buckets "above".
947 For example, suppose under the previous example, the memory footprints
950 free: 8 16 32 64 128 256 512 1024 2048 4096 8192
953 With a non-C<DEBUGGING> perl, the buckets starting from C<128> have
954 a 4-byte overhead, and thus an 8192-long bucket may take up to
955 8188-byte allocations.
957 =item C<Total sbrk(): SBRKed/SBRKs:CONTINUOUS>
959 The first two fields give the total amount of memory perl sbrk(2)ed
960 (ess-broken? :-) and number of sbrk(2)s used. The third number is
961 what perl thinks about continuity of returned chunks. So long as
962 this number is positive, malloc() will assume that it is probable
963 that sbrk(2) will provide continuous memory.
965 Memory allocated by external libraries is not counted.
969 The amount of sbrk(2)ed memory needed to keep buckets aligned.
973 Although memory overhead of bigger buckets is kept inside the bucket, for
974 smaller buckets, it is kept in separate areas. This field gives the
975 total size of these areas.
979 malloc() may want to subdivide a bigger bucket into smaller buckets.
980 If only a part of the deceased bucket is left unsubdivided, the rest
981 is kept as an element of a linked list. This field gives the total
982 size of these chunks.
986 To minimize the number of sbrk(2)s, malloc() asks for more memory. This
987 field gives the size of the yet unused part, which is sbrk(2)ed, but