Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 457 insertions, 0 deletions

diff --git a/upstream/mageia-cauldron/man3pm/File::Spec::Mac.3pm b/upstream/mageia-cauldron/man3pm/File::Spec::Mac.3pm
new file mode 100644
index 00000000..8b05adc5
--- /dev/null
+++ b/upstream/mageia-cauldron/man3pm/File::Spec::Mac.3pm
@@ -0,0 +1,457 @@
+.\" -*- 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::Spec::Mac 3pm"
+.TH File::Spec::Mac 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::Spec::Mac \- File::Spec for Mac OS (Classic)
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 1
+\& require File::Spec::Mac; # Done internally by File::Spec if needed
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+Methods for manipulating file specifications.
+.SH METHODS
+.IX Header "METHODS"
+.IP canonpath 2
+.IX Item "canonpath"
+On Mac OS, there's nothing to be done. Returns what it's given.
+.IP \fBcatdir()\fR 2
+.IX Item "catdir()"
+Concatenate two or more directory names to form a path separated by colons
+(":") ending with a directory. Resulting paths are \fBrelative\fR by default,
+but can be forced to be absolute (but avoid this, see below). Automatically
+puts a trailing ":" on the end of the complete path, because that's what's
+done in MacPerl's environment and helps to distinguish a file path from a
+directory path.
+.Sp
+\&\fBIMPORTANT NOTE:\fR Beginning with version 1.3 of this module, the resulting
+path is relative by default and \fInot\fR absolute. This decision was made due
+to portability reasons. Since \f(CW\*(C`File::Spec\->catdir()\*(C'\fR returns relative paths
+on all other operating systems, it will now also follow this convention on Mac
+OS. Note that this may break some existing scripts.
+.Sp
+The intended purpose of this routine is to concatenate \fIdirectory names\fR.
+But because of the nature of Macintosh paths, some additional possibilities
+are allowed to make using this routine give reasonable results for some
+common situations. In other words, you are also allowed to concatenate
+\&\fIpaths\fR instead of directory names (strictly speaking, a string like ":a"
+is a path, but not a name, since it contains a punctuation character ":").
+.Sp
+So, beside calls like
+.Sp
+.Vb 3
+\&    catdir("a") = ":a:"
+\&    catdir("a","b") = ":a:b:"
+\&    catdir() = ""                    (special case)
+.Ve
+.Sp
+calls like the following
+.Sp
+.Vb 5
+\&    catdir(":a:") = ":a:"
+\&    catdir(":a","b") = ":a:b:"
+\&    catdir(":a:","b") = ":a:b:"
+\&    catdir(":a:",":b:") = ":a:b:"
+\&    catdir(":") = ":"
+.Ve
+.Sp
+are allowed.
+.Sp
+Here are the rules that are used in \f(CWcatdir()\fR; note that we try to be as
+compatible as possible to Unix:
+.RS 2
+.IP 1. 2
+The resulting path is relative by default, i.e. the resulting path will have a
+leading colon.
+.IP 2. 2
+A trailing colon is added automatically to the resulting path, to denote a
+directory.
+.IP 3. 2
+Generally, each argument has one leading ":" and one trailing ":"
+removed (if any). They are then joined together by a ":". Special
+treatment applies for arguments denoting updir paths like "::lib:",
+see (4), or arguments consisting solely of colons ("colon paths"),
+see (5).
+.IP 4. 2
+When an updir path like ":::lib::" is passed as argument, the number
+of directories to climb up is handled correctly, not removing leading
+or trailing colons when necessary. E.g.
+.Sp
+.Vb 2
+\&    catdir(":::a","::b","c")    = ":::a::b:c:"
+\&    catdir(":::a::","::b","c")  = ":::a:::b:c:"
+.Ve
+.IP 5. 2
+Adding a colon ":" or empty string "" to a path at \fIany\fR position
+doesn't alter the path, i.e. these arguments are ignored. (When a ""
+is passed as the first argument, it has a special meaning, see
+(6)). This way, a colon ":" is handled like a "." (curdir) on Unix,
+while an empty string "" is generally ignored (see
+"\fBcanonpath()\fR" in File::Spec::Unix ). Likewise, a "::" is handled like a ".."
+(updir), and a ":::" is handled like a "../.." etc.  E.g.
+.Sp
+.Vb 2
+\&    catdir("a",":",":","b")   = ":a:b:"
+\&    catdir("a",":","::",":b") = ":a::b:"
+.Ve
+.IP 6. 2
+If the first argument is an empty string "" or is a volume name, i.e. matches
+the pattern /^[^:]+:/, the resulting path is \fBabsolute\fR.
+.IP 7. 2
+Passing an empty string "" as the first argument to \f(CWcatdir()\fR is
+like passing\f(CW\*(C`File::Spec\->rootdir()\*(C'\fR as the first argument, i.e.
+.Sp
+.Vb 1
+\&    catdir("","a","b")          is the same as
+\&
+\&    catdir(rootdir(),"a","b").
+.Ve
+.Sp
+This is true on Unix, where \f(CW\*(C`catdir("","a","b")\*(C'\fR yields "/a/b" and
+\&\f(CWrootdir()\fR is "/". Note that \f(CWrootdir()\fR on Mac OS is the startup
+volume, which is the closest in concept to Unix' "/". This should help
+to run existing scripts originally written for Unix.
+.IP 8. 2
+For absolute paths, some cleanup is done, to ensure that the volume
+name isn't immediately followed by updirs. This is invalid, because
+this would go beyond "root". Generally, these cases are handled like
+their Unix counterparts:
+.Sp
+.Vb 10
+\& Unix:
+\&    Unix\->catdir("","")                 =  "/"
+\&    Unix\->catdir("",".")                =  "/"
+\&    Unix\->catdir("","..")               =  "/"        # can\*(Aqt go
+\&                                                      # beyond root
+\&    Unix\->catdir("",".","..","..","a")  =  "/a"
+\& Mac:
+\&    Mac\->catdir("","")                  =  rootdir()  # (e.g. "HD:")
+\&    Mac\->catdir("",":")                 =  rootdir()
+\&    Mac\->catdir("","::")                =  rootdir()  # can\*(Aqt go
+\&                                                      # beyond root
+\&    Mac\->catdir("",":","::","::","a")   =  rootdir() . "a:"
+\&                                                    # (e.g. "HD:a:")
+.Ve
+.Sp
+However, this approach is limited to the first arguments following
+"root" (again, see "\fBcanonpath()\fR" in File::Spec::Unix. If there are more
+arguments that move up the directory tree, an invalid path going
+beyond root can be created.
+.RE
+.RS 2
+.Sp
+As you've seen, you can force \f(CWcatdir()\fR to create an absolute path
+by passing either an empty string or a path that begins with a volume
+name as the first argument. However, you are strongly encouraged not
+to do so, since this is done only for backward compatibility. Newer
+versions of File::Spec come with a method called \f(CWcatpath()\fR (see
+below), that is designed to offer a portable solution for the creation
+of absolute paths.  It takes volume, directory and file portions and
+returns an entire path. While \f(CWcatdir()\fR is still suitable for the
+concatenation of \fIdirectory names\fR, you are encouraged to use
+\&\f(CWcatpath()\fR to concatenate \fIvolume names\fR and \fIdirectory
+paths\fR. E.g.
+.Sp
+.Vb 2
+\&    $dir      = File::Spec\->catdir("tmp","sources");
+\&    $abs_path = File::Spec\->catpath("MacintoshHD:", $dir,"");
+.Ve
+.Sp
+yields
+.Sp
+.Vb 1
+\&    "MacintoshHD:tmp:sources:" .
+.Ve
+.RE
+.IP catfile 2
+.IX Item "catfile"
+Concatenate one or more directory names and a filename to form a
+complete path ending with a filename. Resulting paths are \fBrelative\fR
+by default, but can be forced to be absolute (but avoid this).
+.Sp
+\&\fBIMPORTANT NOTE:\fR Beginning with version 1.3 of this module, the
+resulting path is relative by default and \fInot\fR absolute. This
+decision was made due to portability reasons. Since
+\&\f(CW\*(C`File::Spec\->catfile()\*(C'\fR returns relative paths on all other
+operating systems, it will now also follow this convention on Mac OS.
+Note that this may break some existing scripts.
+.Sp
+The last argument is always considered to be the file portion. Since
+\&\f(CWcatfile()\fR uses \f(CWcatdir()\fR (see above) for the concatenation of the
+directory portions (if any), the following with regard to relative and
+absolute paths is true:
+.Sp
+.Vb 2
+\&    catfile("")     = ""
+\&    catfile("file") = "file"
+.Ve
+.Sp
+but
+.Sp
+.Vb 3
+\&    catfile("","")        = rootdir()         # (e.g. "HD:")
+\&    catfile("","file")    = rootdir() . file  # (e.g. "HD:file")
+\&    catfile("HD:","file") = "HD:file"
+.Ve
+.Sp
+This means that \f(CWcatdir()\fR is called only when there are two or more
+arguments, as one might expect.
+.Sp
+Note that the leading ":" is removed from the filename, so that
+.Sp
+.Vb 1
+\&    catfile("a","b","file")  = ":a:b:file"    and
+\&
+\&    catfile("a","b",":file") = ":a:b:file"
+.Ve
+.Sp
+give the same answer.
+.Sp
+To concatenate \fIvolume names\fR, \fIdirectory paths\fR and \fIfilenames\fR,
+you are encouraged to use \f(CWcatpath()\fR (see below).
+.IP curdir 2
+.IX Item "curdir"
+Returns a string representing the current directory. On Mac OS, this is ":".
+.IP devnull 2
+.IX Item "devnull"
+Returns a string representing the null device. On Mac OS, this is "Dev:Null".
+.IP rootdir 2
+.IX Item "rootdir"
+Returns the empty string.  Mac OS has no real root directory.
+.IP tmpdir 2
+.IX Item "tmpdir"
+Returns the contents of \f(CW$ENV\fR{TMPDIR}, if that directory exits or the
+current working directory otherwise. Under MacPerl, \f(CW$ENV\fR{TMPDIR} will
+contain a path like "MacintoshHD:Temporary Items:", which is a hidden
+directory on your startup volume.
+.IP updir 2
+.IX Item "updir"
+Returns a string representing the parent directory. On Mac OS, this is "::".
+.IP file_name_is_absolute 2
+.IX Item "file_name_is_absolute"
+Takes as argument a path and returns true, if it is an absolute path.
+If the path has a leading ":", it's a relative path. Otherwise, it's an
+absolute path, unless the path doesn't contain any colons, i.e. it's a name
+like "a". In this particular case, the path is considered to be relative
+(i.e. it is considered to be a filename). Use ":" in the appropriate place
+in the path if you want to distinguish unambiguously. As a special case,
+the filename '' is always considered to be absolute. Note that with version
+1.2 of File::Spec::Mac, this does no longer consult the local filesystem.
+.Sp
+E.g.
+.Sp
+.Vb 5
+\&    File::Spec\->file_name_is_absolute("a");         # false (relative)
+\&    File::Spec\->file_name_is_absolute(":a:b:");     # false (relative)
+\&    File::Spec\->file_name_is_absolute("MacintoshHD:");
+\&                                                    # true (absolute)
+\&    File::Spec\->file_name_is_absolute("");          # true (absolute)
+.Ve
+.IP path 2
+.IX Item "path"
+Returns the null list for the MacPerl application, since the concept is
+usually meaningless under Mac OS. But if you're using the MacPerl tool under
+MPW, it gives back \f(CW$ENV\fR{Commands} suitably split, as is done in
+:lib:ExtUtils:MM_Mac.pm.
+.IP splitpath 2
+.IX Item "splitpath"
+.Vb 3
+\&    ($volume,$directories,$file) = File::Spec\->splitpath( $path );
+\&    ($volume,$directories,$file) = File::Spec\->splitpath( $path,
+\&                                                          $no_file );
+.Ve
+.Sp
+Splits a path into volume, directory, and filename portions.
+.Sp
+On Mac OS, assumes that the last part of the path is a filename unless
+\&\f(CW$no_file\fR is true or a trailing separator ":" is present.
+.Sp
+The volume portion is always returned with a trailing ":". The directory portion
+is always returned with a leading (to denote a relative path) and a trailing ":"
+(to denote a directory). The file portion is always returned \fIwithout\fR a leading ":".
+Empty portions are returned as empty string ''.
+.Sp
+The results can be passed to \f(CWcatpath()\fR to get back a path equivalent to
+(usually identical to) the original path.
+.IP splitdir 2
+.IX Item "splitdir"
+The opposite of \f(CWcatdir()\fR.
+.Sp
+.Vb 1
+\&    @dirs = File::Spec\->splitdir( $directories );
+.Ve
+.Sp
+\&\f(CW$directories\fR should be only the directory portion of the path on systems
+that have the concept of a volume or that have path syntax that differentiates
+files from directories. Consider using \f(CWsplitpath()\fR otherwise.
+.Sp
+Unlike just splitting the directories on the separator, empty directory names
+(\f(CW""\fR) can be returned. Since \f(CWcatdir()\fR on Mac OS always appends a trailing
+colon to distinguish a directory path from a file path, a single trailing colon
+will be ignored, i.e. there's no empty directory name after it.
+.Sp
+Hence, on Mac OS, both
+.Sp
+.Vb 2
+\&    File::Spec\->splitdir( ":a:b::c:" );    and
+\&    File::Spec\->splitdir( ":a:b::c" );
+.Ve
+.Sp
+yield:
+.Sp
+.Vb 1
+\&    ( "a", "b", "::", "c")
+.Ve
+.Sp
+while
+.Sp
+.Vb 1
+\&    File::Spec\->splitdir( ":a:b::c::" );
+.Ve
+.Sp
+yields:
+.Sp
+.Vb 1
+\&    ( "a", "b", "::", "c", "::")
+.Ve
+.IP catpath 2
+.IX Item "catpath"
+.Vb 1
+\&    $path = File::Spec\->catpath($volume,$directory,$file);
+.Ve
+.Sp
+Takes volume, directory and file portions and returns an entire path. On Mac OS,
+\&\f(CW$volume\fR, \f(CW$directory\fR and \f(CW$file\fR are concatenated.  A ':' is inserted if need be. You
+may pass an empty string for each portion. If all portions are empty, the empty
+string is returned. If \f(CW$volume\fR is empty, the result will be a relative path,
+beginning with a ':'. If \f(CW$volume\fR and \f(CW$directory\fR are empty, a leading ":" (if any)
+is removed form \f(CW$file\fR and the remainder is returned. If \f(CW$file\fR is empty, the
+resulting path will have a trailing ':'.
+.IP abs2rel 2
+.IX Item "abs2rel"
+Takes a destination path and an optional base path and returns a relative path
+from the base path to the destination path:
+.Sp
+.Vb 2
+\&    $rel_path = File::Spec\->abs2rel( $path ) ;
+\&    $rel_path = File::Spec\->abs2rel( $path, $base ) ;
+.Ve
+.Sp
+Note that both paths are assumed to have a notation that distinguishes a
+directory path (with trailing ':') from a file path (without trailing ':').
+.Sp
+If \f(CW$base\fR is not present or '', then the current working directory is used.
+If \f(CW$base\fR is relative, then it is converted to absolute form using \f(CWrel2abs()\fR.
+This means that it is taken to be relative to the current working directory.
+.Sp
+If \f(CW$path\fR and \f(CW$base\fR appear to be on two different volumes, we will not
+attempt to resolve the two paths, and we will instead simply return
+\&\f(CW$path\fR.  Note that previous versions of this module ignored the volume
+of \f(CW$base\fR, which resulted in garbage results part of the time.
+.Sp
+If \f(CW$base\fR doesn't have a trailing colon, the last element of \f(CW$base\fR is
+assumed to be a filename.  This filename is ignored.  Otherwise all path
+components are assumed to be directories.
+.Sp
+If \f(CW$path\fR is relative, it is converted to absolute form using \f(CWrel2abs()\fR.
+This means that it is taken to be relative to the current working directory.
+.Sp
+Based on code written by Shigio Yamaguchi.
+.IP rel2abs 2
+.IX Item "rel2abs"
+Converts a relative path to an absolute path:
+.Sp
+.Vb 2
+\&    $abs_path = File::Spec\->rel2abs( $path ) ;
+\&    $abs_path = File::Spec\->rel2abs( $path, $base ) ;
+.Ve
+.Sp
+Note that both paths are assumed to have a notation that distinguishes a
+directory path (with trailing ':') from a file path (without trailing ':').
+.Sp
+If \f(CW$base\fR is not present or '', then \f(CW$base\fR is set to the current working
+directory. If \f(CW$base\fR is relative, then it is converted to absolute form
+using \f(CWrel2abs()\fR. This means that it is taken to be relative to the
+current working directory.
+.Sp
+If \f(CW$base\fR doesn't have a trailing colon, the last element of \f(CW$base\fR is
+assumed to be a filename.  This filename is ignored.  Otherwise all path
+components are assumed to be directories.
+.Sp
+If \f(CW$path\fR is already absolute, it is returned and \f(CW$base\fR is ignored.
+.Sp
+Based on code written by Shigio Yamaguchi.
+.SH AUTHORS
+.IX Header "AUTHORS"
+See the authors list in \fIFile::Spec\fR. Mac OS support by Paul Schinder
+<schinder@pobox.com> and Thomas Wegner <wegner_thomas@yahoo.com>.
+.SH COPYRIGHT
+.IX Header "COPYRIGHT"
+Copyright (c) 2004 by the Perl 5 Porters.  All rights reserved.
+.PP
+This program is free software; you can redistribute it and/or modify
+it under the same terms as Perl itself.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+See File::Spec and File::Spec::Unix.  This package overrides the
+implementation of these methods, not the semantics.