mirror of https://github.com/mkerrisk/man-pages
635 lines
25 KiB
Groff
635 lines
25 KiB
Groff
|
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
||
|
.TH "CP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
||
|
.\" cp
|
||
|
.SH NAME
|
||
|
cp \- copy files
|
||
|
.SH SYNOPSIS
|
||
|
.LP
|
||
|
\fBcp\fP \fB[\fP\fB-fip\fP\fB]\fP \fIsource_file target_file\fP\fB
|
||
|
.br
|
||
|
.sp
|
||
|
cp\fP \fB[\fP\fB-fip\fP\fB]\fP \fIsource_file\fP \fB...\fP \fItarget\fP\fB
|
||
|
.br
|
||
|
.sp
|
||
|
cp -R\fP \fB[\fP\fB-H | -L | -P\fP\fB][\fP\fB-fip\fP\fB]\fP \fIsource_file\fP
|
||
|
\fB\&...\fP \fItarget\fP\fB
|
||
|
.br
|
||
|
.sp
|
||
|
cp -r\fP \fB[\fP\fB-H | -L | -P\fP\fB][\fP\fB-fip\fP\fB]\fP \fIsource_file\fP
|
||
|
\fB\&...\fP \fItarget\fP\fB
|
||
|
.br
|
||
|
\fP
|
||
|
.SH DESCRIPTION
|
||
|
.LP
|
||
|
The first synopsis form is denoted by two operands, neither of which
|
||
|
are existing files of type directory. The \fIcp\fP utility
|
||
|
shall copy the contents of \fIsource_file\fP (or, if \fIsource_file\fP
|
||
|
is a file of type symbolic link, the contents of the file
|
||
|
referenced by \fIsource_file\fP) to the destination path named by
|
||
|
\fItarget_file.\fP
|
||
|
.LP
|
||
|
The second synopsis form is denoted by two or more operands where
|
||
|
the \fB-R\fP or \fB-r\fP options are not specified and the
|
||
|
first synopsis form is not applicable. It shall be an error if any
|
||
|
\fIsource_file\fP is a file of type directory, if \fItarget\fP
|
||
|
does not exist, or if \fItarget\fP is a file of a type defined by
|
||
|
the System Interfaces volume of IEEE\ Std\ 1003.1-2001,
|
||
|
but is not a file of type directory. The \fIcp\fP utility shall copy
|
||
|
the contents of each \fIsource_file\fP (or, if
|
||
|
\fIsource_file\fP is a file of type symbolic link, the contents of
|
||
|
the file referenced by \fIsource_file\fP) to the destination
|
||
|
path named by the concatenation of \fItarget\fP, a slash character,
|
||
|
and the last component of \fIsource_file\fP.
|
||
|
.LP
|
||
|
The third and fourth synopsis forms are denoted by two or more operands
|
||
|
where the \fB-R\fP or \fB-r\fP options are specified.
|
||
|
The \fIcp\fP utility shall copy each file in the file hierarchy rooted
|
||
|
in each \fIsource_file\fP to a destination path named as
|
||
|
follows:
|
||
|
.IP " *" 3
|
||
|
If \fItarget\fP exists and is a file of type directory, the name of
|
||
|
the corresponding destination path for each file in the
|
||
|
file hierarchy shall be the concatenation of \fItarget\fP, a slash
|
||
|
character, and the pathname of the file relative to the
|
||
|
directory containing \fIsource_file\fP.
|
||
|
.LP
|
||
|
.IP " *" 3
|
||
|
If \fItarget\fP does not exist and two operands are specified, the
|
||
|
name of the corresponding destination path for
|
||
|
\fIsource_file\fP shall be \fItarget\fP; the name of the corresponding
|
||
|
destination path for all other files in the file hierarchy
|
||
|
shall be the concatenation of \fItarget\fP, a slash character, and
|
||
|
the pathname of the file relative to \fIsource_file\fP.
|
||
|
.LP
|
||
|
.LP
|
||
|
It shall be an error if \fItarget\fP does not exist and more than
|
||
|
two operands are specified, or if \fItarget\fP exists and is
|
||
|
a file of a type defined by the System Interfaces volume of IEEE\ Std\ 1003.1-2001,
|
||
|
but is not a file of type
|
||
|
directory.
|
||
|
.LP
|
||
|
In the following description, the term \fIdest_file\fP refers to the
|
||
|
file named by the destination path. The term
|
||
|
\fIsource_file\fP refers to the file that is being copied, whether
|
||
|
specified as an operand or a file in a file hierarchy rooted in
|
||
|
a \fIsource_file\fP operand. If \fIsource_file\fP is a file of type
|
||
|
symbolic link:
|
||
|
.IP " *" 3
|
||
|
If neither the \fB-R\fP nor \fB-r\fP options were specified, \fIcp\fP
|
||
|
shall take actions based on the type and contents of
|
||
|
the file referenced by the symbolic link, and not by the symbolic
|
||
|
link itself.
|
||
|
.LP
|
||
|
.IP " *" 3
|
||
|
If the \fB-R\fP option was specified:
|
||
|
.RS
|
||
|
.IP " *" 3
|
||
|
If none of the options \fB-H\fP, \fB-L\fP, nor \fB-P\fP were specified,
|
||
|
it is unspecified which of \fB-H\fP, \fB-L\fP, or
|
||
|
\fB-P\fP will be used as a default.
|
||
|
.LP
|
||
|
.IP " *" 3
|
||
|
If the \fB-H\fP option was specified, \fIcp\fP shall take actions
|
||
|
based on the type and contents of the file referenced by any
|
||
|
symbolic link specified as a \fIsource_file\fP operand.
|
||
|
.LP
|
||
|
.IP " *" 3
|
||
|
If the \fB-L\fP option was specified, \fIcp\fP shall take actions
|
||
|
based on the type and contents of the file referenced by any
|
||
|
symbolic link specified as a \fIsource_file\fP operand or any symbolic
|
||
|
links encountered during traversal of a file hierarchy.
|
||
|
.LP
|
||
|
.IP " *" 3
|
||
|
If the \fB-P\fP option was specified, \fIcp\fP shall copy any symbolic
|
||
|
link specified as a \fIsource_file\fP operand and any
|
||
|
symbolic links encountered during traversal of a file hierarchy, and
|
||
|
shall not follow any symbolic links.
|
||
|
.LP
|
||
|
.RE
|
||
|
.LP
|
||
|
.IP " *" 3
|
||
|
If the \fB-r\fP option was specified, the behavior is implementation-defined.
|
||
|
.LP
|
||
|
.LP
|
||
|
For each \fIsource_file\fP, the following steps shall be taken:
|
||
|
.IP " 1." 4
|
||
|
If \fIsource_file\fP references the same file as \fIdest_file\fP,
|
||
|
\fIcp\fP may write a diagnostic message to standard error;
|
||
|
it shall do nothing more with \fIsource_file\fP and shall go on to
|
||
|
any remaining files.
|
||
|
.LP
|
||
|
.IP " 2." 4
|
||
|
If \fIsource_file\fP is of type directory, the following steps shall
|
||
|
be taken:
|
||
|
.RS
|
||
|
.IP " a." 4
|
||
|
If neither the \fB-R\fP or \fB-r\fP options were specified, \fIcp\fP
|
||
|
shall write a diagnostic message to standard error, do
|
||
|
nothing more with \fIsource_file\fP, and go on to any remaining files.
|
||
|
.LP
|
||
|
.IP " b." 4
|
||
|
If \fIsource_file\fP was not specified as an operand and \fIsource_file\fP
|
||
|
is dot or dot-dot, \fIcp\fP shall do nothing more
|
||
|
with \fIsource_file\fP and go on to any remaining files.
|
||
|
.LP
|
||
|
.IP " c." 4
|
||
|
If \fIdest_file\fP exists and it is a file type not specified by the
|
||
|
System Interfaces volume of
|
||
|
IEEE\ Std\ 1003.1-2001, the behavior is implementation-defined.
|
||
|
.LP
|
||
|
.IP " d." 4
|
||
|
If \fIdest_file\fP exists and it is not of type directory, \fIcp\fP
|
||
|
shall write a diagnostic message to standard error, do
|
||
|
nothing more with \fIsource_file\fP or any files below \fIsource_file\fP
|
||
|
in the file hierarchy, and go on to any remaining
|
||
|
files.
|
||
|
.LP
|
||
|
.IP " e." 4
|
||
|
If the directory \fIdest_file\fP does not exist, it shall be created
|
||
|
with file permission bits set to the same value as those
|
||
|
of \fIsource_file\fP, modified by the file creation mask of the user
|
||
|
if the \fB-p\fP option was not specified, and then
|
||
|
bitwise-inclusively OR'ed with S_IRWXU. If \fIdest_file\fP cannot
|
||
|
be created, \fIcp\fP shall write a diagnostic message to
|
||
|
standard error, do nothing more with \fIsource_file\fP, and go on
|
||
|
to any remaining files. It is unspecified if \fIcp\fP attempts
|
||
|
to copy files in the file hierarchy rooted in \fIsource_file\fP.
|
||
|
.LP
|
||
|
.IP " f." 4
|
||
|
The files in the directory \fIsource_file\fP shall be copied to the
|
||
|
directory \fIdest_file\fP, taking the four steps (1 to 4)
|
||
|
listed here with the files as \fIsource_file\fPs.
|
||
|
.LP
|
||
|
.IP " g." 4
|
||
|
If \fIdest_file\fP was created, its file permission bits shall be
|
||
|
changed (if necessary) to be the same as those of
|
||
|
\fIsource_file\fP, modified by the file creation mask of the user
|
||
|
if the \fB-p\fP option was not specified.
|
||
|
.LP
|
||
|
.IP " h." 4
|
||
|
The \fIcp\fP utility shall do nothing more with \fIsource_file\fP
|
||
|
and go on to any remaining files.
|
||
|
.LP
|
||
|
.RE
|
||
|
.LP
|
||
|
.IP " 3." 4
|
||
|
If \fIsource_file\fP is of type regular file, the following steps
|
||
|
shall be taken:
|
||
|
.RS
|
||
|
.IP " a." 4
|
||
|
If \fIdest_file\fP exists, the following steps shall be taken:
|
||
|
.RS
|
||
|
.IP "i. " 5
|
||
|
If the \fB-i\fP option is in effect, the \fIcp\fP utility shall write
|
||
|
a prompt to the standard error and read a line from the
|
||
|
standard input. If the response is not affirmative, \fIcp\fP shall
|
||
|
do nothing more with \fIsource_file\fP and go on to any
|
||
|
remaining files.
|
||
|
.LP
|
||
|
.IP "ii." 5
|
||
|
A file descriptor for \fIdest_file\fP shall be obtained by performing
|
||
|
actions equivalent to the \fIopen\fP() function defined in the System
|
||
|
Interfaces volume of IEEE\ Std\ 1003.1-2001
|
||
|
called using \fIdest_file\fP as the \fIpath\fP argument, and the bitwise-inclusive
|
||
|
OR of O_WRONLY and O_TRUNC as the \fIoflag\fP
|
||
|
argument.
|
||
|
.LP
|
||
|
.IP "iii." 5
|
||
|
If the attempt to obtain a file descriptor fails and the \fB-f\fP
|
||
|
option is in effect, \fIcp\fP shall attempt to remove the
|
||
|
file by performing actions equivalent to the \fIunlink\fP() function
|
||
|
defined in the System
|
||
|
Interfaces volume of IEEE\ Std\ 1003.1-2001 called using \fIdest_file\fP
|
||
|
as the \fIpath\fP argument. If this attempt
|
||
|
succeeds, \fIcp\fP shall continue with step 3b.
|
||
|
.LP
|
||
|
.RE
|
||
|
.LP
|
||
|
.IP " b." 4
|
||
|
If \fIdest_file\fP does not exist, a file descriptor shall be obtained
|
||
|
by performing actions equivalent to the \fIopen\fP() function defined
|
||
|
in the System Interfaces volume of IEEE\ Std\ 1003.1-2001
|
||
|
called using \fIdest_file\fP as the \fIpath\fP argument, and the bitwise-inclusive
|
||
|
OR of O_WRONLY and O_CREAT as the \fIoflag\fP
|
||
|
argument. The file permission bits of \fIsource_file\fP shall be the
|
||
|
\fImode\fP argument.
|
||
|
.LP
|
||
|
.IP " c." 4
|
||
|
If the attempt to obtain a file descriptor fails, \fIcp\fP shall write
|
||
|
a diagnostic message to standard error, do nothing more
|
||
|
with \fIsource_file\fP, and go on to any remaining files.
|
||
|
.LP
|
||
|
.IP " d." 4
|
||
|
The contents of \fIsource_file\fP shall be written to the file descriptor.
|
||
|
Any write errors shall cause \fIcp\fP to write a
|
||
|
diagnostic message to standard error and continue to step 3e.
|
||
|
.LP
|
||
|
.IP " e." 4
|
||
|
The file descriptor shall be closed.
|
||
|
.LP
|
||
|
.IP " f." 4
|
||
|
The \fIcp\fP utility shall do nothing more with \fIsource_file\fP.
|
||
|
If a write error occurred in step 3d, it is unspecified if
|
||
|
\fIcp\fP continues with any remaining files. If no write error occurred
|
||
|
in step 3d, \fIcp\fP shall go on to any remaining
|
||
|
files.
|
||
|
.LP
|
||
|
.RE
|
||
|
.LP
|
||
|
.IP " 4." 4
|
||
|
Otherwise, the following steps shall be taken:
|
||
|
.RS
|
||
|
.IP " a." 4
|
||
|
If the \fB-r\fP option was specified, the behavior is implementation-defined.
|
||
|
.LP
|
||
|
.IP " b." 4
|
||
|
If the \fB-R\fP option was specified, the following steps shall be
|
||
|
taken:
|
||
|
.RS
|
||
|
.IP "i. " 5
|
||
|
The \fIdest_file\fP shall be created with the same file type as \fIsource_file\fP.
|
||
|
.LP
|
||
|
.IP "ii." 5
|
||
|
If \fIsource_file\fP is a file of type FIFO, the file permission bits
|
||
|
shall be the same as those of \fIsource_file,\fP
|
||
|
modified by the file creation mask of the user if the \fB-p\fP option
|
||
|
was not specified. Otherwise, the permissions, owner ID, and
|
||
|
group ID of \fIdest_file\fP are implementation-defined.
|
||
|
.LP
|
||
|
If this creation fails for any reason, \fIcp\fP shall write a diagnostic
|
||
|
message to standard error, do nothing more with
|
||
|
\fIsource_file\fP, and go on to any remaining files.
|
||
|
.LP
|
||
|
.IP "iii." 5
|
||
|
If \fIsource_file\fP is a file of type symbolic link, the pathname
|
||
|
contained in \fIdest_file\fP shall be the same as the
|
||
|
pathname contained in \fIsource_file\fP.
|
||
|
.LP
|
||
|
If this fails for any reason, \fIcp\fP shall write a diagnostic message
|
||
|
to standard error, do nothing more with
|
||
|
\fIsource_file\fP, and go on to any remaining files.
|
||
|
.LP
|
||
|
.RE
|
||
|
.LP
|
||
|
.RE
|
||
|
.LP
|
||
|
.LP
|
||
|
If the implementation provides additional or alternate access control
|
||
|
mechanisms (see the Base Definitions volume of
|
||
|
IEEE\ Std\ 1003.1-2001, Section 4.4, File Access Permissions), their
|
||
|
effect on copies of files is implementation-defined.
|
||
|
.SH OPTIONS
|
||
|
.LP
|
||
|
The \fIcp\fP utility shall conform to the Base Definitions volume
|
||
|
of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
|
||
|
.LP
|
||
|
The following options shall be supported:
|
||
|
.TP 7
|
||
|
\fB-f\fP
|
||
|
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.
|
||
|
.TP 7
|
||
|
\fB-H\fP
|
||
|
Take actions based on the type and contents of the file referenced
|
||
|
by any symbolic link specified as a \fIsource_file\fP
|
||
|
operand.
|
||
|
.TP 7
|
||
|
\fB-i\fP
|
||
|
Write a prompt to standard error before copying to any existing destination
|
||
|
file. If the response from the standard input is
|
||
|
affirmative, the copy shall be attempted; otherwise, it shall not.
|
||
|
.TP 7
|
||
|
\fB-L\fP
|
||
|
Take actions based on the type and contents of the file referenced
|
||
|
by any symbolic link specified as a \fIsource_file\fP
|
||
|
operand or any symbolic links encountered during traversal of a file
|
||
|
hierarchy.
|
||
|
.TP 7
|
||
|
\fB-P\fP
|
||
|
Take actions on any symbolic link specified as a \fIsource_file\fP
|
||
|
operand or any symbolic link encountered during traversal
|
||
|
of a file hierarchy.
|
||
|
.TP 7
|
||
|
\fB-p\fP
|
||
|
Duplicate the following characteristics of each source file in the
|
||
|
corresponding destination file:
|
||
|
.RS
|
||
|
.IP " 1." 4
|
||
|
The time of last data modification and time of last access. If this
|
||
|
duplication fails for any reason, \fIcp\fP shall write a
|
||
|
diagnostic message to standard error.
|
||
|
.LP
|
||
|
.IP " 2." 4
|
||
|
The user ID and group ID. If this duplication fails for any reason,
|
||
|
it is unspecified whether \fIcp\fP writes a diagnostic
|
||
|
message to standard error.
|
||
|
.LP
|
||
|
.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, \fIcp\fP shall write a diagnostic
|
||
|
message to standard error.
|
||
|
.LP
|
||
|
.RE
|
||
|
.LP
|
||
|
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 \fIcp\fP writes a
|
||
|
diagnostic message to standard error.
|
||
|
.LP
|
||
|
The order in which the preceding characteristics are duplicated is
|
||
|
unspecified. The \fIdest_file\fP shall not be deleted if
|
||
|
these characteristics cannot be preserved.
|
||
|
.TP 7
|
||
|
\fB-R\fP
|
||
|
Copy file hierarchies.
|
||
|
.TP 7
|
||
|
\fB-r\fP
|
||
|
Copy file hierarchies. The treatment of special files is implementation-defined.
|
||
|
.sp
|
||
|
.LP
|
||
|
Specifying more than one of the mutually-exclusive options \fB-H\fP,
|
||
|
\fB-L\fP, and \fB-P\fP shall not be considered an error.
|
||
|
The last option specified shall determine the behavior of the utility.
|
||
|
.SH OPERANDS
|
||
|
.LP
|
||
|
The following operands shall be supported:
|
||
|
.TP 7
|
||
|
\fIsource_file\fP
|
||
|
A pathname of a file to be copied.
|
||
|
.TP 7
|
||
|
\fItarget_file\fP
|
||
|
A pathname of an existing or nonexistent file, used for the output
|
||
|
when a single file is copied.
|
||
|
.TP 7
|
||
|
\fItarget\fP
|
||
|
A pathname of a directory to contain the copied files.
|
||
|
.sp
|
||
|
.SH STDIN
|
||
|
.LP
|
||
|
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
|
||
|
.LP
|
||
|
The input files specified as operands may be of any file type.
|
||
|
.SH ENVIRONMENT VARIABLES
|
||
|
.LP
|
||
|
The following environment variables shall affect the execution of
|
||
|
\fIcp\fP:
|
||
|
.TP 7
|
||
|
\fILANG\fP
|
||
|
Provide a default value for the internationalization variables that
|
||
|
are unset or null. (See the Base Definitions volume of
|
||
|
IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables
|
||
|
for
|
||
|
the precedence of internationalization variables used to determine
|
||
|
the values of locale categories.)
|
||
|
.TP 7
|
||
|
\fILC_ALL\fP
|
||
|
If set to a non-empty string value, override the values of all the
|
||
|
other internationalization variables.
|
||
|
.TP 7
|
||
|
\fILC_COLLATE\fP
|
||
|
.sp
|
||
|
Determine the locale for the behavior of ranges, equivalence classes,
|
||
|
and multi-character collating elements used in the extended
|
||
|
regular expression defined for the \fByesexpr\fP locale keyword in
|
||
|
the \fILC_MESSAGES\fP category.
|
||
|
.TP 7
|
||
|
\fILC_CTYPE\fP
|
||
|
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 \fByesexpr\fP locale keyword in the \fILC_MESSAGES\fP
|
||
|
category.
|
||
|
.TP 7
|
||
|
\fILC_MESSAGES\fP
|
||
|
Determine the locale for the processing of affirmative responses that
|
||
|
should be used to affect the format and contents of
|
||
|
diagnostic messages written to standard error.
|
||
|
.TP 7
|
||
|
\fINLSPATH\fP
|
||
|
Determine the location of message catalogs for the processing of \fILC_MESSAGES
|
||
|
\&.\fP
|
||
|
.sp
|
||
|
.SH ASYNCHRONOUS EVENTS
|
||
|
.LP
|
||
|
Default.
|
||
|
.SH STDOUT
|
||
|
.LP
|
||
|
Not used.
|
||
|
.SH STDERR
|
||
|
.LP
|
||
|
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
|
||
|
.LP
|
||
|
The output files may be of any type.
|
||
|
.SH EXTENDED DESCRIPTION
|
||
|
.LP
|
||
|
None.
|
||
|
.SH EXIT STATUS
|
||
|
.LP
|
||
|
The following exit values shall be returned:
|
||
|
.TP 7
|
||
|
\ 0
|
||
|
All files were copied successfully.
|
||
|
.TP 7
|
||
|
>0
|
||
|
An error occurred.
|
||
|
.sp
|
||
|
.SH CONSEQUENCES OF ERRORS
|
||
|
.LP
|
||
|
If \fIcp\fP 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
|
||
|
\fIThe following sections are informative.\fP
|
||
|
.SH APPLICATION USAGE
|
||
|
.LP
|
||
|
The difference between \fB-R\fP and \fB-r\fP is in the treatment by
|
||
|
\fIcp\fP of file types other than regular and directory.
|
||
|
The original \fB-r\fP flag, for historic reasons, does not handle
|
||
|
special files any differently from regular files, but always
|
||
|
reads the file and copies its contents. This has obvious problems
|
||
|
in the presence of special file types; for example, character
|
||
|
devices, FIFOs, and sockets. The \fB-R\fP option is intended to recreate
|
||
|
the file hierarchy and the \fB-r\fP option supports
|
||
|
historical practice. It was anticipated that a future version of this
|
||
|
volume of IEEE\ Std\ 1003.1-2001 would deprecate the
|
||
|
\fB-r\fP option, and for that reason, there has been no attempt to
|
||
|
fix its behavior with respect to FIFOs or other file types
|
||
|
where copying the file is clearly wrong. However, some implementations
|
||
|
support \fB-r\fP with the same abilities as the \fB-R\fP
|
||
|
defined in this volume of IEEE\ Std\ 1003.1-2001. To accommodate them
|
||
|
as well as systems that do not, the differences
|
||
|
between \fB-r\fP and \fB-R\fP are implementation-defined. Implementations
|
||
|
may make them identical. The \fB-r\fP option is marked
|
||
|
obsolescent.
|
||
|
.LP
|
||
|
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
|
||
|
.LP
|
||
|
None.
|
||
|
.SH RATIONALE
|
||
|
.LP
|
||
|
The \fB-i\fP 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 \fB-i\fP is a request for interaction, so when the destination
|
||
|
path exists, the utility takes instructions from whatever
|
||
|
responds on standard input.
|
||
|
.LP
|
||
|
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 \fB-i\fP option relies on the system to provide
|
||
|
the most suitable dialog directly with the user, based on
|
||
|
the behavior specified.
|
||
|
.LP
|
||
|
The \fB-p\fP option is historical practice on BSD systems, duplicating
|
||
|
the time of last data modification and time of last
|
||
|
access. This volume of IEEE\ Std\ 1003.1-2001 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 IEEE\ Std\ 1003.1-2001 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.
|
||
|
.LP
|
||
|
It is unspecified whether \fIcp\fP writes diagnostic messages when
|
||
|
the user and group IDs cannot be set due to the widespread
|
||
|
practice of users using \fB-p\fP 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].
|
||
|
.LP
|
||
|
The \fB-r\fP option is historical practice on BSD and BSD-derived
|
||
|
systems, copying file hierarchies as opposed to single files.
|
||
|
This functionality is used heavily in historical applications, and
|
||
|
its loss would significantly decrease consensus. The \fB-R\fP
|
||
|
option was added as a close synonym to the \fB-r\fP option, selected
|
||
|
for consistency with all other options in this volume of
|
||
|
IEEE\ Std\ 1003.1-2001 that do recursive directory descent.
|
||
|
.LP
|
||
|
When a failure occurs during the copying of a file hierarchy, \fIcp\fP
|
||
|
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 \fIcp\fP shall attempt to copy
|
||
|
files below the file where the failure occurred (which cannot succeed
|
||
|
in any case).
|
||
|
.LP
|
||
|
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 \fImknod\fP, \fIln\fP, 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.
|
||
|
.LP
|
||
|
Additionally, the \fB-p\fP 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.
|
||
|
.LP
|
||
|
When creating regular files, historical versions of \fIcp\fP 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.
|
||
|
.LP
|
||
|
When creating directories, historical versions of \fIcp\fP 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 \fIcp\fP 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, \fIcp\fP
|
||
|
fails. Also, once the copy is done, historical versions of \fIcp\fP
|
||
|
set the permissions on the created directory to be the same as
|
||
|
the source directory, unmodified by the file creation mask.
|
||
|
.LP
|
||
|
This behavior has been modified so that \fIcp\fP 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 \fIcp\fP in creating files.
|
||
|
.LP
|
||
|
It is not a requirement that \fIcp\fP 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.
|
||
|
.LP
|
||
|
There are two methods of copying subtrees in this volume of IEEE\ Std\ 1003.1-2001.
|
||
|
The other method is described as
|
||
|
part of the \fIpax\fP utility (see \fIpax\fP ). Both methods are
|
||
|
historical practice. The \fIcp\fP utility provides a simpler, more
|
||
|
intuitive interface, while \fIpax\fP offers a finer granularity of
|
||
|
control. Each provides additional functionality to the other;
|
||
|
in particular, \fIpax\fP maintains the hard-link structure of the
|
||
|
hierarchy, while \fIcp\fP
|
||
|
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.
|
||
|
.LP
|
||
|
The wording allowing \fIcp\fP to copy a directory to implementation-defined
|
||
|
file types not specified by the System Interfaces
|
||
|
volume of IEEE\ Std\ 1003.1-2001 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 IEEE\ Std\ 1003.1-2001 file
|
||
|
types may need to use this loophole as well.
|
||
|
.SH FUTURE DIRECTIONS
|
||
|
.LP
|
||
|
The \fB-r\fP option may be removed; use \fB-R\fP instead.
|
||
|
.SH SEE ALSO
|
||
|
.LP
|
||
|
\fImv\fP , \fIfind\fP , \fIln\fP , \fIpax\fP , the System Interfaces
|
||
|
volume of IEEE\ Std\ 1003.1-2001, \fIopen\fP(), \fIunlink\fP()
|
||
|
.SH COPYRIGHT
|
||
|
Portions of this text are reprinted and reproduced in electronic form
|
||
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
||
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
||
|
Specifications Issue 6, Copyright (C) 2001-2003 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 .
|