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 "PERLDEBUG 1" | |
132 | .TH PERLDEBUG 1 "2006-01-07" "perl v5.8.8" "Perl Programmers Reference Guide" | |
133 | .SH "NAME" | |
134 | .IX Xref "debug debugger" | |
135 | perldebug \- Perl debugging | |
136 | .SH "DESCRIPTION" | |
137 | .IX Header "DESCRIPTION" | |
138 | First of all, have you tried using the \fB\-w\fR switch? | |
139 | .PP | |
140 | If you're new to the Perl debugger, you may prefer to read | |
141 | perldebtut, which is a tutorial introduction to the debugger . | |
142 | .SH "The Perl Debugger" | |
143 | .IX Header "The Perl Debugger" | |
144 | If you invoke Perl with the \fB\-d\fR switch, your script runs under the | |
145 | Perl source debugger. This works like an interactive Perl | |
146 | environment, prompting for debugger commands that let you examine | |
147 | source code, set breakpoints, get stack backtraces, change the values of | |
148 | variables, etc. This is so convenient that you often fire up | |
149 | the debugger all by itself just to test out Perl constructs | |
150 | interactively to see what they do. For example: | |
151 | .IX Xref "-d" | |
152 | .PP | |
153 | .Vb 1 | |
154 | \& $ perl -d -e 42 | |
155 | .Ve | |
156 | .PP | |
157 | In Perl, the debugger is not a separate program the way it usually is in the | |
158 | typical compiled environment. Instead, the \fB\-d\fR flag tells the compiler | |
159 | to insert source information into the parse trees it's about to hand off | |
160 | to the interpreter. That means your code must first compile correctly | |
161 | for the debugger to work on it. Then when the interpreter starts up, it | |
162 | preloads a special Perl library file containing the debugger. | |
163 | .PP | |
164 | The program will halt \fIright before\fR the first run-time executable | |
165 | statement (but see below regarding compile-time statements) and ask you | |
166 | to enter a debugger command. Contrary to popular expectations, whenever | |
167 | the debugger halts and shows you a line of code, it always displays the | |
168 | line it's \fIabout\fR to execute, rather than the one it has just executed. | |
169 | .PP | |
170 | Any command not recognized by the debugger is directly executed | |
171 | (\f(CW\*(C`eval\*(C'\fR'd) as Perl code in the current package. (The debugger | |
172 | uses the \s-1DB\s0 package for keeping its own state information.) | |
173 | .PP | |
174 | Note that the said \f(CW\*(C`eval\*(C'\fR is bound by an implicit scope. As a | |
175 | result any newly introduced lexical variable or any modified | |
176 | capture buffer content is lost after the eval. The debugger is a | |
177 | nice environment to learn Perl, but if you interactively experiment using | |
178 | material which should be in the same scope, stuff it in one line. | |
179 | .PP | |
180 | For any text entered at the debugger prompt, leading and trailing whitespace | |
181 | is first stripped before further processing. If a debugger command | |
182 | coincides with some function in your own program, merely precede the | |
183 | function with something that doesn't look like a debugger command, such | |
184 | as a leading \f(CW\*(C`;\*(C'\fR or perhaps a \f(CW\*(C`+\*(C'\fR, or by wrapping it with parentheses | |
185 | or braces. | |
186 | .Sh "Debugger Commands" | |
187 | .IX Subsection "Debugger Commands" | |
188 | The debugger understands the following commands: | |
189 | .IP "h" 12 | |
190 | .IX Xref "debugger command, h" | |
191 | .IX Item "h" | |
192 | Prints out a summary help message | |
193 | .IP "h [command]" 12 | |
194 | .IX Item "h [command]" | |
195 | Prints out a help message for the given debugger command. | |
196 | .IP "h h" 12 | |
197 | .IX Item "h h" | |
198 | The special argument of \f(CW\*(C`h h\*(C'\fR produces the entire help page, which is quite long. | |
199 | .Sp | |
200 | If the output of the \f(CW\*(C`h h\*(C'\fR command (or any command, for that matter) scrolls | |
201 | past your screen, precede the command with a leading pipe symbol so | |
202 | that it's run through your pager, as in | |
203 | .Sp | |
204 | .Vb 1 | |
205 | \& DB> |h h | |
206 | .Ve | |
207 | .Sp | |
208 | You may change the pager which is used via \f(CW\*(C`o pager=...\*(C'\fR command. | |
209 | .IP "p expr" 12 | |
210 | .IX Xref "debugger command, p" | |
211 | .IX Item "p expr" | |
212 | Same as \f(CW\*(C`print {$DB::OUT} expr\*(C'\fR in the current package. In particular, | |
213 | because this is just Perl's own \f(CW\*(C`print\*(C'\fR function, this means that nested | |
214 | data structures and objects are not dumped, unlike with the \f(CW\*(C`x\*(C'\fR command. | |
215 | .Sp | |
216 | The \f(CW\*(C`DB::OUT\*(C'\fR filehandle is opened to \fI/dev/tty\fR, regardless of | |
217 | where \s-1STDOUT\s0 may be redirected to. | |
218 | .IP "x [maxdepth] expr" 12 | |
219 | .IX Xref "debugger command, x" | |
220 | .IX Item "x [maxdepth] expr" | |
221 | Evaluates its expression in list context and dumps out the result in a | |
222 | pretty-printed fashion. Nested data structures are printed out | |
223 | recursively, unlike the real \f(CW\*(C`print\*(C'\fR function in Perl. When dumping | |
224 | hashes, you'll probably prefer 'x \e%h' rather than 'x \f(CW%h\fR'. | |
225 | See Dumpvalue if you'd like to do this yourself. | |
226 | .Sp | |
227 | The output format is governed by multiple options described under | |
228 | \&\*(L"Configurable Options\*(R". | |
229 | .Sp | |
230 | If the \f(CW\*(C`maxdepth\*(C'\fR is included, it must be a numeral \fIN\fR; the value is | |
231 | dumped only \fIN\fR levels deep, as if the \f(CW\*(C`dumpDepth\*(C'\fR option had been | |
232 | temporarily set to \fIN\fR. | |
233 | .IP "V [pkg [vars]]" 12 | |
234 | .IX Xref "debugger command, V" | |
235 | .IX Item "V [pkg [vars]]" | |
236 | Display all (or some) variables in package (defaulting to \f(CW\*(C`main\*(C'\fR) | |
237 | using a data pretty-printer (hashes show their keys and values so | |
238 | you see what's what, control characters are made printable, etc.). | |
239 | Make sure you don't put the type specifier (like \f(CW\*(C`$\*(C'\fR) there, just | |
240 | the symbol names, like this: | |
241 | .Sp | |
242 | .Vb 1 | |
243 | \& V DB filename line | |
244 | .Ve | |
245 | .Sp | |
246 | Use \f(CW\*(C`~pattern\*(C'\fR and \f(CW\*(C`!pattern\*(C'\fR for positive and negative regexes. | |
247 | .Sp | |
248 | This is similar to calling the \f(CW\*(C`x\*(C'\fR command on each applicable var. | |
249 | .IP "X [vars]" 12 | |
250 | .IX Xref "debugger command, X" | |
251 | .IX Item "X [vars]" | |
252 | Same as \f(CW\*(C`V currentpackage [vars]\*(C'\fR. | |
253 | .IP "y [level [vars]]" 12 | |
254 | .IX Xref "debugger command, y" | |
255 | .IX Item "y [level [vars]]" | |
256 | Display all (or some) lexical variables (mnemonic: \f(CW\*(C`mY\*(C'\fR variables) | |
257 | in the current scope or \fIlevel\fR scopes higher. You can limit the | |
258 | variables that you see with \fIvars\fR which works exactly as it does | |
259 | for the \f(CW\*(C`V\*(C'\fR and \f(CW\*(C`X\*(C'\fR commands. Requires the \f(CW\*(C`PadWalker\*(C'\fR module | |
260 | version 0.08 or higher; will warn if this isn't installed. Output | |
261 | is pretty-printed in the same style as for \f(CW\*(C`V\*(C'\fR and the format is | |
262 | controlled by the same options. | |
263 | .IP "T" 12 | |
264 | .IX Xref "debugger command, T backtrace stack, backtrace" | |
265 | .IX Item "T" | |
266 | Produce a stack backtrace. See below for details on its output. | |
267 | .IP "s [expr]" 12 | |
268 | .IX Xref "debugger command, s step" | |
269 | .IX Item "s [expr]" | |
270 | Single step. Executes until the beginning of another | |
271 | statement, descending into subroutine calls. If an expression is | |
272 | supplied that includes function calls, it too will be single\-stepped. | |
273 | .IP "n [expr]" 12 | |
274 | .IX Xref "debugger command, n" | |
275 | .IX Item "n [expr]" | |
276 | Next. Executes over subroutine calls, until the beginning | |
277 | of the next statement. If an expression is supplied that includes | |
278 | function calls, those functions will be executed with stops before | |
279 | each statement. | |
280 | .IP "r" 12 | |
281 | .IX Xref "debugger command, r" | |
282 | .IX Item "r" | |
283 | Continue until the return from the current subroutine. | |
284 | Dump the return value if the \f(CW\*(C`PrintRet\*(C'\fR option is set (default). | |
285 | .IP "<\s-1CR\s0>" 12 | |
286 | .IX Item "<CR>" | |
287 | Repeat last \f(CW\*(C`n\*(C'\fR or \f(CW\*(C`s\*(C'\fR command. | |
288 | .IP "c [line|sub]" 12 | |
289 | .IX Xref "debugger command, c" | |
290 | .IX Item "c [line|sub]" | |
291 | Continue, optionally inserting a one-time-only breakpoint | |
292 | at the specified line or subroutine. | |
293 | .IP "l" 12 | |
294 | .IX Xref "debugger command, l" | |
295 | .IX Item "l" | |
296 | List next window of lines. | |
297 | .IP "l min+incr" 12 | |
298 | .IX Item "l min+incr" | |
299 | List \f(CW\*(C`incr+1\*(C'\fR lines starting at \f(CW\*(C`min\*(C'\fR. | |
300 | .IP "l min-max" 12 | |
301 | .IX Item "l min-max" | |
302 | List lines \f(CW\*(C`min\*(C'\fR through \f(CW\*(C`max\*(C'\fR. \f(CW\*(C`l \-\*(C'\fR is synonymous to \f(CW\*(C`\-\*(C'\fR. | |
303 | .IP "l line" 12 | |
304 | .IX Item "l line" | |
305 | List a single line. | |
306 | .IP "l subname" 12 | |
307 | .IX Item "l subname" | |
308 | List first window of lines from subroutine. \fIsubname\fR may | |
309 | be a variable that contains a code reference. | |
310 | .IP "\-" 12 | |
311 | .IX Xref "debugger command, -" | |
312 | List previous window of lines. | |
313 | .IP "v [line]" 12 | |
314 | .IX Xref "debugger command, v" | |
315 | .IX Item "v [line]" | |
316 | View a few lines of code around the current line. | |
317 | .IP "." 12 | |
318 | .IX Xref "debugger command, ." | |
319 | Return the internal debugger pointer to the line last | |
320 | executed, and print out that line. | |
321 | .IP "f filename" 12 | |
322 | .IX Xref "debugger command, f" | |
323 | .IX Item "f filename" | |
324 | Switch to viewing a different file or \f(CW\*(C`eval\*(C'\fR statement. If \fIfilename\fR | |
325 | is not a full pathname found in the values of \f(CW%INC\fR, it is considered | |
326 | a regex. | |
327 | .Sp | |
328 | \&\f(CW\*(C`eval\*(C'\fRed strings (when accessible) are considered to be filenames: | |
329 | \&\f(CW\*(C`f (eval 7)\*(C'\fR and \f(CW\*(C`f eval 7\eb\*(C'\fR access the body of the 7th \f(CW\*(C`eval\*(C'\fRed string | |
330 | (in the order of execution). The bodies of the currently executed \f(CW\*(C`eval\*(C'\fR | |
331 | and of \f(CW\*(C`eval\*(C'\fRed strings that define subroutines are saved and thus | |
332 | accessible. | |
333 | .IP "/pattern/" 12 | |
334 | .IX Item "/pattern/" | |
335 | Search forwards for pattern (a Perl regex); final / is optional. | |
336 | The search is case-insensitive by default. | |
337 | .IP "?pattern?" 12 | |
338 | .IX Item "?pattern?" | |
339 | Search backwards for pattern; final ? is optional. | |
340 | The search is case-insensitive by default. | |
341 | .IP "L [abw]" 12 | |
342 | .IX Xref "debugger command, L" | |
343 | .IX Item "L [abw]" | |
344 | List (default all) actions, breakpoints and watch expressions | |
345 | .IP "S [[!]regex]" 12 | |
346 | .IX Xref "debugger command, S" | |
347 | .IX Item "S [[!]regex]" | |
348 | List subroutine names [not] matching the regex. | |
349 | .IP "t" 12 | |
350 | .IX Xref "debugger command, t" | |
351 | .IX Item "t" | |
352 | Toggle trace mode (see also the \f(CW\*(C`AutoTrace\*(C'\fR option). | |
353 | .IP "t expr" 12 | |
354 | .IX Xref "debugger command, t" | |
355 | .IX Item "t expr" | |
356 | Trace through execution of \f(CW\*(C`expr\*(C'\fR. | |
357 | See \*(L"Frame Listing Output Examples\*(R" in perldebguts for examples. | |
358 | .IP "b" 12 | |
359 | .IX Xref "breakpoint debugger command, b" | |
360 | .IX Item "b" | |
361 | Sets breakpoint on current line | |
362 | .IP "b [line] [condition]" 12 | |
363 | .IX Xref "breakpoint debugger command, b" | |
364 | .IX Item "b [line] [condition]" | |
365 | Set a breakpoint before the given line. If a condition | |
366 | is specified, it's evaluated each time the statement is reached: a | |
367 | breakpoint is taken only if the condition is true. Breakpoints may | |
368 | only be set on lines that begin an executable statement. Conditions | |
369 | don't use \f(CW\*(C`if\*(C'\fR: | |
370 | .Sp | |
371 | .Vb 3 | |
372 | \& b 237 $x > 30 | |
373 | \& b 237 ++$count237 < 11 | |
374 | \& b 33 /pattern/i | |
375 | .Ve | |
376 | .IP "b subname [condition]" 12 | |
377 | .IX Xref "breakpoint debugger command, b" | |
378 | .IX Item "b subname [condition]" | |
379 | Set a breakpoint before the first line of the named subroutine. \fIsubname\fR may | |
380 | be a variable containing a code reference (in this case \fIcondition\fR | |
381 | is not supported). | |
382 | .IP "b postpone subname [condition]" 12 | |
383 | .IX Xref "breakpoint debugger command, b" | |
384 | .IX Item "b postpone subname [condition]" | |
385 | Set a breakpoint at first line of subroutine after it is compiled. | |
386 | .IP "b load filename" 12 | |
387 | .IX Xref "breakpoint debugger command, b" | |
388 | .IX Item "b load filename" | |
389 | Set a breakpoint before the first executed line of the \fIfilename\fR, | |
390 | which should be a full pathname found amongst the \f(CW%INC\fR values. | |
391 | .IP "b compile subname" 12 | |
392 | .IX Xref "breakpoint debugger command, b" | |
393 | .IX Item "b compile subname" | |
394 | Sets a breakpoint before the first statement executed after the specified | |
395 | subroutine is compiled. | |
396 | .IP "B line" 12 | |
397 | .IX Xref "breakpoint debugger command, B" | |
398 | .IX Item "B line" | |
399 | Delete a breakpoint from the specified \fIline\fR. | |
400 | .IP "B *" 12 | |
401 | .IX Xref "breakpoint debugger command, B" | |
402 | .IX Item "B *" | |
403 | Delete all installed breakpoints. | |
404 | .IP "a [line] command" 12 | |
405 | .IX Xref "debugger command, a" | |
406 | .IX Item "a [line] command" | |
407 | Set an action to be done before the line is executed. If \fIline\fR is | |
408 | omitted, set an action on the line about to be executed. | |
409 | The sequence of steps taken by the debugger is | |
410 | .Sp | |
411 | .Vb 5 | |
412 | \& 1. check for a breakpoint at this line | |
413 | \& 2. print the line if necessary (tracing) | |
414 | \& 3. do any actions associated with that line | |
415 | \& 4. prompt user if at a breakpoint or in single-step | |
416 | \& 5. evaluate line | |
417 | .Ve | |
418 | .Sp | |
419 | For example, this will print out \f(CW$foo\fR every time line | |
420 | 53 is passed: | |
421 | .Sp | |
422 | .Vb 1 | |
423 | \& a 53 print "DB FOUND $foo\en" | |
424 | .Ve | |
425 | .IP "A line" 12 | |
426 | .IX Xref "debugger command, A" | |
427 | .IX Item "A line" | |
428 | Delete an action from the specified line. | |
429 | .IP "A *" 12 | |
430 | .IX Xref "debugger command, A" | |
431 | .IX Item "A *" | |
432 | Delete all installed actions. | |
433 | .IP "w expr" 12 | |
434 | .IX Xref "debugger command, w" | |
435 | .IX Item "w expr" | |
436 | Add a global watch\-expression. We hope you know what one of these | |
437 | is, because they're supposed to be obvious. | |
438 | .IP "W expr" 12 | |
439 | .IX Xref "debugger command, W" | |
440 | .IX Item "W expr" | |
441 | Delete watch-expression | |
442 | .IP "W *" 12 | |
443 | .IX Xref "debugger command, W" | |
444 | .IX Item "W *" | |
445 | Delete all watch\-expressions. | |
446 | .IP "o" 12 | |
447 | .IX Xref "debugger command, o" | |
448 | Display all options | |
449 | .IP "o booloption ..." 12 | |
450 | .IX Xref "debugger command, o" | |
451 | .IX Item "booloption ..." | |
452 | Set each listed Boolean option to the value \f(CW1\fR. | |
453 | .IP "o anyoption? ..." 12 | |
454 | .IX Xref "debugger command, o" | |
455 | .IX Item "anyoption? ..." | |
456 | Print out the value of one or more options. | |
457 | .IP "o option=value ..." 12 | |
458 | .IX Xref "debugger command, o" | |
459 | .IX Item "option=value ..." | |
460 | Set the value of one or more options. If the value has internal | |
461 | whitespace, it should be quoted. For example, you could set \f(CW\*(C`o | |
462 | pager="less \-MQeicsNfr"\*(C'\fR to call \fBless\fR with those specific options. | |
463 | You may use either single or double quotes, but if you do, you must | |
464 | escape any embedded instances of same sort of quote you began with, | |
465 | as well as any escaping any escapes that immediately precede that | |
466 | quote but which are not meant to escape the quote itself. In other | |
467 | words, you follow single-quoting rules irrespective of the quote; | |
468 | eg: \f(CW\*(C`o option='this isn\e't bad'\*(C'\fR or \f(CW\*(C`o option="She said, \e"Isn't | |
469 | it?\e""\*(C'\fR. | |
470 | .Sp | |
471 | For historical reasons, the \f(CW\*(C`=value\*(C'\fR is optional, but defaults to | |
472 | 1 only where it is safe to do so\*(--that is, mostly for Boolean | |
473 | options. It is always better to assign a specific value using \f(CW\*(C`=\*(C'\fR. | |
474 | The \f(CW\*(C`option\*(C'\fR can be abbreviated, but for clarity probably should | |
475 | not be. Several options can be set together. See \*(L"Configurable Options\*(R" | |
476 | for a list of these. | |
477 | .IP "< ?" 12 | |
478 | .IX Xref "debugger command, <" | |
479 | List out all pre-prompt Perl command actions. | |
480 | .IP "< [ command ]" 12 | |
481 | .IX Xref "debugger command, <" | |
482 | .IX Item "< [ command ]" | |
483 | Set an action (Perl command) to happen before every debugger prompt. | |
484 | A multi-line command may be entered by backslashing the newlines. | |
485 | .IP "< *" 12 | |
486 | .IX Xref "debugger command, <" | |
487 | Delete all pre-prompt Perl command actions. | |
488 | .IP "<< command" 12 | |
489 | .IX Xref "debugger command, <<" | |
490 | .IX Item "<< command" | |
491 | Add an action (Perl command) to happen before every debugger prompt. | |
492 | A multi-line command may be entered by backwhacking the newlines. | |
493 | .IP "> ?" 12 | |
494 | .IX Xref "debugger command, >" | |
495 | List out post-prompt Perl command actions. | |
496 | .IP "> command" 12 | |
497 | .IX Xref "debugger command, >" | |
498 | .IX Item "> command" | |
499 | Set an action (Perl command) to happen after the prompt when you've | |
500 | just given a command to return to executing the script. A multi-line | |
501 | command may be entered by backslashing the newlines (we bet you | |
502 | couldn't've guessed this by now). | |
503 | .IP "> *" 12 | |
504 | .IX Xref "debugger command, >" | |
505 | Delete all post-prompt Perl command actions. | |
506 | .IP ">> command" 12 | |
507 | .IX Xref "debugger command, >>" | |
508 | .IX Item ">> command" | |
509 | Adds an action (Perl command) to happen after the prompt when you've | |
510 | just given a command to return to executing the script. A multi-line | |
511 | command may be entered by backslashing the newlines. | |
512 | .IP "{ ?" 12 | |
513 | .IX Xref "debugger command, {" | |
514 | List out pre-prompt debugger commands. | |
515 | .IP "{ [ command ]" 12 | |
516 | .IX Item "{ [ command ]" | |
517 | Set an action (debugger command) to happen before every debugger prompt. | |
518 | A multi-line command may be entered in the customary fashion. | |
519 | .Sp | |
520 | Because this command is in some senses new, a warning is issued if | |
521 | you appear to have accidentally entered a block instead. If that's | |
522 | what you mean to do, write it as with \f(CW\*(C`;{ ... }\*(C'\fR or even | |
523 | \&\f(CW\*(C`do { ... }\*(C'\fR. | |
524 | .IP "{ *" 12 | |
525 | .IX Xref "debugger command, {" | |
526 | Delete all pre-prompt debugger commands. | |
527 | .IP "{{ command" 12 | |
528 | .IX Xref "debugger command, {{" | |
529 | .IX Item "{{ command" | |
530 | Add an action (debugger command) to happen before every debugger prompt. | |
531 | A multi-line command may be entered, if you can guess how: see above. | |
532 | .IP "! number" 12 | |
533 | .IX Xref "debugger command, !" | |
534 | .IX Item "! number" | |
535 | Redo a previous command (defaults to the previous command). | |
536 | .IP "! \-number" 12 | |
537 | .IX Xref "debugger command, !" | |
538 | .IX Item "! -number" | |
539 | Redo number'th previous command. | |
540 | .IP "! pattern" 12 | |
541 | .IX Xref "debugger command, !" | |
542 | .IX Item "! pattern" | |
543 | Redo last command that started with pattern. | |
544 | See \f(CW\*(C`o recallCommand\*(C'\fR, too. | |
545 | .IP "!! cmd" 12 | |
546 | .IX Xref "debugger command, !!" | |
547 | .IX Item "!! cmd" | |
548 | Run cmd in a subprocess (reads from \s-1DB::IN\s0, writes to \s-1DB::OUT\s0) See | |
549 | \&\f(CW\*(C`o shellBang\*(C'\fR, also. Note that the user's current shell (well, | |
550 | their \f(CW$ENV{SHELL}\fR variable) will be used, which can interfere | |
551 | with proper interpretation of exit status or signal and coredump | |
552 | information. | |
553 | .IP "source file" 12 | |
554 | .IX Xref "debugger command, source" | |
555 | .IX Item "source file" | |
556 | Read and execute debugger commands from \fIfile\fR. | |
557 | \&\fIfile\fR may itself contain \f(CW\*(C`source\*(C'\fR commands. | |
558 | .IP "H \-number" 12 | |
559 | .IX Xref "debugger command, H" | |
560 | .IX Item "H -number" | |
561 | Display last n commands. Only commands longer than one character are | |
562 | listed. If \fInumber\fR is omitted, list them all. | |
563 | .IP "q or ^D" 12 | |
564 | .IX Xref "debugger command, q debugger command, ^D" | |
565 | .IX Item "q or ^D" | |
566 | Quit. (\*(L"quit\*(R" doesn't work for this, unless you've made an alias) | |
567 | This is the only supported way to exit the debugger, though typing | |
568 | \&\f(CW\*(C`exit\*(C'\fR twice might work. | |
569 | .Sp | |
570 | Set the \f(CW\*(C`inhibit_exit\*(C'\fR option to 0 if you want to be able to step | |
571 | off the end the script. You may also need to set \f(CW$finished\fR to 0 | |
572 | if you want to step through global destruction. | |
573 | .IP "R" 12 | |
574 | .IX Xref "debugger command, R" | |
575 | .IX Item "R" | |
576 | Restart the debugger by \f(CW\*(C`exec()\*(C'\fRing a new session. We try to maintain | |
577 | your history across this, but internal settings and command-line options | |
578 | may be lost. | |
579 | .Sp | |
580 | The following setting are currently preserved: history, breakpoints, | |
581 | actions, debugger options, and the Perl command-line | |
582 | options \fB\-w\fR, \fB\-I\fR, and \fB\-e\fR. | |
583 | .IP "|dbcmd" 12 | |
584 | .IX Xref "debugger command, |" | |
585 | .IX Item "|dbcmd" | |
586 | Run the debugger command, piping \s-1DB::OUT\s0 into your current pager. | |
587 | .IP "||dbcmd" 12 | |
588 | .IX Xref "debugger command, ||" | |
589 | .IX Item "||dbcmd" | |
590 | Same as \f(CW\*(C`|dbcmd\*(C'\fR but \s-1DB::OUT\s0 is temporarily \f(CW\*(C`select\*(C'\fRed as well. | |
591 | .IP "= [alias value]" 12 | |
592 | .IX Xref "debugger command, =" | |
593 | .IX Item "= [alias value]" | |
594 | Define a command alias, like | |
595 | .Sp | |
596 | .Vb 1 | |
597 | \& = quit q | |
598 | .Ve | |
599 | .Sp | |
600 | or list current aliases. | |
601 | .IP "command" 12 | |
602 | .IX Item "command" | |
603 | Execute command as a Perl statement. A trailing semicolon will be | |
604 | supplied. If the Perl statement would otherwise be confused for a | |
605 | Perl debugger, use a leading semicolon, too. | |
606 | .IP "m expr" 12 | |
607 | .IX Xref "debugger command, m" | |
608 | .IX Item "m expr" | |
609 | List which methods may be called on the result of the evaluated | |
610 | expression. The expression may evaluated to a reference to a | |
611 | blessed object, or to a package name. | |
612 | .IP "M" 12 | |
613 | .IX Xref "debugger command, M" | |
614 | .IX Item "M" | |
615 | Displays all loaded modules and their versions | |
616 | .IP "man [manpage]" 12 | |
617 | .IX Xref "debugger command, man" | |
618 | .IX Item "man [manpage]" | |
619 | Despite its name, this calls your system's default documentation | |
620 | viewer on the given page, or on the viewer itself if \fImanpage\fR is | |
621 | omitted. If that viewer is \fBman\fR, the current \f(CW\*(C`Config\*(C'\fR information | |
622 | is used to invoke \fBman\fR using the proper \s-1MANPATH\s0 or \fB\-M\fR\ \fImanpath\fR option. Failed lookups of the form \f(CW\*(C`XXX\*(C'\fR that match | |
623 | known manpages of the form \fIperlXXX\fR will be retried. This lets | |
624 | you type \f(CW\*(C`man debug\*(C'\fR or \f(CW\*(C`man op\*(C'\fR from the debugger. | |
625 | .Sp | |
626 | On systems traditionally bereft of a usable \fBman\fR command, the | |
627 | debugger invokes \fBperldoc\fR. Occasionally this determination is | |
628 | incorrect due to recalcitrant vendors or rather more felicitously, | |
629 | to enterprising users. If you fall into either category, just | |
630 | manually set the \f(CW$DB::doccmd\fR variable to whatever viewer to view | |
631 | the Perl documentation on your system. This may be set in an rc | |
632 | file, or through direct assignment. We're still waiting for a | |
633 | working example of something along the lines of: | |
634 | .Sp | |
635 | .Vb 1 | |
636 | \& $DB::doccmd = 'netscape -remote http://something.here/'; | |
637 | .Ve | |
638 | .Sh "Configurable Options" | |
639 | .IX Subsection "Configurable Options" | |
640 | The debugger has numerous options settable using the \f(CW\*(C`o\*(C'\fR command, | |
641 | either interactively or from the environment or an rc file. | |
642 | (./.perldb or ~/.perldb under Unix.) | |
643 | .ie n .IP """recallCommand""\fR, \f(CW""ShellBang""" 12 | |
644 | .el .IP "\f(CWrecallCommand\fR, \f(CWShellBang\fR" 12 | |
645 | .IX Xref "debugger option, recallCommand debugger option, ShellBang" | |
646 | .IX Item "recallCommand, ShellBang" | |
647 | The characters used to recall command or spawn shell. By | |
648 | default, both are set to \f(CW\*(C`!\*(C'\fR, which is unfortunate. | |
649 | .ie n .IP """pager""" 12 | |
650 | .el .IP "\f(CWpager\fR" 12 | |
651 | .IX Xref "debugger option, pager" | |
652 | .IX Item "pager" | |
653 | Program to use for output of pager-piped commands (those beginning | |
654 | with a \f(CW\*(C`|\*(C'\fR character.) By default, \f(CW$ENV{PAGER}\fR will be used. | |
655 | Because the debugger uses your current terminal characteristics | |
656 | for bold and underlining, if the chosen pager does not pass escape | |
657 | sequences through unchanged, the output of some debugger commands | |
658 | will not be readable when sent through the pager. | |
659 | .ie n .IP """tkRunning""" 12 | |
660 | .el .IP "\f(CWtkRunning\fR" 12 | |
661 | .IX Xref "debugger option, tkRunning" | |
662 | .IX Item "tkRunning" | |
663 | Run Tk while prompting (with ReadLine). | |
664 | .ie n .IP """signalLevel""\fR, \f(CW""warnLevel""\fR, \f(CW""dieLevel""" 12 | |
665 | .el .IP "\f(CWsignalLevel\fR, \f(CWwarnLevel\fR, \f(CWdieLevel\fR" 12 | |
666 | .IX Xref "debugger option, signalLevel debugger option, warnLevel debugger option, dieLevel" | |
667 | .IX Item "signalLevel, warnLevel, dieLevel" | |
668 | Level of verbosity. By default, the debugger leaves your exceptions | |
669 | and warnings alone, because altering them can break correctly running | |
670 | programs. It will attempt to print a message when uncaught \s-1INT\s0, \s-1BUS\s0, or | |
671 | \&\s-1SEGV\s0 signals arrive. (But see the mention of signals in \s-1BUGS\s0 below.) | |
672 | .Sp | |
673 | To disable this default safe mode, set these values to something higher | |
674 | than 0. At a level of 1, you get backtraces upon receiving any kind | |
675 | of warning (this is often annoying) or exception (this is | |
676 | often valuable). Unfortunately, the debugger cannot discern fatal | |
677 | exceptions from non-fatal ones. If \f(CW\*(C`dieLevel\*(C'\fR is even 1, then your | |
678 | non-fatal exceptions are also traced and unceremoniously altered if they | |
679 | came from \f(CW\*(C`eval'd\*(C'\fR strings or from any kind of \f(CW\*(C`eval\*(C'\fR within modules | |
680 | you're attempting to load. If \f(CW\*(C`dieLevel\*(C'\fR is 2, the debugger doesn't | |
681 | care where they came from: It usurps your exception handler and prints | |
682 | out a trace, then modifies all exceptions with its own embellishments. | |
683 | This may perhaps be useful for some tracing purposes, but tends to hopelessly | |
684 | destroy any program that takes its exception handling seriously. | |
685 | .ie n .IP """AutoTrace""" 12 | |
686 | .el .IP "\f(CWAutoTrace\fR" 12 | |
687 | .IX Xref "debugger option, AutoTrace" | |
688 | .IX Item "AutoTrace" | |
689 | Trace mode (similar to \f(CW\*(C`t\*(C'\fR command, but can be put into | |
690 | \&\f(CW\*(C`PERLDB_OPTS\*(C'\fR). | |
691 | .ie n .IP """LineInfo""" 12 | |
692 | .el .IP "\f(CWLineInfo\fR" 12 | |
693 | .IX Xref "debugger option, LineInfo" | |
694 | .IX Item "LineInfo" | |
695 | File or pipe to print line number info to. If it is a pipe (say, | |
696 | \&\f(CW\*(C`|visual_perl_db\*(C'\fR), then a short message is used. This is the | |
697 | mechanism used to interact with a slave editor or visual debugger, | |
698 | such as the special \f(CW\*(C`vi\*(C'\fR or \f(CW\*(C`emacs\*(C'\fR hooks, or the \f(CW\*(C`ddd\*(C'\fR graphical | |
699 | debugger. | |
700 | .ie n .IP """inhibit_exit""" 12 | |
701 | .el .IP "\f(CWinhibit_exit\fR" 12 | |
702 | .IX Xref "debugger option, inhibit_exit" | |
703 | .IX Item "inhibit_exit" | |
704 | If 0, allows \fIstepping off\fR the end of the script. | |
705 | .ie n .IP """PrintRet""" 12 | |
706 | .el .IP "\f(CWPrintRet\fR" 12 | |
707 | .IX Xref "debugger option, PrintRet" | |
708 | .IX Item "PrintRet" | |
709 | Print return value after \f(CW\*(C`r\*(C'\fR command if set (default). | |
710 | .ie n .IP """ornaments""" 12 | |
711 | .el .IP "\f(CWornaments\fR" 12 | |
712 | .IX Xref "debugger option, ornaments" | |
713 | .IX Item "ornaments" | |
714 | Affects screen appearance of the command line (see Term::ReadLine). | |
715 | There is currently no way to disable these, which can render | |
716 | some output illegible on some displays, or with some pagers. | |
717 | This is considered a bug. | |
718 | .ie n .IP """frame""" 12 | |
719 | .el .IP "\f(CWframe\fR" 12 | |
720 | .IX Xref "debugger option, frame" | |
721 | .IX Item "frame" | |
722 | Affects the printing of messages upon entry and exit from subroutines. If | |
723 | \&\f(CW\*(C`frame & 2\*(C'\fR is false, messages are printed on entry only. (Printing | |
724 | on exit might be useful if interspersed with other messages.) | |
725 | .Sp | |
726 | If \f(CW\*(C`frame & 4\*(C'\fR, arguments to functions are printed, plus context | |
727 | and caller info. If \f(CW\*(C`frame & 8\*(C'\fR, overloaded \f(CW\*(C`stringify\*(C'\fR and | |
728 | \&\f(CW\*(C`tie\*(C'\fRd \f(CW\*(C`FETCH\*(C'\fR is enabled on the printed arguments. If \f(CW\*(C`frame | |
729 | & 16\*(C'\fR, the return value from the subroutine is printed. | |
730 | .Sp | |
731 | The length at which the argument list is truncated is governed by the | |
732 | next option: | |
733 | .ie n .IP """maxTraceLen""" 12 | |
734 | .el .IP "\f(CWmaxTraceLen\fR" 12 | |
735 | .IX Xref "debugger option, maxTraceLen" | |
736 | .IX Item "maxTraceLen" | |
737 | Length to truncate the argument list when the \f(CW\*(C`frame\*(C'\fR option's | |
738 | bit 4 is set. | |
739 | .ie n .IP """windowSize""" 12 | |
740 | .el .IP "\f(CWwindowSize\fR" 12 | |
741 | .IX Xref "debugger option, windowSize" | |
742 | .IX Item "windowSize" | |
743 | Change the size of code list window (default is 10 lines). | |
744 | .PP | |
745 | The following options affect what happens with \f(CW\*(C`V\*(C'\fR, \f(CW\*(C`X\*(C'\fR, and \f(CW\*(C`x\*(C'\fR | |
746 | commands: | |
747 | .ie n .IP """arrayDepth""\fR, \f(CW""hashDepth""" 12 | |
748 | .el .IP "\f(CWarrayDepth\fR, \f(CWhashDepth\fR" 12 | |
749 | .IX Xref "debugger option, arrayDepth debugger option, hashDepth" | |
750 | .IX Item "arrayDepth, hashDepth" | |
751 | Print only first N elements ('' for all). | |
752 | .ie n .IP """dumpDepth""" 12 | |
753 | .el .IP "\f(CWdumpDepth\fR" 12 | |
754 | .IX Xref "debugger option, dumpDepth" | |
755 | .IX Item "dumpDepth" | |
756 | Limit recursion depth to N levels when dumping structures. | |
757 | Negative values are interpreted as infinity. Default: infinity. | |
758 | .ie n .IP """compactDump""\fR, \f(CW""veryCompact""" 12 | |
759 | .el .IP "\f(CWcompactDump\fR, \f(CWveryCompact\fR" 12 | |
760 | .IX Xref "debugger option, compactDump debugger option, veryCompact" | |
761 | .IX Item "compactDump, veryCompact" | |
762 | Change the style of array and hash output. If \f(CW\*(C`compactDump\*(C'\fR, short array | |
763 | may be printed on one line. | |
764 | .ie n .IP """globPrint""" 12 | |
765 | .el .IP "\f(CWglobPrint\fR" 12 | |
766 | .IX Xref "debugger option, globPrint" | |
767 | .IX Item "globPrint" | |
768 | Whether to print contents of globs. | |
769 | .ie n .IP """DumpDBFiles""" 12 | |
770 | .el .IP "\f(CWDumpDBFiles\fR" 12 | |
771 | .IX Xref "debugger option, DumpDBFiles" | |
772 | .IX Item "DumpDBFiles" | |
773 | Dump arrays holding debugged files. | |
774 | .ie n .IP """DumpPackages""" 12 | |
775 | .el .IP "\f(CWDumpPackages\fR" 12 | |
776 | .IX Xref "debugger option, DumpPackages" | |
777 | .IX Item "DumpPackages" | |
778 | Dump symbol tables of packages. | |
779 | .ie n .IP """DumpReused""" 12 | |
780 | .el .IP "\f(CWDumpReused\fR" 12 | |
781 | .IX Xref "debugger option, DumpReused" | |
782 | .IX Item "DumpReused" | |
783 | Dump contents of \*(L"reused\*(R" addresses. | |
784 | .ie n .IP """quote""\fR, \f(CW""HighBit""\fR, \f(CW""undefPrint""" 12 | |
785 | .el .IP "\f(CWquote\fR, \f(CWHighBit\fR, \f(CWundefPrint\fR" 12 | |
786 | .IX Xref "debugger option, quote debugger option, HighBit debugger option, undefPrint" | |
787 | .IX Item "quote, HighBit, undefPrint" | |
788 | Change the style of string dump. The default value for \f(CW\*(C`quote\*(C'\fR | |
789 | is \f(CW\*(C`auto\*(C'\fR; one can enable double-quotish or single-quotish format | |
790 | by setting it to \f(CW\*(C`"\*(C'\fR or \f(CW\*(C`'\*(C'\fR, respectively. By default, characters | |
791 | with their high bit set are printed verbatim. | |
792 | .ie n .IP """UsageOnly""" 12 | |
793 | .el .IP "\f(CWUsageOnly\fR" 12 | |
794 | .IX Xref "debugger option, UsageOnly" | |
795 | .IX Item "UsageOnly" | |
796 | Rudimentary per-package memory usage dump. Calculates total | |
797 | size of strings found in variables in the package. This does not | |
798 | include lexicals in a module's file scope, or lost in closures. | |
799 | .PP | |
800 | After the rc file is read, the debugger reads the \f(CW$ENV{PERLDB_OPTS}\fR | |
801 | environment variable and parses this as the remainder of a \*(L"O ...\*(R" | |
802 | line as one might enter at the debugger prompt. You may place the | |
803 | initialization options \f(CW\*(C`TTY\*(C'\fR, \f(CW\*(C`noTTY\*(C'\fR, \f(CW\*(C`ReadLine\*(C'\fR, and \f(CW\*(C`NonStop\*(C'\fR | |
804 | there. | |
805 | .PP | |
806 | If your rc file contains: | |
807 | .PP | |
808 | .Vb 1 | |
809 | \& parse_options("NonStop=1 LineInfo=db.out AutoTrace"); | |
810 | .Ve | |
811 | .PP | |
812 | then your script will run without human intervention, putting trace | |
813 | information into the file \fIdb.out\fR. (If you interrupt it, you'd | |
814 | better reset \f(CW\*(C`LineInfo\*(C'\fR to \fI/dev/tty\fR if you expect to see anything.) | |
815 | .ie n .IP """TTY""" 12 | |
816 | .el .IP "\f(CWTTY\fR" 12 | |
817 | .IX Xref "debugger option, TTY" | |
818 | .IX Item "TTY" | |
819 | The \s-1TTY\s0 to use for debugging I/O. | |
820 | .ie n .IP """noTTY""" 12 | |
821 | .el .IP "\f(CWnoTTY\fR" 12 | |
822 | .IX Xref "debugger option, noTTY" | |
823 | .IX Item "noTTY" | |
824 | If set, the debugger goes into \f(CW\*(C`NonStop\*(C'\fR mode and will not connect to a \s-1TTY\s0. If | |
825 | interrupted (or if control goes to the debugger via explicit setting of | |
826 | \&\f(CW$DB::signal\fR or \f(CW$DB::single\fR from the Perl script), it connects to a \s-1TTY\s0 | |
827 | specified in the \f(CW\*(C`TTY\*(C'\fR option at startup, or to a tty found at | |
828 | runtime using the \f(CW\*(C`Term::Rendezvous\*(C'\fR module of your choice. | |
829 | .Sp | |
830 | This module should implement a method named \f(CW\*(C`new\*(C'\fR that returns an object | |
831 | with two methods: \f(CW\*(C`IN\*(C'\fR and \f(CW\*(C`OUT\*(C'\fR. These should return filehandles to use | |
832 | for debugging input and output correspondingly. The \f(CW\*(C`new\*(C'\fR method should | |
833 | inspect an argument containing the value of \f(CW$ENV{PERLDB_NOTTY}\fR at | |
834 | startup, or \f(CW"$ENV{HOME}/.perldbtty$$"\fR otherwise. This file is not | |
835 | inspected for proper ownership, so security hazards are theoretically | |
836 | possible. | |
837 | .ie n .IP """ReadLine""" 12 | |
838 | .el .IP "\f(CWReadLine\fR" 12 | |
839 | .IX Xref "debugger option, ReadLine" | |
840 | .IX Item "ReadLine" | |
841 | If false, readline support in the debugger is disabled in order | |
842 | to debug applications that themselves use ReadLine. | |
843 | .ie n .IP """NonStop""" 12 | |
844 | .el .IP "\f(CWNonStop\fR" 12 | |
845 | .IX Xref "debugger option, NonStop" | |
846 | .IX Item "NonStop" | |
847 | If set, the debugger goes into non-interactive mode until interrupted, or | |
848 | programmatically by setting \f(CW$DB::signal\fR or \f(CW$DB::single\fR. | |
849 | .PP | |
850 | Here's an example of using the \f(CW$ENV{PERLDB_OPTS}\fR variable: | |
851 | .PP | |
852 | .Vb 1 | |
853 | \& $ PERLDB_OPTS="NonStop frame=2" perl -d myprogram | |
854 | .Ve | |
855 | .PP | |
856 | That will run the script \fBmyprogram\fR without human intervention, | |
857 | printing out the call tree with entry and exit points. Note that | |
858 | \&\f(CW\*(C`NonStop=1 frame=2\*(C'\fR is equivalent to \f(CW\*(C`N f=2\*(C'\fR, and that originally, | |
859 | options could be uniquely abbreviated by the first letter (modulo | |
860 | the \f(CW\*(C`Dump*\*(C'\fR options). It is nevertheless recommended that you | |
861 | always spell them out in full for legibility and future compatibility. | |
862 | .PP | |
863 | Other examples include | |
864 | .PP | |
865 | .Vb 1 | |
866 | \& $ PERLDB_OPTS="NonStop LineInfo=listing frame=2" perl -d myprogram | |
867 | .Ve | |
868 | .PP | |
869 | which runs script non\-interactively, printing info on each entry | |
870 | into a subroutine and each executed line into the file named \fIlisting\fR. | |
871 | (If you interrupt it, you would better reset \f(CW\*(C`LineInfo\*(C'\fR to something | |
872 | \&\*(L"interactive\*(R"!) | |
873 | .PP | |
874 | Other examples include (using standard shell syntax to show environment | |
875 | variable settings): | |
876 | .PP | |
877 | .Vb 2 | |
878 | \& $ ( PERLDB_OPTS="NonStop frame=1 AutoTrace LineInfo=tperl.out" | |
879 | \& perl -d myprogram ) | |
880 | .Ve | |
881 | .PP | |
882 | which may be useful for debugging a program that uses \f(CW\*(C`Term::ReadLine\*(C'\fR | |
883 | itself. Do not forget to detach your shell from the \s-1TTY\s0 in the window that | |
884 | corresponds to \fI/dev/ttyXX\fR, say, by issuing a command like | |
885 | .PP | |
886 | .Vb 1 | |
887 | \& $ sleep 1000000 | |
888 | .Ve | |
889 | .PP | |
890 | See \*(L"Debugger Internals\*(R" in perldebguts for details. | |
891 | .Sh "Debugger input/output" | |
892 | .IX Subsection "Debugger input/output" | |
893 | .IP "Prompt" 8 | |
894 | .IX Item "Prompt" | |
895 | The debugger prompt is something like | |
896 | .Sp | |
897 | .Vb 1 | |
898 | \& DB<8> | |
899 | .Ve | |
900 | .Sp | |
901 | or even | |
902 | .Sp | |
903 | .Vb 1 | |
904 | \& DB<<17>> | |
905 | .Ve | |
906 | .Sp | |
907 | where that number is the command number, and which you'd use to | |
908 | access with the built-in \fBcsh\fR\-like history mechanism. For example, | |
909 | \&\f(CW\*(C`!17\*(C'\fR would repeat command number 17. The depth of the angle | |
910 | brackets indicates the nesting depth of the debugger. You could | |
911 | get more than one set of brackets, for example, if you'd already | |
912 | at a breakpoint and then printed the result of a function call that | |
913 | itself has a breakpoint, or you step into an expression via \f(CW\*(C`s/n/t | |
914 | expression\*(C'\fR command. | |
915 | .IP "Multiline commands" 8 | |
916 | .IX Item "Multiline commands" | |
917 | If you want to enter a multi-line command, such as a subroutine | |
918 | definition with several statements or a format, escape the newline | |
919 | that would normally end the debugger command with a backslash. | |
920 | Here's an example: | |
921 | .Sp | |
922 | .Vb 7 | |
923 | \& DB<1> for (1..4) { \e | |
924 | \& cont: print "ok\en"; \e | |
925 | \& cont: } | |
926 | \& ok | |
927 | \& ok | |
928 | \& ok | |
929 | \& ok | |
930 | .Ve | |
931 | .Sp | |
932 | Note that this business of escaping a newline is specific to interactive | |
933 | commands typed into the debugger. | |
934 | .IP "Stack backtrace" 8 | |
935 | .IX Xref "backtrace stack, backtrace" | |
936 | .IX Item "Stack backtrace" | |
937 | Here's an example of what a stack backtrace via \f(CW\*(C`T\*(C'\fR command might | |
938 | look like: | |
939 | .Sp | |
940 | .Vb 3 | |
941 | \& $ = main::infested called from file `Ambulation.pm' line 10 | |
942 | \& @ = Ambulation::legs(1, 2, 3, 4) called from file `camel_flea' line 7 | |
943 | \& $ = main::pests('bactrian', 4) called from file `camel_flea' line 4 | |
944 | .Ve | |
945 | .Sp | |
946 | The left-hand character up there indicates the context in which the | |
947 | function was called, with \f(CW\*(C`$\*(C'\fR and \f(CW\*(C`@\*(C'\fR meaning scalar or list | |
948 | contexts respectively, and \f(CW\*(C`.\*(C'\fR meaning void context (which is | |
949 | actually a sort of scalar context). The display above says | |
950 | that you were in the function \f(CW\*(C`main::infested\*(C'\fR when you ran the | |
951 | stack dump, and that it was called in scalar context from line | |
952 | 10 of the file \fIAmbulation.pm\fR, but without any arguments at all, | |
953 | meaning it was called as \f(CW&infested\fR. The next stack frame shows | |
954 | that the function \f(CW\*(C`Ambulation::legs\*(C'\fR was called in list context | |
955 | from the \fIcamel_flea\fR file with four arguments. The last stack | |
956 | frame shows that \f(CW\*(C`main::pests\*(C'\fR was called in scalar context, | |
957 | also from \fIcamel_flea\fR, but from line 4. | |
958 | .Sp | |
959 | If you execute the \f(CW\*(C`T\*(C'\fR command from inside an active \f(CW\*(C`use\*(C'\fR | |
960 | statement, the backtrace will contain both a \f(CW\*(C`require\*(C'\fR frame and | |
961 | an \f(CW\*(C`eval\*(C'\fR) frame. | |
962 | .IP "Line Listing Format" 8 | |
963 | .IX Item "Line Listing Format" | |
964 | This shows the sorts of output the \f(CW\*(C`l\*(C'\fR command can produce: | |
965 | .Sp | |
966 | .Vb 11 | |
967 | \& DB<<13>> l | |
968 | \& 101: @i{@i} = (); | |
969 | \& 102:b @isa{@i,$pack} = () | |
970 | \& 103 if(exists $i{$prevpack} || exists $isa{$pack}); | |
971 | \& 104 } | |
972 | \& 105 | |
973 | \& 106 next | |
974 | \& 107==> if(exists $isa{$pack}); | |
975 | \& 108 | |
976 | \& 109:a if ($extra-- > 0) { | |
977 | \& 110: %isa = ($pack,1); | |
978 | .Ve | |
979 | .Sp | |
980 | Breakable lines are marked with \f(CW\*(C`:\*(C'\fR. Lines with breakpoints are | |
981 | marked by \f(CW\*(C`b\*(C'\fR and those with actions by \f(CW\*(C`a\*(C'\fR. The line that's | |
982 | about to be executed is marked by \f(CW\*(C`==>\*(C'\fR. | |
983 | .Sp | |
984 | Please be aware that code in debugger listings may not look the same | |
985 | as your original source code. Line directives and external source | |
986 | filters can alter the code before Perl sees it, causing code to move | |
987 | from its original positions or take on entirely different forms. | |
988 | .IP "Frame listing" 8 | |
989 | .IX Item "Frame listing" | |
990 | When the \f(CW\*(C`frame\*(C'\fR option is set, the debugger would print entered (and | |
991 | optionally exited) subroutines in different styles. See perldebguts | |
992 | for incredibly long examples of these. | |
993 | .Sh "Debugging compile-time statements" | |
994 | .IX Subsection "Debugging compile-time statements" | |
995 | If you have compile-time executable statements (such as code within | |
996 | \&\s-1BEGIN\s0 and \s-1CHECK\s0 blocks or \f(CW\*(C`use\*(C'\fR statements), these will \fInot\fR be | |
997 | stopped by debugger, although \f(CW\*(C`require\*(C'\fRs and \s-1INIT\s0 blocks will, and | |
998 | compile-time statements can be traced with \f(CW\*(C`AutoTrace\*(C'\fR option set | |
999 | in \f(CW\*(C`PERLDB_OPTS\*(C'\fR). From your own Perl code, however, you can | |
1000 | transfer control back to the debugger using the following statement, | |
1001 | which is harmless if the debugger is not running: | |
1002 | .PP | |
1003 | .Vb 1 | |
1004 | \& $DB::single = 1; | |
1005 | .Ve | |
1006 | .PP | |
1007 | If you set \f(CW$DB::single\fR to 2, it's equivalent to having | |
1008 | just typed the \f(CW\*(C`n\*(C'\fR command, whereas a value of 1 means the \f(CW\*(C`s\*(C'\fR | |
1009 | command. The \f(CW$DB::trace\fR variable should be set to 1 to simulate | |
1010 | having typed the \f(CW\*(C`t\*(C'\fR command. | |
1011 | .PP | |
1012 | Another way to debug compile-time code is to start the debugger, set a | |
1013 | breakpoint on the \fIload\fR of some module: | |
1014 | .PP | |
1015 | .Vb 2 | |
1016 | \& DB<7> b load f:/perllib/lib/Carp.pm | |
1017 | \& Will stop on load of `f:/perllib/lib/Carp.pm'. | |
1018 | .Ve | |
1019 | .PP | |
1020 | and then restart the debugger using the \f(CW\*(C`R\*(C'\fR command (if possible). One can use \f(CW\*(C`b | |
1021 | compile subname\*(C'\fR for the same purpose. | |
1022 | .Sh "Debugger Customization" | |
1023 | .IX Subsection "Debugger Customization" | |
1024 | The debugger probably contains enough configuration hooks that you | |
1025 | won't ever have to modify it yourself. You may change the behaviour | |
1026 | of debugger from within the debugger using its \f(CW\*(C`o\*(C'\fR command, from | |
1027 | the command line via the \f(CW\*(C`PERLDB_OPTS\*(C'\fR environment variable, and | |
1028 | from customization files. | |
1029 | .PP | |
1030 | You can do some customization by setting up a \fI.perldb\fR file, which | |
1031 | contains initialization code. For instance, you could make aliases | |
1032 | like these (the last one is one people expect to be there): | |
1033 | .PP | |
1034 | .Vb 4 | |
1035 | \& $DB::alias{'len'} = 's/^len(.*)/p length($1)/'; | |
1036 | \& $DB::alias{'stop'} = 's/^stop (at|in)/b/'; | |
1037 | \& $DB::alias{'ps'} = 's/^ps\eb/p scalar /'; | |
1038 | \& $DB::alias{'quit'} = 's/^quit(\es*)/exit/'; | |
1039 | .Ve | |
1040 | .PP | |
1041 | You can change options from \fI.perldb\fR by using calls like this one; | |
1042 | .PP | |
1043 | .Vb 1 | |
1044 | \& parse_options("NonStop=1 LineInfo=db.out AutoTrace=1 frame=2"); | |
1045 | .Ve | |
1046 | .PP | |
1047 | The code is executed in the package \f(CW\*(C`DB\*(C'\fR. Note that \fI.perldb\fR is | |
1048 | processed before processing \f(CW\*(C`PERLDB_OPTS\*(C'\fR. If \fI.perldb\fR defines the | |
1049 | subroutine \f(CW\*(C`afterinit\*(C'\fR, that function is called after debugger | |
1050 | initialization ends. \fI.perldb\fR may be contained in the current | |
1051 | directory, or in the home directory. Because this file is sourced | |
1052 | in by Perl and may contain arbitrary commands, for security reasons, | |
1053 | it must be owned by the superuser or the current user, and writable | |
1054 | by no one but its owner. | |
1055 | .PP | |
1056 | You can mock \s-1TTY\s0 input to debugger by adding arbitrary commands to | |
1057 | \&\f(CW@DB::typeahead\fR. For example, your \fI.perldb\fR file might contain: | |
1058 | .PP | |
1059 | .Vb 1 | |
1060 | \& sub afterinit { push @DB::typeahead, "b 4", "b 6"; } | |
1061 | .Ve | |
1062 | .PP | |
1063 | Which would attempt to set breakpoints on lines 4 and 6 immediately | |
1064 | after debugger initialization. Note that \f(CW@DB::typeahead\fR is not a supported | |
1065 | interface and is subject to change in future releases. | |
1066 | .PP | |
1067 | If you want to modify the debugger, copy \fIperl5db.pl\fR from the | |
1068 | Perl library to another name and hack it to your heart's content. | |
1069 | You'll then want to set your \f(CW\*(C`PERL5DB\*(C'\fR environment variable to say | |
1070 | something like this: | |
1071 | .PP | |
1072 | .Vb 1 | |
1073 | \& BEGIN { require "myperl5db.pl" } | |
1074 | .Ve | |
1075 | .PP | |
1076 | As a last resort, you could also use \f(CW\*(C`PERL5DB\*(C'\fR to customize the debugger | |
1077 | by directly setting internal variables or calling debugger functions. | |
1078 | .PP | |
1079 | Note that any variables and functions that are not documented in | |
1080 | this document (or in perldebguts) are considered for internal | |
1081 | use only, and as such are subject to change without notice. | |
1082 | .Sh "Readline Support" | |
1083 | .IX Subsection "Readline Support" | |
1084 | As shipped, the only command-line history supplied is a simplistic one | |
1085 | that checks for leading exclamation points. However, if you install | |
1086 | the Term::ReadKey and Term::ReadLine modules from \s-1CPAN\s0, you will | |
1087 | have full editing capabilities much like \s-1GNU\s0 \fIreadline\fR(3) provides. | |
1088 | Look for these in the \fImodules/by\-module/Term\fR directory on \s-1CPAN\s0. | |
1089 | These do not support normal \fBvi\fR command-line editing, however. | |
1090 | .PP | |
1091 | A rudimentary command-line completion is also available. | |
1092 | Unfortunately, the names of lexical variables are not available for | |
1093 | completion. | |
1094 | .Sh "Editor Support for Debugging" | |
1095 | .IX Subsection "Editor Support for Debugging" | |
1096 | If you have the \s-1FSF\s0's version of \fBemacs\fR installed on your system, | |
1097 | it can interact with the Perl debugger to provide an integrated | |
1098 | software development environment reminiscent of its interactions | |
1099 | with C debuggers. | |
1100 | .PP | |
1101 | Perl comes with a start file for making \fBemacs\fR act like a | |
1102 | syntax-directed editor that understands (some of) Perl's syntax. | |
1103 | Look in the \fIemacs\fR directory of the Perl source distribution. | |
1104 | .PP | |
1105 | A similar setup by Tom Christiansen for interacting with any | |
1106 | vendor-shipped \fBvi\fR and the X11 window system is also available. | |
1107 | This works similarly to the integrated multiwindow support that | |
1108 | \&\fBemacs\fR provides, where the debugger drives the editor. At the | |
1109 | time of this writing, however, that tool's eventual location in the | |
1110 | Perl distribution was uncertain. | |
1111 | .PP | |
1112 | Users of \fBvi\fR should also look into \fBvim\fR and \fBgvim\fR, the mousey | |
1113 | and windy version, for coloring of Perl keywords. | |
1114 | .PP | |
1115 | Note that only perl can truly parse Perl, so all such \s-1CASE\s0 tools | |
1116 | fall somewhat short of the mark, especially if you don't program | |
1117 | your Perl as a C programmer might. | |
1118 | .Sh "The Perl Profiler" | |
1119 | .IX Xref "profile profiling profiler" | |
1120 | .IX Subsection "The Perl Profiler" | |
1121 | If you wish to supply an alternative debugger for Perl to run, just | |
1122 | invoke your script with a colon and a package argument given to the | |
1123 | \&\fB\-d\fR flag. The most popular alternative debuggers for Perl is the | |
1124 | Perl profiler. Devel::DProf is now included with the standard Perl | |
1125 | distribution. To profile your Perl program in the file \fImycode.pl\fR, | |
1126 | just type: | |
1127 | .PP | |
1128 | .Vb 1 | |
1129 | \& $ perl -d:DProf mycode.pl | |
1130 | .Ve | |
1131 | .PP | |
1132 | When the script terminates the profiler will dump the profile | |
1133 | information to a file called \fItmon.out\fR. A tool like \fBdprofpp\fR, | |
1134 | also supplied with the standard Perl distribution, can be used to | |
1135 | interpret the information in that profile. | |
1136 | .SH "Debugging regular expressions" | |
1137 | .IX Xref "regular expression, debugging regex, debugging regexp, debugging" | |
1138 | .IX Header "Debugging regular expressions" | |
1139 | \&\f(CW\*(C`use re 'debug'\*(C'\fR enables you to see the gory details of how the Perl | |
1140 | regular expression engine works. In order to understand this typically | |
1141 | voluminous output, one must not only have some idea about how regular | |
1142 | expression matching works in general, but also know how Perl's regular | |
1143 | expressions are internally compiled into an automaton. These matters | |
1144 | are explored in some detail in | |
1145 | \&\*(L"Debugging regular expressions\*(R" in perldebguts. | |
1146 | .SH "Debugging memory usage" | |
1147 | .IX Xref "memory usage" | |
1148 | .IX Header "Debugging memory usage" | |
1149 | Perl contains internal support for reporting its own memory usage, | |
1150 | but this is a fairly advanced concept that requires some understanding | |
1151 | of how memory allocation works. | |
1152 | See \*(L"Debugging Perl memory usage\*(R" in perldebguts for the details. | |
1153 | .SH "SEE ALSO" | |
1154 | .IX Header "SEE ALSO" | |
1155 | You did try the \fB\-w\fR switch, didn't you? | |
1156 | .PP | |
1157 | perldebtut, | |
1158 | perldebguts, | |
1159 | re, | |
1160 | \&\s-1DB\s0, | |
1161 | Devel::DProf, | |
1162 | dprofpp, | |
1163 | Dumpvalue, | |
1164 | and | |
1165 | perlrun. | |
1166 | .PP | |
1167 | When debugging a script that uses #! and is thus normally found in | |
1168 | \&\f(CW$PATH\fR, the \-S option causes perl to search \f(CW$PATH\fR for it, so you don't | |
1169 | have to type the path or \f(CW\*(C`which $scriptname\*(C'\fR. | |
1170 | .PP | |
1171 | .Vb 1 | |
1172 | \& $ perl -Sd foo.pl | |
1173 | .Ve | |
1174 | .SH "BUGS" | |
1175 | .IX Header "BUGS" | |
1176 | You cannot get stack frame information or in any fashion debug functions | |
1177 | that were not compiled by Perl, such as those from C or \*(C+ extensions. | |
1178 | .PP | |
1179 | If you alter your \f(CW@_\fR arguments in a subroutine (such as with \f(CW\*(C`shift\*(C'\fR | |
1180 | or \f(CW\*(C`pop\*(C'\fR), the stack backtrace will not show the original values. | |
1181 | .PP | |
1182 | The debugger does not currently work in conjunction with the \fB\-W\fR | |
1183 | command-line switch, because it itself is not free of warnings. | |
1184 | .PP | |
1185 | If you're in a slow syscall (like \f(CW\*(C`wait\*(C'\fRing, \f(CW\*(C`accept\*(C'\fRing, or \f(CW\*(C`read\*(C'\fRing | |
1186 | from your keyboard or a socket) and haven't set up your own \f(CW$SIG{INT}\fR | |
1187 | handler, then you won't be able to CTRL-C your way back to the debugger, | |
1188 | because the debugger's own \f(CW$SIG{INT}\fR handler doesn't understand that | |
1189 | it needs to raise an exception to \fIlongjmp\fR\|(3) out of slow syscalls. |