File::NCopy::copy copies files to directories, or a single file to
another file.  You can also use a reference to a file handle if you wish
whem doing a file to file copy.  The functionality is very similar to
cp.  If the argument is a directory to directory copy and the
recursive flag is set then it is done recursively like cp -R.
In fact it behaves like cp on Unix for the most part.
If called in array context, an array of successful copies is returned,
otherwise the number of succesful copies is returned.  If passed a file
handle, it's difficult to make sure the file we are copying isn't the
same that we are copying to, since by opening the file in write mode it
gets pooched.  To avoid this use file names instead, if at all possible,
especially for the to file.  If passed a file handle, it is not closed
when copy returns, files opened by copy are closed.

=over 4

=item copy

Copies a file to another file.  Or a file to a directory.  Or multiple
files and directories to another directory.  Or a directory to another
directory.  Wildcard arguments are expanded, except for the last
argument which should not be expanded.  The file and directory
permissions are set to the orginating file's permissions and if preserve
is set the access and modification times are also set.  If preserve is
set then the uid and gid will also be attempted to be set, though this
may only for for the men in white hats.
In list context it returns all the names of the files/directories that
were successfully copied.  In scalar context it returns the number of
successful copies made.  A directory argument is considerd a single
successful copy if it manages to copy anything at all.  To make a
directory to directory copy the recursive flag must be set.

=item cp

Just calls copy.  It's there to be compatible with File::Copy.

=item new

If used then you can treat this as an object oriented module with some
configuration abilities.

=item recursive

If used as an object then you can use this to set the recursive
attribute.  It can also be set when instantiating with new.  The other
attributes must all be set when instantiating the object.  If it isn't
specified then directories are not followed.

=item preserve

Attempt to preserve the last modification and access time as well as
user and group id's.  This is a useful feature for sysadmins, though the
access and modification time should always be preservable, the uid and
gid may not.

=item follow_links

If the link is to a directory and this attribute is true then the
directory is followed and recursively copied.  Otherwise a link is made
to the root directory the link points to. eg.

/sys/ is a link to /usr/src/sys/ is a link to /usr/src/i386/sys
then the link /sys/ is actually created in the source directory as a
link to /usr/src/i386/sys/ rather than /usr/src/sys/ since if the link
/usr/src/sys/ is removed then we lost the link even though the directory
we originally intended to link to still exists.

=item force_write

Force the writing of a file even if the permissions are read only on it.

=back

• Vitaly Lipatov

• perl-File-NCopy