Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 388 insertions, 0 deletions

diff --git a/upstream/mageia-cauldron/man3pm/File::Fetch.3pm b/upstream/mageia-cauldron/man3pm/File::Fetch.3pm
new file mode 100644
index 00000000..9b4c78aa
--- /dev/null
+++ b/upstream/mageia-cauldron/man3pm/File::Fetch.3pm
@@ -0,0 +1,388 @@
+.\" -*- 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 "File::Fetch 3pm"
+.TH File::Fetch 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
+File::Fetch \- A generic file fetching mechanism
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 1
+\&    use File::Fetch;
+\&
+\&    ### build a File::Fetch object ###
+\&    my $ff = File::Fetch\->new(uri => \*(Aqhttp://some.where.com/dir/a.txt\*(Aq);
+\&
+\&    ### fetch the uri to cwd() ###
+\&    my $where = $ff\->fetch() or die $ff\->error;
+\&
+\&    ### fetch the uri to /tmp ###
+\&    my $where = $ff\->fetch( to => \*(Aq/tmp\*(Aq );
+\&
+\&    ### parsed bits from the uri ###
+\&    $ff\->uri;
+\&    $ff\->scheme;
+\&    $ff\->host;
+\&    $ff\->path;
+\&    $ff\->file;
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+File::Fetch is a generic file fetching mechanism.
+.PP
+It allows you to fetch any file pointed to by a \f(CW\*(C`ftp\*(C'\fR, \f(CW\*(C`http\*(C'\fR,
+\&\f(CW\*(C`file\*(C'\fR, \f(CW\*(C`git\*(C'\fR or \f(CW\*(C`rsync\*(C'\fR uri by a number of different means.
+.PP
+See the \f(CW\*(C`HOW IT WORKS\*(C'\fR section further down for details.
+.SH ACCESSORS
+.IX Header "ACCESSORS"
+A \f(CW\*(C`File::Fetch\*(C'\fR object has the following accessors
+.ie n .IP $ff\->uri 4
+.el .IP \f(CW$ff\fR\->uri 4
+.IX Item "$ff->uri"
+The uri you passed to the constructor
+.ie n .IP $ff\->scheme 4
+.el .IP \f(CW$ff\fR\->scheme 4
+.IX Item "$ff->scheme"
+The scheme from the uri (like 'file', 'http', etc)
+.ie n .IP $ff\->host 4
+.el .IP \f(CW$ff\fR\->host 4
+.IX Item "$ff->host"
+The hostname in the uri.  Will be empty if host was originally
+\&'localhost' for a 'file://' url.
+.ie n .IP $ff\->vol 4
+.el .IP \f(CW$ff\fR\->vol 4
+.IX Item "$ff->vol"
+On operating systems with the concept of a volume the second element
+of a file:// is considered to the be volume specification for the file.
+Thus on Win32 this routine returns the volume, on other operating
+systems this returns nothing.
+.Sp
+On Windows this value may be empty if the uri is to a network share, in
+which case the 'share' property will be defined. Additionally, volume
+specifications that use '|' as ':' will be converted on read to use ':'.
+.Sp
+On VMS, which has a volume concept, this field will be empty because VMS
+file specifications are converted to absolute UNIX format and the volume
+information is transparently included.
+.ie n .IP $ff\->share 4
+.el .IP \f(CW$ff\fR\->share 4
+.IX Item "$ff->share"
+On systems with the concept of a network share (currently only Windows) returns
+the sharename from a file://// url.  On other operating systems returns empty.
+.ie n .IP $ff\->path 4
+.el .IP \f(CW$ff\fR\->path 4
+.IX Item "$ff->path"
+The path from the uri, will be at least a single '/'.
+.ie n .IP $ff\->file 4
+.el .IP \f(CW$ff\fR\->file 4
+.IX Item "$ff->file"
+The name of the remote file. For the local file name, the
+result of \f(CW$ff\fR\->output_file will be used.
+.ie n .IP $ff\->file_default 4
+.el .IP \f(CW$ff\fR\->file_default 4
+.IX Item "$ff->file_default"
+The name of the default local file, that \f(CW$ff\fR\->output_file falls back to if
+it would otherwise return no filename. For example when fetching a URI like
+http://www.abc.net.au/ the contents retrieved may be from a remote file called
+\&'index.html'. The default value of this attribute is literally 'file_default'.
+.ie n .IP $ff\->output_file 4
+.el .IP \f(CW$ff\fR\->output_file 4
+.IX Item "$ff->output_file"
+The name of the output file. This is the same as \f(CW$ff\fR\->file,
+but any query parameters are stripped off. For example:
+.Sp
+.Vb 1
+\&    http://example.com/index.html?x=y
+.Ve
+.Sp
+would make the output file be \f(CW\*(C`index.html\*(C'\fR rather than
+\&\f(CW\*(C`index.html?x=y\*(C'\fR.
+.SH METHODS
+.IX Header "METHODS"
+.ie n .SS "$ff = File::Fetch\->new( uri => 'http://some.where.com/dir/file.txt' );"
+.el .SS "\f(CW$ff\fP = File::Fetch\->new( uri => 'http://some.where.com/dir/file.txt' );"
+.IX Subsection "$ff = File::Fetch->new( uri => 'http://some.where.com/dir/file.txt' );"
+Parses the uri and creates a corresponding File::Fetch::Item object,
+that is ready to be \f(CW\*(C`fetch\*(C'\fRed and returns it.
+.PP
+Returns false on failure.
+.ie n .SS "$where = $ff\->fetch( [to => /my/output/dir/ | \e$scalar] )"
+.el .SS "\f(CW$where\fP = \f(CW$ff\fP\->fetch( [to => /my/output/dir/ | \e$scalar] )"
+.IX Subsection "$where = $ff->fetch( [to => /my/output/dir/ | $scalar] )"
+Fetches the file you requested and returns the full path to the file.
+.PP
+By default it writes to \f(CWcwd()\fR, but you can override that by specifying
+the \f(CW\*(C`to\*(C'\fR argument:
+.PP
+.Vb 2
+\&    ### file fetch to /tmp, full path to the file in $where
+\&    $where = $ff\->fetch( to => \*(Aq/tmp\*(Aq );
+\&
+\&    ### file slurped into $scalar, full path to the file in $where
+\&    ### file is downloaded to a temp directory and cleaned up at exit time
+\&    $where = $ff\->fetch( to => \e$scalar );
+.Ve
+.PP
+Returns the full path to the downloaded file on success, and false
+on failure.
+.ie n .SS $ff\->error([BOOL])
+.el .SS \f(CW$ff\fP\->error([BOOL])
+.IX Subsection "$ff->error([BOOL])"
+Returns the last encountered error as string.
+Pass it a true value to get the \f(CWCarp::longmess()\fR output instead.
+.SH "HOW IT WORKS"
+.IX Header "HOW IT WORKS"
+File::Fetch is able to fetch a variety of uris, by using several
+external programs and modules.
+.PP
+Below is a mapping of what utilities will be used in what order
+for what schemes, if available:
+.PP
+.Vb 5
+\&    file    => LWP, lftp, file
+\&    http    => LWP, HTTP::Tiny, wget, curl, lftp, fetch, HTTP::Lite, lynx, iosock
+\&    ftp     => LWP, Net::FTP, wget, curl, lftp, fetch, ncftp, ftp
+\&    rsync   => rsync
+\&    git     => git
+.Ve
+.PP
+If you'd like to disable the use of one or more of these utilities
+and/or modules, see the \f(CW$BLACKLIST\fR variable further down.
+.PP
+If a utility or module isn't available, it will be marked in a cache
+(see the \f(CW$METHOD_FAIL\fR variable further down), so it will not be
+tried again. The \f(CW\*(C`fetch\*(C'\fR method will only fail when all options are
+exhausted, and it was not able to retrieve the file.
+.PP
+The \f(CW\*(C`fetch\*(C'\fR utility is available on FreeBSD. NetBSD and Dragonfly BSD
+may also have it from \f(CW\*(C`pkgsrc\*(C'\fR. We only check for \f(CW\*(C`fetch\*(C'\fR on those
+three platforms.
+.PP
+\&\f(CW\*(C`iosock\*(C'\fR is a very limited IO::Socket::INET based mechanism for
+retrieving \f(CW\*(C`http\*(C'\fR schemed urls. It doesn't follow redirects for instance.
+.PP
+\&\f(CW\*(C`git\*(C'\fR only supports \f(CW\*(C`git://\*(C'\fR style urls.
+.PP
+A special note about fetching files from an ftp uri:
+.PP
+By default, all ftp connections are done in passive mode. To change
+that, see the \f(CW$FTP_PASSIVE\fR variable further down.
+.PP
+Furthermore, ftp uris only support anonymous connections, so no
+named user/password pair can be passed along.
+.PP
+\&\f(CW\*(C`/bin/ftp\*(C'\fR is blacklisted by default; see the \f(CW$BLACKLIST\fR variable
+further down.
+.SH "GLOBAL VARIABLES"
+.IX Header "GLOBAL VARIABLES"
+The behaviour of File::Fetch can be altered by changing the following
+global variables:
+.ie n .SS $File::Fetch::FROM_EMAIL
+.el .SS \f(CW$File::Fetch::FROM_EMAIL\fP
+.IX Subsection "$File::Fetch::FROM_EMAIL"
+This is the email address that will be sent as your anonymous ftp
+password.
+.PP
+Default is \f(CW\*(C`File\-Fetch@example.com\*(C'\fR.
+.ie n .SS $File::Fetch::USER_AGENT
+.el .SS \f(CW$File::Fetch::USER_AGENT\fP
+.IX Subsection "$File::Fetch::USER_AGENT"
+This is the useragent as \f(CW\*(C`LWP\*(C'\fR will report it.
+.PP
+Default is \f(CW\*(C`File::Fetch/$VERSION\*(C'\fR.
+.ie n .SS $File::Fetch::FTP_PASSIVE
+.el .SS \f(CW$File::Fetch::FTP_PASSIVE\fP
+.IX Subsection "$File::Fetch::FTP_PASSIVE"
+This variable controls whether the environment variable \f(CW\*(C`FTP_PASSIVE\*(C'\fR
+and any passive switches to commandline tools will be set to true.
+.PP
+Default value is 1.
+.PP
+Note: When \f(CW$FTP_PASSIVE\fR is true, \f(CW\*(C`ncftp\*(C'\fR will not be used to fetch
+files, since passive mode can only be set interactively for this binary
+.ie n .SS $File::Fetch::TIMEOUT
+.el .SS \f(CW$File::Fetch::TIMEOUT\fP
+.IX Subsection "$File::Fetch::TIMEOUT"
+When set, controls the network timeout (counted in seconds).
+.PP
+Default value is 0.
+.ie n .SS $File::Fetch::WARN
+.el .SS \f(CW$File::Fetch::WARN\fP
+.IX Subsection "$File::Fetch::WARN"
+This variable controls whether errors encountered internally by
+\&\f(CW\*(C`File::Fetch\*(C'\fR should be \f(CW\*(C`carp\*(C'\fR'd or not.
+.PP
+Set to false to silence warnings. Inspect the output of the \f(CWerror()\fR
+method manually to see what went wrong.
+.PP
+Defaults to \f(CW\*(C`true\*(C'\fR.
+.ie n .SS $File::Fetch::DEBUG
+.el .SS \f(CW$File::Fetch::DEBUG\fP
+.IX Subsection "$File::Fetch::DEBUG"
+This enables debugging output when calling commandline utilities to
+fetch files.
+This also enables \f(CW\*(C`Carp::longmess\*(C'\fR errors, instead of the regular
+\&\f(CW\*(C`carp\*(C'\fR errors.
+.PP
+Good for tracking down why things don't work with your particular
+setup.
+.PP
+Default is 0.
+.ie n .SS $File::Fetch::BLACKLIST
+.el .SS \f(CW$File::Fetch::BLACKLIST\fP
+.IX Subsection "$File::Fetch::BLACKLIST"
+This is an array ref holding blacklisted modules/utilities for fetching
+files with.
+.PP
+To disallow the use of, for example, \f(CW\*(C`LWP\*(C'\fR and \f(CW\*(C`Net::FTP\*(C'\fR, you could
+set \f(CW$File::Fetch::BLACKLIST\fR to:
+.PP
+.Vb 1
+\&    $File::Fetch::BLACKLIST = [qw|lwp netftp|]
+.Ve
+.PP
+The default blacklist is [qw|ftp|], as \f(CW\*(C`/bin/ftp\*(C'\fR is rather unreliable.
+.PP
+See the note on \f(CW\*(C`MAPPING\*(C'\fR below.
+.ie n .SS $File::Fetch::METHOD_FAIL
+.el .SS \f(CW$File::Fetch::METHOD_FAIL\fP
+.IX Subsection "$File::Fetch::METHOD_FAIL"
+This is a hashref registering what modules/utilities were known to fail
+for fetching files (mostly because they weren't installed).
+.PP
+You can reset this cache by assigning an empty hashref to it, or
+individually remove keys.
+.PP
+See the note on \f(CW\*(C`MAPPING\*(C'\fR below.
+.SH MAPPING
+.IX Header "MAPPING"
+Here's a quick mapping for the utilities/modules, and their names for
+the \f(CW$BLACKLIST\fR, \f(CW$METHOD_FAIL\fR and other internal functions.
+.PP
+.Vb 10
+\&    LWP         => lwp
+\&    HTTP::Lite  => httplite
+\&    HTTP::Tiny  => httptiny
+\&    Net::FTP    => netftp
+\&    wget        => wget
+\&    lynx        => lynx
+\&    ncftp       => ncftp
+\&    ftp         => ftp
+\&    curl        => curl
+\&    rsync       => rsync
+\&    lftp        => lftp
+\&    fetch       => fetch
+\&    IO::Socket  => iosock
+.Ve
+.SH "FREQUENTLY ASKED QUESTIONS"
+.IX Header "FREQUENTLY ASKED QUESTIONS"
+.SS "So how do I use a proxy with File::Fetch?"
+.IX Subsection "So how do I use a proxy with File::Fetch?"
+\&\f(CW\*(C`File::Fetch\*(C'\fR currently only supports proxies with LWP::UserAgent.
+You will need to set your environment variables accordingly. For
+example, to use an ftp proxy:
+.PP
+.Vb 1
+\&    $ENV{ftp_proxy} = \*(Aqfoo.com\*(Aq;
+.Ve
+.PP
+Refer to the LWP::UserAgent manpage for more details.
+.SS "I used 'lynx' to fetch a file, but its contents is all wrong!"
+.IX Subsection "I used 'lynx' to fetch a file, but its contents is all wrong!"
+\&\f(CW\*(C`lynx\*(C'\fR can only fetch remote files by dumping its contents to \f(CW\*(C`STDOUT\*(C'\fR,
+which we in turn capture. If that content is a 'custom' error file
+(like, say, a \f(CW\*(C`404 handler\*(C'\fR), you will get that contents instead.
+.PP
+Sadly, \f(CW\*(C`lynx\*(C'\fR doesn't support any options to return a different exit
+code on non\-\f(CW\*(C`200 OK\*(C'\fR status, giving us no way to tell the difference
+between a 'successful' fetch and a custom error page.
+.PP
+Therefor, we recommend to only use \f(CW\*(C`lynx\*(C'\fR as a last resort. This is
+why it is at the back of our list of methods to try as well.
+.SS "Files I'm trying to fetch have reserved characters or non-ASCII characters in them. What do I do?"
+.IX Subsection "Files I'm trying to fetch have reserved characters or non-ASCII characters in them. What do I do?"
+\&\f(CW\*(C`File::Fetch\*(C'\fR is relatively smart about things. When trying to write
+a file to disk, it removes the \f(CW\*(C`query parameters\*(C'\fR (see the
+\&\f(CW\*(C`output_file\*(C'\fR method for details) from the file name before creating
+it. In most cases this suffices.
+.PP
+If you have any other characters you need to escape, please install
+the \f(CW\*(C`URI::Escape\*(C'\fR module from CPAN, and pre-encode your URI before
+passing it to \f(CW\*(C`File::Fetch\*(C'\fR. You can read about the details of URIs
+and URI encoding here:
+.PP
+<https://datatracker.ietf.org/doc/html/rfc2396>
+.SH TODO
+.IX Header "TODO"
+.ie n .IP "Implement $PREFER_BIN" 4
+.el .IP "Implement \f(CW$PREFER_BIN\fR" 4
+.IX Item "Implement $PREFER_BIN"
+To indicate to rather use commandline tools than modules
+.SH "BUG REPORTS"
+.IX Header "BUG REPORTS"
+Please report bugs or other issues to <bug\-file\-fetch@rt.cpan.org<gt>.
+.SH AUTHOR
+.IX Header "AUTHOR"
+This module by Jos Boumans <kane@cpan.org>.
+.SH COPYRIGHT
+.IX Header "COPYRIGHT"
+This library is free software; you may redistribute and/or modify it
+under the same terms as Perl itself.