Movatterモバイル変換

NAME

cp — copy files

SYNOPSIS

cp[-Pfip]source_file target_file

cp[-Pfip]source_file...target

cp -R[-H|-L|-P] [-fip]source_file...target


DESCRIPTION

The first synopsis form is denoted by two operands, neither of which are existing files of type directory. Thecp utilityshall copy the contents ofsource_file (or, ifsource_file is a file of type symbolic link, the contents of the filereferenced bysource_file) to the destination path named bytarget_file.

The second synopsis form is denoted by two or more operands where the-R option is not specified and the first synopsisform is not applicable. It shall be an error if anysource_file is a file of type directory, iftarget does notexist, or iftarget does not name a directory. Thecp utility shall copy the contents of eachsource_file (or,ifsource_file is a file of type symbolic link, the contents of the file referenced bysource_file) to thedestination path named by the concatenation oftarget, a single <slash> character iftarget did not end in a<slash>, and the last component ofsource_file.

The third synopsis form is denoted by two or more operands where the-R option is specified. Thecp utility shallcopy each file in the file hierarchy rooted in eachsource_file to a destination path named as follows:

• Iftarget exists and names an existing directory, the name of the corresponding destination path for each file in thefile hierarchy shall be the concatenation oftarget, a single <slash> character iftarget did not end in a<slash>, and the pathname of the file relative to the directory containingsource_file.

• Iftarget does not exist and two operands are specified, the name of the corresponding destination path forsource_file shall betarget; the name of the corresponding destination path for all other files in the file hierarchyshall be the concatenation oftarget, a <slash> character, and the pathname of the file relative tosource_file.

It shall be an error iftarget does not exist and more than two operands are specified, or iftarget exists anddoes not name a directory.

In the following description, the termdest_file refers to the file named by the destination path. The termsource_file refers to the file that is being copied, whether specified as an operand or a file in a file hierarchy rooted inasource_file operand. Ifsource_file is a file of type symbolic link:

• If the-R option was not specified,cp shall take actions based on the type and contents of the file referenced bythe symbolic link, and not by the symbolic link itself, unless the-P option was specified.

• If the-R option was specified:

  • If none of the options-H,-L, nor-P were specified, it is unspecified which of-H,-L, or-P will be used as a default.

  • If the-H option was specified,cp shall take actions based on the type and contents of the file referenced by anysymbolic link specified as asource_file operand.

  • If the-L option was specified,cp shall take actions based on the type and contents of the file referenced by anysymbolic link specified as asource_file operand or any symbolic links encountered during traversal of a file hierarchy.

  • If the-P option was specified,cp shall copy any symbolic link specified as asource_file operand and anysymbolic links encountered during traversal of a file hierarchy, and shall not follow any symbolic links.

For eachsource_file, the following steps shall be taken:

1. Ifsource_file references the same file asdest_file,cp may write a diagnostic message to standard error;it shall do nothing more withsource_file and shall go on to any remaining files.

2. Ifsource_file is of type directory, the following steps shall be taken:

   1. If the-R option was not specified,cp shall write a diagnostic message to standard error, do nothing more withsource_file, and go on to any remaining files.

   2. Ifsource_file was not specified as an operand andsource_file is dot or dot-dot,cp shall do nothing morewithsource_file and go on to any remaining files.

   3. Ifdest_file exists and it is a file type not specified by the System Interfaces volume of POSIX.1-2024, the behavior isimplementation-defined.

   4. Ifdest_file exists and it is not of type directory,cp shall write a diagnostic message to standard error, donothing more withsource_file or any files belowsource_file in the file hierarchy, and go on to any remainingfiles.

   5. If the directorydest_file does not exist, it shall be created with file permission bits set to the same value as thoseofsource_file, modified by the file creation mask of the user if the-p option was not specified, and thenbitwise-inclusively OR'ed with S_IRWXU. Ifdest_file cannot be created,cp shall write a diagnostic message tostandard error, do nothing more withsource_file, and go on to any remaining files. It is unspecified ifcp attemptsto copy files in the file hierarchy rooted insource_file.

   6. The files in the directorysource_file shall be copied to the directorydest_file, taking the four steps (1 to 4)listed here with the files assource_files.

   7. Ifdest_file was created, its file permission bits shall be changed (if necessary) to be the same as those ofsource_file, modified by the file creation mask of the user if the-p option was not specified.

   8. Thecp utility shall do nothing more withsource_file and go on to any remaining files.

