diff options
Diffstat (limited to 'man-pages-posix-2017/man1p/cp.1p')
| -rw-r--r-- | man-pages-posix-2017/man1p/cp.1p | 808 |
1 files changed, 808 insertions, 0 deletions
diff --git a/man-pages-posix-2017/man1p/cp.1p b/man-pages-posix-2017/man1p/cp.1p new file mode 100644 index 0000000..2738fcd --- /dev/null +++ b/man-pages-posix-2017/man1p/cp.1p @@ -0,0 +1,808 @@ +'\" et +.TH CP "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +cp +\(em copy files +.SH SYNOPSIS +.LP +.nf +cp \fB[\fR-Pfip\fB] \fIsource_file target_file\fR +.P +cp \fB[\fR-Pfip\fB] \fIsource_file\fR... \fItarget\fR +.P +cp -R \fB[\fR-H|-L|-P\fB] [\fR-fip\fB] \fIsource_file\fR... \fItarget\fR +.fi +.SH DESCRIPTION +The first synopsis form is denoted by two operands, neither of which +are existing files of type directory. The +.IR cp +utility shall copy the contents of +.IR source_file +(or, if +.IR source_file +is a file of type symbolic link, the contents of the file referenced by +.IR source_file ) +to the destination path named by +.IR target_file. +.P +The second synopsis form is denoted by two or more operands where the +.BR \-R +option is not specified and the first synopsis form is not +applicable. It shall be an error if any +.IR source_file +is a file of type directory, if +.IR target +does not exist, or if +.IR target +does not name a directory. The +.IR cp +utility shall copy the contents of each +.IR source_file +(or, if +.IR source_file +is a file of type symbolic link, the contents of the file referenced by +.IR source_file ) +to the destination path named by the concatenation of +.IR target , +a single +<slash> +character if +.IR target +did not end in a +<slash>, +and the last component of +.IR source_file . +.P +The third synopsis form is denoted by two or more operands where the +.BR \-R +option is specified. The +.IR cp +utility shall copy each file in the file hierarchy rooted in each +.IR source_file +to a destination path named as follows: +.IP " *" 4 +If +.IR target +exists and names an existing directory, the name of the corresponding +destination path for each file in the file hierarchy shall be the +concatenation of +.IR target , +a single +<slash> +character if +.IR target +did not end in a +<slash>, +and the pathname of the file relative to the directory containing +.IR source_file . +.IP " *" 4 +If +.IR target +does not exist and two operands are specified, the name of the +corresponding destination path for +.IR source_file +shall be +.IR target ; +the name of the corresponding destination path for all other files in +the file hierarchy shall be the concatenation of +.IR target , +a +<slash> +character, and the pathname of the file relative to +.IR source_file . +.P +It shall be an error if +.IR target +does not exist and more than two operands are specified, or if +.IR target +exists and does not name a directory. +.P +In the following description, the term +.IR dest_file +refers to the file named by the destination path. The term +.IR source_file +refers to the file that is being copied, whether specified as an +operand or a file in a file hierarchy rooted in a +.IR source_file +operand. If +.IR source_file +is a file of type symbolic link: +.IP " *" 4 +If the +.BR \-R +option was not specified, +.IR cp +shall take actions based on the type and contents of the file referenced +by the symbolic link, and not by the symbolic link itself, unless the +.BR \-P +option was specified. +.IP " *" 4 +If the +.BR \-R +option was specified: +.RS 4 +.IP -- 4 +If none of the options +.BR \-H , +.BR \-L , +nor +.BR \-P +were specified, it is unspecified which of +.BR \-H , +.BR \-L , +or +.BR \-P +will be used as a default. +.IP -- 4 +If the +.BR \-H +option was specified, +.IR cp +shall take actions based on the type and contents of the +file referenced by any symbolic link specified as a +.IR source_file +operand. +.IP -- 4 +If the +.BR \-L +option was specified, +.IR cp +shall take actions based on the type and contents of the +file referenced by any symbolic link specified as a +.IR source_file +operand or any symbolic links encountered during traversal of a +file hierarchy. +.IP -- 4 +If the +.BR \-P +option was specified, +.IR cp +shall copy any symbolic link specified as a +.IR source_file +operand and any symbolic links encountered during traversal of a +file hierarchy, and shall not follow any symbolic links. +.RE +.P +For each +.IR source_file , +the following steps shall be taken: +.IP " 1." 4 +If +.IR source_file +references the same file as +.IR dest_file , +.IR cp +may write a diagnostic message to standard error; it shall do nothing +more with +.IR source_file +and shall go on to any remaining files. +.IP " 2." 4 +If +.IR source_file +is of type directory, the following steps shall be taken: +.RS 4 +.IP " a." 4 +If the +.BR \-R +option was not specified, +.IR cp +shall write a diagnostic message to standard error, do nothing more +with +.IR source_file , +and go on to any remaining files. +.IP " b." 4 +If +.IR source_file +was not specified as an operand and +.IR source_file +is dot or dot-dot, +.IR cp +shall do nothing more with +.IR source_file +and go on to any remaining files. +.IP " c." 4 +If +.IR dest_file +exists and it is a file type not specified by the System Interfaces volume of POSIX.1\(hy2017, the behavior +is implementation-defined. +.IP " d." 4 +If +.IR dest_file +exists and it is not of type directory, +.IR cp +shall write a diagnostic message to standard error, do nothing more +with +.IR source_file +or any files below +.IR source_file +in the file hierarchy, and go on to any remaining files. +.IP " e." 4 +If the directory +.IR dest_file +does not exist, it shall be created with file permission bits set to +the same value as those of +.IR source_file , +modified by the file creation mask of the user if the +.BR \-p +option was not specified, and then bitwise-inclusively OR'ed with +S_IRWXU. If +.IR dest_file +cannot be created, +.IR cp +shall write a diagnostic message to standard error, do nothing more +with +.IR source_file , +and go on to any remaining files. It is unspecified if +.IR cp +attempts to copy files in the file hierarchy rooted in +.IR source_file . +.IP " f." 4 +The files in the directory +.IR source_file +shall be copied to the directory +.IR dest_file , +taking the four steps (1 to 4) listed here with the files as +.IR source_file s. +.IP " g." 4 +If +.IR dest_file +was created, its file permission bits shall be changed (if necessary) +to be the same as those of +.IR source_file , +modified by the file creation mask of the user if the +.BR \-p +option was not specified. +.IP " h." 4 +The +.IR cp +utility shall do nothing more with +.IR source_file +and go on to any remaining files. +.RE +.IP " 3." 4 +If +.IR source_file +is of type regular file, the following steps shall be taken: +.RS 4 +.IP " a." 4 +The behavior is unspecified if +.IR dest_file +exists and was written by a previous step. Otherwise, if +.IR dest_file +exists, the following steps shall be taken: +.RS 4 +.IP " i." 5 +If the +.BR \-i +option is in effect, the +.IR cp +utility shall write a prompt to the standard error and read a line from +the standard input. If the response is not affirmative, +.IR cp +shall do nothing more with +.IR source_file +and go on to any remaining files. +.IP ii. 5 +A file descriptor for +.IR dest_file +shall be obtained by performing actions equivalent to the +\fIopen\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2017 called using +.IR dest_file +as the +.IR path +argument, and the bitwise-inclusive OR of O_WRONLY and O_TRUNC as the +.IR oflag +argument. +.IP iii. 5 +If the attempt to obtain a file descriptor fails and the +.BR \-f +option is in effect, +.IR cp +shall attempt to remove the file by performing actions equivalent to +the +\fIunlink\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2017 called using +.IR dest_file +as the +.IR path +argument. If this attempt succeeds, +.IR cp +shall continue with step 3b. +.RE +.IP " b." 4 +If +.IR dest_file +does not exist, a file descriptor shall be obtained by performing +actions equivalent to the +\fIopen\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2017 called using +.IR dest_file +as the +.IR path +argument, and the bitwise-inclusive OR of O_WRONLY and O_CREAT as the +.IR oflag +argument. The file permission bits of +.IR source_file +shall be the +.IR mode +argument. +.IP " c." 4 +If the attempt to obtain a file descriptor fails, +.IR cp +shall write a diagnostic message to standard error, do nothing more with +.IR source_file , +and go on to any remaining files. +.IP " d." 4 +The contents of +.IR source_file +shall be written to the file descriptor. Any write errors shall cause +.IR cp +to write a diagnostic message to standard error and continue to step +3e. +.IP " e." 4 +The file descriptor shall be closed. +.IP " f." 4 +The +.IR cp +utility shall do nothing more with +.IR source_file . +If a write error occurred in step 3d, it is unspecified if +.IR cp +continues with any remaining files. If no write error occurred in step +3d, +.IR cp +shall go on to any remaining files. +.RE +.IP " 4." 4 +Otherwise, the +.BR \-R +option was specified, and the following steps shall be taken: +.RS 4 +.IP " a." 4 +The +.IR dest_file +shall be created with the same file type as +.IR source_file . +.IP " b." 4 +If +.IR source_file +is a file of type FIFO, the file permission bits shall be the same as +those of +.IR source_file, +modified by the file creation mask of the user if the +.BR \-p +option was not specified. Otherwise, the permissions, owner ID, and +group ID of +.IR dest_file +are implementation-defined. +.RS 4 +.P +If this creation fails for any reason, +.IR cp +shall write a diagnostic message to standard error, do nothing more +with +.IR source_file , +and go on to any remaining files. +.RE +.IP " c." 4 +If +.IR source_file +is a file of type symbolic link, and the options require the symbolic +link itself to be acted upon, the pathname contained in +.IR dest_file +shall be the same as the pathname contained in +.IR source_file . +.RS 4 +.P +If this fails for any reason, +.IR cp +shall write a diagnostic message to standard error, do nothing more +with +.IR source_file , +and go on to any remaining files. +.RE +.RE +.P +If the implementation provides additional or alternate access control +mechanisms (see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.5" ", " "File Access Permissions"), +their effect on copies of files is implementation-defined. +.SH OPTIONS +The +.IR cp +utility shall conform to the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\-f\fP" 10 +If a file descriptor for a destination file cannot be obtained, as +described in step 3.a.ii., attempt to unlink the destination file and +proceed. +.IP "\fB\-H\fP" 10 +Take actions based on the type and contents of the file referenced by +any symbolic link specified as a +.IR source_file +operand. +.IP "\fB\-i\fP" 10 +Write a prompt to standard error before copying to any existing +non-directory destination file. If the response from the standard input +is affirmative, the copy shall be attempted; otherwise, it shall not. +.IP "\fB\-L\fP" 10 +Take actions based on the type and contents of the file referenced by +any symbolic link specified as a +.IR source_file +operand or any symbolic links encountered during traversal of a +file hierarchy. +.IP "\fB\-P\fP" 10 +Take actions on any symbolic link specified as a +.IR source_file +operand or any symbolic link encountered during traversal of a +file hierarchy. +.IP "\fB\-p\fP" 10 +Duplicate the following characteristics of each source file in the +corresponding destination file: +.RS 10 +.IP " 1." 4 +The time of last data modification and time of last access. If this +duplication fails for any reason, +.IR cp +shall write a diagnostic message to standard error. +.IP " 2." 4 +The user ID and group ID. If this duplication fails for any reason, it +is unspecified whether +.IR cp +writes a diagnostic message to standard error. +.IP " 3." 4 +The file permission bits and the S_ISUID and S_ISGID bits. Other, +implementation-defined, bits may be duplicated as well. If this +duplication fails for any reason, +.IR cp +shall write a diagnostic message to standard error. +.P +If the user ID or the group ID cannot be duplicated, the file +permission bits S_ISUID and S_ISGID shall be cleared. If these bits are +present in the source file but are not duplicated in the destination +file, it is unspecified whether +.IR cp +writes a diagnostic message to standard error. +.P +The order in which the preceding characteristics are duplicated is +unspecified. The +.IR dest_file +shall not be deleted if these characteristics cannot be preserved. +.RE +.IP "\fB\-R\fR" 10 +Copy file hierarchies. +.P +Specifying more than one of the mutually-exclusive options +.BR \-H , +.BR \-L , +and +.BR \-P +shall not be considered an error. The last option specified shall +determine the behavior of the utility. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIsource_file\fR" 10 +A pathname of a file to be copied. If a +.IR source_file +operand is +.BR '\-' , +it shall refer to a file named +.BR \- ; +implementations shall not treat it as meaning standard input. +.IP "\fItarget_file\fR" 10 +A pathname of an existing or nonexistent file, used for the output when +a single file is copied. If a +.IR target_file +operand is +.BR '\-' , +it shall refer to a file named +.BR \- ; +implementations shall not treat it as meaning standard output. +.IP "\fItarget\fR" 10 +A pathname of a directory to contain the copied files. +.SH 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. +.SH "INPUT FILES" +The input files specified as operands may be of any file type. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR cp : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements used in the extended regular +expression defined for the +.BR yesexpr +locale keyword in the +.IR LC_MESSAGES +category. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files) and the behavior of +character classes used in the extended regular expression defined for +the +.BR yesexpr +locale keyword in the +.IR LC_MESSAGES +category. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale used to process affirmative responses, and the +locale used to affect the format and contents of diagnostic messages +and prompts written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +A prompt shall be written to standard error under the conditions +specified in the DESCRIPTION section. The prompt shall contain the +destination pathname, but its format is otherwise unspecified. +Otherwise, the standard error shall be used only for diagnostic +messages. +.SH "OUTPUT FILES" +The output files may be of any type. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +All files were copied successfully. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +If +.IR cp +is prematurely terminated by a signal or error, files or file +hierarchies may be only partially copied and files and directories may +have incorrect permissions or access and modification times. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The set-user-ID and set-group-ID bits are explicitly cleared when files +are created. This is to prevent users from creating programs 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 to new 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 of users has execute permission +to a set-user-ID program than did previously. In particular, this is a +problem for superusers copying users' trees. +.SH EXAMPLES +None. +.SH RATIONALE +The +.BR \-i +option exists on BSD systems, giving applications and users a way to +avoid accidentally removing files when copying. Although the 4.3 BSD +version does not prompt if the standard input is not a terminal, the +standard developers decided that use of +.BR \-i +is a request for interaction, so when the destination path exists, the +utility takes instructions from whatever responds on standard input. +.P +The exact format of the interactive prompts is unspecified. Only the +general nature of the contents of prompts are specified because +implementations may desire more descriptive prompts than those used on +historical implementations. Therefore, an application using the +.BR \-i +option relies on the system to provide the most suitable dialog +directly with the user, based on the behavior specified. +.P +The +.BR \-p +option is historical practice on BSD systems, duplicating the time of +last data modification and time of last access. This volume of POSIX.1\(hy2017 extends it to +preserve the user and group IDs, as well as the file permissions. This +requirement has obvious problems in that the directories are almost +certainly modified after being copied. This volume of POSIX.1\(hy2017 requires that the +modification times be preserved. The statement that the order in which +the characteristics are duplicated is unspecified is to permit +implementations to provide the maximum amount of security for the user. +Implementations should take into account the obvious security issues +involved in setting the owner, group, and mode in the wrong order or +creating files with an owner, group, or mode different from the final +value. +.P +It is unspecified whether +.IR cp +writes diagnostic messages when the user and group IDs cannot be set +due to the widespread practice of users using +.BR \-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 +.BR [EPERM] . +.P +Earlier versions of this standard included support for the +.BR \-r +option to copy file hierarchies. The +.BR \-r +option is historical practice on BSD and BSD-derived systems. This +option is no longer specified by POSIX.1\(hy2008 but may be present +in some implementations. The +.BR \-R +option was added as a close synonym to the +.BR \-r +option, selected for consistency with all other options in this volume of POSIX.1\(hy2017 that +do recursive directory descent. +.P +The difference between +.BR \-R +and the removed +.BR \-r +option is in the treatment by +.IR cp +of file types other than regular and directory. It was +implementation-defined how the +.BR \- +option treated special files to allow both historical implementations +and those that chose to support +.BR \-r +with the same abilities as +.BR \-R +defined by this volume of POSIX.1\(hy2017. The original +.BR \-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. +.P +When a failure occurs during the copying of a file hierarchy, +.IR cp +is required to attempt to copy files that are on the same level in the +hierarchy or above the file where the failure occurred. It is +unspecified if +.IR cp +shall attempt to copy files below the file where the failure occurred +(which cannot succeed in any case). +.P +Permissions, owners, and groups of created special file types have been +deliberately left as implementation-defined. This is to allow systems +to satisfy special requirements (for example, allowing users to create +character special devices, but requiring them to be owned by a certain +group). In general, it is strongly suggested that the permissions, +owner, and group be the same as if the user had run the historical +.IR mknod , +.IR ln , +or other utility to create the file. It is also probable that +additional privileges are required to create block, character, or +other implementation-defined special file types. +.P +Additionally, the +.BR \-p +option explicitly requires that all set-user-ID +and set-group-ID permissions be +discarded if any of the owner or group IDs cannot be set. This is to +keep users from unintentionally giving away special privilege when +copying programs. +.P +When creating regular files, historical versions of +.IR cp +use the mode of the source file as modified by the file mode creation +mask. Other choices would have been to use the mode of the source file +unmodified by the creation mask or to use the same mode 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 the file mode creation mask. In the +absence of any strong reason to change historic practice, it was in +large part retained. +.P +When creating directories, historical versions of +.IR cp +use the mode of the source directory, plus read, write, and search bits +for the owner, as modified by the file mode creation mask. This is done +so that +.IR cp +can copy trees where the user has read permission, but the owner does +not. A side-effect is that if the file creation mask denies the owner +permissions, +.IR cp +fails. Also, once the copy is done, historical versions of +.IR cp +set the permissions on the created directory to be the same as the +source directory, unmodified by the file creation mask. +.P +This behavior has been modified so that +.IR cp +is always able to create the contents of the directory, regardless of +the file creation mask. After the copy is done, the permissions are set +to be the same as the source directory, as modified by the file +creation mask. This latter change from historical behavior is to +prevent users from accidentally creating directories with permissions +beyond those they would normally set and for consistency with the +behavior of +.IR cp +in creating files. +.P +It is not a requirement that +.IR cp +detect attempts to copy a file to itself; however, implementations are +strongly encouraged to do so. Historical implementations have detected +the attempt in most cases. +.P +There are two methods of copying subtrees in this volume of POSIX.1\(hy2017. The other method is +described as part of the +.IR pax +utility (see +.IR "\fIpax\fR\^"). +Both methods are historical practice. The +.IR cp +utility provides a simpler, more intuitive interface, while +.IR pax +offers a finer granularity of control. Each provides additional +functionality to the other; in particular, +.IR pax +maintains the hard-link structure of the hierarchy, while +.IR cp +does not. It is the intention of the standard developers that the +results be similar (using appropriate option combinations in both +utilities). The results are not required to be identical; there seemed +insufficient gain to applications to balance the difficulty of +implementations having to guarantee that the results would be exactly +identical. +.P +The wording allowing +.IR cp +to copy a directory to implementation-defined file types not +specified by the System Interfaces volume of POSIX.1\(hy2017 is provided so that implementations supporting +symbolic links are not required to prohibit copying directories to +symbolic links. Other extensions to the System Interfaces volume of POSIX.1\(hy2017 file types may need to +use this loophole as well. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImv\fR\^", +.IR "\fIfind\fR\^", +.IR "\fIln\fR\^", +.IR "\fIpax\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.5" ", " "File Access Permissions", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2017, +.IR "\fIopen\fR\^(\|)", +.IR "\fIunlink\fR\^(\|)" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . |