cp -- copy files
DESCRIPTION
ENVIRONMENT VARIABLES
DIAGNOSTICS
PORTABILITY
AVAILABILITY
cp [-acfimPpqSv]
file1 file2
cp [-acfimPpqSv] file ...
cp -R [-acfimPpqSv]
source... directory
cp -r [-acfimPpqSv]
source... directory
cp copies files to a target named by the last argument on
its command line.
If the target is an existing file, cp
if it does not exist, cp creates it.
If the target file already exists and does not have write permission,
cp denies access and continues with the next copy.
If you specify more than two path names, the last path name (that is, the
target) must be a directory.
If the target is a directory, cp copies the sources into
that directory with names given by the final component of the source path name.
Normally, the destination file has its file mode (see
) set to 777 (that is, readable, writable, and
executable by everyone) and sets the file modification time to the present.
The -m and -p
options can override this behavior.
If a file being copied is a sparse file and the file system to which it is
being copied does not support sparse files, cp warns that
the resulting file will be larger. If the -i option was
also specified, cp asks you if want to expand the file or
skip it. The -S option overrides this behavior and expands
all sparse files automatically when copying.
copies the DACLs associated with the specified file along with the file
This option is only available on NTFS file systems.
prompts you to change the diskette if there is insufficient room to
complete a copy operation. The parent directories must already exist on
the new target diskette. This option has no effect on systems without
floppy drives.
attempts to replace files that do not have write permission.
asks you if you want to overwrite an existing file, whether or not the file
is read-only.
sets the modification time, access time, and file mode
(see ) of each destination file to those
of the corresponding source file.
The compression and archive bits of the file mode are handled separately.
The compression bit for each destination file is always unset, while
the archive bit is always set.
prevents the -m and -p options from copying
the file mode (see ). This option always sets the
archive bit on the copied file.
The behavior of this option is identical to setting the
TK_CP_NOPRESERVE environment variable.
is similar to the -m option, but also sets the owner and group
of each destination file to the owner and group of the corresponding source
Unlike the -m option, the archive bit of all destination
files is always unset.
suppresses warning messages. Error messages are still displayed.
reproduces the source trees.
cp copies all files and subdirectories
specified by source.... into directory,
making careful arrangements to duplicate special files (FIFO,
block special, character special).
reproduces the source trees, but makes no allowances for special files
(FIFO, block special, character special).
Consequently, cp attempts to read from a device rather
than duplicate the special file.
This is similar to, but less useful than, the preferred -R.
automatically expands sparse files. This lets you make a non-sparse copy
of a sparse file.
prints file names to standard output as they are being processed.
TK_CP_NOPRESERVE&
when set, this variable prevents the -m and
-p options from copying
the file mode (see ). This option always sets the
archive bit on the copied file.
Possible exit status values are:
Successful completion.
Failure due to any of the following:
— an argument had a trailing slash (/) but was not a directory
— unable to find a file
— unable to open an input file for reading
— unable to create or open an output file
— a read error occurred on an input file
— a write error occurred on an output file
— the input and output files were the same file
— encountered a fatal error when using -r or -R
Possible fatal -r or -R errors include:
— inability to access a file
— inability to change permissions on a target file
— inability to read a directory
— inability to create a directory
— a target that is not a directory
— source and destination directories are the same
Failure due to any of the following:
— an invalid command line option
— too few arguments on the command line
— a target that should be a directory but is not
— no space left on target device
— out of memory to hold the data to be copied
— inability to create a directory to hold a target file
cannot allocate target string&
cp has no space to hold the name of the target file.
Try to free up some memory to give cp more space.
"name" is a directory (not copied)&
You did not specify -r or -R,
but one of the names you asked to copy was the name of a directory.
"target name"?&
You are attempting to copy a file with the -i option,
but there is already a file with the target name.
If you have specified -f, you can write over the existing
file by typing y and pressing ENTER;
if you do not want to write over the existing file, type n
and press ENTER. If you did not specify -f and the
file is read only, you are not given the opportunity to overwrite it.
source "name" and target "name"
are identical&
The source and the target are actually the same file (for example because
of links, on UNIX and POSIX-compliant systems).
In this case, cp does nothing.
unreadable directory "name"&
cp cannot read the specified directory, for example,
because you do not have appropriate permissions.
x/OPEN Portability Guide 4.0.
All UNIX systems.
Windows 7. Windows Server 2008 R2. Windows 8. Windows Server 2012. Windows 10. Windows Server 2016.
The -c, -f, -m,
-q and -v options are extensions
to the POSIX standard.
On Windows systems, the -R and -r
options are equivalent since special files (FIFO, block special, character
special) are not supported on Windows file systems.
PTC MKS Toolkit for Power Users
PTC MKS Toolkit for System Administrators
PTC MKS Toolkit for Developers
PTC MKS Toolkit for Interoperability
PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition
PTC Integrity
PTC MKS Toolkit 10.1 Documentation Build 15.The Open Group Base Specifications Issue 7
IEEE Std 8, 2016 Edition
Copyright &
The IEEE and The Open Group
cp - copy files
cp [-Pfip] source_file target_file
cp [-Pfip] source_file... target
cp -R [-H|-L|-P] [-fip] source_file... target
DESCRIPTION
The first synopsis form is denoted by two operands, neither of which are existing files of type directory. The cp utility
shall copy the contents of source_file (or, if source_file is a file of type symbolic link, the contents of the file
referenced by source_file) to the destination path named by target_file.
The second synopsis form is denoted by two or more operands where the -R option is not specified and the first synopsis
form is not applicable. It shall be an error if any source_file is a file of type directory, if target does not
exist, or if target does not name a directory. The cp utility shall copy the contents of each source_file (or,
if source_file is a file of type symbolic link, the contents of the file referenced by source_file) to the
destination path named by the concatenation of target, a single &slash& character if target did not end in a
&slash&, and the last component of source_file.
The third synopsis form is denoted by two or more operands where the -R option is specified. The cp utility shall
copy each file in the file hierarchy rooted in each source_file to a destination path named as follows:
If target exists and names an existing directory, the name of the corresponding destination path for each file in the
file hierarchy shall be the concatenation of target, a single &slash& character if target did not end in a
&slash&, and the pathname of the file relative to the directory containing source_file.
If target does not exist and two operands are specified, the name of the corresponding destination path for
source_file shall be target; the name of the corresponding destination path for all other files in the file hierarchy
shall be the concatenation of target, a &slash& character, and the pathname of the file relative to
source_file.
It shall be an error if target does not exist and more than two operands are specified, or if target exists and
does not name a directory.
In the following description, the term dest_file refers to the file named by the destination path. The term
source_file refers to the file that is being copied, whether specified as an operand or a file in a file hierarchy rooted in
a source_file operand. If source_file is a file of type symbolic link:
If the -R option was not specified, cp shall take actions based on the type and contents of the file referenced by
the symbolic link, and not by the symbolic link itself, unless the -P option was specified.
If the -R option was specified:
If none of the options -H, -L, nor -P were specified, it is unspecified which of -H, -L, or
-P will be used as a default.
If the -H option was specified, cp shall take actions based on the type and contents of the file referenced by any
symbolic link specified as a source_file operand.
If the -L option was specified, cp shall take actions based on the type and contents of the file referenced by any
symbolic link specified as a source_file operand or any symbolic links encountered during traversal of a file hierarchy.
If the -P option was specified, cp shall copy any symbolic link specified as a source_file operand and any
symbolic links encountered during traversal of a file hierarchy, and shall not follow any symbolic links.
For each source_file, the following steps shall be taken:
If source_file references the same file as dest_file, cp may write a diagnostic messa
it shall do nothing more with source_file and shall go on to any remaining files.
If source_file is of type directory, the following steps shall be taken:
If the -R option was not specified, cp shall write a diagnostic message to standard error, do nothing more with
source_file, and go on to any remaining files.
If source_file was not specified as an operand and source_file is dot or dot-dot, cp shall do nothing more
with source_file and go on to any remaining files.
If dest_file exists and it is a file type not specified by the System Interfaces volume of POSIX.1-2008, the behavior is
implementation-defined.
If dest_file exists and it is not of type directory, cp shall write a diagnostic message to standard error, do
nothing more with source_file or any files below source_file in the file hierarchy, and go on to any remaining
If the directory dest_file does not exist, it shall be created with file permission bits set to the same value as those
of source_file, modified by the file creation mask of the user if the -p option was not specified, and then
bitwise-inclusively OR'ed with S_IRWXU. If dest_file cannot be created, cp shall write a diagnostic message to
standard error, do nothing more with source_file, and go on to any remaining files. It is unspecified if cp attempts
to copy files in the file hierarchy rooted in source_file.
The files in the directory source_file shall be copied to the directory dest_file, taking the four steps (1 to 4)
listed here with the files as source_files.
If dest_file was created, its file permission bits shall be changed (if necessary) to be the same as those of
source_file, modified by the file creation mask of the user if the -p option was not specified.
The cp utility shall do nothing more with source_file and go on to any remaining files.
If source_file is of type regular file, the following steps shall be taken:
The behavior is unspecified if dest_file exists and was written by a previous step. Otherwise, if dest_file
exists, the following steps shall be taken:
If the -i option is in effect, the cp utility shall write a prompt to the standard error and read a line from the
standard input. If the response is not affirmative, cp shall do nothing more with source_file and go on to any
remaining files.
A file descriptor for dest_file shall be obtained by performing actions equivalent to the
function defined in the System Interfaces volume of POSIX.1-2008 called using
dest_file as the path argument, and the bitwise-inclusive OR of O_WRONLY and O_TRUNC as the oflag
If the attempt to obtain a file descriptor fails and the -f option is in effect, cp shall attempt to remove the
file by performing actions equivalent to the
function defined in the System
Interfaces volume of POSIX.1-2008 called using dest_file as the path argument. If this attempt succeeds, cp
shall continue with step 3b.
If dest_file does not exist, a file descriptor shall be obtained by performing actions equivalent to the
function defined in the System Interfaces volume of POSIX.1-2008 called using
dest_file as the path argument, and the bitwise-inclusive OR of O_WRONLY and O_CREAT as the oflag argument.
The file permission bits of source_file shall be the mode argument.
If the attempt to obtain a file descriptor fails, cp shall write a diagnostic message to standard error, do nothing more
with source_file, and go on to any remaining files.
The contents of source_file shall be written to the file descriptor. Any write errors shall cause cp to write a
diagnostic message to standard error and continue to step 3e.
The file descriptor shall be closed.
The cp utility shall do nothing more with source_file. If a write error occurred in step 3d, it is unspecified if
cp continues with any remaining files. If no write error occurred in step 3d, cp shall go on to any remaining
Otherwise, the -R option was specified, and the following steps shall be taken:
The dest_file shall be created with the same file type as source_file.
If source_file is a file of type FIFO, the file permission bits shall be the same as those of source_file,
modified by the file creation mask of the user if the -p option was not specified. Otherwise, the permissions, owner ID, and
group ID of dest_file are implementation-defined.
If this creation fails for any reason, cp shall write a diagnostic message to standard error, do nothing more with
source_file, and go on to any remaining files.
If source_file is a file of type symbolic link, and the options require the symbolic link itself to be acted upon, the
pathname contained in dest_file shall be the same as the pathname contained in source_file.
If this fails for any reason, cp shall write a diagnostic message to standard error, do nothing more with
source_file, and go on to any remaining files.
If the implementation provides additional or alternate access control mechanisms (see XBD ), their effect on copies of files is
implementation-defined.
The cp utility shall conform to XBD
The following options shall be supported:
If a file descriptor for a destination file cannot be obtained, as described in step 3.a.ii., attempt to unlink the destination
file and proceed.
Take actions based on the type and contents of the file referenced by any symbolic link specified as a source_file
Write a prompt to standard error before copying to any existing non-directory destination file. If the response from the
standard input is affirmative, the cop otherwise, it shall not.
Take actions based on the type and contents of the file referenced by any symbolic link specified as a source_file
operand or any symbolic links encountered during traversal of a file hierarchy.
Take actions on any symbolic link specified as a source_file operand or any symbolic link encountered during traversal
of a file hierarchy.
Duplicate the following characteristics of each source file in the corresponding destination file:
The time of last data modification and time of last access. If this duplication fails for any reason, cp shall write a
diagnostic message to standard error.
The user ID and group ID. If this duplication fails for any reason, it is unspecified whether cp writes a diagnostic
message to standard error.
The file permission bits and the S_ISUID and S_ISGID bits. Other, implementation-defined, bits may be duplicated as well. If
this duplication fails for any reason, cp shall write a diagnostic message to standard error.
If the user ID or the group ID cannot be duplicated, the file permission bits S_ISUID and S_ISGID shall be cleared. If these
bits are present in the source file but are not duplicated in the destination file, it is unspecified whether cp writes a
diagnostic message to standard error.
The order in which the preceding characteristics are duplicated is unspecified. The dest_file shall not be deleted if
these characteristics cannot be preserved.
Copy file hierarchies.
Specifying more than one of the mutually-exclusive options -H, -L, and -P shall not be considered an error.
The last option specified shall determine the behavior of the utility.
The following operands shall be supported:
source_file
A pathname of a file to be copied. If a source_file operand is '-', it shall refer to a file named -;
implementations shall not treat it as meaning standard input.
target_file
A pathname of an existing or nonexistent file, used for the output when a single file is copied. If a target_file
operand is '-', it shall refer to a file named -; implementations shall not treat it as meaning standard
A pathname of a directory to contain the copied files.
The standard input shall be used to read an input line in response to each prompt specified in the STDERR section. Otherwise,
the standard input shall not be used.
INPUT FILES
The input files specified as operands may be of any file type.
ENVIRONMENT VARIABLES
The following environment variables shall affect the execution of cp:
Provide a default value for the internationalization variables that are unset or null. (See XBD
for the precedence of internationalization
variables used to determine the values of locale categories.)
If set to a non-empty string value, override the values of all the other internationalization variables.
LC_COLLATE
Determine the locale for the behavior of ranges, equivalence classes, and multi-character collating elements used in the extended
regular expression defined for the yesexpr locale keyword in the LC_MESSAGES category.
Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as
opposed to multi-byte characters in arguments and input files) and the behavior of character classes used in the extended regular
expression defined for the yesexpr locale keyword in the LC_MESSAGES category.
LC_MESSAGES
Determine the locale used to process affirmative responses, and the locale used to affect the format and contents of diagnostic
messages and prompts written to standard error.
Determine the location of message catalogs for the processing of LC_MESSAGES.
ASYNCHRONOUS EVENTS
A prompt shall be written to standard error under the conditions specified in the DESCRIPTION section. The prompt shall contain
the destination pathname, but its format is otherwise unspecified. Otherwise, the standard error shall be used only for diagnostic
OUTPUT FILES
The output files may be of any type.
EXTENDED DESCRIPTION
EXIT STATUS
The following exit values shall be returned:
All files were copied successfully.
An error occurred.
CONSEQUENCES OF ERRORS
If cp is prematurely terminated by a signal or error, files or file hierarchies may be only partially copied and files
and directories may have incorrect permissions or access and modification times.
The following sections are informative.
APPLICATION USAGE
The set-user-ID and set-group-ID bits are explicitly cleared when files are created. This is to prevent users from creating
programs that are set-user-ID or set-group-ID to them when copying files or to make set-user-ID or set-group-ID files accessible to
new groups of users. For example, if a file is set-user-ID and the copy has a different group ID than the source, a new group of
users has execute permission to a set-user-ID program than did previously. In particular, this is a problem for superusers copying
users' trees.
The -i option exists on BSD systems, giving applications and users a way to avoid accidentally removing files when
copying. Although the 4.3 BSD version does not prompt if the standard input is not a terminal, the standard developers decided that
use of -i is a request for interaction, so when the destination path exists, the utility takes instructions from whatever
responds on standard input.
The exact format of the interactive prompts is unspecified. Only the general nature of the contents of prompts are specified
because implementations may desire more descriptive prompts than those used on historical implementations. Therefore, an
application using the -i option relies on the system to provide the most suitable dialog directly with the user, based on
the behavior specified.
The -p option is historical practice on BSD systems, duplicating the time of last data modification and time of last
access. This volume of POSIX.1-2008 extends it to preserve the user and group IDs, as well as the file permissions. This
requirement has obvious problems in that the directories are almost certainly modified after being copied. This volume of
POSIX.1-2008 requires that the modification times be preserved. The statement that the order in which the characteristics are
duplicated is unspecified is to permit implementations to provide the maximum amount of security for the user. Implementations
should take into account the obvious security issues involved in setting the owner, group, and mode in the wrong order or creating
files with an owner, group, or mode different from the final value.
It is unspecified whether cp writes diagnostic messages when the user and group IDs cannot be set due to the widespread
practice of users using -p to duplicate some portion of the file characteristics, indifferent to the duplication of others.
Historic implementations only write diagnostic messages on errors other than [EPERM].
Earlier versions of this standard included support for the -r option to copy file hierarchies. The -r option is
historical practice on BSD and BSD-derived systems. This option is no longer specified by POSIX.1-2008 but may be present in some
implementations. The -R option was added as a close synonym to the -r option, selected for consistency with all other
options in this volume of POSIX.1-2008 that do recursive directory descent.
The difference between -R and the removed -r option is in the treatment by cp of file types other than
regular and directory. It was implementation-defined how the - option treated special files to allow both historical
implementations and those that chose to support -r with the same abilities as -R defined by this volume of
POSIX.1-2008. The original -r flag, for historic reasons, did not handle special files any differently from regular files,
but always read the file and copied its contents. This had obvious problems in the presence o for example,
character devices, FIFOs, and sockets.
When a failure occurs during the copying of a file hierarchy, cp is required to attempt to copy files that are on the
same level in the hierarchy or above the file where the failure occurred. It is unspecified if cp shall attempt to copy
files below the file where the failure occurred (which cannot succeed in any case).
Permissions, owners, and groups of created special file types have been deliberately left as implementation-defined. This is to
allow systems to satisfy special requirements (for example, allowing users to create character special devices, but requiring them
to be owned by a certain group). In general, it is strongly suggested that the permissions, owner, and group be the same as if the
user had run the historical mknod, , or other utility to create the file. It is
also probable that additional privileges are required to create block, character, or other implementation-defined special file
Additionally, the -p option explicitly requires that all set-user-ID and set-group-ID permissions be discarded if any of
the owner or group IDs cannot be set. This is to keep users from unintentionally giving away special privilege when copying
When creating regular files, historical versions of cp use the mode of the source file as modified by the file mode
creation mask. Other choices would have been to use the mode of the source file unmodified by the creation mask or to use the same
mode as would be given to a new file created by the user (plus the execution bits of the source file) and then modify it by the
file mode creation mask. In the absence of any strong reason to change historic practice, it was in large part retained.
When creating directories, historical versions of cp use the mode of the source directory, plus read, write, and search
bits for the owner, as modified by the file mode creation mask. This is done so that cp can copy trees where the user has
read permission, but the owner does not. A side-effect is that if the file creation mask denies the owner permissions, cp
fails. Also, once the copy is done, historical versions of cp set the permissions on the created directory to be the same as
the source directory, unmodified by the file creation mask.
This behavior has been modified so that cp is always able to create the contents of the directory, regardless of the file
creation mask. After the copy is done, the permissions are set to be the same as the source directory, as modified by the file
creation mask. This latter change from historical behavior is to prevent users from accidentally creating directories with
permissions beyond those they would normally set and for consistency with the behavior of cp in creating files.
It is not a requirement that cp detect attempts to c however, implementations are strongly
encouraged to do so. Historical implementations have detected the attempt in most cases.
There are two methods of copying subtrees in this volume of POSIX.1-2008. The other method is described as part of the
utility (see ). Both methods are historical
practice. The cp utility provides a simpler, more intuitive interface, while
offers a finer granularity of control. Each provides additional functi in particular,
maintains the hard-link structure of the hierarchy, while cp does not. It is the
intention of the standard developers that the results be similar (using appropriate option combinations in both utilities). The
results are not requ there seemed insufficient gain to applications to balance the difficulty of
implementations having to guarantee that the results would be exactly identical.
The wording allowing cp to copy a directory to implementation-defined file types not specified by the System Interfaces
volume of POSIX.1-2008 is provided so that implementations supporting symbolic links are not required to prohibit copying
directories to symbolic links. Other extensions to the System Interfaces volume of POSIX.1-2008 file types may need to use this
loophole as well.
FUTURE DIRECTIONS
CHANGE HISTORY
First released in Issue 2.
The -r option is marked obsolescent.
The new options -H, -L, and -P are added to align with the IEEE&P1003.2b draft standard. These options
affect the processing of symbolic links.
IEEE PASC Interpretation 4 is applied, adding a description of the -P option.
IEEE&Std&1/Cor&1-2002, item XCU/TC1/D6/18 is applied, correcting an error in the SEE ALSO section.
Austin Group Interpretation 1 #126 is applied, changing the description of the LC_MESSAGES environment
Austin Group Interpretations 1 #092, #164, #165, and #168 are applied.
SD5-XCU-ERN-31 and SD5-XCU-ERN-42 are applied, updating the DESCRIPTION.
SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.
SD5-XCU-ERN-102 is applied, clarifying the -i option within the OPTIONS section.
The obsolescent -r option is removed.
The -P option is added to the SYNOPSIS and to the DESCRIPTION with respect to the -R option.
End of informative text.
UNIX & is a registered Trademark of The Open Group.
POSIX & is a registered Trademark of The IEEE.
Copyright &
The IEEE and The Open Group, All Rights Reserved