diff options
Diffstat (limited to 'upstream/mageia-cauldron/man1/perldebug.1')
| -rw-r--r-- | upstream/mageia-cauldron/man1/perldebug.1 | 1213 |
1 files changed, 1213 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man1/perldebug.1 b/upstream/mageia-cauldron/man1/perldebug.1 new file mode 100644 index 00000000..bdbb3cf2 --- /dev/null +++ b/upstream/mageia-cauldron/man1/perldebug.1 @@ -0,0 +1,1213 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "PERLDEBUG 1" +.TH PERLDEBUG 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +perldebug \- Perl debugging +.IX Xref "debug debugger" +.SH DESCRIPTION +.IX Header "DESCRIPTION" +First of all, have you tried using \f(CW\*(C`use strict;\*(C'\fR and +\&\f(CW\*(C`use warnings;\*(C'\fR? +.PP +If you're new to the Perl debugger, you may prefer to read +perldebtut, which is a tutorial introduction to the debugger. +.PP +If you're looking for the nitty gritty details of how the debugger is +\&\fIimplemented\fR, you may prefer to read perldebguts. +.PP +For in-depth technical usage details, see perl5db.pl, the documentation +of the debugger itself. +.SH "The Perl Debugger" +.IX Header "The Perl Debugger" +If you invoke Perl with the \fB\-d\fR switch, your script runs under the +Perl source debugger. This works like an interactive Perl +environment, prompting for debugger commands that let you examine +source code, set breakpoints, get stack backtraces, change the values of +variables, etc. This is so convenient that you often fire up +the debugger all by itself just to test out Perl constructs +interactively to see what they do. For example: +.IX Xref "-d" +.PP +.Vb 1 +\& $ perl \-d \-e 42 +.Ve +.PP +In Perl, the debugger is not a separate program the way it usually is in the +typical compiled environment. Instead, the \fB\-d\fR flag tells the compiler +to insert source information into the parse trees it's about to hand off +to the interpreter. That means your code must first compile correctly +for the debugger to work on it. Then when the interpreter starts up, it +preloads a special Perl library file containing the debugger. +.PP +The program will halt \fIright before\fR the first run-time executable +statement (but see below regarding compile-time statements) and ask you +to enter a debugger command. Contrary to popular expectations, whenever +the debugger halts and shows you a line of code, it always displays the +line it's \fIabout\fR to execute, rather than the one it has just executed. +.PP +Any command not recognized by the debugger is directly executed +(\f(CW\*(C`eval\*(C'\fR'd) as Perl code in the current package. (The debugger +uses the DB package for keeping its own state information.) +.PP +Note that the said \f(CW\*(C`eval\*(C'\fR is bound by an implicit scope. As a +result any newly introduced lexical variable or any modified +capture buffer content is lost after the eval. The debugger is a +nice environment to learn Perl, but if you interactively experiment using +material which should be in the same scope, stuff it in one line. +.PP +For any text entered at the debugger prompt, leading and trailing whitespace +is first stripped before further processing. If a debugger command +coincides with some function in your own program, merely precede the +function with something that doesn't look like a debugger command, such +as a leading \f(CW\*(C`;\*(C'\fR or perhaps a \f(CW\*(C`+\*(C'\fR, or by wrapping it with parentheses +or braces. +.SS "Calling the Debugger" +.IX Subsection "Calling the Debugger" +There are several ways to call the debugger: +.IP "perl \-d program_name" 4 +.IX Item "perl -d program_name" +On the given program identified by \f(CW\*(C`program_name\*(C'\fR. +.IP "perl \-d \-e 0" 4 +.IX Item "perl -d -e 0" +Interactively supply an arbitrary \f(CW\*(C`expression\*(C'\fR using \f(CW\*(C`\-e\*(C'\fR. +.IP "perl \-d:ptkdb program_name" 4 +.IX Item "perl -d:ptkdb program_name" +Debug a given program via the Devel::ptkdb GUI. +.IP "perl \-dt threaded_program_name" 4 +.IX Item "perl -dt threaded_program_name" +Debug a given program using threads (experimental). +.PP +If Perl is called with the \f(CW\*(C`\-d\*(C'\fR switch, the variable \f(CW$^P\fR will hold a true +value. This is useful if you need to know if your code is running under the +debugger: +.PP +.Vb 3 +\& if ( $^P ) { +\& # running under the debugger +\& } +.Ve +.PP +See "$^P" in perlvar for more information on the variable. +.SS "Debugger Commands" +.IX Subsection "Debugger Commands" +The interactive debugger understands the following commands: +.IP h 12 +.IX Xref "debugger command, h" +.IX Item "h" +Prints out a summary help message +.IP "h [command]" 12 +.IX Item "h [command]" +Prints out a help message for the given debugger command. +.IP "h h" 12 +.IX Item "h h" +The special argument of \f(CW\*(C`h h\*(C'\fR produces the entire help page, which is quite long. +.Sp +If the output of the \f(CW\*(C`h h\*(C'\fR command (or any command, for that matter) scrolls +past your screen, precede the command with a leading pipe symbol so +that it's run through your pager, as in +.Sp +.Vb 1 +\& DB> |h h +.Ve +.Sp +You may change the pager which is used via \f(CW\*(C`o pager=...\*(C'\fR command. +.IP "p expr" 12 +.IX Xref "debugger command, p" +.IX Item "p expr" +Same as \f(CW\*(C`print {$DB::OUT} expr\*(C'\fR in the current package. In particular, +because this is just Perl's own \f(CW\*(C`print\*(C'\fR function, this means that nested +data structures and objects are not dumped, unlike with the \f(CW\*(C`x\*(C'\fR command. +.Sp +The \f(CW\*(C`DB::OUT\*(C'\fR filehandle is opened to \fI/dev/tty\fR, regardless of +where STDOUT may be redirected to. +.IP "x [maxdepth] expr" 12 +.IX Xref "debugger command, x" +.IX Item "x [maxdepth] expr" +Evaluates its expression in list context and dumps out the result in a +pretty-printed fashion. Nested data structures are printed out +recursively, unlike the real \f(CW\*(C`print\*(C'\fR function in Perl. When dumping +hashes, you'll probably prefer 'x \e%h' rather than 'x \f(CW%h\fR'. +See Dumpvalue if you'd like to do this yourself. +.Sp +The output format is governed by multiple options described under +"Configurable Options". +.Sp +If the \f(CW\*(C`maxdepth\*(C'\fR is included, it must be a numeral \fIN\fR; the value is +dumped only \fIN\fR levels deep, as if the \f(CW\*(C`dumpDepth\*(C'\fR option had been +temporarily set to \fIN\fR. +.IP "V [pkg [vars]]" 12 +.IX Xref "debugger command, V" +.IX Item "V [pkg [vars]]" +Display all (or some) variables in package (defaulting to \f(CW\*(C`main\*(C'\fR) +using a data pretty-printer (hashes show their keys and values so +you see what's what, control characters are made printable, etc.). +Make sure you don't put the type specifier (like \f(CW\*(C`$\*(C'\fR) there, just +the symbol names, like this: +.Sp +.Vb 1 +\& V DB filename line +.Ve +.Sp +Use \f(CW\*(C`~pattern\*(C'\fR and \f(CW\*(C`!pattern\*(C'\fR for positive and negative regexes. +.Sp +This is similar to calling the \f(CW\*(C`x\*(C'\fR command on each applicable var. +.IP "X [vars]" 12 +.IX Xref "debugger command, X" +.IX Item "X [vars]" +Same as \f(CW\*(C`V currentpackage [vars]\*(C'\fR. +.IP "y [level [vars]]" 12 +.IX Xref "debugger command, y" +.IX Item "y [level [vars]]" +Display all (or some) lexical variables (mnemonic: \f(CW\*(C`mY\*(C'\fR variables) +in the current scope or \fIlevel\fR scopes higher. You can limit the +variables that you see with \fIvars\fR which works exactly as it does +for the \f(CW\*(C`V\*(C'\fR and \f(CW\*(C`X\*(C'\fR commands. Requires the PadWalker module +version 0.08 or higher; will warn if this isn't installed. Output +is pretty-printed in the same style as for \f(CW\*(C`V\*(C'\fR and the format is +controlled by the same options. +.IP T 12 +.IX Xref "debugger command, T backtrace stack, backtrace" +.IX Item "T" +Produce a stack backtrace. See below for details on its output. +.IP "s [expr]" 12 +.IX Xref "debugger command, s step" +.IX Item "s [expr]" +Single step. Executes until the beginning of another +statement, descending into subroutine calls. If an expression is +supplied that includes function calls, it too will be single-stepped. +.IP "n [expr]" 12 +.IX Xref "debugger command, n" +.IX Item "n [expr]" +Next. Executes over subroutine calls, until the beginning +of the next statement. If an expression is supplied that includes +function calls, those functions will be executed with stops before +each statement. +.IP r 12 +.IX Xref "debugger command, r" +.IX Item "r" +Continue until the return from the current subroutine. +Dump the return value if the \f(CW\*(C`PrintRet\*(C'\fR option is set (default). +.IP <CR> 12 +.IX Item "<CR>" +Repeat last \f(CW\*(C`n\*(C'\fR or \f(CW\*(C`s\*(C'\fR command. +.IP "c [line|sub]" 12 +.IX Xref "debugger command, c" +.IX Item "c [line|sub]" +Continue, optionally inserting a one-time-only breakpoint +at the specified line or subroutine. +.IP l 12 +.IX Xref "debugger command, l" +.IX Item "l" +List next window of lines. +.IP "l min+incr" 12 +.IX Item "l min+incr" +List \f(CW\*(C`incr+1\*(C'\fR lines starting at \f(CW\*(C`min\*(C'\fR. +.IP "l min-max" 12 +.IX Item "l min-max" +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. +.IP "l line" 12 +.IX Item "l line" +List a single line. +.IP "l subname" 12 +.IX Item "l subname" +List first window of lines from subroutine. \fIsubname\fR may +be a variable that contains a code reference. +.IP \- 12 +.IX Xref "debugger command, -" +List previous window of lines. +.IP "v [line]" 12 +.IX Xref "debugger command, v" +.IX Item "v [line]" +View a few lines of code around the current line. +.IP . 12 +.IX Xref "debugger command, ." +Return the internal debugger pointer to the line last +executed, and print out that line. +.IP "f filename" 12 +.IX Xref "debugger command, f" +.IX Item "f filename" +Switch to viewing a different file or \f(CW\*(C`eval\*(C'\fR statement. If \fIfilename\fR +is not a full pathname found in the values of \f(CW%INC\fR, it is considered +a regex. +.Sp +\&\f(CW\*(C`eval\*(C'\fRed strings (when accessible) are considered to be filenames: +\&\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 +(in the order of execution). The bodies of the currently executed \f(CW\*(C`eval\*(C'\fR +and of \f(CW\*(C`eval\*(C'\fRed strings that define subroutines are saved and thus +accessible. +.IP /pattern/ 12 +.IX Item "/pattern/" +Search forwards for pattern (a Perl regex); final / is optional. +The search is case-insensitive by default. +.IP ?pattern? 12 +.IX Item "?pattern?" +Search backwards for pattern; final ? is optional. +The search is case-insensitive by default. +.IP "L [abw]" 12 +.IX Xref "debugger command, L" +.IX Item "L [abw]" +List (default all) actions, breakpoints and watch expressions +.IP "S [[!]regex]" 12 +.IX Xref "debugger command, S" +.IX Item "S [[!]regex]" +List subroutine names [not] matching the regex. +.IP "t [n]" 12 +.IX Xref "debugger command, t" +.IX Item "t [n]" +Toggle trace mode (see also the \f(CW\*(C`AutoTrace\*(C'\fR option). +Optional argument is the maximum number of levels to trace below +the current one; anything deeper than that will be silent. +.IP "t [n] expr" 12 +.IX Xref "debugger command, t" +.IX Item "t [n] expr" +Trace through execution of \f(CW\*(C`expr\*(C'\fR. +Optional first argument is the maximum number of levels to trace below +the current one; anything deeper than that will be silent. +See "Frame Listing Output Examples" in perldebguts for examples. +.IP b 12 +.IX Xref "breakpoint debugger command, b" +.IX Item "b" +Sets breakpoint on current line +.IP "b [line] [condition]" 12 +.IX Xref "breakpoint debugger command, b" +.IX Item "b [line] [condition]" +Set a breakpoint before the given line. If a condition +is specified, it's evaluated each time the statement is reached: a +breakpoint is taken only if the condition is true. Breakpoints may +only be set on lines that begin an executable statement. Conditions +don't use \f(CW\*(C`if\*(C'\fR: +.Sp +.Vb 3 +\& b 237 $x > 30 +\& b 237 ++$count237 < 11 +\& b 33 /pattern/i +.Ve +.Sp +If the line number is \f(CW\*(C`.\*(C'\fR, sets a breakpoint on the current line: +.Sp +.Vb 1 +\& b . $n > 100 +.Ve +.IP "b [file]:[line] [condition]" 12 +.IX Xref "breakpoint debugger command, b" +.IX Item "b [file]:[line] [condition]" +Set a breakpoint before the given line in a (possibly different) file. If a +condition is specified, it's evaluated each time the statement is reached: a +breakpoint is taken only if the condition is true. Breakpoints may only be set +on lines that begin an executable statement. Conditions don't use \f(CW\*(C`if\*(C'\fR: +.Sp +.Vb 2 +\& b lib/MyModule.pm:237 $x > 30 +\& b /usr/lib/perl5/site_perl/CGI.pm:100 ++$count100 < 11 +.Ve +.IP "b subname [condition]" 12 +.IX Xref "breakpoint debugger command, b" +.IX Item "b subname [condition]" +Set a breakpoint before the first line of the named subroutine. \fIsubname\fR may +be a variable containing a code reference (in this case \fIcondition\fR +is not supported). +.IP "b postpone subname [condition]" 12 +.IX Xref "breakpoint debugger command, b" +.IX Item "b postpone subname [condition]" +Set a breakpoint at first line of subroutine after it is compiled. +.IP "b load filename" 12 +.IX Xref "breakpoint debugger command, b" +.IX Item "b load filename" +Set a breakpoint before the first executed line of the \fIfilename\fR, +which should be a full pathname found amongst the \f(CW%INC\fR values. +.IP "b compile subname" 12 +.IX Xref "breakpoint debugger command, b" +.IX Item "b compile subname" +Sets a breakpoint before the first statement executed after the specified +subroutine is compiled. +.IP "B line" 12 +.IX Xref "breakpoint debugger command, B" +.IX Item "B line" +Delete a breakpoint from the specified \fIline\fR. +.IP "B *" 12 +.IX Xref "breakpoint debugger command, B" +.IX Item "B *" +Delete all installed breakpoints. +.IP "disable [file]:[line]" 12 +.IX Xref "breakpoint debugger command, disable disable" +.IX Item "disable [file]:[line]" +Disable the breakpoint so it won't stop the execution of the program. +Breakpoints are enabled by default and can be re-enabled using the \f(CW\*(C`enable\*(C'\fR +command. +.IP "disable [line]" 12 +.IX Xref "breakpoint debugger command, disable disable" +.IX Item "disable [line]" +Disable the breakpoint so it won't stop the execution of the program. +Breakpoints are enabled by default and can be re-enabled using the \f(CW\*(C`enable\*(C'\fR +command. +.Sp +This is done for a breakpoint in the current file. +.IP "enable [file]:[line]" 12 +.IX Xref "breakpoint debugger command, disable disable" +.IX Item "enable [file]:[line]" +Enable the breakpoint so it will stop the execution of the program. +.IP "enable [line]" 12 +.IX Xref "breakpoint debugger command, disable disable" +.IX Item "enable [line]" +Enable the breakpoint so it will stop the execution of the program. +.Sp +This is done for a breakpoint in the current file. +.IP "a [line] command" 12 +.IX Xref "debugger command, a" +.IX Item "a [line] command" +Set an action to be done before the line is executed. If \fIline\fR is +omitted, set an action on the line about to be executed. +The sequence of steps taken by the debugger is +.Sp +.Vb 5 +\& 1. check for a breakpoint at this line +\& 2. print the line if necessary (tracing) +\& 3. do any actions associated with that line +\& 4. prompt user if at a breakpoint or in single\-step +\& 5. evaluate line +.Ve +.Sp +For example, this will print out \f(CW$foo\fR every time line +53 is passed: +.Sp +.Vb 1 +\& a 53 print "DB FOUND $foo\en" +.Ve +.IP "A line" 12 +.IX Xref "debugger command, A" +.IX Item "A line" +Delete an action from the specified line. +.IP "A *" 12 +.IX Xref "debugger command, A" +.IX Item "A *" +Delete all installed actions. +.IP "w expr" 12 +.IX Xref "debugger command, w" +.IX Item "w expr" +Add a global watch-expression. Whenever a watched global changes the +debugger will stop and display the old and new values. +.IP "W expr" 12 +.IX Xref "debugger command, W" +.IX Item "W expr" +Delete watch-expression +.IP "W *" 12 +.IX Xref "debugger command, W" +.IX Item "W *" +Delete all watch-expressions. +.IP o 12 +.IX Xref "debugger command, o" +.IX Item "o" +Display all options. +.IP "o booloption ..." 12 +.IX Xref "debugger command, o" +.IX Item "o booloption ..." +Set each listed Boolean option to the value \f(CW1\fR. +.IP "o anyoption? ..." 12 +.IX Xref "debugger command, o" +.IX Item "o anyoption? ..." +Print out the value of one or more options. +.IP "o option=value ..." 12 +.IX Xref "debugger command, o" +.IX Item "o option=value ..." +Set the value of one or more options. If the value has internal +whitespace, it should be quoted. For example, you could set \f(CW\*(C`o +pager="less \-MQeicsNfr"\*(C'\fR to call \fBless\fR with those specific options. +You may use either single or double quotes, but if you do, you must +escape any embedded instances of same sort of quote you began with, +as well as any escaping any escapes that immediately precede that +quote but which are not meant to escape the quote itself. In other +words, you follow single-quoting rules irrespective of the quote; +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 +it?\e""\*(C'\fR. +.Sp +For historical reasons, the \f(CW\*(C`=value\*(C'\fR is optional, but defaults to +1 only where it is safe to do so\-\-that is, mostly for Boolean +options. It is always better to assign a specific value using \f(CW\*(C`=\*(C'\fR. +The \f(CW\*(C`option\*(C'\fR can be abbreviated, but for clarity probably should +not be. Several options can be set together. See "Configurable Options" +for a list of these. +.IP "< ?" 12 +.IX Xref "debugger command, <" +List out all pre-prompt Perl command actions. +.IP "< [ command ]" 12 +.IX Xref "debugger command, <" +.IX Item "< [ command ]" +Set an action (Perl command) to happen before every debugger prompt. +A multi-line command may be entered by backslashing the newlines. +.IP "< *" 12 +.IX Xref "debugger command, <" +Delete all pre-prompt Perl command actions. +.IP "<< command" 12 +.IX Xref "debugger command, <<" +.IX Item "<< command" +Add an action (Perl command) to happen before every debugger prompt. +A multi-line command may be entered by backwhacking the newlines. +.IP "> ?" 12 +.IX Xref "debugger command, >" +List out post-prompt Perl command actions. +.IP "> command" 12 +.IX Xref "debugger command, >" +.IX Item "> command" +Set an action (Perl command) to happen after the prompt when you've +just given a command to return to executing the script. A multi-line +command may be entered by backslashing the newlines (we bet you +couldn't have guessed this by now). +.IP "> *" 12 +.IX Xref "debugger command, >" +Delete all post-prompt Perl command actions. +.IP ">> command" 12 +.IX Xref "debugger command, >>" +.IX Item ">> command" +Adds an action (Perl command) to happen after the prompt when you've +just given a command to return to executing the script. A multi-line +command may be entered by backslashing the newlines. +.IP "{ ?" 12 +.IX Xref "debugger command, {" +List out pre-prompt debugger commands. +.IP "{ [ command ]" 12 +.IX Item "{ [ command ]" +Set an action (debugger command) to happen before every debugger prompt. +A multi-line command may be entered in the customary fashion. +.Sp +Because this command is in some senses new, a warning is issued if +you appear to have accidentally entered a block instead. If that's +what you mean to do, write it as with \f(CW\*(C`;{ ... }\*(C'\fR or even +\&\f(CW\*(C`do { ... }\*(C'\fR. +.IP "{ *" 12 +.IX Xref "debugger command, {" +Delete all pre-prompt debugger commands. +.IP "{{ command" 12 +.IX Xref "debugger command, {{" +.IX Item "{{ command" +Add an action (debugger command) to happen before every debugger prompt. +A multi-line command may be entered, if you can guess how: see above. +.IP "! number" 12 +.IX Xref "debugger command, !" +.IX Item "! number" +Redo a previous command (defaults to the previous command). +.IP "! \-number" 12 +.IX Xref "debugger command, !" +.IX Item "! -number" +Redo number'th previous command. +.IP "! pattern" 12 +.IX Xref "debugger command, !" +.IX Item "! pattern" +Redo last command that started with pattern. +See \f(CW\*(C`o\ recallCommand\*(C'\fR, too. +.IP "!! cmd" 12 +.IX Xref "debugger command, !!" +.IX Item "!! cmd" +Run cmd in a subprocess (reads from DB::IN, writes to DB::OUT) See +\&\f(CW\*(C`o\ shellBang\*(C'\fR, also. Note that the user's current shell (well, +their \f(CW$ENV{SHELL}\fR variable) will be used, which can interfere +with proper interpretation of exit status or signal and coredump +information. +.IP "source file" 12 +.IX Xref "debugger command, source" +.IX Item "source file" +Read and execute debugger commands from \fIfile\fR. +\&\fIfile\fR may itself contain \f(CW\*(C`source\*(C'\fR commands. +.IP "H \-number" 12 +.IX Xref "debugger command, H" +.IX Item "H -number" +Display last n commands. Only commands longer than one character are +listed. If \fInumber\fR is omitted, list them all. +.IP "q or ^D" 12 +.IX Xref "debugger command, q debugger command, ^D" +.IX Item "q or ^D" +Quit. ("quit" doesn't work for this, unless you've made an alias) +This is the only supported way to exit the debugger, though typing +\&\f(CW\*(C`exit\*(C'\fR twice might work. +.Sp +Set the \f(CW\*(C`inhibit_exit\*(C'\fR option to 0 if you want to be able to step +off the end the script. You may also need to set \f(CW$finished\fR to 0 +if you want to step through global destruction. +.IP R 12 +.IX Xref "debugger command, R" +.IX Item "R" +Restart the debugger by \f(CWexec()\fRing a new session. We try to maintain +your history across this, but internal settings and command-line options +may be lost. +.Sp +The following setting are currently preserved: history, breakpoints, +actions, debugger options, and the Perl command-line +options \fB\-w\fR, \fB\-I\fR, and \fB\-e\fR. +.IP |dbcmd 12 +.IX Xref "debugger command, |" +.IX Item "|dbcmd" +Run the debugger command, piping DB::OUT into your current pager. +.IP ||dbcmd 12 +.IX Xref "debugger command, ||" +.IX Item "||dbcmd" +Same as \f(CW\*(C`|dbcmd\*(C'\fR but DB::OUT is temporarily \f(CW\*(C`select\*(C'\fRed as well. +.IP "= [alias value]" 12 +.IX Xref "debugger command, =" +.IX Item "= [alias value]" +Define a command alias, like +.Sp +.Vb 1 +\& = quit q +.Ve +.Sp +or list current aliases. +.IP command 12 +.IX Item "command" +Execute command as a Perl statement. A trailing semicolon will be +supplied. If the Perl statement would otherwise be confused for a +Perl debugger, use a leading semicolon, too. +.IP "m expr" 12 +.IX Xref "debugger command, m" +.IX Item "m expr" +List which methods may be called on the result of the evaluated +expression. The expression may evaluated to a reference to a +blessed object, or to a package name. +.IP M 12 +.IX Xref "debugger command, M" +.IX Item "M" +Display all loaded modules and their versions. +.IP "man [manpage]" 12 +.IX Xref "debugger command, man" +.IX Item "man [manpage]" +Despite its name, this calls your system's default documentation +viewer on the given page, or on the viewer itself if \fImanpage\fR is +omitted. If that viewer is \fBman\fR, the current \f(CW\*(C`Config\*(C'\fR information +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 +known manpages of the form \fIperlXXX\fR will be retried. This lets +you type \f(CW\*(C`man debug\*(C'\fR or \f(CW\*(C`man op\*(C'\fR from the debugger. +.Sp +On systems traditionally bereft of a usable \fBman\fR command, the +debugger invokes \fBperldoc\fR. Occasionally this determination is +incorrect due to recalcitrant vendors or rather more felicitously, +to enterprising users. If you fall into either category, just +manually set the \f(CW$DB::doccmd\fR variable to whatever viewer to view +the Perl documentation on your system. This may be set in an rc +file, or through direct assignment. We're still waiting for a +working example of something along the lines of: +.Sp +.Vb 1 +\& $DB::doccmd = \*(Aqnetscape \-remote http://something.here/\*(Aq; +.Ve +.SS "Configurable Options" +.IX Subsection "Configurable Options" +The debugger has numerous options settable using the \f(CW\*(C`o\*(C'\fR command, +either interactively or from the environment or an rc file. The file +is named \fI./.perldb\fR or \fI~/.perldb\fR under Unix with \fI/dev/tty\fR, +\&\fIperldb.ini\fR otherwise. +.ie n .IP """recallCommand"", ""ShellBang""" 12 +.el .IP "\f(CWrecallCommand\fR, \f(CWShellBang\fR" 12 +.IX Xref "debugger option, recallCommand debugger option, ShellBang" +.IX Item "recallCommand, ShellBang" +The characters used to recall a command or spawn a shell. By +default, both are set to \f(CW\*(C`!\*(C'\fR, which is unfortunate. +.ie n .IP """pager""" 12 +.el .IP \f(CWpager\fR 12 +.IX Xref "debugger option, pager" +.IX Item "pager" +Program to use for output of pager-piped commands (those beginning +with a \f(CW\*(C`|\*(C'\fR character.) By default, \f(CW$ENV{PAGER}\fR will be used. +Because the debugger uses your current terminal characteristics +for bold and underlining, if the chosen pager does not pass escape +sequences through unchanged, the output of some debugger commands +will not be readable when sent through the pager. +.ie n .IP """tkRunning""" 12 +.el .IP \f(CWtkRunning\fR 12 +.IX Xref "debugger option, tkRunning" +.IX Item "tkRunning" +Run Tk while prompting (with ReadLine). +.ie n .IP """signalLevel"", ""warnLevel"", ""dieLevel""" 12 +.el .IP "\f(CWsignalLevel\fR, \f(CWwarnLevel\fR, \f(CWdieLevel\fR" 12 +.IX Xref "debugger option, signalLevel debugger option, warnLevel debugger option, dieLevel" +.IX Item "signalLevel, warnLevel, dieLevel" +Level of verbosity. By default, the debugger leaves your exceptions +and warnings alone, because altering them can break correctly running +programs. It will attempt to print a message when uncaught INT, BUS, or +SEGV signals arrive. (But see the mention of signals in "BUGS" below.) +.Sp +To disable this default safe mode, set these values to something higher +than 0. At a level of 1, you get backtraces upon receiving any kind +of warning (this is often annoying) or exception (this is +often valuable). Unfortunately, the debugger cannot discern fatal +exceptions from non-fatal ones. If \f(CW\*(C`dieLevel\*(C'\fR is even 1, then your +non-fatal exceptions are also traced and unceremoniously altered if they +came from \f(CW\*(C`eval\*(Aqed\*(C'\fR strings or from any kind of \f(CW\*(C`eval\*(C'\fR within modules +you're attempting to load. If \f(CW\*(C`dieLevel\*(C'\fR is 2, the debugger doesn't +care where they came from: It usurps your exception handler and prints +out a trace, then modifies all exceptions with its own embellishments. +This may perhaps be useful for some tracing purposes, but tends to hopelessly +destroy any program that takes its exception handling seriously. +.ie n .IP """AutoTrace""" 12 +.el .IP \f(CWAutoTrace\fR 12 +.IX Xref "debugger option, AutoTrace" +.IX Item "AutoTrace" +Trace mode (similar to \f(CW\*(C`t\*(C'\fR command, but can be put into +\&\f(CW\*(C`PERLDB_OPTS\*(C'\fR). +.ie n .IP """LineInfo""" 12 +.el .IP \f(CWLineInfo\fR 12 +.IX Xref "debugger option, LineInfo" +.IX Item "LineInfo" +File or pipe to print line number info to. If it is a pipe (say, +\&\f(CW\*(C`|visual_perl_db\*(C'\fR), then a short message is used. This is the +mechanism used to interact with a client editor or visual debugger, +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 +debugger. +.ie n .IP """inhibit_exit""" 12 +.el .IP \f(CWinhibit_exit\fR 12 +.IX Xref "debugger option, inhibit_exit" +.IX Item "inhibit_exit" +If 0, allows \fIstepping off\fR the end of the script. +.ie n .IP """PrintRet""" 12 +.el .IP \f(CWPrintRet\fR 12 +.IX Xref "debugger option, PrintRet" +.IX Item "PrintRet" +Print return value after \f(CW\*(C`r\*(C'\fR command if set (default). +.ie n .IP """ornaments""" 12 +.el .IP \f(CWornaments\fR 12 +.IX Xref "debugger option, ornaments" +.IX Item "ornaments" +Affects screen appearance of the command line (see Term::ReadLine). +There is currently no way to disable these, which can render +some output illegible on some displays, or with some pagers. +This is considered a bug. +.ie n .IP """frame""" 12 +.el .IP \f(CWframe\fR 12 +.IX Xref "debugger option, frame" +.IX Item "frame" +Affects the printing of messages upon entry and exit from subroutines. If +\&\f(CW\*(C`frame & 2\*(C'\fR is false, messages are printed on entry only. (Printing +on exit might be useful if interspersed with other messages.) +.Sp +If \f(CW\*(C`frame & 4\*(C'\fR, arguments to functions are printed, plus context +and caller info. If \f(CW\*(C`frame & 8\*(C'\fR, overloaded \f(CW\*(C`stringify\*(C'\fR and +\&\f(CW\*(C`tie\*(C'\fRd \f(CW\*(C`FETCH\*(C'\fR is enabled on the printed arguments. If \f(CW\*(C`frame +& 16\*(C'\fR, the return value from the subroutine is printed. +.Sp +The length at which the argument list is truncated is governed by the +next option: +.ie n .IP """maxTraceLen""" 12 +.el .IP \f(CWmaxTraceLen\fR 12 +.IX Xref "debugger option, maxTraceLen" +.IX Item "maxTraceLen" +Length to truncate the argument list when the \f(CW\*(C`frame\*(C'\fR option's +bit 4 is set. +.ie n .IP """windowSize""" 12 +.el .IP \f(CWwindowSize\fR 12 +.IX Xref "debugger option, windowSize" +.IX Item "windowSize" +Change the size of code list window (default is 10 lines). +.PP +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 +commands: +.ie n .IP """arrayDepth"", ""hashDepth""" 12 +.el .IP "\f(CWarrayDepth\fR, \f(CWhashDepth\fR" 12 +.IX Xref "debugger option, arrayDepth debugger option, hashDepth" +.IX Item "arrayDepth, hashDepth" +Print only first N elements ('' for all). +.ie n .IP """dumpDepth""" 12 +.el .IP \f(CWdumpDepth\fR 12 +.IX Xref "debugger option, dumpDepth" +.IX Item "dumpDepth" +Limit recursion depth to N levels when dumping structures. +Negative values are interpreted as infinity. Default: infinity. +.ie n .IP """compactDump"", ""veryCompact""" 12 +.el .IP "\f(CWcompactDump\fR, \f(CWveryCompact\fR" 12 +.IX Xref "debugger option, compactDump debugger option, veryCompact" +.IX Item "compactDump, veryCompact" +Change the style of array and hash output. If \f(CW\*(C`compactDump\*(C'\fR, short array +may be printed on one line. +.ie n .IP """globPrint""" 12 +.el .IP \f(CWglobPrint\fR 12 +.IX Xref "debugger option, globPrint" +.IX Item "globPrint" +Whether to print contents of globs. +.ie n .IP """DumpDBFiles""" 12 +.el .IP \f(CWDumpDBFiles\fR 12 +.IX Xref "debugger option, DumpDBFiles" +.IX Item "DumpDBFiles" +Dump arrays holding debugged files. +.ie n .IP """DumpPackages""" 12 +.el .IP \f(CWDumpPackages\fR 12 +.IX Xref "debugger option, DumpPackages" +.IX Item "DumpPackages" +Dump symbol tables of packages. +.ie n .IP """DumpReused""" 12 +.el .IP \f(CWDumpReused\fR 12 +.IX Xref "debugger option, DumpReused" +.IX Item "DumpReused" +Dump contents of "reused" addresses. +.ie n .IP """quote"", ""HighBit"", ""undefPrint""" 12 +.el .IP "\f(CWquote\fR, \f(CWHighBit\fR, \f(CWundefPrint\fR" 12 +.IX Xref "debugger option, quote debugger option, HighBit debugger option, undefPrint" +.IX Item "quote, HighBit, undefPrint" +Change the style of string dump. The default value for \f(CW\*(C`quote\*(C'\fR +is \f(CW\*(C`auto\*(C'\fR; one can enable double-quotish or single-quotish format +by setting it to \f(CW\*(C`"\*(C'\fR or \f(CW\*(C`\*(Aq\*(C'\fR, respectively. By default, characters +with their high bit set are printed verbatim. +.ie n .IP """UsageOnly""" 12 +.el .IP \f(CWUsageOnly\fR 12 +.IX Xref "debugger option, UsageOnly" +.IX Item "UsageOnly" +Rudimentary per-package memory usage dump. Calculates total +size of strings found in variables in the package. This does not +include lexicals in a module's file scope, or lost in closures. +.ie n .IP """HistFile""" 12 +.el .IP \f(CWHistFile\fR 12 +.IX Xref "debugger option, history, HistFile" +.IX Item "HistFile" +The path of the file from which the history (assuming a usable +Term::ReadLine backend) will be read on the debugger's startup, and to which +it will be saved on shutdown (for persistence across sessions). Similar in +concept to Bash's \f(CW\*(C`.bash_history\*(C'\fR file. +.ie n .IP """HistSize""" 12 +.el .IP \f(CWHistSize\fR 12 +.IX Xref "debugger option, history, HistSize" +.IX Item "HistSize" +The count of the saved lines in the history (assuming \f(CW\*(C`HistFile\*(C'\fR above). +.PP +After the rc file is read, the debugger reads the \f(CW$ENV{PERLDB_OPTS}\fR +environment variable and parses this as the remainder of a "O ..." +line as one might enter at the debugger prompt. You may place the +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 +there. +.PP +If your rc file contains: +.PP +.Vb 1 +\& parse_options("NonStop=1 LineInfo=db.out AutoTrace"); +.Ve +.PP +then your script will run without human intervention, putting trace +information into the file \fIdb.out\fR. (If you interrupt it, you'd +better reset \f(CW\*(C`LineInfo\*(C'\fR to \fI/dev/tty\fR if you expect to see anything.) +.ie n .IP """TTY""" 12 +.el .IP \f(CWTTY\fR 12 +.IX Xref "debugger option, TTY" +.IX Item "TTY" +The TTY to use for debugging I/O. +.ie n .IP """noTTY""" 12 +.el .IP \f(CWnoTTY\fR 12 +.IX Xref "debugger option, noTTY" +.IX Item "noTTY" +If set, the debugger goes into \f(CW\*(C`NonStop\*(C'\fR mode and will not connect to a TTY. If +interrupted (or if control goes to the debugger via explicit setting of +\&\f(CW$DB::signal\fR or \f(CW$DB::single\fR from the Perl script), it connects to a TTY +specified in the \f(CW\*(C`TTY\*(C'\fR option at startup, or to a tty found at +runtime using the \f(CW\*(C`Term::Rendezvous\*(C'\fR module of your choice. +.Sp +This module should implement a method named \f(CW\*(C`new\*(C'\fR that returns an object +with two methods: \f(CW\*(C`IN\*(C'\fR and \f(CW\*(C`OUT\*(C'\fR. These should return filehandles to use +for debugging input and output correspondingly. The \f(CW\*(C`new\*(C'\fR method should +inspect an argument containing the value of \f(CW$ENV{PERLDB_NOTTY}\fR at +startup, or \f(CW"$ENV{HOME}/.perldbtty$$"\fR otherwise. This file is not +inspected for proper ownership, so security hazards are theoretically +possible. +.ie n .IP """ReadLine""" 12 +.el .IP \f(CWReadLine\fR 12 +.IX Xref "debugger option, ReadLine" +.IX Item "ReadLine" +If false, readline support in the debugger is disabled in order +to debug applications that themselves use ReadLine. +.ie n .IP """NonStop""" 12 +.el .IP \f(CWNonStop\fR 12 +.IX Xref "debugger option, NonStop" +.IX Item "NonStop" +If set, the debugger goes into non-interactive mode until interrupted, or +programmatically by setting \f(CW$DB::signal\fR or \f(CW$DB::single\fR. +.PP +Here's an example of using the \f(CW$ENV{PERLDB_OPTS}\fR variable: +.PP +.Vb 1 +\& $ PERLDB_OPTS="NonStop frame=2" perl \-d myprogram +.Ve +.PP +That will run the script \fBmyprogram\fR without human intervention, +printing out the call tree with entry and exit points. Note that +\&\f(CW\*(C`NonStop=1 frame=2\*(C'\fR is equivalent to \f(CW\*(C`N f=2\*(C'\fR, and that originally, +options could be uniquely abbreviated by the first letter (modulo +the \f(CW\*(C`Dump*\*(C'\fR options). It is nevertheless recommended that you +always spell them out in full for legibility and future compatibility. +.PP +Other examples include +.PP +.Vb 1 +\& $ PERLDB_OPTS="NonStop LineInfo=listing frame=2" perl \-d myprogram +.Ve +.PP +which runs script non-interactively, printing info on each entry +into a subroutine and each executed line into the file named \fIlisting\fR. +(If you interrupt it, you would better reset \f(CW\*(C`LineInfo\*(C'\fR to something +"interactive"!) +.PP +Other examples include (using standard shell syntax to show environment +variable settings): +.PP +.Vb 2 +\& $ ( PERLDB_OPTS="NonStop frame=1 AutoTrace LineInfo=tperl.out" +\& perl \-d myprogram ) +.Ve +.PP +which may be useful for debugging a program that uses Term::ReadLine +itself. Do not forget to detach your shell from the TTY in the window that +corresponds to \fI/dev/ttyXX\fR, say, by issuing a command like +.PP +.Vb 1 +\& $ sleep 1000000 +.Ve +.PP +See "Debugger Internals" in perldebguts for details. +.SS "Debugger Input/Output" +.IX Subsection "Debugger Input/Output" +.IP Prompt 8 +.IX Item "Prompt" +The debugger prompt is something like +.Sp +.Vb 1 +\& DB<8> +.Ve +.Sp +or even +.Sp +.Vb 1 +\& DB<<17>> +.Ve +.Sp +where that number is the command number, and which you'd use to +access with the built-in \fBcsh\fR\-like history mechanism. For example, +\&\f(CW\*(C`!17\*(C'\fR would repeat command number 17. The depth of the angle +brackets indicates the nesting depth of the debugger. You could +get more than one set of brackets, for example, if you'd already +at a breakpoint and then printed the result of a function call that +itself has a breakpoint, or you step into an expression via \f(CW\*(C`s/n/t +expression\*(C'\fR command. +.IP "Multiline commands" 8 +.IX Item "Multiline commands" +If you want to enter a multi-line command, such as a subroutine +definition with several statements or a format, escape the newline +that would normally end the debugger command with a backslash. +Here's an example: +.Sp +.Vb 7 +\& DB<1> for (1..4) { \e +\& cont: print "ok\en"; \e +\& cont: } +\& ok +\& ok +\& ok +\& ok +.Ve +.Sp +Note that this business of escaping a newline is specific to interactive +commands typed into the debugger. +.IP "Stack backtrace" 8 +.IX Xref "backtrace stack, backtrace" +.IX Item "Stack backtrace" +Here's an example of what a stack backtrace via \f(CW\*(C`T\*(C'\fR command might +look like: +.Sp +.Vb 5 +\& $ = main::infested called from file \*(AqAmbulation.pm\*(Aq line 10 +\& @ = Ambulation::legs(1, 2, 3, 4) called from file \*(Aqcamel_flea\*(Aq +\& line 7 +\& $ = main::pests(\*(Aqbactrian\*(Aq, 4) called from file \*(Aqcamel_flea\*(Aq +\& line 4 +.Ve +.Sp +The left-hand character up there indicates the context in which the +function was called, with \f(CW\*(C`$\*(C'\fR and \f(CW\*(C`@\*(C'\fR meaning scalar or list +contexts respectively, and \f(CW\*(C`.\*(C'\fR meaning void context (which is +actually a sort of scalar context). The display above says +that you were in the function \f(CW\*(C`main::infested\*(C'\fR when you ran the +stack dump, and that it was called in scalar context from line +10 of the file \fIAmbulation.pm\fR, but without any arguments at all, +meaning it was called as \f(CW&infested\fR. The next stack frame shows +that the function \f(CW\*(C`Ambulation::legs\*(C'\fR was called in list context +from the \fIcamel_flea\fR file with four arguments. The last stack +frame shows that \f(CW\*(C`main::pests\*(C'\fR was called in scalar context, +also from \fIcamel_flea\fR, but from line 4. +.Sp +If you execute the \f(CW\*(C`T\*(C'\fR command from inside an active \f(CW\*(C`use\*(C'\fR +statement, the backtrace will contain both a \f(CW\*(C`require\*(C'\fR frame and +an \f(CW\*(C`eval\*(C'\fR frame. +.IP "Line Listing Format" 8 +.IX Item "Line Listing Format" +This shows the sorts of output the \f(CW\*(C`l\*(C'\fR command can produce: +.Sp +.Vb 11 +\& DB<<13>> l +\& 101: @i{@i} = (); +\& 102:b @isa{@i,$pack} = () +\& 103 if(exists $i{$prevpack} || exists $isa{$pack}); +\& 104 } +\& 105 +\& 106 next +\& 107==> if(exists $isa{$pack}); +\& 108 +\& 109:a if ($extra\-\- > 0) { +\& 110: %isa = ($pack,1); +.Ve +.Sp +Breakable lines are marked with \f(CW\*(C`:\*(C'\fR. Lines with breakpoints are +marked by \f(CW\*(C`b\*(C'\fR and those with actions by \f(CW\*(C`a\*(C'\fR. The line that's +about to be executed is marked by \f(CW\*(C`==>\*(C'\fR. +.Sp +Please be aware that code in debugger listings may not look the same +as your original source code. Line directives and external source +filters can alter the code before Perl sees it, causing code to move +from its original positions or take on entirely different forms. +.IP "Frame listing" 8 +.IX Item "Frame listing" +When the \f(CW\*(C`frame\*(C'\fR option is set, the debugger would print entered (and +optionally exited) subroutines in different styles. See perldebguts +for incredibly long examples of these. +.SS "Debugging Compile-Time Statements" +.IX Subsection "Debugging Compile-Time Statements" +If you have compile-time executable statements (such as code within +BEGIN, UNITCHECK and CHECK blocks or \f(CW\*(C`use\*(C'\fR statements), these will +\&\fInot\fR be stopped by debugger, although \f(CW\*(C`require\*(C'\fRs and INIT blocks +will, and compile-time statements can be traced with the \f(CW\*(C`AutoTrace\*(C'\fR +option set in \f(CW\*(C`PERLDB_OPTS\*(C'\fR). From your own Perl code, however, you +can transfer control back to the debugger using the following +statement, which is harmless if the debugger is not running: +.PP +.Vb 1 +\& $DB::single = 1; +.Ve +.PP +If you set \f(CW$DB::single\fR to 2, it's equivalent to having +just typed the \f(CW\*(C`n\*(C'\fR command, whereas a value of 1 means the \f(CW\*(C`s\*(C'\fR +command. The \f(CW$DB::trace\fR variable should be set to 1 to simulate +having typed the \f(CW\*(C`t\*(C'\fR command. +.PP +Another way to debug compile-time code is to start the debugger, set a +breakpoint on the \fIload\fR of some module: +.PP +.Vb 2 +\& DB<7> b load f:/perllib/lib/Carp.pm +\& Will stop on load of \*(Aqf:/perllib/lib/Carp.pm\*(Aq. +.Ve +.PP +and then restart the debugger using the \f(CW\*(C`R\*(C'\fR command (if possible). One can use \f(CW\*(C`b +compile subname\*(C'\fR for the same purpose. +.SS "Debugger Customization" +.IX Subsection "Debugger Customization" +The debugger probably contains enough configuration hooks that you +won't ever have to modify it yourself. You may change the behaviour +of the debugger from within the debugger using its \f(CW\*(C`o\*(C'\fR command, from +the command line via the \f(CW\*(C`PERLDB_OPTS\*(C'\fR environment variable, and +from customization files. +.PP +You can do some customization by setting up a \fI.perldb\fR file, which +contains initialization code. For instance, you could make aliases +like these (the last one is one people expect to be there): +.PP +.Vb 4 +\& $DB::alias{\*(Aqlen\*(Aq} = \*(Aqs/^len(.*)/p length($1)/\*(Aq; +\& $DB::alias{\*(Aqstop\*(Aq} = \*(Aqs/^stop (at|in)/b/\*(Aq; +\& $DB::alias{\*(Aqps\*(Aq} = \*(Aqs/^ps\eb/p scalar /\*(Aq; +\& $DB::alias{\*(Aqquit\*(Aq} = \*(Aqs/^quit(\es*)/exit/\*(Aq; +.Ve +.PP +You can change options from \fI.perldb\fR by using calls like this one; +.PP +.Vb 1 +\& parse_options("NonStop=1 LineInfo=db.out AutoTrace=1 frame=2"); +.Ve +.PP +The code is executed in the package \f(CW\*(C`DB\*(C'\fR. Note that \fI.perldb\fR is +processed before processing \f(CW\*(C`PERLDB_OPTS\*(C'\fR. If \fI.perldb\fR defines the +subroutine \f(CW\*(C`afterinit\*(C'\fR, that function is called after debugger +initialization ends. \fI.perldb\fR may be contained in the current +directory, or in the home directory. Because this file is sourced +in by Perl and may contain arbitrary commands, for security reasons, +it must be owned by the superuser or the current user, and writable +by no one but its owner. +.PP +You can mock TTY input to debugger by adding arbitrary commands to +\&\f(CW@DB::typeahead\fR. For example, your \fI.perldb\fR file might contain: +.PP +.Vb 1 +\& sub afterinit { push @DB::typeahead, "b 4", "b 6"; } +.Ve +.PP +Which would attempt to set breakpoints on lines 4 and 6 immediately +after debugger initialization. Note that \f(CW@DB::typeahead\fR is not a supported +interface and is subject to change in future releases. +.PP +If you want to modify the debugger, copy \fIperl5db.pl\fR from the +Perl library to another name and hack it to your heart's content. +You'll then want to set your \f(CW\*(C`PERL5DB\*(C'\fR environment variable to say +something like this: +.PP +.Vb 1 +\& BEGIN { require "myperl5db.pl" } +.Ve +.PP +As a last resort, you could also use \f(CW\*(C`PERL5DB\*(C'\fR to customize the debugger +by directly setting internal variables or calling debugger functions. +.PP +Note that any variables and functions that are not documented in +this document (or in perldebguts) are considered for internal +use only, and as such are subject to change without notice. +.SS "Readline Support / History in the Debugger" +.IX Subsection "Readline Support / History in the Debugger" +As shipped, the only command-line history supplied is a simplistic one +that checks for leading exclamation points. However, if you install +the Term::ReadKey and Term::ReadLine modules from CPAN (such as +Term::ReadLine::Gnu, Term::ReadLine::Perl, ...) you will +have full editing capabilities much like those GNU \fIreadline\fR(3) provides. +Look for these in the \fImodules/by\-module/Term\fR directory on CPAN. +These do not support normal \fBvi\fR command-line editing, however. +.PP +A rudimentary command-line completion is also available, including +lexical variables in the current scope if the PadWalker module +is installed. +.PP +Without Readline support you may see the symbols "^[[A", "^[[C", "^[[B", +"^[[D"", "^H", ... when using the arrow keys and/or the backspace key. +.SS "Editor Support for Debugging" +.IX Subsection "Editor Support for Debugging" +If you have the GNU's version of \fBemacs\fR installed on your system, +it can interact with the Perl debugger to provide an integrated +software development environment reminiscent of its interactions +with C debuggers. +.PP +Recent versions of Emacs come with a +start file for making \fBemacs\fR act like a +syntax-directed editor that understands (some of) Perl's syntax. +See perlfaq3. +.PP +Users of \fBvi\fR should also look into \fBvim\fR and \fBgvim\fR, the mousey +and windy version, for coloring of Perl keywords. +.PP +Note that only perl can truly parse Perl, so all such CASE tools +fall somewhat short of the mark, especially if you don't program +your Perl as a C programmer might. +.SS "The Perl Profiler" +.IX Xref "profile profiling profiler" +.IX Subsection "The Perl Profiler" +If you wish to supply an alternative debugger for Perl to run, +invoke your script with a colon and a package argument given to the +\&\fB\-d\fR flag. Perl's alternative debuggers include a Perl profiler, +Devel::NYTProf, which is available separately as a CPAN +distribution. To profile your Perl program in the file \fImycode.pl\fR, +just type: +.PP +.Vb 1 +\& $ perl \-d:NYTProf mycode.pl +.Ve +.PP +When the script terminates the profiler will create a database of the +profile information that you can turn into reports using the profiler's +tools. See <perlperf> for details. +.SH "Debugging Regular Expressions" +.IX Xref "regular expression, debugging regex, debugging regexp, debugging" +.IX Header "Debugging Regular Expressions" +\&\f(CW\*(C`use re \*(Aqdebug\*(Aq\*(C'\fR enables you to see the gory details of how the Perl +regular expression engine works. In order to understand this typically +voluminous output, one must not only have some idea about how regular +expression matching works in general, but also know how Perl's regular +expressions are internally compiled into an automaton. These matters +are explored in some detail in +"Debugging Regular Expressions" in perldebguts. +.SH "Debugging Memory Usage" +.IX Xref "memory usage" +.IX Header "Debugging Memory Usage" +Perl contains internal support for reporting its own memory usage, +but this is a fairly advanced concept that requires some understanding +of how memory allocation works. +See "Debugging Perl Memory Usage" in perldebguts for the details. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +You do have \f(CW\*(C`use strict\*(C'\fR and \f(CW\*(C`use warnings\*(C'\fR enabled, don't you? +.PP +perldebtut, +perldebguts, +perl5db.pl, +re, +DB, +Devel::NYTProf, +Dumpvalue, +and +perlrun. +.PP +When debugging a script that uses #! and is thus normally found in +\&\f(CW$PATH\fR, the \-S option causes perl to search \f(CW$PATH\fR for it, so you don't +have to type the path or \f(CW\*(C`which $scriptname\*(C'\fR. +.PP +.Vb 1 +\& $ perl \-Sd foo.pl +.Ve +.SH BUGS +.IX Header "BUGS" +You cannot get stack frame information or in any fashion debug functions +that were not compiled by Perl, such as those from C or C++ extensions. +.PP +If you alter your \f(CW@_\fR arguments in a subroutine (such as with \f(CW\*(C`shift\*(C'\fR +or \f(CW\*(C`pop\*(C'\fR), the stack backtrace will not show the original values. +.PP +The debugger does not currently work in conjunction with the \fB\-W\fR +command-line switch, because it itself is not free of warnings. +.PP +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 +from your keyboard or a socket) and haven't set up your own \f(CW$SIG{INT}\fR +handler, then you won't be able to CTRL-C your way back to the debugger, +because the debugger's own \f(CW$SIG{INT}\fR handler doesn't understand that +it needs to raise an exception to \fBlongjmp\fR\|(3) out of slow syscalls. |