Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 |
2 | .\" | |
3 | .\" Standard preamble: | |
4 | .\" ======================================================================== | |
5 | .de Sh \" Subsection heading | |
6 | .br | |
7 | .if t .Sp | |
8 | .ne 5 | |
9 | .PP | |
10 | \fB\\$1\fR | |
11 | .PP | |
12 | .. | |
13 | .de Sp \" Vertical space (when we can't use .PP) | |
14 | .if t .sp .5v | |
15 | .if n .sp | |
16 | .. | |
17 | .de Vb \" Begin verbatim text | |
18 | .ft CW | |
19 | .nf | |
20 | .ne \\$1 | |
21 | .. | |
22 | .de Ve \" End verbatim text | |
23 | .ft R | |
24 | .fi | |
25 | .. | |
26 | .\" Set up some character translations and predefined strings. \*(-- will | |
27 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left | |
28 | .\" double quote, and \*(R" will give a right double quote. | will give a | |
29 | .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to | |
30 | .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' | |
31 | .\" expand to `' in nroff, nothing in troff, for use with C<>. | |
32 | .tr \(*W-|\(bv\*(Tr | |
33 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' | |
34 | .ie n \{\ | |
35 | . ds -- \(*W- | |
36 | . ds PI pi | |
37 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch | |
38 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch | |
39 | . ds L" "" | |
40 | . ds R" "" | |
41 | . ds C` "" | |
42 | . ds C' "" | |
43 | 'br\} | |
44 | .el\{\ | |
45 | . ds -- \|\(em\| | |
46 | . ds PI \(*p | |
47 | . ds L" `` | |
48 | . ds R" '' | |
49 | 'br\} | |
50 | .\" | |
51 | .\" If the F register is turned on, we'll generate index entries on stderr for | |
52 | .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index | |
53 | .\" entries marked with X<> in POD. Of course, you'll have to process the | |
54 | .\" output yourself in some meaningful fashion. | |
55 | .if \nF \{\ | |
56 | . de IX | |
57 | . tm Index:\\$1\t\\n%\t"\\$2" | |
58 | .. | |
59 | . nr % 0 | |
60 | . rr F | |
61 | .\} | |
62 | .\" | |
63 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes | |
64 | .\" way too many mistakes in technical documents. | |
65 | .hy 0 | |
66 | .if n .na | |
67 | .\" | |
68 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). | |
69 | .\" Fear. Run. Save yourself. No user-serviceable parts. | |
70 | . \" fudge factors for nroff and troff | |
71 | .if n \{\ | |
72 | . ds #H 0 | |
73 | . ds #V .8m | |
74 | . ds #F .3m | |
75 | . ds #[ \f1 | |
76 | . ds #] \fP | |
77 | .\} | |
78 | .if t \{\ | |
79 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) | |
80 | . ds #V .6m | |
81 | . ds #F 0 | |
82 | . ds #[ \& | |
83 | . ds #] \& | |
84 | .\} | |
85 | . \" simple accents for nroff and troff | |
86 | .if n \{\ | |
87 | . ds ' \& | |
88 | . ds ` \& | |
89 | . ds ^ \& | |
90 | . ds , \& | |
91 | . ds ~ ~ | |
92 | . ds / | |
93 | .\} | |
94 | .if t \{\ | |
95 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" | |
96 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' | |
97 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' | |
98 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' | |
99 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' | |
100 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' | |
101 | .\} | |
102 | . \" troff and (daisy-wheel) nroff accents | |
103 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' | |
104 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' | |
105 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] | |
106 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' | |
107 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' | |
108 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] | |
109 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] | |
110 | .ds ae a\h'-(\w'a'u*4/10)'e | |
111 | .ds Ae A\h'-(\w'A'u*4/10)'E | |
112 | . \" corrections for vroff | |
113 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' | |
114 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' | |
115 | . \" for low resolution devices (crt and lpr) | |
116 | .if \n(.H>23 .if \n(.V>19 \ | |
117 | \{\ | |
118 | . ds : e | |
119 | . ds 8 ss | |
120 | . ds o a | |
121 | . ds d- d\h'-1'\(ga | |
122 | . ds D- D\h'-1'\(hy | |
123 | . ds th \o'bp' | |
124 | . ds Th \o'LP' | |
125 | . ds ae ae | |
126 | . ds Ae AE | |
127 | .\} | |
128 | .rm #[ #] #H #V #F C | |
129 | .\" ======================================================================== | |
130 | .\" | |
131 | .IX Title "PERLDEBGUTS 1" | |
132 | .TH PERLDEBGUTS 1 "2006-01-07" "perl v5.8.8" "Perl Programmers Reference Guide" | |
133 | .SH "NAME" | |
134 | perldebguts \- Guts of Perl debugging | |
135 | .SH "DESCRIPTION" | |
136 | .IX Header "DESCRIPTION" | |
137 | This is not the \fIperldebug\fR\|(1) manpage, which tells you how to use | |
138 | the debugger. This manpage describes low-level details concerning | |
139 | the debugger's internals, which range from difficult to impossible | |
140 | to understand for anyone who isn't incredibly intimate with Perl's guts. | |
141 | Caveat lector. | |
142 | .SH "Debugger Internals" | |
143 | .IX Header "Debugger Internals" | |
144 | Perl has special debugging hooks at compile-time and run-time used | |
145 | to create debugging environments. These hooks are not to be confused | |
146 | with the \fIperl \-Dxxx\fR command described in perlrun, which is | |
147 | usable only if a special Perl is built per the instructions in the | |
148 | \&\fI\s-1INSTALL\s0\fR podpage in the Perl source tree. | |
149 | .PP | |
150 | For example, whenever you call Perl's built-in \f(CW\*(C`caller\*(C'\fR function | |
151 | from the package \f(CW\*(C`DB\*(C'\fR, the arguments that the corresponding stack | |
152 | frame was called with are copied to the \f(CW@DB::args\fR array. These | |
153 | mechanisms are enabled by calling Perl with the \fB\-d\fR switch. | |
154 | Specifically, the following additional features are enabled | |
155 | (cf. \*(L"$^P\*(R" in perlvar): | |
156 | .IP "\(bu" 4 | |
157 | Perl inserts the contents of \f(CW$ENV{PERL5DB}\fR (or \f(CW\*(C`BEGIN {require | |
158 | \&'perl5db.pl'}\*(C'\fR if not present) before the first line of your program. | |
159 | .IP "\(bu" 4 | |
160 | Each array \f(CW\*(C`@{"_<$filename"}\*(C'\fR holds the lines of \f(CW$filename\fR for a | |
161 | file compiled by Perl. The same is also true for \f(CW\*(C`eval\*(C'\fRed strings | |
162 | that contain subroutines, or which are currently being executed. | |
163 | The \f(CW$filename\fR for \f(CW\*(C`eval\*(C'\fRed strings looks like \f(CW\*(C`(eval 34)\*(C'\fR. | |
164 | Code assertions in regexes look like \f(CW\*(C`(re_eval 19)\*(C'\fR. | |
165 | .Sp | |
166 | Values in this array are magical in numeric context: they compare | |
167 | equal to zero only if the line is not breakable. | |
168 | .IP "\(bu" 4 | |
169 | Each hash \f(CW\*(C`%{"_<$filename"}\*(C'\fR contains breakpoints and actions keyed | |
170 | by line number. Individual entries (as opposed to the whole hash) | |
171 | are settable. Perl only cares about Boolean true here, although | |
172 | the values used by \fIperl5db.pl\fR have the form | |
173 | \&\f(CW"$break_condition\e0$action"\fR. | |
174 | .Sp | |
175 | The same holds for evaluated strings that contain subroutines, or | |
176 | which are currently being executed. The \f(CW$filename\fR for \f(CW\*(C`eval\*(C'\fRed strings | |
177 | looks like \f(CW\*(C`(eval 34)\*(C'\fR or \f(CW\*(C`(re_eval 19)\*(C'\fR. | |
178 | .IP "\(bu" 4 | |
179 | Each scalar \f(CW\*(C`${"_<$filename"}\*(C'\fR contains \f(CW"_<$filename"\fR. This is | |
180 | also the case for evaluated strings that contain subroutines, or | |
181 | which are currently being executed. The \f(CW$filename\fR for \f(CW\*(C`eval\*(C'\fRed | |
182 | strings looks like \f(CW\*(C`(eval 34)\*(C'\fR or \f(CW\*(C`(re_eval 19)\*(C'\fR. | |
183 | .IP "\(bu" 4 | |
184 | After each \f(CW\*(C`require\*(C'\fRd file is compiled, but before it is executed, | |
185 | \&\f(CW\*(C`DB::postponed(*{"_<$filename"})\*(C'\fR is called if the subroutine | |
186 | \&\f(CW\*(C`DB::postponed\*(C'\fR exists. Here, the \f(CW$filename\fR is the expanded name of | |
187 | the \f(CW\*(C`require\*(C'\fRd file, as found in the values of \f(CW%INC\fR. | |
188 | .IP "\(bu" 4 | |
189 | After each subroutine \f(CW\*(C`subname\*(C'\fR is compiled, the existence of | |
190 | \&\f(CW$DB::postponed{subname}\fR is checked. If this key exists, | |
191 | \&\f(CW\*(C`DB::postponed(subname)\*(C'\fR is called if the \f(CW\*(C`DB::postponed\*(C'\fR subroutine | |
192 | also exists. | |
193 | .IP "\(bu" 4 | |
194 | A hash \f(CW%DB::sub\fR is maintained, whose keys are subroutine names | |
195 | and whose values have the form \f(CW\*(C`filename:startline\-endline\*(C'\fR. | |
196 | \&\f(CW\*(C`filename\*(C'\fR has the form \f(CW\*(C`(eval 34)\*(C'\fR for subroutines defined inside | |
197 | \&\f(CW\*(C`eval\*(C'\fRs, or \f(CW\*(C`(re_eval 19)\*(C'\fR for those within regex code assertions. | |
198 | .IP "\(bu" 4 | |
199 | When the execution of your program reaches a point that can hold a | |
200 | breakpoint, the \f(CW\*(C`DB::DB()\*(C'\fR subroutine is called if any of the variables | |
201 | \&\f(CW$DB::trace\fR, \f(CW$DB::single\fR, or \f(CW$DB::signal\fR is true. These variables | |
202 | are not \f(CW\*(C`local\*(C'\fRizable. This feature is disabled when executing | |
203 | inside \f(CW\*(C`DB::DB()\*(C'\fR, including functions called from it | |
204 | unless \f(CW\*(C`$^D & (1<<30)\*(C'\fR is true. | |
205 | .IP "\(bu" 4 | |
206 | When execution of the program reaches a subroutine call, a call to | |
207 | \&\f(CW&DB::sub\fR(\fIargs\fR) is made instead, with \f(CW$DB::sub\fR holding the | |
208 | name of the called subroutine. (This doesn't happen if the subroutine | |
209 | was compiled in the \f(CW\*(C`DB\*(C'\fR package.) | |
210 | .PP | |
211 | Note that if \f(CW&DB::sub\fR needs external data for it to work, no | |
212 | subroutine call is possible without it. As an example, the standard | |
213 | debugger's \f(CW&DB::sub\fR depends on the \f(CW$DB::deep\fR variable | |
214 | (it defines how many levels of recursion deep into the debugger you can go | |
215 | before a mandatory break). If \f(CW$DB::deep\fR is not defined, subroutine | |
216 | calls are not possible, even though \f(CW&DB::sub\fR exists. | |
217 | .Sh "Writing Your Own Debugger" | |
218 | .IX Subsection "Writing Your Own Debugger" | |
219 | \fIEnvironment Variables\fR | |
220 | .IX Subsection "Environment Variables" | |
221 | .PP | |
222 | The \f(CW\*(C`PERL5DB\*(C'\fR environment variable can be used to define a debugger. | |
223 | For example, the minimal \*(L"working\*(R" debugger (it actually doesn't do anything) | |
224 | consists of one line: | |
225 | .PP | |
226 | .Vb 1 | |
227 | \& sub DB::DB {} | |
228 | .Ve | |
229 | .PP | |
230 | It can easily be defined like this: | |
231 | .PP | |
232 | .Vb 1 | |
233 | \& $ PERL5DB="sub DB::DB {}" perl -d your-script | |
234 | .Ve | |
235 | .PP | |
236 | Another brief debugger, slightly more useful, can be created | |
237 | with only the line: | |
238 | .PP | |
239 | .Vb 1 | |
240 | \& sub DB::DB {print ++$i; scalar <STDIN>} | |
241 | .Ve | |
242 | .PP | |
243 | This debugger prints a number which increments for each statement | |
244 | encountered and waits for you to hit a newline before continuing | |
245 | to the next statement. | |
246 | .PP | |
247 | The following debugger is actually useful: | |
248 | .PP | |
249 | .Vb 5 | |
250 | \& { | |
251 | \& package DB; | |
252 | \& sub DB {} | |
253 | \& sub sub {print ++$i, " $sub\en"; &$sub} | |
254 | \& } | |
255 | .Ve | |
256 | .PP | |
257 | It prints the sequence number of each subroutine call and the name of the | |
258 | called subroutine. Note that \f(CW&DB::sub\fR is being compiled into the | |
259 | package \f(CW\*(C`DB\*(C'\fR through the use of the \f(CW\*(C`package\*(C'\fR directive. | |
260 | .PP | |
261 | When it starts, the debugger reads your rc file (\fI./.perldb\fR or | |
262 | \&\fI~/.perldb\fR under Unix), which can set important options. | |
263 | (A subroutine (\f(CW&afterinit\fR) can be defined here as well; it is executed | |
264 | after the debugger completes its own initialization.) | |
265 | .PP | |
266 | After the rc file is read, the debugger reads the \s-1PERLDB_OPTS\s0 | |
267 | environment variable and uses it to set debugger options. The | |
268 | contents of this variable are treated as if they were the argument | |
269 | of an \f(CW\*(C`o ...\*(C'\fR debugger command (q.v. in \*(L"Options\*(R" in perldebug). | |
270 | .PP | |
271 | \fIDebugger internal variables In addition to the file and subroutine-related variables mentioned above, the debugger also maintains various magical internal variables.\fR | |
272 | .IX Subsection "Debugger internal variables In addition to the file and subroutine-related variables mentioned above, the debugger also maintains various magical internal variables." | |
273 | .IP "\(bu" 4 | |
274 | \&\f(CW@DB::dbline\fR is an alias for \f(CW\*(C`@{"::_<current_file"}\*(C'\fR, which | |
275 | holds the lines of the currently-selected file (compiled by Perl), either | |
276 | explicitly chosen with the debugger's \f(CW\*(C`f\*(C'\fR command, or implicitly by flow | |
277 | of execution. | |
278 | .Sp | |
279 | Values in this array are magical in numeric context: they compare | |
280 | equal to zero only if the line is not breakable. | |
281 | .IP "\(bu" 4 | |
282 | \&\f(CW%DB::dbline\fR, is an alias for \f(CW\*(C`%{"::_<current_file"}\*(C'\fR, which | |
283 | contains breakpoints and actions keyed by line number in | |
284 | the currently-selected file, either explicitly chosen with the | |
285 | debugger's \f(CW\*(C`f\*(C'\fR command, or implicitly by flow of execution. | |
286 | .Sp | |
287 | As previously noted, individual entries (as opposed to the whole hash) | |
288 | are settable. Perl only cares about Boolean true here, although | |
289 | the values used by \fIperl5db.pl\fR have the form | |
290 | \&\f(CW"$break_condition\e0$action"\fR. | |
291 | .PP | |
292 | \fIDebugger customization functions\fR | |
293 | .IX Subsection "Debugger customization functions" | |
294 | .PP | |
295 | Some functions are provided to simplify customization. | |
296 | .IP "\(bu" 4 | |
297 | See \*(L"Options\*(R" in perldebug for description of options parsed by | |
298 | \&\f(CW\*(C`DB::parse_options(string)\*(C'\fR parses debugger options; see | |
299 | \&\*(L"Options\*(R" in pperldebug for a description of options recognized. | |
300 | .IP "\(bu" 4 | |
301 | \&\f(CW\*(C`DB::dump_trace(skip[,count])\*(C'\fR skips the specified number of frames | |
302 | and returns a list containing information about the calling frames (all | |
303 | of them, if \f(CW\*(C`count\*(C'\fR is missing). Each entry is reference to a hash | |
304 | with keys \f(CW\*(C`context\*(C'\fR (either \f(CW\*(C`.\*(C'\fR, \f(CW\*(C`$\*(C'\fR, or \f(CW\*(C`@\*(C'\fR), \f(CW\*(C`sub\*(C'\fR (subroutine | |
305 | name, or info about \f(CW\*(C`eval\*(C'\fR), \f(CW\*(C`args\*(C'\fR (\f(CW\*(C`undef\*(C'\fR or a reference to | |
306 | an array), \f(CW\*(C`file\*(C'\fR, and \f(CW\*(C`line\*(C'\fR. | |
307 | .IP "\(bu" 4 | |
308 | \&\f(CW\*(C`DB::print_trace(FH, skip[, count[, short]])\*(C'\fR prints | |
309 | formatted info about caller frames. The last two functions may be | |
310 | convenient as arguments to \f(CW\*(C`<\*(C'\fR, \f(CW\*(C`<<\*(C'\fR commands. | |
311 | .PP | |
312 | Note that any variables and functions that are not documented in | |
313 | this manpages (or in perldebug) are considered for internal | |
314 | use only, and as such are subject to change without notice. | |
315 | .SH "Frame Listing Output Examples" | |
316 | .IX Header "Frame Listing Output Examples" | |
317 | The \f(CW\*(C`frame\*(C'\fR option can be used to control the output of frame | |
318 | information. For example, contrast this expression trace: | |
319 | .PP | |
320 | .Vb 2 | |
321 | \& $ perl -de 42 | |
322 | \& Stack dump during die enabled outside of evals. | |
323 | .Ve | |
324 | .PP | |
325 | .Vb 2 | |
326 | \& Loading DB routines from perl5db.pl patch level 0.94 | |
327 | \& Emacs support available. | |
328 | .Ve | |
329 | .PP | |
330 | .Vb 1 | |
331 | \& Enter h or `h h' for help. | |
332 | .Ve | |
333 | .PP | |
334 | .Vb 2 | |
335 | \& main::(-e:1): 0 | |
336 | \& DB<1> sub foo { 14 } | |
337 | .Ve | |
338 | .PP | |
339 | .Vb 1 | |
340 | \& DB<2> sub bar { 3 } | |
341 | .Ve | |
342 | .PP | |
343 | .Vb 5 | |
344 | \& DB<3> t print foo() * bar() | |
345 | \& main::((eval 172):3): print foo() + bar(); | |
346 | \& main::foo((eval 168):2): | |
347 | \& main::bar((eval 170):2): | |
348 | \& 42 | |
349 | .Ve | |
350 | .PP | |
351 | with this one, once the \f(CW\*(C`o\*(C'\fRption \f(CW\*(C`frame=2\*(C'\fR has been set: | |
352 | .PP | |
353 | .Vb 11 | |
354 | \& DB<4> o f=2 | |
355 | \& frame = '2' | |
356 | \& DB<5> t print foo() * bar() | |
357 | \& 3: foo() * bar() | |
358 | \& entering main::foo | |
359 | \& 2: sub foo { 14 }; | |
360 | \& exited main::foo | |
361 | \& entering main::bar | |
362 | \& 2: sub bar { 3 }; | |
363 | \& exited main::bar | |
364 | \& 42 | |
365 | .Ve | |
366 | .PP | |
367 | By way of demonstration, we present below a laborious listing | |
368 | resulting from setting your \f(CW\*(C`PERLDB_OPTS\*(C'\fR environment variable to | |
369 | the value \f(CW\*(C`f=n N\*(C'\fR, and running \fIperl \-d \-V\fR from the command line. | |
370 | Examples use various values of \f(CW\*(C`n\*(C'\fR are shown to give you a feel | |
371 | for the difference between settings. Long those it may be, this | |
372 | is not a complete listing, but only excerpts. | |
373 | .IP "1" 4 | |
374 | .IX Item "1" | |
375 | .Vb 13 | |
376 | \& entering main::BEGIN | |
377 | \& entering Config::BEGIN | |
378 | \& Package lib/Exporter.pm. | |
379 | \& Package lib/Carp.pm. | |
380 | \& Package lib/Config.pm. | |
381 | \& entering Config::TIEHASH | |
382 | \& entering Exporter::import | |
383 | \& entering Exporter::export | |
384 | \& entering Config::myconfig | |
385 | \& entering Config::FETCH | |
386 | \& entering Config::FETCH | |
387 | \& entering Config::FETCH | |
388 | \& entering Config::FETCH | |
389 | .Ve | |
390 | .IP "2" 4 | |
391 | .IX Item "2" | |
392 | .Vb 19 | |
393 | \& entering main::BEGIN | |
394 | \& entering Config::BEGIN | |
395 | \& Package lib/Exporter.pm. | |
396 | \& Package lib/Carp.pm. | |
397 | \& exited Config::BEGIN | |
398 | \& Package lib/Config.pm. | |
399 | \& entering Config::TIEHASH | |
400 | \& exited Config::TIEHASH | |
401 | \& entering Exporter::import | |
402 | \& entering Exporter::export | |
403 | \& exited Exporter::export | |
404 | \& exited Exporter::import | |
405 | \& exited main::BEGIN | |
406 | \& entering Config::myconfig | |
407 | \& entering Config::FETCH | |
408 | \& exited Config::FETCH | |
409 | \& entering Config::FETCH | |
410 | \& exited Config::FETCH | |
411 | \& entering Config::FETCH | |
412 | .Ve | |
413 | .IP "4" 4 | |
414 | .IX Item "4" | |
415 | .Vb 15 | |
416 | \& in $=main::BEGIN() from /dev/null:0 | |
417 | \& in $=Config::BEGIN() from lib/Config.pm:2 | |
418 | \& Package lib/Exporter.pm. | |
419 | \& Package lib/Carp.pm. | |
420 | \& Package lib/Config.pm. | |
421 | \& in $=Config::TIEHASH('Config') from lib/Config.pm:644 | |
422 | \& in $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0 | |
423 | \& in $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from li | |
424 | \& in @=Config::myconfig() from /dev/null:0 | |
425 | \& in $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574 | |
426 | \& in $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574 | |
427 | \& in $=Config::FETCH(ref(Config), 'PERL_VERSION') from lib/Config.pm:574 | |
428 | \& in $=Config::FETCH(ref(Config), 'PERL_SUBVERSION') from lib/Config.pm:574 | |
429 | \& in $=Config::FETCH(ref(Config), 'osname') from lib/Config.pm:574 | |
430 | \& in $=Config::FETCH(ref(Config), 'osvers') from lib/Config.pm:574 | |
431 | .Ve | |
432 | .IP "6" 4 | |
433 | .IX Item "6" | |
434 | .Vb 21 | |
435 | \& in $=main::BEGIN() from /dev/null:0 | |
436 | \& in $=Config::BEGIN() from lib/Config.pm:2 | |
437 | \& Package lib/Exporter.pm. | |
438 | \& Package lib/Carp.pm. | |
439 | \& out $=Config::BEGIN() from lib/Config.pm:0 | |
440 | \& Package lib/Config.pm. | |
441 | \& in $=Config::TIEHASH('Config') from lib/Config.pm:644 | |
442 | \& out $=Config::TIEHASH('Config') from lib/Config.pm:644 | |
443 | \& in $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0 | |
444 | \& in $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/ | |
445 | \& out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/ | |
446 | \& out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0 | |
447 | \& out $=main::BEGIN() from /dev/null:0 | |
448 | \& in @=Config::myconfig() from /dev/null:0 | |
449 | \& in $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574 | |
450 | \& out $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574 | |
451 | \& in $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574 | |
452 | \& out $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574 | |
453 | \& in $=Config::FETCH(ref(Config), 'PERL_VERSION') from lib/Config.pm:574 | |
454 | \& out $=Config::FETCH(ref(Config), 'PERL_VERSION') from lib/Config.pm:574 | |
455 | \& in $=Config::FETCH(ref(Config), 'PERL_SUBVERSION') from lib/Config.pm:574 | |
456 | .Ve | |
457 | .IP "14" 4 | |
458 | .IX Item "14" | |
459 | .Vb 18 | |
460 | \& in $=main::BEGIN() from /dev/null:0 | |
461 | \& in $=Config::BEGIN() from lib/Config.pm:2 | |
462 | \& Package lib/Exporter.pm. | |
463 | \& Package lib/Carp.pm. | |
464 | \& out $=Config::BEGIN() from lib/Config.pm:0 | |
465 | \& Package lib/Config.pm. | |
466 | \& in $=Config::TIEHASH('Config') from lib/Config.pm:644 | |
467 | \& out $=Config::TIEHASH('Config') from lib/Config.pm:644 | |
468 | \& in $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0 | |
469 | \& in $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/E | |
470 | \& out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/E | |
471 | \& out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0 | |
472 | \& out $=main::BEGIN() from /dev/null:0 | |
473 | \& in @=Config::myconfig() from /dev/null:0 | |
474 | \& in $=Config::FETCH('Config=HASH(0x1aa444)', 'package') from lib/Config.pm:574 | |
475 | \& out $=Config::FETCH('Config=HASH(0x1aa444)', 'package') from lib/Config.pm:574 | |
476 | \& in $=Config::FETCH('Config=HASH(0x1aa444)', 'baserev') from lib/Config.pm:574 | |
477 | \& out $=Config::FETCH('Config=HASH(0x1aa444)', 'baserev') from lib/Config.pm:574 | |
478 | .Ve | |
479 | .IP "30" 4 | |
480 | .IX Item "30" | |
481 | .Vb 15 | |
482 | \& in $=CODE(0x15eca4)() from /dev/null:0 | |
483 | \& in $=CODE(0x182528)() from lib/Config.pm:2 | |
484 | \& Package lib/Exporter.pm. | |
485 | \& out $=CODE(0x182528)() from lib/Config.pm:0 | |
486 | \& scalar context return from CODE(0x182528): undef | |
487 | \& Package lib/Config.pm. | |
488 | \& in $=Config::TIEHASH('Config') from lib/Config.pm:628 | |
489 | \& out $=Config::TIEHASH('Config') from lib/Config.pm:628 | |
490 | \& scalar context return from Config::TIEHASH: empty hash | |
491 | \& in $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0 | |
492 | \& in $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/Exporter.pm:171 | |
493 | \& out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/Exporter.pm:171 | |
494 | \& scalar context return from Exporter::export: '' | |
495 | \& out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0 | |
496 | \& scalar context return from Exporter::import: '' | |
497 | .Ve | |
498 | .PP | |
499 | In all cases shown above, the line indentation shows the call tree. | |
500 | If bit 2 of \f(CW\*(C`frame\*(C'\fR is set, a line is printed on exit from a | |
501 | subroutine as well. If bit 4 is set, the arguments are printed | |
502 | along with the caller info. If bit 8 is set, the arguments are | |
503 | printed even if they are tied or references. If bit 16 is set, the | |
504 | return value is printed, too. | |
505 | .PP | |
506 | When a package is compiled, a line like this | |
507 | .PP | |
508 | .Vb 1 | |
509 | \& Package lib/Carp.pm. | |
510 | .Ve | |
511 | .PP | |
512 | is printed with proper indentation. | |
513 | .SH "Debugging regular expressions" | |
514 | .IX Header "Debugging regular expressions" | |
515 | There are two ways to enable debugging output for regular expressions. | |
516 | .PP | |
517 | If your perl is compiled with \f(CW\*(C`\-DDEBUGGING\*(C'\fR, you may use the | |
518 | \&\fB\-Dr\fR flag on the command line. | |
519 | .PP | |
520 | Otherwise, one can \f(CW\*(C`use re 'debug'\*(C'\fR, which has effects at | |
521 | compile time and run time. It is not lexically scoped. | |
522 | .Sh "Compile-time output" | |
523 | .IX Subsection "Compile-time output" | |
524 | The debugging output at compile time looks like this: | |
525 | .PP | |
526 | .Vb 29 | |
527 | \& Compiling REx `[bc]d(ef*g)+h[ij]k$' | |
528 | \& size 45 Got 364 bytes for offset annotations. | |
529 | \& first at 1 | |
530 | \& rarest char g at 0 | |
531 | \& rarest char d at 0 | |
532 | \& 1: ANYOF[bc](12) | |
533 | \& 12: EXACT <d>(14) | |
534 | \& 14: CURLYX[0] {1,32767}(28) | |
535 | \& 16: OPEN1(18) | |
536 | \& 18: EXACT <e>(20) | |
537 | \& 20: STAR(23) | |
538 | \& 21: EXACT <f>(0) | |
539 | \& 23: EXACT <g>(25) | |
540 | \& 25: CLOSE1(27) | |
541 | \& 27: WHILEM[1/1](0) | |
542 | \& 28: NOTHING(29) | |
543 | \& 29: EXACT <h>(31) | |
544 | \& 31: ANYOF[ij](42) | |
545 | \& 42: EXACT <k>(44) | |
546 | \& 44: EOL(45) | |
547 | \& 45: END(0) | |
548 | \& anchored `de' at 1 floating `gh' at 3..2147483647 (checking floating) | |
549 | \& stclass `ANYOF[bc]' minlen 7 | |
550 | \& Offsets: [45] | |
551 | \& 1[4] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 5[1] | |
552 | \& 0[0] 12[1] 0[0] 6[1] 0[0] 7[1] 0[0] 9[1] 8[1] 0[0] 10[1] 0[0] | |
553 | \& 11[1] 0[0] 12[0] 12[0] 13[1] 0[0] 14[4] 0[0] 0[0] 0[0] 0[0] | |
554 | \& 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 18[1] 0[0] 19[1] 20[0] | |
555 | \& Omitting $` $& $' support. | |
556 | .Ve | |
557 | .PP | |
558 | The first line shows the pre-compiled form of the regex. The second | |
559 | shows the size of the compiled form (in arbitrary units, usually | |
560 | 4\-byte words) and the total number of bytes allocated for the | |
561 | offset/length table, usually 4+\f(CW\*(C`size\*(C'\fR*8. The next line shows the | |
562 | label \fIid\fR of the first node that does a match. | |
563 | .PP | |
564 | The | |
565 | .PP | |
566 | .Vb 2 | |
567 | \& anchored `de' at 1 floating `gh' at 3..2147483647 (checking floating) | |
568 | \& stclass `ANYOF[bc]' minlen 7 | |
569 | .Ve | |
570 | .PP | |
571 | line (split into two lines above) contains optimizer | |
572 | information. In the example shown, the optimizer found that the match | |
573 | should contain a substring \f(CW\*(C`de\*(C'\fR at offset 1, plus substring \f(CW\*(C`gh\*(C'\fR | |
574 | at some offset between 3 and infinity. Moreover, when checking for | |
575 | these substrings (to abandon impossible matches quickly), Perl will check | |
576 | for the substring \f(CW\*(C`gh\*(C'\fR before checking for the substring \f(CW\*(C`de\*(C'\fR. The | |
577 | optimizer may also use the knowledge that the match starts (at the | |
578 | \&\f(CW\*(C`first\*(C'\fR \fIid\fR) with a character class, and no string | |
579 | shorter than 7 characters can possibly match. | |
580 | .PP | |
581 | The fields of interest which may appear in this line are | |
582 | .ie n .IP """anchored""\fR \fI\s-1STRING\s0\fR \f(CW""at""\fR \fI\s-1POS\s0" 4 | |
583 | .el .IP "\f(CWanchored\fR \fI\s-1STRING\s0\fR \f(CWat\fR \fI\s-1POS\s0\fR" 4 | |
584 | .IX Item "anchored STRING at POS" | |
585 | .PD 0 | |
586 | .ie n .IP """floating""\fR \fI\s-1STRING\s0\fR \f(CW""at""\fR \fI\s-1POS1\s0..POS2" 4 | |
587 | .el .IP "\f(CWfloating\fR \fI\s-1STRING\s0\fR \f(CWat\fR \fI\s-1POS1\s0..POS2\fR" 4 | |
588 | .IX Item "floating STRING at POS1..POS2" | |
589 | .PD | |
590 | See above. | |
591 | .ie n .IP """matching floating/anchored""" 4 | |
592 | .el .IP "\f(CWmatching floating/anchored\fR" 4 | |
593 | .IX Item "matching floating/anchored" | |
594 | Which substring to check first. | |
595 | .ie n .IP """minlen""" 4 | |
596 | .el .IP "\f(CWminlen\fR" 4 | |
597 | .IX Item "minlen" | |
598 | The minimal length of the match. | |
599 | .ie n .IP """stclass""\fR \fI\s-1TYPE\s0" 4 | |
600 | .el .IP "\f(CWstclass\fR \fI\s-1TYPE\s0\fR" 4 | |
601 | .IX Item "stclass TYPE" | |
602 | Type of first matching node. | |
603 | .ie n .IP """noscan""" 4 | |
604 | .el .IP "\f(CWnoscan\fR" 4 | |
605 | .IX Item "noscan" | |
606 | Don't scan for the found substrings. | |
607 | .ie n .IP """isall""" 4 | |
608 | .el .IP "\f(CWisall\fR" 4 | |
609 | .IX Item "isall" | |
610 | Means that the optimizer information is all that the regular | |
611 | expression contains, and thus one does not need to enter the regex engine at | |
612 | all. | |
613 | .ie n .IP """GPOS""" 4 | |
614 | .el .IP "\f(CWGPOS\fR" 4 | |
615 | .IX Item "GPOS" | |
616 | Set if the pattern contains \f(CW\*(C`\eG\*(C'\fR. | |
617 | .ie n .IP """plus""" 4 | |
618 | .el .IP "\f(CWplus\fR" 4 | |
619 | .IX Item "plus" | |
620 | Set if the pattern starts with a repeated char (as in \f(CW\*(C`x+y\*(C'\fR). | |
621 | .ie n .IP """implicit""" 4 | |
622 | .el .IP "\f(CWimplicit\fR" 4 | |
623 | .IX Item "implicit" | |
624 | Set if the pattern starts with \f(CW\*(C`.*\*(C'\fR. | |
625 | .ie n .IP """with eval""" 4 | |
626 | .el .IP "\f(CWwith eval\fR" 4 | |
627 | .IX Item "with eval" | |
628 | Set if the pattern contain eval\-groups, such as \f(CW\*(C`(?{ code })\*(C'\fR and | |
629 | \&\f(CW\*(C`(??{ code })\*(C'\fR. | |
630 | .ie n .IP """anchored(TYPE)""" 4 | |
631 | .el .IP "\f(CWanchored(TYPE)\fR" 4 | |
632 | .IX Item "anchored(TYPE)" | |
633 | If the pattern may match only at a handful of places, (with \f(CW\*(C`TYPE\*(C'\fR | |
634 | being \f(CW\*(C`BOL\*(C'\fR, \f(CW\*(C`MBOL\*(C'\fR, or \f(CW\*(C`GPOS\*(C'\fR. See the table below. | |
635 | .PP | |
636 | If a substring is known to match at end-of-line only, it may be | |
637 | followed by \f(CW\*(C`$\*(C'\fR, as in \f(CW\*(C`floating `k'$\*(C'\fR. | |
638 | .PP | |
639 | The optimizer-specific information is used to avoid entering (a slow) regex | |
640 | engine on strings that will not definitely match. If the \f(CW\*(C`isall\*(C'\fR flag | |
641 | is set, a call to the regex engine may be avoided even when the optimizer | |
642 | found an appropriate place for the match. | |
643 | .PP | |
644 | Above the optimizer section is the list of \fInodes\fR of the compiled | |
645 | form of the regex. Each line has format | |
646 | .PP | |
647 | \&\f(CW\*(C` \*(C'\fR\fIid\fR: \fI\s-1TYPE\s0\fR \fIOPTIONAL-INFO\fR (\fInext-id\fR) | |
648 | .Sh "Types of nodes" | |
649 | .IX Subsection "Types of nodes" | |
650 | Here are the possible types, with short descriptions: | |
651 | .PP | |
652 | .Vb 1 | |
653 | \& # TYPE arg-description [num-args] [longjump-len] DESCRIPTION | |
654 | .Ve | |
655 | .PP | |
656 | .Vb 3 | |
657 | \& # Exit points | |
658 | \& END no End of program. | |
659 | \& SUCCEED no Return from a subroutine, basically. | |
660 | .Ve | |
661 | .PP | |
662 | .Vb 13 | |
663 | \& # Anchors: | |
664 | \& BOL no Match "" at beginning of line. | |
665 | \& MBOL no Same, assuming multiline. | |
666 | \& SBOL no Same, assuming singleline. | |
667 | \& EOS no Match "" at end of string. | |
668 | \& EOL no Match "" at end of line. | |
669 | \& MEOL no Same, assuming multiline. | |
670 | \& SEOL no Same, assuming singleline. | |
671 | \& BOUND no Match "" at any word boundary | |
672 | \& BOUNDL no Match "" at any word boundary | |
673 | \& NBOUND no Match "" at any word non-boundary | |
674 | \& NBOUNDL no Match "" at any word non-boundary | |
675 | \& GPOS no Matches where last m//g left off. | |
676 | .Ve | |
677 | .PP | |
678 | .Vb 14 | |
679 | \& # [Special] alternatives | |
680 | \& ANY no Match any one character (except newline). | |
681 | \& SANY no Match any one character. | |
682 | \& ANYOF sv Match character in (or not in) this class. | |
683 | \& ALNUM no Match any alphanumeric character | |
684 | \& ALNUML no Match any alphanumeric char in locale | |
685 | \& NALNUM no Match any non-alphanumeric character | |
686 | \& NALNUML no Match any non-alphanumeric char in locale | |
687 | \& SPACE no Match any whitespace character | |
688 | \& SPACEL no Match any whitespace char in locale | |
689 | \& NSPACE no Match any non-whitespace character | |
690 | \& NSPACEL no Match any non-whitespace char in locale | |
691 | \& DIGIT no Match any numeric character | |
692 | \& NDIGIT no Match any non-numeric character | |
693 | .Ve | |
694 | .PP | |
695 | .Vb 9 | |
696 | \& # BRANCH The set of branches constituting a single choice are hooked | |
697 | \& # together with their "next" pointers, since precedence prevents | |
698 | \& # anything being concatenated to any individual branch. The | |
699 | \& # "next" pointer of the last BRANCH in a choice points to the | |
700 | \& # thing following the whole choice. This is also where the | |
701 | \& # final "next" pointer of each individual branch points; each | |
702 | \& # branch starts with the operand node of a BRANCH node. | |
703 | \& # | |
704 | \& BRANCH node Match this alternative, or the next... | |
705 | .Ve | |
706 | .PP | |
707 | .Vb 4 | |
708 | \& # BACK Normal "next" pointers all implicitly point forward; BACK | |
709 | \& # exists to make loop structures possible. | |
710 | \& # not used | |
711 | \& BACK no Match "", "next" ptr points backward. | |
712 | .Ve | |
713 | .PP | |
714 | .Vb 4 | |
715 | \& # Literals | |
716 | \& EXACT sv Match this string (preceded by length). | |
717 | \& EXACTF sv Match this string, folded (prec. by length). | |
718 | \& EXACTFL sv Match this string, folded in locale (w/len). | |
719 | .Ve | |
720 | .PP | |
721 | .Vb 4 | |
722 | \& # Do nothing | |
723 | \& NOTHING no Match empty string. | |
724 | \& # A variant of above which delimits a group, thus stops optimizations | |
725 | \& TAIL no Match empty string. Can jump here from outside. | |
726 | .Ve | |
727 | .PP | |
728 | .Vb 7 | |
729 | \& # STAR,PLUS '?', and complex '*' and '+', are implemented as circular | |
730 | \& # BRANCH structures using BACK. Simple cases (one character | |
731 | \& # per match) are implemented with STAR and PLUS for speed | |
732 | \& # and to minimize recursive plunges. | |
733 | \& # | |
734 | \& STAR node Match this (simple) thing 0 or more times. | |
735 | \& PLUS node Match this (simple) thing 1 or more times. | |
736 | .Ve | |
737 | .PP | |
738 | .Vb 5 | |
739 | \& CURLY sv 2 Match this simple thing {n,m} times. | |
740 | \& CURLYN no 2 Match next-after-this simple thing | |
741 | \& # {n,m} times, set parens. | |
742 | \& CURLYM no 2 Match this medium-complex thing {n,m} times. | |
743 | \& CURLYX sv 2 Match this complex thing {n,m} times. | |
744 | .Ve | |
745 | .PP | |
746 | .Vb 2 | |
747 | \& # This terminator creates a loop structure for CURLYX | |
748 | \& WHILEM no Do curly processing and see if rest matches. | |
749 | .Ve | |
750 | .PP | |
751 | .Vb 3 | |
752 | \& # OPEN,CLOSE,GROUPP ...are numbered at compile time. | |
753 | \& OPEN num 1 Mark this point in input as start of #n. | |
754 | \& CLOSE num 1 Analogous to OPEN. | |
755 | .Ve | |
756 | .PP | |
757 | .Vb 3 | |
758 | \& REF num 1 Match some already matched string | |
759 | \& REFF num 1 Match already matched string, folded | |
760 | \& REFFL num 1 Match already matched string, folded in loc. | |
761 | .Ve | |
762 | .PP | |
763 | .Vb 6 | |
764 | \& # grouping assertions | |
765 | \& IFMATCH off 1 2 Succeeds if the following matches. | |
766 | \& UNLESSM off 1 2 Fails if the following matches. | |
767 | \& SUSPEND off 1 1 "Independent" sub-regex. | |
768 | \& IFTHEN off 1 1 Switch, should be preceded by switcher . | |
769 | \& GROUPP num 1 Whether the group matched. | |
770 | .Ve | |
771 | .PP | |
772 | .Vb 3 | |
773 | \& # Support for long regex | |
774 | \& LONGJMP off 1 1 Jump far away. | |
775 | \& BRANCHJ off 1 1 BRANCH with long offset. | |
776 | .Ve | |
777 | .PP | |
778 | .Vb 2 | |
779 | \& # The heavy worker | |
780 | \& EVAL evl 1 Execute some Perl code. | |
781 | .Ve | |
782 | .PP | |
783 | .Vb 3 | |
784 | \& # Modifiers | |
785 | \& MINMOD no Next operator is not greedy. | |
786 | \& LOGICAL no Next opcode should set the flag only. | |
787 | .Ve | |
788 | .PP | |
789 | .Vb 2 | |
790 | \& # This is not used yet | |
791 | \& RENUM off 1 1 Group with independently numbered parens. | |
792 | .Ve | |
793 | .PP | |
794 | .Vb 3 | |
795 | \& # This is not really a node, but an optimized away piece of a "long" node. | |
796 | \& # To simplify debugging output, we mark it as if it were a node | |
797 | \& OPTIMIZED off Placeholder for dump. | |
798 | .Ve | |
799 | .PP | |
800 | Following the optimizer information is a dump of the offset/length | |
801 | table, here split across several lines: | |
802 | .PP | |
803 | .Vb 5 | |
804 | \& Offsets: [45] | |
805 | \& 1[4] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 5[1] | |
806 | \& 0[0] 12[1] 0[0] 6[1] 0[0] 7[1] 0[0] 9[1] 8[1] 0[0] 10[1] 0[0] | |
807 | \& 11[1] 0[0] 12[0] 12[0] 13[1] 0[0] 14[4] 0[0] 0[0] 0[0] 0[0] | |
808 | \& 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 18[1] 0[0] 19[1] 20[0] | |
809 | .Ve | |
810 | .PP | |
811 | The first line here indicates that the offset/length table contains 45 | |
812 | entries. Each entry is a pair of integers, denoted by \f(CW\*(C`offset[length]\*(C'\fR. | |
813 | Entries are numbered starting with 1, so entry #1 here is \f(CW\*(C`1[4]\*(C'\fR and | |
814 | entry #12 is \f(CW\*(C`5[1]\*(C'\fR. \f(CW\*(C`1[4]\*(C'\fR indicates that the node labeled \f(CW\*(C`1:\*(C'\fR | |
815 | (the \f(CW\*(C`1: ANYOF[bc]\*(C'\fR) begins at character position 1 in the | |
816 | pre-compiled form of the regex, and has a length of 4 characters. | |
817 | \&\f(CW\*(C`5[1]\*(C'\fR in position 12 | |
818 | indicates that the node labeled \f(CW\*(C`12:\*(C'\fR | |
819 | (the \f(CW\*(C`12: EXACT <d>\*(C'\fR) begins at character position 5 in the | |
820 | pre-compiled form of the regex, and has a length of 1 character. | |
821 | \&\f(CW\*(C`12[1]\*(C'\fR in position 14 | |
822 | indicates that the node labeled \f(CW\*(C`14:\*(C'\fR | |
823 | (the \f(CW\*(C`14: CURLYX[0] {1,32767}\*(C'\fR) begins at character position 12 in the | |
824 | pre-compiled form of the regex, and has a length of 1 character\-\-\-that | |
825 | is, it corresponds to the \f(CW\*(C`+\*(C'\fR symbol in the precompiled regex. | |
826 | .PP | |
827 | \&\f(CW\*(C`0[0]\*(C'\fR items indicate that there is no corresponding node. | |
828 | .Sh "Run-time output" | |
829 | .IX Subsection "Run-time output" | |
830 | First of all, when doing a match, one may get no run-time output even | |
831 | if debugging is enabled. This means that the regex engine was never | |
832 | entered and that all of the job was therefore done by the optimizer. | |
833 | .PP | |
834 | If the regex engine was entered, the output may look like this: | |
835 | .PP | |
836 | .Vb 25 | |
837 | \& Matching `[bc]d(ef*g)+h[ij]k$' against `abcdefg__gh__' | |
838 | \& Setting an EVAL scope, savestack=3 | |
839 | \& 2 <ab> <cdefg__gh_> | 1: ANYOF | |
840 | \& 3 <abc> <defg__gh_> | 11: EXACT <d> | |
841 | \& 4 <abcd> <efg__gh_> | 13: CURLYX {1,32767} | |
842 | \& 4 <abcd> <efg__gh_> | 26: WHILEM | |
843 | \& 0 out of 1..32767 cc=effff31c | |
844 | \& 4 <abcd> <efg__gh_> | 15: OPEN1 | |
845 | \& 4 <abcd> <efg__gh_> | 17: EXACT <e> | |
846 | \& 5 <abcde> <fg__gh_> | 19: STAR | |
847 | \& EXACT <f> can match 1 times out of 32767... | |
848 | \& Setting an EVAL scope, savestack=3 | |
849 | \& 6 <bcdef> <g__gh__> | 22: EXACT <g> | |
850 | \& 7 <bcdefg> <__gh__> | 24: CLOSE1 | |
851 | \& 7 <bcdefg> <__gh__> | 26: WHILEM | |
852 | \& 1 out of 1..32767 cc=effff31c | |
853 | \& Setting an EVAL scope, savestack=12 | |
854 | \& 7 <bcdefg> <__gh__> | 15: OPEN1 | |
855 | \& 7 <bcdefg> <__gh__> | 17: EXACT <e> | |
856 | \& restoring \e1 to 4(4)..7 | |
857 | \& failed, try continuation... | |
858 | \& 7 <bcdefg> <__gh__> | 27: NOTHING | |
859 | \& 7 <bcdefg> <__gh__> | 28: EXACT <h> | |
860 | \& failed... | |
861 | \& failed... | |
862 | .Ve | |
863 | .PP | |
864 | The most significant information in the output is about the particular \fInode\fR | |
865 | of the compiled regex that is currently being tested against the target string. | |
866 | The format of these lines is | |
867 | .PP | |
868 | \&\f(CW\*(C` \*(C'\fR\fISTRING-OFFSET\fR <\fIPRE-STRING\fR> <\fIPOST-STRING\fR> |\fI\s-1ID\s0\fR: \fI\s-1TYPE\s0\fR | |
869 | .PP | |
870 | The \fI\s-1TYPE\s0\fR info is indented with respect to the backtracking level. | |
871 | Other incidental information appears interspersed within. | |
872 | .SH "Debugging Perl memory usage" | |
873 | .IX Header "Debugging Perl memory usage" | |
874 | Perl is a profligate wastrel when it comes to memory use. There | |
875 | is a saying that to estimate memory usage of Perl, assume a reasonable | |
876 | algorithm for memory allocation, multiply that estimate by 10, and | |
877 | while you still may miss the mark, at least you won't be quite so | |
878 | astonished. This is not absolutely true, but may provide a good | |
879 | grasp of what happens. | |
880 | .PP | |
881 | Assume that an integer cannot take less than 20 bytes of memory, a | |
882 | float cannot take less than 24 bytes, a string cannot take less | |
883 | than 32 bytes (all these examples assume 32\-bit architectures, the | |
884 | result are quite a bit worse on 64\-bit architectures). If a variable | |
885 | is accessed in two of three different ways (which require an integer, | |
886 | a float, or a string), the memory footprint may increase yet another | |
887 | 20 bytes. A sloppy \fImalloc\fR\|(3) implementation can inflate these | |
888 | numbers dramatically. | |
889 | .PP | |
890 | On the opposite end of the scale, a declaration like | |
891 | .PP | |
892 | .Vb 1 | |
893 | \& sub foo; | |
894 | .Ve | |
895 | .PP | |
896 | may take up to 500 bytes of memory, depending on which release of Perl | |
897 | you're running. | |
898 | .PP | |
899 | Anecdotal estimates of source-to-compiled code bloat suggest an | |
900 | eightfold increase. This means that the compiled form of reasonable | |
901 | (normally commented, properly indented etc.) code will take | |
902 | about eight times more space in memory than the code took | |
903 | on disk. | |
904 | .PP | |
905 | The \fB\-DL\fR command-line switch is obsolete since circa Perl 5.6.0 | |
906 | (it was available only if Perl was built with \f(CW\*(C`\-DDEBUGGING\*(C'\fR). | |
907 | The switch was used to track Perl's memory allocations and possible | |
908 | memory leaks. These days the use of malloc debugging tools like | |
909 | \&\fIPurify\fR or \fIvalgrind\fR is suggested instead. | |
910 | .PP | |
911 | One way to find out how much memory is being used by Perl data | |
912 | structures is to install the Devel::Size module from \s-1CPAN:\s0 it gives | |
913 | you the minimum number of bytes required to store a particular data | |
914 | structure. Please be mindful of the difference between the \fIsize()\fR | |
915 | and \fItotal_size()\fR. | |
916 | .PP | |
917 | If Perl has been compiled using Perl's malloc you can analyze Perl | |
918 | memory usage by setting the \f(CW$ENV\fR{\s-1PERL_DEBUG_MSTATS\s0}. | |
919 | .ie n .Sh "Using $ENV{PERL_DEBUG_MSTATS}" | |
920 | .el .Sh "Using \f(CW$ENV{PERL_DEBUG_MSTATS}\fP" | |
921 | .IX Subsection "Using $ENV{PERL_DEBUG_MSTATS}" | |
922 | If your perl is using Perl's \fImalloc()\fR and was compiled with the | |
923 | necessary switches (this is the default), then it will print memory | |
924 | usage statistics after compiling your code when \f(CW\*(C`$ENV{PERL_DEBUG_MSTATS} | |
925 | > 1\*(C'\fR, and before termination of the program when \f(CW\*(C`$ENV{PERL_DEBUG_MSTATS} >= 1\*(C'\fR. The report format is similar to | |
926 | the following example: | |
927 | .PP | |
928 | .Vb 13 | |
929 | \& $ PERL_DEBUG_MSTATS=2 perl -e "require Carp" | |
930 | \& Memory allocation statistics after compilation: (buckets 4(4)..8188(8192) | |
931 | \& 14216 free: 130 117 28 7 9 0 2 2 1 0 0 | |
932 | \& 437 61 36 0 5 | |
933 | \& 60924 used: 125 137 161 55 7 8 6 16 2 0 1 | |
934 | \& 74 109 304 84 20 | |
935 | \& Total sbrk(): 77824/21:119. Odd ends: pad+heads+chain+tail: 0+636+0+2048. | |
936 | \& Memory allocation statistics after execution: (buckets 4(4)..8188(8192) | |
937 | \& 30888 free: 245 78 85 13 6 2 1 3 2 0 1 | |
938 | \& 315 162 39 42 11 | |
939 | \& 175816 used: 265 176 1112 111 26 22 11 27 2 1 1 | |
940 | \& 196 178 1066 798 39 | |
941 | \& Total sbrk(): 215040/47:145. Odd ends: pad+heads+chain+tail: 0+2192+0+6144. | |
942 | .Ve | |
943 | .PP | |
944 | It is possible to ask for such a statistic at arbitrary points in | |
945 | your execution using the \fImstat()\fR function out of the standard | |
946 | Devel::Peek module. | |
947 | .PP | |
948 | Here is some explanation of that format: | |
949 | .ie n .IP """buckets SMALLEST(APPROX)..GREATEST(APPROX)""" 4 | |
950 | .el .IP "\f(CWbuckets SMALLEST(APPROX)..GREATEST(APPROX)\fR" 4 | |
951 | .IX Item "buckets SMALLEST(APPROX)..GREATEST(APPROX)" | |
952 | Perl's \fImalloc()\fR uses bucketed allocations. Every request is rounded | |
953 | up to the closest bucket size available, and a bucket is taken from | |
954 | the pool of buckets of that size. | |
955 | .Sp | |
956 | The line above describes the limits of buckets currently in use. | |
957 | Each bucket has two sizes: memory footprint and the maximal size | |
958 | of user data that can fit into this bucket. Suppose in the above | |
959 | example that the smallest bucket were size 4. The biggest bucket | |
960 | would have usable size 8188, and the memory footprint would be 8192. | |
961 | .Sp | |
962 | In a Perl built for debugging, some buckets may have negative usable | |
963 | size. This means that these buckets cannot (and will not) be used. | |
964 | For larger buckets, the memory footprint may be one page greater | |
965 | than a power of 2. If so, case the corresponding power of two is | |
966 | printed in the \f(CW\*(C`APPROX\*(C'\fR field above. | |
967 | .IP "Free/Used" 4 | |
968 | .IX Item "Free/Used" | |
969 | The 1 or 2 rows of numbers following that correspond to the number | |
970 | of buckets of each size between \f(CW\*(C`SMALLEST\*(C'\fR and \f(CW\*(C`GREATEST\*(C'\fR. In | |
971 | the first row, the sizes (memory footprints) of buckets are powers | |
972 | of two\*(--or possibly one page greater. In the second row, if present, | |
973 | the memory footprints of the buckets are between the memory footprints | |
974 | of two buckets \*(L"above\*(R". | |
975 | .Sp | |
976 | For example, suppose under the previous example, the memory footprints | |
977 | were | |
978 | .Sp | |
979 | .Vb 2 | |
980 | \& free: 8 16 32 64 128 256 512 1024 2048 4096 8192 | |
981 | \& 4 12 24 48 80 | |
982 | .Ve | |
983 | .Sp | |
984 | With non\-\f(CW\*(C`DEBUGGING\*(C'\fR perl, the buckets starting from \f(CW128\fR have | |
985 | a 4\-byte overhead, and thus an 8192\-long bucket may take up to | |
986 | 8188\-byte allocations. | |
987 | .ie n .IP """Total sbrk(): SBRKed/SBRKs:CONTINUOUS""" 4 | |
988 | .el .IP "\f(CWTotal sbrk(): SBRKed/SBRKs:CONTINUOUS\fR" 4 | |
989 | .IX Item "Total sbrk(): SBRKed/SBRKs:CONTINUOUS" | |
990 | The first two fields give the total amount of memory perl \fIsbrk\fR\|(2)ed | |
991 | (ess\-broken? :\-) and number of \fIsbrk\fR\|(2)s used. The third number is | |
992 | what perl thinks about continuity of returned chunks. So long as | |
993 | this number is positive, \fImalloc()\fR will assume that it is probable | |
994 | that \fIsbrk\fR\|(2) will provide continuous memory. | |
995 | .Sp | |
996 | Memory allocated by external libraries is not counted. | |
997 | .ie n .IP """pad: 0""" 4 | |
998 | .el .IP "\f(CWpad: 0\fR" 4 | |
999 | .IX Item "pad: 0" | |
1000 | The amount of \fIsbrk\fR\|(2)ed memory needed to keep buckets aligned. | |
1001 | .ie n .IP """heads: 2192""" 4 | |
1002 | .el .IP "\f(CWheads: 2192\fR" 4 | |
1003 | .IX Item "heads: 2192" | |
1004 | Although memory overhead of bigger buckets is kept inside the bucket, for | |
1005 | smaller buckets, it is kept in separate areas. This field gives the | |
1006 | total size of these areas. | |
1007 | .ie n .IP """chain: 0""" 4 | |
1008 | .el .IP "\f(CWchain: 0\fR" 4 | |
1009 | .IX Item "chain: 0" | |
1010 | \&\fImalloc()\fR may want to subdivide a bigger bucket into smaller buckets. | |
1011 | If only a part of the deceased bucket is left unsubdivided, the rest | |
1012 | is kept as an element of a linked list. This field gives the total | |
1013 | size of these chunks. | |
1014 | .ie n .IP """tail: 6144""" 4 | |
1015 | .el .IP "\f(CWtail: 6144\fR" 4 | |
1016 | .IX Item "tail: 6144" | |
1017 | To minimize the number of \fIsbrk\fR\|(2)s, \fImalloc()\fR asks for more memory. This | |
1018 | field gives the size of the yet unused part, which is \fIsbrk\fR\|(2)ed, but | |
1019 | never touched. | |
1020 | .SH "SEE ALSO" | |
1021 | .IX Header "SEE ALSO" | |
1022 | perldebug, | |
1023 | perlguts, | |
1024 | perlrun | |
1025 | re, | |
1026 | and | |
1027 | Devel::DProf. |