Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 303 insertions, 0 deletions

diff --git a/upstream/archlinux/man3/AutoLoader.3perl b/upstream/archlinux/man3/AutoLoader.3perl
new file mode 100644
index 00000000..c8ce437f
--- /dev/null
+++ b/upstream/archlinux/man3/AutoLoader.3perl
@@ -0,0 +1,303 @@
+.\" -*- 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 "AutoLoader 3perl"
+.TH AutoLoader 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
+AutoLoader \- load subroutines only on demand
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 2
+\&    package Foo;
+\&    use AutoLoader \*(AqAUTOLOAD\*(Aq;   # import the default AUTOLOAD subroutine
+\&
+\&    package Bar;
+\&    use AutoLoader;              # don\*(Aqt import AUTOLOAD, define our own
+\&    sub AUTOLOAD {
+\&        ...
+\&        $AutoLoader::AUTOLOAD = "...";
+\&        goto &AutoLoader::AUTOLOAD;
+\&    }
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+The \fBAutoLoader\fR module works with the \fBAutoSplit\fR module and the
+\&\f(CW\*(C`_\|_END_\|_\*(C'\fR token to defer the loading of some subroutines until they are
+used rather than loading them all at once.
+.PP
+To use \fBAutoLoader\fR, the author of a module has to place the
+definitions of subroutines to be autoloaded after an \f(CW\*(C`_\|_END_\|_\*(C'\fR token.
+(See perldata.)  The \fBAutoSplit\fR module can then be run manually to
+extract the definitions into individual files \fIauto/funcname.al\fR.
+.PP
+\&\fBAutoLoader\fR implements an AUTOLOAD subroutine.  When an undefined
+subroutine in is called in a client module of \fBAutoLoader\fR,
+\&\fBAutoLoader\fR's AUTOLOAD subroutine attempts to locate the subroutine in a
+file with a name related to the location of the file from which the
+client module was read.  As an example, if \fIPOSIX.pm\fR is located in
+\&\fI/usr/local/lib/perl5/POSIX.pm\fR, \fBAutoLoader\fR will look for perl
+subroutines \fBPOSIX\fR in \fI/usr/local/lib/perl5/auto/POSIX/*.al\fR, where
+the \f(CW\*(C`.al\*(C'\fR file has the same name as the subroutine, sans package.  If
+such a file exists, AUTOLOAD will read and evaluate it,
+thus (presumably) defining the needed subroutine.  AUTOLOAD will then
+\&\f(CW\*(C`goto\*(C'\fR the newly defined subroutine.
+.PP
+Once this process completes for a given function, it is defined, so
+future calls to the subroutine will bypass the AUTOLOAD mechanism.
+.SS "Subroutine Stubs"
+.IX Subsection "Subroutine Stubs"
+In order for object method lookup and/or prototype checking to operate
+correctly even when methods have not yet been defined it is necessary to
+"forward declare" each subroutine (as in \f(CW\*(C`sub NAME;\*(C'\fR).  See
+"SYNOPSIS" in perlsub.  Such forward declaration creates "subroutine
+stubs", which are place holders with no code.
+.PP
+The AutoSplit and \fBAutoLoader\fR modules automate the creation of forward
+declarations.  The AutoSplit module creates an 'index' file containing
+forward declarations of all the AutoSplit subroutines.  When the
+AutoLoader module is 'use'd it loads these declarations into its callers
+package.
+.PP
+Because of this mechanism it is important that \fBAutoLoader\fR is always
+\&\f(CW\*(C`use\*(C'\fRd and not \f(CW\*(C`require\*(C'\fRd.
+.SS "Using \fBAutoLoader\fP's AUTOLOAD Subroutine"
+.IX Subsection "Using AutoLoader's AUTOLOAD Subroutine"
+In order to use \fBAutoLoader\fR's AUTOLOAD subroutine you \fImust\fR
+explicitly import it:
+.PP
+.Vb 1
+\&    use AutoLoader \*(AqAUTOLOAD\*(Aq;
+.Ve
+.SS "Overriding \fBAutoLoader\fP's AUTOLOAD Subroutine"
+.IX Subsection "Overriding AutoLoader's AUTOLOAD Subroutine"
+Some modules, mainly extensions, provide their own AUTOLOAD subroutines.
+They typically need to check for some special cases (such as constants)
+and then fallback to \fBAutoLoader\fR's AUTOLOAD for the rest.
+.PP
+Such modules should \fInot\fR import \fBAutoLoader\fR's AUTOLOAD subroutine.
+Instead, they should define their own AUTOLOAD subroutines along these
+lines:
+.PP
+.Vb 2
+\&    use AutoLoader;
+\&    use Carp;
+\&
+\&    sub AUTOLOAD {
+\&        my $sub = $AUTOLOAD;
+\&        (my $constname = $sub) =~ s/.*:://;
+\&        my $val = constant($constname, @_ ? $_[0] : 0);
+\&        if ($! != 0) {
+\&            if ($! =~ /Invalid/ || $!{EINVAL}) {
+\&                $AutoLoader::AUTOLOAD = $sub;
+\&                goto &AutoLoader::AUTOLOAD;
+\&            }
+\&            else {
+\&                croak "Your vendor has not defined constant $constname";
+\&            }
+\&        }
+\&        *$sub = sub { $val }; # same as: eval "sub $sub { $val }";
+\&        goto &$sub;
+\&    }
+.Ve
+.PP
+If any module's own AUTOLOAD subroutine has no need to fallback to the
+AutoLoader's AUTOLOAD subroutine (because it doesn't have any AutoSplit
+subroutines), then that module should not use \fBAutoLoader\fR at all.
+.SS "Package Lexicals"
+.IX Subsection "Package Lexicals"
+Package lexicals declared with \f(CW\*(C`my\*(C'\fR in the main block of a package
+using \fBAutoLoader\fR will not be visible to auto-loaded subroutines, due to
+the fact that the given scope ends at the \f(CW\*(C`_\|_END_\|_\*(C'\fR marker.  A module
+using such variables as package globals will not work properly under the
+\&\fBAutoLoader\fR.
+.PP
+The \f(CW\*(C`vars\*(C'\fR pragma (see "vars" in perlmod) may be used in such
+situations as an alternative to explicitly qualifying all globals with
+the package namespace.  Variables pre-declared with this pragma will be
+visible to any autoloaded routines (but will not be invisible outside
+the package, unfortunately).
+.SS "Not Using AutoLoader"
+.IX Subsection "Not Using AutoLoader"
+You can stop using AutoLoader by simply
+.PP
+.Vb 1
+\&        no AutoLoader;
+.Ve
+.SS "\fBAutoLoader\fP vs. \fBSelfLoader\fP"
+.IX Subsection "AutoLoader vs. SelfLoader"
+The \fBAutoLoader\fR is similar in purpose to \fBSelfLoader\fR: both delay the
+loading of subroutines.
+.PP
+\&\fBSelfLoader\fR uses the \f(CW\*(C`_\|_DATA_\|_\*(C'\fR marker rather than \f(CW\*(C`_\|_END_\|_\*(C'\fR.
+While this avoids the use of a hierarchy of disk files and the
+associated open/close for each routine loaded, \fBSelfLoader\fR suffers a
+startup speed disadvantage in the one-time parsing of the lines after
+\&\f(CW\*(C`_\|_DATA_\|_\*(C'\fR, after which routines are cached.  \fBSelfLoader\fR can also
+handle multiple packages in a file.
+.PP
+\&\fBAutoLoader\fR only reads code as it is requested, and in many cases
+should be faster, but requires a mechanism like \fBAutoSplit\fR be used to
+create the individual files.  ExtUtils::MakeMaker will invoke
+\&\fBAutoSplit\fR automatically if \fBAutoLoader\fR is used in a module source
+file.
+.SS "Forcing AutoLoader to Load a Function"
+.IX Subsection "Forcing AutoLoader to Load a Function"
+Sometimes, it can be necessary or useful to make sure that a certain
+function is fully loaded by AutoLoader. This is the case, for example,
+when you need to wrap a function to inject debugging code. It is also
+helpful to force early loading of code before forking to make use of
+copy-on-write as much as possible.
+.PP
+Starting with AutoLoader 5.73, you can call the
+\&\f(CW\*(C`AutoLoader::autoload_sub\*(C'\fR function with the fully-qualified name of
+the function to load from its \fI.al\fR file. The behaviour is exactly
+the same as if you called the function, triggering the regular
+\&\f(CW\*(C`AUTOLOAD\*(C'\fR mechanism, but it does not actually execute the
+autoloaded function.
+.SH CAVEATS
+.IX Header "CAVEATS"
+AutoLoaders prior to Perl 5.002 had a slightly different interface.  Any
+old modules which use \fBAutoLoader\fR should be changed to the new calling
+style.  Typically this just means changing a require to a use, adding
+the explicit \f(CW\*(AqAUTOLOAD\*(Aq\fR import if needed, and removing \fBAutoLoader\fR
+from \f(CW@ISA\fR.
+.PP
+On systems with restrictions on file name length, the file corresponding
+to a subroutine may have a shorter name that the routine itself.  This
+can lead to conflicting file names.  The \fIAutoSplit\fR package warns of
+these potential conflicts when used to split a module.
+.PP
+AutoLoader may fail to find the autosplit files (or even find the wrong
+ones) in cases where \f(CW@INC\fR contains relative paths, \fBand\fR the program
+does \f(CW\*(C`chdir\*(C'\fR.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+SelfLoader \- an autoloader that doesn't use external files.
+.SH AUTHOR
+.IX Header "AUTHOR"
+\&\f(CW\*(C`AutoLoader\*(C'\fR is maintained by the perl5\-porters. Please direct
+any questions to the canonical mailing list. Anything that
+is applicable to the CPAN release can be sent to its maintainer,
+though.
+.PP
+Author and Maintainer: The Perl5\-Porters <perl5\-porters@perl.org>
+.PP
+Maintainer of the CPAN release: Steffen Mueller <smueller@cpan.org>
+.SH "COPYRIGHT AND LICENSE"
+.IX Header "COPYRIGHT AND LICENSE"
+This package has been part of the perl core since the first release
+of perl5. It has been released separately to CPAN so older installations
+can benefit from bug fixes.
+.PP
+This package has the same copyright and license as the perl core:
+.PP
+.Vb 4
+\&             Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999,
+\&        2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
+\&        2011, 2012, 2013
+\&        by Larry Wall and others
+\&    
+\&                            All rights reserved.
+\&    
+\&    This program is free software; you can redistribute it and/or modify
+\&    it under the terms of either:
+\&    
+\&        a) the GNU General Public License as published by the Free
+\&        Software Foundation; either version 1, or (at your option) any
+\&        later version, or
+\&    
+\&        b) the "Artistic License" which comes with this Kit.
+\&    
+\&    This program is distributed in the hope that it will be useful,
+\&    but WITHOUT ANY WARRANTY; without even the implied warranty of
+\&    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See either
+\&    the GNU General Public License or the Artistic License for more details.
+\&    
+\&    You should have received a copy of the Artistic License with this
+\&    Kit, in the file named "Artistic".  If not, I\*(Aqll be glad to provide one.
+\&    
+\&    You should also have received a copy of the GNU General Public License
+\&    along with this program in the file named "Copying". If not, write to the 
+\&    Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston,
+\&    MA 02110\-1301, USA or visit their web page on the internet at
+\&    http://www.gnu.org/copyleft/gpl.html.
+\&    
+\&    For those of you that choose to use the GNU General Public License,
+\&    my interpretation of the GNU General Public License is that no Perl
+\&    script falls under the terms of the GPL unless you explicitly put
+\&    said script under the terms of the GPL yourself.  Furthermore, any
+\&    object code linked with perl does not automatically fall under the
+\&    terms of the GPL, provided such object code only adds definitions
+\&    of subroutines and variables, and does not otherwise impair the
+\&    resulting interpreter from executing any standard Perl script.  I
+\&    consider linking in C subroutines in this manner to be the moral
+\&    equivalent of defining subroutines in the Perl language itself.  You
+\&    may sell such an object file as proprietary provided that you provide
+\&    or offer to provide the Perl source, as specified by the GNU General
+\&    Public License.  (This is merely an alternate way of specifying input
+\&    to the program.)  You may also sell a binary produced by the dumping of
+\&    a running Perl script that belongs to you, provided that you provide or
+\&    offer to provide the Perl source as specified by the GPL.  (The
+\&    fact that a Perl interpreter and your code are in the same binary file
+\&    is, in this case, a form of mere aggregation.)  This is my interpretation
+\&    of the GPL.  If you still have concerns or difficulties understanding
+\&    my intent, feel free to contact me.  Of course, the Artistic License
+\&    spells all this out for your protection, so you may prefer to use that.
+.Ve