cp - copy files

cp copies files. Copying means: the file is afterwards physically present in two locations.

cp has four formats. The command copies

• one file to another with a different name (Format 1)

• one or more files to a different directory, with the copy retaining the same basename as the corresponding original (Format 2).

• each file file in the file hierarchy to one of the target paths specified below (formats 3 and 4)

Syntax

Format 1:	cp[ -fip] file copyfile
Format 2:	cp[ -fip] file ... directory
Format 3:	cp -R[ -fip] file ... directory
Format 4:	cp -r[ -fip] file ... directory

Format 1:

cp[ -fip] file copyfile

Copy one file

-f

If it is impossible to obtain a file descriptor for copyfile (step 3.a.ii.), then an attempt is made to call unlink() for copyfile. Processing is continued.

-i

(interactive)

If the named copyfile already exists, cp will ask you to confirm whether this file may be overwritten. A y answer means that the copy operation should proceed. Any other answer prevents cp from overwriting copyfile.
If the standard input is not a terminal, this option is ignored and no copying is performed.

-p

The following properties of all files are duplicated in the corresponding copyfile:

1. The last time the data was changed and the time of the last access. If this procedure should fail for any reason then cp writes a message to the standard error output.

2. The user ID and group ID. If this procedure should fail for any reason then cp writes a message to the standard error output.

3. The bits for permissions as well as the bits S_ISUID and S_ISGID. If this procedure should fail for any reason then cp writes a message to the standard error output.

If it is impossible to duplicate user ID or group ID then the bits for S_ISUID and S_ISGID are duplicated.

The sequence for the duplication of the properties listed above is not defined. copyfile is not deleted if these properties cannot be retained.

file

Name of the original file.

copyfile

Name of the copy file.
If copyfile does not yet exist, a new file is created.

Unless the -p option is used, the copy will have the same mode as the original file, and the user and group ID of the copy will be those of the user who called cp, but the time of last modification of the copy will be set to the time the copy was made.

Caution!
If a file named copyfile already exists and the -i option is not used, the existing file will be overwritten without confirmation, but its mode, owner, and group will be preserved.

If copyfile is a link to a file, all links will be retained. The contents of copyfile will be overwritten with the contents of file.

Format 2:

cp[ -fip] file ... directory

Copy files to another directory

-fip

see Format 1

file

Name of the original file. You can give a list of names and thus copy several files at once. Each of the copies is assigned the same basic file name (basename) as the corresponding original.

Caution!
If there is a file in directory with the same basename as any original, and the -i option has not been set, the existing file will be overwritten without confirmation.

directory

Name of the directory in which the copies are to be placed. This must not be the directory in which the original files are located.

Unless the -p option is set, the copies will have the same modes as the originals, and the user and group ID of the copies will be those of the user who called cp, but the time of last modification of each copy will be set to the time the copy was made.

Format 3:

cp -R[ -fip] file ... directory

-fip

see Format 1

-R

copies data hierarchies.

If the option -R is set then the following steps are performed:

1. copyfile is created with the same file type as file.

2. The permissions for copyfile are set to match those of file. Modification is subsequently performed via the user’s file creation mask provided that the option -p has not been specified.

If this procedure should fail for any reason then cp writes a message to the standard error output. Processing of file is halted. However, other files may be processed as appropriate.

file, directory

see Format 2

Format 4:

cp -r[ -fip] file ... directory

-fip

see Format 1

-r

Copies file hierarchies. The way in which special files are handled is implementation-dependent.

If option -r is set then the way in which special files are handled is implementation-dependent.

file, directory

see Format 2

Procedure

If directory already exists and is actually a directory, then the name of the target path for the individual files in the file hierarchy consists of a string formed by directory, a slash and the relative path name of the file corresponding to the directory which contains file.

If directory does not yet exist and two operands are specified, then the name of the corresponding target path for file is the directory directory. The name of the corresponding target path for all other files in the file hierarchy consists of directory, a slash and the relative path name of the file corresponding to file.

An error occurs if directory does not exist and more than two operands are specified. An error also occurs if directory exists and is a file type as defined in the XSH specification but is not a directory.

In the following description file is the file to be copied irrespective of whether it is specified via an operand or whether it is specified in a file operand as a file in a file hierarchy. The term copyfile designates the file which is specified by the target path.

The following steps are performed for each file:

1. If file and copyfile designate the same file, cp writes a message to the standard error output where required. Processing of file is halted. However, other files may be processed as appropriate.

