Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 383 insertions, 0 deletions

diff --git a/upstream/debian-unstable/man3/File::Find.3perl b/upstream/debian-unstable/man3/File::Find.3perl
new file mode 100644
index 00000000..477116fe
--- /dev/null
+++ b/upstream/debian-unstable/man3/File::Find.3perl
@@ -0,0 +1,383 @@
+.\" -*- 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::Find 3perl"
+.TH File::Find 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
+File::Find \- Traverse a directory tree.
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 3
+\&    use File::Find;
+\&    find(\e&wanted, @directories_to_search);
+\&    sub wanted { ... }
+\&
+\&    use File::Find;
+\&    finddepth(\e&wanted, @directories_to_search);
+\&    sub wanted { ... }
+\&
+\&    use File::Find;
+\&    find({ wanted => \e&process, follow => 1 }, \*(Aq.\*(Aq);
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+These are functions for searching through directory trees doing work
+on each file found similar to the Unix \fIfind\fR command.  File::Find
+exports two functions, \f(CW\*(C`find\*(C'\fR and \f(CW\*(C`finddepth\*(C'\fR.  They work similarly
+but have subtle differences.
+.IP \fBfind\fR 4
+.IX Item "find"
+.Vb 2
+\&  find(\e&wanted,  @directories);
+\&  find(\e%options, @directories);
+.Ve
+.Sp
+\&\f(CWfind()\fR does a depth-first search over the given \f(CW@directories\fR in
+the order they are given.  For each file or directory found, it calls
+the \f(CW&wanted\fR subroutine.  (See below for details on how to use the
+\&\f(CW&wanted\fR function).  Additionally, for each directory found, it will
+\&\f(CWchdir()\fR into that directory and continue the search, invoking the
+\&\f(CW&wanted\fR function on each file or subdirectory in the directory.
+.IP \fBfinddepth\fR 4
+.IX Item "finddepth"
+.Vb 2
+\&  finddepth(\e&wanted,  @directories);
+\&  finddepth(\e%options, @directories);
+.Ve
+.Sp
+\&\f(CWfinddepth()\fR works just like \f(CWfind()\fR except that it invokes the
+\&\f(CW&wanted\fR function for a directory \fIafter\fR invoking it for the
+directory's contents.  It does a postorder traversal instead of a
+preorder traversal, working from the bottom of the directory tree up
+where \f(CWfind()\fR works from the top of the tree down.
+.PP
+Despite the name of the \f(CWfinddepth()\fR function, both \f(CWfind()\fR and
+\&\f(CWfinddepth()\fR perform a depth-first search of the directory hierarchy.
+.ie n .SS %options
+.el .SS \f(CW%options\fP
+.IX Subsection "%options"
+The first argument to \f(CWfind()\fR is either a code reference to your
+\&\f(CW&wanted\fR function, or a hash reference describing the operations
+to be performed for each file.  The
+code reference is described in "The wanted function" below.
+.PP
+Here are the possible keys for the hash:
+.ie n .IP """wanted""" 4
+.el .IP \f(CWwanted\fR 4
+.IX Item "wanted"
+The value should be a code reference.  This code reference is
+described in "The wanted function" below. The \f(CW&wanted\fR subroutine is
+mandatory.
+.ie n .IP """bydepth""" 4
+.el .IP \f(CWbydepth\fR 4
+.IX Item "bydepth"
+Reports the name of a directory only AFTER all its entries
+have been reported.  Entry point \f(CWfinddepth()\fR is a shortcut for
+specifying \f(CW\*(C`{ bydepth => 1 }\*(C'\fR in the first argument of \f(CWfind()\fR.
+.ie n .IP """preprocess""" 4
+.el .IP \f(CWpreprocess\fR 4
+.IX Item "preprocess"
+The value should be a code reference. This code reference is used to
+preprocess the current directory. The name of the currently processed
+directory is in \f(CW$File::Find::dir\fR. Your preprocessing function is
+called after \f(CWreaddir()\fR, but before the loop that calls the \f(CWwanted()\fR
+function. It is called with a list of strings (actually file/directory
+names) and is expected to return a list of strings. The code can be
+used to sort the file/directory names alphabetically, numerically,
+or to filter out directory entries based on their name alone. When
+\&\fIfollow\fR or \fIfollow_fast\fR are in effect, \f(CW\*(C`preprocess\*(C'\fR is a no-op.
+.ie n .IP """postprocess""" 4
+.el .IP \f(CWpostprocess\fR 4
+.IX Item "postprocess"
+The value should be a code reference. It is invoked just before leaving
+the currently processed directory. It is called in void context with no
+arguments. The name of the current directory is in \f(CW$File::Find::dir\fR. This
+hook is handy for summarizing a directory, such as calculating its disk
+usage. When \fIfollow\fR or \fIfollow_fast\fR are in effect, \f(CW\*(C`postprocess\*(C'\fR is a
+no-op.
+.ie n .IP """follow""" 4
+.el .IP \f(CWfollow\fR 4
+.IX Item "follow"
+Causes symbolic links to be followed. Since directory trees with symbolic
+links (followed) may contain files more than once and may even have
+cycles, a hash has to be built up with an entry for each file.
+This might be expensive both in space and time for a large
+directory tree. See "follow_fast" and "follow_skip" below.
+If either \fIfollow\fR or \fIfollow_fast\fR is in effect:
+.RS 4
+.IP \(bu 4
+It is guaranteed that an \fIlstat\fR has been called before the user's
+\&\f(CWwanted()\fR function is called. This enables fast file checks involving \f(CW\*(C`_\*(C'\fR.
+Note that this guarantee no longer holds if \fIfollow\fR or \fIfollow_fast\fR
+are not set.
+.IP \(bu 4
+There is a variable \f(CW$File::Find::fullname\fR which holds the absolute
+pathname of the file with all symbolic links resolved.  If the link is
+a dangling symbolic link, then fullname will be set to \f(CW\*(C`undef\*(C'\fR.
+.RE
+.RS 4
+.RE
+.ie n .IP """follow_fast""" 4
+.el .IP \f(CWfollow_fast\fR 4
+.IX Item "follow_fast"
+This is similar to \fIfollow\fR except that it may report some files more
+than once.  It does detect cycles, however.  Since only symbolic links
+have to be hashed, this is much cheaper both in space and time.  If
+processing a file more than once (by the user's \f(CWwanted()\fR function)
+is worse than just taking time, the option \fIfollow\fR should be used.
+.ie n .IP """follow_skip""" 4
+.el .IP \f(CWfollow_skip\fR 4
+.IX Item "follow_skip"
+\&\f(CW\*(C`follow_skip==1\*(C'\fR, which is the default, causes all files which are
+neither directories nor symbolic links to be ignored if they are about
+to be processed a second time. If a directory or a symbolic link
+are about to be processed a second time, File::Find dies.
+.Sp
+\&\f(CW\*(C`follow_skip==0\*(C'\fR causes File::Find to die if any file is about to be
+processed a second time.
+.Sp
+\&\f(CW\*(C`follow_skip==2\*(C'\fR causes File::Find to ignore any duplicate files and
+directories but to proceed normally otherwise.
+.ie n .IP """dangling_symlinks""" 4
+.el .IP \f(CWdangling_symlinks\fR 4
+.IX Item "dangling_symlinks"
+Specifies what to do with symbolic links whose target doesn't exist.
+If true and a code reference, will be called with the symbolic link
+name and the directory it lives in as arguments.  Otherwise, if true
+and warnings are on, a warning of the form \f(CW"symbolic_link_name is a dangling
+symbolic link\en"\fR will be issued.  If false, the dangling symbolic link
+will be silently ignored.
+.ie n .IP """no_chdir""" 4
+.el .IP \f(CWno_chdir\fR 4
+.IX Item "no_chdir"
+Does not \f(CWchdir()\fR to each directory as it recurses. The \f(CWwanted()\fR
+function will need to be aware of this, of course. In this case,
+\&\f(CW$_\fR will be the same as \f(CW$File::Find::name\fR.
+.ie n .IP """untaint""" 4
+.el .IP \f(CWuntaint\fR 4
+.IX Item "untaint"
+If find is used in taint-mode (\-T command line switch or
+if EUID != UID or if EGID != GID), then internally directory names have to be
+untainted before they can be \f(CW\*(C`chdir\*(C'\fR'd to. Therefore they are checked against
+a regular expression \fIuntaint_pattern\fR.  Note that all names passed to the
+user's \f(CWwanted()\fR function are still tainted. If this option is used while not
+in taint-mode, \f(CW\*(C`untaint\*(C'\fR is a no-op.
+.ie n .IP """untaint_pattern""" 4
+.el .IP \f(CWuntaint_pattern\fR 4
+.IX Item "untaint_pattern"
+See above. This should be set using the \f(CW\*(C`qr\*(C'\fR quoting operator.
+The default is set to \f(CW\*(C`qr|^([\-+@\ew./]+)$|\*(C'\fR.
+Note that the parentheses are vital.
+.ie n .IP """untaint_skip""" 4
+.el .IP \f(CWuntaint_skip\fR 4
+.IX Item "untaint_skip"
+If set, a directory which fails the \fIuntaint_pattern\fR is skipped,
+including all its sub-directories. The default is to \f(CW\*(C`die\*(C'\fR in such a case.
+.SS "The wanted function"
+.IX Subsection "The wanted function"
+The \f(CWwanted()\fR function does whatever verifications you want on
+each file and directory.  Note that despite its name, the \f(CWwanted()\fR
+function is a generic callback function, and does \fBnot\fR tell
+File::Find if a file is "wanted" or not.  In fact, its return value
+is ignored.
+.PP
+The wanted function takes no arguments but rather does its work
+through a collection of variables.
+.ie n .IP "$File::Find::dir is the current directory name," 4
+.el .IP "\f(CW$File::Find::dir\fR is the current directory name," 4
+.IX Item "$File::Find::dir is the current directory name,"
+.PD 0
+.ie n .IP "$_ is the current filename within that directory" 4
+.el .IP "\f(CW$_\fR is the current filename within that directory" 4
+.IX Item "$_ is the current filename within that directory"
+.ie n .IP "$File::Find::name is the complete pathname to the file." 4
+.el .IP "\f(CW$File::Find::name\fR is the complete pathname to the file." 4
+.IX Item "$File::Find::name is the complete pathname to the file."
+.PD
+.PP
+The above variables have all been localized and may be changed without
+affecting data outside of the wanted function.
+.PP
+For example, when examining the file \fI/some/path/foo.ext\fR you will have:
+.PP
+.Vb 3
+\&    $File::Find::dir  = /some/path/
+\&    $_                = foo.ext
+\&    $File::Find::name = /some/path/foo.ext
+.Ve
+.PP
+You are \fBchdir()\fR'd to \f(CW$File::Find::dir\fR when the function is called,
+unless \f(CW\*(C`no_chdir\*(C'\fR was specified. Note that when changing to
+directories is in effect, the root directory (\fI/\fR) is a somewhat
+special case inasmuch as the concatenation of \f(CW$File::Find::dir\fR,
+\&\f(CW\*(Aq/\*(Aq\fR and \f(CW$_\fR is not literally equal to \f(CW$File::Find::name\fR. The
+table below summarizes all variants:
+.PP
+.Vb 4
+\&              $File::Find::name  $File::Find::dir  $_
+\& default      /                  /                 .
+\& no_chdir=>0  /etc               /                 etc
+\&              /etc/x             /etc              x
+\&
+\& no_chdir=>1  /                  /                 /
+\&              /etc               /                 /etc
+\&              /etc/x             /etc              /etc/x
+.Ve
+.PP
+When \f(CW\*(C`follow\*(C'\fR or \f(CW\*(C`follow_fast\*(C'\fR are in effect, there is
+also a \f(CW$File::Find::fullname\fR.  The function may set
+\&\f(CW$File::Find::prune\fR to prune the tree unless \f(CW\*(C`bydepth\*(C'\fR was
+specified.  Unless \f(CW\*(C`follow\*(C'\fR or \f(CW\*(C`follow_fast\*(C'\fR is specified, for
+compatibility reasons (find.pl, find2perl) there are in addition the
+following globals available: \f(CW$File::Find::topdir\fR,
+\&\f(CW$File::Find::topdev\fR, \f(CW$File::Find::topino\fR,
+\&\f(CW$File::Find::topmode\fR and \f(CW$File::Find::topnlink\fR.
+.PP
+This library is useful for the \f(CW\*(C`find2perl\*(C'\fR tool (distributed as part of the
+App\-find2perl CPAN distribution), which when fed,
+.PP
+.Vb 2
+\&  find2perl / \-name .nfs\e* \-mtime +7 \e
+\&    \-exec rm \-f {} \e; \-o \-fstype nfs \-prune
+.Ve
+.PP
+produces something like:
+.PP
+.Vb 10
+\& sub wanted {
+\&    /^\e.nfs.*\ez/s &&
+\&    (($dev, $ino, $mode, $nlink, $uid, $gid) = lstat($_)) &&
+\&    int(\-M _) > 7 &&
+\&    unlink($_)
+\&    ||
+\&    ($nlink || (($dev, $ino, $mode, $nlink, $uid, $gid) = lstat($_))) &&
+\&    $dev < 0 &&
+\&    ($File::Find::prune = 1);
+\& }
+.Ve
+.PP
+Notice the \f(CW\*(C`_\*(C'\fR in the above \f(CW\*(C`int(\-M _)\*(C'\fR: the \f(CW\*(C`_\*(C'\fR is a magical
+filehandle that caches the information from the preceding
+\&\f(CWstat()\fR, \f(CWlstat()\fR, or filetest.
+.PP
+Here's another interesting wanted function.  It will find all symbolic
+links that don't resolve:
+.PP
+.Vb 3
+\&    sub wanted {
+\&         \-l && !\-e && print "bogus link: $File::Find::name\en";
+\&    }
+.Ve
+.PP
+Note that you may mix directories and (non-directory) files in the list of 
+directories to be searched by the \f(CWwanted()\fR function.
+.PP
+.Vb 1
+\&    find(\e&wanted, "./foo", "./bar", "./baz/epsilon");
+.Ve
+.PP
+In the example above, no file in \fI./baz/\fR other than \fI./baz/epsilon\fR will be
+evaluated by \f(CWwanted()\fR.
+.PP
+See also the script \f(CW\*(C`pfind\*(C'\fR on CPAN for a nice application of this
+module.
+.SH WARNINGS
+.IX Header "WARNINGS"
+If you run your program with the \f(CW\*(C`\-w\*(C'\fR switch, or if you use the
+\&\f(CW\*(C`warnings\*(C'\fR pragma, File::Find will report warnings for several weird
+situations. You can disable these warnings by putting the statement
+.PP
+.Vb 1
+\&    no warnings \*(AqFile::Find\*(Aq;
+.Ve
+.PP
+in the appropriate scope. See warnings for more info about lexical
+warnings.
+.SH "BUGS AND CAVEATS"
+.IX Header "BUGS AND CAVEATS"
+.ie n .IP $dont_use_nlink 4
+.el .IP \f(CW$dont_use_nlink\fR 4
+.IX Item "$dont_use_nlink"
+You can set the variable \f(CW$File::Find::dont_use_nlink\fR to 0 if you
+are sure the filesystem you are scanning reflects the number of
+subdirectories in the parent directory's \f(CW\*(C`nlink\*(C'\fR count.
+.Sp
+If you do set \f(CW$File::Find::dont_use_nlink\fR to 0, you may notice an
+improvement in speed at the risk of not recursing into subdirectories
+if a filesystem doesn't populate \f(CW\*(C`nlink\*(C'\fR as expected.
+.Sp
+\&\f(CW$File::Find::dont_use_nlink\fR now defaults to 1 on all platforms.
+.IP symlinks 4
+.IX Item "symlinks"
+Be aware that the option to follow symbolic links can be dangerous.
+Depending on the structure of the directory tree (including symbolic
+links to directories) you might traverse a given (physical) directory
+more than once (only if \f(CW\*(C`follow_fast\*(C'\fR is in effect).
+Furthermore, deleting or changing files in a symbolically linked directory
+might cause very unpleasant surprises, since you delete or change files
+in an unknown directory.
+.SH HISTORY
+.IX Header "HISTORY"
+File::Find used to produce incorrect results if called recursively.
+During the development of perl 5.8 this bug was fixed.
+The first fixed version of File::Find was 1.01.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fBfind\fR\|(1), find2perl.