Commit | Line | Data |
---|---|---|
a0d0e21e LW |
1 | =head1 NAME |
2 | ||
3 | perldebug - Perl debugging | |
4 | ||
5 | =head1 DESCRIPTION | |
6 | ||
7 | First of all, have you tried using the B<-w> switch? | |
8 | ||
4e1d3b43 | 9 | =head1 The Perl Debugger |
10 | ||
26f28346 GB |
11 | "As soon as we started programming, we found to our |
12 | surprise that it wasn't as easy to get programs right | |
13 | as we had thought. Debugging had to be discovered. | |
14 | I can remember the exact instant when I realized that | |
15 | a large part of my life from then on was going to be | |
16 | spent in finding mistakes in my own programs." | |
84902520 TB |
17 | |
18 | I< --Maurice Wilkes, 1949> | |
26f28346 | 19 | |
4e1d3b43 | 20 | If you invoke Perl with the B<-d> switch, your script runs under the |
21 | Perl source debugger. This works like an interactive Perl | |
22 | environment, prompting for debugger commands that let you examine | |
68dc0745 | 23 | source code, set breakpoints, get stack backtraces, change the values of |
4e1d3b43 | 24 | variables, etc. This is so convenient that you often fire up |
54310121 | 25 | the debugger all by itself just to test out Perl constructs |
4e1d3b43 | 26 | interactively to see what they do. For example: |
27 | ||
28 | perl -d -e 42 | |
29 | ||
30 | In Perl, the debugger is not a separate program as it usually is in the | |
31 | typical compiled environment. Instead, the B<-d> flag tells the compiler | |
32 | to insert source information into the parse trees it's about to hand off | |
33 | to the interpreter. That means your code must first compile correctly | |
34 | for the debugger to work on it. Then when the interpreter starts up, it | |
54310121 | 35 | preloads a Perl library file containing the debugger itself. |
4e1d3b43 | 36 | |
37 | The program will halt I<right before> the first run-time executable | |
38 | statement (but see below regarding compile-time statements) and ask you | |
39 | to enter a debugger command. Contrary to popular expectations, whenever | |
40 | the debugger halts and shows you a line of code, it always displays the | |
41 | line it's I<about> to execute, rather than the one it has just executed. | |
42 | ||
43 | Any command not recognized by the debugger is directly executed | |
44 | (C<eval>'d) as Perl code in the current package. (The debugger uses the | |
45 | DB package for its own state information.) | |
46 | ||
47 | Leading white space before a command would cause the debugger to think | |
48 | it's I<NOT> a debugger command but for Perl, so be careful not to do | |
49 | that. | |
50 | ||
51 | =head2 Debugger Commands | |
52 | ||
53 | The debugger understands the following commands: | |
a0d0e21e LW |
54 | |
55 | =over 12 | |
56 | ||
4e1d3b43 | 57 | =item h [command] |
58 | ||
54310121 | 59 | Prints out a help message. |
4e1d3b43 | 60 | |
61 | If you supply another debugger command as an argument to the C<h> command, | |
62 | it prints out the description for just that command. The special | |
63 | argument of C<h h> produces a more compact help listing, designed to fit | |
64 | together on one screen. | |
65 | ||
7b8d334a | 66 | If the output of the C<h> command (or any command, for that matter) scrolls |
4e1d3b43 | 67 | past your screen, either precede the command with a leading pipe symbol so |
68 | it's run through your pager, as in | |
69 | ||
70 | DB> |h | |
71 | ||
e7ea3e70 IZ |
72 | You may change the pager which is used via C<O pager=...> command. |
73 | ||
4e1d3b43 | 74 | =item p expr |
75 | ||
36477c24 | 76 | Same as C<print {$DB::OUT} expr> in the current package. In particular, |
5f05dabc | 77 | because this is just Perl's own B<print> function, this means that nested |
4e1d3b43 | 78 | data structures and objects are not dumped, unlike with the C<x> command. |
79 | ||
e7ea3e70 IZ |
80 | The C<DB::OUT> filehandle is opened to F</dev/tty>, regardless of |
81 | where STDOUT may be redirected to. | |
82 | ||
4e1d3b43 | 83 | =item x expr |
84 | ||
54310121 | 85 | Evaluates its expression in list context and dumps out the result |
4e1d3b43 | 86 | in a pretty-printed fashion. Nested data structures are printed out |
87 | recursively, unlike the C<print> function. | |
88 | ||
36477c24 | 89 | The details of printout are governed by multiple C<O>ptions. |
90 | ||
4e1d3b43 | 91 | =item V [pkg [vars]] |
92 | ||
93 | Display all (or some) variables in package (defaulting to the C<main> | |
94 | package) using a data pretty-printer (hashes show their keys and values so | |
95 | you see what's what, control characters are made printable, etc.). Make | |
96 | sure you don't put the type specifier (like C<$>) there, just the symbol | |
97 | names, like this: | |
98 | ||
99 | V DB filename line | |
100 | ||
101 | Use C<~pattern> and C<!pattern> for positive and negative regexps. | |
a0d0e21e | 102 | |
4e1d3b43 | 103 | Nested data structures are printed out in a legible fashion, unlike |
104 | the C<print> function. | |
105 | ||
36477c24 | 106 | The details of printout are governed by multiple C<O>ptions. |
107 | ||
4e1d3b43 | 108 | =item X [vars] |
109 | ||
110 | Same as C<V currentpackage [vars]>. | |
a0d0e21e LW |
111 | |
112 | =item T | |
113 | ||
68dc0745 | 114 | Produce a stack backtrace. See below for details on its output. |
a0d0e21e | 115 | |
4e1d3b43 | 116 | =item s [expr] |
a0d0e21e LW |
117 | |
118 | Single step. Executes until it reaches the beginning of another | |
4e1d3b43 | 119 | statement, descending into subroutine calls. If an expression is |
120 | supplied that includes function calls, it too will be single-stepped. | |
a0d0e21e | 121 | |
e7ea3e70 | 122 | =item n [expr] |
a0d0e21e LW |
123 | |
124 | Next. Executes over subroutine calls, until it reaches the beginning | |
774d564b | 125 | of the next statement. If an expression is supplied that includes |
126 | function calls, those functions will be executed with stops before | |
127 | each statement. | |
a0d0e21e | 128 | |
184e9718 | 129 | =item E<lt>CRE<gt> |
a0d0e21e | 130 | |
4e1d3b43 | 131 | Repeat last C<n> or C<s> command. |
a0d0e21e | 132 | |
36477c24 | 133 | =item c [line|sub] |
a0d0e21e | 134 | |
4e1d3b43 | 135 | Continue, optionally inserting a one-time-only breakpoint |
36477c24 | 136 | at the specified line or subroutine. |
a0d0e21e | 137 | |
4e1d3b43 | 138 | =item l |
a0d0e21e | 139 | |
4e1d3b43 | 140 | List next window of lines. |
a0d0e21e LW |
141 | |
142 | =item l min+incr | |
143 | ||
4e1d3b43 | 144 | List C<incr+1> lines starting at C<min>. |
a0d0e21e LW |
145 | |
146 | =item l min-max | |
147 | ||
774d564b | 148 | List lines C<min> through C<max>. C<l -> is synonymous to C<->. |
a0d0e21e LW |
149 | |
150 | =item l line | |
151 | ||
4e1d3b43 | 152 | List a single line. |
a0d0e21e | 153 | |
4e1d3b43 | 154 | =item l subname |
a0d0e21e | 155 | |
4e1d3b43 | 156 | List first window of lines from subroutine. |
a0d0e21e LW |
157 | |
158 | =item - | |
159 | ||
4e1d3b43 | 160 | List previous window of lines. |
a0d0e21e | 161 | |
4e1d3b43 | 162 | =item w [line] |
a0d0e21e | 163 | |
4e1d3b43 | 164 | List window (a few lines) around the current line. |
a0d0e21e | 165 | |
4e1d3b43 | 166 | =item . |
a0d0e21e | 167 | |
4e1d3b43 | 168 | Return debugger pointer to the last-executed line and |
169 | print it out. | |
170 | ||
171 | =item f filename | |
172 | ||
774d564b | 173 | Switch to viewing a different file or eval statement. If C<filename> |
e7ea3e70 IZ |
174 | is not a full filename as found in values of %INC, it is considered as |
175 | a regexp. | |
a0d0e21e LW |
176 | |
177 | =item /pattern/ | |
178 | ||
4e1d3b43 | 179 | Search forwards for pattern; final / is optional. |
a0d0e21e LW |
180 | |
181 | =item ?pattern? | |
182 | ||
4e1d3b43 | 183 | Search backwards for pattern; final ? is optional. |
a0d0e21e LW |
184 | |
185 | =item L | |
186 | ||
36477c24 | 187 | List all breakpoints and actions. |
a0d0e21e | 188 | |
4e1d3b43 | 189 | =item S [[!]pattern] |
a0d0e21e | 190 | |
4e1d3b43 | 191 | List subroutine names [not] matching pattern. |
a0d0e21e LW |
192 | |
193 | =item t | |
194 | ||
36477c24 | 195 | Toggle trace mode (see also C<AutoTrace> C<O>ption). |
4e1d3b43 | 196 | |
197 | =item t expr | |
198 | ||
199 | Trace through execution of expr. For example: | |
200 | ||
201 | $ perl -de 42 | |
202 | Stack dump during die enabled outside of evals. | |
a0d0e21e | 203 | |
4e1d3b43 | 204 | Loading DB routines from perl5db.pl patch level 0.94 |
205 | Emacs support available. | |
206 | ||
207 | Enter h or `h h' for help. | |
208 | ||
209 | main::(-e:1): 0 | |
210 | DB<1> sub foo { 14 } | |
211 | ||
212 | DB<2> sub bar { 3 } | |
213 | ||
214 | DB<3> t print foo() * bar() | |
215 | main::((eval 172):3): print foo() + bar(); | |
216 | main::foo((eval 168):2): | |
217 | main::bar((eval 170):2): | |
218 | 42 | |
36477c24 | 219 | |
220 | or, with the C<O>ption C<frame=2> set, | |
221 | ||
222 | DB<4> O f=2 | |
223 | frame = '2' | |
224 | DB<5> t print foo() * bar() | |
225 | 3: foo() * bar() | |
226 | entering main::foo | |
227 | 2: sub foo { 14 }; | |
228 | exited main::foo | |
229 | entering main::bar | |
230 | 2: sub bar { 3 }; | |
231 | exited main::bar | |
232 | 42 | |
4e1d3b43 | 233 | |
234 | =item b [line] [condition] | |
a0d0e21e LW |
235 | |
236 | Set a breakpoint. If line is omitted, sets a breakpoint on the line | |
4e1d3b43 | 237 | that is about to be executed. If a condition is specified, it's |
a0d0e21e | 238 | evaluated each time the statement is reached and a breakpoint is taken |
5f05dabc | 239 | only if the condition is true. Breakpoints may be set on only lines |
4e1d3b43 | 240 | that begin an executable statement. Conditions don't use B<if>: |
a0d0e21e LW |
241 | |
242 | b 237 $x > 30 | |
36477c24 | 243 | b 237 ++$count237 < 11 |
a0d0e21e LW |
244 | b 33 /pattern/i |
245 | ||
4e1d3b43 | 246 | =item b subname [condition] |
a0d0e21e | 247 | |
4e1d3b43 | 248 | Set a breakpoint at the first line of the named subroutine. |
a0d0e21e | 249 | |
36477c24 | 250 | =item b postpone subname [condition] |
251 | ||
252 | Set breakpoint at first line of subroutine after it is compiled. | |
253 | ||
254 | =item b load filename | |
255 | ||
774d564b | 256 | Set breakpoint at the first executed line of the file. Filename should |
e7ea3e70 IZ |
257 | be a full name as found in values of %INC. |
258 | ||
259 | =item b compile subname | |
260 | ||
261 | Sets breakpoint at the first statement executed after the subroutine | |
262 | is compiled. | |
36477c24 | 263 | |
4e1d3b43 | 264 | =item d [line] |
a0d0e21e | 265 | |
4e1d3b43 | 266 | Delete a breakpoint at the specified line. If line is omitted, deletes |
267 | the breakpoint on the line that is about to be executed. | |
a0d0e21e LW |
268 | |
269 | =item D | |
270 | ||
4e1d3b43 | 271 | Delete all installed breakpoints. |
272 | ||
273 | =item a [line] command | |
274 | ||
275 | Set an action to be done before the line is executed. | |
276 | The sequence of steps taken by the debugger is | |
277 | ||
8ebc5c01 | 278 | 1. check for a breakpoint at this line |
279 | 2. print the line if necessary (tracing) | |
280 | 3. do any actions associated with that line | |
281 | 4. prompt user if at a breakpoint or in single-step | |
282 | 5. evaluate line | |
a0d0e21e | 283 | |
7b8d334a | 284 | For example, this will print out $foo every time line |
4e1d3b43 | 285 | 53 is passed: |
a0d0e21e | 286 | |
4e1d3b43 | 287 | a 53 print "DB FOUND $foo\n" |
a0d0e21e LW |
288 | |
289 | =item A | |
290 | ||
4e1d3b43 | 291 | Delete all installed actions. |
292 | ||
6ee623d5 GS |
293 | =item W [expr] |
294 | ||
295 | Add a global watch-expression. | |
296 | ||
297 | =item W | |
298 | ||
299 | Delete all watch-expressions. | |
300 | ||
4e1d3b43 | 301 | =item O [opt[=val]] [opt"val"] [opt?]... |
302 | ||
303 | Set or query values of options. val defaults to 1. opt can | |
304 | be abbreviated. Several options can be listed. | |
305 | ||
306 | =over 12 | |
307 | ||
e7ea3e70 | 308 | =item C<recallCommand>, C<ShellBang> |
4e1d3b43 | 309 | |
310 | The characters used to recall command or spawn shell. By | |
311 | default, these are both set to C<!>. | |
312 | ||
e7ea3e70 | 313 | =item C<pager> |
4e1d3b43 | 314 | |
315 | Program to use for output of pager-piped commands (those | |
316 | beginning with a C<|> character.) By default, | |
317 | C<$ENV{PAGER}> will be used. | |
318 | ||
e7ea3e70 | 319 | =item C<tkRunning> |
36477c24 | 320 | |
321 | Run Tk while prompting (with ReadLine). | |
322 | ||
e7ea3e70 IZ |
323 | =item C<signalLevel>, C<warnLevel>, C<dieLevel> |
324 | ||
774d564b | 325 | Level of verbosity. By default the debugger is in a sane verbose mode, |
e7ea3e70 IZ |
326 | thus it will print backtraces on all the warnings and die-messages |
327 | which are going to be printed out, and will print a message when | |
54310121 | 328 | interesting uncaught signals arrive. |
36477c24 | 329 | |
774d564b | 330 | To disable this behaviour, set these values to 0. If C<dieLevel> is 2, |
e7ea3e70 IZ |
331 | then the messages which will be caught by surrounding C<eval> are also |
332 | printed. | |
36477c24 | 333 | |
e7ea3e70 | 334 | =item C<AutoTrace> |
36477c24 | 335 | |
e7ea3e70 IZ |
336 | Trace mode (similar to C<t> command, but can be put into |
337 | C<PERLDB_OPTS>). | |
36477c24 | 338 | |
e7ea3e70 | 339 | =item C<LineInfo> |
36477c24 | 340 | |
e7ea3e70 IZ |
341 | File or pipe to print line number info to. If it is a pipe (say, |
342 | C<|visual_perl_db>), then a short, "emacs like" message is used. | |
36477c24 | 343 | |
344 | =item C<inhibit_exit> | |
345 | ||
346 | If 0, allows I<stepping off> the end of the script. | |
347 | ||
54310121 | 348 | =item C<PrintRet> |
36477c24 | 349 | |
350 | affects printing of return value after C<r> command. | |
351 | ||
28d1fb14 IZ |
352 | =item C<ornaments> |
353 | ||
3e3baf6d | 354 | affects screen appearance of the command line (see L<Term::ReadLine>). |
28d1fb14 | 355 | |
54310121 | 356 | =item C<frame> |
36477c24 | 357 | |
358 | affects printing messages on entry and exit from subroutines. If | |
359 | C<frame & 2> is false, messages are printed on entry only. (Printing | |
5f05dabc | 360 | on exit may be useful if inter(di)spersed with other messages.) |
36477c24 | 361 | |
362 | If C<frame & 4>, arguments to functions are printed as well as the | |
774d564b | 363 | context and caller info. If C<frame & 8>, overloaded C<stringify> and |
28d1fb14 IZ |
364 | C<tie>d C<FETCH> are enabled on the printed arguments. If C<frame & |
365 | 16>, the return value from the subroutine is printed as well. | |
366 | ||
367 | The length at which the argument list is truncated is governed by the | |
368 | next option: | |
e7ea3e70 IZ |
369 | |
370 | =item C<maxTraceLen> | |
371 | ||
372 | length at which the argument list is truncated when C<frame> option's | |
373 | bit 4 is set. | |
36477c24 | 374 | |
4e1d3b43 | 375 | =back |
376 | ||
377 | The following options affect what happens with C<V>, C<X>, and C<x> | |
378 | commands: | |
379 | ||
380 | =over 12 | |
381 | ||
e7ea3e70 | 382 | =item C<arrayDepth>, C<hashDepth> |
4e1d3b43 | 383 | |
384 | Print only first N elements ('' for all). | |
385 | ||
e7ea3e70 | 386 | =item C<compactDump>, C<veryCompact> |
4e1d3b43 | 387 | |
774d564b | 388 | Change style of array and hash dump. If C<compactDump>, short array |
e7ea3e70 | 389 | may be printed on one line. |
4e1d3b43 | 390 | |
e7ea3e70 | 391 | =item C<globPrint> |
4e1d3b43 | 392 | |
393 | Whether to print contents of globs. | |
394 | ||
e7ea3e70 | 395 | =item C<DumpDBFiles> |
4e1d3b43 | 396 | |
397 | Dump arrays holding debugged files. | |
398 | ||
e7ea3e70 | 399 | =item C<DumpPackages> |
4e1d3b43 | 400 | |
401 | Dump symbol tables of packages. | |
402 | ||
6ee623d5 GS |
403 | =item C<DumpReused> |
404 | ||
405 | Dump contents of "reused" addresses. | |
406 | ||
e7ea3e70 IZ |
407 | =item C<quote>, C<HighBit>, C<undefPrint> |
408 | ||
774d564b | 409 | Change style of string dump. Default value of C<quote> is C<auto>, one |
e7ea3e70 | 410 | can enable either double-quotish dump, or single-quotish by setting it |
774d564b | 411 | to C<"> or C<'>. By default, characters with high bit set are printed |
e7ea3e70 IZ |
412 | I<as is>. |
413 | ||
54310121 | 414 | =item C<UsageOnly> |
4e1d3b43 | 415 | |
774d564b | 416 | I<very> rudimentally per-package memory usage dump. Calculates total |
e7ea3e70 | 417 | size of strings in variables in the package. |
4e1d3b43 | 418 | |
36477c24 | 419 | =back |
4e1d3b43 | 420 | |
36477c24 | 421 | During startup options are initialized from C<$ENV{PERLDB_OPTS}>. |
422 | You can put additional initialization options C<TTY>, C<noTTY>, | |
423 | C<ReadLine>, and C<NonStop> there. | |
424 | ||
425 | Example rc file: | |
4e1d3b43 | 426 | |
e7ea3e70 | 427 | &parse_options("NonStop=1 LineInfo=db.out AutoTrace"); |
4e1d3b43 | 428 | |
36477c24 | 429 | The script will run without human intervention, putting trace information |
430 | into the file I<db.out>. (If you interrupt it, you would better reset | |
431 | C<LineInfo> to something "interactive"!) | |
4e1d3b43 | 432 | |
36477c24 | 433 | =over 12 |
4e1d3b43 | 434 | |
36477c24 | 435 | =item C<TTY> |
4e1d3b43 | 436 | |
36477c24 | 437 | The TTY to use for debugging I/O. |
438 | ||
36477c24 | 439 | =item C<noTTY> |
440 | ||
774d564b | 441 | If set, goes in C<NonStop> mode, and would not connect to a TTY. If |
36477c24 | 442 | interrupt (or if control goes to debugger via explicit setting of |
443 | $DB::signal or $DB::single from the Perl script), connects to a TTY | |
444 | specified by the C<TTY> option at startup, or to a TTY found at | |
445 | runtime using C<Term::Rendezvous> module of your choice. | |
446 | ||
447 | This module should implement a method C<new> which returns an object | |
448 | with two methods: C<IN> and C<OUT>, returning two filehandles to use | |
774d564b | 449 | for debugging input and output correspondingly. Method C<new> may |
36477c24 | 450 | inspect an argument which is a value of C<$ENV{PERLDB_NOTTY}> at |
451 | startup, or is C<"/tmp/perldbtty$$"> otherwise. | |
452 | ||
453 | =item C<ReadLine> | |
454 | ||
455 | If false, readline support in debugger is disabled, so you can debug | |
456 | ReadLine applications. | |
457 | ||
458 | =item C<NonStop> | |
459 | ||
54310121 | 460 | If set, debugger goes into noninteractive mode until interrupted, or |
36477c24 | 461 | programmatically by setting $DB::signal or $DB::single. |
462 | ||
463 | =back | |
464 | ||
465 | Here's an example of using the C<$ENV{PERLDB_OPTS}> variable: | |
4e1d3b43 | 466 | |
e7ea3e70 | 467 | $ PERLDB_OPTS="N f=2" perl -d myprogram |
4e1d3b43 | 468 | |
469 | will run the script C<myprogram> without human intervention, printing | |
470 | out the call tree with entry and exit points. Note that C<N f=2> is | |
774d564b | 471 | equivalent to C<NonStop=1 frame=2>. Note also that at the moment when |
4e1d3b43 | 472 | this documentation was written all the options to the debugger could |
36477c24 | 473 | be uniquely abbreviated by the first letter (with exception of |
474 | C<Dump*> options). | |
4e1d3b43 | 475 | |
36477c24 | 476 | Other examples may include |
a0d0e21e | 477 | |
e7ea3e70 | 478 | $ PERLDB_OPTS="N f A L=listing" perl -d myprogram |
a0d0e21e | 479 | |
54310121 | 480 | - runs script noninteractively, printing info on each entry into a |
36477c24 | 481 | subroutine and each executed line into the file F<listing>. (If you |
482 | interrupt it, you would better reset C<LineInfo> to something | |
483 | "interactive"!) | |
484 | ||
485 | ||
e7ea3e70 | 486 | $ env "PERLDB_OPTS=R=0 TTY=/dev/ttyc" perl -d myprogram |
36477c24 | 487 | |
488 | may be useful for debugging a program which uses C<Term::ReadLine> | |
774d564b | 489 | itself. Do not forget detach shell from the TTY in the window which |
36477c24 | 490 | corresponds to F</dev/ttyc>, say, by issuing a command like |
491 | ||
e7ea3e70 | 492 | $ sleep 1000000 |
36477c24 | 493 | |
494 | See L<"Debugger Internals"> below for more details. | |
495 | ||
496 | =item E<lt> [ command ] | |
497 | ||
498 | Set an action (Perl command) to happen before every debugger prompt. | |
4a6725af | 499 | A multi-line command may be entered by backslashing the newlines. If |
36477c24 | 500 | C<command> is missing, resets the list of actions. |
501 | ||
502 | =item E<lt>E<lt> command | |
503 | ||
504 | Add an action (Perl command) to happen before every debugger prompt. | |
4a6725af | 505 | A multi-line command may be entered by backslashing the newlines. |
a0d0e21e | 506 | |
184e9718 | 507 | =item E<gt> command |
a0d0e21e | 508 | |
36477c24 | 509 | Set an action (Perl command) to happen after the prompt when you've |
4a6725af | 510 | just given a command to return to executing the script. A multi-line |
36477c24 | 511 | command may be entered by backslashing the newlines. If C<command> is |
512 | missing, resets the list of actions. | |
513 | ||
514 | =item E<gt>E<gt> command | |
515 | ||
516 | Adds an action (Perl command) to happen after the prompt when you've | |
4a6725af | 517 | just given a command to return to executing the script. A multi-line |
36477c24 | 518 | command may be entered by backslashing the newlines. |
519 | ||
520 | =item { [ command ] | |
521 | ||
522 | Set an action (debugger command) to happen before every debugger prompt. | |
4a6725af | 523 | A multi-line command may be entered by backslashing the newlines. If |
36477c24 | 524 | C<command> is missing, resets the list of actions. |
525 | ||
526 | =item {{ command | |
527 | ||
528 | Add an action (debugger command) to happen before every debugger prompt. | |
4a6725af | 529 | A multi-line command may be entered by backslashing the newlines. |
a0d0e21e | 530 | |
4e1d3b43 | 531 | =item ! number |
a0d0e21e | 532 | |
4e1d3b43 | 533 | Redo a previous command (default previous command). |
a0d0e21e | 534 | |
4e1d3b43 | 535 | =item ! -number |
a0d0e21e | 536 | |
4e1d3b43 | 537 | Redo number'th-to-last command. |
a0d0e21e | 538 | |
4e1d3b43 | 539 | =item ! pattern |
a0d0e21e | 540 | |
4e1d3b43 | 541 | Redo last command that started with pattern. |
542 | See C<O recallCommand>, too. | |
a0d0e21e | 543 | |
4e1d3b43 | 544 | =item !! cmd |
a0d0e21e | 545 | |
4e1d3b43 | 546 | Run cmd in a subprocess (reads from DB::IN, writes to DB::OUT) |
547 | See C<O shellBang> too. | |
a0d0e21e LW |
548 | |
549 | =item H -number | |
550 | ||
551 | Display last n commands. Only commands longer than one character are | |
552 | listed. If number is omitted, lists them all. | |
553 | ||
554 | =item q or ^D | |
555 | ||
36477c24 | 556 | Quit. ("quit" doesn't work for this.) This is the only supported way |
557 | to exit the debugger, though typing C<exit> twice may do it too. | |
558 | ||
559 | Set an C<O>ption C<inhibit_exit> to 0 if you want to be able to I<step | |
19799a22 | 560 | off> the end the script. You may also need to set $finished to 0 at |
36477c24 | 561 | some moment if you want to step through global destruction. |
a0d0e21e | 562 | |
4e1d3b43 | 563 | =item R |
564 | ||
565 | Restart the debugger by B<exec>ing a new session. It tries to maintain | |
566 | your history across this, but internal settings and command line options | |
567 | may be lost. | |
568 | ||
5f05dabc | 569 | Currently the following setting are preserved: history, breakpoints, |
54310121 | 570 | actions, debugger C<O>ptions, and the following command line |
5f05dabc | 571 | options: B<-w>, B<-I>, and B<-e>. |
36477c24 | 572 | |
4e1d3b43 | 573 | =item |dbcmd |
574 | ||
575 | Run debugger command, piping DB::OUT to current pager. | |
576 | ||
577 | =item ||dbcmd | |
578 | ||
579 | Same as C<|dbcmd> but DB::OUT is temporarily B<select>ed as well. | |
580 | Often used with commands that would otherwise produce long | |
581 | output, such as | |
582 | ||
583 | |V main | |
584 | ||
585 | =item = [alias value] | |
586 | ||
e7ea3e70 IZ |
587 | Define a command alias, like |
588 | ||
589 | = quit q | |
590 | ||
591 | or list current aliases. | |
4e1d3b43 | 592 | |
a0d0e21e LW |
593 | =item command |
594 | ||
595 | Execute command as a Perl statement. A missing semicolon will be | |
596 | supplied. | |
597 | ||
e7ea3e70 | 598 | =item m expr |
a0d0e21e | 599 | |
e7ea3e70 IZ |
600 | The expression is evaluated, and the methods which may be applied to |
601 | the result are listed. | |
602 | ||
603 | =item m package | |
604 | ||
605 | The methods which may be applied to objects in the C<package> are listed. | |
a0d0e21e LW |
606 | |
607 | =back | |
608 | ||
e7ea3e70 IZ |
609 | =head2 Debugger input/output |
610 | ||
611 | =over 8 | |
612 | ||
613 | =item Prompt | |
614 | ||
4e1d3b43 | 615 | The debugger prompt is something like |
616 | ||
617 | DB<8> | |
618 | ||
619 | or even | |
620 | ||
621 | DB<<17>> | |
622 | ||
623 | where that number is the command number, which you'd use to access with | |
54310121 | 624 | the builtin B<csh>-like history mechanism, e.g., C<!17> would repeat |
4e1d3b43 | 625 | command number 17. The number of angle brackets indicates the depth of |
626 | the debugger. You could get more than one set of brackets, for example, if | |
627 | you'd already at a breakpoint and then printed out the result of a | |
36477c24 | 628 | function call that itself also has a breakpoint, or you step into an |
629 | expression via C<s/n/t expression> command. | |
4e1d3b43 | 630 | |
54310121 | 631 | =item Multiline commands |
e7ea3e70 | 632 | |
4a6725af | 633 | If you want to enter a multi-line command, such as a subroutine |
e7ea3e70 IZ |
634 | definition with several statements, or a format, you may escape the |
635 | newline that would normally end the debugger command with a backslash. | |
636 | Here's an example: | |
a0d0e21e | 637 | |
4e1d3b43 | 638 | DB<1> for (1..4) { \ |
639 | cont: print "ok\n"; \ | |
640 | cont: } | |
641 | ok | |
642 | ok | |
643 | ok | |
644 | ok | |
645 | ||
646 | Note that this business of escaping a newline is specific to interactive | |
647 | commands typed into the debugger. | |
648 | ||
e7ea3e70 IZ |
649 | =item Stack backtrace |
650 | ||
68dc0745 | 651 | Here's an example of what a stack backtrace via C<T> command might |
e7ea3e70 | 652 | look like: |
4e1d3b43 | 653 | |
654 | $ = main::infested called from file `Ambulation.pm' line 10 | |
655 | @ = Ambulation::legs(1, 2, 3, 4) called from file `camel_flea' line 7 | |
656 | $ = main::pests('bactrian', 4) called from file `camel_flea' line 4 | |
657 | ||
658 | The left-hand character up there tells whether the function was called | |
659 | in a scalar or list context (we bet you can tell which is which). What | |
660 | that says is that you were in the function C<main::infested> when you ran | |
661 | the stack dump, and that it was called in a scalar context from line 10 | |
662 | of the file I<Ambulation.pm>, but without any arguments at all, meaning | |
663 | it was called as C<&infested>. The next stack frame shows that the | |
664 | function C<Ambulation::legs> was called in a list context from the | |
665 | I<camel_flea> file with four arguments. The last stack frame shows that | |
666 | C<main::pests> was called in a scalar context, also from I<camel_flea>, | |
667 | but from line 4. | |
668 | ||
e7ea3e70 | 669 | Note that if you execute C<T> command from inside an active C<use> |
7b8d334a GS |
670 | statement, the backtrace will contain both C<require> |
671 | frame and an C<eval>) frame. | |
e7ea3e70 IZ |
672 | |
673 | =item Listing | |
674 | ||
675 | Listing given via different flavors of C<l> command looks like this: | |
676 | ||
677 | DB<<13>> l | |
678 | 101: @i{@i} = (); | |
679 | 102:b @isa{@i,$pack} = () | |
680 | 103 if(exists $i{$prevpack} || exists $isa{$pack}); | |
681 | 104 } | |
682 | 105 | |
683 | 106 next | |
684 | 107==> if(exists $isa{$pack}); | |
685 | 108 | |
686 | 109:a if ($extra-- > 0) { | |
687 | 110: %isa = ($pack,1); | |
688 | ||
689 | Note that the breakable lines are marked with C<:>, lines with | |
690 | breakpoints are marked by C<b>, with actions by C<a>, and the | |
691 | next executed line is marked by C<==E<gt>>. | |
692 | ||
693 | =item Frame listing | |
694 | ||
695 | When C<frame> option is set, debugger would print entered (and | |
696 | optionally exited) subroutines in different styles. | |
697 | ||
54310121 | 698 | What follows is the start of the listing of |
e7ea3e70 | 699 | |
28d1fb14 IZ |
700 | env "PERLDB_OPTS=f=n N" perl -d -V |
701 | ||
702 | for different values of C<n>: | |
e7ea3e70 IZ |
703 | |
704 | =over 4 | |
705 | ||
706 | =item 1 | |
707 | ||
708 | entering main::BEGIN | |
709 | entering Config::BEGIN | |
710 | Package lib/Exporter.pm. | |
711 | Package lib/Carp.pm. | |
712 | Package lib/Config.pm. | |
713 | entering Config::TIEHASH | |
714 | entering Exporter::import | |
715 | entering Exporter::export | |
716 | entering Config::myconfig | |
717 | entering Config::FETCH | |
718 | entering Config::FETCH | |
719 | entering Config::FETCH | |
720 | entering Config::FETCH | |
721 | ||
722 | =item 2 | |
723 | ||
724 | entering main::BEGIN | |
725 | entering Config::BEGIN | |
726 | Package lib/Exporter.pm. | |
727 | Package lib/Carp.pm. | |
728 | exited Config::BEGIN | |
729 | Package lib/Config.pm. | |
730 | entering Config::TIEHASH | |
731 | exited Config::TIEHASH | |
732 | entering Exporter::import | |
733 | entering Exporter::export | |
734 | exited Exporter::export | |
735 | exited Exporter::import | |
736 | exited main::BEGIN | |
737 | entering Config::myconfig | |
738 | entering Config::FETCH | |
739 | exited Config::FETCH | |
740 | entering Config::FETCH | |
741 | exited Config::FETCH | |
742 | entering Config::FETCH | |
743 | ||
744 | =item 4 | |
745 | ||
746 | in $=main::BEGIN() from /dev/nul:0 | |
747 | in $=Config::BEGIN() from lib/Config.pm:2 | |
748 | Package lib/Exporter.pm. | |
749 | Package lib/Carp.pm. | |
750 | Package lib/Config.pm. | |
751 | in $=Config::TIEHASH('Config') from lib/Config.pm:644 | |
752 | in $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/nul:0 | |
753 | in $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from li | |
754 | in @=Config::myconfig() from /dev/nul:0 | |
755 | in $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574 | |
756 | in $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574 | |
cceca5ed GS |
757 | in $=Config::FETCH(ref(Config), 'PERL_VERSION') from lib/Config.pm:574 |
758 | in $=Config::FETCH(ref(Config), 'PERL_SUBVERSION') from lib/Config.pm:574 | |
e7ea3e70 IZ |
759 | in $=Config::FETCH(ref(Config), 'osname') from lib/Config.pm:574 |
760 | in $=Config::FETCH(ref(Config), 'osvers') from lib/Config.pm:574 | |
761 | ||
762 | =item 6 | |
763 | ||
764 | in $=main::BEGIN() from /dev/nul:0 | |
765 | in $=Config::BEGIN() from lib/Config.pm:2 | |
766 | Package lib/Exporter.pm. | |
767 | Package lib/Carp.pm. | |
768 | out $=Config::BEGIN() from lib/Config.pm:0 | |
769 | Package lib/Config.pm. | |
770 | in $=Config::TIEHASH('Config') from lib/Config.pm:644 | |
771 | out $=Config::TIEHASH('Config') from lib/Config.pm:644 | |
772 | in $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/nul:0 | |
773 | in $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/ | |
774 | out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/ | |
775 | out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/nul:0 | |
776 | out $=main::BEGIN() from /dev/nul:0 | |
777 | in @=Config::myconfig() from /dev/nul:0 | |
778 | in $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574 | |
779 | out $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574 | |
780 | in $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574 | |
781 | out $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574 | |
cceca5ed GS |
782 | in $=Config::FETCH(ref(Config), 'PERL_VERSION') from lib/Config.pm:574 |
783 | out $=Config::FETCH(ref(Config), 'PERL_VERSION') from lib/Config.pm:574 | |
784 | in $=Config::FETCH(ref(Config), 'PERL_SUBVERSION') from lib/Config.pm:574 | |
e7ea3e70 IZ |
785 | |
786 | =item 14 | |
787 | ||
788 | in $=main::BEGIN() from /dev/nul:0 | |
789 | in $=Config::BEGIN() from lib/Config.pm:2 | |
790 | Package lib/Exporter.pm. | |
791 | Package lib/Carp.pm. | |
792 | out $=Config::BEGIN() from lib/Config.pm:0 | |
793 | Package lib/Config.pm. | |
794 | in $=Config::TIEHASH('Config') from lib/Config.pm:644 | |
795 | out $=Config::TIEHASH('Config') from lib/Config.pm:644 | |
796 | in $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/nul:0 | |
797 | in $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/E | |
798 | out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/E | |
799 | out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/nul:0 | |
800 | out $=main::BEGIN() from /dev/nul:0 | |
801 | in @=Config::myconfig() from /dev/nul:0 | |
802 | in $=Config::FETCH('Config=HASH(0x1aa444)', 'package') from lib/Config.pm:574 | |
803 | out $=Config::FETCH('Config=HASH(0x1aa444)', 'package') from lib/Config.pm:574 | |
804 | in $=Config::FETCH('Config=HASH(0x1aa444)', 'baserev') from lib/Config.pm:574 | |
805 | out $=Config::FETCH('Config=HASH(0x1aa444)', 'baserev') from lib/Config.pm:574 | |
806 | ||
28d1fb14 IZ |
807 | =item 30 |
808 | ||
809 | in $=CODE(0x15eca4)() from /dev/null:0 | |
810 | in $=CODE(0x182528)() from lib/Config.pm:2 | |
811 | Package lib/Exporter.pm. | |
812 | out $=CODE(0x182528)() from lib/Config.pm:0 | |
813 | scalar context return from CODE(0x182528): undef | |
814 | Package lib/Config.pm. | |
815 | in $=Config::TIEHASH('Config') from lib/Config.pm:628 | |
816 | out $=Config::TIEHASH('Config') from lib/Config.pm:628 | |
817 | scalar context return from Config::TIEHASH: empty hash | |
818 | in $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0 | |
819 | in $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/Exporter.pm:171 | |
820 | out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/Exporter.pm:171 | |
821 | scalar context return from Exporter::export: '' | |
822 | out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0 | |
823 | scalar context return from Exporter::import: '' | |
824 | ||
825 | ||
e7ea3e70 IZ |
826 | =back |
827 | ||
828 | In all the cases indentation of lines shows the call tree, if bit 2 of | |
829 | C<frame> is set, then a line is printed on exit from a subroutine as | |
830 | well, if bit 4 is set, then the arguments are printed as well as the | |
831 | caller info, if bit 8 is set, the arguments are printed even if they | |
28d1fb14 IZ |
832 | are tied or references, if bit 16 is set, the return value is printed |
833 | as well. | |
e7ea3e70 IZ |
834 | |
835 | When a package is compiled, a line like this | |
836 | ||
837 | Package lib/Carp.pm. | |
838 | ||
839 | is printed with proper indentation. | |
840 | ||
841 | =back | |
842 | ||
843 | =head2 Debugging compile-time statements | |
844 | ||
4e1d3b43 | 845 | If you have any compile-time executable statements (code within a BEGIN |
846 | block or a C<use> statement), these will C<NOT> be stopped by debugger, | |
36477c24 | 847 | although C<require>s will (and compile-time statements can be traced |
54310121 | 848 | with C<AutoTrace> option set in C<PERLDB_OPTS>). From your own Perl |
36477c24 | 849 | code, however, you can |
4e1d3b43 | 850 | transfer control back to the debugger using the following statement, |
851 | which is harmless if the debugger is not running: | |
a0d0e21e LW |
852 | |
853 | $DB::single = 1; | |
854 | ||
4e1d3b43 | 855 | If you set C<$DB::single> to the value 2, it's equivalent to having |
856 | just typed the C<n> command, whereas a value of 1 means the C<s> | |
857 | command. The C<$DB::trace> variable should be set to 1 to simulate | |
858 | having typed the C<t> command. | |
859 | ||
e7ea3e70 IZ |
860 | Another way to debug compile-time code is to start debugger, set a |
861 | breakpoint on I<load> of some module thusly | |
862 | ||
863 | DB<7> b load f:/perllib/lib/Carp.pm | |
864 | Will stop on load of `f:/perllib/lib/Carp.pm'. | |
865 | ||
774d564b | 866 | and restart debugger by C<R> command (if possible). One can use C<b |
e7ea3e70 IZ |
867 | compile subname> for the same purpose. |
868 | ||
4e1d3b43 | 869 | =head2 Debugger Customization |
a0d0e21e | 870 | |
7b8d334a | 871 | Most probably you do not want to modify the debugger, it contains enough |
774d564b | 872 | hooks to satisfy most needs. You may change the behaviour of debugger |
36477c24 | 873 | from the debugger itself, using C<O>ptions, from the command line via |
874 | C<PERLDB_OPTS> environment variable, and from I<customization files>. | |
a0d0e21e LW |
875 | |
876 | You can do some customization by setting up a F<.perldb> file which | |
877 | contains initialization code. For instance, you could make aliases | |
4e1d3b43 | 878 | like these (the last one is one people expect to be there): |
a0d0e21e | 879 | |
4e1d3b43 | 880 | $DB::alias{'len'} = 's/^len(.*)/p length($1)/'; |
a0d0e21e | 881 | $DB::alias{'stop'} = 's/^stop (at|in)/b/'; |
4e1d3b43 | 882 | $DB::alias{'ps'} = 's/^ps\b/p scalar /'; |
883 | $DB::alias{'quit'} = 's/^quit(\s*)/exit\$/'; | |
884 | ||
36477c24 | 885 | One changes options from F<.perldb> file via calls like this one; |
886 | ||
887 | parse_options("NonStop=1 LineInfo=db.out AutoTrace=1 frame=2"); | |
888 | ||
774d564b | 889 | (the code is executed in the package C<DB>). Note that F<.perldb> is |
890 | processed before processing C<PERLDB_OPTS>. If F<.perldb> defines the | |
36477c24 | 891 | subroutine C<afterinit>, it is called after all the debugger |
774d564b | 892 | initialization ends. F<.perldb> may be contained in the current |
36477c24 | 893 | directory, or in the C<LOGDIR>/C<HOME> directory. |
894 | ||
895 | If you want to modify the debugger, copy F<perl5db.pl> from the Perl | |
896 | library to another name and modify it as necessary. You'll also want | |
897 | to set your C<PERL5DB> environment variable to say something like this: | |
898 | ||
899 | BEGIN { require "myperl5db.pl" } | |
900 | ||
901 | As the last resort, one can use C<PERL5DB> to customize debugger by | |
902 | directly setting internal variables or calling debugger functions. | |
903 | ||
4e1d3b43 | 904 | =head2 Readline Support |
905 | ||
906 | As shipped, the only command line history supplied is a simplistic one | |
907 | that checks for leading exclamation points. However, if you install | |
908 | the Term::ReadKey and Term::ReadLine modules from CPAN, you will | |
909 | have full editing capabilities much like GNU I<readline>(3) provides. | |
910 | Look for these in the F<modules/by-module/Term> directory on CPAN. | |
911 | ||
54310121 | 912 | A rudimentary command line completion is also available. |
e7ea3e70 IZ |
913 | Unfortunately, the names of lexical variables are not available for |
914 | completion. | |
915 | ||
4e1d3b43 | 916 | =head2 Editor Support for Debugging |
917 | ||
918 | If you have GNU B<emacs> installed on your system, it can interact with | |
919 | the Perl debugger to provide an integrated software development | |
920 | environment reminiscent of its interactions with C debuggers. | |
921 | ||
922 | Perl is also delivered with a start file for making B<emacs> act like a | |
923 | syntax-directed editor that understands (some of) Perl's syntax. Look in | |
924 | the I<emacs> directory of the Perl source distribution. | |
925 | ||
926 | (Historically, a similar setup for interacting with B<vi> and the | |
927 | X11 window system had also been available, but at the time of this | |
928 | writing, no debugger support for B<vi> currently exists.) | |
929 | ||
930 | =head2 The Perl Profiler | |
931 | ||
932 | If you wish to supply an alternative debugger for Perl to run, just | |
933 | invoke your script with a colon and a package argument given to the B<-d> | |
934 | flag. One of the most popular alternative debuggers for Perl is | |
935 | B<DProf>, the Perl profiler. As of this writing, B<DProf> is not | |
936 | included with the standard Perl distribution, but it is expected to | |
937 | be included soon, for certain values of "soon". | |
938 | ||
939 | Meanwhile, you can fetch the Devel::Dprof module from CPAN. Assuming | |
940 | it's properly installed on your system, to profile your Perl program in | |
941 | the file F<mycode.pl>, just type: | |
942 | ||
943 | perl -d:DProf mycode.pl | |
944 | ||
945 | When the script terminates the profiler will dump the profile information | |
946 | to a file called F<tmon.out>. A tool like B<dprofpp> (also supplied with | |
947 | the Devel::DProf package) can be used to interpret the information which is | |
948 | in that profile. | |
949 | ||
36477c24 | 950 | =head2 Debugger support in perl |
4e1d3b43 | 951 | |
e7ea3e70 IZ |
952 | When you call the B<caller> function (see L<perlfunc/caller>) from the |
953 | package DB, Perl sets the array @DB::args to contain the arguments the | |
54310121 | 954 | corresponding stack frame was called with. |
4e1d3b43 | 955 | |
36477c24 | 956 | If perl is run with B<-d> option, the following additional features |
84902520 | 957 | are enabled (cf. L<perlvar/$^P>): |
a0d0e21e | 958 | |
36477c24 | 959 | =over |
4e1d3b43 | 960 | |
36477c24 | 961 | =item * |
4e1d3b43 | 962 | |
36477c24 | 963 | Perl inserts the contents of C<$ENV{PERL5DB}> (or C<BEGIN {require |
964 | 'perl5db.pl'}> if not present) before the first line of the | |
965 | application. | |
4e1d3b43 | 966 | |
36477c24 | 967 | =item * |
4e1d3b43 | 968 | |
7b8d334a | 969 | The array C<@{"_E<lt>$filename"}> is the line-by-line contents of |
774d564b | 970 | $filename for all the compiled files. Same for C<eval>ed strings which |
19799a22 | 971 | contain subroutines, or which are currently executed. The $filename |
36477c24 | 972 | for C<eval>ed strings looks like C<(eval 34)>. |
4e1d3b43 | 973 | |
36477c24 | 974 | =item * |
4e1d3b43 | 975 | |
7b8d334a | 976 | The hash C<%{"_E<lt>$filename"}> contains breakpoints and action (it is |
36477c24 | 977 | keyed by line number), and individual entries are settable (as opposed |
774d564b | 978 | to the whole hash). Only true/false is important to Perl, though the |
36477c24 | 979 | values used by F<perl5db.pl> have the form |
774d564b | 980 | C<"$break_condition\0$action">. Values are magical in numeric context: |
36477c24 | 981 | they are zeros if the line is not breakable. |
4e1d3b43 | 982 | |
36477c24 | 983 | Same for evaluated strings which contain subroutines, or which are |
7b8d334a | 984 | currently executed. The $filename for C<eval>ed strings looks like |
36477c24 | 985 | C<(eval 34)>. |
4e1d3b43 | 986 | |
36477c24 | 987 | =item * |
4e1d3b43 | 988 | |
7b8d334a | 989 | The scalar C<${"_E<lt>$filename"}> contains C<"_E<lt>$filename">. Same for |
36477c24 | 990 | evaluated strings which contain subroutines, or which are currently |
7b8d334a | 991 | executed. The $filename for C<eval>ed strings looks like C<(eval |
36477c24 | 992 | 34)>. |
4e1d3b43 | 993 | |
36477c24 | 994 | =item * |
4e1d3b43 | 995 | |
36477c24 | 996 | After each C<require>d file is compiled, but before it is executed, |
7b8d334a | 997 | C<DB::postponed(*{"_E<lt>$filename"})> is called (if subroutine |
774d564b | 998 | C<DB::postponed> exists). Here the $filename is the expanded name of |
7b8d334a | 999 | the C<require>d file (as found in values of %INC). |
4e1d3b43 | 1000 | |
36477c24 | 1001 | =item * |
4e1d3b43 | 1002 | |
36477c24 | 1003 | After each subroutine C<subname> is compiled existence of |
774d564b | 1004 | C<$DB::postponed{subname}> is checked. If this key exists, |
36477c24 | 1005 | C<DB::postponed(subname)> is called (if subroutine C<DB::postponed> |
1006 | exists). | |
4e1d3b43 | 1007 | |
36477c24 | 1008 | =item * |
4e1d3b43 | 1009 | |
36477c24 | 1010 | A hash C<%DB::sub> is maintained, with keys being subroutine names, |
774d564b | 1011 | values having the form C<filename:startline-endline>. C<filename> has |
36477c24 | 1012 | the form C<(eval 31)> for subroutines defined inside C<eval>s. |
4e1d3b43 | 1013 | |
36477c24 | 1014 | =item * |
1015 | ||
5f05dabc | 1016 | When execution of the application reaches a place that can have |
1017 | a breakpoint, a call to C<DB::DB()> is performed if any one of | |
1018 | variables $DB::trace, $DB::single, or $DB::signal is true. (Note that | |
36477c24 | 1019 | these variables are not C<local>izable.) This feature is disabled when |
1020 | the control is inside C<DB::DB()> or functions called from it (unless | |
e7ea3e70 | 1021 | C<$^D & (1E<lt>E<lt>30)>). |
36477c24 | 1022 | |
1023 | =item * | |
1024 | ||
5f05dabc | 1025 | When execution of the application reaches a subroutine call, a call |
36477c24 | 1026 | to C<&DB::sub>(I<args>) is performed instead, with C<$DB::sub> being |
1027 | the name of the called subroutine. (Unless the subroutine is compiled | |
1028 | in the package C<DB>.) | |
4e1d3b43 | 1029 | |
1030 | =back | |
a0d0e21e | 1031 | |
84902520 TB |
1032 | Note that if C<&DB::sub> needs some external data to be setup for it |
1033 | to work, no subroutine call is possible until this is done. For the | |
1034 | standard debugger C<$DB::deep> (how many levels of recursion deep into | |
1035 | the debugger you can go before a mandatory break) gives an example of | |
1036 | such a dependency. | |
e7ea3e70 | 1037 | |
84902520 | 1038 | The minimal working debugger consists of one line |
e7ea3e70 IZ |
1039 | |
1040 | sub DB::DB {} | |
1041 | ||
1042 | which is quite handy as contents of C<PERL5DB> environment | |
1043 | variable: | |
1044 | ||
1045 | env "PERL5DB=sub DB::DB {}" perl -d your-script | |
1046 | ||
1047 | Another (a little bit more useful) minimal debugger can be created | |
1048 | with the only line being | |
1049 | ||
1050 | sub DB::DB {print ++$i; scalar <STDIN>} | |
1051 | ||
1052 | This debugger would print the sequential number of encountered | |
1053 | statement, and would wait for your C<CR> to continue. | |
1054 | ||
1055 | The following debugger is quite functional: | |
1056 | ||
54310121 | 1057 | { |
1058 | package DB; | |
1059 | sub DB {} | |
e7ea3e70 IZ |
1060 | sub sub {print ++$i, " $sub\n"; &$sub} |
1061 | } | |
1062 | ||
1063 | It prints the sequential number of subroutine call and the name of the | |
774d564b | 1064 | called subroutine. Note that C<&DB::sub> should be compiled into the |
e7ea3e70 | 1065 | package C<DB>. |
36477c24 | 1066 | |
1067 | =head2 Debugger Internals | |
1068 | ||
1069 | At the start, the debugger reads your rc file (F<./.perldb> or | |
54310121 | 1070 | F<~/.perldb> under Unix), which can set important options. This file may |
36477c24 | 1071 | define a subroutine C<&afterinit> to be executed after the debugger is |
1072 | initialized. | |
1073 | ||
5f05dabc | 1074 | After the rc file is read, the debugger reads environment variable |
36477c24 | 1075 | PERLDB_OPTS and parses it as a rest of C<O ...> line in debugger prompt. |
1076 | ||
1077 | It also maintains magical internal variables, such as C<@DB::dbline>, | |
1078 | C<%DB::dbline>, which are aliases for C<@{"::_<current_file"}> | |
774d564b | 1079 | C<%{"::_<current_file"}>. Here C<current_file> is the currently |
36477c24 | 1080 | selected (with the debugger's C<f> command, or by flow of execution) |
1081 | file. | |
1082 | ||
774d564b | 1083 | Some functions are provided to simplify customization. See L<"Debugger |
1084 | Customization"> for description of C<DB::parse_options(string)>. The | |
36477c24 | 1085 | function C<DB::dump_trace(skip[, count])> skips the specified number |
1d2dff63 | 1086 | of frames, and returns a list containing info about the caller |
774d564b | 1087 | frames (all if C<count> is missing). Each entry is a hash with keys |
36477c24 | 1088 | C<context> (C<$> or C<@>), C<sub> (subroutine name, or info about |
5f05dabc | 1089 | eval), C<args> (C<undef> or a reference to an array), C<file>, and |
36477c24 | 1090 | C<line>. |
1091 | ||
54310121 | 1092 | The function C<DB::print_trace(FH, skip[, count[, short]])> prints |
774d564b | 1093 | formatted info about caller frames. The last two functions may be |
36477c24 | 1094 | convenient as arguments to C<E<lt>>, C<E<lt>E<lt>> commands. |
1095 | ||
a0d0e21e LW |
1096 | =head2 Other resources |
1097 | ||
1098 | You did try the B<-w> switch, didn't you? | |
1099 | ||
a77df738 | 1100 | =head2 BUGS |
a0d0e21e | 1101 | |
4e1d3b43 | 1102 | You cannot get the stack frame information or otherwise debug functions |
1103 | that were not compiled by Perl, such as C or C++ extensions. | |
a0d0e21e | 1104 | |
4e1d3b43 | 1105 | If you alter your @_ arguments in a subroutine (such as with B<shift> |
68dc0745 | 1106 | or B<pop>, the stack backtrace will not show the original values. |
a77df738 IZ |
1107 | |
1108 | =head1 Debugging Perl memory usage | |
1109 | ||
1110 | Perl is I<very> frivolous with memory. There is a saying that to | |
1111 | estimate memory usage of Perl, assume a reasonable algorithm of | |
c2611fb3 | 1112 | allocation, and multiply your estimates by 10. This is not absolutely |
a77df738 IZ |
1113 | true, but may give you a good grasp of what happens. |
1114 | ||
1115 | Say, an integer cannot take less than 20 bytes of memory, a float | |
1116 | cannot take less than 24 bytes, a string cannot take less than 32 | |
1117 | bytes (all these examples assume 32-bit architectures, the result are | |
1118 | much worse on 64-bit architectures). If a variable is accessed in two | |
1119 | of three different ways (which require an integer, a float, or a | |
1120 | string), the memory footprint may increase by another 20 bytes. A | |
1121 | sloppy malloc() implementation will make these numbers yet more. | |
1122 | ||
1123 | On the opposite end of the scale, a declaration like | |
1124 | ||
1125 | sub foo; | |
1126 | ||
1127 | may take (on some versions of perl) up to 500 bytes of memory. | |
1128 | ||
1129 | Off-the-cuff anecdotal estimates of a code bloat give a factor around | |
1130 | 8. This means that the compiled form of reasonable (commented | |
1131 | indented etc.) code will take approximately 8 times more than the | |
1132 | disk space the code takes. | |
1133 | ||
1134 | There are two Perl-specific ways to analyze the memory usage: | |
1135 | $ENV{PERL_DEBUG_MSTATS} and B<-DL> switch. First one is available | |
1136 | only if perl is compiled with Perl's malloc(), the second one only if | |
1137 | Perl compiled with C<-DDEBUGGING> (as with giving C<-D optimise=-g> | |
1138 | option to F<Configure>). | |
1139 | ||
1140 | =head2 Using C<$ENV{PERL_DEBUG_MSTATS}> | |
1141 | ||
1142 | If your perl is using Perl's malloc(), and compiled with correct | |
1143 | switches (this is the default), then it will print memory usage | |
1144 | statistics after compiling your code (if C<$ENV{PERL_DEBUG_MSTATS}> > | |
1145 | 1), and before termination of the script (if | |
1146 | C<$ENV{PERL_DEBUG_MSTATS}> >= 1). The report format is similar to one | |
1147 | in the following example: | |
1148 | ||
1149 | env PERL_DEBUG_MSTATS=2 perl -e "require Carp" | |
1150 | Memory allocation statistics after compilation: (buckets 4(4)..8188(8192) | |
1151 | 14216 free: 130 117 28 7 9 0 2 2 1 0 0 | |
1152 | 437 61 36 0 5 | |
1153 | 60924 used: 125 137 161 55 7 8 6 16 2 0 1 | |
1154 | 74 109 304 84 20 | |
1155 | Total sbrk(): 77824/21:119. Odd ends: pad+heads+chain+tail: 0+636+0+2048. | |
1156 | Memory allocation statistics after execution: (buckets 4(4)..8188(8192) | |
1157 | 30888 free: 245 78 85 13 6 2 1 3 2 0 1 | |
1158 | 315 162 39 42 11 | |
1159 | 175816 used: 265 176 1112 111 26 22 11 27 2 1 1 | |
1160 | 196 178 1066 798 39 | |
1161 | Total sbrk(): 215040/47:145. Odd ends: pad+heads+chain+tail: 0+2192+0+6144. | |
1162 | ||
1163 | It is possible to ask for such a statistic at arbitrary moment by | |
c2611fb3 | 1164 | using Devel::Peek::mstats() (module Devel::Peek is available on CPAN). |
a77df738 IZ |
1165 | |
1166 | Here is the explanation of different parts of the format: | |
1167 | ||
1168 | =over | |
1169 | ||
1170 | =item C<buckets SMALLEST(APPROX)..GREATEST(APPROX)> | |
1171 | ||
1172 | Perl's malloc() uses bucketed allocations. Every request is rounded | |
1173 | up to the closest bucket size available, and a bucket of these size is | |
1174 | taken from the pool of the buckets of this size. | |
1175 | ||
1176 | The above line describes limits of buckets currently in use. Each | |
1177 | bucket has two sizes: memory footprint, and the maximal size of user | |
1178 | data which may be put into this bucket. Say, in the above example the | |
1179 | smallest bucket is both sizes 4. The biggest bucket has usable size | |
1180 | 8188, and the memory footprint 8192. | |
1181 | ||
1182 | With debugging Perl some buckets may have negative usable size. This | |
1183 | means that these buckets cannot (and will not) be used. For greater | |
1184 | buckets the memory footprint may be one page greater than a power of | |
1185 | 2. In such a case the corresponding power of two is printed instead | |
1186 | in the C<APPROX> field above. | |
1187 | ||
1188 | =item Free/Used | |
1189 | ||
1190 | The following 1 or 2 rows of numbers correspond to the number of | |
1191 | buckets of each size between C<SMALLEST> and C<GREATEST>. In the | |
1192 | first row the sizes (memory footprints) of buckets are powers of two | |
1193 | (or possibly one page greater). In the second row (if present) the | |
1194 | memory footprints of the buckets are between memory footprints of two | |
1195 | buckets "above". | |
1196 | ||
1197 | Say, with the above example the memory footprints are (with current | |
c2611fb3 | 1198 | algorithm) |
a77df738 IZ |
1199 | |
1200 | free: 8 16 32 64 128 256 512 1024 2048 4096 8192 | |
1201 | 4 12 24 48 80 | |
1202 | ||
1203 | With non-C<DEBUGGING> perl the buckets starting from C<128>-long ones | |
1204 | have 4-byte overhead, thus 8192-long bucket may take up to | |
1205 | 8188-byte-long allocations. | |
1206 | ||
1207 | =item C<Total sbrk(): SBRKed/SBRKs:CONTINUOUS> | |
1208 | ||
1209 | The first two fields give the total amount of memory perl sbrk()ed, | |
1210 | and number of sbrk()s used. The third number is what perl thinks | |
1211 | about continuity of returned chunks. As far as this number is | |
1212 | positive, malloc() will assume that it is probable that sbrk() will | |
1213 | provide continuous memory. | |
1214 | ||
1215 | The amounts sbrk()ed by external libraries is not counted. | |
1216 | ||
1217 | =item C<pad: 0> | |
1218 | ||
1219 | The amount of sbrk()ed memory needed to keep buckets aligned. | |
1220 | ||
1221 | =item C<heads: 2192> | |
1222 | ||
1223 | While memory overhead of bigger buckets is kept inside the bucket, for | |
1224 | smaller buckets it is kept in separate areas. This field gives the | |
1225 | total size of these areas. | |
1226 | ||
1227 | =item C<chain: 0> | |
1228 | ||
1229 | malloc() may want to subdivide a bigger bucket into smaller buckets. | |
1230 | If only a part of the deceased-bucket is left non-subdivided, the rest | |
1231 | is kept as an element of a linked list. This field gives the total | |
1232 | size of these chunks. | |
1233 | ||
1234 | =item C<tail: 6144> | |
1235 | ||
1236 | To minimize amount of sbrk()s malloc() asks for more memory. This | |
1237 | field gives the size of the yet-unused part, which is sbrk()ed, but | |
1238 | never touched. | |
1239 | ||
1240 | =back | |
1241 | ||
1242 | =head2 Example of using B<-DL> switch | |
1243 | ||
1244 | Below we show how to analyse memory usage by | |
1245 | ||
1246 | do 'lib/auto/POSIX/autosplit.ix'; | |
1247 | ||
1248 | The file in question contains a header and 146 lines similar to | |
1249 | ||
1250 | sub getcwd ; | |
1251 | ||
1252 | B<Note:> I<the discussion below supposes 32-bit architecture. In the | |
1253 | newer versions of perl the memory usage of the constructs discussed | |
1254 | here is much improved, but the story discussed below is a real-life | |
1255 | story. This story is very terse, and assumes more than cursory | |
1256 | knowledge of Perl internals.> | |
1257 | ||
1258 | Here is the itemized list of Perl allocations performed during parsing | |
1259 | of this file: | |
1260 | ||
1261 | !!! "after" at test.pl line 3. | |
1262 | Id subtot 4 8 12 16 20 24 28 32 36 40 48 56 64 72 80 80+ | |
1263 | 0 02 13752 . . . . 294 . . . . . . . . . . 4 | |
1264 | 0 54 5545 . . 8 124 16 . . . 1 1 . . . . . 3 | |
1265 | 5 05 32 . . . . . . . 1 . . . . . . . . | |
1266 | 6 02 7152 . . . . . . . . . . 149 . . . . . | |
1267 | 7 02 3600 . . . . . 150 . . . . . . . . . . | |
1268 | 7 03 64 . -1 . 1 . . 2 . . . . . . . . . | |
1269 | 7 04 7056 . . . . . . . . . . . . . . . 7 | |
1270 | 7 17 38404 . . . . . . . 1 . . 442 149 . . 147 . | |
1271 | 9 03 2078 17 249 32 . . . . 2 . . . . . . . . | |
1272 | ||
1273 | ||
1274 | To see this list insert two C<warn('!...')> statements around the call: | |
1275 | ||
1276 | warn('!'); | |
1277 | do 'lib/auto/POSIX/autosplit.ix'; | |
1278 | warn('!!! "after"'); | |
1279 | ||
1280 | and run it with B<-DL> option. The first warn() will print memory | |
1281 | allocation info before the parsing of the file, and will memorize the | |
1282 | statistics at this point (we ignore what it prints). The second warn() | |
1283 | will print increments w.r.t. this memorized statistics. This is the | |
1284 | above printout. | |
1285 | ||
1286 | Different I<Id>s on the left correspond to different subsystems of | |
1287 | perl interpreter, they are just first argument given to perl memory | |
1288 | allocation API New(). To find what C<9 03> means C<grep> the perl | |
1289 | source for C<903>. You will see that it is F<util.c>, function | |
1290 | savepvn(). This function is used to store a copy of existing chunk of | |
1291 | memory. Using C debugger, one can see that it is called either | |
1292 | directly from gv_init(), or via sv_magic(), and gv_init() is called | |
1293 | from gv_fetchpv() - which is called from newSUB(). | |
1294 | ||
1295 | B<Note:> to reach this place in debugger and skip all the calls to | |
1296 | savepvn during the compilation of the main script, set a C breakpoint | |
1297 | in Perl_warn(), C<continue> this point is reached, I<then> set | |
1298 | breakpoint in Perl_savepvn(). Note that you may need to skip a | |
1299 | handful of Perl_savepvn() which do not correspond to mass production | |
1300 | of CVs (there are more C<903> allocations than 146 similar lines of | |
1301 | F<lib/auto/POSIX/autosplit.ix>). Note also that C<Perl_> prefixes are | |
1302 | added by macroization code in perl header files to avoid conflicts | |
1303 | with external libraries. | |
1304 | ||
1305 | Anyway, we see that C<903> ids correspond to creation of globs, twice | |
1306 | per glob - for glob name, and glob stringification magic. | |
1307 | ||
1308 | Here are explanations for other I<Id>s above: | |
1309 | ||
1310 | =over | |
1311 | ||
1312 | =item C<717> | |
1313 | ||
1314 | is for creation of bigger C<XPV*> structures. In the above case it | |
1315 | creates 3 C<AV> per subroutine, one for a list of lexical variable | |
1316 | names, one for a scratchpad (which contains lexical variables and | |
1317 | C<targets>), and one for the array of scratchpads needed for | |
1318 | recursion. | |
1319 | ||
1320 | It also creates a C<GV> and a C<CV> per subroutine (all called from | |
1321 | start_subparse()). | |
1322 | ||
1323 | =item C<002> | |
1324 | ||
1325 | Creates C array corresponding to the C<AV> of scratchpads, and the | |
1326 | scratchpad itself (the first fake entry of this scratchpad is created | |
1327 | though the subroutine itself is not defined yet). | |
1328 | ||
1329 | It also creates C arrays to keep data for the stash (this is one HV, | |
1330 | but it grows, thus there are 4 big allocations: the big chunks are not | |
c2611fb3 | 1331 | freed, but are kept as additional arenas for C<SV> allocations). |
a77df738 IZ |
1332 | |
1333 | =item C<054> | |
1334 | ||
1335 | creates a C<HEK> for the name of the glob for the subroutine (this | |
1336 | name is a key in a I<stash>). | |
1337 | ||
1338 | Big allocations with this I<Id> correspond to allocations of new | |
1339 | arenas to keep C<HE>. | |
1340 | ||
1341 | =item C<602> | |
1342 | ||
1343 | creates a C<GP> for the glob for the subroutine. | |
1344 | ||
1345 | =item C<702> | |
1346 | ||
1347 | creates the C<MAGIC> for the glob for the subroutine. | |
1348 | ||
1349 | =item C<704> | |
1350 | ||
1351 | creates I<arenas> which keep SVs. | |
1352 | ||
1353 | =back | |
1354 | ||
1355 | =head2 B<-DL> details | |
1356 | ||
1357 | If Perl is run with B<-DL> option, then warn()s which start with `!' | |
1358 | behave specially. They print a list of I<categories> of memory | |
1359 | allocations, and statistics of allocations of different sizes for | |
1360 | these categories. | |
1361 | ||
1362 | If warn() string starts with | |
1363 | ||
1364 | =over | |
1365 | ||
1366 | =item C<!!!> | |
1367 | ||
1368 | print changed categories only, print the differences in counts of allocations; | |
1369 | ||
1370 | =item C<!!> | |
1371 | ||
1372 | print grown categories only; print the absolute values of counts, and totals; | |
1373 | ||
1374 | =item C<!> | |
1375 | ||
1376 | print nonempty categories, print the absolute values of counts and totals. | |
1377 | ||
1378 | =back | |
1379 | ||
1380 | =head2 Limitations of B<-DL> statistic | |
1381 | ||
1382 | If an extension or an external library does not use Perl API to | |
1383 | allocate memory, these allocations are not counted. | |
1384 | ||
54dc92de IZ |
1385 | =head1 Debugging regular expressions |
1386 | ||
1387 | There are two ways to enable debugging output for regular expressions. | |
1388 | ||
1389 | If your perl is compiled with C<-DDEBUGGING>, you may use the | |
1390 | B<-Dr> flag on the command line. | |
1391 | ||
1392 | Otherwise, one can C<use re 'debug'>, which has effects both at | |
1393 | compile time, and at run time (and is I<not> lexically scoped). | |
1394 | ||
1395 | =head2 Compile-time output | |
1396 | ||
1397 | The debugging output for the compile time looks like this: | |
1398 | ||
1399 | compiling RE `[bc]d(ef*g)+h[ij]k$' | |
1400 | size 43 first at 1 | |
1401 | 1: ANYOF(11) | |
1402 | 11: EXACT <d>(13) | |
1403 | 13: CURLYX {1,32767}(27) | |
1404 | 15: OPEN1(17) | |
1405 | 17: EXACT <e>(19) | |
1406 | 19: STAR(22) | |
1407 | 20: EXACT <f>(0) | |
1408 | 22: EXACT <g>(24) | |
1409 | 24: CLOSE1(26) | |
1410 | 26: WHILEM(0) | |
1411 | 27: NOTHING(28) | |
1412 | 28: EXACT <h>(30) | |
1413 | 30: ANYOF(40) | |
1414 | 40: EXACT <k>(42) | |
1415 | 42: EOL(43) | |
1416 | 43: END(0) | |
1417 | anchored `de' at 1 floating `gh' at 3..2147483647 (checking floating) | |
1418 | stclass `ANYOF' minlen 7 | |
1419 | ||
1420 | The first line shows the pre-compiled form of the regexp, and the | |
1421 | second shows the size of the compiled form (in arbitrary units, | |
1422 | usually 4-byte words) and the label I<id> of the first node which | |
1423 | does a match. | |
1424 | ||
1425 | The last line (split into two lines in the above) contains the optimizer | |
1426 | info. In the example shown, the optimizer found that the match | |
1427 | should contain a substring C<de> at the offset 1, and substring C<gh> | |
1428 | at some offset between 3 and infinity. Moreover, when checking for | |
1429 | these substrings (to abandon impossible matches quickly) it will check | |
1430 | for the substring C<gh> before checking for the substring C<de>. The | |
1431 | optimizer may also use the knowledge that the match starts (at the | |
1432 | C<first> I<id>) with a character class, and the match cannot be | |
1433 | shorter than 7 chars. | |
1434 | ||
1435 | The fields of interest which may appear in the last line are | |
1436 | ||
1437 | =over | |
1438 | ||
1439 | =item C<anchored> I<STRING> C<at> I<POS> | |
1440 | ||
1441 | =item C<floating> I<STRING> C<at> I<POS1..POS2> | |
1442 | ||
1443 | see above; | |
1444 | ||
1445 | =item C<matching floating/anchored> | |
1446 | ||
1447 | which substring to check first; | |
1448 | ||
1449 | =item C<minlen> | |
1450 | ||
1451 | the minimal length of the match; | |
1452 | ||
1453 | =item C<stclass> I<TYPE> | |
1454 | ||
1455 | The type of the first matching node. | |
1456 | ||
1457 | =item C<noscan> | |
1458 | ||
1459 | which advises to not scan for the found substrings; | |
1460 | ||
1461 | =item C<isall> | |
1462 | ||
1463 | which says that the optimizer info is in fact all that the regular | |
1464 | expression contains (thus one does not need to enter the RE engine at | |
1465 | all); | |
1466 | ||
1467 | =item C<GPOS> | |
1468 | ||
1469 | if the pattern contains C<\G>; | |
1470 | ||
1471 | =item C<plus> | |
1472 | ||
1473 | if the pattern starts with a repeated char (as in C<x+y>); | |
1474 | ||
1475 | =item C<implicit> | |
1476 | ||
1477 | if the pattern starts with C<.*>; | |
1478 | ||
1479 | =item C<with eval> | |
1480 | ||
1481 | if the pattern contain eval-groups (see L<perlre/(?{ code })>); | |
1482 | ||
1483 | =item C<anchored(TYPE)> | |
1484 | ||
1485 | if the pattern may | |
1486 | match only at a handful of places (with C<TYPE> being | |
1487 | C<BOL>, C<MBOL>, or C<GPOS>, see the table below). | |
1488 | ||
1489 | =back | |
1490 | ||
1491 | If a substring is known to match at end-of-line only, it may be | |
1492 | followed by C<$>, as in C<floating `k'$>. | |
1493 | ||
1494 | The optimizer-specific info is used to avoid entering (a slow) RE | |
1495 | engine on strings which will definitely not match. If C<isall> flag | |
1496 | is set, a call to the RE engine may be avoided even when optimizer | |
1497 | found an appropriate place for the match. | |
1498 | ||
1499 | The rest of the output contains the list of I<nodes> of the compiled | |
1500 | form of the RE. Each line has format | |
1501 | ||
1502 | C< >I<id>: I<TYPE> I<OPTIONAL-INFO> (I<next-id>) | |
1503 | ||
1504 | =head2 Types of nodes | |
1505 | ||
1506 | Here is the list of possible types with short descriptions: | |
1507 | ||
1508 | # TYPE arg-description [num-args] [longjump-len] DESCRIPTION | |
1509 | ||
1510 | # Exit points | |
1511 | END no End of program. | |
1512 | SUCCEED no Return from a subroutine, basically. | |
1513 | ||
1514 | # Anchors: | |
1515 | BOL no Match "" at beginning of line. | |
1516 | MBOL no Same, assuming multiline. | |
1517 | SBOL no Same, assuming singleline. | |
1518 | EOS no Match "" at end of string. | |
1519 | EOL no Match "" at end of line. | |
1520 | MEOL no Same, assuming multiline. | |
1521 | SEOL no Same, assuming singleline. | |
1522 | BOUND no Match "" at any word boundary | |
1523 | BOUNDL no Match "" at any word boundary | |
1524 | NBOUND no Match "" at any word non-boundary | |
1525 | NBOUNDL no Match "" at any word non-boundary | |
1526 | GPOS no Matches where last m//g left off. | |
1527 | ||
1528 | # [Special] alternatives | |
1529 | ANY no Match any one character (except newline). | |
1530 | SANY no Match any one character. | |
1531 | ANYOF sv Match character in (or not in) this class. | |
1532 | ALNUM no Match any alphanumeric character | |
1533 | ALNUML no Match any alphanumeric char in locale | |
1534 | NALNUM no Match any non-alphanumeric character | |
1535 | NALNUML no Match any non-alphanumeric char in locale | |
1536 | SPACE no Match any whitespace character | |
1537 | SPACEL no Match any whitespace char in locale | |
1538 | NSPACE no Match any non-whitespace character | |
1539 | NSPACEL no Match any non-whitespace char in locale | |
1540 | DIGIT no Match any numeric character | |
1541 | NDIGIT no Match any non-numeric character | |
1542 | ||
1543 | # BRANCH The set of branches constituting a single choice are hooked | |
1544 | # together with their "next" pointers, since precedence prevents | |
1545 | # anything being concatenated to any individual branch. The | |
1546 | # "next" pointer of the last BRANCH in a choice points to the | |
1547 | # thing following the whole choice. This is also where the | |
1548 | # final "next" pointer of each individual branch points; each | |
1549 | # branch starts with the operand node of a BRANCH node. | |
1550 | # | |
1551 | BRANCH node Match this alternative, or the next... | |
1552 | ||
1553 | # BACK Normal "next" pointers all implicitly point forward; BACK | |
1554 | # exists to make loop structures possible. | |
1555 | # not used | |
1556 | BACK no Match "", "next" ptr points backward. | |
1557 | ||
1558 | # Literals | |
1559 | EXACT sv Match this string (preceded by length). | |
1560 | EXACTF sv Match this string, folded (prec. by length). | |
1561 | EXACTFL sv Match this string, folded in locale (w/len). | |
1562 | ||
1563 | # Do nothing | |
1564 | NOTHING no Match empty string. | |
1565 | # A variant of above which delimits a group, thus stops optimizations | |
1566 | TAIL no Match empty string. Can jump here from outside. | |
1567 | ||
1568 | # STAR,PLUS '?', and complex '*' and '+', are implemented as circular | |
1569 | # BRANCH structures using BACK. Simple cases (one character | |
1570 | # per match) are implemented with STAR and PLUS for speed | |
1571 | # and to minimize recursive plunges. | |
1572 | # | |
1573 | STAR node Match this (simple) thing 0 or more times. | |
1574 | PLUS node Match this (simple) thing 1 or more times. | |
1575 | ||
1576 | CURLY sv 2 Match this simple thing {n,m} times. | |
1577 | CURLYN no 2 Match next-after-this simple thing | |
1578 | # {n,m} times, set parenths. | |
1579 | CURLYM no 2 Match this medium-complex thing {n,m} times. | |
1580 | CURLYX sv 2 Match this complex thing {n,m} times. | |
1581 | ||
1582 | # This terminator creates a loop structure for CURLYX | |
1583 | WHILEM no Do curly processing and see if rest matches. | |
1584 | ||
1585 | # OPEN,CLOSE,GROUPP ...are numbered at compile time. | |
1586 | OPEN num 1 Mark this point in input as start of #n. | |
1587 | CLOSE num 1 Analogous to OPEN. | |
1588 | ||
1589 | REF num 1 Match some already matched string | |
1590 | REFF num 1 Match already matched string, folded | |
1591 | REFFL num 1 Match already matched string, folded in loc. | |
1592 | ||
1593 | # grouping assertions | |
1594 | IFMATCH off 1 2 Succeeds if the following matches. | |
1595 | UNLESSM off 1 2 Fails if the following matches. | |
1596 | SUSPEND off 1 1 "Independent" sub-RE. | |
1597 | IFTHEN off 1 1 Switch, should be preceeded by switcher . | |
1598 | GROUPP num 1 Whether the group matched. | |
1599 | ||
1600 | # Support for long RE | |
1601 | LONGJMP off 1 1 Jump far away. | |
1602 | BRANCHJ off 1 1 BRANCH with long offset. | |
1603 | ||
1604 | # The heavy worker | |
1605 | EVAL evl 1 Execute some Perl code. | |
1606 | ||
1607 | # Modifiers | |
1608 | MINMOD no Next operator is not greedy. | |
1609 | LOGICAL no Next opcode should set the flag only. | |
1610 | ||
1611 | # This is not used yet | |
1612 | RENUM off 1 1 Group with independently numbered parens. | |
1613 | ||
1614 | # This is not really a node, but an optimized away piece of a "long" node. | |
1615 | # To simplify debugging output, we mark it as if it were a node | |
1616 | OPTIMIZED off Placeholder for dump. | |
1617 | ||
1618 | =head2 Run-time output | |
1619 | ||
1620 | First of all, when doing a match, one may get no run-time output even | |
1621 | if debugging is enabled. this means that the RE engine was never | |
1622 | entered, all of the job was done by the optimizer. | |
1623 | ||
1624 | If RE engine was entered, the output may look like this: | |
1625 | ||
1626 | Matching `[bc]d(ef*g)+h[ij]k$' against `abcdefg__gh__' | |
1627 | Setting an EVAL scope, savestack=3 | |
1628 | 2 <ab> <cdefg__gh_> | 1: ANYOF | |
1629 | 3 <abc> <defg__gh_> | 11: EXACT <d> | |
1630 | 4 <abcd> <efg__gh_> | 13: CURLYX {1,32767} | |
1631 | 4 <abcd> <efg__gh_> | 26: WHILEM | |
1632 | 0 out of 1..32767 cc=effff31c | |
1633 | 4 <abcd> <efg__gh_> | 15: OPEN1 | |
1634 | 4 <abcd> <efg__gh_> | 17: EXACT <e> | |
1635 | 5 <abcde> <fg__gh_> | 19: STAR | |
1636 | EXACT <f> can match 1 times out of 32767... | |
1637 | Setting an EVAL scope, savestack=3 | |
1638 | 6 <bcdef> <g__gh__> | 22: EXACT <g> | |
1639 | 7 <bcdefg> <__gh__> | 24: CLOSE1 | |
1640 | 7 <bcdefg> <__gh__> | 26: WHILEM | |
1641 | 1 out of 1..32767 cc=effff31c | |
1642 | Setting an EVAL scope, savestack=12 | |
1643 | 7 <bcdefg> <__gh__> | 15: OPEN1 | |
1644 | 7 <bcdefg> <__gh__> | 17: EXACT <e> | |
1645 | restoring \1 to 4(4)..7 | |
1646 | failed, try continuation... | |
1647 | 7 <bcdefg> <__gh__> | 27: NOTHING | |
1648 | 7 <bcdefg> <__gh__> | 28: EXACT <h> | |
1649 | failed... | |
1650 | failed... | |
1651 | ||
1652 | The most significant information in the output is about the particular I<node> | |
1653 | of the compiled RE which is currently being tested against the target string. | |
1654 | The format of these lines is | |
1655 | ||
1656 | C< >I<STRING-OFFSET> <I<PRE-STRING>> <I<POST-STRING>> |I<ID>: I<TYPE> | |
1657 | ||
1658 | The I<TYPE> info is indented with respect to the backtracking level. | |
1659 | Other incidental information appears interspersed within. | |
1660 | ||
a77df738 | 1661 | =cut |