cp(1)cp(1)NAMEcp - copy files and directory subtrees
SYNOPSIS
extarg] file1 new_file
extarg] file1 [file2 ...] dest_directory
extarg] directory1 [directory2 ...] dest_directory
extarg] file1|directory1 [file2|directory2 ...] dest_directory
DESCRIPTION
copies:
· file1 to new or existing new_file,
· file1 to existing dest_directory,
· file1, file2, ... to existing dest_directory,
· directory subtree directory1, to new or existing dest_direc‐
tory. or
· multiple directory subtrees directory1, directory2, ... to
new or existing dest_directory.
fails if file1 and new_file are the same (be cautious when using shell
metacharacters). When destination is a directory, one or more files
are copied into that directory. If two or more files are copied, the
destination must be a directory. When copying a single file to a new
file, if new_file exists, its contents are destroyed.
If the access permissions of the destination dest_directory or existing
destination file new_file forbid writing, aborts and produces an error
message "cannot create file".
To copy one or more directory subtrees to another directory, the option
is required. The option is ignored if used when copying a file to
another file or files to a directory.
If new_file is a link to an existing file with other links, overwrites
the existing file and retains all links. If copying a file to an
existing file, does not change existing file access permission bits,
owner, or group.
When copying files to a directory or to a new file that does not
already exist, creates a new file with the same file permission bits as
file1, modified by the file creation mask of the user if the option was
not specified, and then bitwise inclusively ORed with S_IRWXU. The
owner and group of the new file or files are those of the user. The
last modification time of new_file (and last access time, if new_file
did not exist) and the last access time of the source file1 are set to
the time the copy was made.
Options
(interactive copy) Causes
to write a prompt to standard error and wait for a response
before copying a file that would overwrite an existing file.
If the response from the standard input is affirmative, the
file is copied if permissions allow the copy.
(force copy) Forces existing destination pathnames to be removed before
copying,
without prompting for confirmation. This option has the effect
of destroying and replacing any existing file whose name and
directory location conflicts with the name and location of the
new file created by the copy operation.
When the flag is set and if the destination file exists and the
user has write permission on the destination file, then the
destination file is not removed.
(preserve permissions) Causes
to preserve in the copy as many of the modification time,
access time, file mode, user ID, and group ID as allowed by
permissions.
(recursive subtree copy) Causes
to copy the subtree rooted at each source directory to
dest_directory. If dest_directory exists, it must be a direc‐
tory, in which case creates a directory within dest_directory
with the same name as file1 and copies the subtree rooted at
file1 to dest_directory/file1. An error occurs if dest_direc‐
tory/file1 already exists. If dest_directory does not exist,
creates it and copies the subtree rooted at file1 to
dest_directory. Note that cannot merge subtrees.
Usually normal files and directories are copied. Character
special devices, block special devices, network special files,
named pipes, symbolic links, and sockets are copied, if the
user has access to the file; otherwise, a warning is printed
stating that the file cannot be created, and the file is
skipped.
dest_directory should not reside within directory1, nor should
directory1 have a cyclic directory structure, since in both
cases attempts to copy an infinite amount of data.
Under the UNIX Standard environment (see standards(5)), will
exit with error if multiple sources are being copied to a non-
existing directory.
(recursive subtree copy) The
option is identical to the option.
With the and options, in addition to regular files and directo‐
ries, also copies FIFOs, character and block device files and
symbolic links. Only superusers can copy device files. All
other users get an error. Symbolic links are copied so the
target points to the same location that the source did.
Warning: While copying a directory tree that has device spe‐
cial files, use the option; otherwise, an infinite amount of
data is read from the device special file and is duplicated as
a special file in the destination directory occupying large
file system space.
Causes to traverse the symbolic link specified as an operand and copy
it to the destination.
Causes to traverse the symbolic link specified as an operand or any
symbolic links encountered during traversal of a file hierar‐
chy, and copy it to the destination.
Causes to copy the symbolic link specified as an operand and any sym‐
bolic links encountered during traversal of a file hierarchy.
This option will not follow any symbolic links.
Specifies the handling of any extent attributes of the file[s] to be
copied. extarg takes one of the following values.
Issues a warning message if extent attributes cannot be
copied,
but copies the file anyway.
Does not copy the extent attributes.
Fails to copy the file if the extent attribute can not be
copied.
Extent attributes can not be copied if the files are being
copied to a file system which does not support extent
attributes or if that file system has a different block size
than the original. If is not specified, the default value for
extarg is
Specifies "safe" mode. This option minimizes the impact of
on the performance of the system by opening the target file
using the flag. This is recommended when the total size of the
copy (not of a single file) is a significant portion of the
size of system buffer cache. Usage of this option increases
copy time.
Causes not to copy ACL attributes of the source to destination.
Specifying more than one of the mutually-exclusive options and will not
be considered an error. The last option specified will determine the
behavior of the utility.
Access Control Lists (ACLs)
If new_file is a new file, or if a new file is created in dest_direc‐
tory, it inherits the access control list of the original file1, file2,
etc., altered to reflect any difference in ownership between the two
files (see acl(5) and aclv(5)). In JFS file systems, new files created
by do not inherit their parent directory's default ACL entries (if
any), but instead retain the ACLs of the files being copied. When
copying files from a JFS file system to an HFS file system or vice
versa, optional ACL entries are lost.
If is used with the option, ACL entries will not be copied to the des‐
tination. If the destination file does not already exits and the
option is not specified, then the file permission bits of the destina‐
tion will be set according to the file creation mask of the user.
EXTERNAL INFLUENCES
For information about the UNIX standard environment, see standards(5).
Environment Variables
determines the interpretation of text as single and/or multi-byte char‐
acters.
and determine the local language equivalent of (for yes/no queries).
determines the language in which messages are displayed.
If is not specified in the environment or is set to the empty string,
the value of is used as a default for each unspecified or empty vari‐
able. If is not specified or is set to the empty string, a default of
"C" (see lang(5)) is used instead of If any internationalization vari‐
able contains an invalid setting, behaves as if all internationaliza‐
tion variables are set to "C". See environ(5).
International Code Set Support
Single- and multi-byte character code sets are supported.
EXAMPLES
The following command moves the directory sourcedir and its contents to
a new location (targetdir) in the file system. Since creates the new
directory, the destination directory targetdir should not already
exist.
The option copies the subtree (files and subdirectories) in directory
sourcedir to directory targetdir. The double ampersand causes a condi‐
tional action. If the operation on the left side of the is successful,
the right side is executed (and removes the old directory). If the
operation on the left of the is not successful, the old directory is
not removed.
This example is equivalent to:
To copy all files and directory subtrees in the current directory to an
existing targetdir, use:
To copy all files and directory subtrees in sourcedir to targetdir,
use:
Note that directory pathnames can precede both sourcedir and targetdir.
To create a zero-length file, use any of the following:
DEPENDENCIES
NFS
Access control lists of networked files are summarized (as returned in
by but not copied to the new file. When using or on such files, a is
not printed after the mode value when asking for permission to over‐
write a file.
AUTHOR
was developed by AT&T, the University of California, Berkeley, and HP.
SEE ALSOcpio(1), ln(1), mv(1), rm(1), link(1M), lstat(2), readlink(2), stat(2),
symlink(2), symlink(4), acl(5), aclv(5), standards(5).
STANDARDS CONFORMANCEcp(1)