Copy files (POSIX)
cp [-f|-i] [-Rrp] [QNX Neutrino extensions] source_file target_file cp [-f|-i] [-Rrp] [QNX Neutrino extensions] source_file... target_dir
- (BlackBerry PlayBook OS extension) Preserve source file access times.
- (BlackBerry PlayBook OS extension) Use a very small (2 KB) copy buffer.
- (BlackBerry PlayBook OS extension) Create any directories necessary to open the destination path. For
example, if the directory /home/eric
doesn't exist, and you enter:
cp -c file /home/eric/source/file
cp performs the equivalent of:
mkdir -p /home/eric/source cp file /home/eric/source/file
- (BlackBerry PlayBook OS extension) Descend past device boundaries when using the -R option. This is the default behavior; if you want to prevent cp -R from descending past device boundaries, use the -N option.
- (BlackBerry PlayBook OS extension) Force the unlinking of the destination file prior to copying. This option prevents interactive prompting (unless you also specify -i) but doesn't disable diagnostic messages.
- Run interactively; always prompt for confirmation
when the destination path exists, regardless of whether you have
write permission for the destination file. The -i option
is useful when you want to avoid accidentally clobbering files when
copying. When you don't have write permission for the destination
file and you answer yes to the prompt, the destination file is
unlinked first. Otherwise, the destination is simply overwritten and
The combination of -i and -f works as if you specified only -i, except that when you answer yes to the prompt, the destination is always unlinked first — even if you have write permission for the destination file. When you specify only -i, the destination is unlinked only when you don't have write permission for the destination file.
- -l n
- (el — QNX Neutrino extension) If source_file is a directory, and you specify the -R or -r option, copy only n levels of the directory tree. If you specify -l 0, -R or -r is defeated; only files at the current level (files named directly on the command line) are copied.
- (BlackBerry PlayBook OS extension) Attempt to preserve hard links. When cp encounters a file that has a link count greater than 1, it remembers that file's device ID and serial number (inode). If during the cp another file with a link count greater than 1 is found matching the serial number and device ID, cp creates a link instead of making a second copy of the file. When the destination media is changed, cp wipes its memory of links encountered to that point. (This is significant when making floppy backups, or backups to removable hard disks.)
- -M qnx|unix
- (BlackBerry PlayBook OS extension) Do recursive copies in UNIX (the default)
or old-style QNX mode.
QNX has, in the past, copied the contents of the directories named on the command line into the target directory. UNIX copies the directory itself into the target directory (like mv). In either case, if there's only one directory being copied and the destination names a directory that doesn't exist, cp creates the destination directory and then copies the contents of the source directory into the destination directory.The default mode under QNX Neutrino is different from that under QNX 4.
For more information, see Recursive Copying, below.
- (BlackBerry PlayBook OS extension) Don't descend past device boundaries when using
the -R option.
By default, cp -R descends past device boundaries while traversing a
directory tree; specifying -N prevents this behavior. For example:
cp -R / /hd/backup
causes cp to back up the contents of the disk, including the contents of the /dev directory.In this particular example, only the disk devices (block special files) actually have their data backed up to files in /hd/backup/dev because cp doesn't copy character special files on recursive copies.
The addition of -N, as follows:
cp -RN / /hd/backup
causes the contents of the disk to be backed up, but the /dev directory is skipped, since it doesn't exist on the hard disk device.
- (BlackBerry PlayBook OS extension) See the -u option.
- After copying, attempt to duplicate the modification time and file mode of each input file in the corresponding output file. Also duplicate the ownership of each file if the process is run with the privileges of the superuser (root). If the process doesn't have the appropriate privileges, the duplication fails.
- Recursively copy directories. If a source file is a special file (e.g. FIFO, named special file), cp doesn't create a special file as the destination. Read the section on recursive copying and see the -M and -R options.
- If the source_file is a directory, recursively copy the directory with the files and subdirectories under it, attempting to preserve special files. BlackBerry PlayBook OS doesn't allow block special files and character special files to be created in this manner. Read the section on recursive copying, and see the -M and -r options.
- (BlackBerry PlayBook OS extension) Run safely; copy only if the existing destination file has write permission. If the file doesn't have write permission, skip the file without prompting.
- (BlackBerry PlayBook OS extension) Don't attempt to duplicate file time and mode if the -p option was specified or if the POSIX_STRICT environment variable is set to on.
- (BlackBerry PlayBook OS extension) Copy only if the source is newer than the destination (i.e the source has a more recent file-modified time), or if the destination doesn't already exist.
- (BlackBerry PlayBook OS extension) Be extra verbose. In addition to doing everything -v
does, this option displays a running progress counter (% complete)
and it also displays lines when cp skips a file or a
directory (i.e. you can see what cp isn't doing as well
as what it is doing).
For example, if you select options -R and -n, you'll find that cp -VRn is more useful than cp -vRn, because the -v option in this case might let cp go away and put you back at the prompt without providing you with any feedback.
- (BlackBerry PlayBook OS extension) Be verbose. Display a line of explanatory text every time a file is copied or a directory is created.
- (BlackBerry PlayBook OS extension) Copy only if the destination file doesn't exist.
- (BlackBerry PlayBook OS extension) Copy only if the destination file already exists.
- The pathname of a file to be copied. If you want source_file to name a directory, you must also specify the -R option.
- The pathname to which a single file is copied.
- The pathname of an existing directory that's to contain the output file(s).
There are two syntax forms for cp:
- cp [-f|-i] [-Rrp] [QNX Neutrino extensions] source_file target_file
- The cp utility copies the contents of the source file to the destination file named by target_file. This first syntax form is assumed when the destination file isn't an existing directory and there's only one source file.
- cp [-f|-i] [-Rrp] [QNX Neutrino extensions] source_file... target_dir
- For each source_file, cp copies the contents of
the file to a destination file in the existing directory named by
target_dir. The destination's filename under the target directory
is the same as its basename (final path component), unless it's
a directory (see
cp dir/dir/myfile /existingdir
copies the contents of dir/dir/myfile to the file /existingdir/myfile.
This second form is assumed when the destination file is an existing directory or when you specify more than one source file.
Unless you specify the -R (recursive) option, cp refuses to copy any source_file that is a directory.
What cp does when a destination file already exists depends on the options used. If you don't specify -f or -i, cp prompts you only if you don't have write permission for the existing destination file. When this happens, you're asked if you want to unlink the file first. If you don't, cp goes on to any remaining files. You're prompted only if stdin is a tty. Otherwise, cp prints a diagnostic message to stderr and skips that file.
If you're copying to removable media, such as a floppy or removable disk, and the media becomes full, cp closes and removes the incompletely copied destination file, displays a message, then exits.
When doing a recursive copy of a directory, the destination must be a directory. If you're copying more than one item, the directory must already exist. If you're copying a single directory, cp creates the destination directory (all intermediate directories must already exist unless you specify the -c option).
There are two recursive copying modes available with cp:
- In the historical QNX 4 behavior, specified by the -Mqnx option, cp copies the files and directories underneath the source directory to the destination directory. The source directory itself isn't duplicated within the destination directory.
- The default mode (-Munix) causes cp to duplicate the source directory within the destination directory (unless a single directory is being copied and the destination directory doesn't yet exist, in which case -Munix and -Mqnx modes do the same thing).
In the default -Munix mode, cp -r /bin /mydir/bin duplicates /bin in /mydir/bin, i.e. the destination is /mydir/bin/bin and, for example, the file /bin/sh is copied to /mydir/bin/bin/sh. This is analogous to the way the mv utility treats destinations.
In -Mqnx mode, cp -Mqnx -r /bin /mydir/bin copies the contents of /bin to /mydir/bin (so, for example, /bin/sh is copied to /mydir/bin/sh).
Copy file1, file2, and file3 from the current working directory to the /home/eric directory:
cp file1 file2 file3 /home/eric
Perform a backup of the entire contents of the home directory to floppy disks (assuming that /f0 is a mountpoint for /dev/fd0), in the (default) UNIX recursive-copy mode:
cp -rvp /home /f0
Do the same in QNX recursive-copy mode:
cp -Mqnx -rvp /home /f0/home
Recursively copy the /home/eric directory to the /home/ejohnson directory, assuming /home/ejohnson doesn't yet exist (this works in either -Munix or -Mqnx mode):
cp -rv /home/eric /home/ejohnson
Do the same in -Mqnx mode if the directory ejohnson already exists:
cp -Mqnx -rv /home/eric /home/ejohnson
Do the same in -Munix mode if the directory ejohnson already exists:
cp -Munix -rv /home/eric/. /home/ejohnson
Recursively copy the contents of the current directory into /mydir/ in -Mqnx or -Munix mode:
cp -Rpv . /mydir/
Do the same in -Munix mode only:
cp -Munix -Rpv * /mydir/
Using -Mqnx instead of -Munix in the previous example copies the contents of the directories named on the command line into /mydir/ (i.e. the file ./bin/ls is copied to /mydir/ls, and the directory ./usr/bin is /mydir/bin in the destination).
Recursively copy the /home/eric directory to the /backups/eric directory:
cp -rv /home/eric /backups
Do the same in QNX-style recursive copy mode:
cp -Mqnx -rv /home/eric /backups/eric
- Input files
- If you don't specify the -r option, and you name only one
source file, that source file may be of any filetype.
If you specify the -r option, or there's more than one source file, the input files specified by each source_file operand, including those files contained within named directories, must be either regular files, block special files, or directories.
If you use the -R option, FIFOs are duplicated in the destination directory structure, but contents of the source FIFOs aren't copied. If cp encounters any block special or character special files in the source files, an error occurs, because cp can't create them at the destination.
- Output files
- Each newly created output file is one of the following:
- A directory that contains copies of the files and subdirectories — if any — found in the input directory.
- A regular file that has the same contents as the corresponding input file.
- A FIFO that was created because the corresponding input file was a FIFO and you specified -R. The data from the original FIFO isn't copied into the new FIFO (i.e. the new FIFO is empty).
- A symbolic link that was created because the corresponding input file was a symbolic link and you specified -R. The new symbolic link references the same pathname as the original symbolic link.
Affects whether file modification times are copied, and,
if set on, causes the QNX Neutrino extension options to be disabled.
The setting of the POSIX_STRICT environment variable affects the -p and -t options, as follows:
POSIX_STRICT Option Action Set Neither -p nor -t If the destination doesn't exist, duplicate the mode only. Set -p Duplicate the time and mode; if run by root, also duplicate the user ID and group ID. Set -pt If run by root, duplicate the user ID and group ID. Set -t If destination doesn't exist, duplicate the mode only. Unset Neither -p nor -t Duplicate the time and mode. Unset -p Duplicate the time and mode; if run by root, also duplicate the user ID and group ID. Unset -pt If run by root, duplicate the user ID and group ID. Unset -t If destination doesn't exist, duplicate the mode only.
- All input files were copied successfully.
- An error occurred.
If cp is copying multiple files or doing a recursive copy, but you didn't specify the -R option, cp refuses to copy FIFO and character special files.
If you specify the -R option, and cp attempts but fails to copy a particular file in a specified file hierarchy, it continues to process the remaining files in the hierarchy.