File: perldebguts.html

package info (click to toggle)
perl-doc-html 5.26.0-4
  • links: PTS, VCS
  • area: main
  • in suites: sid
  • size: 39,400 kB
  • sloc: xml: 36; makefile: 7
file content (1018 lines) | stat: -rw-r--r-- 137,661 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
  <title>perldebguts - perldoc.perl.org</title>
  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
  <meta http-equiv="Content-Language" content="en-gb">
  <link rel="search" type="application/opensearchdescription+xml" title="Search perldoc.perl.org" href="/static/search.xml"/>
  <link href="static/css-20100830.css" rel="stylesheet" rev="stylesheet" type="text/css" media="screen">
  <link href="static/exploreperl.css" rel="stylesheet" rev="stylesheet" type="text/css">
</head>

<body onLoad="perldoc.startup();" onPageShow="if (event.persisted) perldoc.startup();">
    <div id="page">
      
      <div id="header">
	<div id="homepage_link">
	  <a href="index.html"></a>
	</div>
	<div id="strapline">
	  Perl Programming Documentation
	</div>
	<div id="download_link" class="download">
	  <a href="http://www.perl.org/get.html">Download Perl</a>
	</div>
	<div id="explore_link" class="download">
	  <a id="explore_anchor" href="#">Explore</a>
	</div>
      </div>
      
      <div id="body">
        <div id="left_column">
          <div class="side_group">
            
	    <div class="side_panel doc_panel">
              <p>Manual</p>
              <ul>
                <li><a href="index-overview.html">Overview</a>
                <li><a href="index-tutorials.html">Tutorials</a>
                <li><a href="index-faq.html">FAQs</a>
                <li><a href="index-history.html">History / Changes</a>
                <li><a href="index-licence.html">License</a>
              </ul>
            </div>
            <div class="side_panel doc_panel">
              <p>Reference</p>
              <ul>
                <li><a href="index-language.html">Language</a>
                <li><a href="index-functions.html">Functions</a>
                <li><a href="perlop.html">Operators</a>
                <li><a href="perlvar.html">Special Variables</a>
                <li><a href="index-pragmas.html">Pragmas</a>
                <li><a href="index-utilities.html">Utilities</a>
                <li><a href="index-internals.html">Internals</a>
                <li><a href="index-platforms.html">Platform Specific</a>
              </ul>
            </div>
            <div class="side_panel doc_panel">
              <p>Modules</p>
              <ul>
		<li>
		
                
                  
		    
		  
		
                  
		    
		  
		
                  
		    
		  
		
                  
		    
		  
		
                  
		    
		  
		
                  
		    
		  
		
                  
		    
		  
		
                  
		    
		  
		
                  
		    
		  
		
                  
		
                  
		
                  
		    
		  
		
                  
		    
		  
		
                  
		    
		  
		
                  
		    
		  
		
                  
		    
		  
		
                  
		
                  
		
                  
		    
		  
		
                  
		    
		  
		
                  
		    
		  
		
                  
		
                  
		
                  
		    
		  
		
                  
		
                  
		
		
                    <a href="index-modules-A.html">A</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-B.html">B</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-C.html">C</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-D.html">D</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-E.html">E</a>
                    
                      
                        <li>
                      
                    
                
                    <a href="index-modules-F.html">F</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-G.html">G</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-H.html">H</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-I.html">I</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-L.html">L</a>
                    
                      
                        <li>
                      
                    
                
                    <a href="index-modules-M.html">M</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-N.html">N</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-O.html">O</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-P.html">P</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-S.html">S</a>
                    
                      
                        <li>
                      
                    
                
                    <a href="index-modules-T.html">T</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-U.html">U</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-X.html">X</a>
                    
                
              </ul>
            </div>
            
	      <div class="side_panel doc_panel">
		<p>Tools</p>
		<ul>
		  <li><a href="preferences.html">Preferences</a>
		</ul>
	      </div>
            
          </div>
        </div>
        <div id="centre_column">
          <div id="content_header">
            <div id="title_bar">
              <div id="page_name">
                <h1>perldebguts</h1>
              </div>
              <div id="perl_version">
                Perl 5 version 26.0 documentation
              </div>
              <div class="page_links" id="page_links_top">
                <a href="#" onClick="toolbar.goToTop();return false;">Go to top</a>
		
              </div>
	      <div class="page_links" id="page_links_bottom">
		
                  <a href="#" id="page_index_toggle">Show page index</a> &bull;
		
                <a href="#" id="recent_pages_toggle">Show recent pages</a>		
	      </div>
	      <div id="search_form">
		<form action="search.html" method="GET" id="search">
		  <input type="text" name="q" id="search_box" alt="Search">
		</form>
	      </div>
            </div>
            <div id="breadcrumbs">
                
    <a href="index.html">Home</a> &gt;
    
      
        <a href="index-internals.html">Internals and C language interface</a> &gt;
      
    
    perldebguts
  

            </div>
          </div>
          <div id="content_body">
	    <!--[if lt IE 7]>
 <div class="noscript">
   <p>
     <strong>It looks like you're using Internet Explorer 6. This is a very old
     browser which does not offer full support for modern websites.</strong>
   </p>
   <p>
     Unfortunately this means that this website will not work on
     your computer.
   </p>
   <p>
     Don't miss out though! To view the site (and get a better experience from
     many other websites), simply upgrade to
     <a href="http://www.microsoft.com/windows/Internet-explorer/default.aspx">Internet
Explorer 8</a>
     or download an alternative browser such as
     <a href="http://www.mozilla.com/en-US/firefox/firefox.html">Firefox</a>,
     <a href="http://www.apple.com/safari/download/">Safari</a>, or
     <a href="http://www.google.co.uk/chrome">Google Chrome</a>.
   </p>
   <p>
     All of these browsers are free. If you're using a PC at work, you may
     need to contact your IT administrator.
   </p>
 </div>
<![endif]-->
	    <noscript>
	      <div class="noscript">
	      <p>
                <strong>Please note: Many features of this site require JavaScript. You appear to have JavaScript disabled,
	        or are running a non-JavaScript capable web browser.</strong>
	      </p>
	      <p>
		To get the best experience, please enable JavaScript or download a modern web browser such as <a href="http://www.microsoft.com/windows/Internet-explorer/default.aspx">Internet Explorer 8</a>, <a href="http://www.mozilla.com/en-US/firefox/firefox.html">Firefox</a>, <a href="http://www.apple.com/safari/download/">Safari</a>, or <a href="http://www.google.co.uk/chrome">Google Chrome</a>.
              </p>
	      </div>
	    </noscript>

	    <div id="recent_pages" class="hud_container">
	      <div id="recent_pages_header" class="hud_header">
		<div id="recent_pages_close" class="hud_close"><a href="#" onClick="recentPages.hide();return false;"></a></div>
		<div id="recent_pages_title" class="hud_title"><span class="hud_span_top">Recently read</span></div>
		<div id="recent_pages_topright" class="hud_topright"></div>
	      </div>
	      <div id="recent_pages_content" class="hud_content">
	      </div>
	      <div id="recent_pages_footer" class="hud_footer">
		<div id="recent_pages_bottomleft" class="hud_bottomleft"></div>
		<div id="recent_pages_bottom" class="hud_bottom"><span class="hud_span_bottom"></span></div>
		<div id="recent_pages_resize" class="hud_resize"></div>
	      </div>
	    </div>
  
	    <div id="from_search"></div>
            <h1>perldebguts</h1>


  <!--    -->
<ul><li><a href="#NAME">NAME</a><li><a href="#DESCRIPTION">DESCRIPTION</a><li><a href="#Debugger-Internals">Debugger Internals</a><ul><li><a href="#Writing-Your-Own-Debugger">Writing Your Own Debugger</a></ul><li><a href="#Frame-Listing-Output-Examples">Frame Listing Output Examples</a><li><a href="#Debugging-Regular-Expressions">Debugging Regular Expressions</a><ul><li><a href="#Compile-time-Output">Compile-time Output</a><li><a href="#Types-of-Nodes">Types of Nodes</a><li><a href="#Run-time-Output">Run-time Output</a></ul><li><a href="#Debugging-Perl-Memory-Usage">Debugging Perl Memory Usage</a><ul><li><a href="#Using-%24ENV%7bPERL_DEBUG_MSTATS%7d">Using $ENV{PERL_DEBUG_MSTATS}</a></ul><li><a href="#SEE-ALSO">SEE ALSO</a></ul><a name="NAME"></a><h1>NAME</h1>
<p>perldebguts - Guts of Perl debugging</p>
<a name="DESCRIPTION"></a><h1>DESCRIPTION</h1>
<p>This is not <a href="perldebug.html">perldebug</a>, which tells you how to use
the debugger.  This manpage describes low-level details concerning
the debugger's internals, which range from difficult to impossible
to understand for anyone who isn't incredibly intimate with Perl's guts.
Caveat lector.</p>
<a name="Debugger-Internals"></a><h1>Debugger Internals</h1>
<p>Perl has special debugging hooks at compile-time and run-time used
to create debugging environments.  These hooks are not to be confused
with the <i>perl -Dxxx</i> command described in <a href="perlrun.html">perlrun</a>, which is
usable only if a special Perl is built per the instructions in the
<i>INSTALL</i> podpage in the Perl source tree.</p>
<p>For example, whenever you call Perl's built-in <code class="inline"><a class="l_k" href="functions/caller.html">caller</a></code> function
from the package <code class="inline"><span class="w">DB</span></code>
, the arguments that the corresponding stack
frame was called with are copied to the <code class="inline"><span class="i">@DB::args</span></code>
 array.  These
