Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 229 insertions, 0 deletions

diff --git a/upstream/debian-unstable/man3/File::Copy.3perl b/upstream/debian-unstable/man3/File::Copy.3perl
new file mode 100644
index 00000000..c2d19895
--- /dev/null
+++ b/upstream/debian-unstable/man3/File::Copy.3perl
@@ -0,0 +1,229 @@
+.\" -*- 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::Copy 3perl"
+.TH File::Copy 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::Copy \- Copy files or filehandles
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 1
+\&        use File::Copy;
+\&
+\&        copy("sourcefile", "destinationfile") or die "Copy failed: $!";
+\&        copy("Copy.pm", \e*STDOUT);
+\&        move("/dev1/sourcefile", "/dev2/destinationfile");
+\&
+\&        use File::Copy "cp";
+\&
+\&        my $n = FileHandle\->new("/a/file", "r");
+\&        cp($n, "x");
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+The File::Copy module provides two basic functions, \f(CW\*(C`copy\*(C'\fR and
+\&\f(CW\*(C`move\*(C'\fR, which are useful for getting the contents of a file from
+one place to another.
+.IP copy 4
+.IX Xref "copy cp"
+.IX Item "copy"
+The \f(CW\*(C`copy\*(C'\fR function takes two
+parameters: a file to copy from and a file to copy to. Either
+argument may be a string, a FileHandle reference or a FileHandle
+glob. Obviously, if the first argument is a filehandle of some
+sort, it will be read from, and if it is a file \fIname\fR it will
+be opened for reading. Likewise, the second argument will be
+written to. If the second argument does not exist but the parent
+directory does exist, then it will be created. Trying to copy
+a file into a non-existent directory is an error.
+Trying to copy a file on top of itself is also an error.
+\&\f(CW\*(C`copy\*(C'\fR will not overwrite read-only files.
+.Sp
+If the destination (second argument) already exists and is a directory,
+and the source (first argument) is not a filehandle, then the source
+file will be copied into the directory specified by the destination,
+using the same base name as the source file.  It's a failure to have a
+filehandle as the source when the destination is a directory.
+.Sp
+\&\fBNote that passing in
+files as handles instead of names may lead to loss of information
+on some operating systems; it is recommended that you use file
+names whenever possible.\fR  Files are opened in binary mode where
+applicable.  To get a consistent behaviour when copying from a
+filehandle to a file, use \f(CW\*(C`binmode\*(C'\fR on the filehandle.
+.Sp
+An optional third parameter can be used to specify the buffer
+size used for copying. This is the number of bytes from the
+first file, that will be held in memory at any given time, before
+being written to the second file. The default buffer size depends
+upon the file, but will generally be the whole file (up to 2MB), or
+1k for filehandles that do not reference files (eg. sockets).
+.Sp
+You may use the syntax \f(CW\*(C`use File::Copy "cp"\*(C'\fR to get at the \f(CW\*(C`cp\*(C'\fR
+alias for this function. The syntax is \fIexactly\fR the same.  The
+behavior is nearly the same as well: as of version 2.15, \f(CW\*(C`cp\*(C'\fR will
+preserve the source file's permission bits like the shell utility
+\&\f(CWcp(1)\fR would do with default options, while \f(CW\*(C`copy\*(C'\fR uses the default
+permissions for the target file (which may depend on the process'
+\&\f(CW\*(C`umask\*(C'\fR, file ownership, inherited ACLs, etc.).  That is, if the
+destination file already exists, \f(CW\*(C`cp\*(C'\fR will leave its permissions
+unchanged; otherwise the permissions are taken from the source file
+and modified by the \f(CW\*(C`umask\*(C'\fR.  If an error occurs in setting
+permissions, \f(CW\*(C`cp\*(C'\fR will return 0, regardless of whether the file was
+successfully copied.
+.IP move 4
+.IX Xref "move mv rename"
+.IX Item "move"
+The \f(CW\*(C`move\*(C'\fR function also takes two parameters: the current name
+and the intended name of the file to be moved.  If the destination
+already exists and is a directory, and the source is not a
+directory, then the source file will be renamed into the directory
+specified by the destination.
+.Sp
+If possible, \fBmove()\fR will simply rename the file.  Otherwise, it copies
+the file to the new location and deletes the original.  If an error occurs
+during this copy-and-delete process, you may be left with a (possibly partial)
+copy of the file under the destination name.
+.Sp
+You may use the \f(CW\*(C`mv\*(C'\fR alias for this function in the same way that
+you may use the \f(CW\*(C`cp\*(C'\fR alias for \f(CW\*(C`copy\*(C'\fR.
+.IP syscopy 4
+.IX Xref "syscopy"
+.IX Item "syscopy"
+File::Copy also provides the \f(CW\*(C`syscopy\*(C'\fR routine, which copies the
+file specified in the first parameter to the file specified in the
+second parameter, preserving OS-specific attributes and file
+structure.  For Unix systems, this is equivalent to the simple
+\&\f(CW\*(C`copy\*(C'\fR routine, which doesn't preserve OS-specific attributes.  For
+VMS systems, this calls the \f(CW\*(C`rmscopy\*(C'\fR routine (see below).  For OS/2
+systems, this calls the \f(CW\*(C`syscopy\*(C'\fR XSUB directly. For Win32 systems,
+this calls \f(CW\*(C`Win32::CopyFile\*(C'\fR.
+.Sp
+\&\fBSpecial behaviour if \fR\f(CB\*(C`syscopy\*(C'\fR\fB is defined (OS/2, VMS and Win32)\fR:
+.Sp
+If both arguments to \f(CW\*(C`copy\*(C'\fR are not file handles,
+then \f(CW\*(C`copy\*(C'\fR will perform a "system copy" of
+the input file to a new output file, in order to preserve file
+attributes, indexed file structure, \fIetc.\fR  The buffer size
+parameter is ignored.  If either argument to \f(CW\*(C`copy\*(C'\fR is a
+handle to an opened file, then data is copied using Perl
+operators, and no effort is made to preserve file attributes
+or record structure.
+.Sp
+The system copy routine may also be called directly under VMS and OS/2
+as \f(CW\*(C`File::Copy::syscopy\*(C'\fR (or under VMS as \f(CW\*(C`File::Copy::rmscopy\*(C'\fR, which
+is the routine that does the actual work for syscopy).
+.IP rmscopy($from,$to[,$date_flag]) 4
+.IX Xref "rmscopy"
+.IX Item "rmscopy($from,$to[,$date_flag])"
+The first and second arguments may be strings, typeglobs, typeglob
+references, or objects inheriting from IO::Handle;
+they are used in all cases to obtain the
+\&\fIfilespec\fR of the input and output files, respectively.  The
+name and type of the input file are used as defaults for the
+output file, if necessary.
+.Sp
+A new version of the output file is always created, which
+inherits the structure and RMS attributes of the input file,
+except for owner and protections (and possibly timestamps;
+see below).  All data from the input file is copied to the
+output file; if either of the first two parameters to \f(CW\*(C`rmscopy\*(C'\fR
+is a file handle, its position is unchanged.  (Note that this
+means a file handle pointing to the output file will be
+associated with an old version of that file after \f(CW\*(C`rmscopy\*(C'\fR
+returns, not the newly created version.)
+.Sp
+The third parameter is an integer flag, which tells \f(CW\*(C`rmscopy\*(C'\fR
+how to handle timestamps.  If it is < 0, none of the input file's
+timestamps are propagated to the output file.  If it is > 0, then
+it is interpreted as a bitmask: if bit 0 (the LSB) is set, then
+timestamps other than the revision date are propagated; if bit 1
+is set, the revision date is propagated.  If the third parameter
+to \f(CW\*(C`rmscopy\*(C'\fR is 0, then it behaves much like the DCL COPY command:
+if the name or type of the output file was explicitly specified,
+then no timestamps are propagated, but if they were taken implicitly
+from the input filespec, then all timestamps other than the
+revision date are propagated.  If this parameter is not supplied,
+it defaults to 0.
+.Sp
+\&\f(CW\*(C`rmscopy\*(C'\fR is VMS specific and cannot be exported; it must be
+referenced by its full name, e.g.:
+.Sp
+.Vb 1
+\&  File::Copy::rmscopy($from, $to) or die $!;
+.Ve
+.Sp
+Like \f(CW\*(C`copy\*(C'\fR, \f(CW\*(C`rmscopy\*(C'\fR returns 1 on success.  If an error occurs,
+it sets \f(CW$!\fR, deletes the output file, and returns 0.
+.SH RETURN
+.IX Header "RETURN"
+All functions return 1 on success, 0 on failure.
+$! will be set if an error was encountered.
+.SH NOTES
+.IX Header "NOTES"
+Before calling \fBcopy()\fR or \fBmove()\fR on a filehandle, the caller should
+close or \fBflush()\fR the file to avoid writes being lost. Note that this
+is the case even for \fBmove()\fR, because it may actually copy the file,
+depending on the OS-specific implementation, and the underlying
+filesystem(s).
+.SH AUTHOR
+.IX Header "AUTHOR"
+File::Copy was written by Aaron Sherman \fI<ajs@ajs.com>\fR in 1995,
+and updated by Charles Bailey \fI<bailey@newman.upenn.edu>\fR in 1996.