`cp`

Copy files (POSIX)

Syntax:

cp [-f|-i] [-Rrp] [QNX Neutrino extensions] 
   source_file target_file

cp [-f|-i] [-Rrp] [QNX Neutrino extensions] 
   source_file... target_dir

(QNX Neutrino 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.

-f

(QNX Neutrino 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.

-i

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 truncated.

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.

-L

(QNX Neutrino 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

(QNX Neutrino 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.

-N

(QNX Neutrino 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.

-n

(QNX Neutrino extension) See the -u option.

-p

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.

-r

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.

-R

If the source_file is a directory, recursively copy the directory with the files and subdirectories under it, attempting to preserve special files. QNX Neutrino 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.

-s

(QNX Neutrino 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.

-t

(QNX Neutrino 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.

-u

(QNX Neutrino 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.

-V

(QNX Neutrino 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.

-v

(QNX Neutrino extension) Be verbose. Display a line of explanatory text every time a file is copied or a directory is created.

-X

(QNX Neutrino extension) Copy only if the destination file doesn't exist.

-x

(QNX Neutrino extension) Copy only if the destination file already exists.

source_file

The pathname of a file to be copied. If you want source_file to name a directory, you must also specify the -R option.

target_file

The pathname to which a single file is copied.

target_dir

The pathname of an existing directory that's to contain the output file(s).

Description:

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 “Recursive Copying”). For example:

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.

General

Unless you specify the -R (recursive) option, cp refuses to copy any source_file that is a directory.

For duplicating lists of files, see the pax -rw utility, which is another POSIX utility for duplicating files. You can select sets of files that match complex criteria by using find, and then pipe them to pax.

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.

Recursive copying

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).

The default mode under QNX Neutrino is different from that under QNX 4.

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).

Examples:

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

Files:

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.

If an existing destination names some other type of file, cp opens it for writing and attempts to copy the contents of the corresponding input file to it.

Environment variables:

POSIX_STRICT

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.

Exit status:

0: All input files were copied successfully.
>0: An error occurred.

Caveats:

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.