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.
-
-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
-
(QNX extension) 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.
-
-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.
-
-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.
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
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
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.
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.
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. The data from the original FIFO will
not be copied into the new FIFO (i.e. the new FIFO will be empty).
-
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.
See also:
-
mv utility (Move files)
-
ln utility (Create links to files)
-
pax utility (Portable archive interchange)
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.