.\" Automatically generated by Pod::Man 4.14 (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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    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 "perl5db 3pm"
.TH perl5db 3pm "2022-11-29" "perl v5.36.0" "User Contributed Perl Documentation"
.\" 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"
perl5db.pl \- the perl debugger
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    perl \-d  your_Perl_script
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`perl5db.pl\*(C'\fR is the perl debugger. It is loaded automatically by Perl when
you invoke a script with \f(CW\*(C`perl \-d\*(C'\fR. This documentation tries to outline the
structure and services provided by \f(CW\*(C`perl5db.pl\*(C'\fR, and to describe how you
can use them.
.PP
See perldebug for an overview of how to use the debugger.
.SH "GENERAL NOTES"
.IX Header "GENERAL NOTES"
The debugger can look pretty forbidding to many Perl programmers. There are
a number of reasons for this, many stemming out of the debugger's history.
.PP
When the debugger was first written, Perl didn't have a lot of its nicer
features \- no references, no lexical variables, no closures, no object-oriented
programming. So a lot of the things one would normally have done using such
features was done using global variables, globs and the \f(CW\*(C`local()\*(C'\fR operator
in creative ways.
.PP
Some of these have survived into the current debugger; a few of the more
interesting and still-useful idioms are noted in this section, along with notes
on the comments themselves.
.SS "Why not use more lexicals?"
.IX Subsection "Why not use more lexicals?"
Experienced Perl programmers will note that the debugger code tends to use
mostly package globals rather than lexically-scoped variables. This is done
to allow a significant amount of control of the debugger from outside the
debugger itself.
.PP
Unfortunately, though the variables are accessible, they're not well
documented, so it's generally been a decision that hasn't made a lot of
difference to most users. Where appropriate, comments have been added to
make variables more accessible and usable, with the understanding that these
\&\fIare\fR debugger internals, and are therefore subject to change. Future
development should probably attempt to replace the globals with a well-defined
\&\s-1API,\s0 but for now, the variables are what we've got.
.ie n .SS "Automated variable stacking via ""local()"""
.el .SS "Automated variable stacking via \f(CWlocal()\fP"
.IX Subsection "Automated variable stacking via local()"
As you may recall from reading \f(CW\*(C`perlfunc\*(C'\fR, the \f(CW\*(C`local()\*(C'\fR operator makes a
temporary copy of a variable in the current scope. When the scope ends, the
old copy is restored. This is often used in the debugger to handle the
automatic stacking of variables during recursive calls:
.PP
.Vb 2
\&     sub foo {
\&        local $some_global++;
\&
\&        # Do some stuff, then ...
\&        return;
\&     }
.Ve
.PP
What happens is that on entry to the subroutine, \f(CW$some_global\fR is localized,
then altered. When the subroutine returns, Perl automatically undoes the
localization, restoring the previous value. Voila, automatic stack management.
.PP
The debugger uses this trick a \fIlot\fR. Of particular note is \f(CW\*(C`DB::eval\*(C'\fR,
which lets the debugger get control inside of \f(CW\*(C`eval\*(C'\fR'ed code. The debugger
localizes a saved copy of \f(CW$@\fR inside the subroutine, which allows it to
keep \f(CW$@\fR safe until it \f(CW\*(C`DB::eval\*(C'\fR returns, at which point the previous
value of \f(CW$@\fR is restored. This makes it simple (well, \fIsimpler\fR) to keep
track of \f(CW$@\fR inside \f(CW\*(C`eval\*(C'\fRs which \f(CW\*(C`eval\*(C'\fR other \f(CW\*(C`eval\*(Aqs\*(C'\fR.
.PP
In any case, watch for this pattern. It occurs fairly often.
.ie n .SS "The ""^"" trick"
.el .SS "The \f(CW^\fP trick"
.IX Subsection "The ^ trick"
This is used to cleverly reverse the sense of a logical test depending on
the value of an auxiliary variable. For instance, the debugger's \f(CW\*(C`S\*(C'\fR
(search for subroutines by pattern) allows you to negate the pattern
like this:
.PP
.Vb 2
\&   # Find all non\-\*(Aqfoo\*(Aq subs:
\&   S !/foo/
.Ve
.PP
Boolean algebra states that the truth table for \s-1XOR\s0 looks like this:
.IP "\(bu" 4
0 ^ 0 = 0
.Sp
(! not present and no match) \-\-> false, don't print
.IP "\(bu" 4
0 ^ 1 = 1
.Sp
(! not present and matches) \-\-> true, print
.IP "\(bu" 4
1 ^ 0 = 1
.Sp
(! present and no match) \-\-> true, print
.IP "\(bu" 4
1 ^ 1 = 0
.Sp
(! present and matches) \-\-> false, don't print
.PP
As you can see, the first pair applies when \f(CW\*(C`!\*(C'\fR isn't supplied, and
the second pair applies when it is. The \s-1XOR\s0 simply allows us to
compact a more complicated if-then-elseif-else into a more elegant
(but perhaps overly clever) single test. After all, it needed this
explanation...
.SS "\s-1FLAGS, FLAGS, FLAGS\s0"
.IX Subsection "FLAGS, FLAGS, FLAGS"
There is a certain C programming legacy in the debugger. Some variables,
such as \f(CW$single\fR, \f(CW$trace\fR, and \f(CW$frame\fR, have \fImagical\fR values composed
of 1, 2, 4, etc. (powers of 2) \s-1OR\s0'ed together. This allows several pieces
of state to be stored independently in a single scalar.
.PP
A test like
.PP
.Vb 1
\&    if ($scalar & 4) ...
.Ve
.PP
is checking to see if the appropriate bit is on. Since each bit can be
\&\*(L"addressed\*(R" independently in this way, \f(CW$scalar\fR is acting sort of like
an array of bits. Obviously, since the contents of \f(CW$scalar\fR are just a
bit-pattern, we can save and restore it easily (it will just look like
a number).
.PP
The problem, is of course, that this tends to leave magic numbers scattered
all over your program whenever a bit is set, cleared, or checked. So why do
it?
.IP "\(bu" 4
First, doing an arithmetical or bitwise operation on a scalar is
just about the fastest thing you can do in Perl: \f(CW\*(C`use constant\*(C'\fR actually
creates a subroutine call, and array and hash lookups are much slower. Is
this over-optimization at the expense of readability? Possibly, but the
debugger accesses these  variables a \fIlot\fR. Any rewrite of the code will
probably have to benchmark alternate implementations and see which is the
best balance of readability and speed, and then document how it actually
works.
.IP "\(bu" 4
Second, it's very easy to serialize a scalar number. This is done in
the restart code; the debugger state variables are saved in \f(CW%ENV\fR and then
restored when the debugger is restarted. Having them be just numbers makes
this trivial.
.IP "\(bu" 4
Third, some of these variables are being shared with the Perl core
smack in the middle of the interpreter's execution loop. It's much faster for
a C program (like the interpreter) to check a bit in a scalar than to access
several different variables (or a Perl array).
.ie n .SS "What are those ""XXX"" comments for?"
.el .SS "What are those \f(CWXXX\fP comments for?"
.IX Subsection "What are those XXX comments for?"
Any comment containing \f(CW\*(C`XXX\*(C'\fR means that the comment is either somewhat
speculative \- it's not exactly clear what a given variable or chunk of
code is doing, or that it is incomplete \- the basics may be clear, but the
subtleties are not completely documented.
.PP
Send in a patch if you can clear up, fill out, or clarify an \f(CW\*(C`XXX\*(C'\fR.
.SH "DATA STRUCTURES MAINTAINED BY CORE"
.IX Header "DATA STRUCTURES MAINTAINED BY CORE"
There are a number of special data structures provided to the debugger by
the Perl interpreter.
.PP
The array \f(CW\*(C`@{$main::{\*(Aq_<\*(Aq.$filename}}\*(C'\fR (aliased locally to \f(CW@dbline\fR
via glob assignment) contains the text from \f(CW$filename\fR, with each
element corresponding to a single line of \f(CW$filename\fR. Additionally,
breakable lines will be dualvars with the numeric component being the
memory address of a \s-1COP\s0 node. Non-breakable lines are dualvar to 0.
.PP
The hash \f(CW\*(C`%{\*(Aq_<\*(Aq.$filename}\*(C'\fR (aliased locally to \f(CW%dbline\fR via glob
assignment) contains breakpoints and actions.  The keys are line numbers;
you can set individual values, but not the whole hash. The Perl interpreter
uses this hash to determine where breakpoints have been set. Any true value is
considered to be a breakpoint; \f(CW\*(C`perl5db.pl\*(C'\fR uses \f(CW\*(C`$break_condition\e0$action\*(C'\fR.
Values are magical in numeric context: 1 if the line is breakable, 0 if not.
.PP
The scalar \f(CW\*(C`${"_<$filename"}\*(C'\fR simply contains the string \f(CW$filename\fR.
This is also the case for evaluated strings that contain subroutines, or
which are currently being executed.  The \f(CW$filename\fR for \f(CW\*(C`eval\*(C'\fRed strings looks
like \f(CW\*(C`(eval 34)\*(C'\fR.
.SH "DEBUGGER STARTUP"
.IX Header "DEBUGGER STARTUP"
When \f(CW\*(C`perl5db.pl\*(C'\fR starts, it reads an rcfile (\f(CW\*(C`perl5db.ini\*(C'\fR for
non-interactive sessions, \f(CW\*(C`.perldb\*(C'\fR for interactive ones) that can set a number
of options. In addition, this file may define a subroutine \f(CW&afterinit\fR
that will be executed (in the debugger's context) after the debugger has
initialized itself.
.PP
Next, it checks the \f(CW\*(C`PERLDB_OPTS\*(C'\fR environment variable and treats its
contents as the argument of a \f(CW\*(C`o\*(C'\fR command in the debugger.
.SS "STARTUP-ONLY \s-1OPTIONS\s0"
.IX Subsection "STARTUP-ONLY OPTIONS"
The following options can only be specified at startup.
To set them in your rcfile, add a call to
\&\f(CW\*(C`&parse_options("optionName=new_value")\*(C'\fR.
.IP "\(bu" 4
\&\s-1TTY\s0
.Sp
the \s-1TTY\s0 to use for debugging i/o.
.IP "\(bu" 4
noTTY
.Sp
if set, goes in NonStop mode.  On interrupt, if \s-1TTY\s0 is not set,
uses the value of noTTY or \fI\f(CI$HOME\fI/.perldbtty$$\fR to find \s-1TTY\s0 using
Term::Rendezvous.  Current variant is to have the name of \s-1TTY\s0 in this
file.
.IP "\(bu" 4
ReadLine
.Sp
if false, a dummy ReadLine is used, so you can debug
ReadLine applications.
.IP "\(bu" 4
NonStop
.Sp
if true, no i/o is performed until interrupt.
.IP "\(bu" 4
LineInfo
.Sp
file or pipe to print line number info to.  If it is a
pipe, a short \*(L"emacs like\*(R" message is used.
.IP "\(bu" 4
RemotePort
.Sp
host:port to connect to on remote host for remote debugging.
.IP "\(bu" 4
HistFile
.Sp
file to store session history to. There is no default and so no
history file is written unless this variable is explicitly set.
.IP "\(bu" 4
HistSize
.Sp
number of commands to store to the file specified in \f(CW\*(C`HistFile\*(C'\fR.
Default is 100.
.PP
\fI\s-1SAMPLE RCFILE\s0\fR
.IX Subsection "SAMPLE RCFILE"
.PP
.Vb 2
\& &parse_options("NonStop=1 LineInfo=db.out");
\&  sub afterinit { $trace = 1; }
.Ve
.PP
The script will run without human intervention, putting trace
information into \f(CW\*(C`db.out\*(C'\fR.  (If you interrupt it, you had better
reset \f(CW\*(C`LineInfo\*(C'\fR to something \fIinteractive\fR!)
.SH "INTERNALS DESCRIPTION"
.IX Header "INTERNALS DESCRIPTION"
.SS "\s-1DEBUGGER INTERFACE VARIABLES\s0"
.IX Subsection "DEBUGGER INTERFACE VARIABLES"
Perl supplies the values for \f(CW%sub\fR.  It effectively inserts
a \f(CW\*(C`&DB::DB();\*(C'\fR in front of each place that can have a
breakpoint. At each subroutine call, it calls \f(CW&DB::sub\fR with
\&\f(CW$DB::sub\fR set to the called subroutine. It also inserts a \f(CW\*(C`BEGIN
{require \*(Aqperl5db.pl\*(Aq}\*(C'\fR before the first line.
.PP
After each \f(CW\*(C`require\*(C'\fRd file is compiled, but before it is executed, a
call to \f(CW\*(C`&DB::postponed($main::{\*(Aq_<\*(Aq.$filename})\*(C'\fR is done. \f(CW$filename\fR
is the expanded name of the \f(CW\*(C`require\*(C'\fRd file (as found via \f(CW%INC\fR).
.PP
\fI\s-1IMPORTANT INTERNAL VARIABLES\s0\fR
.IX Subsection "IMPORTANT INTERNAL VARIABLES"
.PP
\f(CW$CreateTTY\fR
.IX Subsection "$CreateTTY"
.PP
Used to control when the debugger will attempt to acquire another \s-1TTY\s0 to be
used for input.
.IP "\(bu" 4
1 \-  on \f(CW\*(C`fork()\*(C'\fR
.IP "\(bu" 4
2 \- debugger is started inside debugger
.IP "\(bu" 4
4 \-  on startup
.PP
\f(CW$doret\fR
.IX Subsection "$doret"
.PP
The value \-2 indicates that no return value should be printed.
Any other positive value causes \f(CW\*(C`DB::sub\*(C'\fR to print return values.
.PP
\f(CW$evalarg\fR
.IX Subsection "$evalarg"
.PP
The item to be eval'ed by \f(CW\*(C`DB::eval\*(C'\fR. Used to prevent messing with the current
contents of \f(CW@_\fR when \f(CW\*(C`DB::eval\*(C'\fR is called.
.PP
\f(CW$frame\fR
.IX Subsection "$frame"
.PP
Determines what messages (if any) will get printed when a subroutine (or eval)
is entered or exited.
.IP "\(bu" 4
0 \-  No enter/exit messages
.IP "\(bu" 4
1 \- Print \fIentering\fR messages on subroutine entry
.IP "\(bu" 4
2 \- Adds exit messages on subroutine exit. If no other flag is on, acts like 1+2.
.IP "\(bu" 4
4 \- Extended messages: \f(CW\*(C`<in|out> \f(CIcontext\f(CW=\f(CIfully\-qualified sub name\f(CW from \f(CIfile\f(CW:\f(CIline\f(CW\*(C'\fR. If no other flag is on, acts like 1+4.
.IP "\(bu" 4
8 \- Adds parameter information to messages, and overloaded stringify and tied \s-1FETCH\s0 is enabled on the printed arguments. Ignored if \f(CW4\fR is not on.
.IP "\(bu" 4
16 \- Adds \f(CW\*(C`\f(CIcontext\f(CW return from \f(CIsubname\f(CW: \f(CIvalue\f(CW\*(C'\fR messages on subroutine/eval exit. Ignored if \f(CW4\fR is not on.
.PP
To get everything, use \f(CW\*(C`$frame=30\*(C'\fR (or \f(CW\*(C`o f=30\*(C'\fR as a debugger command).
The debugger internally juggles the value of \f(CW$frame\fR during execution to
protect external modules that the debugger uses from getting traced.
.PP
\f(CW$level\fR
.IX Subsection "$level"
.PP
Tracks current debugger nesting level. Used to figure out how many
\&\f(CW\*(C`<>\*(C'\fR pairs to surround the line number with when the debugger
outputs a prompt. Also used to help determine if the program has finished
during command parsing.
.PP
\f(CW$onetimeDump\fR
.IX Subsection "$onetimeDump"
.PP
Controls what (if anything) \f(CW\*(C`DB::eval()\*(C'\fR will print after evaluating an
expression.
.IP "\(bu" 4
\&\f(CW\*(C`undef\*(C'\fR \- don't print anything
.IP "\(bu" 4
\&\f(CW\*(C`dump\*(C'\fR \- use \f(CW\*(C`dumpvar.pl\*(C'\fR to display the value returned
.IP "\(bu" 4
\&\f(CW\*(C`methods\*(C'\fR \- print the methods callable on the first item returned
.PP
\f(CW$onetimeDumpDepth\fR
.IX Subsection "$onetimeDumpDepth"
.PP
Controls how far down \f(CW\*(C`dumpvar.pl\*(C'\fR will go before printing \f(CW\*(C`...\*(C'\fR while
dumping a structure. Numeric. If \f(CW\*(C`undef\*(C'\fR, print all levels.
.PP
\f(CW$signal\fR
.IX Subsection "$signal"
.PP
Used to track whether or not an \f(CW\*(C`INT\*(C'\fR signal has been detected. \f(CW\*(C`DB::DB()\*(C'\fR,
which is called before every statement, checks this and puts the user into
command mode if it finds \f(CW$signal\fR set to a true value.
.PP
\f(CW$single\fR
.IX Subsection "$single"
.PP
Controls behavior during single-stepping. Stacked in \f(CW@stack\fR on entry to
each subroutine; popped again at the end of each subroutine.
.IP "\(bu" 4
0 \- run continuously.
.IP "\(bu" 4
1 \- single-step, go into subs. The \f(CW\*(C`s\*(C'\fR command.
.IP "\(bu" 4
2 \- single-step, don't go into subs. The \f(CW\*(C`n\*(C'\fR command.
.IP "\(bu" 4
4 \- print current sub depth (turned on to force this when \f(CW\*(C`too much
recursion\*(C'\fR occurs.
.PP
\f(CW$trace\fR
.IX Subsection "$trace"
.PP
Controls the output of trace information.
.IP "\(bu" 4
1 \- The \f(CW\*(C`t\*(C'\fR command was entered to turn on tracing (every line executed is printed)
.IP "\(bu" 4
2 \- watch expressions are active
.IP "\(bu" 4
4 \- user defined a \f(CW\*(C`watchfunction()\*(C'\fR in \f(CW\*(C`afterinit()\*(C'\fR
.PP
\f(CW$client_editor\fR
.IX Subsection "$client_editor"
.PP
1 if \f(CW\*(C`LINEINFO\*(C'\fR was directed to a pipe; 0 otherwise.  (The term
\&\f(CW$slave_editor\fR was formerly used here.)
.PP
\f(CW@cmdfhs\fR
.IX Subsection "@cmdfhs"
.PP
Stack of filehandles that \f(CW\*(C`DB::readline()\*(C'\fR will read commands from.
Manipulated by the debugger's \f(CW\*(C`source\*(C'\fR command and \f(CW\*(C`DB::readline()\*(C'\fR itself.
.PP
\f(CW@dbline\fR
.IX Subsection "@dbline"
.PP
Local alias to the magical line array, \f(CW\*(C`@{$main::{\*(Aq_<\*(Aq.$filename}}\*(C'\fR ,
supplied by the Perl interpreter to the debugger. Contains the source.
.PP
\f(CW@old_watch\fR
.IX Subsection "@old_watch"
.PP
Previous values of watch expressions. First set when the expression is
entered; reset whenever the watch expression changes.
.PP
\f(CW@saved\fR
.IX Subsection "@saved"
.PP
Saves important globals (\f(CW$@\fR, \f(CW$!\fR, \f(CW$^E\fR, \f(CW$,\fR, \f(CW$/\fR, \f(CW\*(C`$\e\*(C'\fR, \f(CW$^W\fR)
so that the debugger can substitute safe values while it's running, and
restore them when it returns control.
.PP
\f(CW@stack\fR
.IX Subsection "@stack"
.PP
Saves the current value of \f(CW$single\fR on entry to a subroutine.
Manipulated by the \f(CW\*(C`c\*(C'\fR command to turn off tracing in all subs above the
current one.
.PP
\f(CW@to_watch\fR
.IX Subsection "@to_watch"
.PP
The 'watch' expressions: to be evaluated before each line is executed.
.PP
\f(CW@typeahead\fR
.IX Subsection "@typeahead"
.PP
The typeahead buffer, used by \f(CW\*(C`DB::readline\*(C'\fR.
.PP
\f(CW%alias\fR
.IX Subsection "%alias"
.PP
Command aliases. Stored as character strings to be substituted for a command
entered.
.PP
\f(CW%break_on_load\fR
.IX Subsection "%break_on_load"
.PP
Keys are file names, values are 1 (break when this file is loaded) or undef
(don't break when it is loaded).
.PP
\f(CW%dbline\fR
.IX Subsection "%dbline"
.PP
Keys are line numbers, values are \f(CW\*(C`condition\e0action\*(C'\fR. If used in numeric
context, values are 0 if not breakable, 1 if breakable, no matter what is
in the actual hash entry.
.PP
\f(CW%had_breakpoints\fR
.IX Subsection "%had_breakpoints"
.PP
Keys are file names; values are bitfields:
.IP "\(bu" 4
1 \- file has a breakpoint in it.
.IP "\(bu" 4
2 \- file has an action in it.
.PP
A zero or undefined value means this file has neither.
.PP
\f(CW%option\fR
.IX Subsection "%option"
.PP
Stores the debugger options. These are character string values.
.PP
\f(CW%postponed\fR
.IX Subsection "%postponed"
.PP
Saves breakpoints for code that hasn't been compiled yet.
Keys are subroutine names, values are:
.IP "\(bu" 4
\&\f(CW\*(C`compile\*(C'\fR \- break when this sub is compiled
.IP "\(bu" 4
\&\f(CW\*(C`break +0 if <condition>\*(C'\fR \- break (conditionally) at the start of this routine. The condition will be '1' if no condition was specified.
.PP
\f(CW%postponed_file\fR
.IX Subsection "%postponed_file"
.PP
This hash keeps track of breakpoints that need to be set for files that have
not yet been compiled. Keys are filenames; values are references to hashes.
Each of these hashes is keyed by line number, and its values are breakpoint
definitions (\f(CW\*(C`condition\e0action\*(C'\fR).
.SH "DEBUGGER INITIALIZATION"
.IX Header "DEBUGGER INITIALIZATION"
The debugger's initialization actually jumps all over the place inside this
package. This is because there are several \s-1BEGIN\s0 blocks (which of course
execute immediately) spread through the code. Why is that?
.PP
The debugger needs to be able to change some things and set some things up
before the debugger code is compiled; most notably, the \f(CW$deep\fR variable that
\&\f(CW\*(C`DB::sub\*(C'\fR uses to tell when a program has recursed deeply. In addition, the
debugger has to turn off warnings while the debugger code is compiled, but then
restore them to their original setting before the program being debugged begins
executing.
.PP
The first \f(CW\*(C`BEGIN\*(C'\fR block simply turns off warnings by saving the current
setting of \f(CW$^W\fR and then setting it to zero. The second one initializes
the debugger variables that are needed before the debugger begins executing.
The third one puts \f(CW$^X\fR back to its former value.
.PP
We'll detail the second \f(CW\*(C`BEGIN\*(C'\fR block later; just remember that if you need
to initialize something before the debugger starts really executing, that's
where it has to go.
.SH "DEBUGGER ROUTINES"
.IX Header "DEBUGGER ROUTINES"
.ie n .SS """DB::eval()"""
.el .SS "\f(CWDB::eval()\fP"
.IX Subsection "DB::eval()"
This function replaces straight \f(CW\*(C`eval()\*(C'\fR inside the debugger; it simplifies
the process of evaluating code in the user's context.
.PP
The code to be evaluated is passed via the package global variable
\&\f(CW$DB::evalarg\fR; this is done to avoid fiddling with the contents of \f(CW@_\fR.
.PP
Before we do the \f(CW\*(C`eval()\*(C'\fR, we preserve the current settings of \f(CW$trace\fR,
\&\f(CW$single\fR, \f(CW$^D\fR and \f(CW$usercontext\fR.  The latter contains the
preserved values of \f(CW$@\fR, \f(CW$!\fR, \f(CW$^E\fR, \f(CW$,\fR, \f(CW$/\fR, \f(CW\*(C`$\e\*(C'\fR, \f(CW$^W\fR and the
user's current package, grabbed when \f(CW\*(C`DB::DB\*(C'\fR got control.  This causes the
proper context to be used when the eval is actually done.  Afterward, we
restore \f(CW$trace\fR, \f(CW$single\fR, and \f(CW$^D\fR.
.PP
Next we need to handle \f(CW$@\fR without getting confused. We save \f(CW$@\fR in a
local lexical, localize \f(CW$saved[0]\fR (which is where \f(CW\*(C`save()\*(C'\fR will put
\&\f(CW$@\fR), and then call \f(CW\*(C`save()\*(C'\fR to capture \f(CW$@\fR, \f(CW$!\fR, \f(CW$^E\fR, \f(CW$,\fR,
\&\f(CW$/\fR, \f(CW\*(C`$\e\*(C'\fR, and \f(CW$^W\fR) and set \f(CW$,\fR, \f(CW$/\fR, \f(CW\*(C`$\e\*(C'\fR, and \f(CW$^W\fR to values
considered sane by the debugger. If there was an \f(CW\*(C`eval()\*(C'\fR error, we print
it on the debugger's output. If \f(CW$onetimedump\fR is defined, we call
\&\f(CW\*(C`dumpit\*(C'\fR if it's set to 'dump', or \f(CW\*(C`methods\*(C'\fR if it's set to
\&'methods'. Setting it to something else causes the debugger to do the eval
but not print the result \- handy if you want to do something else with it
(the \*(L"watch expressions\*(R" code does this to get the value of the watch
expression but not show it unless it matters).
.PP
In any case, we then return the list of output from \f(CW\*(C`eval\*(C'\fR to the caller,
and unwinding restores the former version of \f(CW$@\fR in \f(CW@saved\fR as well
(the localization of \f(CW$saved[0]\fR goes away at the end of this scope).
.PP
\fIParameters and variables influencing execution of \f(BIDB::eval()\fI\fR
.IX Subsection "Parameters and variables influencing execution of DB::eval()"
.PP
\&\f(CW\*(C`DB::eval\*(C'\fR isn't parameterized in the standard way; this is to keep the
debugger's calls to \f(CW\*(C`DB::eval()\*(C'\fR from mucking with \f(CW@_\fR, among other things.
The variables listed below influence \f(CW\*(C`DB::eval()\*(C'\fR's execution directly.
.ie n .IP "$evalarg \- the thing to actually be eval'ed" 4
.el .IP "\f(CW$evalarg\fR \- the thing to actually be eval'ed" 4
.IX Item "$evalarg - the thing to actually be eval'ed"
.PD 0
.ie n .IP "$trace \- Current state of execution tracing" 4
.el .IP "\f(CW$trace\fR \- Current state of execution tracing" 4
.IX Item "$trace - Current state of execution tracing"
.ie n .IP "$single \- Current state of single-stepping" 4
.el .IP "\f(CW$single\fR \- Current state of single-stepping" 4
.IX Item "$single - Current state of single-stepping"
.ie n .IP "$onetimeDump \- what is to be displayed after the evaluation" 4
.el .IP "\f(CW$onetimeDump\fR \- what is to be displayed after the evaluation" 4
.IX Item "$onetimeDump - what is to be displayed after the evaluation"
.ie n .IP "$onetimeDumpDepth \- how deep ""dumpit()"" should go when dumping results" 4
.el .IP "\f(CW$onetimeDumpDepth\fR \- how deep \f(CWdumpit()\fR should go when dumping results" 4
.IX Item "$onetimeDumpDepth - how deep dumpit() should go when dumping results"
.PD
.PP
The following variables are altered by \f(CW\*(C`DB::eval()\*(C'\fR during its execution. They
are \*(L"stacked\*(R" via \f(CW\*(C`local()\*(C'\fR, enabling recursive calls to \f(CW\*(C`DB::eval()\*(C'\fR.
.ie n .IP "@res \- used to capture output from actual ""eval""." 4
.el .IP "\f(CW@res\fR \- used to capture output from actual \f(CWeval\fR." 4
.IX Item "@res - used to capture output from actual eval."
.PD 0
.ie n .IP "$otrace \- saved value of $trace." 4
.el .IP "\f(CW$otrace\fR \- saved value of \f(CW$trace\fR." 4
.IX Item "$otrace - saved value of $trace."
.ie n .IP "$osingle \- saved value of $single." 4
.el .IP "\f(CW$osingle\fR \- saved value of \f(CW$single\fR." 4
.IX Item "$osingle - saved value of $single."
.ie n .IP "$od \- saved value of $^D." 4
.el .IP "\f(CW$od\fR \- saved value of \f(CW$^D\fR." 4
.IX Item "$od - saved value of $^D."
.ie n .IP "$saved[0] \- saved value of $@." 4
.el .IP "\f(CW$saved[0]\fR \- saved value of \f(CW$@\fR." 4
.IX Item "$saved[0] - saved value of $@."
.ie n .IP "$\e \- for output of $@ if there is an evaluation error." 4
.el .IP "$\e \- for output of \f(CW$@\fR if there is an evaluation error." 4
.IX Item "$ - for output of $@ if there is an evaluation error."
.PD
.PP
\fIThe problem of lexicals\fR
.IX Subsection "The problem of lexicals"
.PP
The context of \f(CW\*(C`DB::eval()\*(C'\fR presents us with some problems. Obviously,
we want to be 'sandboxed' away from the debugger's internals when we do
the eval, but we need some way to control how punctuation variables and
debugger globals are used.
.PP
We can't use local, because the code inside \f(CW\*(C`DB::eval\*(C'\fR can see localized
variables; and we can't use \f(CW\*(C`my\*(C'\fR either for the same reason. The code
in this routine compromises and uses \f(CW\*(C`my\*(C'\fR.
.PP
After this routine is over, we don't have user code executing in the debugger's
context, so we can use \f(CW\*(C`my\*(C'\fR freely.
.SH "DEBUGGER INITIALIZATION"
.IX Header "DEBUGGER INITIALIZATION"
The debugger starts up in phases.
.SS "\s-1BASIC SETUP\s0"
.IX Subsection "BASIC SETUP"
First, it initializes the environment it wants to run in: turning off
warnings during its own compilation, defining variables which it will need
to avoid warnings later, setting itself up to not exit when the program
terminates, and defaulting to printing return values for the \f(CW\*(C`r\*(C'\fR command.
.SS "\s-1THREADS SUPPORT\s0"
.IX Subsection "THREADS SUPPORT"
If we are running under a threaded Perl, we require threads and threads::shared
if the environment variable \f(CW\*(C`PERL5DB_THREADED\*(C'\fR is set, to enable proper
threaded debugger control.  \f(CW\*(C`\-dt\*(C'\fR can also be used to set this.
.PP
Each new thread will be announced and the debugger prompt will always inform
you of each new thread created.  It will also indicate the thread id in which
we are currently running within the prompt like this:
.PP
.Vb 1
\&    [tid] DB<$i>
.Ve
.PP
Where \f(CW\*(C`[tid]\*(C'\fR is an integer thread id and \f(CW$i\fR is the familiar debugger
command prompt.  The prompt will show: \f(CW\*(C`[0]\*(C'\fR when running under threads, but
not actually in a thread.  \f(CW\*(C`[tid]\*(C'\fR is consistent with \f(CW\*(C`gdb\*(C'\fR usage.
.PP
While running under threads, when you set or delete a breakpoint (etc.), this
will apply to all threads, not just the currently running one.  When you are
in a currently executing thread, you will stay there until it completes.  With
the current implementation it is not currently possible to hop from one thread
to another.
.PP
The \f(CW\*(C`e\*(C'\fR and \f(CW\*(C`E\*(C'\fR commands are currently fairly minimal \- see
\&\f(CW\*(C`h e\*(C'\fR and \f(CW\*(C`h E\*(C'\fR.
.PP
Note that threading support was built into the debugger as of Perl version
\&\f(CW5.8.6\fR and debugger version \f(CW1.2.8\fR.
.SH "OPTION PROCESSING"
.IX Header "OPTION PROCESSING"
The debugger's options are actually spread out over the debugger itself and
\&\f(CW\*(C`dumpvar.pl\*(C'\fR; some of these are variables to be set, while others are
subs to be called with a value. To try to make this a little easier to
manage, the debugger uses a few data structures to define what options
are legal and how they are to be processed.
.PP
First, the \f(CW@options\fR array defines the \fInames\fR of all the options that
are to be accepted.
.PP
Second, \f(CW\*(C`optionVars\*(C'\fR lists the variables that each option uses to save its
state.
.PP
Third, \f(CW%optionAction\fR defines the subroutine to be called to process each
option.
.PP
Last, the \f(CW%optionRequire\fR notes modules that must be \f(CW\*(C`require\*(C'\fRd if an
option is used.
.PP
There are a number of initialization-related variables which can be set
by putting code to set them in a \s-1BEGIN\s0 block in the \f(CW\*(C`PERL5DB\*(C'\fR environment
variable. These are:
.ie n .IP "$rl \- readline control \s-1XXX\s0 needs more explanation" 4
.el .IP "\f(CW$rl\fR \- readline control \s-1XXX\s0 needs more explanation" 4
.IX Item "$rl - readline control XXX needs more explanation"
.PD 0
.ie n .IP "$warnLevel \- whether or not debugger takes over warning handling" 4
.el .IP "\f(CW$warnLevel\fR \- whether or not debugger takes over warning handling" 4
.IX Item "$warnLevel - whether or not debugger takes over warning handling"
.ie n .IP "$dieLevel \- whether or not debugger takes over die handling" 4
.el .IP "\f(CW$dieLevel\fR \- whether or not debugger takes over die handling" 4
.IX Item "$dieLevel - whether or not debugger takes over die handling"
.ie n .IP "$signalLevel \- whether or not debugger takes over signal handling" 4
.el .IP "\f(CW$signalLevel\fR \- whether or not debugger takes over signal handling" 4
.IX Item "$signalLevel - whether or not debugger takes over signal handling"
.ie n .IP "$pre \- preprompt actions (array reference)" 4
.el .IP "\f(CW$pre\fR \- preprompt actions (array reference)" 4
.IX Item "$pre - preprompt actions (array reference)"
.ie n .IP "$post \- postprompt actions (array reference)" 4
.el .IP "\f(CW$post\fR \- postprompt actions (array reference)" 4
.IX Item "$post - postprompt actions (array reference)"
.ie n .IP "$pretype" 4
.el .IP "\f(CW$pretype\fR" 4
.IX Item "$pretype"
.ie n .IP "$CreateTTY \- whether or not to create a new \s-1TTY\s0 for this debugger" 4
.el .IP "\f(CW$CreateTTY\fR \- whether or not to create a new \s-1TTY\s0 for this debugger" 4
.IX Item "$CreateTTY - whether or not to create a new TTY for this debugger"
.ie n .IP "$CommandSet \- which command set to use (defaults to new, documented set)" 4
.el .IP "\f(CW$CommandSet\fR \- which command set to use (defaults to new, documented set)" 4
.IX Item "$CommandSet - which command set to use (defaults to new, documented set)"
.PD
.PP
The default \f(CW\*(C`die\*(C'\fR, \f(CW\*(C`warn\*(C'\fR, and \f(CW\*(C`signal\*(C'\fR handlers are set up.
.PP
The pager to be used is needed next. We try to get it from the
environment first.  If it's not defined there, we try to find it in
the Perl \f(CW\*(C`Config.pm\*(C'\fR.  If it's not there, we default to \f(CW\*(C`more\*(C'\fR. We
then call the \f(CW\*(C`pager()\*(C'\fR function to save the pager name.
.PP
We set up the command to be used to access the man pages, the command
recall character (\f(CW\*(C`!\*(C'\fR unless otherwise defined) and the shell escape
character (\f(CW\*(C`!\*(C'\fR unless otherwise defined). Yes, these do conflict, and
neither works in the debugger at the moment.
.PP
We then set up the gigantic string containing the debugger help.
We also set the limit on the number of arguments we'll display during a
trace.
.SS "\s-1SETTING UP THE DEBUGGER GREETING\s0"
.IX Subsection "SETTING UP THE DEBUGGER GREETING"
The debugger \fIgreeting\fR helps to inform the user how many debuggers are
running, and whether the current debugger is the primary or a child.
.PP
If we are the primary, we just hang onto our pid so we'll have it when
or if we start a child debugger. If we are a child, we'll set things up
so we'll have a unique greeting and so the parent will give us our own
\&\s-1TTY\s0 later.
.PP
We save the current contents of the \f(CW\*(C`PERLDB_PIDS\*(C'\fR environment variable
because we mess around with it. We'll also need to hang onto it because
we'll need it if we restart.
.PP
Child debuggers make a label out of the current \s-1PID\s0 structure recorded in
\&\s-1PERLDB_PIDS\s0 plus the new \s-1PID.\s0 They also mark themselves as not having a \s-1TTY\s0
yet so the parent will give them one later via \f(CW\*(C`resetterm()\*(C'\fR.
.SS "\s-1READING THE RC FILE\s0"
.IX Subsection "READING THE RC FILE"
The debugger will read a file of initialization options if supplied. If
running interactively, this is \f(CW\*(C`.perldb\*(C'\fR; if not, it's \f(CW\*(C`perldb.ini\*(C'\fR.
.PP
The debugger does a safety test of the file to be read. It must be owned
either by the current user or root, and must only be writable by the owner.
.PP
The last thing we do during initialization is determine which subroutine is
to be used to obtain a new terminal when a new debugger is started. Right now,
the debugger only handles \s-1TCP\s0 sockets, X11, \s-1OS/2,\s0 amd Mac \s-1OS X\s0
(darwin).
.SS "\s-1RESTART PROCESSING\s0"
.IX Subsection "RESTART PROCESSING"
This section handles the restart command. When the \f(CW\*(C`R\*(C'\fR command is invoked, it
tries to capture all of the state it can into environment variables, and
then sets \f(CW\*(C`PERLDB_RESTART\*(C'\fR. When we start executing again, we check to see
if \f(CW\*(C`PERLDB_RESTART\*(C'\fR is there; if so, we reload all the information that
the R command stuffed into the environment variables.
.PP
.Vb 10
\&  PERLDB_RESTART   \- flag only, contains no restart data itself.
\&  PERLDB_HIST      \- command history, if it\*(Aqs available
\&  PERLDB_ON_LOAD   \- breakpoints set by the rc file
\&  PERLDB_POSTPONE  \- subs that have been loaded/not executed,
\&                     and have actions
\&  PERLDB_VISITED   \- files that had breakpoints
\&  PERLDB_FILE_...  \- breakpoints for a file
\&  PERLDB_OPT       \- active options
\&  PERLDB_INC       \- the original @INC
\&  PERLDB_PRETYPE   \- preprompt debugger actions
\&  PERLDB_PRE       \- preprompt Perl code
\&  PERLDB_POST      \- post\-prompt Perl code
\&  PERLDB_TYPEAHEAD \- typeahead captured by readline()
.Ve
.PP
We chug through all these variables and plug the values saved in them
back into the appropriate spots in the debugger.
.SS "\s-1SETTING UP THE TERMINAL\s0"
.IX Subsection "SETTING UP THE TERMINAL"
Now, we'll decide how the debugger is going to interact with the user.
If there's no \s-1TTY,\s0 we set the debugger to run non-stop; there's not going
to be anyone there to enter commands.
.PP
If there is a \s-1TTY,\s0 we have to determine who it belongs to before we can
proceed. If this is a client editor or graphical debugger (denoted by
the first command-line switch being '\-emacs'), we shift this off and
set \f(CW$rl\fR to 0 (\s-1XXX\s0 ostensibly to do straight reads).
.PP
We then determine what the console should be on various systems:
.IP "\(bu" 4
Cygwin \- We use \f(CW\*(C`stdin\*(C'\fR instead of a separate device.
.IP "\(bu" 4
Windows \- use \f(CW\*(C`con\*(C'\fR.
.IP "\(bu" 4
AmigaOS \- use \f(CW\*(C`CONSOLE:\*(C'\fR.
.IP "\(bu" 4
\&\s-1VMS\s0 \- use \f(CW\*(C`sys$command\*(C'\fR.
.IP "\(bu" 4
Unix \- use \fI/dev/tty\fR.
.PP
Several other systems don't use a specific console. We \f(CW\*(C`undef $console\*(C'\fR
for those (Windows using a client editor/graphical debugger, \s-1OS/2\s0
with a client editor).
.PP
If there is a \s-1TTY\s0 hanging around from a parent, we use that as the console.
.SS "\s-1SOCKET HANDLING\s0"
.IX Subsection "SOCKET HANDLING"
The debugger is capable of opening a socket and carrying out a debugging
session over the socket.
.PP
If \f(CW\*(C`RemotePort\*(C'\fR was defined in the options, the debugger assumes that it
should try to start a debugging session on that port. It builds the socket
and then tries to connect the input and output filehandles to it.
.PP
If no \f(CW\*(C`RemotePort\*(C'\fR was defined, and we want to create a \s-1TTY\s0 on startup,
this is probably a situation where multiple debuggers are running (for example,
a backticked command that starts up another debugger). We create a new \s-1IN\s0 and
\&\s-1OUT\s0 filehandle, and do the necessary mojo to create a new \s-1TTY\s0 if we know how
and if we can.
.PP
To finish initialization, we show the debugger greeting,
and then call the \f(CW\*(C`afterinit()\*(C'\fR subroutine if there is one.
.SH "SUBROUTINES"
.IX Header "SUBROUTINES"
.SS "\s-1DB\s0"
.IX Subsection "DB"
This gigantic subroutine is the heart of the debugger. Called before every
statement, its job is to determine if a breakpoint has been reached, and
stop if so; read commands from the user, parse them, and execute
them, and then send execution off to the next statement.
.PP
Note that the order in which the commands are processed is very important;
some commands earlier in the loop will actually alter the \f(CW$cmd\fR variable
to create other commands to be executed later. This is all highly \fIoptimized\fR
but can be confusing. Check the comments for each \f(CW\*(C`$cmd ... && do {}\*(C'\fR to
see what's happening in any given command.
.PP
\fI\f(CI\*(C`_DB_\|_handle_i_command\*(C'\fI \- inheritance display\fR
.IX Subsection "_DB__handle_i_command - inheritance display"
.PP
Display the (nested) parentage of the module or object given.
.PP
\fI\f(CI\*(C`_cmd_l_main\*(C'\fI \- list lines (command)\fR
.IX Subsection "_cmd_l_main - list lines (command)"
.PP
Most of the command is taken up with transforming all the different line
specification syntaxes into 'start\-stop'. After that is done, the command
runs a loop over \f(CW@dbline\fR for the specified range of lines. It handles
the printing of each line and any markers (\f(CW\*(C`==>\*(C'\fR for current line,
\&\f(CW\*(C`b\*(C'\fR for break on this line, \f(CW\*(C`a\*(C'\fR for action on this line, \f(CW\*(C`:\*(C'\fR for this
line breakable).
.PP
We save the last line listed in the \f(CW$start\fR global for further listing
later.
.ie n .SS """watchfunction()"""
.el .SS "\f(CWwatchfunction()\fP"
.IX Subsection "watchfunction()"
\&\f(CW\*(C`watchfunction()\*(C'\fR is a function that can be defined by the user; it is a
function which will be run on each entry to \f(CW\*(C`DB::DB\*(C'\fR; it gets the
current package, filename, and line as its parameters.
.PP
The watchfunction can do anything it likes; it is executing in the
debugger's context, so it has access to all of the debugger's internal
data structures and functions.
.PP
\&\f(CW\*(C`watchfunction()\*(C'\fR can control the debugger's actions. Any of the following
will cause the debugger to return control to the user's program after
\&\f(CW\*(C`watchfunction()\*(C'\fR executes:
.IP "\(bu" 4
Returning a false value from the \f(CW\*(C`watchfunction()\*(C'\fR itself.
.IP "\(bu" 4
Altering \f(CW$single\fR to a false value.
.IP "\(bu" 4
Altering \f(CW$signal\fR to a false value.
.IP "\(bu" 4
Turning off the \f(CW4\fR bit in \f(CW$trace\fR (this also disables the
check for \f(CW\*(C`watchfunction()\*(C'\fR. This can be done with
.Sp
.Vb 1
\&    $trace &= ~4;
.Ve
.SS "\s-1GETTING READY TO EXECUTE COMMANDS\s0"
.IX Subsection "GETTING READY TO EXECUTE COMMANDS"
The debugger decides to take control if single-step mode is on, the
\&\f(CW\*(C`t\*(C'\fR command was entered, or the user generated a signal. If the program
has fallen off the end, we set things up so that entering further commands
won't cause trouble, and we say that the program is over.
.PP
If there's an action to be executed for the line we stopped at, execute it.
If there are any preprompt actions, execute those as well.
.SS "\s-1WHERE ARE WE\s0?"
.IX Subsection "WHERE ARE WE?"
\&\s-1XXX\s0 Relocate this section?
.PP
The debugger normally shows the line corresponding to the current line of
execution. Sometimes, though, we want to see the next line, or to move elsewhere
in the file. This is done via the \f(CW$incr\fR, \f(CW$start\fR, and \f(CW$max\fR variables.
.PP
\&\f(CW$incr\fR controls by how many lines the \fIcurrent\fR line should move forward
after a command is executed. If set to \-1, this indicates that the \fIcurrent\fR
line shouldn't change.
.PP
\&\f(CW$start\fR is the \fIcurrent\fR line. It is used for things like knowing where to
move forwards or backwards from when doing an \f(CW\*(C`L\*(C'\fR or \f(CW\*(C`\-\*(C'\fR command.
.PP
\&\f(CW$max\fR tells the debugger where the last line of the current file is. It's
used to terminate loops most often.
.SS "\s-1THE COMMAND LOOP\s0"
.IX Subsection "THE COMMAND LOOP"
Most of \f(CW\*(C`DB::DB\*(C'\fR is actually a command parsing and dispatch loop. It comes
in two parts:
.IP "\(bu" 4
The outer part of the loop, starting at the \f(CW\*(C`CMD\*(C'\fR label. This loop
reads a command and then executes it.
.IP "\(bu" 4
The inner part of the loop, starting at the \f(CW\*(C`PIPE\*(C'\fR label. This part
is wholly contained inside the \f(CW\*(C`CMD\*(C'\fR block and only executes a command.
Used to handle commands running inside a pager.
.PP
So why have two labels to restart the loop? Because sometimes, it's easier to
have a command \fIgenerate\fR another command and then re-execute the loop to do
the new command. This is faster, but perhaps a bit more convoluted.
.PP
The null command
.IX Subsection "The null command"
.PP
A newline entered by itself means \fIre-execute the last command\fR. We grab the
command out of \f(CW$laststep\fR (where it was recorded previously), and copy it
back into \f(CW$cmd\fR to be executed below. If there wasn't any previous command,
we'll do nothing below (no command will match). If there was, we also save it
in the command history and fall through to allow the command parsing to pick
it up.
.PP
\fI\s-1COMMAND ALIASES\s0\fR
.IX Subsection "COMMAND ALIASES"
.PP
The debugger can create aliases for commands (these are stored in the
\&\f(CW%alias\fR hash). Before a command is executed, the command loop looks it up
in the alias hash and substitutes the contents of the alias for the command,
completely replacing it.
.PP
\fIMAIN-LINE \s-1COMMANDS\s0\fR
.IX Subsection "MAIN-LINE COMMANDS"
.PP
All of these commands work up to and after the program being debugged has
terminated.
.PP
\f(CW\*(C`q\*(C'\fR \- quit
.IX Subsection "q - quit"
.PP
Quit the debugger. This entails setting the \f(CW$fall_off_end\fR flag, so we don't
try to execute further, cleaning any restart-related stuff out of the
environment, and executing with the last value of \f(CW$?\fR.
.PP
\f(CW\*(C`t\*(C'\fR \- trace [n]
.IX Subsection "t - trace [n]"
.PP
Turn tracing on or off. Inverts the appropriate bit in \f(CW$trace\fR (q.v.).
If level is specified, set \f(CW$trace_to_depth\fR.
.PP
\f(CW\*(C`S\*(C'\fR \- list subroutines matching/not matching a pattern
.IX Subsection "S - list subroutines matching/not matching a pattern"
.PP
Walks through \f(CW%sub\fR, checking to see whether or not to print the name.
.PP
\f(CW\*(C`X\*(C'\fR \- list variables in current package
.IX Subsection "X - list variables in current package"
.PP
Since the \f(CW\*(C`V\*(C'\fR command actually processes this, just change this to the
appropriate \f(CW\*(C`V\*(C'\fR command and fall through.
.PP
\f(CW\*(C`V\*(C'\fR \- list variables
.IX Subsection "V - list variables"
.PP
Uses \f(CW\*(C`dumpvar.pl\*(C'\fR to dump out the current values for selected variables.
.PP
\f(CW\*(C`x\*(C'\fR \- evaluate and print an expression
.IX Subsection "x - evaluate and print an expression"
.PP
Hands the expression off to \f(CW\*(C`DB::eval\*(C'\fR, setting it up to print the value
via \f(CW\*(C`dumpvar.pl\*(C'\fR instead of just printing it directly.
.PP
\f(CW\*(C`m\*(C'\fR \- print methods
.IX Subsection "m - print methods"
.PP
Just uses \f(CW\*(C`DB::methods\*(C'\fR to determine what methods are available.
.PP
\f(CW\*(C`f\*(C'\fR \- switch files
.IX Subsection "f - switch files"
.PP
Switch to a different filename.
.PP
\f(CW\*(C`.\*(C'\fR \- return to last-executed line.
.IX Subsection ". - return to last-executed line."
.PP
We set \f(CW$incr\fR to \-1 to indicate that the debugger shouldn't move ahead,
and then we look up the line in the magical \f(CW%dbline\fR hash.
.PP
\f(CW\*(C`\-\*(C'\fR \- back one window
.IX Subsection "- - back one window"
.PP
We change \f(CW$start\fR to be one window back; if we go back past the first line,
we set it to be the first line. We set \f(CW$incr\fR to put us back at the
currently-executing line, and then put a \f(CW\*(C`l $start +\*(C'\fR (list one window from
\&\f(CW$start\fR) in \f(CW$cmd\fR to be executed later.
.PP
\fI\s-1PRE\-580 COMMANDS VS. NEW COMMANDS:\s0 \f(CI\*(C`a, A, b, B, h, l, L, M, o, O, P, v, w, W, <, <<, {, {{\*(C'\fI\fR
.IX Subsection "PRE-580 COMMANDS VS. NEW COMMANDS: a, A, b, B, h, l, L, M, o, O, P, v, w, W, <, <<, {, {{"
.PP
In Perl 5.8.0, a realignment of the commands was done to fix up a number of
problems, most notably that the default case of several commands destroying
the user's work in setting watchpoints, actions, etc. We wanted, however, to
retain the old commands for those who were used to using them or who preferred
them. At this point, we check for the new commands and call \f(CW\*(C`cmd_wrapper\*(C'\fR to
deal with them instead of processing them in-line.
.PP
\f(CW\*(C`y\*(C'\fR \- List lexicals in higher scope
.IX Subsection "y - List lexicals in higher scope"
.PP
Uses \f(CW\*(C`PadWalker\*(C'\fR to find the lexicals supplied as arguments in a scope
above the current one and then displays then using \f(CW\*(C`dumpvar.pl\*(C'\fR.
.PP
\fI\s-1COMMANDS NOT WORKING AFTER PROGRAM ENDS\s0\fR
.IX Subsection "COMMANDS NOT WORKING AFTER PROGRAM ENDS"
.PP
All of the commands below this point don't work after the program being
debugged has ended. All of them check to see if the program has ended; this
allows the commands to be relocated without worrying about a 'line of
demarcation' above which commands can be entered anytime, and below which
they can't.
.PP
\f(CW\*(C`n\*(C'\fR \- single step, but don't trace down into subs
.IX Subsection "n - single step, but don't trace down into subs"
.PP
Done by setting \f(CW$single\fR to 2, which forces subs to execute straight through
when entered (see \f(CW\*(C`DB::sub\*(C'\fR in \*(L"\s-1DEBUGGER INTERFACE VARIABLES\*(R"\s0). We also
save the \f(CW\*(C`n\*(C'\fR command in \f(CW$laststep\fR,
.PP
so a null command knows what to re-execute.
.PP
\f(CW\*(C`s\*(C'\fR \- single-step, entering subs
.IX Subsection "s - single-step, entering subs"
.PP
Sets \f(CW$single\fR to 1, which causes \f(CW\*(C`DB::sub\*(C'\fR to continue tracing inside
subs. Also saves \f(CW\*(C`s\*(C'\fR as \f(CW$lastcmd\fR.
.PP
\f(CW\*(C`c\*(C'\fR \- run continuously, setting an optional breakpoint
.IX Subsection "c - run continuously, setting an optional breakpoint"
.PP
Most of the code for this command is taken up with locating the optional
breakpoint, which is either a subroutine name or a line number. We set
the appropriate one-time-break in \f(CW@dbline\fR and then turn off single-stepping
in this and all call levels above this one.
.PP
\f(CW\*(C`r\*(C'\fR \- return from a subroutine
.IX Subsection "r - return from a subroutine"
.PP
For \f(CW\*(C`r\*(C'\fR to work properly, the debugger has to stop execution again
immediately after the return is executed. This is done by forcing
single-stepping to be on in the call level above the current one. If
we are printing return values when a \f(CW\*(C`r\*(C'\fR is executed, set \f(CW$doret\fR
appropriately, and force us out of the command loop.
.PP
\f(CW\*(C`T\*(C'\fR \- stack trace
.IX Subsection "T - stack trace"
.PP
Just calls \f(CW\*(C`DB::print_trace\*(C'\fR.
.PP
\f(CW\*(C`w\*(C'\fR \- List window around current line.
.IX Subsection "w - List window around current line."
.PP
Just calls \f(CW\*(C`DB::cmd_w\*(C'\fR.
.PP
\f(CW\*(C`W\*(C'\fR \- watch-expression processing.
.IX Subsection "W - watch-expression processing."
.PP
Just calls \f(CW\*(C`DB::cmd_W\*(C'\fR.
.PP
\f(CW\*(C`/\*(C'\fR \- search forward for a string in the source
.IX Subsection "/ - search forward for a string in the source"
.PP
We take the argument and treat it as a pattern. If it turns out to be a
bad one, we return the error we got from trying to \f(CW\*(C`eval\*(C'\fR it and exit.
If not, we create some code to do the search and \f(CW\*(C`eval\*(C'\fR it so it can't
mess us up.
.PP
\f(CW\*(C`?\*(C'\fR \- search backward for a string in the source
.IX Subsection "? - search backward for a string in the source"
.PP
Same as for \f(CW\*(C`/\*(C'\fR, except the loop runs backwards.
.PP
\f(CW$rc\fR \- Recall command
.IX Subsection "$rc - Recall command"
.PP
Manages the commands in \f(CW@hist\fR (which is created if \f(CW\*(C`Term::ReadLine\*(C'\fR reports
that the terminal supports history). It finds the command required, puts it
into \f(CW$cmd\fR, and redoes the loop to execute it.
.PP
\f(CW\*(C`$sh$sh\*(C'\fR \- \f(CW\*(C`system()\*(C'\fR command
.IX Subsection "$sh$sh - system() command"
.PP
Calls the \f(CW\*(C`_db_system()\*(C'\fR to handle the command. This keeps the \f(CW\*(C`STDIN\*(C'\fR and
\&\f(CW\*(C`STDOUT\*(C'\fR from getting messed up.
.PP
\f(CW\*(C`$rc \f(CIpattern\f(CW $rc\*(C'\fR \- Search command history
.IX Subsection "$rc pattern $rc - Search command history"
.PP
Another command to manipulate \f(CW@hist\fR: this one searches it with a pattern.
If a command is found, it is placed in \f(CW$cmd\fR and executed via \f(CW\*(C`redo\*(C'\fR.
.PP
\f(CW$sh\fR \- Invoke a shell
.IX Subsection "$sh - Invoke a shell"
.PP
Uses \f(CW\*(C`_db_system()\*(C'\fR to invoke a shell.
.PP
\f(CW\*(C`$sh \f(CIcommand\f(CW\*(C'\fR \- Force execution of a command in a shell
.IX Subsection "$sh command - Force execution of a command in a shell"
.PP
Like the above, but the command is passed to the shell. Again, we use
\&\f(CW\*(C`_db_system()\*(C'\fR to avoid problems with \f(CW\*(C`STDIN\*(C'\fR and \f(CW\*(C`STDOUT\*(C'\fR.
.PP
\f(CW\*(C`H\*(C'\fR \- display commands in history
.IX Subsection "H - display commands in history"
.PP
Prints the contents of \f(CW@hist\fR (if any).
.PP
\f(CW\*(C`man, doc, perldoc\*(C'\fR \- look up documentation
.IX Subsection "man, doc, perldoc - look up documentation"
.PP
Just calls \f(CW\*(C`runman()\*(C'\fR to print the appropriate document.
.PP
\f(CW\*(C`p\*(C'\fR \- print
.IX Subsection "p - print"
.PP
Builds a \f(CW\*(C`print EXPR\*(C'\fR expression in the \f(CW$cmd\fR; this will get executed at
the bottom of the loop.
.PP
\f(CW\*(C`=\*(C'\fR \- define command alias
.IX Subsection "= - define command alias"
.PP
Manipulates \f(CW%alias\fR to add or list command aliases.
.PP
\f(CW\*(C`source\*(C'\fR \- read commands from a file.
.IX Subsection "source - read commands from a file."
.PP
Opens a lexical filehandle and stacks it on \f(CW@cmdfhs\fR; \f(CW\*(C`DB::readline\*(C'\fR will
pick it up.
.PP
\f(CW\*(C`enable\*(C'\fR \f(CW\*(C`disable\*(C'\fR \- enable or disable breakpoints
.IX Subsection "enable disable - enable or disable breakpoints"
.PP
This enables or disables breakpoints.
.PP
\f(CW\*(C`save\*(C'\fR \- send current history to a file
.IX Subsection "save - send current history to a file"
.PP
Takes the complete history, (not the shrunken version you see with \f(CW\*(C`H\*(C'\fR),
and saves it to the given filename, so it can be replayed using \f(CW\*(C`source\*(C'\fR.
.PP
Note that all \f(CW\*(C`^(save|source)\*(C'\fR's are commented out with a view to minimise recursion.
.PP
\f(CW\*(C`R\*(C'\fR \- restart
.IX Subsection "R - restart"
.PP
Restart the debugger session.
.PP
\f(CW\*(C`rerun\*(C'\fR \- rerun the current session
.IX Subsection "rerun - rerun the current session"
.PP
Return to any given position in the \fBtrue\fR\-history list
.PP
\f(CW\*(C`|, ||\*(C'\fR \- pipe output through the pager.
.IX Subsection "|, || - pipe output through the pager."
.PP
For \f(CW\*(C`|\*(C'\fR, we save \f(CW\*(C`OUT\*(C'\fR (the debugger's output filehandle) and \f(CW\*(C`STDOUT\*(C'\fR
(the program's standard output). For \f(CW\*(C`||\*(C'\fR, we only save \f(CW\*(C`OUT\*(C'\fR. We open a
pipe to the pager (restoring the output filehandles if this fails). If this
is the \f(CW\*(C`|\*(C'\fR command, we also set up a \f(CW\*(C`SIGPIPE\*(C'\fR handler which will simply
set \f(CW$signal\fR, sending us back into the debugger.
.PP
We then trim off the pipe symbols and \f(CW\*(C`redo\*(C'\fR the command loop at the
\&\f(CW\*(C`PIPE\*(C'\fR label, causing us to evaluate the command in \f(CW$cmd\fR without
reading another.
.PP
\fI\s-1END OF COMMAND PARSING\s0\fR
.IX Subsection "END OF COMMAND PARSING"
.PP
Anything left in \f(CW$cmd\fR at this point is a Perl expression that we want to
evaluate. We'll always evaluate in the user's context, and fully qualify
any variables we might want to address in the \f(CW\*(C`DB\*(C'\fR package.
.PP
\fIPOST-COMMAND \s-1PROCESSING\s0\fR
.IX Subsection "POST-COMMAND PROCESSING"
.PP
After each command, we check to see if the command output was piped anywhere.
If so, we go through the necessary code to unhook the pipe and go back to
our standard filehandles for input and output.
.PP
\fI\s-1COMMAND LOOP TERMINATION\s0\fR
.IX Subsection "COMMAND LOOP TERMINATION"
.PP
When commands have finished executing, we come here. If the user closed the
input filehandle, we turn on \f(CW$fall_off_end\fR to emulate a \f(CW\*(C`q\*(C'\fR command. We
evaluate any post-prompt items. We restore \f(CW$@\fR, \f(CW$!\fR, \f(CW$^E\fR, \f(CW$,\fR, \f(CW$/\fR,
\&\f(CW\*(C`$\e\*(C'\fR, and \f(CW$^W\fR, and return a null list as expected by the Perl interpreter.
The interpreter will then execute the next line and then return control to us
again.
.PP
Special check: if we're in package \f(CW\*(C`DB::fake\*(C'\fR, we've gone through the
\&\f(CW\*(C`END\*(C'\fR block at least once. We set up everything so that we can continue
to enter commands and have a valid context to be in.
.PP
If the program hasn't finished executing, we scan forward to the
next executable line, print that out, build the prompt from the file and line
number information, and print that.
.SS "sub"
.IX Subsection "sub"
\&\f(CW\*(C`sub\*(C'\fR is called whenever a subroutine call happens in the program being
debugged. The variable \f(CW$DB::sub\fR contains the name of the subroutine
being called.
.PP
The core function of this subroutine is to actually call the sub in the proper
context, capturing its output. This of course causes \f(CW\*(C`DB::DB\*(C'\fR to get called
again, repeating until the subroutine ends and returns control to \f(CW\*(C`DB::sub\*(C'\fR
again. Once control returns, \f(CW\*(C`DB::sub\*(C'\fR figures out whether or not to dump the
return value, and returns its captured copy of the return value as its own
return value. The value then feeds back into the program being debugged as if
\&\f(CW\*(C`DB::sub\*(C'\fR hadn't been there at all.
.PP
\&\f(CW\*(C`sub\*(C'\fR does all the work of printing the subroutine entry and exit messages
enabled by setting \f(CW$frame\fR. It notes what sub the autoloader got called for,
and also prints the return value if needed (for the \f(CW\*(C`r\*(C'\fR command and if
the 16 bit is set in \f(CW$frame\fR).
.PP
It also tracks the subroutine call depth by saving the current setting of
\&\f(CW$single\fR in the \f(CW@stack\fR package global; if this exceeds the value in
\&\f(CW$deep\fR, \f(CW\*(C`sub\*(C'\fR automatically turns on printing of the current depth by
setting the \f(CW4\fR bit in \f(CW$single\fR. In any case, it keeps the current setting
of stop/don't stop on entry to subs set as it currently is set.
.PP
\fI\f(CI\*(C`caller()\*(C'\fI support\fR
.IX Subsection "caller() support"
.PP
If \f(CW\*(C`caller()\*(C'\fR is called from the package \f(CW\*(C`DB\*(C'\fR, it provides some
additional data, in the following order:
.IP "\(bu" 4
\&\f(CW$package\fR
.Sp
The package name the sub was in
.IP "\(bu" 4
\&\f(CW$filename\fR
.Sp
The filename it was defined in
.IP "\(bu" 4
\&\f(CW$line\fR
.Sp
The line number it was defined on
.IP "\(bu" 4
\&\f(CW$subroutine\fR
.Sp
The subroutine name; \f(CW\*(C`(eval)\*(C'\fR if an \f(CW\*(C`eval\*(C'\fR().
.IP "\(bu" 4
\&\f(CW$hasargs\fR
.Sp
1 if it has arguments, 0 if not
.IP "\(bu" 4
\&\f(CW$wantarray\fR
.Sp
1 if array context, 0 if scalar context
.IP "\(bu" 4
\&\f(CW$evaltext\fR
.Sp
The \f(CW\*(C`eval\*(C'\fR() text, if any (undefined for \f(CW\*(C`eval BLOCK\*(C'\fR)
.IP "\(bu" 4
\&\f(CW$is_require\fR
.Sp
frame was created by a \f(CW\*(C`use\*(C'\fR or \f(CW\*(C`require\*(C'\fR statement
.IP "\(bu" 4
\&\f(CW$hints\fR
.Sp
pragma information; subject to change between versions
.IP "\(bu" 4
\&\f(CW$bitmask\fR
.Sp
pragma information; subject to change between versions
.IP "\(bu" 4
\&\f(CW@DB::args\fR
.Sp
arguments with which the subroutine was invoked
.SH "EXTENDED COMMAND HANDLING AND THE COMMAND API"
.IX Header "EXTENDED COMMAND HANDLING AND THE COMMAND API"
In Perl 5.8.0, there was a major realignment of the commands and what they did,
Most of the changes were to systematize the command structure and to eliminate
commands that threw away user input without checking.
.PP
The following sections describe the code added to make it easy to support
multiple command sets with conflicting command names. This section is a start
at unifying all command processing to make it simpler to develop commands.
.PP
Note that all the cmd_[a\-zA\-Z] subroutines require the command name, a line
number, and \f(CW$dbline\fR (the current line) as arguments.
.PP
Support functions in this section which have multiple modes of failure \f(CW\*(C`die\*(C'\fR
on error; the rest simply return a false value.
.PP
The user-interface functions (all of the \f(CW\*(C`cmd_*\*(C'\fR functions) just output
error messages.
.ie n .SS "%set"
.el .SS "\f(CW%set\fP"
.IX Subsection "%set"
The \f(CW%set\fR hash defines the mapping from command letter to subroutine
name suffix.
.PP
\&\f(CW%set\fR is a two-level hash, indexed by set name and then by command name.
Note that trying to set the CommandSet to \f(CW\*(C`foobar\*(C'\fR simply results in the
5.8.0 command set being used, since there's no top-level entry for \f(CW\*(C`foobar\*(C'\fR.
.ie n .SS """cmd_wrapper()"" (\s-1API\s0)"
.el .SS "\f(CWcmd_wrapper()\fP (\s-1API\s0)"
.IX Subsection "cmd_wrapper() (API)"
\&\f(CW\*(C`cmd_wrapper()\*(C'\fR allows the debugger to switch command sets
depending on the value of the \f(CW\*(C`CommandSet\*(C'\fR option.
.PP
It tries to look up the command in the \f(CW%set\fR package-level \fIlexical\fR
(which means external entities can't fiddle with it) and create the name of
the sub to call based on the value found in the hash (if it's there). \fIAll\fR
of the commands to be handled in a set have to be added to \f(CW%set\fR; if they
aren't found, the 5.8.0 equivalent is called (if there is one).
.PP
This code uses symbolic references.
.PP
\fI\f(CI\*(C`cmd_a\*(C'\fI (command)\fR
.IX Subsection "cmd_a (command)"
.PP
The \f(CW\*(C`a\*(C'\fR command handles pre-execution actions. These are associated with a
particular line, so they're stored in \f(CW%dbline\fR. We default to the current
line if none is specified.
.PP
\fI\f(CI\*(C`cmd_A\*(C'\fI (command)\fR
.IX Subsection "cmd_A (command)"
.PP
Delete actions. Similar to above, except the delete code is in a separate
subroutine, \f(CW\*(C`delete_action\*(C'\fR.
.PP
\fI\f(CI\*(C`delete_action\*(C'\fI (\s-1API\s0)\fR
.IX Subsection "delete_action (API)"
.PP
\&\f(CW\*(C`delete_action\*(C'\fR accepts either a line number or \f(CW\*(C`undef\*(C'\fR. If a line number
is specified, we check for the line being executable (if it's not, it
couldn't have had an  action). If it is, we just take the action off (this
will get any kind of an action, including breakpoints).
.PP
\fI\f(CI\*(C`cmd_b\*(C'\fI (command)\fR
.IX Subsection "cmd_b (command)"
.PP
Set breakpoints. Since breakpoints can be set in so many places, in so many
ways, conditionally or not, the breakpoint code is kind of complex. Mostly,
we try to parse the command type, and then shuttle it off to an appropriate
subroutine to actually do the work of setting the breakpoint in the right
place.
.PP
\fI\f(CI\*(C`break_on_load\*(C'\fI (\s-1API\s0)\fR
.IX Subsection "break_on_load (API)"
.PP
We want to break when this file is loaded. Mark this file in the
\&\f(CW%break_on_load\fR hash, and note that it has a breakpoint in
\&\f(CW%had_breakpoints\fR.
.PP
\fI\f(CI\*(C`report_break_on_load\*(C'\fI (\s-1API\s0)\fR
.IX Subsection "report_break_on_load (API)"
.PP
Gives us an array of filenames that are set to break on load. Note that
only files with break-on-load are in here, so simply showing the keys
suffices.
.PP
\fI\f(CI\*(C`cmd_b_load\*(C'\fI (command)\fR
.IX Subsection "cmd_b_load (command)"
.PP
We take the file passed in and try to find it in \f(CW%INC\fR (which maps modules
to files they came from). We mark those files for break-on-load via
\&\f(CW\*(C`break_on_load\*(C'\fR and then report that it was done.
.PP
\fI\f(CI$filename_error\fI (\s-1API\s0 package global)\fR
.IX Subsection "$filename_error (API package global)"
.PP
Several of the functions we need to implement in the \s-1API\s0 need to work both
on the current file and on other files. We don't want to duplicate code, so
\&\f(CW$filename_error\fR is used to contain the name of the file that's being
worked on (if it's not the current one).
.PP
We can now build functions in pairs: the basic function works on the current
file, and uses \f(CW$filename_error\fR as part of its error message. Since this is
initialized to \f(CW""\fR, no filename will appear when we are working on the
current file.
.PP
The second function is a wrapper which does the following:
.IP "\(bu" 4
Localizes \f(CW$filename_error\fR and sets it to the name of the file to be processed.
.IP "\(bu" 4
Localizes the \f(CW*dbline\fR glob and reassigns it to point to the file we want to process.
.IP "\(bu" 4
Calls the first function.
.Sp
The first function works on the \fIcurrent\fR file (i.e., the one we changed to),
and prints \f(CW$filename_error\fR in the error message (the name of the other file)
if it needs to. When the functions return, \f(CW*dbline\fR is restored to point
to the actual current file (the one we're executing in) and
\&\f(CW$filename_error\fR is restored to \f(CW""\fR. This restores everything to
the way it was before the second function was called at all.
.Sp
See the comments in \f(CW\*(C`sub breakable_line\*(C'\fR
and
\&\f(CW\*(C`sub breakable_line_in_filename\*(C'\fR
for more details.
.PP
\fIbreakable_line(from, to) (\s-1API\s0)\fR
.IX Subsection "breakable_line(from, to) (API)"
.PP
The subroutine decides whether or not a line in the current file is breakable.
It walks through \f(CW@dbline\fR within the range of lines specified, looking for
the first line that is breakable.
.PP
If \f(CW$to\fR is greater than \f(CW$from\fR, the search moves forwards, finding the
first line \fIafter\fR \f(CW$to\fR that's breakable, if there is one.
.PP
If \f(CW$from\fR is greater than \f(CW$to\fR, the search goes \fIbackwards\fR, finding the
first line \fIbefore\fR \f(CW$to\fR that's breakable, if there is one.
.PP
\fIbreakable_line_in_filename(file, from, to) (\s-1API\s0)\fR
.IX Subsection "breakable_line_in_filename(file, from, to) (API)"
.PP
Like \f(CW\*(C`breakable_line\*(C'\fR, but look in another file.
.PP
\fIbreak_on_line(lineno, [condition]) (\s-1API\s0)\fR
.IX Subsection "break_on_line(lineno, [condition]) (API)"
.PP
Adds a breakpoint with the specified condition (or 1 if no condition was
specified) to the specified line. Dies if it can't.
.PP
\fIcmd_b_line(line, [condition]) (command)\fR
.IX Subsection "cmd_b_line(line, [condition]) (command)"
.PP
Wrapper for \f(CW\*(C`break_on_line\*(C'\fR. Prints the failure message if it
doesn't work.
.PP
\fIcmd_b_filename_line(line, [condition]) (command)\fR
.IX Subsection "cmd_b_filename_line(line, [condition]) (command)"
.PP
Wrapper for \f(CW\*(C`break_on_filename_line\*(C'\fR. Prints the failure message if it
doesn't work.
.PP
\fIbreak_on_filename_line(file, line, [condition]) (\s-1API\s0)\fR
.IX Subsection "break_on_filename_line(file, line, [condition]) (API)"
.PP
Switches to the file specified and then calls \f(CW\*(C`break_on_line\*(C'\fR to set
the breakpoint.
.PP
\fIbreak_on_filename_line_range(file, from, to, [condition]) (\s-1API\s0)\fR
.IX Subsection "break_on_filename_line_range(file, from, to, [condition]) (API)"
.PP
Switch to another file, search the range of lines specified for an
executable one, and put a breakpoint on the first one you find.
.PP
\fIsubroutine_filename_lines(subname, [condition]) (\s-1API\s0)\fR
.IX Subsection "subroutine_filename_lines(subname, [condition]) (API)"
.PP
Search for a subroutine within a given file. The condition is ignored.
Uses \f(CW\*(C`find_sub\*(C'\fR to locate the desired subroutine.
.PP
\fIbreak_subroutine(subname) (\s-1API\s0)\fR
.IX Subsection "break_subroutine(subname) (API)"
.PP
Places a break on the first line possible in the specified subroutine. Uses
\&\f(CW\*(C`subroutine_filename_lines\*(C'\fR to find the subroutine, and
\&\f(CW\*(C`break_on_filename_line_range\*(C'\fR to place the break.
.PP
\fIcmd_b_sub(subname, [condition]) (command)\fR
.IX Subsection "cmd_b_sub(subname, [condition]) (command)"
.PP
We take the incoming subroutine name and fully-qualify it as best we can.
.IP "1. If it's already fully-qualified, leave it alone." 4
.IX Item "1. If it's already fully-qualified, leave it alone."
.PD 0
.IP "2. Try putting it in the current package." 4
.IX Item "2. Try putting it in the current package."
.IP "3. If it's not there, try putting it in \s-1CORE::GLOBAL\s0 if it exists there." 4
.IX Item "3. If it's not there, try putting it in CORE::GLOBAL if it exists there."
.IP "4. If it starts with '::', put it in 'main::'." 4
.IX Item "4. If it starts with '::', put it in 'main::'."
.PD
.PP
After all this cleanup, we call \f(CW\*(C`break_subroutine\*(C'\fR to try to set the
breakpoint.
.PP
\fI\f(CI\*(C`cmd_B\*(C'\fI \- delete breakpoint(s) (command)\fR
.IX Subsection "cmd_B - delete breakpoint(s) (command)"
.PP
The command mostly parses the command line and tries to turn the argument
into a line spec. If it can't, it uses the current line. It then calls
\&\f(CW\*(C`delete_breakpoint\*(C'\fR to actually do the work.
.PP
If \f(CW\*(C`*\*(C'\fR is  specified, \f(CW\*(C`cmd_B\*(C'\fR calls \f(CW\*(C`delete_breakpoint\*(C'\fR with no arguments,
thereby deleting all the breakpoints.
.PP
\fIdelete_breakpoint([line]) (\s-1API\s0)\fR
.IX Subsection "delete_breakpoint([line]) (API)"
.PP
This actually does the work of deleting either a single breakpoint, or all
of them.
.PP
For a single line, we look for it in \f(CW@dbline\fR. If it's nonbreakable, we
just drop out with a message saying so. If it is, we remove the condition
part of the 'condition\e0action' that says there's a breakpoint here. If,
after we've done that, there's nothing left, we delete the corresponding
line in \f(CW%dbline\fR to signal that no action needs to be taken for this line.
.PP
For all breakpoints, we iterate through the keys of \f(CW%had_breakpoints\fR,
which lists all currently-loaded files which have breakpoints. We then look
at each line in each of these files, temporarily switching the \f(CW%dbline\fR
and \f(CW@dbline\fR structures to point to the files in question, and do what
we did in the single line case: delete the condition in \f(CW@dbline\fR, and
delete the key in \f(CW%dbline\fR if nothing's left.
.PP
We then wholesale delete \f(CW%postponed\fR, \f(CW%postponed_file\fR, and
\&\f(CW%break_on_load\fR, because these structures contain breakpoints for files
and code that haven't been loaded yet. We can just kill these off because there
are no magical debugger structures associated with them.
.PP
\fIcmd_stop (command)\fR
.IX Subsection "cmd_stop (command)"
.PP
This is meant to be part of the new command \s-1API,\s0 but it isn't called or used
anywhere else in the debugger. \s-1XXX\s0 It is probably meant for use in development
of new commands.
.PP
\fI\f(CI\*(C`cmd_e\*(C'\fI \- threads\fR
.IX Subsection "cmd_e - threads"
.PP
Display the current thread id:
.PP
.Vb 1
\&    e
.Ve
.PP
This could be how (when implemented) to send commands to this thread id (e cmd)
or that thread id (e tid cmd).
.PP
\fI\f(CI\*(C`cmd_E\*(C'\fI \- list of thread ids\fR
.IX Subsection "cmd_E - list of thread ids"
.PP
Display the list of available thread ids:
.PP
.Vb 1
\&    E
.Ve
.PP
This could be used (when implemented) to send commands to all threads (E cmd).
.PP
\fI\f(CI\*(C`cmd_h\*(C'\fI \- help command (command)\fR
.IX Subsection "cmd_h - help command (command)"
.PP
Does the work of either
.IP "\(bu" 4
Showing all the debugger help
.IP "\(bu" 4
Showing help for a specific command
.PP
\fI\f(CI\*(C`cmd_L\*(C'\fI \- list breakpoints, actions, and watch expressions (command)\fR
.IX Subsection "cmd_L - list breakpoints, actions, and watch expressions (command)"
.PP
To list breakpoints, the command has to look determine where all of them are
first. It starts a \f(CW%had_breakpoints\fR, which tells us what all files have
breakpoints and/or actions. For each file, we switch the \f(CW*dbline\fR glob (the
magic source and breakpoint data structures) to the file, and then look
through \f(CW%dbline\fR for lines with breakpoints and/or actions, listing them
out. We look through \f(CW%postponed\fR not-yet-compiled subroutines that have
breakpoints, and through \f(CW%postponed_file\fR for not\-yet\-\f(CW\*(C`require\*(C'\fR'd files
that have breakpoints.
.PP
Watchpoints are simpler: we just list the entries in \f(CW@to_watch\fR.
.PP
\fI\f(CI\*(C`cmd_M\*(C'\fI \- list modules (command)\fR
.IX Subsection "cmd_M - list modules (command)"
.PP
Just call \f(CW\*(C`list_modules\*(C'\fR.
.PP
\fI\f(CI\*(C`cmd_o\*(C'\fI \- options (command)\fR
.IX Subsection "cmd_o - options (command)"
.PP
If this is just \f(CW\*(C`o\*(C'\fR by itself, we list the current settings via
\&\f(CW\*(C`dump_option\*(C'\fR. If there's a nonblank value following it, we pass that on to
\&\f(CW\*(C`parse_options\*(C'\fR for processing.
.PP
\fI\f(CI\*(C`cmd_O\*(C'\fI \- nonexistent in 5.8.x (command)\fR
.IX Subsection "cmd_O - nonexistent in 5.8.x (command)"
.PP
Advises the user that the O command has been renamed.
.PP
\fI\f(CI\*(C`cmd_v\*(C'\fI \- view window (command)\fR
.IX Subsection "cmd_v - view window (command)"
.PP
Uses the \f(CW$preview\fR variable set in the second \f(CW\*(C`BEGIN\*(C'\fR block (q.v.) to
move back a few lines to list the selected line in context. Uses \f(CW\*(C`_cmd_l_main\*(C'\fR
to do the actual listing after figuring out the range of line to request.
.PP
\fI\f(CI\*(C`cmd_w\*(C'\fI \- add a watch expression (command)\fR
.IX Subsection "cmd_w - add a watch expression (command)"
.PP
The 5.8 version of this command adds a watch expression if one is specified;
it does nothing if entered with no operands.
.PP
We extract the expression, save it, evaluate it in the user's context, and
save the value. We'll re-evaluate it each time the debugger passes a line,
and will stop (see the code at the top of the command loop) if the value
of any of the expressions changes.
.PP
\fI\f(CI\*(C`cmd_W\*(C'\fI \- delete watch expressions (command)\fR
.IX Subsection "cmd_W - delete watch expressions (command)"
.PP
This command accepts either a watch expression to be removed from the list
of watch expressions, or \f(CW\*(C`*\*(C'\fR to delete them all.
.PP
If \f(CW\*(C`*\*(C'\fR is specified, we simply empty the watch expression list and the
watch expression value list. We also turn off the bit that says we've got
watch expressions.
.PP
If an expression (or partial expression) is specified, we pattern-match
through the expressions and remove the ones that match. We also discard
the corresponding values. If no watch expressions are left, we turn off
the \fIwatching expressions\fR bit.
.SH "SUPPORT ROUTINES"
.IX Header "SUPPORT ROUTINES"
These are general support routines that are used in a number of places
throughout the debugger.
.SS "save"
.IX Subsection "save"
\&\fBsave()\fR saves the user's versions of globals that would mess us up in \f(CW@saved\fR,
and installs the versions we like better.
.ie n .SS """print_lineinfo"" \- show where we are now"
.el .SS "\f(CWprint_lineinfo\fP \- show where we are now"
.IX Subsection "print_lineinfo - show where we are now"
print_lineinfo prints whatever it is that it is handed; it prints it to the
\&\f(CW$LINEINFO\fR filehandle instead of just printing it to \s-1STDOUT.\s0 This allows
us to feed line information to a client editor without messing up the
debugger output.
.ie n .SS """postponed_sub"""
.el .SS "\f(CWpostponed_sub\fP"
.IX Subsection "postponed_sub"
Handles setting postponed breakpoints in subroutines once they're compiled.
For breakpoints, we use \f(CW\*(C`DB::find_sub\*(C'\fR to locate the source file and line
range for the subroutine, then mark the file as having a breakpoint,
temporarily switch the \f(CW*dbline\fR glob over to the source file, and then
search the given range of lines to find a breakable line. If we find one,
we set the breakpoint on it, deleting the breakpoint from \f(CW%postponed\fR.
.ie n .SS """postponed"""
.el .SS "\f(CWpostponed\fP"
.IX Subsection "postponed"
Called after each required file is compiled, but before it is executed;
also called if the name of a just-compiled subroutine is a key of
\&\f(CW%postponed\fR. Propagates saved breakpoints (from \f(CW\*(C`b compile\*(C'\fR,
\&\f(CW\*(C`b load\*(C'\fR, etc.) into the just-compiled code.
.PP
If this is a \f(CW\*(C`require\*(C'\fR'd file, the incoming parameter is the glob
\&\f(CW\*(C`*{"_<$filename"}\*(C'\fR, with \f(CW$filename\fR the name of the \f(CW\*(C`require\*(C'\fR'd file.
.PP
If it's a subroutine, the incoming parameter is the subroutine name.
.ie n .SS """dumpit"""
.el .SS "\f(CWdumpit\fP"
.IX Subsection "dumpit"
\&\f(CW\*(C`dumpit\*(C'\fR is the debugger's wrapper around dumpvar.pl.
.PP
It gets a filehandle (to which \f(CW\*(C`dumpvar.pl\*(C'\fR's output will be directed) and
a reference to a variable (the thing to be dumped) as its input.
.PP
The incoming filehandle is selected for output (\f(CW\*(C`dumpvar.pl\*(C'\fR is printing to
the currently-selected filehandle, thank you very much). The current
values of the package globals \f(CW$single\fR and \f(CW$trace\fR are backed up in
lexicals, and they are turned off (this keeps the debugger from trying
to single-step through \f(CW\*(C`dumpvar.pl\*(C'\fR (I think.)). \f(CW$frame\fR is localized to
preserve its current value and it is set to zero to prevent entry/exit
messages from printing, and \f(CW$doret\fR is localized as well and set to \-2 to
prevent return values from being shown.
.PP
\&\f(CW\*(C`dumpit()\*(C'\fR then checks to see if it needs to load \f(CW\*(C`dumpvar.pl\*(C'\fR and
tries to load it (note: if you have a \f(CW\*(C`dumpvar.pl\*(C'\fR  ahead of the
installed version in \f(CW@INC\fR, yours will be used instead. Possible security
problem?).
.PP
It then checks to see if the subroutine \f(CW\*(C`main::dumpValue\*(C'\fR is now defined
it should have been defined by \f(CW\*(C`dumpvar.pl\*(C'\fR). If it has, \f(CW\*(C`dumpit()\*(C'\fR
localizes the globals necessary for things to be sane when \f(CW\*(C`main::dumpValue()\*(C'\fR
is called, and picks up the variable to be dumped from the parameter list.
.PP
It checks the package global \f(CW%options\fR to see if there's a \f(CW\*(C`dumpDepth\*(C'\fR
specified. If not, \-1 is assumed; if so, the supplied value gets passed on to
\&\f(CW\*(C`dumpvar.pl\*(C'\fR. This tells \f(CW\*(C`dumpvar.pl\*(C'\fR where to leave off when dumping a
structure: \-1 means dump everything.
.PP
\&\f(CW\*(C`dumpValue()\*(C'\fR is then called if possible; if not, \f(CW\*(C`dumpit()\*(C'\fRjust prints a
warning.
.PP
In either case, \f(CW$single\fR, \f(CW$trace\fR, \f(CW$frame\fR, and \f(CW$doret\fR are restored
and we then return to the caller.
.ie n .SS """print_trace"""
.el .SS "\f(CWprint_trace\fP"
.IX Subsection "print_trace"
\&\f(CW\*(C`print_trace\*(C'\fR's job is to print a stack trace. It does this via the
\&\f(CW\*(C`dump_trace\*(C'\fR routine, which actually does all the ferreting-out of the
stack trace data. \f(CW\*(C`print_trace\*(C'\fR takes care of formatting it nicely and
printing it to the proper filehandle.
.PP
Parameters:
.IP "\(bu" 4
The filehandle to print to.
.IP "\(bu" 4
How many frames to skip before starting trace.
.IP "\(bu" 4
How many frames to print.
.IP "\(bu" 4
A flag: if true, print a \fIshort\fR trace without filenames, line numbers, or arguments
.PP
The original comment below seems to be noting that the traceback may not be
correct if this routine is called in a tied method.
.SS "dump_trace(skip[,count])"
.IX Subsection "dump_trace(skip[,count])"
Actually collect the traceback information available via \f(CW\*(C`caller()\*(C'\fR. It does
some filtering and cleanup of the data, but mostly it just collects it to
make \f(CW\*(C`print_trace()\*(C'\fR's job easier.
.PP
\&\f(CW\*(C`skip\*(C'\fR defines the number of stack frames to be skipped, working backwards
from the most current. \f(CW\*(C`count\*(C'\fR determines the total number of frames to
be returned; all of them (well, the first 10^9) are returned if \f(CW\*(C`count\*(C'\fR
is omitted.
.PP
This routine returns a list of hashes, from most-recent to least-recent
stack frame. Each has the following keys and values:
.IP "\(bu" 4
\&\f(CW\*(C`context\*(C'\fR \- \f(CW\*(C`.\*(C'\fR (null), \f(CW\*(C`$\*(C'\fR (scalar), or \f(CW\*(C`@\*(C'\fR (array)
.IP "\(bu" 4
\&\f(CW\*(C`sub\*(C'\fR \- subroutine name, or \f(CW\*(C`eval\*(C'\fR information
.IP "\(bu" 4
\&\f(CW\*(C`args\*(C'\fR \- undef, or a reference to an array of arguments
.IP "\(bu" 4
\&\f(CW\*(C`file\*(C'\fR \- the file in which this item was defined (if any)
.IP "\(bu" 4
\&\f(CW\*(C`line\*(C'\fR \- the line on which it was defined
.ie n .SS """action()"""
.el .SS "\f(CWaction()\fP"
.IX Subsection "action()"
\&\f(CW\*(C`action()\*(C'\fR takes input provided as the argument to an add-action command,
either pre\- or post\-, and makes sure it's a complete command. It doesn't do
any fancy parsing; it just keeps reading input until it gets a string
without a trailing backslash.
.SS "unbalanced"
.IX Subsection "unbalanced"
This routine mostly just packages up a regular expression to be used
to check that the thing it's being matched against has properly-matched
curly braces.
.PP
Of note is the definition of the \f(CW$balanced_brace_re\fR global via \f(CW\*(C`||=\*(C'\fR, which
speeds things up by only creating the qr//'ed expression once; if it's
already defined, we don't try to define it again. A speed hack.
.ie n .SS """gets()"""
.el .SS "\f(CWgets()\fP"
.IX Subsection "gets()"
\&\f(CW\*(C`gets()\*(C'\fR is a primitive (very primitive) routine to read continuations.
It was devised for reading continuations for actions.
it just reads more input with \f(CW\*(C`readline()\*(C'\fR and returns it.
.ie n .SS """_db_system()"" \- handle calls to<\fBsystem()\fP> without messing up the debugger"
.el .SS "\f(CW_db_system()\fP \- handle calls to<\fBsystem()\fP> without messing up the debugger"
.IX Subsection "_db_system() - handle calls to<system()> without messing up the debugger"
The \f(CW\*(C`system()\*(C'\fR function assumes that it can just go ahead and use \s-1STDIN\s0 and
\&\s-1STDOUT,\s0 but under the debugger, we want it to use the debugger's input and
outout filehandles.
.PP
\&\f(CW\*(C`_db_system()\*(C'\fR socks away the program's \s-1STDIN\s0 and \s-1STDOUT,\s0 and then substitutes
the debugger's \s-1IN\s0 and \s-1OUT\s0 filehandles for them. It does the \f(CW\*(C`system()\*(C'\fR call,
and then puts everything back again.
.SH "TTY MANAGEMENT"
.IX Header "TTY MANAGEMENT"
The subs here do some of the terminal management for multiple debuggers.
.SS "setterm"
.IX Subsection "setterm"
Top-level function called when we want to set up a new terminal for use
by the debugger.
.PP
If the \f(CW\*(C`noTTY\*(C'\fR debugger option was set, we'll either use the terminal
supplied (the value of the \f(CW\*(C`noTTY\*(C'\fR option), or we'll use \f(CW\*(C`Term::Rendezvous\*(C'\fR
to find one. If we're a forked debugger, we call \f(CW\*(C`resetterm\*(C'\fR to try to
get a whole new terminal if we can.
.PP
In either case, we set up the terminal next. If the \f(CW\*(C`ReadLine\*(C'\fR option was
true, we'll get a \f(CW\*(C`Term::ReadLine\*(C'\fR object for the current terminal and save
the appropriate attributes. We then
.SH "GET_FORK_TTY EXAMPLE FUNCTIONS"
.IX Header "GET_FORK_TTY EXAMPLE FUNCTIONS"
When the process being debugged forks, or the process invokes a command
via \f(CW\*(C`system()\*(C'\fR which starts a new debugger, we need to be able to get a new
\&\f(CW\*(C`IN\*(C'\fR and \f(CW\*(C`OUT\*(C'\fR filehandle for the new debugger. Otherwise, the two processes
fight over the terminal, and you can never quite be sure who's going to get the
input you're typing.
.PP
\&\f(CW\*(C`get_fork_TTY\*(C'\fR is a glob-aliased function which calls the real function that
is tasked with doing all the necessary operating system mojo to get a new
\&\s-1TTY\s0 (and probably another window) and to direct the new debugger to read and
write there.
.PP
The debugger provides \f(CW\*(C`get_fork_TTY\*(C'\fR functions which work for \s-1TCP\s0
socket servers, X11, \s-1OS/2,\s0 and Mac \s-1OS X.\s0 Other systems are not
supported. You are encouraged to write \f(CW\*(C`get_fork_TTY\*(C'\fR functions which
work for \fIyour\fR platform and contribute them.
.PP
\fI\f(CI\*(C`socket_get_fork_TTY\*(C'\fI\fR
.IX Subsection "socket_get_fork_TTY"
.PP
\fI\f(CI\*(C`xterm_get_fork_TTY\*(C'\fI\fR
.IX Subsection "xterm_get_fork_TTY"
.PP
This function provides the \f(CW\*(C`get_fork_TTY\*(C'\fR function for X11. If a
program running under the debugger forks, a new <xterm> window is opened and
the subsidiary debugger is directed there.
.PP
The \f(CW\*(C`open()\*(C'\fR call is of particular note here. We have the new \f(CW\*(C`xterm\*(C'\fR
we're spawning route file number 3 to \s-1STDOUT,\s0 and then execute the \f(CW\*(C`tty\*(C'\fR
command (which prints the device name of the \s-1TTY\s0 we'll want to use for input
and output to \s-1STDOUT,\s0 then \f(CW\*(C`sleep\*(C'\fR for a very long time, routing this output
to file number 3. This way we can simply read from the <\s-1XT\s0> filehandle (which
is \s-1STDOUT\s0 from the \fIcommands\fR we ran) to get the \s-1TTY\s0 we want to use.
.PP
Only works if \f(CW\*(C`xterm\*(C'\fR is in your path and \f(CW$ENV{DISPLAY}\fR, etc. are
properly set up.
.PP
\fI\f(CI\*(C`os2_get_fork_TTY\*(C'\fI\fR
.IX Subsection "os2_get_fork_TTY"
.PP
\&\s-1XXX\s0 It behooves an \s-1OS/2\s0 expert to write the necessary documentation for this!
.PP
\fI\f(CI\*(C`macosx_get_fork_TTY\*(C'\fI\fR
.IX Subsection "macosx_get_fork_TTY"
.PP
The Mac \s-1OS X\s0 version uses AppleScript to tell Terminal.app to create
a new window.
.PP
\fI\f(CI\*(C`tmux_get_fork_TTY\*(C'\fI\fR
.IX Subsection "tmux_get_fork_TTY"
.PP
Creates a split window for subprocesses when a process running under the
perl debugger in Tmux forks.
.ie n .SS """create_IN_OUT($flags)"""
.el .SS "\f(CWcreate_IN_OUT($flags)\fP"
.IX Subsection "create_IN_OUT($flags)"
Create a new pair of filehandles, pointing to a new \s-1TTY.\s0 If impossible,
try to diagnose why.
.PP
Flags are:
.IP "\(bu" 4
1 \- Don't know how to create a new \s-1TTY.\s0
.IP "\(bu" 4
2 \- Debugger has forked, but we can't get a new \s-1TTY.\s0
.IP "\(bu" 4
4 \- standard debugger startup is happening.
.ie n .SS """resetterm"""
.el .SS "\f(CWresetterm\fP"
.IX Subsection "resetterm"
Handles rejiggering the prompt when we've forked off a new debugger.
.PP
If the new debugger happened because of a \f(CW\*(C`system()\*(C'\fR that invoked a
program under the debugger, the arrow between the old pid and the new
in the prompt has \fItwo\fR dashes instead of one.
.PP
We take the current list of pids and add this one to the end. If there
isn't any list yet, we make one up out of the initial pid associated with
the terminal and our new pid, sticking an arrow (either one-dashed or
two dashed) in between them.
.PP
If \f(CW\*(C`CreateTTY\*(C'\fR is off, or \f(CW\*(C`resetterm\*(C'\fR was called with no arguments,
we don't try to create a new \s-1IN\s0 and \s-1OUT\s0 filehandle. Otherwise, we go ahead
and try to do that.
.ie n .SS """readline"""
.el .SS "\f(CWreadline\fP"
.IX Subsection "readline"
First, we handle stuff in the typeahead buffer. If there is any, we shift off
the next line, print a message saying we got it, add it to the terminal
history (if possible), and return it.
.PP
If there's nothing in the typeahead buffer, check the command filehandle stack.
If there are any filehandles there, read from the last one, and return the line
if we got one. If not, we pop the filehandle off and close it, and try the
next one up the stack.
.PP
If we've emptied the filehandle stack, we check to see if we've got a socket
open, and we read that and return it if we do. If we don't, we just call the
core \f(CW\*(C`readline()\*(C'\fR and return its value.
.SH "OPTIONS SUPPORT ROUTINES"
.IX Header "OPTIONS SUPPORT ROUTINES"
These routines handle listing and setting option values.
.ie n .SS """dump_option"" \- list the current value of an option setting"
.el .SS "\f(CWdump_option\fP \- list the current value of an option setting"
.IX Subsection "dump_option - list the current value of an option setting"
This routine uses \f(CW\*(C`option_val\*(C'\fR to look up the value for an option.
It cleans up escaped single-quotes and then displays the option and
its value.
.ie n .SS """option_val"" \- find the current value of an option"
.el .SS "\f(CWoption_val\fP \- find the current value of an option"
.IX Subsection "option_val - find the current value of an option"
This can't just be a simple hash lookup because of the indirect way that
the option values are stored. Some are retrieved by calling a subroutine,
some are just variables.
.PP
You must supply a default value to be used in case the option isn't set.
.ie n .SS """parse_options"""
.el .SS "\f(CWparse_options\fP"
.IX Subsection "parse_options"
Handles the parsing and execution of option setting/displaying commands.
.PP
An option entered by itself is assumed to be \fIset me to 1\fR (the default value)
if the option is a boolean one. If not, the user is prompted to enter a valid
value or to query the current value (via \f(CW\*(C`option? \*(C'\fR).
.PP
If \f(CW\*(C`option=value\*(C'\fR is entered, we try to extract a quoted string from the
value (if it is quoted). If it's not, we just use the whole value as-is.
.PP
We load any modules required to service this option, and then we set it: if
it just gets stuck in a variable, we do that; if there's a subroutine to
handle setting the option, we call that.
.PP
Finally, if we're running in interactive mode, we display the effect of the
user's command back to the terminal, skipping this if we're setting things
during initialization.
.SH "RESTART SUPPORT"
.IX Header "RESTART SUPPORT"
These routines are used to store (and restore) lists of items in environment
variables during a restart.
.SS "set_list"
.IX Subsection "set_list"
Set_list packages up items to be stored in a set of environment variables
(VAR_n, containing the number of items, and \s-1VAR_0, VAR_1,\s0 etc., containing
the values). Values outside the standard \s-1ASCII\s0 charset are stored by encoding
them as hexadecimal values.
.SS "get_list"
.IX Subsection "get_list"
Reverse the set_list operation: grab VAR_n to see how many we should be getting
back, and then pull \s-1VAR_0, VAR_1.\s0 etc. back out.
.SH "MISCELLANEOUS SIGNAL AND I/O MANAGEMENT"
.IX Header "MISCELLANEOUS SIGNAL AND I/O MANAGEMENT"
.SS "\fBcatch()\fP"
.IX Subsection "catch()"
The \f(CW\*(C`catch()\*(C'\fR subroutine is the essence of fast and low-impact. We simply
set an already-existing global scalar variable to a constant value. This
avoids allocating any memory possibly in the middle of something that will
get all confused if we do, particularly under \fIunsafe signals\fR.
.ie n .SS """warn()"""
.el .SS "\f(CWwarn()\fP"
.IX Subsection "warn()"
\&\f(CW\*(C`warn\*(C'\fR emits a warning, by joining together its arguments and printing
them, with couple of fillips.
.PP
If the composited message \fIdoesn't\fR end with a newline, we automatically
add \f(CW$!\fR and a newline to the end of the message. The subroutine expects \f(CW$OUT\fR
to be set to the filehandle to be used to output warnings; it makes no
assumptions about what filehandles are available.
.SH "INITIALIZATION TTY SUPPORT"
.IX Header "INITIALIZATION TTY SUPPORT"
.ie n .SS """reset_IN_OUT"""
.el .SS "\f(CWreset_IN_OUT\fP"
.IX Subsection "reset_IN_OUT"
This routine handles restoring the debugger's input and output filehandles
after we've tried and failed to move them elsewhere.  In addition, it assigns
the debugger's output filehandle to \f(CW$LINEINFO\fR if it was already open there.
.SH "OPTION SUPPORT ROUTINES"
.IX Header "OPTION SUPPORT ROUTINES"
The following routines are used to process some of the more complicated
debugger options.
.ie n .SS """TTY"""
.el .SS "\f(CWTTY\fP"
.IX Subsection "TTY"
Sets the input and output filehandles to the specified files or pipes.
If the terminal supports switching, we go ahead and do it. If not, and
there's already a terminal in place, we save the information to take effect
on restart.
.PP
If there's no terminal yet (for instance, during debugger initialization),
we go ahead and set \f(CW$console\fR and \f(CW$tty\fR to the file indicated.
.ie n .SS """noTTY"""
.el .SS "\f(CWnoTTY\fP"
.IX Subsection "noTTY"
Sets the \f(CW$notty\fR global, controlling whether or not the debugger tries to
get a terminal to read from. If called after a terminal is already in place,
we save the value to use it if we're restarted.
.ie n .SS """ReadLine"""
.el .SS "\f(CWReadLine\fP"
.IX Subsection "ReadLine"
Sets the \f(CW$rl\fR option variable. If 0, we use \f(CW\*(C`Term::ReadLine::Stub\*(C'\fR
(essentially, no \f(CW\*(C`readline\*(C'\fR processing on this \fIterminal\fR). Otherwise, we
use \f(CW\*(C`Term::ReadLine\*(C'\fR. Can't be changed after a terminal's in place; we save
the value in case a restart is done so we can change it then.
.ie n .SS """RemotePort"""
.el .SS "\f(CWRemotePort\fP"
.IX Subsection "RemotePort"
Sets the port that the debugger will try to connect to when starting up.
If the terminal's already been set up, we can't do it, but we remember the
setting in case the user does a restart.
.ie n .SS """tkRunning"""
.el .SS "\f(CWtkRunning\fP"
.IX Subsection "tkRunning"
Checks with the terminal to see if \f(CW\*(C`Tk\*(C'\fR is running, and returns true or
false. Returns false if the current terminal doesn't support \f(CW\*(C`readline\*(C'\fR.
.ie n .SS """NonStop"""
.el .SS "\f(CWNonStop\fP"
.IX Subsection "NonStop"
Sets nonstop mode. If a terminal's already been set up, it's too late; the
debugger remembers the setting in case you restart, though.
.ie n .SS """pager"""
.el .SS "\f(CWpager\fP"
.IX Subsection "pager"
Set up the \f(CW$pager\fR variable. Adds a pipe to the front unless there's one
there already.
.ie n .SS """shellBang"""
.el .SS "\f(CWshellBang\fP"
.IX Subsection "shellBang"
Sets the shell escape command, and generates a printable copy to be used
in the help.
.ie n .SS """ornaments"""
.el .SS "\f(CWornaments\fP"
.IX Subsection "ornaments"
If the terminal has its own ornaments, fetch them. Otherwise accept whatever
was passed as the argument. (This means you can't override the terminal's
ornaments.)
.ie n .SS """recallCommand"""
.el .SS "\f(CWrecallCommand\fP"
.IX Subsection "recallCommand"
Sets the recall command, and builds a printable version which will appear in
the help text.
.ie n .SS """LineInfo"" \- where the line number information goes"
.el .SS "\f(CWLineInfo\fP \- where the line number information goes"
.IX Subsection "LineInfo - where the line number information goes"
Called with no arguments, returns the file or pipe that line info should go to.
.PP
Called with an argument (a file or a pipe), it opens that onto the
\&\f(CW\*(C`LINEINFO\*(C'\fR filehandle, unbuffers the filehandle, and then returns the
file or pipe again to the caller.
.SH "COMMAND SUPPORT ROUTINES"
.IX Header "COMMAND SUPPORT ROUTINES"
These subroutines provide functionality for various commands.
.ie n .SS """list_modules"""
.el .SS "\f(CWlist_modules\fP"
.IX Subsection "list_modules"
For the \f(CW\*(C`M\*(C'\fR command: list modules loaded and their versions.
Essentially just runs through the keys in \f(CW%INC\fR, picks each package's
\&\f(CW$VERSION\fR variable, gets the file name, and formats the information
for output.
.ie n .SS """sethelp()"""
.el .SS "\f(CWsethelp()\fP"
.IX Subsection "sethelp()"
Sets up the monster string used to format and print the help.
.PP
\fI\s-1HELP MESSAGE FORMAT\s0\fR
.IX Subsection "HELP MESSAGE FORMAT"
.PP
The help message is a peculiar format unto itself; it mixes \f(CW\*(C`pod\*(C'\fR \fIornaments\fR
(\f(CW\*(C`\f(CB\f(CW\*(C'\fR \f(CW\*(C`\f(CI\f(CW\*(C'\fR) with tabs to come up with a format that's fairly
easy to parse and portable, but which still allows the help to be a little
nicer than just plain text.
.PP
Essentially, you define the command name (usually marked up with \f(CW\*(C`\f(CB\f(CW\*(C'\fR
and \f(CW\*(C`\f(CI\f(CW\*(C'\fR), followed by a tab, and then the descriptive text, ending in a
newline. The descriptive text can also be marked up in the same way. If you
need to continue the descriptive text to another line, start that line with
just tabs and then enter the marked-up text.
.PP
If you are modifying the help text, \fIbe careful\fR. The help-string parser is
not very sophisticated, and if you don't follow these rules it will mangle the
help beyond hope until you fix the string.
.ie n .SS """print_help()"""
.el .SS "\f(CWprint_help()\fP"
.IX Subsection "print_help()"
Most of what \f(CW\*(C`print_help\*(C'\fR does is just text formatting. It finds the
\&\f(CW\*(C`B\*(C'\fR and \f(CW\*(C`I\*(C'\fR ornaments, cleans them off, and substitutes the proper
terminal control characters to simulate them (courtesy of
\&\f(CW\*(C`Term::ReadLine::TermCap\*(C'\fR).
.ie n .SS """fix_less"""
.el .SS "\f(CWfix_less\fP"
.IX Subsection "fix_less"
This routine does a lot of gyrations to be sure that the pager is \f(CW\*(C`less\*(C'\fR.
It checks for \f(CW\*(C`less\*(C'\fR masquerading as \f(CW\*(C`more\*(C'\fR and records the result in
\&\f(CW$fixed_less\fR so we don't have to go through doing the stats again.
.SH "DIE AND WARN MANAGEMENT"
.IX Header "DIE AND WARN MANAGEMENT"
.ie n .SS """diesignal"""
.el .SS "\f(CWdiesignal\fP"
.IX Subsection "diesignal"
\&\f(CW\*(C`diesignal\*(C'\fR is a just-drop-dead \f(CW\*(C`die\*(C'\fR handler. It's most useful when trying
to debug a debugger problem.
.PP
It does its best to report the error that occurred, and then forces the
program, debugger, and everything to die.
.ie n .SS """dbwarn"""
.el .SS "\f(CWdbwarn\fP"
.IX Subsection "dbwarn"
The debugger's own default \f(CW$SIG{_\|_WARN_\|_}\fR handler. We load \f(CW\*(C`Carp\*(C'\fR to
be able to get a stack trace, and output the warning message vi \f(CW\*(C`DB::dbwarn()\*(C'\fR.
.ie n .SS """dbdie"""
.el .SS "\f(CWdbdie\fP"
.IX Subsection "dbdie"
The debugger's own \f(CW$SIG{_\|_DIE_\|_}\fR handler. Handles providing a stack trace
by loading \f(CW\*(C`Carp\*(C'\fR and calling \f(CW\*(C`Carp::longmess()\*(C'\fR to get it. We turn off
single stepping and tracing during the call to \f(CW\*(C`Carp::longmess\*(C'\fR to avoid
debugging it \- we just want to use it.
.PP
If \f(CW\*(C`dieLevel\*(C'\fR is zero, we let the program being debugged handle the
exceptions. If it's 1, you get backtraces for any exception. If it's 2,
the debugger takes over all exception handling, printing a backtrace and
displaying the exception via its \f(CW\*(C`dbwarn()\*(C'\fR routine.
.ie n .SS """warnlevel()"""
.el .SS "\f(CWwarnlevel()\fP"
.IX Subsection "warnlevel()"
Set the \f(CW$DB::warnLevel\fR variable that stores the value of the
\&\f(CW\*(C`warnLevel\*(C'\fR option. Calling \f(CW\*(C`warnLevel()\*(C'\fR with a positive value
results in the debugger taking over all warning handlers. Setting
\&\f(CW\*(C`warnLevel\*(C'\fR to zero leaves any warning handlers set up by the program
being debugged in place.
.ie n .SS """dielevel"""
.el .SS "\f(CWdielevel\fP"
.IX Subsection "dielevel"
Similar to \f(CW\*(C`warnLevel\*(C'\fR. Non-zero values for \f(CW\*(C`dieLevel\*(C'\fR result in the
\&\f(CW\*(C`DB::dbdie()\*(C'\fR function overriding any other \f(CW\*(C`die()\*(C'\fR handler. Setting it to
zero lets you use your own \f(CW\*(C`die()\*(C'\fR handler.
.ie n .SS """signalLevel"""
.el .SS "\f(CWsignalLevel\fP"
.IX Subsection "signalLevel"
Number three in a series: set \f(CW\*(C`signalLevel\*(C'\fR to zero to keep your own
signal handler for \f(CW\*(C`SIGSEGV\*(C'\fR and/or \f(CW\*(C`SIGBUS\*(C'\fR. Otherwise, the debugger
takes over and handles them with \f(CW\*(C`DB::diesignal()\*(C'\fR.
.SH "SUBROUTINE DECODING SUPPORT"
.IX Header "SUBROUTINE DECODING SUPPORT"
These subroutines are used during the \f(CW\*(C`x\*(C'\fR and \f(CW\*(C`X\*(C'\fR commands to try to
produce as much information as possible about a code reference. They use
Devel::Peek to try to find the glob in which this code reference lives
(if it does) \- this allows us to actually code references which correspond
to named subroutines (including those aliased via glob assignment).
.ie n .SS """CvGV_name()"""
.el .SS "\f(CWCvGV_name()\fP"
.IX Subsection "CvGV_name()"
Wrapper for \f(CW\*(C`CvGV_name_or_bust\*(C'\fR; tries to get the name of a reference
via that routine. If this fails, return the reference again (when the
reference is stringified, it'll come out as \f(CW\*(C`SOMETHING(0x...)\*(C'\fR).
.ie n .SS """CvGV_name_or_bust"" \fIcoderef\fP"
.el .SS "\f(CWCvGV_name_or_bust\fP \fIcoderef\fP"
.IX Subsection "CvGV_name_or_bust coderef"
Calls Devel::Peek to try to find the glob the ref lives in; returns
\&\f(CW\*(C`undef\*(C'\fR if Devel::Peek can't be loaded, or if \f(CW\*(C`Devel::Peek::CvGV\*(C'\fR can't
find a glob for this ref.
.PP
Returns \f(CW\*(C`\f(CIpackage\f(CW::\f(CIglob name\f(CW\*(C'\fR if the code ref is found in a glob.
.ie n .SS """find_sub"""
.el .SS "\f(CWfind_sub\fP"
.IX Subsection "find_sub"
A utility routine used in various places; finds the file where a subroutine
was defined, and returns that filename and a line-number range.
.PP
Tries to use \f(CW@sub\fR first; if it can't find it there, it tries building a
reference to the subroutine and uses \f(CW\*(C`CvGV_name_or_bust\*(C'\fR to locate it,
loading it into \f(CW@sub\fR as a side effect (\s-1XXX I\s0 think). If it can't find it
this way, it brute-force searches \f(CW%sub\fR, checking for identical references.
.ie n .SS """methods"""
.el .SS "\f(CWmethods\fP"
.IX Subsection "methods"
A subroutine that uses the utility function \f(CW\*(C`methods_via\*(C'\fR to find all the
methods in the class corresponding to the current reference and in
\&\f(CW\*(C`UNIVERSAL\*(C'\fR.
.ie n .SS """methods_via($class, $prefix, $crawl_upward)"""
.el .SS "\f(CWmethods_via($class, $prefix, $crawl_upward)\fP"
.IX Subsection "methods_via($class, $prefix, $crawl_upward)"
\&\f(CW\*(C`methods_via\*(C'\fR does the work of crawling up the \f(CW@ISA\fR tree and reporting
all the parent class methods. \f(CW$class\fR is the name of the next class to
try; \f(CW$prefix\fR is the message prefix, which gets built up as we go up the
\&\f(CW@ISA\fR tree to show parentage; \f(CW$crawl_upward\fR is 1 if we should try to go
higher in the \f(CW@ISA\fR tree, 0 if we should stop.
.ie n .SS """setman"" \- figure out which command to use to show documentation"
.el .SS "\f(CWsetman\fP \- figure out which command to use to show documentation"
.IX Subsection "setman - figure out which command to use to show documentation"
Just checks the contents of \f(CW$^O\fR and sets the \f(CW$doccmd\fR global accordingly.
.ie n .SS """runman"" \- run the appropriate command to show documentation"
.el .SS "\f(CWrunman\fP \- run the appropriate command to show documentation"
.IX Subsection "runman - run the appropriate command to show documentation"
Accepts a man page name; runs the appropriate command to display it (set up
during debugger initialization). Uses \f(CW\*(C`_db_system()\*(C'\fR to avoid mucking up the
program's \s-1STDIN\s0 and \s-1STDOUT.\s0
.SH "DEBUGGER INITIALIZATION \- THE SECOND BEGIN BLOCK"
.IX Header "DEBUGGER INITIALIZATION - THE SECOND BEGIN BLOCK"
Because of the way the debugger interface to the Perl core is designed, any
debugger package globals that \f(CW\*(C`DB::sub()\*(C'\fR requires have to be defined before
any subroutines can be called. These are defined in the second \f(CW\*(C`BEGIN\*(C'\fR block.
.PP
This block sets things up so that (basically) the world is sane
before the debugger starts executing. We set up various variables that the
debugger has to have set up before the Perl core starts running:
.IP "\(bu" 4
The debugger's own filehandles (copies of \s-1STD\s0 and \s-1STDOUT\s0 for now).
.IP "\(bu" 4
Characters for shell escapes, the recall command, and the history command.
.IP "\(bu" 4
The maximum recursion depth.
.IP "\(bu" 4
The size of a \f(CW\*(C`w\*(C'\fR command's window.
.IP "\(bu" 4
The before-this-line context to be printed in a \f(CW\*(C`v\*(C'\fR (view a window around this line) command.
.IP "\(bu" 4
The fact that we're not in a sub at all right now.
.IP "\(bu" 4
The default \s-1SIGINT\s0 handler for the debugger.
.IP "\(bu" 4
The appropriate value of the flag in \f(CW$^D\fR that says the debugger is running
.IP "\(bu" 4
The current debugger recursion level
.IP "\(bu" 4
The list of postponed items and the \f(CW$single\fR stack (\s-1XXX\s0 define this)
.IP "\(bu" 4
That we want no return values and no subroutine entry/exit trace.
.SH "READLINE SUPPORT \- COMPLETION FUNCTION"
.IX Header "READLINE SUPPORT - COMPLETION FUNCTION"
.SS "db_complete"
.IX Subsection "db_complete"
\&\f(CW\*(C`readline\*(C'\fR support \- adds command completion to basic \f(CW\*(C`readline\*(C'\fR.
.PP
Returns a list of possible completions to \f(CW\*(C`readline\*(C'\fR when invoked. \f(CW\*(C`readline\*(C'\fR
will print the longest common substring following the text already entered.
.PP
If there is only a single possible completion, \f(CW\*(C`readline\*(C'\fR will use it in full.
.PP
This code uses \f(CW\*(C`map\*(C'\fR and \f(CW\*(C`grep\*(C'\fR heavily to create lists of possible
completion. Think \s-1LISP\s0 in this section.
.PP
\fI\f(CI\*(C`b postpone|compile\*(C'\fI\fR
.IX Subsection "b postpone|compile"
.IP "\(bu" 4
Find all the subroutines that might match in this package
.IP "\(bu" 4
Add \f(CW\*(C`postpone\*(C'\fR, \f(CW\*(C`load\*(C'\fR, and \f(CW\*(C`compile\*(C'\fR as possibles (we may be completing the keyword itself)
.IP "\(bu" 4
Include all the rest of the subs that are known
.IP "\(bu" 4
\&\f(CW\*(C`grep\*(C'\fR out the ones that match the text we have so far
.IP "\(bu" 4
Return this as the list of possible completions
.PP
\fI\f(CI\*(C`b load\*(C'\fI\fR
.IX Subsection "b load"
.PP
Get all the possible files from \f(CW@INC\fR as it currently stands and
select the ones that match the text so far.
.PP
\fI\f(CI\*(C`V\*(C'\fI (list variable) and \f(CI\*(C`m\*(C'\fI (list modules)\fR
.IX Subsection "V (list variable) and m (list modules)"
.PP
There are two entry points for these commands:
.PP
Unqualified package names
.IX Subsection "Unqualified package names"
.PP
Get the top-level packages and grab everything that matches the text
so far. For each match, recursively complete the partial packages to
get all possible matching packages. Return this sorted list.
.PP
Qualified package names
.IX Subsection "Qualified package names"
.PP
Take a partially-qualified package and find all subpackages for it
by getting all the subpackages for the package so far, matching all
the subpackages against the text, and discarding all of them which
start with 'main::'. Return this list.
.PP
\fI\f(CI\*(C`f\*(C'\fI \- switch files\fR
.IX Subsection "f - switch files"
.PP
Here, we want to get a fully-qualified filename for the \f(CW\*(C`f\*(C'\fR command.
Possibilities are:
.IP "1. The original source file itself" 4
.IX Item "1. The original source file itself"
.PD 0
.ie n .IP "2. A file from @INC" 4
.el .IP "2. A file from \f(CW@INC\fR" 4
.IX Item "2. A file from @INC"
.ie n .IP "3. An ""eval"" (the debugger gets a ""(eval N)"" fake file for each ""eval"")." 4
.el .IP "3. An \f(CWeval\fR (the debugger gets a \f(CW(eval N)\fR fake file for each \f(CWeval\fR)." 4
.IX Item "3. An eval (the debugger gets a (eval N) fake file for each eval)."
.PD
.PP
Under the debugger, source files are represented as \f(CW\*(C`_</fullpath/to/file\*(C'\fR
(\f(CW\*(C`eval\*(C'\fRs are \f(CW\*(C`_<(eval NNN)\*(C'\fR) keys in \f(CW%main::\fR. We pull all of these
out of \f(CW%main::\fR, add the initial source file, and extract the ones that
match the completion text so far.
.PP
\fISubroutine name completion\fR
.IX Subsection "Subroutine name completion"
.PP
We look through all of the defined subs (the keys of \f(CW%sub\fR) and
return both all the possible matches to the subroutine name plus
all the matches qualified to the current package.
.PP
\fIScalar, array, and hash completion: partially qualified package\fR
.IX Subsection "Scalar, array, and hash completion: partially qualified package"
.PP
Much like the above, except we have to do a little more cleanup:
.IP "\(bu" 4
Determine the package that the symbol is in. Put it in \f(CW\*(C`::\*(C'\fR (effectively \f(CW\*(C`main::\*(C'\fR) if no package is specified.
.IP "\(bu" 4
Figure out the prefix vs. what needs completing.
.IP "\(bu" 4
Look through all the symbols in the package. \f(CW\*(C`grep\*(C'\fR out all the possible hashes/arrays/scalars, and then \f(CW\*(C`grep\*(C'\fR the possible matches out of those. \f(CW\*(C`map\*(C'\fR the prefix onto all the possibilities.
.IP "\(bu" 4
If there's only one hit, and it's a package qualifier, and it's not equal to the initial text, re-complete it using the symbol we actually found.
.PP
\fISymbol completion: current package or package \f(CI\*(C`main\*(C'\fI.\fR
.IX Subsection "Symbol completion: current package or package main."
.IP "\(bu" 4
If it's \f(CW\*(C`main\*(C'\fR, delete main to just get \f(CW\*(C`::\*(C'\fR leading.
.IP "\(bu" 4
We set the prefix to the item's sigil, and trim off the sigil to get the text to be completed.
.IP "\(bu" 4
We look for the lexical scope above \s-1DB::DB\s0 and auto-complete lexical variables
if PadWalker could be loaded.
.IP "\(bu" 4
If the package is \f(CW\*(C`::\*(C'\fR (\f(CW\*(C`main\*(C'\fR), create an empty list; if it's something else, create a list of all the packages known.  Append whichever list to a list of all the possible symbols in the current package. \f(CW\*(C`grep\*(C'\fR out the matches to the text entered so far, then \f(CW\*(C`map\*(C'\fR the prefix back onto the symbols.
.IP "\(bu" 4
If there's only one hit, it's a package qualifier, and it's not equal to the initial text, recomplete using this symbol.
.PP
\fIOptions\fR
.IX Subsection "Options"
.PP
We use \f(CW\*(C`option_val()\*(C'\fR to look up the current value of the option. If there's
only a single value, we complete the command in such a way that it is a
complete command for setting the option in question. If there are multiple
possible values, we generate a command consisting of the option plus a trailing
question mark, which, if executed, will list the current value of the option.
.PP
\fIFilename completion\fR
.IX Subsection "Filename completion"
.PP
For entering filenames. We simply call \f(CW\*(C`readline\*(C'\fR's \f(CW\*(C`filename_list()\*(C'\fR
method with the completion text to get the possible completions.
.SH "MISCELLANEOUS SUPPORT FUNCTIONS"
.IX Header "MISCELLANEOUS SUPPORT FUNCTIONS"
Functions that possibly ought to be somewhere else.
.SS "end_report"
.IX Subsection "end_report"
Say we're done.
.SS "clean_ENV"
.IX Subsection "clean_ENV"
If we have \f(CW$ini_pids\fR, save it in the environment; else remove it from the
environment. Used by the \f(CW\*(C`R\*(C'\fR (restart) command.
.IP "rerun" 4
.IX Item "rerun"
Rerun the current session to:
.Sp
.Vb 1
\&    rerun        current position
\&
\&    rerun 4      command number 4
\&
\&    rerun \-4     current command minus 4 (go back 4 steps)
.Ve
.Sp
Whether this always makes sense, in the current context is unknowable, and is
in part left as a useful exercise for the reader.  This sub returns the
appropriate arguments to rerun the current session.
.IP "restart" 4
.IX Item "restart"
Restarting the debugger is a complex operation that occurs in several phases.
First, we try to reconstruct the command line that was used to invoke Perl
and the debugger.
.Sp
After the command line  has been reconstructed, the next step is to save
the debugger's status in environment variables. The \f(CW\*(C`DB::set_list\*(C'\fR routine
is used to save aggregate variables (both hashes and arrays); scalars are
just popped into environment variables directly.
.Sp
The most complex part of this is the saving of all of the breakpoints. They
can live in an awful lot of places, and we have to go through all of them,
find the breakpoints, and then save them in the appropriate environment
variable via \f(CW\*(C`DB::set_list\*(C'\fR.
.Sp
After all the debugger status has been saved, we take the command we built up
and then return it, so we can \f(CW\*(C`exec()\*(C'\fR it. The debugger will spot the
\&\f(CW\*(C`PERLDB_RESTART\*(C'\fR environment variable and realize it needs to reload its state
from the environment.
.ie n .SH "END PROCESSING \- THE ""END"" BLOCK"
.el .SH "END PROCESSING \- THE \f(CWEND\fP BLOCK"
.IX Header "END PROCESSING - THE END BLOCK"
Come here at the very end of processing. We want to go into a
loop where we allow the user to enter commands and interact with the
debugger, but we don't want anything else to execute.
.PP
First we set the \f(CW$finished\fR variable, so that some commands that
shouldn't be run after the end of program quit working.
.PP
We then figure out whether we're truly done (as in the user entered a \f(CW\*(C`q\*(C'\fR
command, or we finished execution while running nonstop). If we aren't,
we set \f(CW$single\fR to 1 (causing the debugger to get control again).
.PP
We then call \f(CW\*(C`DB::fake::at_exit()\*(C'\fR, which returns the \f(CW\*(C`Use \*(Aqq\*(Aq to quit ...\*(C'\fR
message and returns control to the debugger. Repeat.
.PP
When the user finally enters a \f(CW\*(C`q\*(C'\fR command, \f(CW$fall_off_end\fR is set to
1 and the \f(CW\*(C`END\*(C'\fR block simply exits with \f(CW$single\fR set to 0 (don't
break, run to completion.).
.SH "PRE\-5.8 COMMANDS"
.IX Header "PRE-5.8 COMMANDS"
Some of the commands changed function quite a bit in the 5.8 command
realignment, so much so that the old code had to be replaced completely.
Because we wanted to retain the option of being able to go back to the
former command set, we moved the old code off to this section.
.PP
There's an awful lot of duplicated code here. We've duplicated the
comments to keep things clear.
.SS "Null command"
.IX Subsection "Null command"
Does nothing. Used to \fIturn off\fR commands.
.ie n .SS "Old ""a"" command."
.el .SS "Old \f(CWa\fP command."
.IX Subsection "Old a command."
This version added actions if you supplied them, and deleted them
if you didn't.
.ie n .SS "Old ""b"" command"
.el .SS "Old \f(CWb\fP command"
.IX Subsection "Old b command"
Add breakpoints.
.ie n .SS "Old ""D"" command."
.el .SS "Old \f(CWD\fP command."
.IX Subsection "Old D command."
Delete all breakpoints unconditionally.
.ie n .SS "Old ""h"" command"
.el .SS "Old \f(CWh\fP command"
.IX Subsection "Old h command"
Print help. Defaults to printing the long-form help; the 5.8 version
prints the summary by default.
.ie n .SS "Old ""W"" command"
.el .SS "Old \f(CWW\fP command"
.IX Subsection "Old W command"
\&\f(CW\*(C`W <expr>\*(C'\fR adds a watch expression, \f(CW\*(C`W\*(C'\fR deletes them all.
.SH "PRE-AND-POST-PROMPT COMMANDS AND ACTIONS"
.IX Header "PRE-AND-POST-PROMPT COMMANDS AND ACTIONS"
The debugger used to have a bunch of nearly-identical code to handle
the pre-and-post-prompt action commands. \f(CW\*(C`cmd_pre590_prepost\*(C'\fR and
\&\f(CW\*(C`cmd_prepost\*(C'\fR unify all this into one set of code to handle the
appropriate actions.
.ie n .SS """cmd_pre590_prepost"""
.el .SS "\f(CWcmd_pre590_prepost\fP"
.IX Subsection "cmd_pre590_prepost"
A small wrapper around \f(CW\*(C`cmd_prepost\*(C'\fR; it makes sure that the default doesn't
do something destructive. In pre 5.8 debuggers, the default action was to
delete all the actions.
.ie n .SS """cmd_prepost"""
.el .SS "\f(CWcmd_prepost\fP"
.IX Subsection "cmd_prepost"
Actually does all the handling for \f(CW\*(C`<\*(C'\fR, \f(CW\*(C`>\*(C'\fR, \f(CW\*(C`{{\*(C'\fR, \f(CW\*(C`{\*(C'\fR, etc.
Since the lists of actions are all held in arrays that are pointed to by
references anyway, all we have to do is pick the right array reference and
then use generic code to all, delete, or list actions.
.ie n .SH """DB::fake"""
.el .SH "\f(CWDB::fake\fP"
.IX Header "DB::fake"
Contains the \f(CW\*(C`at_exit\*(C'\fR routine that the debugger uses to issue the
\&\f(CW\*(C`Debugged program terminated ...\*(C'\fR message after the program completes. See
the \f(CW\*(C`END\*(C'\fR block documentation for more details.