3. Ifsource_file is of type regular file, the following steps shall be taken:

   1. The behavior is unspecified ifdest_file exists and was written by a previous step. Otherwise, ifdest_fileexists, the following steps shall be taken:

      1. If the-i option is in effect, thecp utility shall write a prompt to the standard error and read a line from thestandard input. If the response is not affirmative,cp shall do nothing more withsource_file and go on to anyremaining files.

      2. A file descriptor fordest_file shall be obtained by performing actions equivalent to theopen() function defined in the System Interfaces volume of POSIX.1-2024 called usingdest_file as thepath argument, and the bitwise-inclusive OR of O_WRONLY and O_TRUNC as theoflagargument.

      3. If the attempt to obtain a file descriptor fails and the-f option is in effect,cp shall attempt to remove thefile by performing actions equivalent to theunlink() function defined in the SystemInterfaces volume of POSIX.1-2024 called usingdest_file as thepath argument. If this attempt succeeds,cpshall continue with step 3b.

   2. Ifdest_file does not exist, a file descriptor shall be obtained by performing actions equivalent to theopen() function defined in the System Interfaces volume of POSIX.1-2024 called usingdest_file as thepath argument, and the bitwise-inclusive OR of O_WRONLY and O_CREAT as theoflag argument.The file permission bits ofsource_file shall be themode argument.

   3. If the attempt to obtain a file descriptor fails,cp shall write a diagnostic message to standard error, do nothing morewithsource_file, and go on to any remaining files.

   4. The contents ofsource_file shall be written to the file descriptor. Any write errors shall causecp to write adiagnostic message to standard error and continue to step 3e.

   5. The file descriptor shall be closed.

   6. Thecp utility shall do nothing more withsource_file. If a write error occurred in step 3d, it is unspecified ifcp continues with any remaining files. If no write error occurred in step 3d,cp shall go on to any remainingfiles.

4. Otherwise, the-R option was specified, and the following steps shall be taken:

   1. Thedest_file shall be created with the same file type assource_file.

   2. Ifsource_file is a file of type FIFO, the file permission bits shall be the same as those ofsource_file,modified by the file creation mask of the user if the-p option was not specified. Otherwise, the permissions, owner ID, andgroup ID ofdest_file are implementation-defined.

      If this creation fails for any reason,cp shall write a diagnostic message to standard error, do nothing more withsource_file, and go on to any remaining files.

   3. Ifsource_file is a file of type symbolic link, and the options require the symbolic link itself to be acted upon, thepathname contained indest_file shall be the same as the pathname contained insource_file.

      If this fails for any reason,cp shall write a diagnostic message to standard error, do nothing more withsource_file, and go on to any remaining files.

If the implementation provides additional or alternate access control mechanisms (see XBD4.7 File Access Permissions), their effect on copies of files isimplementation-defined.

OPTIONS

Thecp utility shall conform to XBD12.2 Utility SyntaxGuidelines.

The following options shall be supported:

-f

If a file descriptor for a destination file cannot be obtained, as described in step 3.a.ii., attempt to unlink the destinationfile and proceed.

-H

Take actions based on the type and contents of the file referenced by any symbolic link specified as asource_fileoperand.

-i

Write a prompt to standard error before copying to any existing non-directory destination file. If the response from thestandard input is affirmative, the copy shall be attempted; otherwise, it shall not.

-L

Take actions based on the type and contents of the file referenced by any symbolic link specified as asource_fileoperand or any symbolic links encountered during traversal of a file hierarchy.

-P

Take actions on any symbolic link specified as asource_file operand or any symbolic link encountered during traversalof a file hierarchy.

-p

Duplicate the following characteristics of each source file in the corresponding destination file:

1. The time of last data modification and time of last access. If this duplication fails for any reason,cp shall write adiagnostic message to standard error.

2. The user ID and group ID. If this duplication fails for any reason, it is unspecified whethercp writes a diagnosticmessage to standard error.

3. The file permission bits and the S_ISUID and S_ISGID bits. Other, implementation-defined, bits may be duplicated as well. Ifthis duplication fails for any reason,cp shall write a diagnostic message to standard error.

If the user ID or the group ID cannot be duplicated, the file permission bits S_ISUID and S_ISGID shall be cleared. If thesebits are present in the source file but are not duplicated in the destination file, it is unspecified whethercp writes adiagnostic message to standard error.

The order in which the preceding characteristics are duplicated is unspecified. Thedest_file shall not be deleted ifthese characteristics cannot be preserved.

-R

Copy file hierarchies.

Specifying more than one of the mutually-exclusive options-H,-L, and-P shall not be considered an error.The last option specified shall determine the behavior of the utility.

OPERANDS

The following operands shall be supported:

source_file

A pathname of a file to be copied. If asource_file operand is'-', it shall refer to a file named-;implementations shall not treat it as meaning standard input.

target_file

A pathname of an existing or nonexistent file, used for the output when a single file is copied. If atarget_fileoperand is'-', it shall refer to a file named-; implementations shall not treat it as meaning standardoutput.