mechanisms are enabled by calling Perl with the <b>-d</b> switch.
Specifically, the following additional features are enabled
(cf. <a href="perlvar.html#%24%5eP">$^P in perlvar</a>):</p>
<ul>
<li>
<p>Perl inserts the contents of <code class="inline"><span class="i">$ENV</span>{<span class="w">PERL5DB</span>}</code>
 (or <code class="inline">BEGIN <span class="s">{</span><a class="l_k" href="functions/require.html">require</a>
<span class="q">&#39;perl5db.pl&#39;</span><span class="s">}</span></code>
 if not present) before the first line of your program.</p>
</li>
<li>
<p>Each array <code class="inline"><span class="i">@</span>{<span class="q">&quot;_&lt;$filename&quot;</span>}</code>
 holds the lines of $filename for a
file compiled by Perl.  The same is also true for <code class="inline"><a class="l_k" href="functions/eval.html">eval</a></code>ed strings
that contain subroutines, or which are currently being executed.
The $filename for <code class="inline"><a class="l_k" href="functions/eval.html">eval</a></code>ed strings looks like <code class="inline"><span class="s">(</span><a class="l_k" href="functions/eval.html">eval</a> <span class="n">34</span><span class="s">)</span></code>
.</p>
<p>Values in this array are magical in numeric context: they compare
equal to zero only if the line is not breakable.</p>
</li>
<li>
<p>Each hash <code class="inline"><span class="i">%</span>{<span class="q">&quot;_&lt;$filename&quot;</span>}</code>
 contains breakpoints and actions keyed
by line number.  Individual entries (as opposed to the whole hash)
are settable.  Perl only cares about Boolean true here, although
the values used by <i>perl5db.pl</i> have the form
<code class="inline"><span class="q">&quot;$break_condition\0$action&quot;</span></code>
.</p>
<p>The same holds for evaluated strings that contain subroutines, or
which are currently being executed.  The $filename for <code class="inline"><a class="l_k" href="functions/eval.html">eval</a></code>ed strings
looks like <code class="inline"><span class="s">(</span><a class="l_k" href="functions/eval.html">eval</a> <span class="n">34</span><span class="s">)</span></code>
.</p>
</li>
<li>
<p>Each scalar <code class="inline"><span class="i">$</span>{<span class="q">&quot;_&lt;$filename&quot;</span>}</code>
 contains <code class="inline"><span class="q">&quot;_&lt;$filename&quot;</span></code>
.  This is
also the case for evaluated strings that contain subroutines, or
which are currently being executed.  The $filename for <code class="inline"><a class="l_k" href="functions/eval.html">eval</a></code>ed
strings looks like <code class="inline"><span class="s">(</span><a class="l_k" href="functions/eval.html">eval</a> <span class="n">34</span><span class="s">)</span></code>
.</p>
</li>
<li>
<p>After each <code class="inline"><a class="l_k" href="functions/require.html">require</a></code>d file is compiled, but before it is executed,
<code class="inline"><span class="i">DB::postponed</span><span class="s">(</span><span class="i">*</span>{<span class="q">&quot;_&lt;$filename&quot;</span>}<span class="s">)</span></code>
 is called if the subroutine
<code class="inline"><span class="w">DB::postponed</span></code>
 exists.  Here, the $filename is the expanded name of
the <code class="inline"><a class="l_k" href="functions/require.html">require</a></code>d file, as found in the values of %INC.</p>
</li>
<li>
<p>After each subroutine <code class="inline"><span class="w">subname</span></code>
 is compiled, the existence of
<code class="inline"><span class="i">$DB::postponed</span>{<span class="w">subname</span>}</code>
 is checked.  If this key exists,
<code class="inline"><span class="i">DB::postponed</span><span class="s">(</span><span class="w">subname</span><span class="s">)</span></code>
 is called if the <code class="inline"><span class="w">DB::postponed</span></code>
 subroutine
also exists.</p>
</li>
<li>
<p>A hash <code class="inline"><span class="i">%DB::sub</span></code>
 is maintained, whose keys are subroutine names
and whose values have the form <code class="inline"><span class="j">filename:</span><span class="w">startline</span>-<span class="w">endline</span></code>
.
<code class="inline"><span class="w">filename</span></code>
 has the form <code class="inline"><span class="s">(</span><a class="l_k" href="functions/eval.html">eval</a> <span class="n">34</span><span class="s">)</span></code>
 for subroutines defined inside
<code class="inline"><a class="l_k" href="functions/eval.html">eval</a></code>s.</p>
</li>
<li>
<p>When the execution of your program reaches a point that can hold a
breakpoint, the <code class="inline"><span class="i">DB::DB</span><span class="s">(</span><span class="s">)</span></code>
 subroutine is called if any of the variables
<code class="inline"><span class="i">$DB::trace</span></code>
, <code class="inline"><span class="i">$DB::single</span></code>
, or <code class="inline"><span class="i">$DB::signal</span></code>
 is true.  These variables
are not <code class="inline"><a class="l_k" href="functions/local.html">local</a></code>izable.  This feature is disabled when executing
inside <code class="inline"><span class="i">DB::DB</span><span class="s">(</span><span class="s">)</span></code>
, including functions called from it 
unless <code class="inline"><span class="i">$^D</span> &amp; <span class="s">(</span><span class="n">1</span>&lt;&lt;<span class="n">30</span><span class="s">)</span></code>
 is true.</p>
</li>
<li>
<p>When execution of the program reaches a subroutine call, a call to
<code class="inline"><span class="i">&amp;DB::sub</span></code>
(<i>args</i>) is made instead, with <code class="inline"><span class="i">$DB::sub</span></code>
 holding the
name of the called subroutine. (This doesn't happen if the subroutine
was compiled in the <code class="inline"><span class="w">DB</span></code>
 package.)</p>
<p>If the call is to an lvalue subroutine, and <code class="inline"><span class="i">&amp;DB::lsub</span></code>

is defined <code class="inline"><span class="i">&amp;DB::lsub</span></code>
(<i>args</i>) is called instead, otherwise falling
back to <code class="inline"><span class="i">&amp;DB::sub</span></code>
(<i>args</i>).</p>
</li>
<li>
<p>When execution of the program uses <code class="inline"><a class="l_k" href="functions/goto.html">goto</a></code> to enter a non-XS
subroutine and the 0x80 bit is set in <code class="inline"><span class="i">$^P</span></code>
, a call to <code class="inline"><span class="i">&amp;DB::goto</span></code>

is made, with <code class="inline"><span class="i">$DB::sub</span></code>
 holding the name of the subroutine being
entered.</p>
</li>
</ul>
<p>Note that if <code class="inline"><span class="i">&amp;DB::sub</span></code>
 needs external data for it to work, no
subroutine call is possible without it. As an example, the standard
debugger's <code class="inline"><span class="i">&amp;DB::sub</span></code>
 depends on the <code class="inline"><span class="i">$DB::deep</span></code>
 variable
(it defines how many levels of recursion deep into the debugger you can go
before a mandatory break).  If <code class="inline"><span class="i">$DB::deep</span></code>
 is not defined, subroutine
calls are not possible, even though <code class="inline"><span class="i">&amp;DB::sub</span></code>
 exists.</p>
<a name="Writing-Your-Own-Debugger"></a><h2>Writing Your Own Debugger</h2>
<a name="Environment-Variables"></a><h3>Environment Variables</h3>
<p>The <code class="inline"><span class="w">PERL5DB</span></code>
 environment variable can be used to define a debugger.
For example, the minimal "working" debugger (it actually doesn't do anything)
consists of one line:</p>
<pre class="verbatim"><ol><li><a name="DB::DB"></a>  sub <span class="m">DB::DB</span> <span class="s">{</span><span class="s">}</span></li></ol></pre><p>It can easily be defined like this:</p>
<pre class="verbatim"><ol><li>  $ PERL5DB="sub DB::DB {}" perl -d your-script</li></ol></pre><p>Another brief debugger, slightly more useful, can be created
with only the line:</p>
<pre class="verbatim"><ol><li><a name="DB::DB"></a>  sub <span class="m">DB::DB</span> <span class="s">{</span><a class="l_k" href="functions/print.html">print</a> ++<span class="i">$i</span><span class="sc">;</span> <a class="l_k" href="functions/scalar.html">scalar</a> <span class="q">&lt;STDIN&gt;</span><span class="s">}</span></li></ol></pre><p>This debugger prints a number which increments for each statement
encountered and waits for you to hit a newline before continuing
to the next statement.</p>
<p>The following debugger is actually useful:</p>
<pre class="verbatim"><ol><li>  <span class="s">{</span></li><li><a name="package-DB"></a>    package <span class="i">DB</span><span class="sc">;</span></li><li><a name="DB"></a>    sub <span class="m">DB</span>  <span class="s">{</span><span class="s">}</span></li><li><a name="sub"></a>    sub <span class="m">sub</span> <span class="s">{</span><a class="l_k" href="functions/print.html">print</a> ++<span class="i">$i</span><span class="cm">,</span> <span class="q">&quot; $sub\n&quot;</span><span class="sc">;</span> <span class="i">&amp;$sub</span><span class="s">}</span></li><li><a name="package-main"></a>  <span class="s">}</span></li></ol></pre><p>It prints the sequence number of each subroutine call and the name of the
called subroutine.  Note that <code class="inline"><span class="i">&amp;DB::sub</span></code>
 is being compiled into the
package <code class="inline"><span class="w">DB</span></code>
 through the use of the <code class="inline"><a class="l_k" href="functions/package.html">package</a></code> directive.</p>
<p>When it starts, the debugger reads your rc file (<i>./.perldb</i> or
<i>~/.perldb</i> under Unix), which can set important options.
(A subroutine (<code class="inline"><span class="i">&amp;afterinit</span></code>
) can be defined here as well; it is executed
after the debugger completes its own initialization.)</p>
<p>After the rc file is read, the debugger reads the PERLDB_OPTS
environment variable and uses it to set debugger options. The
contents of this variable are treated as if they were the argument
of an <code class="inline"><span class="w">o</span> ...</code>
 debugger command (q.v. in <a href="perldebug.html#Configurable-Options">Configurable Options in perldebug</a>).</p>
<a name="Debugger-Internal-Variables"></a><h3>Debugger Internal Variables</h3>
<p>In addition to the file and subroutine-related variables mentioned above,
the debugger also maintains various magical internal variables.</p>
<ul>
<li>
<p><code class="inline"><span class="i">@DB::dbline</span></code>
 is an alias for <code class="inline"><span class="i">@</span>{<span class="q">&quot;::_&lt;current_file&quot;</span>}</code>
, which
holds the lines of the currently-selected file (compiled by Perl), either
explicitly chosen with the debugger's <code class="inline"><span class="w">f</span></code>
 command, or implicitly by flow
of execution.</p>
<p>Values in this array are magical in numeric context: they compare
equal to zero only if the line is not breakable.</p>
</li>
<li>
<p><code class="inline"><span class="i">%DB::dbline</span></code>
 is an alias for <code class="inline"><span class="i">%</span>{<span class="q">&quot;::_&lt;current_file&quot;</span>}</code>
, which
contains breakpoints and actions keyed by line number in
the currently-selected file, either explicitly chosen with the
debugger's <code class="inline"><span class="w">f</span></code>
 command, or implicitly by flow of execution.</p>
<p>As previously noted, individual entries (as opposed to the whole hash)
are settable.  Perl only cares about Boolean true here, although
the values used by <i>perl5db.pl</i> have the form
<code class="inline"><span class="q">&quot;$break_condition\0$action&quot;</span></code>
.</p>
</li>
</ul>
<a name="Debugger-Customization-Functions"></a><h3>Debugger Customization Functions</h3>
<p>Some functions are provided to simplify customization.</p>
<ul>
<li>
<p>See <a href="perldebug.html#Configurable-Options">Configurable Options in perldebug</a> for a description of options parsed by
<code class="inline"><span class="i">DB::parse_options</span><span class="s">(</span><span class="w">string</span><span class="s">)</span></code>
.</p>
</li>
<li>
<p><code class="inline"><span class="i">DB::dump_trace</span><span class="s">(</span><span class="w">skip</span><span class="s">[</span><span class="cm">,</span><span class="w">count</span><span class="s">]</span><span class="s">)</span></code>
 skips the specified number of frames
and returns a list containing information about the calling frames (all
of them, if <code class="inline"><span class="w">count</span></code>
 is missing).  Each entry is reference to a hash
with keys <code class="inline"><span class="w">context</span></code>
 (either <code class="inline">.</code>, <code class="inline"><span class="i">$</span></code>
, or <code class="inline"><span class="i">@</span></code>
), <code class="inline"><a class="l_k" href="functions/sub.html">sub</a></code> (subroutine
name, or info about <code class="inline"><a class="l_k" href="functions/eval.html">eval</a></code>), <code class="inline"><span class="w">args</span></code>
 (<code class="inline"><a class="l_k" href="functions/undef.html">undef</a></code> or a reference to
an array), <code class="inline"><span class="w">file</span></code>
, and <code class="inline"><span class="w">line</span></code>
.</p>
</li>
<li>
<p><code class="inline"><span class="i">DB::print_trace</span><span class="s">(</span><span class="w">FH</span><span class="cm">,</span> <span class="w">skip</span><span class="s">[</span><span class="cm">,</span> <span class="w">count</span><span class="s">[</span><span class="cm">,</span> <span class="w">short</span><span class="s">]</span><span class="s">]</span><span class="s">)</span></code>
 prints
formatted info about caller frames.  The last two functions may be
convenient as arguments to <code class="inline">&lt;</code>
, <code class="inline">&lt;&lt;</code>
 commands.</p>
</li>
</ul>
<p>Note that any variables and functions that are not documented in
this manpages (or in <a href="perldebug.html">perldebug</a>) are considered for internal   
use only, and as such are subject to change without notice.</p>
<a name="Frame-Listing-Output-Examples"></a><h1>Frame Listing Output Examples</h1>
<p>The <code class="inline"><span class="w">frame</span></code>
 option can be used to control the output of frame 
information.  For example, contrast this expression trace:</p>
<pre class="verbatim"><ol><li> <span class="i">$ perl</span> -<span class="w">de</span> <span class="n">42</span></li><li> <span class="w">Stack</span> <a class="l_k" href="functions/dump.html">dump</a> <span class="w">during</span> <a class="l_k" href="functions/die.html">die</a> <span class="w">enabled</span> <span class="w">outside</span> <span class="w">of</span> <span class="w">evals</span>.</li><li></li><li> <span class="w">Loading</span> <span class="w">DB</span> <span class="w">routines</span> <span class="w">from</span> <span class="w">perl5db</span>.<span class="w">pl</span> <span class="w">patch</span> <span class="w">level</span> <span class="n">0.94</span></li><li> <span class="w">Emacs</span> <span class="w">support</span> <span class="w">available</span>.</li><li></li><li> <span class="w">Enter</span> <span class="w">h</span> <a class="l_k" href="functions/or.html">or</a> <span class="q">&#39;h h&#39;</span> <a class="l_k" href="functions/for.html">for</a> <span class="w">help</span>.</li><li></li><li> <span class="i">main::</span><span class="s">(</span>-e<span class="co">:</span><span class="n">1</span><span class="s">)</span><span class="co">:</span>   <span class="n">0</span></li><li><a name="foo"></a>   <span class="w">DB</span><span class="q">&lt;1&gt;</span> sub <span class="m">foo</span> <span class="s">{</span> <span class="n">14</span> <span class="s">}</span></li><li></li><li><a name="bar"></a>   <span class="w">DB</span><span class="q">&lt;2&gt;</span> sub <span class="m">bar</span> <span class="s">{</span> <span class="n">3</span> <span class="s">}</span></li><li></li><li>   <span class="w">DB</span><span class="q">&lt;3&gt;</span> <span class="w">t</span> <a class="l_k" href="functions/print.html">print</a> <span class="i">foo</span><span class="s">(</span><span class="s">)</span> * <span class="i">bar</span><span class="s">(</span><span class="s">)</span></li><li> <span class="i">main::</span><span class="s">(</span><span class="s">(</span><a class="l_k" href="functions/eval.html">eval</a> <span class="n">172</span><span class="s">)</span><span class="co">:</span><span class="n">3</span><span class="s">)</span><span class="co">:</span>   <a class="l_k" href="functions/print.html">print</a> <span class="i">foo</span><span class="s">(</span><span class="s">)</span> + <span class="i">bar</span><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">main::foo</span><span class="s">(</span><span class="s">(</span><a class="l_k" href="functions/eval.html">eval</a> <span class="n">168</span><span class="s">)</span><span class="co">:</span><span class="n">2</span><span class="s">)</span><span class="co">:</span></li><li> <span class="i">main::bar</span><span class="s">(</span><span class="s">(</span><a class="l_k" href="functions/eval.html">eval</a> <span class="n">170</span><span class="s">)</span><span class="co">:</span><span class="n">2</span><span class="s">)</span><span class="co">:</span></li><li> <span class="n">42</span></li></ol></pre><p>with this one, once the <code class="inline"><span class="w">o</span></code>
ption <code class="inline"><span class="w">frame</span>=<span class="n">2</span></code>
 has been set:</p>
<pre class="verbatim"><ol><li>   DB&lt;4&gt; o f=2</li><li>                frame = '2'</li><li>   DB&lt;5&gt; t print foo() * bar()</li><li> 3:      foo() * bar()</li><li> entering main::foo</li><li>  2:     sub foo { 14 };</li><li> exited main::foo</li><li> entering main::bar</li><li>  2:     sub bar { 3 };</li><li> exited main::bar</li><li> 42</li></ol></pre><p>By way of demonstration, we present below a laborious listing
resulting from setting your <code class="inline"><span class="w">PERLDB_OPTS</span></code>
 environment variable to
the value <code class="inline"><span class="w">f</span>=<span class="w">n</span> <span class="w">N</span></code>
, and running <i>perl -d -V</i> from the command line.
Examples using various values of <code class="inline"><span class="w">n</span></code>
 are shown to give you a feel
for the difference between settings.  Long though it may be, this
is not a complete listing, but only excerpts.</p>
<dl>
<dt>1</dt><dd>
<pre class="verbatim"><ol><li> <span class="w">entering</span> <span class="w">main::BEGIN</span></li><li>  <span class="w">entering</span> <span class="w">Config::BEGIN</span></li><li>   <span class="w">Package</span> <span class="w">lib</span>/<span class="w">Exporter</span>.<span class="w">pm</span>.</li><li>   <span class="w">Package</span> <span class="w">lib</span>/<span class="w">Carp</span>.<span class="w">pm</span>.</li><li>  <span class="w">Package</span> <span class="w">lib</span>/<span class="w">Config</span>.<span class="w">pm</span>.</li><li>  <span class="w">entering</span> <span class="w">Config::TIEHASH</span></li><li>  <span class="w">entering</span> <span class="w">Exporter::import</span></li><li>   <span class="w">entering</span> <span class="w">Exporter::export</span></li><li> <span class="w">entering</span> <span class="w">Config::myconfig</span></li><li>  <span class="w">entering</span> <span class="w">Config::FETCH</span></li><li>  <span class="w">entering</span> <span class="w">Config::FETCH</span></li><li>  <span class="w">entering</span> <span class="w">Config::FETCH</span></li><li>  <span class="w">entering</span> <span class="w">Config::FETCH</span></li></ol></pre></dd>
<dt>2</dt><dd>
<pre class="verbatim"><ol><li> <span class="w">entering</span> <span class="w">main::BEGIN</span></li><li>  <span class="w">entering</span> <span class="w">Config::BEGIN</span></li><li>   <span class="w">Package</span> <span class="w">lib</span>/<span class="w">Exporter</span>.<span class="w">pm</span>.</li><li>   <span class="w">Package</span> <span class="w">lib</span>/<span class="w">Carp</span>.<span class="w">pm</span>.</li><li>  <span class="w">exited</span> <span class="w">Config::BEGIN</span></li><li>  <span class="w">Package</span> <span class="w">lib</span>/<span class="w">Config</span>.<span class="w">pm</span>.</li><li>  <span class="w">entering</span> <span class="w">Config::TIEHASH</span></li><li>  <span class="w">exited</span> <span class="w">Config::TIEHASH</span></li><li>  <span class="w">entering</span> <span class="w">Exporter::import</span></li><li>   <span class="w">entering</span> <span class="w">Exporter::export</span></li><li>   <span class="w">exited</span> <span class="w">Exporter::export</span></li><li>  <span class="w">exited</span> <span class="w">Exporter::import</span></li><li> <span class="w">exited</span> <span class="w">main::BEGIN</span></li><li> <span class="w">entering</span> <span class="w">Config::myconfig</span></li><li>  <span class="w">entering</span> <span class="w">Config::FETCH</span></li><li>  <span class="w">exited</span> <span class="w">Config::FETCH</span></li><li>  <span class="w">entering</span> <span class="w">Config::FETCH</span></li><li>  <span class="w">exited</span> <span class="w">Config::FETCH</span></li><li>  <span class="w">entering</span> <span class="w">Config::FETCH</span></li></ol></pre></dd>
<dt>3</dt><dd>
<pre class="verbatim"><ol><li> <span class="w">in</span>  <span class="i">$=</span><span class="i">main::BEGIN</span><span class="s">(</span><span class="s">)</span> <span class="w">from</span> /<span class="w">dev</span>/<span class="w">null</span><span class="co">:</span><span class="n">0</span></li><li>  <span class="w">in</span>  <span class="i">$=</span><span class="i">Config::BEGIN</span><span class="s">(</span><span class="s">)</span> <span class="w">from</span> <span class="w">lib</span>/<span class="w">Config</span>.<span class="w">pm</span><span class="co">:</span><span class="n">2</span></li><li>   <span class="w">Package</span> <span class="w">lib</span>/<span class="w">Exporter</span>.<span class="w">pm</span>.</li><li>   <span class="w">Package</span> <span class="w">lib</span>/<span class="w">Carp</span>.<span class="w">pm</span>.</li><li>  <span class="w">Package</span> <span class="w">lib</span>/<span class="w">Config</span>.<span class="w">pm</span>.</li><li>  <span class="w">in</span>  <span class="i">$=</span><span class="i">Config::TIEHASH</span><span class="s">(</span><span class="q">&#39;Config&#39;</span><span class="s">)</span> <span class="w">from</span> <span class="w">lib</span>/<span class="w">Config</span>.<span class="w">pm</span><span class="co">:</span><span class="n">644</span></li><li>  <span class="w">in</span>  <span class="i">$=</span><span class="i">Exporter::import</span><span class="s">(</span><span class="q">&#39;Config&#39;</span><span class="cm">,</span> <span class="q">&#39;myconfig&#39;</span><span class="cm">,</span> <span class="q">&#39;config_vars&#39;</span><span class="s">)</span> <span class="w">from</span> /<span class="w">dev</span>/<span class="w">null</span><span class="co">:</span><span class="n">0</span></li><li>   <span class="w">in</span>  <span class="i">$=</span><span class="i">Exporter::export</span><span class="s">(</span><span class="q">&#39;Config&#39;</span><span class="cm">,</span> <span class="q">&#39;main&#39;</span><span class="cm">,</span> <span class="q">&#39;myconfig&#39;</span><span class="cm">,</span> <span class="q">&#39;config_vars&#39;</span><span class="s">)</span> <span class="w">from</span> <span class="w">li</span></li><li> <span class="w">in</span>  <span class="i">@=</span><span class="i">Config::myconfig</span><span class="s">(</span><span class="s">)</span> <span class="w">from</span> /<span class="w">dev</span>/<span class="w">null</span><span class="co">:</span><span class="n">0</span></li><li>  <span class="w">in</span>  <span class="i">$=</span><span class="i">Config::FETCH</span><span class="s">(</span><a class="l_k" href="functions/ref.html">ref</a><span class="s">(</span><span class="w">Config</span><span class="s">)</span><span class="cm">,</span> <span class="q">&#39;package&#39;</span><span class="s">)</span> <span class="w">from</span> <span class="w">lib</span>/<span class="w">Config</span>.<span class="w">pm</span><span class="co">:</span><span class="n">574</span></li><li>  <span class="w">in</span>  <span class="i">$=</span><span class="i">Config::FETCH</span><span class="s">(</span><a class="l_k" href="functions/ref.html">ref</a><span class="s">(</span><span class="w">Config</span><span class="s">)</span><span class="cm">,</span> <span class="q">&#39;baserev&#39;</span><span class="s">)</span> <span class="w">from</span> <span class="w">lib</span>/<span class="w">Config</span>.<span class="w">pm</span><span class="co">:</span><span class="n">574</span></li><li>  <span class="w">in</span>  <span class="i">$=</span><span class="i">Config::FETCH</span><span class="s">(</span><a class="l_k" href="functions/ref.html">ref</a><span class="s">(</span><span class="w">Config</span><span class="s">)</span><span class="cm">,</span> <span class="q">&#39;PERL_VERSION&#39;</span><span class="s">)</span> <span class="w">from</span> <span class="w">lib</span>/<span class="w">Config</span>.<span class="w">pm</span><span class="co">:</span><span class="n">574</span></li><li>  <span class="w">in</span>  <span class="i">$=</span><span class="i">Config::FETCH</span><span class="s">(</span><a class="l_k" href="functions/ref.html">ref</a><span class="s">(</span><span class="w">Config</span><span class="s">)</span><span class="cm">,</span> <span class="q">&#39;PERL_SUBVERSION&#39;</span><span class="s">)</span> <span class="w">from</span> <span class="w">lib</span>/<span class="w">Config</span>.<span class="w">pm</span><span class="co">:</span><span class="n">574</span></li><li>  <span class="w">in</span>  <span class="i">$=</span><span class="i">Config::FETCH</span><span class="s">(</span><a class="l_k" href="functions/ref.html">ref</a><span class="s">(</span><span class="w">Config</span><span class="s">)</span><span class="cm">,</span> <span class="q">&#39;osname&#39;</span><span class="s">)</span> <span class="w">from</span> <span class="w">lib</span>/<span class="w">Config</span>.<span class="w">pm</span><span class="co">:</span><span class="n">574</span></li><li>  <span class="w">in</span>  <span class="i">$=</span><span class="i">Config::FETCH</span><span class="s">(</span><a class="l_k" href="functions/ref.html">ref</a><span class="s">(</span><span class="w">Config</span><span class="s">)</span><span class="cm">,</span> <span class="q">&#39;osvers&#39;</span><span class="s">)</span> <span class="w">from</span> <span class="w">lib</span>/<span class="w">Config</span>.<span class="w">pm</span><span class="co">:</span><span class="n">574</span></li></ol></pre></dd>
<dt>4</dt><dd>
<pre class="verbatim"><ol><li> <span class="w">in</span>  <span class="i">$=</span><span class="i">main::BEGIN</span><span class="s">(</span><span class="s">)</span> <span class="w">from</span> /<span class="w">dev</span>/<span class="w">null</span><span class="co">:</span><span class="n">0</span></li><li>  <span class="w">in</span>  <span class="i">$=</span><span class="i">Config::BEGIN</span><span class="s">(</span><span class="s">)</span> <span class="w">from</span> <span class="w">lib</span>/<span class="w">Config</span>.<span class="w">pm</span><span class="co">:</span><span class="n">2</span></li><li>   <span class="w">Package</span> <span class="w">lib</span>/<span class="w">Exporter</span>.<span class="w">pm</span>.</li><li>   <span class="w">Package</span> <span class="w">lib</span>/<span class="w">Carp</span>.<span class="w">pm</span>.</li><li>  <span class="w">out</span> <span class="i">$=</span><span class="i">Config::BEGIN</span><span class="s">(</span><span class="s">)</span> <span class="w">from</span> <span class="w">lib</span>/<span class="w">Config</span>.<span class="w">pm</span><span class="co">:</span><span class="n">0</span></li><li>  <span class="w">Package</span> <span class="w">lib</span>/<span class="w">Config</span>.<span class="w">pm</span>.</li><li>  <span class="w">in</span>  <span class="i">$=</span><span class="i">Config::TIEHASH</span><span class="s">(</span><span class="q">&#39;Config&#39;</span><span class="s">)</span> <span class="w">from</span> <span class="w">lib</span>/<span class="w">Config</span>.<span class="w">pm</span><span class="co">:</span><span class="n">644</span></li><li>  <span class="w">out</span> <span class="i">$=</span><span class="i">Config::TIEHASH</span><span class="s">(</span><span class="q">&#39;Config&#39;</span><span class="s">)</span> <span class="w">from</span> <span class="w">lib</span>/<span class="w">Config</span>.<span class="w">pm</span><span class="co">:</span><span class="n">644</span></li><li>  <span class="w">in</span>  <span class="i">$=</span><span class="i">Exporter::import</span><span class="s">(</span><span class="q">&#39;Config&#39;</span><span class="cm">,</span> <span class="q">&#39;myconfig&#39;</span><span class="cm">,</span> <span class="q">&#39;config_vars&#39;</span><span class="s">)</span> <span class="w">from</span> /<span class="w">dev</span>/<span class="w">null</span><span class="co">:</span><span class="n">0</span></li><li>   <span class="w">in</span>  <span class="i">$=</span><span class="i">Exporter::export</span><span class="s">(</span><span class="q">&#39;Config&#39;</span><span class="cm">,</span> <span class="q">&#39;main&#39;</span><span class="cm">,</span> <span class="q">&#39;myconfig&#39;</span><span class="cm">,</span> <span class="q">&#39;config_vars&#39;</span><span class="s">)</span> <span class="w">from</span> <span class="w">lib</span>/</li><li>   <span class="w">out</span> <span class="i">$=</span><span class="i">Exporter::export</span><span class="s">(</span><span class="q">&#39;Config&#39;</span><span class="cm">,</span> <span class="q">&#39;main&#39;</span><span class="cm">,</span> <span class="q">&#39;myconfig&#39;</span><span class="cm">,</span> <span class="q">&#39;config_vars&#39;</span><span class="s">)</span> <span class="w">from</span> <span class="w">lib</span>/</li><li>  <span class="w">out</span> <span class="i">$=</span><span class="i">Exporter::import</span><span class="s">(</span><span class="q">&#39;Config&#39;</span><span class="cm">,</span> <span class="q">&#39;myconfig&#39;</span><span class="cm">,</span> <span class="q">&#39;config_vars&#39;</span><span class="s">)</span> <span class="w">from</span> /<span class="w">dev</span>/<span class="w">null</span><span class="co">:</span><span class="n">0</span></li><li> <span class="w">out</span> <span class="i">$=</span><span class="i">main::BEGIN</span><span class="s">(</span><span class="s">)</span> <span class="w">from</span> /<span class="w">dev</span>/<span class="w">null</span><span class="co">:</span><span class="n">0</span></li><li> <span class="w">in</span>  <span class="i">@=</span><span class="i">Config::myconfig</span><span class="s">(</span><span class="s">)</span> <span class="w">from</span> /<span class="w">dev</span>/<span class="w">null</span><span class="co">:</span><span class="n">0</span></li><li>  <span class="w">in</span>  <span class="i">$=</span><span class="i">Config::FETCH</span><span class="s">(</span><a class="l_k" href="functions/ref.html">ref</a><span class="s">(</span><span class="w">Config</span><span class="s">)</span><span class="cm">,</span> <span class="q">&#39;package&#39;</span><span class="s">)</span> <span class="w">from</span> <span class="w">lib</span>/<span class="w">Config</span>.<span class="w">pm</span><span class="co">:</span><span class="n">574</span></li><li>  <span class="w">out</span> <span class="i">$=</span><span class="i">Config::FETCH</span><span class="s">(</span><a class="l_k" href="functions/ref.html">ref</a><span class="s">(</span><span class="w">Config</span><span class="s">)</span><span class="cm">,</span> <span class="q">&#39;package&#39;</span><span class="s">)</span> <span class="w">from</span> <span class="w">lib</span>/<span class="w">Config</span>.<span class="w">pm</span><span class="co">:</span><span class="n">574</span></li><li>  <span class="w">in</span>  <span class="i">$=</span><span class="i">Config::FETCH</span><span class="s">(</span><a class="l_k" href="functions/ref.html">ref</a><span class="s">(</span><span class="w">Config</span><span class="s">)</span><span class="cm">,</span> <span class="q">&#39;baserev&#39;</span><span class="s">)</span> <span class="w">from</span> <span class="w">lib</span>/<span class="w">Config</span>.<span class="w">pm</span><span class="co">:</span><span class="n">574</span></li><li>  <span class="w">out</span> <span class="i">$=</span><span class="i">Config::FETCH</span><span class="s">(</span><a class="l_k" href="functions/ref.html">ref</a><span class="s">(</span><span class="w">Config</span><span class="s">)</span><span class="cm">,</span> <span class="q">&#39;baserev&#39;</span><span class="s">)</span> <span class="w">from</span> <span class="w">lib</span>/<span class="w">Config</span>.<span class="w">pm</span><span class="co">:</span><span class="n">574</span></li><li>  <span class="w">in</span>  <span class="i">$=</span><span class="i">Config::FETCH</span><span class="s">(</span><a class="l_k" href="functions/ref.html">ref</a><span class="s">(</span><span class="w">Config</span><span class="s">)</span><span class="cm">,</span> <span class="q">&#39;PERL_VERSION&#39;</span><span class="s">)</span> <span class="w">from</span> <span class="w">lib</span>/<span class="w">Config</span>.<span class="w">pm</span><span class="co">:</span><span class="n">574</span></li><li>  <span class="w">out</span> <span class="i">$=</span><span class="i">Config::FETCH</span><span class="s">(</span><a class="l_k" href="functions/ref.html">ref</a><span class="s">(</span><span class="w">Config</span><span class="s">)</span><span class="cm">,</span> <span class="q">&#39;PERL_VERSION&#39;</span><span class="s">)</span> <span class="w">from</span> <span class="w">lib</span>/<span class="w">Config</span>.<span class="w">pm</span><span class="co">:</span><span class="n">574</span></li><li>  <span class="w">in</span>  <span class="i">$=</span><span class="i">Config::FETCH</span><span class="s">(</span><a class="l_k" href="functions/ref.html">ref</a><span class="s">(</span><span class="w">Config</span><span class="s">)</span><span class="cm">,</span> <span class="q">&#39;PERL_SUBVERSION&#39;</span><span class="s">)</span> <span class="w">from</span> <span class="w">lib</span>/<span class="w">Config</span>.<span class="w">pm</span><span class="co">:</span><span class="n">574</span></li></ol></pre></dd>
<dt>5</dt><dd>
<pre class="verbatim"><ol><li> <span class="w">in</span>  <span class="i">$=</span><span class="i">main::BEGIN</span><span class="s">(</span><span class="s">)</span> <span class="w">from</span> /<span class="w">dev</span>/<span class="w">null</span><span class="co">:</span><span class="n">0</span></li><li>  <span class="w">in</span>  <span class="i">$=</span><span class="i">Config::BEGIN</span><span class="s">(</span><span class="s">)</span> <span class="w">from</span> <span class="w">lib</span>/<span class="w">Config</span>.<span class="w">pm</span><span class="co">:</span><span class="n">2</span></li><li>   <span class="w">Package</span> <span class="w">lib</span>/<span class="w">Exporter</span>.<span class="w">pm</span>.</li><li>   <span class="w">Package</span> <span class="w">lib</span>/<span class="w">Carp</span>.<span class="w">pm</span>.</li><li>  <span class="w">out</span> <span class="i">$=</span><span class="i">Config::BEGIN</span><span class="s">(</span><span class="s">)</span> <span class="w">from</span> <span class="w">lib</span>/<span class="w">Config</span>.<span class="w">pm</span><span class="co">:</span><span class="n">0</span></li><li>  <span class="w">Package</span> <span class="w">lib</span>/<span class="w">Config</span>.<span class="w">pm</span>.</li><li>  <span class="w">in</span>  <span class="i">$=</span><span class="i">Config::TIEHASH</span><span class="s">(</span><span class="q">&#39;Config&#39;</span><span class="s">)</span> <span class="w">from</span> <span class="w">lib</span>/<span class="w">Config</span>.<span class="w">pm</span><span class="co">:</span><span class="n">644</span></li><li>  <span class="w">out</span> <span class="i">$=</span><span class="i">Config::TIEHASH</span><span class="s">(</span><span class="q">&#39;Config&#39;</span><span class="s">)</span> <span class="w">from</span> <span class="w">lib</span>/<span class="w">Config</span>.<span class="w">pm</span><span class="co">:</span><span class="n">644</span></li><li>  <span class="w">in</span>  <span class="i">$=</span><span class="i">Exporter::import</span><span class="s">(</span><span class="q">&#39;Config&#39;</span><span class="cm">,</span> <span class="q">&#39;myconfig&#39;</span><span class="cm">,</span> <span class="q">&#39;config_vars&#39;</span><span class="s">)</span> <span class="w">from</span> /<span class="w">dev</span>/<span class="w">null</span><span class="co">:</span><span class="n">0</span></li><li>   <span class="w">in</span>  <span class="i">$=</span><span class="i">Exporter::export</span><span class="s">(</span><span class="q">&#39;Config&#39;</span><span class="cm">,</span> <span class="q">&#39;main&#39;</span><span class="cm">,</span> <span class="q">&#39;myconfig&#39;</span><span class="cm">,</span> <span class="q">&#39;config_vars&#39;</span><span class="s">)</span> <span class="w">from</span> <span class="w">lib</span>/<span class="w">E</span></li><li>   <span class="w">out</span> <span class="i">$=</span><span class="i">Exporter::export</span><span class="s">(</span><span class="q">&#39;Config&#39;</span><span class="cm">,</span> <span class="q">&#39;main&#39;</span><span class="cm">,</span> <span class="q">&#39;myconfig&#39;</span><span class="cm">,</span> <span class="q">&#39;config_vars&#39;</span><span class="s">)</span> <span class="w">from</span> <span class="w">lib</span>/<span class="w">E</span></li><li>  <span class="w">out</span> <span class="i">$=</span><span class="i">Exporter::import</span><span class="s">(</span><span class="q">&#39;Config&#39;</span><span class="cm">,</span> <span class="q">&#39;myconfig&#39;</span><span class="cm">,</span> <span class="q">&#39;config_vars&#39;</span><span class="s">)</span> <span class="w">from</span> /<span class="w">dev</span>/<span class="w">null</span><span class="co">:</span><span class="n">0</span></li><li> <span class="w">out</span> <span class="i">$=</span><span class="i">main::BEGIN</span><span class="s">(</span><span class="s">)</span> <span class="w">from</span> /<span class="w">dev</span>/<span class="w">null</span><span class="co">:</span><span class="n">0</span></li><li> <span class="w">in</span>  <span class="i">@=</span><span class="i">Config::myconfig</span><span class="s">(</span><span class="s">)</span> <span class="w">from</span> /<span class="w">dev</span>/<span class="w">null</span><span class="co">:</span><span class="n">0</span></li><li>  <span class="w">in</span>  <span class="i">$=</span><span class="i">Config::FETCH</span><span class="s">(</span><span class="q">&#39;Config=HASH(0x1aa444)&#39;</span><span class="cm">,</span> <span class="q">&#39;package&#39;</span><span class="s">)</span> <span class="w">from</span> <span class="w">lib</span>/<span class="w">Config</span>.<span class="w">pm</span><span class="co">:</span><span class="n">574</span></li><li>  <span class="w">out</span> <span class="i">$=</span><span class="i">Config::FETCH</span><span class="s">(</span><span class="q">&#39;Config=HASH(0x1aa444)&#39;</span><span class="cm">,</span> <span class="q">&#39;package&#39;</span><span class="s">)</span> <span class="w">from</span> <span class="w">lib</span>/<span class="w">Config</span>.<span class="w">pm</span><span class="co">:</span><span class="n">574</span></li><li>  <span class="w">in</span>  <span class="i">$=</span><span class="i">Config::FETCH</span><span class="s">(</span><span class="q">&#39;Config=HASH(0x1aa444)&#39;</span><span class="cm">,</span> <span class="q">&#39;baserev&#39;</span><span class="s">)</span> <span class="w">from</span> <span class="w">lib</span>/<span class="w">Config</span>.<span class="w">pm</span><span class="co">:</span><span class="n">574</span></li><li>  <span class="w">out</span> <span class="i">$=</span><span class="i">Config::FETCH</span><span class="s">(</span><span class="q">&#39;Config=HASH(0x1aa444)&#39;</span><span class="cm">,</span> <span class="q">&#39;baserev&#39;</span><span class="s">)</span> <span class="w">from</span> <span class="w">lib</span>/<span class="w">Config</span>.<span class="w">pm</span><span class="co">:</span><span class="n">574</span></li></ol></pre></dd>
<dt>6</dt><dd>
<pre class="verbatim"><ol><li> <span class="w">in</span>  <span class="i">$=</span><span class="i">CODE</span><span class="s">(</span><span class="n">0x15eca4</span><span class="s">)</span><span class="s">(</span><span class="s">)</span> <span class="w">from</span> /<span class="w">dev</span>/<span class="w">null</span><span class="co">:</span><span class="n">0</span></li><li>  <span class="w">in</span>  <span class="i">$=</span><span class="i">CODE</span><span class="s">(</span><span class="n">0x182528</span><span class="s">)</span><span class="s">(</span><span class="s">)</span> <span class="w">from</span> <span class="w">lib</span>/<span class="w">Config</span>.<span class="w">pm</span><span class="co">:</span><span class="n">2</span></li><li>   <span class="w">Package</span> <span class="w">lib</span>/<span class="w">Exporter</span>.<span class="w">pm</span>.</li><li>  <span class="w">out</span> <span class="i">$=</span><span class="i">CODE</span><span class="s">(</span><span class="n">0x182528</span><span class="s">)</span><span class="s">(</span><span class="s">)</span> <span class="w">from</span> <span class="w">lib</span>/<span class="w">Config</span>.<span class="w">pm</span><span class="co">:</span><span class="n">0</span></li><li>  <a class="l_k" href="functions/scalar.html">scalar</a> <span class="w">context</span> <a class="l_k" href="functions/return.html">return</a> <span class="w">from</span> <span class="i">CODE</span><span class="s">(</span><span class="n">0x182528</span><span class="s">)</span><span class="co">:</span> <a class="l_k" href="functions/undef.html">undef</a></li><li>  <span class="w">Package</span> <span class="w">lib</span>/<span class="w">Config</span>.<span class="w">pm</span>.</li><li>  <span class="w">in</span>  <span class="i">$=</span><span class="i">Config::TIEHASH</span><span class="s">(</span><span class="q">&#39;Config&#39;</span><span class="s">)</span> <span class="w">from</span> <span class="w">lib</span>/<span class="w">Config</span>.<span class="w">pm</span><span class="co">:</span><span class="n">628</span></li><li>  <span class="w">out</span> <span class="i">$=</span><span class="i">Config::TIEHASH</span><span class="s">(</span><span class="q">&#39;Config&#39;</span><span class="s">)</span> <span class="w">from</span> <span class="w">lib</span>/<span class="w">Config</span>.<span class="w">pm</span><span class="co">:</span><span class="n">628</span></li><li>  <a class="l_k" href="functions/scalar.html">scalar</a> <span class="w">context</span> <a class="l_k" href="functions/return.html">return</a> <span class="w">from</span> <span class="w">Config::TIEHASH</span><span class="co">:</span>   <span class="w">empty</span> <span class="w">hash</span></li><li>  <span class="w">in</span>  <span class="i">$=</span><span class="i">Exporter::import</span><span class="s">(</span><span class="q">&#39;Config&#39;</span><span class="cm">,</span> <span class="q">&#39;myconfig&#39;</span><span class="cm">,</span> <span class="q">&#39;config_vars&#39;</span><span class="s">)</span> <span class="w">from</span> /<span class="w">dev</span>/<span class="w">null</span><span class="co">:</span><span class="n">0</span></li><li>   <span class="w">in</span>  <span class="i">$=</span><span class="i">Exporter::export</span><span class="s">(</span><span class="q">&#39;Config&#39;</span><span class="cm">,</span> <span class="q">&#39;main&#39;</span><span class="cm">,</span> <span class="q">&#39;myconfig&#39;</span><span class="cm">,</span> <span class="q">&#39;config_vars&#39;</span><span class="s">)</span> <span class="w">from</span> <span class="w">lib</span>/<span class="w">Exporter</span>.<span class="w">pm</span><span class="co">:</span><span class="n">171</span></li><li>   <span class="w">out</span> <span class="i">$=</span><span class="i">Exporter::export</span><span class="s">(</span><span class="q">&#39;Config&#39;</span><span class="cm">,</span> <span class="q">&#39;main&#39;</span><span class="cm">,</span> <span class="q">&#39;myconfig&#39;</span><span class="cm">,</span> <span class="q">&#39;config_vars&#39;</span><span class="s">)</span> <span class="w">from</span> <span class="w">lib</span>/<span class="w">Exporter</span>.<span class="w">pm</span><span class="co">:</span><span class="n">171</span></li><li>   <a class="l_k" href="functions/scalar.html">scalar</a> <span class="w">context</span> <a class="l_k" href="functions/return.html">return</a> <span class="w">from</span> <span class="w">Exporter::export</span><span class="co">:</span> <span class="q">&#39;&#39;</span></li><li>  <span class="w">out</span> <span class="i">$=</span><span class="i">Exporter::import</span><span class="s">(</span><span class="q">&#39;Config&#39;</span><span class="cm">,</span> <span class="q">&#39;myconfig&#39;</span><span class="cm">,</span> <span class="q">&#39;config_vars&#39;</span><span class="s">)</span> <span class="w">from</span> /<span class="w">dev</span>/<span class="w">null</span><span class="co">:</span><span class="n">0</span></li><li>  <a class="l_k" href="functions/scalar.html">scalar</a> <span class="w">context</span> <a class="l_k" href="functions/return.html">return</a> <span class="w">from</span> <span class="w">Exporter::import</span><span class="co">:</span> <span class="q">&#39;&#39;</span></li></ol></pre></dd>
</dl>
<p>In all cases shown above, the line indentation shows the call tree.
If bit 2 of <code class="inline"><span class="w">frame</span></code>
 is set, a line is printed on exit from a
subroutine as well.  If bit 4 is set, the arguments are printed
along with the caller info.  If bit 8 is set, the arguments are
printed even if they are tied or references.  If bit 16 is set, the
return value is printed, too.</p>
<p>When a package is compiled, a line like this</p>
<pre class="verbatim"><ol><li>    <span class="w">Package</span> <span class="w">lib</span>/<span class="w">Carp</span>.<span class="w">pm</span>.</li></ol></pre><p>is printed with proper indentation.</p>
<a name="Debugging-Regular-Expressions"></a><h1>Debugging Regular Expressions</h1>
<p>There are two ways to enable debugging output for regular expressions.</p>
<p>If your perl is compiled with <code class="inline">-<span class="w">DDEBUGGING</span></code>
, you may use the
<b>-Dr</b> flag on the command line.</p>
<p>Otherwise, one can <code class="inline"><a class="l_k" href="functions/use.html">use</a> <span class="w">re</span> <span class="q">&#39;debug&#39;</span></code>
, which has effects at
compile time and run time.  Since Perl 5.9.5, this pragma is lexically
scoped.</p>
<a name="Compile-time-Output"></a><h2>Compile-time Output</h2>
<p>The debugging output at compile time looks like this:</p>
<pre class="verbatim"><ol><li>  <span class="w">Compiling</span> <span class="w">REx</span> <span class="q">&#39;[bc]d(ef*g)+h[ij]k$&#39;</span></li><li>  <span class="w">size</span> <span class="n">45</span> <span class="w">Got</span> <span class="n">364</span> <span class="w">bytes</span> <a class="l_k" href="functions/for.html">for</a> <span class="w">offset</span> <span class="w">annotations</span>.</li><li>  <span class="w">first</span> <span class="w">at</span> <span class="n">1</span></li><li>  <span class="w">rarest</span> <span class="w">char</span> <span class="w">g</span> <span class="w">at</span> <span class="n">0</span></li><li>  <span class="w">rarest</span> <span class="w">char</span> <span class="w">d</span> <span class="w">at</span> <span class="n">0</span></li><li>     <span class="n">1</span><span class="co">:</span> <span class="w">ANYOF</span><span class="s">[</span><span class="w">bc</span><span class="s">]</span><span class="s">(</span><span class="n">12</span><span class="s">)</span></li><li>    <span class="n">12</span><span class="co">:</span> <span class="w">EXACT</span> <span class="q">&lt;d&gt;</span><span class="s">(</span><span class="n">14</span><span class="s">)</span></li><li>    <span class="n">14</span><span class="co">:</span> <span class="w">CURLYX</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="s">{</span><span class="n">1</span><span class="cm">,</span><span class="n">32767</span><span class="s">}</span><span class="s">(</span><span class="n">28</span><span class="s">)</span></li><li>    <span class="n">16</span><span class="co">:</span>   <span class="i">OPEN1</span><span class="s">(</span><span class="n">18</span><span class="s">)</span></li><li>    <span class="n">18</span><span class="co">:</span>     <span class="w">EXACT</span> <span class="q">&lt;e&gt;</span><span class="s">(</span><span class="n">20</span><span class="s">)</span></li><li>    <span class="n">20</span><span class="co">:</span>     <span class="i">STAR</span><span class="s">(</span><span class="n">23</span><span class="s">)</span></li><li>    <span class="n">21</span><span class="co">:</span>       <span class="w">EXACT</span> <span class="q">&lt;f&gt;</span><span class="s">(</span><span class="n">0</span><span class="s">)</span></li><li>    <span class="n">23</span><span class="co">:</span>     <span class="w">EXACT</span> <span class="q">&lt;g&gt;</span><span class="s">(</span><span class="n">25</span><span class="s">)</span></li><li>    <span class="n">25</span><span class="co">:</span>   <span class="i">CLOSE1</span><span class="s">(</span><span class="n">27</span><span class="s">)</span></li><li>    <span class="n">27</span><span class="co">:</span>   <span class="w">WHILEM</span><span class="s">[</span><span class="n">1</span>/<span class="n">1</span><span class="s">]</span><span class="s">(</span><span class="n">0</span><span class="s">)</span></li><li>    <span class="n">28</span><span class="co">:</span> <span class="i">NOTHING</span><span class="s">(</span><span class="n">29</span><span class="s">)</span></li><li>    <span class="n">29</span><span class="co">:</span> <span class="w">EXACT</span> <span class="q">&lt;h&gt;</span><span class="s">(</span><span class="n">31</span><span class="s">)</span></li><li>    <span class="n">31</span><span class="co">:</span> <span class="w">ANYOF</span><span class="s">[</span><span class="w">ij</span><span class="s">]</span><span class="s">(</span><span class="n">42</span><span class="s">)</span></li><li>    <span class="n">42</span><span class="co">:</span> <span class="w">EXACT</span> <span class="q">&lt;k&gt;</span><span class="s">(</span><span class="n">44</span><span class="s">)</span></li><li>    <span class="n">44</span><span class="co">:</span> <span class="i">EOL</span><span class="s">(</span><span class="n">45</span><span class="s">)</span></li><li>    <span class="n">45</span><span class="co">:</span> <a class="l_k" href="functions/END.html">END</a><span class="s">(</span><span class="n">0</span><span class="s">)</span></li><li>  <span class="w">anchored</span> <span class="q">&#39;de&#39;</span> <span class="w">at</span> <span class="n">1</span> <span class="w">floating</span> <span class="q">&#39;gh&#39;</span> <span class="w">at</span> <span class="n">3</span>..<span class="n">2147483647</span> <span class="s">(</span><span class="w">checking</span> <span class="w">floating</span><span class="s">)</span> </li><li>        <span class="w">stclass</span> <span class="q">&#39;ANYOF[bc]&#39;</span> <span class="w">minlen</span> <span class="n">7</span> </li><li>  <span class="w">Offsets</span><span class="co">:</span> <span class="s">[</span><span class="n">45</span><span class="s">]</span></li><li>  	<span class="n">1</span><span class="s">[</span><span class="n">4</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">5</span><span class="s">[</span><span class="n">1</span><span class="s">]</span></li><li>  	<span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">12</span><span class="s">[</span><span class="n">1</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">6</span><span class="s">[</span><span class="n">1</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">7</span><span class="s">[</span><span class="n">1</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">9</span><span class="s">[</span><span class="n">1</span><span class="s">]</span> <span class="n">8</span><span class="s">[</span><span class="n">1</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">10</span><span class="s">[</span><span class="n">1</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span></li><li>  	<span class="n">11</span><span class="s">[</span><span class="n">1</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">12</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">12</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">13</span><span class="s">[</span><span class="n">1</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">14</span><span class="s">[</span><span class="n">4</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span></li><li>  	<span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">18</span><span class="s">[</span><span class="n">1</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">19</span><span class="s">[</span><span class="n">1</span><span class="s">]</span> <span class="n">20</span><span class="s">[</span><span class="n">0</span><span class="s">]</span>  </li><li>  <span class="w">Omitting</span> <span class="i">$`</span> <span class="i">$&amp;</span> <span class="i">$&#39;</span> <span class="w">support</span>.</li></ol></pre><p>The first line shows the pre-compiled form of the regex.  The second
shows the size of the compiled form (in arbitrary units, usually
4-byte words) and the total number of bytes allocated for the
offset/length table, usually 4+<code class="inline"><span class="w">size</span></code>
*8.  The next line shows the
label <i>id</i> of the first node that does a match.</p>
<p>The</p>
<pre class="verbatim"><ol><li>  <span class="w">anchored</span> <span class="q">&#39;de&#39;</span> <span class="w">at</span> <span class="n">1</span> <span class="w">floating</span> <span class="q">&#39;gh&#39;</span> <span class="w">at</span> <span class="n">3</span>..<span class="n">2147483647</span> <span class="s">(</span><span class="w">checking</span> <span class="w">floating</span><span class="s">)</span> </li><li>        <span class="w">stclass</span> <span class="q">&#39;ANYOF[bc]&#39;</span> <span class="w">minlen</span> <span class="n">7</span></li></ol></pre><p>line (split into two lines above) contains optimizer
information.  In the example shown, the optimizer found that the match 
should contain a substring <code class="inline"><span class="w">de</span></code>
 at offset 1, plus substring <code class="inline"><span class="w">gh</span></code>

at some offset between 3 and infinity.  Moreover, when checking for
these substrings (to abandon impossible matches quickly), Perl will check
for the substring <code class="inline"><span class="w">gh</span></code>
 before checking for the substring <code class="inline"><span class="w">de</span></code>
.  The
optimizer may also use the knowledge that the match starts (at the
<code class="inline"><span class="w">first</span></code>
 <i>id</i>) with a character class, and no string 
shorter than 7 characters can possibly match.</p>
<p>The fields of interest which may appear in this line are</p>
<ul>
<li><a name="anchored-_STRING_-at-_POS_"></a><b><code class="inline"><span class="w">anchored</span></code>
 <i>STRING</i> <code class="inline"><span class="w">at</span></code>
 <i>POS</i></b>
</li>
<li><a name="floating-_STRING_-at-_POS1..POS2_"></a><b><code class="inline"><span class="w">floating</span></code>
 <i>STRING</i> <code class="inline"><span class="w">at</span></code>
 <i>POS1..POS2</i></b>
<p>See above.</p>
</li>
<li><a name="matching-floating%2fanchored"></a><b><code class="inline"><span class="w">matching</span> <span class="w">floating</span>/<span class="w">anchored</span></code>
</b>
<p>Which substring to check first.</p>
</li>
<li><a name="minlen"></a><b><code class="inline"><span class="w">minlen</span></code>
</b>
<p>The minimal length of the match.</p>
</li>
<li><a name="stclass-_TYPE_"></a><b><code class="inline"><span class="w">stclass</span></code>
 <i>TYPE</i></b>
<p>Type of first matching node.</p>
</li>
<li><a name="noscan"></a><b><code class="inline"><span class="w">noscan</span></code>
</b>
<p>Don't scan for the found substrings.</p>
</li>
<li><a name="isall"></a><b><code class="inline"><span class="w">isall</span></code>
</b>
<p>Means that the optimizer information is all that the regular
expression contains, and thus one does not need to enter the regex engine at
all.</p>
</li>
<li><a name="GPOS"></a><b><code class="inline"><span class="w">GPOS</span></code>
</b>
<p>Set if the pattern contains <code class="inline">\<span class="w">G</span></code>
.</p>
</li>
<li><a name="plus"></a><b><code class="inline"><span class="w">plus</span></code>
</b>
<p>Set if the pattern starts with a repeated char (as in <code class="inline">x+y</code>).</p>
</li>
<li><a name="implicit"></a><b><code class="inline"><span class="w">implicit</span></code>
</b>
<p>Set if the pattern starts with <code class="inline">.*</code>.</p>
</li>
<li><a name="with-eval"></a><b><code class="inline"><span class="w">with</span> <a class="l_k" href="functions/eval.html">eval</a></code>
</b>
<p>Set if the pattern contain eval-groups, such as <code class="inline">(?{ code })</code> and
<code class="inline"><span class="s">(</span><span class="q">??</span><span class="s">{</span> <span class="w">code</span> <span class="s">}</span><span class="s">)</span></code>
.</p>
</li>
<li><a name="anchored(TYPE)"></a><b><code class="inline"><span class="i">anchored</span><span class="s">(</span><span class="w">TYPE</span><span class="s">)</span></code>
</b>
<p>If the pattern may match only at a handful of places, with <code class="inline"><span class="w">TYPE</span></code>

being <code class="inline"><span class="w">SBOL</span></code>
, <code class="inline"><span class="w">MBOL</span></code>
, or <code class="inline"><span class="w">GPOS</span></code>
.  See the table below.</p>
</li>
</ul>
<p>If a substring is known to match at end-of-line only, it may be
followed by <code class="inline"><span class="i">$</span></code>
, as in <code class="inline"><span class="w">floating</span> <span class="q">&#39;k&#39;</span><span class="i">$</span></code>
.</p>
<p>The optimizer-specific information is used to avoid entering (a slow) regex
engine on strings that will not definitely match.  If the <code class="inline"><span class="w">isall</span></code>
 flag
is set, a call to the regex engine may be avoided even when the optimizer
found an appropriate place for the match.</p>
<p>Above the optimizer section is the list of <i>nodes</i> of the compiled
form of the regex.  Each line has format</p>
<p><code class="inline">   </code>
<i>id</i>: <i>TYPE</i> <i>OPTIONAL-INFO</i> (<i>next-id</i>)</p>
<a name="Types-of-Nodes"></a><h2>Types of Nodes</h2>
<p>Here are the current possible types, with short descriptions:</p>
<pre class="verbatim"><ol><li> <span class="c"># TYPE arg-description [num-args] [longjump-len] DESCRIPTION</span></li><li></li><li> <span class="c"># Exit points</span></li><li></li><li> <a class="l_k" href="functions/END.html">END</a>             <a class="l_k" href="functions/no.html">no</a>         <span class="w">End</span> <span class="w">of</span> <span class="w">program</span>.</li><li> <span class="w">SUCCEED</span>         <a class="l_k" href="functions/no.html">no</a>         <span class="w">Return</span> <span class="w">from</span> <span class="w">a</span> <span class="w">subroutine</span><span class="cm">,</span> <span class="w">basically</span>.</li><li></li><li> <span class="c"># Line Start Anchors:</span></li><li> <span class="w">SBOL</span>            <a class="l_k" href="functions/no.html">no</a>         <span class="w">Match</span> <span class="q">&quot;&quot;</span> <span class="w">at</span> <span class="w">beginning</span> <span class="w">of</span> <span class="w">line</span><span class="co">:</span> <span class="q">/^/</span><span class="cm">,</span> <span class="q">/\A/</span></li><li> <span class="w">MBOL</span>            <a class="l_k" href="functions/no.html">no</a>         <span class="w">Same</span><span class="cm">,</span> <span class="w">assuming</span> <span class="w">multiline</span><span class="co">:</span> <span class="q">/^/m</span></li><li></li><li> <span class="c"># Line End Anchors:</span></li><li> <span class="w">SEOL</span>            <a class="l_k" href="functions/no.html">no</a>         <span class="w">Match</span> <span class="q">&quot;&quot;</span> <span class="w">at</span> <span class="w">end</span> <span class="w">of</span> <span class="w">line</span><span class="co">:</span> <span class="q">/$/</span></li><li> <span class="w">MEOL</span>            <a class="l_k" href="functions/no.html">no</a>         <span class="w">Same</span><span class="cm">,</span> <span class="w">assuming</span> <span class="w">multiline</span><span class="co">:</span> <span class="q">/$/m</span></li><li> <span class="w">EOS</span>             <a class="l_k" href="functions/no.html">no</a>         <span class="w">Match</span> <span class="q">&quot;&quot;</span> <span class="w">at</span> <span class="w">end</span> <span class="w">of</span> <span class="w">string</span><span class="co">:</span> <span class="q">/\z/</span></li><li></li><li> <span class="c"># Match Start Anchors:</span></li><li> <span class="w">GPOS</span>            <a class="l_k" href="functions/no.html">no</a>         <span class="w">Matches</span> <span class="w">where</span> <a class="l_k" href="functions/last.html">last</a> <span class="q">m//g</span> <span class="w">left</span> <span class="w">off</span>.</li><li></li><li> <span class="c"># Word Boundary Opcodes:</span></li><li> <span class="w">BOUND</span>           <a class="l_k" href="functions/no.html">no</a>         <span class="w">Like</span> <span class="w">BOUNDA</span> <a class="l_k" href="functions/for.html">for</a> <span class="w">non</span>-<span class="w">utf8</span><span class="cm">,</span> <span class="w">otherwise</span> <span class="w">match</span> <span class="q">&quot;&quot;</span></li><li>                            <span class="w">between</span> <span class="w">any</span> <span class="w">Unicode</span> \<span class="w">w</span>\<span class="w">W</span> <a class="l_k" href="functions/or.html">or</a> \<span class="w">W</span>\<span class="w">w</span></li><li> <span class="w">BOUNDL</span>          <a class="l_k" href="functions/no.html">no</a>         <span class="w">Like</span> <span class="w">BOUND</span>/<span class="w">BOUNDU</span><span class="cm">,</span> <span class="w">but</span> \<span class="w">w</span> <a class="l_k" href="functions/and.html">and</a> \<span class="w">W</span> <span class="w">are</span> <a class="l_k" href="functions/defined.html">defined</a></li><li>                            <span class="w">by</span> <span class="w">current</span> <span class="w">locale</span></li><li> <span class="w">BOUNDU</span>          <a class="l_k" href="functions/no.html">no</a>         <span class="w">Match</span> <span class="q">&quot;&quot;</span> <span class="w">at</span> <span class="w">any</span> <span class="w">boundary</span> <span class="w">of</span> <span class="w">a</span> <a class="l_k" href="functions/given.html">given</a> <span class="w">type</span></li><li>                            <span class="w">using</span> <span class="w">Unicode</span> <span class="w">rules</span></li><li> <span class="w">BOUNDA</span>          <a class="l_k" href="functions/no.html">no</a>         <span class="w">Match</span> <span class="q">&quot;&quot;</span> <span class="w">at</span> <span class="w">any</span> <span class="w">boundary</span> <span class="w">between</span> \<span class="w">w</span>\<span class="w">W</span> <a class="l_k" href="functions/or.html">or</a></li><li>                            \<span class="w">W</span>\<span class="w">w</span><span class="cm">,</span> <span class="w">where</span> \<span class="w">w</span> <span class="w">is</span> <span class="s">[</span><span class="w">_a</span>-<span class="w">zA</span>-<span class="w">Z0</span>-<span class="n">9</span><span class="s">]</span></li><li> <span class="w">NBOUND</span>          <a class="l_k" href="functions/no.html">no</a>         <span class="w">Like</span> <span class="w">NBOUNDA</span> <a class="l_k" href="functions/for.html">for</a> <span class="w">non</span>-<span class="w">utf8</span><span class="cm">,</span> <span class="w">otherwise</span> <span class="w">match</span></li><li>                            <span class="q">&quot;&quot;</span> <span class="w">between</span> <span class="w">any</span> <span class="w">Unicode</span> \<span class="w">w</span>\<span class="w">w</span> <a class="l_k" href="functions/or.html">or</a> \<span class="w">W</span>\<span class="w">W</span></li><li> <span class="w">NBOUNDL</span>         <a class="l_k" href="functions/no.html">no</a>         <span class="w">Like</span> <span class="w">NBOUND</span>/<span class="w">NBOUNDU</span><span class="cm">,</span> <span class="w">but</span> \<span class="w">w</span> <a class="l_k" href="functions/and.html">and</a> \<span class="w">W</span> <span class="w">are</span></li><li>                            <a class="l_k" href="functions/defined.html">defined</a> <span class="w">by</span> <span class="w">current</span> <span class="w">locale</span></li><li> <span class="w">NBOUNDU</span>         <a class="l_k" href="functions/no.html">no</a>         <span class="w">Match</span> <span class="q">&quot;&quot;</span> <span class="w">at</span> <span class="w">any</span> <span class="w">non</span>-<span class="w">boundary</span> <span class="w">of</span> <span class="w">a</span> <a class="l_k" href="functions/given.html">given</a> <span class="w">type</span></li><li>                            <span class="w">using</span> <span class="w">using</span> <span class="w">Unicode</span> <span class="w">rules</span></li><li> <span class="w">NBOUNDA</span>         <a class="l_k" href="functions/no.html">no</a>         <span class="w">Match</span> <span class="q">&quot;&quot;</span> <span class="w">betweeen</span> <span class="w">any</span> \<span class="w">w</span>\<span class="w">w</span> <a class="l_k" href="functions/or.html">or</a> \<span class="w">W</span>\<span class="w">W</span><span class="cm">,</span> <span class="w">where</span> \<span class="w">w</span></li><li>                            <span class="w">is</span> <span class="s">[</span><span class="w">_a</span>-<span class="w">zA</span>-<span class="w">Z0</span>-<span class="n">9</span><span class="s">]</span></li><li></li><li> <span class="c"># [Special] alternatives:</span></li><li> <span class="w">REG_ANY</span>         <a class="l_k" href="functions/no.html">no</a>         <span class="w">Match</span> <span class="w">any</span> <span class="w">one</span> <span class="w">character</span> <span class="s">(</span><span class="w">except</span> <span class="w">newline</span><span class="s">)</span>.</li><li> <span class="w">SANY</span>            <a class="l_k" href="functions/no.html">no</a>         <span class="w">Match</span> <span class="w">any</span> <span class="w">one</span> <span class="w">character</span>.</li><li> <span class="w">ANYOF</span>           <span class="w">sv</span> <span class="n">1</span>       <span class="w">Match</span> <span class="w">character</span> <span class="w">in</span> <span class="s">(</span><a class="l_k" href="functions/or.html">or</a> <a class="l_k" href="functions/not.html">not</a> <span class="w">in</span><span class="s">)</span> <span class="w">this</span> <span class="w">class</span><span class="cm">,</span></li><li>                            <span class="w">single</span> <span class="w">char</span> <span class="w">match</span> <span class="w">only</span></li><li> <span class="w">ANYOFD</span>          <span class="w">sv</span> <span class="n">1</span>       <span class="w">Like</span> <span class="w">ANYOF</span><span class="cm">,</span> <span class="w">but</span> /<span class="w">d</span> <span class="w">is</span> <span class="w">in</span> <span class="w">effect</span></li><li> <span class="w">ANYOFL</span>          <span class="w">sv</span> <span class="n">1</span>       <span class="w">Like</span> <span class="w">ANYOF</span><span class="cm">,</span> <span class="w">but</span> /<span class="w">l</span> <span class="w">is</span> <span class="w">in</span> <span class="w">effect</span></li><li></li><li> <span class="c"># POSIX Character Classes:</span></li><li> <span class="w">POSIXD</span>          <span class="w">none</span>       <span class="w">Some</span> <span class="s">[</span><span class="s">[</span><span class="co">:</span><span class="w">class</span><span class="co">:</span><span class="s">]</span><span class="s">]</span> <span class="w">under</span> /<span class="w">d</span><span class="sc">;</span> <span class="w">the</span> <span class="w">FLAGS</span> <span class="w">field</span></li><li>                            <span class="w">gives</span> <span class="w">which</span> <span class="w">one</span></li><li> <span class="w">POSIXL</span>          <span class="w">none</span>       <span class="w">Some</span> <span class="s">[</span><span class="s">[</span><span class="co">:</span><span class="w">class</span><span class="co">:</span><span class="s">]</span><span class="s">]</span> <span class="w">under</span> /<span class="w">l</span><span class="sc">;</span> <span class="w">the</span> <span class="w">FLAGS</span> <span class="w">field</span></li><li>                            <span class="w">gives</span> <span class="w">which</span> <span class="w">one</span></li><li> <span class="w">POSIXU</span>          <span class="w">none</span>       <span class="w">Some</span> <span class="s">[</span><span class="s">[</span><span class="co">:</span><span class="w">class</span><span class="co">:</span><span class="s">]</span><span class="s">]</span> <span class="w">under</span> /<span class="w">u</span><span class="sc">;</span> <span class="w">the</span> <span class="w">FLAGS</span> <span class="w">field</span></li><li>                            <span class="w">gives</span> <span class="w">which</span> <span class="w">one</span></li><li> <span class="w">POSIXA</span>          <span class="w">none</span>       <span class="w">Some</span> <span class="s">[</span><span class="s">[</span><span class="co">:</span><span class="w">class</span><span class="co">:</span><span class="s">]</span><span class="s">]</span> <span class="w">under</span> /<span class="w">a</span><span class="sc">;</span> <span class="w">the</span> <span class="w">FLAGS</span> <span class="w">field</span></li><li>                            <span class="w">gives</span> <span class="w">which</span> <span class="w">one</span></li><li> <span class="w">NPOSIXD</span>         <span class="w">none</span>       <span class="w">complement</span> <span class="w">of</span> <span class="w">POSIXD</span><span class="cm">,</span> <span class="s">[</span><span class="s">[</span><span class="co">:</span>^<span class="w">class</span><span class="co">:</span><span class="s">]</span><span class="s">]</span></li><li> <span class="w">NPOSIXL</span>         <span class="w">none</span>       <span class="w">complement</span> <span class="w">of</span> <span class="w">POSIXL</span><span class="cm">,</span> <span class="s">[</span><span class="s">[</span><span class="co">:</span>^<span class="w">class</span><span class="co">:</span><span class="s">]</span><span class="s">]</span></li><li> <span class="w">NPOSIXU</span>         <span class="w">none</span>       <span class="w">complement</span> <span class="w">of</span> <span class="w">POSIXU</span><span class="cm">,</span> <span class="s">[</span><span class="s">[</span><span class="co">:</span>^<span class="w">class</span><span class="co">:</span><span class="s">]</span><span class="s">]</span></li><li> <span class="w">NPOSIXA</span>         <span class="w">none</span>       <span class="w">complement</span> <span class="w">of</span> <span class="w">POSIXA</span><span class="cm">,</span> <span class="s">[</span><span class="s">[</span><span class="co">:</span>^<span class="w">class</span><span class="co">:</span><span class="s">]</span><span class="s">]</span></li><li></li><li> <span class="w">CLUMP</span>           <a class="l_k" href="functions/no.html">no</a>         <span class="w">Match</span> <span class="w">any</span> <span class="w">extended</span> <span class="w">grapheme</span> <span class="w">cluster</span> <span class="w">sequence</span></li><li></li><li> <span class="c"># Alternation</span></li><li></li><li> <span class="c"># BRANCH        The set of branches constituting a single choice are</span></li><li> <span class="c">#               hooked together with their &quot;next&quot; pointers, since</span></li><li> <span class="c">#               precedence prevents anything being concatenated to</span></li><li> <span class="c">#               any individual branch.  The &quot;next&quot; pointer of the last</span></li><li> <span class="c">#               BRANCH in a choice points to the thing following the</span></li><li> <span class="c">#               whole choice.  This is also where the final &quot;next&quot;</span></li><li> <span class="c">#               pointer of each individual branch points; each branch</span></li><li> <span class="c">#               starts with the operand node of a BRANCH node.</span></li><li> <span class="c">#</span></li><li> <span class="w">BRANCH</span>          <span class="w">node</span>       <span class="w">Match</span> <span class="w">this</span> <span class="w">alternative</span><span class="cm">,</span> <a class="l_k" href="functions/or.html">or</a> <span class="w">the</span> <a class="l_k" href="functions/next.html">next</a>...</li><li></li><li> <span class="c"># Literals</span></li><li></li><li> <span class="w">EXACT</span>           <span class="w">str</span>        <span class="w">Match</span> <span class="w">this</span> <span class="w">string</span> <span class="s">(</span><span class="w">preceded</span> <span class="w">by</span> <a class="l_k" href="functions/length.html">length</a><span class="s">)</span>.</li><li> <span class="w">EXACTL</span>          <span class="w">str</span>        <span class="w">Like</span> <span class="w">EXACT</span><span class="cm">,</span> <span class="w">but</span> /<span class="w">l</span> <span class="w">is</span> <span class="w">in</span> <span class="w">effect</span> <span class="s">(</span><span class="w">used</span> <span class="w">so</span></li><li>                            <span class="w">locale</span>-<span class="w">related</span> <span class="w">warnings</span> <span class="w">can</span> <span class="w">be</span> <span class="w">checked</span> <a class="l_k" href="functions/for.html">for</a><span class="s">)</span>.</li><li> <span class="w">EXACTF</span>          <span class="w">str</span>        <span class="w">Match</span> <span class="w">this</span> <span class="w">non</span>-<span class="w">UTF</span>-<span class="n">8</span> <span class="w">string</span> <span class="s">(</span><a class="l_k" href="functions/not.html">not</a> <span class="w">guaranteed</span></li><li>                            <span class="w">to</span> <span class="w">be</span> <span class="w">folded</span><span class="s">)</span> <span class="w">using</span> /<span class="w">id</span> <span class="w">rules</span> <span class="s">(</span><span class="w">w</span>/<span class="w">len</span><span class="s">)</span>.</li><li> <span class="w">EXACTFL</span>         <span class="w">str</span>        <span class="w">Match</span> <span class="w">this</span> <span class="w">string</span> <span class="s">(</span><a class="l_k" href="functions/not.html">not</a> <span class="w">guaranteed</span> <span class="w">to</span> <span class="w">be</span></li><li>                            <span class="w">folded</span><span class="s">)</span> <span class="w">using</span> /<span class="w">il</span> <span class="w">rules</span> <span class="s">(</span><span class="w">w</span>/<span class="w">len</span><span class="s">)</span>.</li><li> <span class="w">EXACTFU</span>         <span class="w">str</span>        <span class="w">Match</span> <span class="w">this</span> <span class="w">string</span> <span class="s">(</span><span class="w">folded</span> <span class="w">iff</span> <span class="w">in</span> <span class="w">UTF</span>-<span class="n">8</span><span class="cm">,</span></li><li>                            <a class="l_k" href="functions/length.html">length</a> <span class="w">in</span> <span class="w">folding</span> <span class="w">doesn&#39;t</span> <span class="w">change</span> <a class="l_k" href="functions/if.html">if</a> <a class="l_k" href="functions/not.html">not</a> <span class="w">in</span></li><li>                            <span class="w">UTF</span>-<span class="n">8</span><span class="s">)</span> <span class="w">using</span> /<span class="w">iu</span> <span class="w">rules</span> <span class="s">(</span><span class="w">w</span>/<span class="w">len</span><span class="s">)</span>.</li><li> <span class="w">EXACTFA</span>         <span class="w">str</span>        <span class="w">Match</span> <span class="w">this</span> <span class="w">string</span> <span class="s">(</span><a class="l_k" href="functions/not.html">not</a> <span class="w">guaranteed</span> <span class="w">to</span> <span class="w">be</span></li><li>                            <span class="w">folded</span><span class="s">)</span> <span class="w">using</span> /<span class="w">iaa</span> <span class="w">rules</span> <span class="s">(</span><span class="w">w</span>/<span class="w">len</span><span class="s">)</span>.</li><li></li><li> <span class="w">EXACTFU_SS</span>      <span class="w">str</span>        <span class="w">Match</span> <span class="w">this</span> <span class="w">string</span> <span class="s">(</span><span class="w">folded</span> <span class="w">iff</span> <span class="w">in</span> <span class="w">UTF</span>-<span class="n">8</span><span class="cm">,</span></li><li>                            <a class="l_k" href="functions/length.html">length</a> <span class="w">in</span> <span class="w">folding</span> <span class="w">may</span> <span class="w">change</span> <span class="w">even</span> <a class="l_k" href="functions/if.html">if</a> <a class="l_k" href="functions/not.html">not</a> <span class="w">in</span></li><li>                            <span class="w">UTF</span>-<span class="n">8</span><span class="s">)</span> <span class="w">using</span> /<span class="w">iu</span> <span class="w">rules</span> <span class="s">(</span><span class="w">w</span>/<span class="w">len</span><span class="s">)</span>.</li><li> <span class="w">EXACTFLU8</span>       <span class="w">str</span>        <span class="w">Rare</span> <span class="w">cirucmstances</span><span class="co">:</span> <span class="w">like</span> <span class="w">EXACTFU</span><span class="cm">,</span> <span class="w">but</span> <span class="w">is</span></li><li>                            <span class="w">under</span> /<span class="w">l</span><span class="cm">,</span> <span class="w">UTF</span>-<span class="n">8</span><span class="cm">,</span> <span class="w">folded</span><span class="cm">,</span> <a class="l_k" href="functions/and.html">and</a> <span class="w">everything</span> <span class="w">in</span></li><li>                            <span class="w">it</span> <span class="w">is</span> <span class="w">above</span> <span class="n">255.</span></li><li> <span class="w">EXACTFA_NO_TRIE</span> <span class="w">str</span>        <span class="w">Match</span> <span class="w">this</span> <span class="w">string</span> <span class="s">(</span><span class="w">which</span> <span class="w">is</span> <a class="l_k" href="functions/not.html">not</a> <span class="w">trie</span>-<span class="w">able</span><span class="sc">;</span></li><li>                            <a class="l_k" href="functions/not.html">not</a> <span class="w">guaranteed</span> <span class="w">to</span> <span class="w">be</span> <span class="w">folded</span><span class="s">)</span> <span class="w">using</span> /<span class="w">iaa</span></li><li>                            <span class="w">rules</span> <span class="s">(</span><span class="w">w</span>/<span class="w">len</span><span class="s">)</span>.</li><li></li><li> <span class="c"># Do nothing types</span></li><li></li><li> <span class="w">NOTHING</span>         <a class="l_k" href="functions/no.html">no</a>         <span class="w">Match</span> <span class="w">empty</span> <span class="w">string</span>.</li><li> <span class="c"># A variant of above which delimits a group, thus stops optimizations</span></li><li> <span class="w">TAIL</span>            <a class="l_k" href="functions/no.html">no</a>         <span class="w">Match</span> <span class="w">empty</span> <span class="w">string</span>. <span class="w">Can</span> <span class="w">jump</span> <span class="w">here</span> <span class="w">from</span></li><li>                            <span class="w">outside</span>.</li><li></li><li> <span class="c"># Loops</span></li><li></li><li> <span class="c"># STAR,PLUS    &#39;?&#39;, and complex &#39;*&#39; and &#39;+&#39;, are implemented as</span></li><li> <span class="c">#               circular BRANCH structures.  Simple cases</span></li><li> <span class="c">#               (one character per match) are implemented with STAR</span></li><li> <span class="c">#               and PLUS for speed and to minimize recursive plunges.</span></li><li> <span class="c">#</span></li><li> <span class="w">STAR</span>            <span class="w">node</span>       <span class="w">Match</span> <span class="w">this</span> <span class="s">(</span><span class="w">simple</span><span class="s">)</span> <span class="w">thing</span> <span class="n">0</span> <a class="l_k" href="functions/or.html">or</a> <span class="w">more</span> <a class="l_k" href="functions/times.html">times</a>.</li><li> <span class="w">PLUS</span>            <span class="w">node</span>       <span class="w">Match</span> <span class="w">this</span> <span class="s">(</span><span class="w">simple</span><span class="s">)</span> <span class="w">thing</span> <span class="n">1</span> <a class="l_k" href="functions/or.html">or</a> <span class="w">more</span> <a class="l_k" href="functions/times.html">times</a>.</li><li></li><li> <span class="w">CURLY</span>           <span class="w">sv</span> <span class="n">2</span>       <span class="w">Match</span> <span class="w">this</span> <span class="w">simple</span> <span class="w">thing</span> <span class="s">{</span><span class="w">n</span><span class="cm">,</span><span class="q">m} times.</span></li><li> <span class="q"> CURLYN          no 2       Capture next-after-this simple thing</span></li><li> <span class="q"> CURLYM          no 2       Capture this medium-complex thing {n,m}</span></li><li>                            <a class="l_k" href="functions/times.html">times</a>.</li><li> <span class="w">CURLYX</span>          <span class="w">sv</span> <span class="n">2</span>       <span class="w">Match</span> <span class="w">this</span> <span class="w">complex</span> <span class="w">thing</span> <span class="s">{</span><span class="w">n</span><span class="cm">,</span><span class="q">m} times.</span></li><li></li><li> <span class="q"> # This terminator creates a loop structure for CURLYX</span></li><li> <span class="q"> WHILEM          no         Do curly processing and see if rest matches.</span></li><li></li><li> <span class="q"> # Buffer related</span></li><li></li><li> <span class="q"> # OPEN,CLOSE,GROUPP     ...are numbered at compile time.</span></li><li> <span class="q"> OPEN            num 1      Mark this point in input as start of #n.</span></li><li> <span class="q"> CLOSE           num 1      Analogous to OPEN.</span></li><li></li><li> <span class="q"> REF             num 1      Match some already matched string</span></li><li> <span class="q"> REFF            num 1      Match already matched string, folded using</span></li><li>                            <span class="q">                            native charset rules for non-utf8</span></li><li> <span class="q"> REFFL           num 1      Match already matched string, folded in loc.</span></li><li> <span class="q"> REFFU           num 1      Match already matched string, folded using</span></li><li>                            <span class="q">                            unicode rules for non-utf8</span></li><li> <span class="q"> REFFA           num 1      Match already matched string, folded using</span></li><li>                            <span class="q">                            unicode rules for non-utf8, no mixing ASCII,</span></li><li>                            <span class="q">                            non-ASCII</span></li><li></li><li> <span class="q"> # Named references.  Code in regcomp.c assumes that these all are after</span></li><li> <span class="q"> # the numbered references</span></li><li> <span class="q"> NREF            no-sv 1    Match some already matched string</span></li><li> <span class="q"> NREFF           no-sv 1    Match already matched string, folded using</span></li><li>                            <span class="q">                            native charset rules for non-utf8</span></li><li> <span class="q"> NREFFL          no-sv 1    Match already matched string, folded in loc.</span></li><li> <span class="q"> NREFFU          num 1      Match already matched string, folded using</span></li><li>                            <span class="q">                            unicode rules for non-utf8</span></li><li> <span class="q"> NREFFA          num 1      Match already matched string, folded using</span></li><li>                            <span class="q">                            unicode rules for non-utf8, no mixing ASCII,</span></li><li>                            <span class="q">                            non-ASCII</span></li><li></li><li> <span class="q"> # Support for long RE</span></li><li> <span class="q"> LONGJMP         off 1 1    Jump far away.</span></li><li> <span class="q"> BRANCHJ         off 1 1    BRANCH with long offset.</span></li><li></li><li> <span class="q"> # Special Case Regops</span></li><li> <span class="q"> IFMATCH         off 1 2    Succeeds if the following matches.</span></li><li> <span class="q"> UNLESSM         off 1 2    Fails if the following matches.</span></li><li> <span class="q"> SUSPEND         off 1 1    &quot;Independent&quot; sub-RE.</span></li><li> <span class="q"> IFTHEN          off 1 1    Switch, should be preceded by switcher.</span></li><li> <span class="q"> GROUPP          num 1      Whether the group matched.</span></li><li></li><li> <span class="q"> # The heavy worker</span></li><li></li><li> <span class="q"> EVAL            evl/flags  Execute some Perl code.</span></li><li>                 <span class="q">                 2L</span></li><li></li><li> <span class="q"> # Modifiers</span></li><li></li><li> <span class="q"> MINMOD          no         Next operator is not greedy.</span></li><li> <span class="q"> LOGICAL         no         Next opcode should set the flag only.</span></li><li></li><li> <span class="q"> # This is not used yet</span></li><li> <span class="q"> RENUM           off 1 1    Group with independently numbered parens.</span></li><li></li><li> <span class="q"> # Trie Related</span></li><li></li><li> <span class="q"> # Behave the same as A|LIST|OF|WORDS would. The &#39;..C&#39; variants</span></li><li> <span class="q"> # have inline charclass data (ascii only), the &#39;C&#39; store it in the</span></li><li> <span class="q"> # structure.</span></li><li></li><li> <span class="q"> TRIE            trie 1     Match many EXACT(F[ALU]?)? at once.</span></li><li>                            <span class="q">                            flags==type</span></li><li> <span class="q"> TRIEC           trie       Same as TRIE, but with embedded charclass</span></li><li>                 <span class="q">                 charclass  data</span></li><li></li><li> <span class="q"> AHOCORASICK     trie 1     Aho Corasick stclass. flags==type</span></li><li> <span class="q"> AHOCORASICKC    trie       Same as AHOCORASICK, but with embedded</span></li><li>                 <span class="q">                 charclass  charclass data</span></li><li></li><li> <span class="q"> # Regex Subroutines</span></li><li> <span class="q"> GOSUB           num/ofs 2L recurse to paren arg1 at (signed) ofs arg2</span></li><li></li><li> <span class="q"> # Special conditionals</span></li><li> <span class="q"> NGROUPP         no-sv 1    Whether the group matched.</span></li><li> <span class="q"> INSUBP          num 1      Whether we are in a specific recurse.</span></li><li> <span class="q"> DEFINEP         none 1     Never execute directly.</span></li><li></li><li> <span class="q"> # Backtracking Verbs</span></li><li> <span class="q"> ENDLIKE         none       Used only for the type field of verbs</span></li><li> <span class="q"> OPFAIL          no-sv 1    Same as (?!), but with verb arg</span></li><li> <span class="q"> ACCEPT          no-sv/num  Accepts the current matched string, with</span></li><li>                 <span class="q">                 2L         verbar</span></li><li></li><li> <span class="q"> # Verbs With Arguments</span></li><li> <span class="q"> VERB            no-sv 1    Used only for the type field of verbs</span></li><li> <span class="q"> PRUNE           no-sv 1    Pattern fails at this startpoint if no-</span></li><li>                            <span class="q">                            backtracking through this</span></li><li> <span class="q"> MARKPOINT       no-sv 1    Push the current location for rollback by</span></li><li>                            <span class="q">                            cut.</span></li><li> <span class="q"> SKIP            no-sv 1    On failure skip forward (to the mark) before</span></li><li>                            <span class="q">                            retrying</span></li><li> <span class="q"> COMMIT          no-sv 1    Pattern fails outright if backtracking</span></li><li>                            <span class="q">                            through this</span></li><li> <span class="q"> CUTGROUP        no-sv 1    On failure go to the next alternation in the</span></li><li>                            <span class="q">                            group</span></li><li></li><li> <span class="q"> # Control what to keep in $&amp;.</span></li><li> <span class="q"> KEEPS           no         $&amp; begins here.</span></li><li></li><li> <span class="q"> # New charclass like patterns</span></li><li> <span class="q"> LNBREAK         none       generic newline pattern</span></li><li></li><li> <span class="q"> # SPECIAL  REGOPS</span></li><li></li><li> <span class="q"> # This is not really a node, but an optimized away piece of a &quot;long&quot;</span></li><li> <span class="q"> # node.  To simplify debugging output, we mark it as if it were a node</span></li><li> <span class="q"> OPTIMIZED       off        Placeholder for dump.</span></li><li></li><li> <span class="q"> # Special opcode with the property that no opcode in a compiled program</span></li><li> <span class="q"> # will ever be of this type. Thus it can be used as a flag value that</span></li><li> <span class="q"> # no other opcode has been seen. END is used similarly, in that an END</span></li><li> <span class="q"> # node cant be optimized. So END implies &quot;unoptimizable&quot; and PSEUDO</span></li><li> <span class="q"> # mean &quot;not seen anything to optimize yet&quot;.</span></li><li> <span class="q"> PSEUDO          off        Pseudo opcode for internal use.</span></li></ol></pre><p>Following the optimizer information is a dump of the offset/length
table, here split across several lines:</p>
<pre class="verbatim"><ol><li>  <span class="j">Offsets:</span> <span class="s">[</span><span class="n">45</span><span class="s">]</span></li><li>  	<span class="n">1</span><span class="s">[</span><span class="n">4</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">5</span><span class="s">[</span><span class="n">1</span><span class="s">]</span></li><li>  	<span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">12</span><span class="s">[</span><span class="n">1</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">6</span><span class="s">[</span><span class="n">1</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">7</span><span class="s">[</span><span class="n">1</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">9</span><span class="s">[</span><span class="n">1</span><span class="s">]</span> <span class="n">8</span><span class="s">[</span><span class="n">1</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">10</span><span class="s">[</span><span class="n">1</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span></li><li>  	<span class="n">11</span><span class="s">[</span><span class="n">1</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">12</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">12</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">13</span><span class="s">[</span><span class="n">1</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">14</span><span class="s">[</span><span class="n">4</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span></li><li>  	<span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">18</span><span class="s">[</span><span class="n">1</span><span class="s">]</span> <span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span> <span class="n">19</span><span class="s">[</span><span class="n">1</span><span class="s">]</span> <span class="n">20</span><span class="s">[</span><span class="n">0</span><span class="s">]</span></li></ol></pre><p>The first line here indicates that the offset/length table contains 45
entries.  Each entry is a pair of integers, denoted by <code class="inline"><span class="w">offset</span><span class="s">[</span><a class="l_k" href="functions/length.html">length</a><span class="s">]</span></code>
.
Entries are numbered starting with 1, so entry #1 here is <code class="inline"><span class="n">1</span><span class="s">[</span><span class="n">4</span><span class="s">]</span></code>
 and
entry #12 is <code class="inline"><span class="n">5</span><span class="s">[</span><span class="n">1</span><span class="s">]</span></code>
.  <code class="inline"><span class="n">1</span><span class="s">[</span><span class="n">4</span><span class="s">]</span></code>
 indicates that the node labeled <code class="inline">1:</code>
(the <code class="inline">1: ANYOF[bc]</code>) begins at character position 1 in the
pre-compiled form of the regex, and has a length of 4 characters.
<code class="inline"><span class="n">5</span><span class="s">[</span><span class="n">1</span><span class="s">]</span></code>
 in position 12 
indicates that the node labeled <code class="inline">12:</code>
(the <code class="inline">12: EXACT &lt;d&gt;</code>) begins at character position 5 in the
pre-compiled form of the regex, and has a length of 1 character.
<code class="inline"><span class="n">12</span><span class="s">[</span><span class="n">1</span><span class="s">]</span></code>
 in position 14 
indicates that the node labeled <code class="inline">14:</code>
(the <code class="inline">14: CURLYX[0] {1,32767}</code>) begins at character position 12 in the
pre-compiled form of the regex, and has a length of 1 character---that
is, it corresponds to the <code class="inline">+</code>
 symbol in the precompiled regex.</p>
<p><code class="inline"><span class="n">0</span><span class="s">[</span><span class="n">0</span><span class="s">]</span></code>
 items indicate that there is no corresponding node.</p>
<a name="Run-time-Output"></a><h2>Run-time Output</h2>
<p>First of all, when doing a match, one may get no run-time output even
if debugging is enabled.  This means that the regex engine was never
entered and that all of the job was therefore done by the optimizer.</p>
<p>If the regex engine was entered, the output may look like this:</p>
<pre class="verbatim"><ol><li>  <span class="w">Matching</span> <span class="q">&#39;[bc]d(ef*g)+h[ij]k$&#39;</span> <span class="w">against</span> <span class="q">&#39;abcdefg__gh__&#39;</span></li><li>    <span class="w">Setting</span> <span class="w">an</span> <span class="w">EVAL</span> <span class="w">scope</span><span class="cm">,</span> <span class="w">savestack</span>=<span class="n">3</span></li><li>     <span class="n">2</span> &lt;<span class="w">ab</span>&gt; <span class="q">&lt;cdefg__gh_&gt;</span>    |  <span class="n">1</span><span class="co">:</span> <span class="w">ANYOF</span></li><li>     <span class="n">3</span> &lt;<span class="w">abc</span>&gt; <span class="q">&lt;defg__gh_&gt;</span>    | <span class="n">11</span><span class="co">:</span> <span class="w">EXACT</span> <span class="q">&lt;d&gt;</span></li><li>     <span class="n">4</span> &lt;<span class="w">abcd</span>&gt; <span class="q">&lt;efg__gh_&gt;</span>    | <span class="n">13</span><span class="co">:</span> <span class="w">CURLYX</span> <span class="s">{</span><span class="n">1</span><span class="cm">,</span><span class="n">32767</span><span class="s">}</span></li><li>     <span class="n">4</span> &lt;<span class="w">abcd</span>&gt; <span class="q">&lt;efg__gh_&gt;</span>    | <span class="n">26</span><span class="co">:</span>   <span class="w">WHILEM</span></li><li>				<span class="n">0</span> <span class="w">out</span> <span class="w">of</span> <span class="n">1</span>..<span class="n">32767</span>  <span class="w">cc</span>=<span class="w">effff31c</span></li><li>     <span class="n">4</span> &lt;<span class="w">abcd</span>&gt; <span class="q">&lt;efg__gh_&gt;</span>    | <span class="n">15</span><span class="co">:</span>     <span class="w">OPEN1</span></li><li>     <span class="n">4</span> &lt;<span class="w">abcd</span>&gt; <span class="q">&lt;efg__gh_&gt;</span>    | <span class="n">17</span><span class="co">:</span>     <span class="w">EXACT</span> <span class="q">&lt;e&gt;</span></li><li>     <span class="n">5</span> &lt;<span class="w">abcde</span>&gt; <span class="q">&lt;fg__gh_&gt;</span>    | <span class="n">19</span><span class="co">:</span>     <span class="w">STAR</span></li><li>			     <span class="w">EXACT</span> <span class="q">&lt;f&gt;</span> <span class="w">can</span> <span class="w">match</span> <span class="n">1</span> <a class="l_k" href="functions/times.html">times</a> <span class="w">out</span> <span class="w">of</span> <span class="n">32767</span>...</li><li>    <span class="w">Setting</span> <span class="w">an</span> <span class="w">EVAL</span> <span class="w">scope</span><span class="cm">,</span> <span class="w">savestack</span>=<span class="n">3</span></li><li>     <span class="n">6</span> &lt;<span class="w">bcdef</span>&gt; <span class="q">&lt;g__gh__&gt;</span>    | <span class="n">22</span><span class="co">:</span>       <span class="w">EXACT</span> <span class="q">&lt;g&gt;</span></li><li>     <span class="n">7</span> &lt;<span class="w">bcdefg</span>&gt; <span class="q">&lt;__gh__&gt;</span>    | <span class="n">24</span><span class="co">:</span>       <span class="w">CLOSE1</span></li><li>     <span class="n">7</span> &lt;<span class="w">bcdefg</span>&gt; <span class="q">&lt;__gh__&gt;</span>    | <span class="n">26</span><span class="co">:</span>       <span class="w">WHILEM</span></li><li>				    <span class="n">1</span> <span class="w">out</span> <span class="w">of</span> <span class="n">1</span>..<span class="n">32767</span>  <span class="w">cc</span>=<span class="w">effff31c</span></li><li>    <span class="w">Setting</span> <span class="w">an</span> <span class="w">EVAL</span> <span class="w">scope</span><span class="cm">,</span> <span class="w">savestack</span>=<span class="n">12</span></li><li>     <span class="n">7</span> &lt;<span class="w">bcdefg</span>&gt; <span class="q">&lt;__gh__&gt;</span>    | <span class="n">15</span><span class="co">:</span>         <span class="w">OPEN1</span></li><li>     <span class="n">7</span> &lt;<span class="w">bcdefg</span>&gt; <span class="q">&lt;__gh__&gt;</span>    | <span class="n">17</span><span class="co">:</span>         <span class="w">EXACT</span> <span class="q">&lt;e&gt;</span></li><li>       <span class="w">restoring</span> \<span class="n">1</span> <span class="w">to</span> <span class="n">4</span><span class="s">(</span><span class="n">4</span><span class="s">)</span>..<span class="n">7</span></li><li>				    <span class="w">failed</span><span class="cm">,</span> <span class="w">try</span> <span class="w">continuation</span>...</li><li>     <span class="n">7</span> &lt;<span class="w">bcdefg</span>&gt; <span class="q">&lt;__gh__&gt;</span>    | <span class="n">27</span><span class="co">:</span>         <span class="w">NOTHING</span></li><li>     <span class="n">7</span> &lt;<span class="w">bcdefg</span>&gt; <span class="q">&lt;__gh__&gt;</span>    | <span class="n">28</span><span class="co">:</span>         <span class="w">EXACT</span> <span class="q">&lt;h&gt;</span></li><li>				    <span class="w">failed</span>...</li><li>				<span class="w">failed</span>...</li></ol></pre><p>The most significant information in the output is about the particular <i>node</i>
of the compiled regex that is currently being tested against the target string.
The format of these lines is</p>
<p><code class="inline">    </code>
<i>STRING-OFFSET</i> &lt;<i>PRE-STRING</i>&gt; &lt;<i>POST-STRING</i>&gt;   |<i>ID</i>:  <i>TYPE</i></p>
<p>The <i>TYPE</i> info is indented with respect to the backtracking level.
Other incidental information appears interspersed within.</p>
<a name="Debugging-Perl-Memory-Usage"></a><h1>Debugging Perl Memory Usage</h1>
<p>Perl is a profligate wastrel when it comes to memory use.  There
is a saying that to estimate memory usage of Perl, assume a reasonable
algorithm for memory allocation, multiply that estimate by 10, and
while you still may miss the mark, at least you won't be quite so
astonished.  This is not absolutely true, but may provide a good
grasp of what happens.</p>
<p>Assume that an integer cannot take less than 20 bytes of memory, a
float cannot take less than 24 bytes, a string cannot take less
than 32 bytes (all these examples assume 32-bit architectures, the
result are quite a bit worse on 64-bit architectures).  If a variable
is accessed in two of three different ways (which require an integer,
a float, or a string), the memory footprint may increase yet another
20 bytes.  A sloppy malloc(3) implementation can inflate these
numbers dramatically.</p>
<p>On the opposite end of the scale, a declaration like</p>
<pre class="verbatim"><ol><li>  sub <span class="m">foo</span><span class="sc">;</span></li></ol></pre><p>may take up to 500 bytes of memory, depending on which release of Perl
you're running.</p>
<p>Anecdotal estimates of source-to-compiled code bloat suggest an
eightfold increase.  This means that the compiled form of reasonable
(normally commented, properly indented etc.) code will take
about eight times more space in memory than the code took
on disk.</p>
<p>The <b>-DL</b> command-line switch is obsolete since circa Perl 5.6.0
(it was available only if Perl was built with <code class="inline">-<span class="w">DDEBUGGING</span></code>
).
The switch was used to track Perl's memory allocations and possible
memory leaks.  These days the use of malloc debugging tools like
<i>Purify</i> or <i>valgrind</i> is suggested instead.  See also
<a href="perlhacktips.html#PERL_MEM_LOG">PERL_MEM_LOG in perlhacktips</a>.</p>
<p>One way to find out how much memory is being used by Perl data
structures is to install the Devel::Size module from CPAN: it gives
you the minimum number of bytes required to store a particular data
structure.  Please be mindful of the difference between the size()
and total_size().</p>
<p>If Perl has been compiled using Perl's malloc you can analyze Perl
memory usage by setting $ENV{PERL_DEBUG_MSTATS}.</p>
<a name="Using-%24ENV%7bPERL_DEBUG_MSTATS%7d"></a><h2>Using <code class="inline"><span class="i">$ENV</span>{<span class="w">PERL_DEBUG_MSTATS</span>}</code>
</h2>
<p>If your perl is using Perl's malloc() and was compiled with the
necessary switches (this is the default), then it will print memory
usage statistics after compiling your code when <code class="inline"><span class="i">$ENV</span>{<span class="w">PERL_DEBUG_MSTATS</span>}
&gt; <span class="n">1</span></code>
, and before termination of the program when <code class="inline"><span class="i">$ENV</span>{<span class="w">PERL_DEBUG_MSTATS</span>} &gt;= <span class="n">1</span></code>
.  The report format is similar to
the following example:</p>
<pre class="verbatim"><ol><li> <span class="i">$ PERL_DEBUG_MSTATS</span>=<span class="n">2</span> <span class="w">perl</span> -e <span class="q">&quot;require Carp&quot;</span></li><li> <span class="w">Memory</span> <span class="w">allocation</span> <span class="w">statistics</span> <span class="w">after</span> <span class="w">compilation</span><span class="co">:</span> <span class="s">(</span><span class="w">buckets</span> <span class="n">4</span><span class="s">(</span><span class="n">4</span><span class="s">)</span>..<span class="n">8188</span><span class="s">(</span><span class="n">8192</span><span class="s">)</span></li><li>    <span class="n">14216</span> <span class="w">free</span><span class="co">:</span>   <span class="n">130</span>   <span class="n">117</span>    <span class="n">28</span>     <span class="n">7</span>     <span class="n">9</span>   <span class="n">0</span>   <span class="n">2</span>     <span class="n">2</span>   <span class="n">1</span> <span class="n">0</span> <span class="n">0</span></li><li>		<span class="n">437</span>    <span class="n">61</span>    <span class="n">36</span>     <span class="n">0</span>     <span class="n">5</span></li><li>    <span class="n">60924</span> <span class="w">used</span><span class="co">:</span>   <span class="n">125</span>   <span class="n">137</span>   <span class="n">161</span>    <span class="n">55</span>     <span class="n">7</span>   <span class="n">8</span>   <span class="n">6</span>    <span class="n">16</span>   <span class="n">2</span> <span class="n">0</span> <span class="n">1</span></li><li>		 <span class="n">74</span>   <span class="n">109</span>   <span class="n">304</span>    <span class="n">84</span>    <span class="n">20</span></li><li> <span class="w">Total</span> <span class="i">sbrk</span><span class="s">(</span><span class="s">)</span><span class="co">:</span> <span class="n">77824</span>/<span class="n">21</span><span class="co">:</span><span class="n">119.</span> <span class="w">Odd</span> <span class="w">ends</span><span class="co">:</span> <span class="w">pad</span>+<span class="w">heads</span>+<span class="w">chain</span>+<span class="w">tail</span><span class="co">:</span> <span class="n">0</span>+<span class="n">636</span>+<span class="n">0</span>+<span class="n">2048.</span></li><li> <span class="w">Memory</span> <span class="w">allocation</span> <span class="w">statistics</span> <span class="w">after</span> <span class="w">execution</span><span class="co">:</span>   <span class="s">(</span><span class="w">buckets</span> <span class="n">4</span><span class="s">(</span><span class="n">4</span><span class="s">)</span>..<span class="n">8188</span><span class="s">(</span><span class="n">8192</span><span class="s">)</span></li><li>    <span class="n">30888</span> <span class="w">free</span><span class="co">:</span>   <span class="n">245</span>    <span class="n">78</span>    <span class="n">85</span>    <span class="n">13</span>     <span class="n">6</span>   <span class="n">2</span>   <span class="n">1</span>     <span class="n">3</span>   <span class="n">2</span> <span class="n">0</span> <span class="n">1</span></li><li>		<span class="n">315</span>   <span class="n">162</span>    <span class="n">39</span>    <span class="n">42</span>    <span class="n">11</span></li><li>   <span class="n">175816</span> <span class="w">used</span><span class="co">:</span>   <span class="n">265</span>   <span class="n">176</span>  <span class="n">1112</span>   <span class="n">111</span>    <span class="n">26</span>  <span class="n">22</span>  <span class="n">11</span>    <span class="n">27</span>   <span class="n">2</span> <span class="n">1</span> <span class="n">1</span></li><li>		<span class="n">196</span>   <span class="n">178</span>  <span class="n">1066</span>   <span class="n">798</span>    <span class="n">39</span></li><li> <span class="w">Total</span> <span class="i">sbrk</span><span class="s">(</span><span class="s">)</span><span class="co">:</span> <span class="n">215040</span>/<span class="n">47</span><span class="co">:</span><span class="n">145.</span> <span class="w">Odd</span> <span class="w">ends</span><span class="co">:</span> <span class="w">pad</span>+<span class="w">heads</span>+<span class="w">chain</span>+<span class="w">tail</span><span class="co">:</span> <span class="n">0</span>+<span class="n">2192</span>+<span class="n">0</span>+<span class="n">6144.</span></li></ol></pre><p>It is possible to ask for such a statistic at arbitrary points in
your execution using the mstat() function out of the standard
Devel::Peek module.</p>
<p>Here is some explanation of that format:</p>
<ul>
<li><a name="buckets-SMALLEST(APPROX)..GREATEST(APPROX)"></a><b><code class="inline"><span class="w">buckets</span> <span class="i">SMALLEST</span><span class="s">(</span><span class="w">APPROX</span><span class="s">)</span>..<span class="i">GREATEST</span><span class="s">(</span><span class="w">APPROX</span><span class="s">)</span></code>
</b>
<p>Perl's malloc() uses bucketed allocations.  Every request is rounded
up to the closest bucket size available, and a bucket is taken from
the pool of buckets of that size.</p>
<p>The line above describes the limits of buckets currently in use.
Each bucket has two sizes: memory footprint and the maximal size
of user data that can fit into this bucket.  Suppose in the above
example that the smallest bucket were size 4.  The biggest bucket
would have usable size 8188, and the memory footprint would be 8192.</p>
<p>In a Perl built for debugging, some buckets may have negative usable
size.  This means that these buckets cannot (and will not) be used.
For larger buckets, the memory footprint may be one page greater
than a power of 2.  If so, the corresponding power of two is
printed in the <code class="inline"><span class="w">APPROX</span></code>
 field above.</p>
</li>
<li><a name="Free%2fUsed"></a><b>Free/Used</b>
<p>The 1 or 2 rows of numbers following that correspond to the number
of buckets of each size between <code class="inline"><span class="w">SMALLEST</span></code>
 and <code class="inline"><span class="w">GREATEST</span></code>
.  In
the first row, the sizes (memory footprints) of buckets are powers
of two--or possibly one page greater.  In the second row, if present,
the memory footprints of the buckets are between the memory footprints
of two buckets "above".</p>
<p>For example, suppose under the previous example, the memory footprints
were</p>
<pre class="verbatim"><ol><li>   <span class="j">free:</span>    <span class="n">8</span>     <span class="n">16</span>    <span class="n">32</span>    <span class="n">64</span>    <span class="n">128</span>  <span class="n">256</span> <span class="n">512</span> <span class="n">1024</span> <span class="n">2048</span> <span class="n">4096</span> <span class="n">8192</span></li><li>	   <span class="n">4</span>     <span class="n">12</span>    <span class="n">24</span>    <span class="n">48</span>    <span class="n">80</span></li></ol></pre><p>With a non-<code class="inline"><span class="w">DEBUGGING</span></code>
 perl, the buckets starting from <code class="inline"><span class="n">128</span></code>
 have
a 4-byte overhead, and thus an 8192-long bucket may take up to
8188-byte allocations.</p>
</li>
<li><a name="Total-sbrk()%3a-SBRKed%2fSBRKs%3aCONTINUOUS"></a><b><code class="inline">Total sbrk(): SBRKed/SBRKs:CONTINUOUS</code></b>
<p>The first two fields give the total amount of memory perl sbrk(2)ed
(ess-broken? :-) and number of sbrk(2)s used.  The third number is
what perl thinks about continuity of returned chunks.  So long as
this number is positive, malloc() will assume that it is probable
that sbrk(2) will provide continuous memory.</p>
<p>Memory allocated by external libraries is not counted.</p>
</li>
<li><a name="pad%3a-0"></a><b><code class="inline"><span class="j">pad:</span> <span class="n">0</span></code>
</b>
<p>The amount of sbrk(2)ed memory needed to keep buckets aligned.</p>
</li>
<li><a name="heads%3a-2192"></a><b><code class="inline"><span class="j">heads:</span> <span class="n">2192</span></code>
</b>
<p>Although memory overhead of bigger buckets is kept inside the bucket, for
smaller buckets, it is kept in separate areas.  This field gives the
total size of these areas.</p>
</li>
<li><a name="chain%3a-0"></a><b><code class="inline"><span class="j">chain:</span> <span class="n">0</span></code>
</b>
<p>malloc() may want to subdivide a bigger bucket into smaller buckets.
If only a part of the deceased bucket is left unsubdivided, the rest
is kept as an element of a linked list.  This field gives the total
size of these chunks.</p>
</li>
<li><a name="tail%3a-6144"></a><b><code class="inline"><span class="j">tail:</span> <span class="n">6144</span></code>
</b>
<p>To minimize the number of sbrk(2)s, malloc() asks for more memory.  This
field gives the size of the yet unused part, which is sbrk(2)ed, but
never touched.</p>
</li>
</ul>
<a name="SEE-ALSO"></a><h1>SEE ALSO</h1>
<p><a href="perldebug.html">perldebug</a>,
<a href="perlguts.html">perlguts</a>,
<a href="perlrun.html">perlrun</a>
<a href="re.html">re</a>,
and
<a href="http://search.cpan.org/perldoc/Devel::DProf">Devel::DProf</a>.</p>




  <div id="page_index" class="hud_container">
    <div id="page_index_header" class="hud_header">
      <div id="page_index_close" class="hud_close"><a href="#" onClick="pageIndex.hide();return false;"></a></div>
      <div id="page_index_title" class="hud_title"><span class="hud_span_top">Page index</span></div>
      <div id="page_index_topright" class="hud_topright"></div>
    </div>
    <div id="page_index_content" class="hud_content">
      <ul><li><a href="#NAME">NAME</a><li><a href="#DESCRIPTION">DESCRIPTION</a><li><a href="#Debugger-Internals">Debugger Internals</a><ul><li><a href="#Writing-Your-Own-Debugger">Writing Your Own Debugger</a></ul><li><a href="#Frame-Listing-Output-Examples">Frame Listing Output Examples</a><li><a href="#Debugging-Regular-Expressions">Debugging Regular Expressions</a><ul><li><a href="#Compile-time-Output">Compile-time Output</a><li><a href="#Types-of-Nodes">Types of Nodes</a><li><a href="#Run-time-Output">Run-time Output</a></ul><li><a href="#Debugging-Perl-Memory-Usage">Debugging Perl Memory Usage</a><ul><li><a href="#Using-%24ENV%7bPERL_DEBUG_MSTATS%7d">Using $ENV{PERL_DEBUG_MSTATS}</a></ul><li><a href="#SEE-ALSO">SEE ALSO</a></ul>
    </div>
    <div id="page_index_footer" class="hud_footer">
      <div id="page_index_bottomleft" class="hud_bottomleft"></div>
      <div id="page_index_bottom" class="hud_bottom"><span class="hud_span_bottom"></span></div>
      <div id="page_index_resize" class="hud_resize"></div>
    </div>
  </div>


	    &nbsp;
          </div>
          <div id="content_footer">
          </div>
        </div>
        <div class="clear"></div>
      </div>
      
    <div id="footer">
      <div id="footer_content">
        <div id="footer_strapline">
          perldoc.perl.org - Official documentation for the Perl programming language
        </div>
        <div id="footer_links">
          <div id="address">
            <p class="name">Contact details</p>
            <p class="address">
	      Site maintained by <a href="mailto:jj@jonallen.info">Jon Allen (JJ)</a><br>
	    </p>
            <p class="contact">
              Documentation maintained by the <a href="http://lists.cpan.org/showlist.cgi?name=perl5-porters">Perl 5 Porters</a>
            </p>
          </div>
          <ul class="f1">
            <li>Manual
              <ul class="f2">
                <li><a href="index-overview.html">Overview</a>
                <li><a href="index-tutorials.html">Tutorials</a>
                <li><a href="index-faq.html">FAQs</a>
                <li><a href="index-history.html">Changes</a>
              </ul>
            <li>Reference
              <ul class="f2">
                <li><a href="index-language.html">Language</a>
                <li><a href="index-functions.html">Functions</a>
                <li><a href="perlop.html">Operators</a>
                <li><a href="perlvar.html">Variables</a>
              </ul>
            <li>Modules
              <ul class="f2">
                <li><a href="index-modules-A.html">Modules</a>
                <li><a href="index-pragmas.html">Pragmas</a>
                <li><a href="index-utilities.html">Utilities</a>
              </ul>
            <li>Misc
              <ul class="f2">
                <li><a href="index-licence.html">License</a>
                <li><a href="index-internals.html">Internals</a>
                <li><a href="index-platforms.html">Platforms</a>
              </ul>          </ul>
          <div class="clear"></div>
        </div>
      </div>
      <div id="footer_end">
      </div>
    </div>
      
    </div>
      <script language="JavaScript" type="text/javascript" src="static/exploreperl.js"></script>
      <script language="JavaScript" src="static/combined-20100403.js" type="text/javascript"></script>
<script language="JavaScript" type="text/javascript">
  perldoc.setPath(0);
  perldoc.pageName    = 'perldebguts';
  perldoc.pageAddress = 'perldebguts.html';
  perldoc.contentPage = 1;
  explorePerl.render();
  explorePerl.addEvents('explore_anchor');
</script>
    
  </body>
</html>