1DB(3pm) Perl Programmers Reference Guide DB(3pm)
2
6 DB - programmatic interface to the Perl debugging API (draft, subject
7 to change)
8
10 package CLIENT;
11 use DB;
12 @ISA = qw(DB);
13 # these (inherited) methods can be called by the client
15 CLIENT->register() # register a client package name
17 CLIENT->done() # de-register from the debugging API
18 CLIENT->skippkg('hide::hide') # ask DB not to stop in this package
19 CLIENT->cont([WHERE]) # run some more (until BREAK or another breakpt)
20 CLIENT->step() # single step
21 CLIENT->next() # step over
22 CLIENT->ret() # return from current subroutine
23 CLIENT->backtrace() # return the call stack description
24 CLIENT->ready() # call when client setup is done
25 CLIENT->trace_toggle() # toggle subroutine call trace mode
26 CLIENT->subs([SUBS]) # return subroutine information
27 CLIENT->files() # return list of all files known to DB
28 CLIENT->lines() # return lines in currently loaded file
29 CLIENT->loadfile(FILE,LINE) # load a file and let other clients know
30 CLIENT->lineevents() # return info on lines with actions
31 CLIENT->set_break([WHERE],[COND])
32 CLIENT->set_tbreak([WHERE])
33 CLIENT->clr_breaks([LIST])
34 CLIENT->set_action(WHERE,ACTION)
35 CLIENT->clr_actions([LIST])
36 CLIENT->evalcode(STRING) # eval STRING in executing code's context
37 CLIENT->prestop([STRING]) # execute in code context before stopping
38 CLIENT->poststop([STRING])# execute in code context before resuming
39 # These methods will be called at the appropriate times.
41 # Stub versions provided do nothing.
42 # None of these can block.
43 CLIENT->init() # called when debug API inits itself
45 CLIENT->stop(FILE,LINE) # when execution stops
46 CLIENT->idle() # while stopped (can be a client event loop)
47 CLIENT->cleanup() # just before exit
48 CLIENT->output(LIST) # called to print any output that API must show
49
51 Perl debug information is frequently required not just by debuggers,
52 but also by modules that need some "special" information to do their
53 job properly, like profilers.
54 This module abstracts and provides all of the hooks into Perl internal
56 debugging functionality, so that various implementations of Perl debug‐
57 gers (or packages that want to simply get at the "privileged" debugging
58 data) can all benefit from the development of this common code. Cur‐
59 rently used by Swat, the perl/Tk GUI debugger.
60 Note that multiple "front-ends" can latch into this debugging API
62 simultaneously. This is intended to facilitate things like debugging
63 with a command line and GUI at the same time, debugging debuggers etc.
64 [Sounds nice, but this needs some serious support -- GSAR]
65 In particular, this API does not provide the following functions:
67 · data display
69 · command processing
71 · command alias management
73 · user interface (tty or graphical)
75 These are intended to be services performed by the clients of this API.
77 This module attempts to be squeaky clean w.r.t "use strict;" and when
79 warnings are enabled.
80 Global Variables
82 The following "public" global names can be read by clients of this API.
84 Beware that these should be considered "readonly".
85 $DB::sub
87 Name of current executing subroutine.
88 %DB::sub
90 The keys of this hash are the names of all the known subrou‐
91 tines. Each value is an encoded string that has the sprintf(3)
92 format "("%s:%d-%d", filename, fromline, toline)".
93 $DB::single
95 Single-step flag. Will be true if the API will stop at the
96 next statement.
97 $DB::signal
99 Signal flag. Will be set to a true value if a signal was
100 caught. Clients may check for this flag to abort time-consum‐
101 ing operations.
102 $DB::trace
104 This flag is set to true if the API is tracing through subrou‐
105 tine calls.
106 @DB::args
108 Contains the arguments of current subroutine, or the @ARGV
109 array if in the toplevel context.
110 @DB::dbline
112 List of lines in currently loaded file.
113 %DB::dbline
115 Actions in current file (keys are line numbers). The values
116 are strings that have the sprintf(3) format "("%s\000%s",
117 breakcondition, actioncode)".
118 $DB::package
120 Package namespace of currently executing code.
121 $DB::filename
123 Currently loaded filename.
124 $DB::subname
126 Fully qualified name of currently executing subroutine.
127 $DB::lineno
129 Line number that will be executed next.
130 API Methods
132 The following are methods in the DB base class. A client must access
134 these methods by inheritance (*not* by calling them directly), since
135 the API keeps track of clients through the inheritance mechanism.
136 CLIENT->register()
138 register a client object/package
139 CLIENT->evalcode(STRING)
141 eval STRING in executing code context
142 CLIENT->skippkg('D::hide')
144 ask DB not to stop in these packages
145 CLIENT->run()
147 run some more (until a breakpt is reached)
148 CLIENT->step()
150 single step
151 CLIENT->next()
153 step over
154 CLIENT->done()
156 de-register from the debugging API
157 Client Callback Methods
159 The following "virtual" methods can be defined by the client. They
161 will be called by the API at appropriate points. Note that unless
162 specified otherwise, the debug API only defines empty, non-functional
163 default versions of these methods.
164 CLIENT->init()
166 Called after debug API inits itself.
167 CLIENT->prestop([STRING])
169 Usually inherited from DB package. If no arguments are passed,
170 returns the prestop action string.
171 CLIENT->stop()
173 Called when execution stops (w/ args file, line).
174 CLIENT->idle()
176 Called while stopped (can be a client event loop).
177 CLIENT->poststop([STRING])
179 Usually inherited from DB package. If no arguments are passed,
180 returns the poststop action string.
181 CLIENT->evalcode(STRING)
183 Usually inherited from DB package. Ask for a STRING to be
184 "eval"-ed in executing code context.
185 CLIENT->cleanup()
187 Called just before exit.
188 CLIENT->output(LIST)
190 Called when API must show a message (warnings, errors etc.).
191
193 The interface defined by this module is missing some of the later addi‐
194 tions to perl's debugging functionality. As such, this interface
195 should be considered highly experimental and subject to change.
196
198 Gurusamy Sarathy gsar@activestate.com
199 This code heavily adapted from an early version of perl5db.pl attribut‐
201 able to Larry Wall and the Perl Porters.
202perl v5.8.8 2001-09-21 DB(3pm)