From fc22b3d6507c6745911b9dfcc68f1e665ae13dbc Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 15 Apr 2024 21:43:11 +0200 Subject: Adding upstream version 4.22.0. Signed-off-by: Daniel Baumann --- upstream/mageia-cauldron/man3pm/DB.3pm | 268 +++++++++++++++++++++++++++++++++ 1 file changed, 268 insertions(+) create mode 100644 upstream/mageia-cauldron/man3pm/DB.3pm (limited to 'upstream/mageia-cauldron/man3pm/DB.3pm') diff --git a/upstream/mageia-cauldron/man3pm/DB.3pm b/upstream/mageia-cauldron/man3pm/DB.3pm new file mode 100644 index 00000000..8c6aefcf --- /dev/null +++ b/upstream/mageia-cauldron/man3pm/DB.3pm @@ -0,0 +1,268 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "DB 3pm" +.TH DB 3pm 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +DB \- programmatic interface to the Perl debugging API +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 3 +\& package CLIENT; +\& use DB; +\& @ISA = qw(DB); +\& +\& # these (inherited) methods can be called by the client +\& +\& CLIENT\->register() # register a client package name +\& CLIENT\->done() # de\-register from the debugging API +\& CLIENT\->skippkg(\*(Aqhide::hide\*(Aq) # ask DB not to stop in this package +\& CLIENT\->cont([WHERE]) # run some more (until BREAK or +\& # another breakpointt) +\& CLIENT\->step() # single step +\& CLIENT\->next() # step over +\& CLIENT\->ret() # return from current subroutine +\& CLIENT\->backtrace() # return the call stack description +\& CLIENT\->ready() # call when client setup is done +\& CLIENT\->trace_toggle() # toggle subroutine call trace mode +\& CLIENT\->subs([SUBS]) # return subroutine information +\& CLIENT\->files() # return list of all files known to DB +\& CLIENT\->lines() # return lines in currently loaded file +\& CLIENT\->loadfile(FILE,LINE) # load a file and let other clients know +\& CLIENT\->lineevents() # return info on lines with actions +\& CLIENT\->set_break([WHERE],[COND]) +\& CLIENT\->set_tbreak([WHERE]) +\& CLIENT\->clr_breaks([LIST]) +\& CLIENT\->set_action(WHERE,ACTION) +\& CLIENT\->clr_actions([LIST]) +\& CLIENT\->evalcode(STRING) # eval STRING in executing code\*(Aqs context +\& CLIENT\->prestop([STRING]) # execute in code context before stopping +\& CLIENT\->poststop([STRING])# execute in code context before resuming +\& +\& # These methods will be called at the appropriate times. +\& # Stub versions provided do nothing. +\& # None of these can block. +\& +\& CLIENT\->init() # called when debug API inits itself +\& CLIENT\->stop(FILE,LINE) # when execution stops +\& CLIENT\->idle() # while stopped (can be a client event loop) +\& CLIENT\->cleanup() # just before exit +\& CLIENT\->output(LIST) # called to print any output that +\& # the API must show +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Perl debug information is frequently required not just by debuggers, +but also by modules that need some "special" information to do their +job properly, like profilers. +.PP +This module abstracts and provides all of the hooks into Perl internal +debugging functionality, so that various implementations of Perl debuggers +(or packages that want to simply get at the "privileged" debugging data) +can all benefit from the development of this common code. Currently used +by Swat, the perl/Tk GUI debugger. +.PP +Note that multiple "front-ends" can latch into this debugging API +simultaneously. This is intended to facilitate things like +debugging with a command line and GUI at the same time, debugging +debuggers etc. [Sounds nice, but this needs some serious support \-\- GSAR] +.PP +In particular, this API does \fBnot\fR provide the following functions: +.IP \(bu 4 +data display +.IP \(bu 4 +command processing +.IP \(bu 4 +command alias management +.IP \(bu 4 +user interface (tty or graphical) +.PP +These are intended to be services performed by the clients of this API. +.PP +This module attempts to be squeaky clean w.r.t \f(CW\*(C`use strict;\*(C'\fR and when +warnings are enabled. +.SS "Global Variables" +.IX Subsection "Global Variables" +The following "public" global names can be read by clients of this API. +Beware that these should be considered "readonly". +.ie n .IP $DB::sub 8 +.el .IP \f(CW$DB::sub\fR 8 +.IX Item "$DB::sub" +Name of current executing subroutine. +.ie n .IP %DB::sub 8 +.el .IP \f(CW%DB::sub\fR 8 +.IX Item "%DB::sub" +The keys of this hash are the names of all the known subroutines. Each value +is an encoded string that has the \fBsprintf\fR\|(3) format +\&\f(CW\*(C`("%s:%d\-%d", filename, fromline, toline)\*(C'\fR. +.ie n .IP $DB::single 8 +.el .IP \f(CW$DB::single\fR 8 +.IX Item "$DB::single" +Single-step flag. Will be true if the API will stop at the next statement. +.ie n .IP $DB::signal 8 +.el .IP \f(CW$DB::signal\fR 8 +.IX Item "$DB::signal" +Signal flag. Will be set to a true value if a signal was caught. Clients may +check for this flag to abort time-consuming operations. +.ie n .IP $DB::trace 8 +.el .IP \f(CW$DB::trace\fR 8 +.IX Item "$DB::trace" +This flag is set to true if the API is tracing through subroutine calls. +.ie n .IP @DB::args 8 +.el .IP \f(CW@DB::args\fR 8 +.IX Item "@DB::args" +Contains the arguments of current subroutine, or the \f(CW@ARGV\fR array if in the +toplevel context. +.ie n .IP @DB::dbline 8 +.el .IP \f(CW@DB::dbline\fR 8 +.IX Item "@DB::dbline" +List of lines in currently loaded file. +.ie n .IP %DB::dbline 8 +.el .IP \f(CW%DB::dbline\fR 8 +.IX Item "%DB::dbline" +Actions in current file (keys are line numbers). The values are strings that +have the \fBsprintf\fR\|(3) format \f(CW\*(C`("%s\e000%s", breakcondition, actioncode)\*(C'\fR. +.ie n .IP $DB::package 8 +.el .IP \f(CW$DB::package\fR 8 +.IX Item "$DB::package" +Package namespace of currently executing code. +.ie n .IP $DB::filename 8 +.el .IP \f(CW$DB::filename\fR 8 +.IX Item "$DB::filename" +Currently loaded filename. +.ie n .IP $DB::subname 8 +.el .IP \f(CW$DB::subname\fR 8 +.IX Item "$DB::subname" +Fully qualified name of currently executing subroutine. +.ie n .IP $DB::lineno 8 +.el .IP \f(CW$DB::lineno\fR 8 +.IX Item "$DB::lineno" +Line number that will be executed next. +.SS "API Methods" +.IX Subsection "API Methods" +The following are methods in the DB base class. A client must +access these methods by inheritance (*not* by calling them directly), +since the API keeps track of clients through the inheritance +mechanism. +.IP CLIENT\->\fBregister()\fR 8 +.IX Item "CLIENT->register()" +register a client object/package +.IP CLIENT\->evalcode(STRING) 8 +.IX Item "CLIENT->evalcode(STRING)" +eval STRING in executing code context +.IP CLIENT\->skippkg('D::hide') 8 +.IX Item "CLIENT->skippkg('D::hide')" +ask DB not to stop in these packages +.IP CLIENT\->\fBrun()\fR 8 +.IX Item "CLIENT->run()" +run some more (until a breakpt is reached) +.IP CLIENT\->\fBstep()\fR 8 +.IX Item "CLIENT->step()" +single step +.IP CLIENT\->\fBnext()\fR 8 +.IX Item "CLIENT->next()" +step over +.IP CLIENT\->\fBdone()\fR 8 +.IX Item "CLIENT->done()" +de-register from the debugging API +.SS "Client Callback Methods" +.IX Subsection "Client Callback Methods" +The following "virtual" methods can be defined by the client. They will +be called by the API at appropriate points. Note that unless specified +otherwise, the debug API only defines empty, non-functional default versions +of these methods. +.IP CLIENT\->\fBinit()\fR 8 +.IX Item "CLIENT->init()" +Called after debug API inits itself. +.IP CLIENT\->prestop([STRING]) 8 +.IX Item "CLIENT->prestop([STRING])" +Usually inherited from DB package. If no arguments are passed, +returns the prestop action string. +.IP CLIENT\->\fBstop()\fR 8 +.IX Item "CLIENT->stop()" +Called when execution stops (w/ args file, line). +.IP CLIENT\->\fBidle()\fR 8 +.IX Item "CLIENT->idle()" +Called while stopped (can be a client event loop). +.IP CLIENT\->poststop([STRING]) 8 +.IX Item "CLIENT->poststop([STRING])" +Usually inherited from DB package. If no arguments are passed, +returns the poststop action string. +.IP CLIENT\->evalcode(STRING) 8 +.IX Item "CLIENT->evalcode(STRING)" +Usually inherited from DB package. Ask for a STRING to be \f(CW\*(C`eval\*(C'\fR\-ed +in executing code context. +.IP CLIENT\->\fBcleanup()\fR 8 +.IX Item "CLIENT->cleanup()" +Called just before exit. +.IP CLIENT\->output(LIST) 8 +.IX Item "CLIENT->output(LIST)" +Called when API must show a message (warnings, errors etc.). +.SH BUGS +.IX Header "BUGS" +The interface defined by this module is missing some of the later additions +to perl's debugging functionality. As such, this interface should be considered +highly experimental and subject to change. +.SH AUTHOR +.IX Header "AUTHOR" +Gurusamy Sarathy gsar@activestate.com +.PP +This code heavily adapted from an early version of perl5db.pl attributable +to Larry Wall and the Perl Porters. -- cgit v1.2.3