target

A pathname of a directory to contain the copied files.

STDIN

The standard input shall be used to read an input line in response to each prompt specified in the STDERR section. Otherwise,the standard input shall not be used.

INPUT FILES

The input files specified as operands may be of any file type.

ENVIRONMENT VARIABLES

The following environment variables shall affect the execution ofcp:

LANG

Provide a default value for the internationalization variables that are unset or null. (See XBD8.2 Internationalization Variables for the precedence of internationalizationvariables used to determine the values of locale categories.)

LC_ALL

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

LC_COLLATE

Determine the locale for the behavior of ranges, equivalence classes, and multi-character collating elements used in the extendedregular expression defined for theyesexpr locale keyword in theLC_MESSAGES category.

LC_CTYPE

Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte asopposed to multi-byte characters in arguments and input files) and the behavior of character classes used in the extended regularexpression defined for theyesexpr locale keyword in theLC_MESSAGES category.

LC_MESSAGES

Determine the locale used to process affirmative responses, and the locale used to affect the format and contents of diagnosticmessages and prompts written to standard error.

NLSPATH

^[XSI]Determine the location of messages objects and message catalogs.

ASYNCHRONOUS EVENTS

Default.

STDOUT

Not used.

STDERR

A prompt shall be written to standard error under the conditions specified in the DESCRIPTION section. The prompt shall containthe destination pathname, but its format is otherwise unspecified. Otherwise, the standard error shall be used only for diagnosticmessages.

OUTPUT FILES

The output files may be of any type.

EXTENDED DESCRIPTION

None.

EXIT STATUS

The following exit values shall be returned:

 0

All requested files (excluding files where a non-affirmative response was given to a request for confirmation) weresuccessfully copied.

>0

An error occurred.

CONSEQUENCES OF ERRORS

Ifcp is prematurely terminated by a signal or error, files or file hierarchies may be only partially copied and filesand directories may have incorrect permissions or access and modification times.

APPLICATION USAGE

The set-user-ID and set-group-ID bits are explicitly cleared when files are created. This is to prevent users from creatingprograms that are set-user-ID or set-group-ID to them when copying files or to make set-user-ID or set-group-ID files accessible tonew groups of users. For example, if a file is set-user-ID and the copy has a different group ID than the source, a new group ofusers has execute permission to a set-user-ID program than did previously. In particular, this is a problem for superusers copyingusers' trees.

EXAMPLES

None.

RATIONALE

The-i option exists on BSD systems, giving applications and users a way to avoid accidentally removing files whencopying. Although the 4.3 BSD version does not prompt if the standard input is not a terminal, the standard developers decided thatuse of-i is a request for interaction, so when the destination path exists, the utility takes instructions from whateverresponds on standard input.

The exact format of the interactive prompts is unspecified. Only the general nature of the contents of prompts are specifiedbecause implementations may desire more descriptive prompts than those used on historical implementations. Therefore, anapplication using the-i option relies on the system to provide the most suitable dialog directly with the user, based onthe behavior specified.

The-p option is historical practice on BSD systems, duplicating the time of last data modification and time of lastaccess. This volume of POSIX.1-2024 extends it to preserve the user and group IDs, as well as the file permissions. Thisrequirement has obvious problems in that the directories are almost certainly modified after being copied. This volume ofPOSIX.1-2024 requires that the modification times be preserved. The statement that the order in which the characteristics areduplicated is unspecified is to permit implementations to provide the maximum amount of security for the user. Implementationsshould take into account the obvious security issues involved in setting the owner, group, and mode in the wrong order or creatingfiles with an owner, group, or mode different from the final value.

It is unspecified whethercp writes diagnostic messages when the user and group IDs cannot be set due to the widespreadpractice of users using-p to duplicate some portion of the file characteristics, indifferent to the duplication of others.Historic implementations only write diagnostic messages on errors other than [EPERM].

Earlier versions of this standard included support for the-r option to copy file hierarchies. The-r option ishistorical practice on BSD and BSD-derived systems. This option is no longer specified by POSIX.1-2024 but may be present in someimplementations. The-R option was added as a close synonym to the-r option, selected for consistency with all otheroptions in this volume of POSIX.1-2024 that do recursive directory descent.

The difference between-R and the removed-r option is in the treatment bycp of file types other thanregular and directory. It was implementation-defined how the- option treated special files to allow both historicalimplementations and those that chose to support-r with the same abilities as-R defined by this volume ofPOSIX.1-2024. The original-r flag, for historic reasons, did not handle special files any differently from regular files,but always read the file and copied its contents. This had obvious problems in the presence of special file types; for example,character devices, FIFOs, and sockets.

