summaryrefslogtreecommitdiffstats
path: root/upstream/archlinux/man3/DB.3perl
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-15 19:43:11 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-15 19:43:11 +0000
commitfc22b3d6507c6745911b9dfcc68f1e665ae13dbc (patch)
treece1e3bce06471410239a6f41282e328770aa404a /upstream/archlinux/man3/DB.3perl
parentInitial commit. (diff)
downloadmanpages-l10n-fc22b3d6507c6745911b9dfcc68f1e665ae13dbc.tar.xz
manpages-l10n-fc22b3d6507c6745911b9dfcc68f1e665ae13dbc.zip
Adding upstream version 4.22.0.upstream/4.22.0
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'upstream/archlinux/man3/DB.3perl')
-rw-r--r--upstream/archlinux/man3/DB.3perl268
1 files changed, 268 insertions, 0 deletions
diff --git a/upstream/archlinux/man3/DB.3perl b/upstream/archlinux/man3/DB.3perl
new file mode 100644
index 00000000..85625914
--- /dev/null
+++ b/upstream/archlinux/man3/DB.3perl
@@ -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 3perl"
+.TH DB 3perl 2024-02-11 "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.