Debian Codegraph @

upstream/debian-unstable/man3/DB.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "DB 3perl"
58 .TH DB 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 DB \- programmatic interface to the Perl debugging API
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 3
68 \& package CLIENT;
69 \& use DB;
70 \& @ISA = qw(DB);
71 \&
72 \& # these (inherited) methods can be called by the client
73 \&
74 \& CLIENT\->register() # register a client package name
75 \& CLIENT\->done() # de\-register from the debugging API
76 \& CLIENT\->skippkg(\*(Aqhide::hide\*(Aq) # ask DB not to stop in this package
77 \& CLIENT\->cont([WHERE]) # run some more (until BREAK or
78 \& # another breakpointt)
79 \& CLIENT\->step() # single step
80 \& CLIENT\->next() # step over
81 \& CLIENT\->ret() # return from current subroutine
82 \& CLIENT\->backtrace() # return the call stack description
83 \& CLIENT\->ready() # call when client setup is done
84 \& CLIENT\->trace_toggle() # toggle subroutine call trace mode
85 \& CLIENT\->subs([SUBS]) # return subroutine information
86 \& CLIENT\->files() # return list of all files known to DB
87 \& CLIENT\->lines() # return lines in currently loaded file
88 \& CLIENT\->loadfile(FILE,LINE) # load a file and let other clients know
89 \& CLIENT\->lineevents() # return info on lines with actions
90 \& CLIENT\->set_break([WHERE],[COND])
91 \& CLIENT\->set_tbreak([WHERE])
92 \& CLIENT\->clr_breaks([LIST])
93 \& CLIENT\->set_action(WHERE,ACTION)
94 \& CLIENT\->clr_actions([LIST])
95 \& CLIENT\->evalcode(STRING) # eval STRING in executing code\*(Aqs context
96 \& CLIENT\->prestop([STRING]) # execute in code context before stopping
97 \& CLIENT\->poststop([STRING])# execute in code context before resuming
98 \&
99 \& # These methods will be called at the appropriate times.
100 \& # Stub versions provided do nothing.
101 \& # None of these can block.
102 \&
103 \& CLIENT\->init() # called when debug API inits itself
104 \& CLIENT\->stop(FILE,LINE) # when execution stops
105 \& CLIENT\->idle() # while stopped (can be a client event loop)
106 \& CLIENT\->cleanup() # just before exit
107 \& CLIENT\->output(LIST) # called to print any output that
108 \& # the API must show
109 .Ve
110 .SH DESCRIPTION
111 .IX Header "DESCRIPTION"
112 Perl debug information is frequently required not just by debuggers,
113 but also by modules that need some "special" information to do their
114 job properly, like profilers.
115 .PP
116 This module abstracts and provides all of the hooks into Perl internal
117 debugging functionality, so that various implementations of Perl debuggers
118 (or packages that want to simply get at the "privileged" debugging data)
119 can all benefit from the development of this common code. Currently used
120 by Swat, the perl/Tk GUI debugger.
121 .PP
122 Note that multiple "front-ends" can latch into this debugging API
123 simultaneously. This is intended to facilitate things like
124 debugging with a command line and GUI at the same time, debugging
125 debuggers etc. [Sounds nice, but this needs some serious support \-\- GSAR]
126 .PP
127 In particular, this API does \fBnot\fR provide the following functions:
128 .IP \(bu 4
129 data display
130 .IP \(bu 4
131 command processing
132 .IP \(bu 4
133 command alias management
134 .IP \(bu 4
135 user interface (tty or graphical)
136 .PP
137 These are intended to be services performed by the clients of this API.
138 .PP
139 This module attempts to be squeaky clean w.r.t \f(CW\*(C`use strict;\*(C'\fR and when
140 warnings are enabled.
141 .SS "Global Variables"
142 .IX Subsection "Global Variables"
143 The following "public" global names can be read by clients of this API.
144 Beware that these should be considered "readonly".
145 .ie n .IP $DB::sub 8
146 .el .IP \f(CW$DB::sub\fR 8
147 .IX Item "$DB::sub"
148 Name of current executing subroutine.
149 .ie n .IP %DB::sub 8
150 .el .IP \f(CW%DB::sub\fR 8
151 .IX Item "%DB::sub"
152 The keys of this hash are the names of all the known subroutines. Each value
153 is an encoded string that has the \fBsprintf\fR\|(3) format
154 \&\f(CW\*(C`("%s:%d\-%d", filename, fromline, toline)\*(C'\fR.
155 .ie n .IP $DB::single 8
156 .el .IP \f(CW$DB::single\fR 8
157 .IX Item "$DB::single"
158 Single-step flag. Will be true if the API will stop at the next statement.
159 .ie n .IP $DB::signal 8
160 .el .IP \f(CW$DB::signal\fR 8
161 .IX Item "$DB::signal"
162 Signal flag. Will be set to a true value if a signal was caught. Clients may
163 check for this flag to abort time-consuming operations.
164 .ie n .IP $DB::trace 8
165 .el .IP \f(CW$DB::trace\fR 8
166 .IX Item "$DB::trace"
167 This flag is set to true if the API is tracing through subroutine calls.
168 .ie n .IP @DB::args 8
169 .el .IP \f(CW@DB::args\fR 8
170 .IX Item "@DB::args"
171 Contains the arguments of current subroutine, or the \f(CW@ARGV\fR array if in the
172 toplevel context.
173 .ie n .IP @DB::dbline 8
174 .el .IP \f(CW@DB::dbline\fR 8
175 .IX Item "@DB::dbline"
176 List of lines in currently loaded file.
177 .ie n .IP %DB::dbline 8
178 .el .IP \f(CW%DB::dbline\fR 8
179 .IX Item "%DB::dbline"
180 Actions in current file (keys are line numbers). The values are strings that
181 have the \fBsprintf\fR\|(3) format \f(CW\*(C`("%s\e000%s", breakcondition, actioncode)\*(C'\fR.
182 .ie n .IP $DB::package 8
183 .el .IP \f(CW$DB::package\fR 8
184 .IX Item "$DB::package"
185 Package namespace of currently executing code.
186 .ie n .IP $DB::filename 8
187 .el .IP \f(CW$DB::filename\fR 8
188 .IX Item "$DB::filename"
189 Currently loaded filename.
190 .ie n .IP $DB::subname 8
191 .el .IP \f(CW$DB::subname\fR 8
192 .IX Item "$DB::subname"
193 Fully qualified name of currently executing subroutine.
194 .ie n .IP $DB::lineno 8
195 .el .IP \f(CW$DB::lineno\fR 8
196 .IX Item "$DB::lineno"
197 Line number that will be executed next.
198 .SS "API Methods"
199 .IX Subsection "API Methods"
200 The following are methods in the DB base class. A client must
201 access these methods by inheritance (*not* by calling them directly),
202 since the API keeps track of clients through the inheritance
203 mechanism.
204 .IP CLIENT\->\fBregister()\fR 8
205 .IX Item "CLIENT->register()"
206 register a client object/package
207 .IP CLIENT\->evalcode(STRING) 8
208 .IX Item "CLIENT->evalcode(STRING)"
209 eval STRING in executing code context
210 .IP CLIENT\->skippkg('D::hide') 8
211 .IX Item "CLIENT->skippkg('D::hide')"
212 ask DB not to stop in these packages
213 .IP CLIENT\->\fBrun()\fR 8
214 .IX Item "CLIENT->run()"
215 run some more (until a breakpt is reached)
216 .IP CLIENT\->\fBstep()\fR 8
217 .IX Item "CLIENT->step()"
218 single step
219 .IP CLIENT\->\fBnext()\fR 8
220 .IX Item "CLIENT->next()"
221 step over
222 .IP CLIENT\->\fBdone()\fR 8
223 .IX Item "CLIENT->done()"
224 de-register from the debugging API
225 .SS "Client Callback Methods"
226 .IX Subsection "Client Callback Methods"
227 The following "virtual" methods can be defined by the client. They will
228 be called by the API at appropriate points. Note that unless specified
229 otherwise, the debug API only defines empty, non-functional default versions
230 of these methods.
231 .IP CLIENT\->\fBinit()\fR 8
232 .IX Item "CLIENT->init()"
233 Called after debug API inits itself.
234 .IP CLIENT\->prestop([STRING]) 8
235 .IX Item "CLIENT->prestop([STRING])"
236 Usually inherited from DB package. If no arguments are passed,
237 returns the prestop action string.
238 .IP CLIENT\->\fBstop()\fR 8
239 .IX Item "CLIENT->stop()"
240 Called when execution stops (w/ args file, line).
241 .IP CLIENT\->\fBidle()\fR 8
242 .IX Item "CLIENT->idle()"
243 Called while stopped (can be a client event loop).
244 .IP CLIENT\->poststop([STRING]) 8
245 .IX Item "CLIENT->poststop([STRING])"
246 Usually inherited from DB package. If no arguments are passed,
247 returns the poststop action string.
248 .IP CLIENT\->evalcode(STRING) 8
249 .IX Item "CLIENT->evalcode(STRING)"
250 Usually inherited from DB package. Ask for a STRING to be \f(CW\*(C`eval\*(C'\fR\-ed
251 in executing code context.
252 .IP CLIENT\->\fBcleanup()\fR 8
253 .IX Item "CLIENT->cleanup()"
254 Called just before exit.
255 .IP CLIENT\->output(LIST) 8
256 .IX Item "CLIENT->output(LIST)"
257 Called when API must show a message (warnings, errors etc.).
258 .SH BUGS
259 .IX Header "BUGS"
260 The interface defined by this module is missing some of the later additions
261 to perl's debugging functionality. As such, this interface should be considered
262 highly experimental and subject to change.
263 .SH AUTHOR
264 .IX Header "AUTHOR"
265 Gurusamy Sarathy [email protected]
266 .PP
267 This code heavily adapted from an early version of perl5db.pl attributable
268 to Larry Wall and the Perl Porters.