Debian Codegraph @

upstream/debian-unstable/man1/perldebug.1

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