When a failure occurs during the copying of a file hierarchy,cp is required to attempt to copy files that are on thesame level in the hierarchy or above the file where the failure occurred. It is unspecified ifcp shall attempt to copyfiles below the file where the failure occurred (which cannot succeed in any case).

Permissions, owners, and groups of created special file types have been deliberately left as implementation-defined. This is toallow systems to satisfy special requirements (for example, allowing users to create character special devices, but requiring themto be owned by a certain group). In general, it is strongly suggested that the permissions, owner, and group be the same as if theuser had run the historicalmknod,ln, or other utility to create the file. It isalso probable that additional privileges are required to create block, character, or other implementation-defined special filetypes.

Additionally, the-p option explicitly requires that all set-user-ID and set-group-ID permissions be discarded if any ofthe owner or group IDs cannot be set. This is to keep users from unintentionally giving away special privilege when copyingprograms.

When creating regular files, historical versions ofcp use the mode of the source file as modified by the file modecreation mask. Other choices would have been to use the mode of the source file unmodified by the creation mask or to use the samemode as would be given to a new file created by the user (plus the execution bits of the source file) and then modify it by thefile mode creation mask. In the absence of any strong reason to change historic practice, it was in large part retained.

When creating directories, historical versions ofcp use the mode of the source directory, plus read, write, and searchbits for the owner, as modified by the file mode creation mask. This is done so thatcp can copy trees where the user hasread permission, but the owner does not. A side-effect is that if the file creation mask denies the owner permissions,cpfails. Also, once the copy is done, historical versions ofcp set the permissions on the created directory to be the same asthe source directory, unmodified by the file creation mask.

This behavior has been modified so thatcp is always able to create the contents of the directory, regardless of the filecreation mask. After the copy is done, the permissions are set to be the same as the source directory, as modified by the filecreation mask. This latter change from historical behavior is to prevent users from accidentally creating directories withpermissions beyond those they would normally set and for consistency with the behavior ofcp in creating files.

It is not a requirement thatcp detect attempts to copy a file to itself; however, implementations are stronglyencouraged to do so. Historical implementations have detected the attempt in most cases.

There are two methods of copying subtrees in this volume of POSIX.1-2024. The other method is described as part of thepax utility (seepax). Both methods are historicalpractice. Thecp utility provides a simpler, more intuitive interface, whilepaxoffers a finer granularity of control. Each provides additional functionality to the other; in particular,pax maintains the hard-link structure of the hierarchy, whilecp does not. It is theintention of the standard developers that the results be similar (using appropriate option combinations in both utilities). Theresults are not required to be identical; there seemed insufficient gain to applications to balance the difficulty ofimplementations having to guarantee that the results would be exactly identical.

The wording allowingcp to copy a directory to implementation-defined file types not specified by the System Interfacesvolume of POSIX.1-2024 is provided so that implementations supporting symbolic links are not required to prohibit copyingdirectories to symbolic links. Other extensions to the System Interfaces volume of POSIX.1-2024 file types may need to use thisloophole as well.

FUTURE DIRECTIONS

If this utility is directed to create a new directory entry that contains any bytes that have the encoded value of a<newline> character, implementations are encouraged to treat this as an error. A future version of this standard may requireimplementations to treat this as an error.

SEE ALSO

mv,find,ln,pax

XBD4.7 File Access Permissions,8. Environment Variables,12.2Utility Syntax Guidelines

XSHopen(),unlink()

CHANGE HISTORY

First released in Issue 2.

Issue 6

The-r option is marked obsolescent.

The new options-H,-L, and-P are added to align with the IEEE P1003.2b draft standard. These optionsaffect the processing of symbolic links.

IEEE PASC Interpretation 1003.2 #194 is applied, adding a description of the-P option.

IEEE Std 1003.1-2001/Cor 1-2002, item XCU/TC1/D6/18 is applied, correcting an error in the SEE ALSO section.

Issue 7

Austin Group Interpretation 1003.1-2001 #126 is applied, changing the description of theLC_MESSAGES environmentvariable.

Austin Group Interpretations 1003.1-2001 #092, #164, #165, and #168 are applied.

SD5-XCU-ERN-31 and SD5-XCU-ERN-42 are applied, updating the DESCRIPTION.

SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.

SD5-XCU-ERN-102 is applied, clarifying the-i option within the OPTIONS section.

The obsolescent-r option is removed.

The-P option is added to the SYNOPSIS and to the DESCRIPTION with respect to the-R option.

Issue 8

Austin Group Defect 251 is applied, encouraging implementations to disallow the creation of filenames containing any bytes thathave the encoded value of a <newline> character.

Austin Group Defect 1122 is applied, changing the description ofNLSPATH .

Austin Group Defect 1732 is applied, changing the EXIT STATUS section.