2. If file is a directory then the following steps are performed:

   1. If neither the option -R nor the option -r is specified, cp writes a message to the standard error output. Processing of file is halted. However, other files may be processed as appropriate.

   2. If file is not specified as an operand, and if file is either "." or "..", then processing of file is halted. However, other files may be processed as appropriate.

   3. If copyfile/directory is present and is a file type which is not specified in the XSH specification then the system reaction will depend on the specific implementation.

   4. If copyfile/directory is present and is not a directory, then cp writes a message to the standard error output. Processing of file as well as of any other files which are subordinate to file in the file hierarchy is halted. However, other files may be processed as appropriate.

   5. If the directory copyfile/directory does not exist then it is created and assigned the access permissions which apply to file. Modification is subsequently performed via the user’s file creation mask, if the option -p has not been set, together with a bitwise OR operation with S_IRWXU. If copyfile cannot be created, cp writes a message to the standard error output. Processing of file is halted. However, other files may be processed as appropriate. It is not possible to predict whether or not cp will attempt to copy files to the file hierarchy corresponding to file.

   6. The files in the directory file are copied to the directory copyfile/directory. Steps 1 to 3 are followed for the files.

   7. If copyfile/directory have already been created then the access permissions are modified (if necessary) so that they are compatible with the access permissions for file. Modification is subsequently performed via the user’s file creation mask provided that the option -p has not been specified.

   8. cp does not process file any further. However, other files may be processed as appropriate.

3. If file is a regular file then the following steps are performed:

   1. If copyfile is present then the following steps are performed:

      1. If the option -i has been set then cp writes a prompt to the default standard output and reads a line from the standard input. If the input is not a confirmation then cp discontinues processing of file. However, other files may be processed as appropriate.

      2. A file descriptor for copyfile is obtained by performing the steps specified in the function open() in accordance with the XSH specification. copyfile is used as the path argument and the bitwise, inclusive OR operation of O_WRONLY and O_TRUNC is used as the oflag argument.
      3. If the attempt to obtain a file descriptor fails and if the option -f has been set then cp attempts to remove the file by performing the steps specified in the function unlink() in accordance with the XSH specification. copyfile is used as the path argument. If this attempt is successful then cp continues processing with step 3b.
   2. If copyfile is not present then file descriptor is obtained by performing the steps specified in the function open() in accordance with the XSH specification. copyfile is used as the path argument and the bitwise, inclusive OR operation of O_WRONLY and O_TRUNC is used as the oflag argument. The permissions for file are taken from the mode argument.
   3. If the attempt to obtain a file descriptor fails then cp writes a message to the standard error output. Processing of file is halted. However, other files may be processed as appropriate.
   4. The contents of file are written to the file descriptor. If write errors occur then cp writes a message to the standard error output and continues processing with step 3e.
   5. The file descriptor is terminated.
   6. cp halts processing of file. If a write error has occurred at step 3d then it is impossible to predict whether or not cp will continue to process further files. If no write error occurred in step 3d then cp will continue to process files.

Error

cp: Cannot access file

The named file does not exist.

cp: Cannot open file : Permission denied
You have no read permission for file.

cp: cannot create file
You do not have write permission for the directory in which file is to be created, or the named directory does not exist.

cp: dir directory
dir is a directory and cannot be copied (Format 1), or you have not set the -r option (Format 4).

Locale

The following environment variables affect the execution of cp:

LANG

Provide a default value for the internationalization variables that are unset or null. If LANG is unset of null, the corresponding value from the implementation-specific default locale will be used. If any of the internationalization variables contains an invalid setting, the utility will behave as if none of the variables had been defined.

LC_ALL

If set to a non-empty string value, override the values of all the other internationalization variables.

LC_COLLATE

Determines the internationalized environment for the behavior of ranges, equivalence classes and multicharacter collating elements used in the extended regular expressions defined for the affirmative response.

LC_CTYPE

Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single- as opposed to multi-byte characters in arguments). LC_CTYPE governs character classes, character conversion (shifting) and the behavior of character classes in regular expressions.

LC_MESSAGES

Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.

NLSPATH

Determine the location of message catalogs for the processing of LC_MESSAGES.

Example 1

The file techlit is to be copied before it is changed. The copy is to be called tl and to be located in the same directory as techlit.

$ cp techlit tl

Example 2

All files from the current directory with names beginning with fil are to be copied into the directory /home/do/save, and their times of last modification are to be duplicated.

$ cp -p fil* /home/do/save

$ ls -l /home/do/save

total 4

-rw------  1  DOBER  gr1        37 Nov 11 11:11  file1

-rw------  1  DOBER  gr1        97 Apr 01 13:24  file2

-rw------  1  DOBER  gr1       116 Dec 31 12:13  filei3
-rw------  1  DOBER  gr1       381 Feb 16 08:08  file4

See also

chmod, ln, mv, rm