`cp`

Copy files (POSIX)

Syntax:

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

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

Options:

-a date/time

(QNX extension -- Deprecated. Use find | pax -rw.) Copy only those files that were last modified after the specified date/time, where date/time is:

[UTC] dd/mm/yy [HH:MM:SS]

specified in 24 hour time (the time portion is optional). To use Coordinated Universal Time, specify UTC; to use the local time, don't include UTC.

If you're running cp from the shell, and you want to specify both the date and the time, you must use the quotation marks. If you want to specify only the date (dd/mm/yy), quotation marks aren't needed.

-A

(QNX extension) Preserve source file access times, if possible. Cannot be used with -O. The access and modification times of source files and directories will be memorized then restored when cp has finished reading them.

-b date/time

(QNX extension -- Deprecated. Use find | pax -rw.) Copy only those files that were last modified before the specified date/time (see the -a date/time option).

-B

(QNX extension -- Deprecated.) Use a small copy buffer (2K) instead of grabbing a large buffer (16K). If you don't specify this option and there isn't enough free memory to use a 16K buffer, cp dynamically reduces its buffer by 1K increments until there's enough memory available (down to a minimum of 1K).

When even using -B fails, one can resort to using the cat utility to copy data.

-c

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

-d

(QNX extension -- Deprecated.) Distribute source files to multiple destinations. Ordinarily, you can specify only one destination file or directory to cp. But when you specify -d, and only when you specify -d, cp treats the word "to" as a special marker separating source files and source directories from destinations. For example:

cp -d myprog to //61/hd/bin //73/hd/bin //15/hd/bin

performs the equivalent of:

cp myprog //61/hd/bin
cp myprog //73/hd/bin
cp myprog //15/hd/bin

When you don't specify -d, the word "to" is treated like any other filename.

-D

(QNX extension) This option, when used in conjunction with -R, controls whether cp will or will not descend past device boundaries while traversing a directory tree. When the POSIX_STRICT environment variable is set, cp will ignore device boundaries (i.e. will copy everything). When POSIX_STRICT isn't set, cp will by default not descend past device boundaries.

Specifying -D will cause cp to descend past device boundaries. For example:

cp -R //1/ //2/backup

will, when //1/ is a local hard disk, cause the contents of the disk to be backed up, but the //1/dev directory will be skipped, since it does not exist on the hard disk device. The addition of -D, as follows:

cp -RD //1/ //2/backup

would cause cp to also attempt to back up the contents of the //1/dev directory. Note that in this particular example only the disk devices (block special files) would actually have their data backed up to files in //2/backup/dev because cp won't copy character special files on recursive copies.

-f

Force the unlinking of the destination file prior to copying. This option prevents interactive prompting (unless -i is also specified) but does not disable diagnostic messages. Note that this behavior follows an early POSIX draft and does not comply with POSIX 1003.2-1992. The standard specifies that the file will be unlinked only if a file descriptor for the destination file cannot be obtained (i.e. cp cannot open the destination file for write).

-g group[,group]

(QNX extension -- Deprecated. Use find | pax -rw.) Copy only files belonging to these groups (where group is a groupid or a group name).

-i

Run interactively; always prompt the invoking user for confirmation when the destination path exists, regardless of whether the user has 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 will be unlinked first. Otherwise, the destination is simply overwritten and truncated.

The combination of -i and -f works as if only -i were specified, 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 only -i is specified, the destination is unlinked only when you do not have write permission for the destination file. See note about POSIX compatibility of the current -f behavior.

-l n

("el") (QNX extension -- Deprecated. Use find | pax -rw.) If source_file is a directory, and if option -R is specified, copy only n levels of the directory tree. If you specify -l 0, -R is defeated; only files at the current level (files named directly on the command line) are copied.

-L

(QNX extension) Attempt to preserve hard links. When cp encounters a file that has a link count >1, it remembers that file's device ID and serial number (inode). If during the cp another file with a link count >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 [!]mode[,[!]mode]...

