| 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. |