path: root/man1p/cp.1p

.\" 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 .