Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 493 insertions, 0 deletions

diff --git a/upstream/mageia-cauldron/man3pm/DynaLoader.3pm b/upstream/mageia-cauldron/man3pm/DynaLoader.3pm
new file mode 100644
index 00000000..9b9e6b17
--- /dev/null
+++ b/upstream/mageia-cauldron/man3pm/DynaLoader.3pm
@@ -0,0 +1,493 @@
+.\" -*- 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 "DynaLoader 3pm"
+.TH DynaLoader 3pm 2023-12-15 "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
+DynaLoader \- Dynamically load C libraries into Perl code
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 4
+\&    package YourPackage;
+\&    require DynaLoader;
+\&    @ISA = qw(... DynaLoader ...);
+\&    _\|_PACKAGE_\|_\->bootstrap;
+\&
+\&    # optional method for \*(Aqglobal\*(Aq loading
+\&    sub dl_load_flags { 0x01 }
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document defines a standard generic interface to the dynamic
+linking mechanisms available on many platforms.  Its primary purpose is
+to implement automatic dynamic loading of Perl modules.
+.PP
+This document serves as both a specification for anyone wishing to
+implement the DynaLoader for a new platform and as a guide for
+anyone wishing to use the DynaLoader directly in an application.
+.PP
+The DynaLoader is designed to be a very simple high-level
+interface that is sufficiently general to cover the requirements
+of SunOS, HP-UX, Linux, VMS and other platforms.
+.PP
+It is also hoped that the interface will cover the needs of OS/2, NT
+etc and also allow pseudo-dynamic linking (using \f(CW\*(C`ld \-A\*(C'\fR at runtime).
+.PP
+It must be stressed that the DynaLoader, by itself, is practically
+useless for accessing non-Perl libraries because it provides almost no
+Perl-to-C 'glue'.  There is, for example, no mechanism for calling a C
+library function or supplying arguments.  A C::DynaLib module
+is available from CPAN sites which performs that function for some
+common system types.  And since the year 2000, there's also Inline::C,
+a module that allows you to write Perl subroutines in C.  Also available
+from your local CPAN site.
+.PP
+DynaLoader Interface Summary
+.PP
+.Vb 10
+\&  @dl_library_path
+\&  @dl_resolve_using
+\&  @dl_require_symbols
+\&  $dl_debug
+\&  $dl_dlext
+\&  @dl_librefs
+\&  @dl_modules
+\&  @dl_shared_objects
+\&                                                  Implemented in:
+\&  bootstrap($modulename)                               Perl
+\&  @filepaths = dl_findfile(@names)                     Perl
+\&  $flags = $modulename\->dl_load_flags                  Perl
+\&  $symref  = dl_find_symbol_anywhere($symbol)          Perl
+\&
+\&  $libref  = dl_load_file($filename, $flags)           C
+\&  $status  = dl_unload_file($libref)                   C
+\&  $symref  = dl_find_symbol($libref, $symbol)          C
+\&  @symbols = dl_undef_symbols()                        C
+\&  dl_install_xsub($name, $symref [, $filename])        C
+\&  $message = dl_error                                  C
+.Ve
+.ie n .IP @dl_library_path 4
+.el .IP \f(CW@dl_library_path\fR 4
+.IX Item "@dl_library_path"
+The standard/default list of directories in which \fBdl_findfile()\fR will
+search for libraries etc.  Directories are searched in order:
+\&\f(CW$dl_library_path\fR[0], [1], ... etc
+.Sp
+\&\f(CW@dl_library_path\fR is initialised to hold the list of 'normal' directories
+(\fI/usr/lib\fR, etc) determined by \fBConfigure\fR (\f(CW$Config{\*(Aqlibpth\*(Aq}\fR).  This should
+ensure portability across a wide range of platforms.
+.Sp
+\&\f(CW@dl_library_path\fR should also be initialised with any other directories
+that can be determined from the environment at runtime (such as
+LD_LIBRARY_PATH for SunOS).
+.Sp
+After initialisation \f(CW@dl_library_path\fR can be manipulated by an
+application using push and unshift before calling \fBdl_findfile()\fR.
+Unshift can be used to add directories to the front of the search order
+either to save search time or to override libraries with the same name
+in the 'normal' directories.
+.Sp
+The load function that \fBdl_load_file()\fR calls may require an absolute
+pathname.  The \fBdl_findfile()\fR function and \f(CW@dl_library_path\fR can be
+used to search for and return the absolute pathname for the
+library/object that you wish to load.
+.ie n .IP @dl_resolve_using 4
+.el .IP \f(CW@dl_resolve_using\fR 4
+.IX Item "@dl_resolve_using"
+A list of additional libraries or other shared objects which can be
+used to resolve any undefined symbols that might be generated by a
+later call to \fBload_file()\fR.
+.Sp
+This is only required on some platforms which do not handle dependent
+libraries automatically.  For example the Socket Perl extension
+library (\fIauto/Socket/Socket.so\fR) contains references to many socket
+functions which need to be resolved when it's loaded.  Most platforms
+will automatically know where to find the 'dependent' library (e.g.,
+\&\fI/usr/lib/libsocket.so\fR).  A few platforms need to be told the
+location of the dependent library explicitly.  Use \f(CW@dl_resolve_using\fR
+for this.
+.Sp
+Example usage:
+.Sp
+.Vb 1
+\&    @dl_resolve_using = dl_findfile(\*(Aq\-lsocket\*(Aq);
+.Ve
+.ie n .IP @dl_require_symbols 4
+.el .IP \f(CW@dl_require_symbols\fR 4
+.IX Item "@dl_require_symbols"
+A list of one or more symbol names that are in the library/object file
+to be dynamically loaded.  This is only required on some platforms.
+.ie n .IP @dl_librefs 4
+.el .IP \f(CW@dl_librefs\fR 4
+.IX Item "@dl_librefs"
+An array of the handles returned by successful calls to \fBdl_load_file()\fR,
+made by bootstrap, in the order in which they were loaded.
+Can be used with \fBdl_find_symbol()\fR to look for a symbol in any of
+the loaded files.
+.ie n .IP @dl_modules 4
+.el .IP \f(CW@dl_modules\fR 4
+.IX Item "@dl_modules"
+An array of module (package) names that have been bootstrap'ed.
+.ie n .IP @dl_shared_objects 4
+.el .IP \f(CW@dl_shared_objects\fR 4
+.IX Item "@dl_shared_objects"
+An array of file names for the shared objects that were loaded.
+.IP \fBdl_error()\fR 4
+.IX Item "dl_error()"
+Syntax:
+.Sp
+.Vb 1
+\&    $message = dl_error();
+.Ve
+.Sp
+Error message text from the last failed DynaLoader function.  Note
+that, similar to errno in unix, a successful function call does not
+reset this message.
+.Sp
+Implementations should detect the error as soon as it occurs in any of
+the other functions and save the corresponding message for later
+retrieval.  This will avoid problems on some platforms (such as SunOS)
+where the error message is very temporary (e.g., \fBdlerror()\fR).
+.ie n .IP $dl_debug 4
+.el .IP \f(CW$dl_debug\fR 4
+.IX Item "$dl_debug"
+Internal debugging messages are enabled when \f(CW$dl_debug\fR is set true.
+Currently setting \f(CW$dl_debug\fR only affects the Perl side of the
+DynaLoader.  These messages should help an application developer to
+resolve any DynaLoader usage problems.
+.Sp
+\&\f(CW$dl_debug\fR is set to \f(CW$ENV{\*(AqPERL_DL_DEBUG\*(Aq}\fR if defined.
+.Sp
+For the DynaLoader developer/porter there is a similar debugging
+variable added to the C code (see dlutils.c) and enabled if Perl was
+built with the \fB\-DDEBUGGING\fR flag.  This can also be set via the
+PERL_DL_DEBUG environment variable.  Set to 1 for minimal information or
+higher for more.
+.ie n .IP $dl_dlext 4
+.el .IP \f(CW$dl_dlext\fR 4
+.IX Item "$dl_dlext"
+When specified (localised) in a module's \fI.pm\fR file, indicates the extension
+which the module's loadable object will have. For example:
+.Sp
+.Vb 1
+\&    local $DynaLoader::dl_dlext = \*(Aqunusual_ext\*(Aq;
+.Ve
+.Sp
+would indicate that the module's loadable object has an extension of
+\&\f(CW\*(C`unusual_ext\*(C'\fR instead of the more usual \f(CW$Config{dlext}\fR.  NOTE: This also
+requires that the module's \fIMakefile.PL\fR specify (in \f(CWWriteMakefile()\fR):
+.Sp
+.Vb 1
+\&    DLEXT => \*(Aqunusual_ext\*(Aq,
+.Ve
+.IP \fBdl_findfile()\fR 4
+.IX Item "dl_findfile()"
+Syntax:
+.Sp
+.Vb 1
+\&    @filepaths = dl_findfile(@names)
+.Ve
+.Sp
+Determine the full paths (including file suffix) of one or more
+loadable files given their generic names and optionally one or more
+directories.  Searches directories in \f(CW@dl_library_path\fR by default and
+returns an empty list if no files were found.
+.Sp
+Names can be specified in a variety of platform independent forms.  Any
+names in the form \fB\-lname\fR are converted into \fIlibname.*\fR, where \fI.*\fR is
+an appropriate suffix for the platform.
+.Sp
+If a name does not already have a suitable prefix and/or suffix then
+the corresponding file will be searched for by trying combinations of
+prefix and suffix appropriate to the platform: "$name.o", "lib$name.*"
+and "$name".
+.Sp
+If any directories are included in \f(CW@names\fR they are searched before
+\&\f(CW@dl_library_path\fR.  Directories may be specified as \fB\-Ldir\fR.  Any other
+names are treated as filenames to be searched for.
+.Sp
+Using arguments of the form \f(CW\*(C`\-Ldir\*(C'\fR and \f(CW\*(C`\-lname\*(C'\fR is recommended.
+.Sp
+Example:
+.Sp
+.Vb 1
+\&    @dl_resolve_using = dl_findfile(qw(\-L/usr/5lib \-lposix));
+.Ve
+.IP \fBdl_expandspec()\fR 4
+.IX Item "dl_expandspec()"
+Syntax:
+.Sp
+.Vb 1
+\&    $filepath = dl_expandspec($spec)
+.Ve
+.Sp
+Some unusual systems, such as VMS, require special filename handling in
+order to deal with symbolic names for files (i.e., VMS's Logical Names).
+.Sp
+To support these systems a \fBdl_expandspec()\fR function can be implemented
+either in the \fIdl_*.xs\fR file or code can be added to the \fBdl_expandspec()\fR
+function in \fIDynaLoader.pm\fR.  See \fIDynaLoader_pm.PL\fR for more information.
+.IP \fBdl_load_file()\fR 4
+.IX Item "dl_load_file()"
+Syntax:
+.Sp
+.Vb 1
+\&    $libref = dl_load_file($filename, $flags)
+.Ve
+.Sp
+Dynamically load \f(CW$filename\fR, which must be the path to a shared object
+or library.  An opaque 'library reference' is returned as a handle for
+the loaded object.  Returns undef on error.
+.Sp
+The \f(CW$flags\fR argument to alters dl_load_file behaviour.  
+Assigned bits:
+.Sp
+.Vb 3
+\& 0x01  make symbols available for linking later dl_load_file\*(Aqs.
+\&       (only known to work on Solaris 2 using dlopen(RTLD_GLOBAL))
+\&       (ignored under VMS; this is a normal part of image linking)
+.Ve
+.Sp
+(On systems that provide a handle for the loaded object such as SunOS
+and HPUX, \f(CW$libref\fR will be that handle.  On other systems \f(CW$libref\fR will
+typically be \f(CW$filename\fR or a pointer to a buffer containing \f(CW$filename\fR.
+The application should not examine or alter \f(CW$libref\fR in any way.)
+.Sp
+This is the function that does the real work.  It should use the
+current values of \f(CW@dl_require_symbols\fR and \f(CW@dl_resolve_using\fR if required.
+.Sp
+.Vb 4
+\&    SunOS: dlopen($filename)
+\&    HP\-UX: shl_load($filename)
+\&    Linux: dld_create_reference(@dl_require_symbols); dld_link($filename)
+\&    VMS:   lib$find_image_symbol($filename,$dl_require_symbols[0])
+.Ve
+.Sp
+(The \fBdlopen()\fR function is also used by Solaris and some versions of
+Linux, and is a common choice when providing a "wrapper" on other
+mechanisms as is done in the OS/2 port.)
+.IP \fBdl_unload_file()\fR 4
+.IX Item "dl_unload_file()"
+Syntax:
+.Sp
+.Vb 1
+\&    $status = dl_unload_file($libref)
+.Ve
+.Sp
+Dynamically unload \f(CW$libref\fR, which must be an opaque 'library reference' as
+returned from dl_load_file.  Returns one on success and zero on failure.
+This function is optional and may not necessarily be provided on all platforms.
+.Sp
+If it is defined and perl is compiled with the C macro \f(CW\*(C`DL_UNLOAD_ALL_AT_EXIT\*(C'\fR
+defined, then it is called automatically when the interpreter exits for
+every shared object or library loaded by DynaLoader::bootstrap.  All such
+library references are stored in \f(CW@dl_librefs\fR by DynaLoader::Bootstrap as it
+loads the libraries.  The files are unloaded in last-in, first-out order.
+.Sp
+This unloading is usually necessary when embedding a shared-object perl (e.g.
+one configured with \-Duseshrplib) within a larger application, and the perl
+interpreter is created and destroyed several times within the lifetime of the
+application.  In this case it is possible that the system dynamic linker will
+unload and then subsequently reload the shared libperl without relocating any
+references to it from any files DynaLoaded by the previous incarnation of the
+interpreter.  As a result, any shared objects opened by DynaLoader may point to
+a now invalid 'ghost' of the libperl shared object, causing apparently random
+memory corruption and crashes.  This behaviour is most commonly seen when using
+Apache and mod_perl built with the APXS mechanism.
+.Sp
+.Vb 4
+\&    SunOS: dlclose($libref)
+\&    HP\-UX: ???
+\&    Linux: ???
+\&    VMS:   ???
+.Ve
+.Sp
+(The \fBdlclose()\fR function is also used by Solaris and some versions of
+Linux, and is a common choice when providing a "wrapper" on other
+mechanisms as is done in the OS/2 port.)
+.IP \fBdl_load_flags()\fR 4
+.IX Item "dl_load_flags()"
+Syntax:
+.Sp
+.Vb 1
+\&    $flags = dl_load_flags $modulename;
+.Ve
+.Sp
+Designed to be a method call, and to be overridden by a derived class
+(i.e. a class which has DynaLoader in its \f(CW@ISA\fR).  The definition in
+DynaLoader itself returns 0, which produces standard behavior from
+\&\fBdl_load_file()\fR.
+.IP \fBdl_find_symbol()\fR 4
+.IX Item "dl_find_symbol()"
+Syntax:
+.Sp
+.Vb 1
+\&    $symref = dl_find_symbol($libref, $symbol)
+.Ve
+.Sp
+Return the address of the symbol \f(CW$symbol\fR or \f(CW\*(C`undef\*(C'\fR if not found.  If the
+target system has separate functions to search for symbols of different
+types then \fBdl_find_symbol()\fR should search for function symbols first and
+then other types.
+.Sp
+The exact manner in which the address is returned in \f(CW$symref\fR is not
+currently defined.  The only initial requirement is that \f(CW$symref\fR can
+be passed to, and understood by, \fBdl_install_xsub()\fR.
+.Sp
+.Vb 4
+\&    SunOS: dlsym($libref, $symbol)
+\&    HP\-UX: shl_findsym($libref, $symbol)
+\&    Linux: dld_get_func($symbol) and/or dld_get_symbol($symbol)
+\&    VMS:   lib$find_image_symbol($libref,$symbol)
+.Ve
+.IP \fBdl_find_symbol_anywhere()\fR 4
+.IX Item "dl_find_symbol_anywhere()"
+Syntax:
+.Sp
+.Vb 1
+\&    $symref = dl_find_symbol_anywhere($symbol)
+.Ve
+.Sp
+Applies \fBdl_find_symbol()\fR to the members of \f(CW@dl_librefs\fR and returns
+the first match found.
+.IP \fBdl_undef_symbols()\fR 4
+.IX Item "dl_undef_symbols()"
+Example
+.Sp
+.Vb 1
+\&    @symbols = dl_undef_symbols()
+.Ve
+.Sp
+Return a list of symbol names which remain undefined after \fBload_file()\fR.
+Returns \f(CW\*(C`()\*(C'\fR if not known.  Don't worry if your platform does not provide
+a mechanism for this.  Most do not need it and hence do not provide it,
+they just return an empty list.
+.IP \fBdl_install_xsub()\fR 4
+.IX Item "dl_install_xsub()"
+Syntax:
+.Sp
+.Vb 1
+\&    dl_install_xsub($perl_name, $symref [, $filename])
+.Ve
+.Sp
+Create a new Perl external subroutine named \f(CW$perl_name\fR using \f(CW$symref\fR as
+a pointer to the function which implements the routine.  This is simply
+a direct call to \fBnewXS()\fR/\fBnewXS_flags()\fR.  Returns a reference to the installed
+function.
+.Sp
+The \f(CW$filename\fR parameter is used by Perl to identify the source file for
+the function if required by \fBdie()\fR, \fBcaller()\fR or the debugger.  If
+\&\f(CW$filename\fR is not defined then "DynaLoader" will be used.
+.IP \fBbootstrap()\fR 4
+.IX Item "bootstrap()"
+Syntax:
+.Sp
+bootstrap($module [...])
+.Sp
+This is the normal entry point for automatic dynamic loading in Perl.
+.Sp
+It performs the following actions:
+.RS 4
+.IP \(bu 8
+locates an auto/$module directory by searching \f(CW@INC\fR
+.IP \(bu 8
+uses \fBdl_findfile()\fR to determine the filename to load
+.IP \(bu 8
+sets \f(CW@dl_require_symbols\fR to \f(CW\*(C`("boot_$module")\*(C'\fR
+.IP \(bu 8
+executes an \fIauto/$module/$module.bs\fR file if it exists
+(typically used to add to \f(CW@dl_resolve_using\fR any files which
+are required to load the module on the current platform)
+.IP \(bu 8
+calls \fBdl_load_flags()\fR to determine how to load the file.
+.IP \(bu 8
+calls \fBdl_load_file()\fR to load the file
+.IP \(bu 8
+calls \fBdl_undef_symbols()\fR and warns if any symbols are undefined
+.IP \(bu 8
+calls \fBdl_find_symbol()\fR for "boot_$module"
+.IP \(bu 8
+calls \fBdl_install_xsub()\fR to install it as "${module}::bootstrap"
+.IP \(bu 8
+calls &{"${module}::bootstrap"} to bootstrap the module (actually
+it uses the function reference returned by dl_install_xsub for speed)
+.RE
+.RS 4
+.Sp
+All arguments to \fBbootstrap()\fR are passed to the module's bootstrap function.
+The default code generated by \fIxsubpp\fR expects \f(CW$module\fR [, \f(CW$version\fR]
+If the optional \f(CW$version\fR argument is not given, it defaults to
+\&\f(CW\*(C`$XS_VERSION // $VERSION\*(C'\fR in the module's symbol table. The default code
+compares the Perl-space version with the version of the compiled XS code,
+and croaks with an error if they do not match.
+.RE
+.SH AUTHOR
+.IX Header "AUTHOR"
+Tim Bunce, 11 August 1994.
+.PP
+This interface is based on the work and comments of (in no particular
+order): Larry Wall, Robert Sanders, Dean Roehrich, Jeff Okamoto, Anno
+Siegel, Thomas Neumann, Paul Marquess, Charles Bailey, myself and others.
+.PP
+Larry Wall designed the elegant inherited bootstrap mechanism and
+implemented the first Perl 5 dynamic loader using it.
+.PP
+Solaris global loading added by Nick Ing-Simmons with design/coding
+assistance from Tim Bunce, January 1996.