1DB(3pm)                Perl Programmers Reference Guide                DB(3pm)
2
3
4

NAME

6       DB - programmatic interface to the Perl debugging API
7

SYNOPSIS

9           package CLIENT;
10           use DB;
11           @ISA = qw(DB);
12
13           # these (inherited) methods can be called by the client
14
15           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
40           # These methods will be called at the appropriate times.
41           # Stub versions provided do nothing.
42           # None of these can block.
43
44           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

DESCRIPTION

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
56       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
62       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
67       In particular, this API does not provide the following functions:
68
69       ·   data display
70
71       ·   command processing
72
73       ·   command alias management
74
75       ·   user interface (tty or graphical)
76
77       These are intended to be services performed by the clients of this API.
78
79       This module attempts to be squeaky clean w.r.t "use strict;" and when
80       warnings are enabled.
81
82   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
86       $DB::sub
87               Name of current executing subroutine.
88
89       %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
94       $DB::single
95               Single-step flag.  Will be true if the API will stop at the
96               next statement.
97
98       $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
103       $DB::trace
104               This flag is set to true if the API is tracing through
105               subroutine calls.
106
107       @DB::args
108               Contains the arguments of current subroutine, or the @ARGV
109               array if in the toplevel context.
110
111       @DB::dbline
112               List of lines in currently loaded file.
113
114       %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
119       $DB::package
120               Package namespace of currently executing code.
121
122       $DB::filename
123               Currently loaded filename.
124
125       $DB::subname
126               Fully qualified name of currently executing subroutine.
127
128       $DB::lineno
129               Line number that will be executed next.
130
131   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
136       CLIENT->register()
137               register a client object/package
138
139       CLIENT->evalcode(STRING)
140               eval STRING in executing code context
141
142       CLIENT->skippkg('D::hide')
143               ask DB not to stop in these packages
144
145       CLIENT->run()
146               run some more (until a breakpt is reached)
147
148       CLIENT->step()
149               single step
150
151       CLIENT->next()
152               step over
153
154       CLIENT->done()
155               de-register from the debugging API
156
157   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
163       CLIENT->init()
164               Called after debug API inits itself.
165
166       CLIENT->prestop([STRING])
167               Usually inherited from DB package.  If no arguments are passed,
168               returns the prestop action string.
169
170       CLIENT->stop()
171               Called when execution stops (w/ args file, line).
172
173       CLIENT->idle()
174               Called while stopped (can be a client event loop).
175
176       CLIENT->poststop([STRING])
177               Usually inherited from DB package.  If no arguments are passed,
178               returns the poststop action string.
179
180       CLIENT->evalcode(STRING)
181               Usually inherited from DB package.  Ask for a STRING to be
182               "eval"-ed in executing code context.
183
184       CLIENT->cleanup()
185               Called just before exit.
186
187       CLIENT->output(LIST)
188               Called when API must show a message (warnings, errors etc.).
189

BUGS

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

AUTHOR

196       Gurusamy Sarathy    gsar@activestate.com
197
198       This code heavily adapted from an early version of perl5db.pl
199       attributable to Larry Wall and the Perl Porters.
200
201
202
203perl v5.26.3                      2018-03-01                           DB(3pm)
Impressum