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
19 # another breakpointt)
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
49 # the API must show
50
52 Perl debug information is frequently required not just by debuggers,
53 but also by modules that need some "special" information to do their
54 job properly, like profilers.
55 This module abstracts and provides all of the hooks into Perl internal
57 debugging functionality, so that various implementations of Perl
58 debuggers (or packages that want to simply get at the "privileged"
59 debugging data) can all benefit from the development of this common
60 code. Currently used by Swat, the perl/Tk GUI debugger.
61 Note that multiple "front-ends" can latch into this debugging API
63 simultaneously. This is intended to facilitate things like debugging
64 with a command line and GUI at the same time, debugging debuggers etc.
65 [Sounds nice, but this needs some serious support -- GSAR]
66 In particular, this API does not provide the following functions:
68 • data display
70 • command processing
72 • command alias management
74 • user interface (tty or graphical)
76 These are intended to be services performed by the clients of this API.
78 This module attempts to be squeaky clean w.r.t "use strict;" and when
80 warnings are enabled.
81 Global Variables
83 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
91 subroutines. Each value is an encoded string that has the
92 sprintf(3) 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-
101 consuming operations.
102 $DB::trace
104 This flag is set to true if the API is tracing through
105 subroutine 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
133 these methods by inheritance (*not* by calling them directly), since
134 the API keeps track of clients through the inheritance mechanism.
135 CLIENT->register()
137 register a client object/package
138 CLIENT->evalcode(STRING)
140 eval STRING in executing code context
141 CLIENT->skippkg('D::hide')
143 ask DB not to stop in these packages
144 CLIENT->run()
146 run some more (until a breakpt is reached)
147 CLIENT->step()
149 single step
150 CLIENT->next()
152 step over
153 CLIENT->done()
155 de-register from the debugging API
156 Client Callback Methods
158 The following "virtual" methods can be defined by the client. They
159 will be called by the API at appropriate points. Note that unless
160 specified otherwise, the debug API only defines empty, non-functional
161 default versions of these methods.
162 CLIENT->init()
164 Called after debug API inits itself.
165 CLIENT->prestop([STRING])
167 Usually inherited from DB package. If no arguments are passed,
168 returns the prestop action string.
169 CLIENT->stop()
171 Called when execution stops (w/ args file, line).
172 CLIENT->idle()
174 Called while stopped (can be a client event loop).
175 CLIENT->poststop([STRING])
177 Usually inherited from DB package. If no arguments are passed,
178 returns the poststop action string.
179 CLIENT->evalcode(STRING)
181 Usually inherited from DB package. Ask for a STRING to be
182 "eval"-ed in executing code context.
183 CLIENT->cleanup()
185 Called just before exit.
186 CLIENT->output(LIST)
188 Called when API must show a message (warnings, errors etc.).
189
191 The interface defined by this module is missing some of the later
192 additions to perl's debugging functionality. As such, this interface
193 should be considered highly experimental and subject to change.
194
196 Gurusamy Sarathy gsar@activestate.com
197 This code heavily adapted from an early version of perl5db.pl
199 attributable to Larry Wall and the Perl Porters.
200perl v5.36.0 2022-08-30 DB(3pm)