(QNX extension -- Deprecated. Use find | pax -rw.) Copy only files with these modes (where mode is expressed as an octal number or symbolically similar to the format used in the chmod utility). If you specify a mode with a preceding ! the cp utility will not copy any file that has that mode. The symbolic mode is of the form

[[agou]=[rswx]][,symbolic_mode]

as used by the chmod utility.

For example, an option of -m ug=rx copies only files for which user and group have read and execute permission.

-M qnx|unix

(QNX extension) Recursive copies to be done in UNIX or old-style QNX mode. (Default: qnx). 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 is only one directory being copied and the destination names a directory that doesn't exist, cp will create the destination directory and then copy the contents of the source directory into the destination directory. At some point in the future a version of QNX will be released which makes unix the default for this option.

-n

(QNX extension) Copy only if the source is newer than the destination (has a more recent file modified time), or if the destination doesn't already exist.

-O

(QNX extension) Optimize the copy operation; run the copy on the CPU of the destination node or on the node that will most likely speed up the operation. The cp utility will not spawn itself on more than one other node, so when multiple destinations (on different nodes) are specified, it tries to make a "best guess" decision as to which node to run on.

-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 will fail.

-P [!]pat[,[!]pat]...

(QNX extension; Deprecated. Use find | pax -rw) Copy only files matching these patterns (where pat is a filename matching pattern as per the fnmatch() function; for details, see the section on "Pattern-matching special characters"). If you specify a pattern with a preceding !, and if a file you've specified matches that pattern, cp doesn't copy the file.

-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 look at 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 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 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 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 owner[,owner]...

(QNX extension -- Deprecated. Use find | pax -rw.) Copy only files belonging to these owners, where owner is a userid or a username.

-v

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

-V

