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