Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 268 insertions, 0 deletions

diff --git a/upstream/debian-unstable/man3/DB.3perl b/upstream/debian-unstable/man3/DB.3perl
new file mode 100644
index 00000000..3366d807
--- /dev/null
+++ b/upstream/debian-unstable/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-01-12 "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.