(QNX 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 since option -v in this case might let cp go away and put you back at the prompt without providing you with any feedback.

-x

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

-X

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

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 is to contain the output file(s).

The QNX extended options listed above that are deprecated may not be present in future versions of QNX.

Description:

First syntax form:

cp [-f|-i] [-Rrp] [QNX 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.

Second syntax form:

cp [-f|-i] [-Rrp] [QNX 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 will be the same as its basename (final path component), unless it is 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 more than one source file is specified.

General

By default cp duplicates file contents and also duplicates the file times of the original file. This is not standard UNIX behavior for cp. To disable this, either disable the duplication of file times by using the -t or set POSIX_STRICT - see Environment variables for details.

Unless the -R (recursive) option is specified, 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. Sets of files which match complex criteria may be selected with the find utility and piped into pax. The abilities built into cp to accomplish the same thing (e.g. pattern matching) are deprecated and will be removed in a future release.

What cp does when a destination file already exists depends on the options used. When neither -f nor -i is specified, you'll be prompted only if you don't have write permission for the existing destination file. When this happens, you'll be asked if you want to unlink the file first. If you don't, cp goes on to any remaining files. You'll be prompted only if stdin is a tty. Otherwise, cp will print a diagnostic message to stderr and skip that file.

If you're copying to removable media, such as a floppy or removable disk, and the media becomes full, cp performs the following steps:

Closes and removes the incompletely copied destination file.
Prompts you to insert a new diskette. If you type y (yes), cp will create the necessary directory tree on the new disk and resume copying, starting with the file that was being copied when space ran out. If you type n, cp will stop copying and exit.

Recursive copying

When doing a recursive copy of a directory, the destination must be a directory. If more than one item is being copied, the directory must already exist. If a single directory is being copied, the cp command will create the destination directory (all intermediate directories must already exist unless the -c option is specified).

There are two recursive copying modes available with cp. The default is the historical QNX behavior which is to copy the files and directories underneath the source directory to the destination directory. The source directory itself will not be duplicated within the destination directory.

The other mode, specified by the -Munix option, causes cp to duplicate the source directory within the destination directory (unless a single directory is being copied and the destination directory does not yet exist, in which case -Munix and -Mqnx modes do the same thing).

In -Mqnx mode, cp -r /bin //2/bin will copy the contents of /bin to //2/bin (so, for example, /bin/sh will be copied to //2/bin/sh etc.).

In -Munix mode, cp -Munix -r /bin //2/bin would duplicate /bin in //2/bin, i.e. the destination would be //2/bin/bin and, for example, the file /bin/sh would be copied to //2/bin/bin/sh. This is analogous to the way the mv utility treats destinations.

The default behavior is currently -Mqnx, but this will change in a future major revision of QNX.

Pattern-matching special characters

A pattern-matching special character that is quoted is a pattern that matches the special character itself. When not quoted, such special characters have special meaning in the specification of patterns. The pattern-matching special characters and the contexts in which they have their special meaning are as follows:

?

matches any printable or non-printable character except newline

*

matches any string, including the null string

[bracket_expr]

a pattern that matches a single character, except that:

the exclamation mark (!) replaces the circumflex (^) in its role as a nonmatching list in the regular expression notation
the backslash is used as an escape character within bracket expressions

Note that the characters ?, *, and [ are not special when used inside a bracket expression.

The concatenation of patterns matching a single character is a valid pattern that matches the concatenation of the characters matched by each of the concatenated patterns. For example, the pattern a[bc] matches the strings ab and ac.

The concatenation of one or more patterns matching a single character with one or more asterisks (*) is a valid pattern. In such patterns, each asterisk matches a string of zero or more characters, up to the first character that matches the character following the asterisk in the pattern. For example, the pattern a*d matches the strings ad, abd, and abcd, but not the string abc.

When an asterisk is the first or last character in a pattern, it matches zero or more characters that precede or follow the characters matched by the remainder of the pattern. For example, the pattern a*d* matches the strings ad, abcd, abcdef, aaaad, and adddd. The pattern *a*d matches the strings ad, abcd, efabcd, aaaad, and adddd.

Examples:

Copy file1, file2, and file3 from the current working directory to the /home/eric directory:

    cp file1 file2 file3 /home/eric

Do a raw block copy from the floppy drive on node 4 to the floppy drive on node 6:

    cp //4/dev/fd0 //6/dev/fd0

Perform a backup of the entire contents of the home directory to floppy disks (assuming that /f0 is a mount point for /dev/f0), in the (default) QNX recursive-copy mode:

    cp -rvp /home /f0/home

Do the same in UNIX recursive-copy mode:

    cp -Munix -rvp /home /f0

Recursively copy the /home/eric directory to the /home/ejohnson directory (assuming /home/ejohnson does not yet exist) (will work 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 //2/ in -Mqnx or -Munix modes:

    cp -Rpv . //2/

Do the same in -Munix mode only:

    cp -Munix -Rpv * //2/

In the previous example, doing cp -Mqnx -Rpv * //2/ would have resulted in copying the contents of the directories named on the command line into //2/ (i.e. the file ./bin/ls would have been copied to //2/ls, and the directory ./usr/bin would have been //2/bin in the destination).

Recursively copy the /home/eric directory to the /backups/eric directory:

    cp -rv /home/eric /backups/eric

Do the same in UNIX-style recursive copy mode:

    cp -Munix -rv /home/eric /backups

Files:

Input files

If you don't specify the -r option, and only one source file is named, 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 will be duplicated in the destination directory structure, but contents of the source FIFOs won't be copied. Any block special or character special files encountered in the source files will result in an error, since cp cannot create these 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 -R was specified. Data will not be copied from the original FIFO to the new FIFO.
A symbolic link that was created because the corresponding input file was a symbolic link and -R was specified. The new symbolic link will reference 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 to on, causes the QNX 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 destination doesn't exist, duplicate mode only
set	`-p`	duplicate time, mode; if run by `root`, also duplicate userid, groupid
set	`-pt`	if run by `root`, duplicate userid, groupid
set	`-t`	if destination doesn't exist, duplicate mode only
unset	neither `-p` nor `-t`	duplicate time and mode
unset	`-p`	duplicate time, mode; if run by `root`, also duplicate userid, groupid
unset	`-pt`	if run by `root`, duplicate userid, groupid
unset	`-t`	if destination doesn't exist, duplicate 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 the -R option is not specified, cp will refuse 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.