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