On Apache/1.3.41 (Unix) PHP/5.2.5 mod_perl/1.30 mod_gzip/1.3.26.1a
Under GNU General Public License
2009-01-08 06:12 @38.103.63.58 CrawledBy CCBot/1.0 (+http://www.commoncrawl.org/bot.html)
CP(P) CP(P)
NAME
cp - copy files
SYNOPSIS
cp [-fip] source_file target_file
cp [-fip] source_file ... target
cp -R [-H | -L | -P][-fip] 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. The cp utility shall copy the contents of source_file (or,
if source_file is a file of type symbolic link, the contents of the file referenced
by source_file) to the destination path named by target_file.
The second synopsis form is denoted by two or more operands where the -R or -r
options are not specified and the first synopsis form is not applicable. It shall
be an error if any source_file is a file of type directory, if target does not
exist, or if target 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 cp utility shall
copy the contents of each source_file (or, if source_file is a file of type sym-
bolic link, the contents of the file referenced by source_file) to the destination
path named by the concatenation of target, a slash character, and the last compo-
nent of source_file.
The third and fourth synopsis forms are denoted by two or more operands where the
-R or -r options are specified. The cp utility shall copy each file in the file
hierarchy rooted in each source_file to a destination path named as follows:
* If target 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 target, a slash character, and the pathname of the file relative to the
directory containing source_file.
* If target does not exist and two operands are specified, the name of the corre-
sponding destination path for source_file shall be target; the name of the cor-
responding destination path for all other files in the file hierarchy shall be
the concatenation of target, a slash character, and the pathname of the file
relative to source_file.
It shall be an error if target does not exist and more than two operands are speci-
fied, or if target 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.
In the following description, the term dest_file refers to the file named by the
destination path. The term 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
source_file operand. If source_file is a file of type symbolic link:
* If neither the -R nor -r options were specified, 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.
* 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 any symbolic link specified as a
source_file operand.
* If the -L option was specified, cp shall take actions based on the type and
contents of the file referenced by any symbolic link specified as a
source_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
a source_file operand and any symbolic links encountered during traversal of
a file hierarchy, and shall not follow any symbolic links.
* If the -r option was specified, the behavior is implementation-defined.
For each source_file, the following steps shall be taken:
1. If source_file references the same file as dest_file, cp may write a diagnostic
message to standard error; it shall do nothing more with source_file and shall
go on to any remaining files.
2. If source_file is of type directory, the following steps shall be taken:
a. If neither the -R or -r options were specified, cp shall write a diagnostic
message to standard error, do nothing more with source_file, and go on to
any remaining files.
b. If source_file was not specified as an operand and source_file is dot or
dot-dot, cp shall do nothing more with source_file and go on to any remain-
ing files.
c. If dest_file 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.
d. If dest_file exists and it is not of type directory, cp shall write a diag-
nostic message to standard error, do nothing more with source_file or any
files below source_file in the file hierarchy, and go on to any remaining
files.
e. If the directory dest_file does not exist, it shall be created with file
permission bits set to the same value as those of source_file, modified by
the file creation mask of the user if the -p option was not specified, and
then bitwise-inclusively OR’ed with S_IRWXU. If dest_file cannot be cre-
ated, cp shall write a diagnostic message to standard error, do nothing
more with source_file, and go on to any remaining files. It is unspecified
if cp attempts to copy files in the file hierarchy rooted in source_file.
f. The files in the directory source_file shall be copied to the directory
dest_file, taking the four steps (1 to 4) listed here with the files as
source_files.
g. If dest_file was created, its file permission bits shall be changed (if
necessary) to be the same as those of source_file, modified by the file
creation mask of the user if the -p option was not specified.
h. The cp utility shall do nothing more with source_file and go on to any
remaining files.
3. If source_file is of type regular file, the following steps shall be taken:
a. If dest_file exists, the following steps shall be taken:
i. If the -i option is in effect, the cp utility shall write a prompt to
the standard error and read a line from the standard input. If the
response is not affirmative, cp shall do nothing more with source_file
and go on to any remaining files.
ii. A file descriptor for dest_file shall be obtained by performing
actions equivalent to the open() function defined in the System Inter-
faces volume of IEEE Std 1003.1-2001 called using dest_file as the
path argument, and the bitwise-inclusive OR of O_WRONLY and O_TRUNC as
the oflag argument.
iii. If the attempt to obtain a file descriptor fails and the -f option is
in effect, cp shall attempt to remove the file by performing actions
equivalent to the unlink() function defined in the System Interfaces
volume of IEEE Std 1003.1-2001 called using dest_file as the path
argument. If this attempt succeeds, cp shall continue with step 3b.
b. If dest_file does not exist, a file descriptor shall be obtained by per-
forming actions equivalent to the open() function defined in the System
Interfaces volume of IEEE Std 1003.1-2001 called using dest_file as the
path argument, and the bitwise-inclusive OR of O_WRONLY and O_CREAT as the
oflag argument. The file permission bits of source_file shall be the mode
argument.
c. If the attempt to obtain a file descriptor fails, cp shall write a diagnos-
tic message to standard error, do nothing more with source_file, and go on
to any remaining files.
d. The contents of source_file shall be written to the file descriptor. Any
write errors shall cause cp to write a diagnostic message to standard error
and continue to step 3e.
e. The file descriptor shall be closed.
f. The cp utility shall do nothing more with source_file. If a write error
occurred in step 3d, it is unspecified if cp continues with any remaining
files. If no write error occurred in step 3d, cp shall go on to any remain-
ing files.
4. Otherwise, the following steps shall be taken:
a. If the -r option was specified, the behavior is implementation-defined.
b. If the -R option was specified, the following steps shall be taken:
i. The dest_file shall be created with the same file type as source_file.
ii. If source_file is a file of type FIFO, the file permission bits shall
be the same as those of source_file, modified by the file creation
mask of the user if the -p option was not specified. Otherwise, the
permissions, owner ID, and group ID of dest_file are implementation-
defined.
If this creation fails for any reason, cp shall write a diagnostic message
to standard error, do nothing more with source_file, and go on to any
remaining files.
iii. If source_file is a file of type symbolic link, the pathname contained
in dest_file shall be the same as the pathname contained in
source_file.
If this fails for any reason, cp shall write a diagnostic message to stan-
dard error, do nothing more with source_file, and go on to any remaining
files.
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.
OPTIONS
The cp utility shall conform to the Base Definitions volume of
IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
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 destination file and proceed.
-H Take actions based on the type and contents of the file referenced by any
symbolic link specified as a source_file operand.
-i 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.
-L Take actions based on the type and contents of the file referenced by any
symbolic link specified as a source_file operand or any symbolic links
encountered during traversal of a file hierarchy.
-P Take actions on any symbolic link specified as a source_file operand or any
symbolic link encountered during traversal of a file hierarchy.
-p Duplicate the following characteristics of each source file in the corre-
sponding destination file:
1. The time of last data modification and time of last access. If this
duplication fails for any reason, cp shall write a diagnostic message to
standard error.
2. The user ID and group ID. If this duplication fails for any reason, it
is unspecified whether cp writes a diagnostic message to standard error.
3. The file permission bits and the S_ISUID and S_ISGID bits. Other, imple-
mentation-defined, bits may be duplicated as well. If this 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 these bits are present in the source file
but are not duplicated in the destination file, it is unspecified whether cp writes
a diagnostic message to standard error.
The order in which the preceding characteristics are duplicated is unspecified. The
dest_file shall not be deleted if these characteristics cannot be preserved.
-R Copy file hierarchies.
-r Copy file hierarchies. The treatment of special files is implementation-
defined.
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.
target_file
A pathname of an existing or nonexistent file, used for the output when a
single file is copied.
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 of cp:
LANG 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 interna-
tionalization variables 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 extended regular expression
defined for the yesexpr locale keyword in the LC_MESSAGES category.
LC_CTYPE
Determine the locale for the interpretation of sequences of bytes of text
data as characters (for example, single-byte as opposed to multi-byte char-
acters in arguments and input files) and the behavior of character classes
used in the extended regular expression defined for the yesexpr locale key-
word in the LC_MESSAGES category.
LC_MESSAGES
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.
NLSPATH
Determine the location of message catalogs for the processing of LC_MESSAGES
.
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 contain the destination pathname, but its
format is otherwise unspecified. Otherwise, the standard error shall be used only
for diagnostic messages.
OUTPUT FILES
The output files may be of any type.
EXTENDED DESCRIPTION
None.
EXIT STATUS
The following exit values shall be returned:
0 All files were copied successfully.
>0 An error occurred.
CONSEQUENCES OF ERRORS
If 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.
The following sections are informative.
APPLICATION USAGE
The difference between -R and -r is in the treatment by cp of file types other than
regular and directory. The original -r 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 -R option is
intended to recreate the file hierarchy and the -r option supports historical prac-
tice. It was anticipated that a future version of this volume of
IEEE Std 1003.1-2001 would deprecate the -r 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 -r with
the same abilities as the -R defined in this volume of IEEE Std 1003.1-2001. To
accommodate them as well as systems that do not, the differences between -r and -R
are implementation-defined. Implementations may make them identical. The -r option
is marked obsolescent.
The set-user-ID and set-group-ID bits are explicitly cleared when files are cre-
ated. 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.
EXAMPLES
None.
RATIONALE
The -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 -i is a request for interaction, so when the destination path exists,
the utility takes instructions from whatever responds on standard input.
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 -i option relies on the system to provide the most suitable
dialog directly with the user, based on the behavior specified.
The -p 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 charac-
teristics 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.
It is unspecified whether cp writes diagnostic messages when the user and group IDs
cannot be set due to the widespread practice 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].
The -r option is historical practice on BSD and BSD-derived systems, copying file
hierarchies as opposed to single files. This functionality is used heavily in his-
torical applications, and its loss would significantly decrease consensus. The -R
option was added as a close synonym to the -r option, selected for consistency with
all other options in this volume of IEEE Std 1003.1-2001 that do recursive direc-
tory descent.
When a failure occurs during the copying of a file hierarchy, 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 cp shall attempt to copy files
below the file where the failure occurred (which cannot succeed in any case).
Permissions, owners, and groups of created special file types have been deliber-
ately 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 sug-
gested that the permissions, owner, and group be the same as if the user had run
the historical mknod, ln, or other utility to create the file. It is also probable
that additional privileges are required to create block, character, or other imple-
mentation-defined special file types.
Additionally, the -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 pro-
grams.
When creating regular files, historical versions of 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.
When creating directories, historical versions of 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 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, cp fails. Also, once the copy is done, historical
versions of cp set the permissions on the created directory to be the same as the
source directory, unmodified by the file creation mask.
This behavior has been modified so that 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 cp in creating files.
It is not a requirement that 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.
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 pax utility (see pax ). Both methods
are historical practice. The cp utility provides a simpler, more intuitive inter-
face, while pax offers a finer granularity of control. Each provides additional
functionality to the other; in particular, pax maintains the hard-link structure of
the hierarchy, while cp does not. It is the intention of the standard developers
that the results be similar (using appropriate option combinations in both utili-
ties). 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.
The wording allowing cp 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.
FUTURE DIRECTIONS
The -r option may be removed; use -R instead.
SEE ALSO
mv , find , ln , pax , the System Interfaces volume of IEEE Std 1003.1-2001,
open(), unlink()
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 .
POSIX 2003 CP(P)
Generated by $Id: phpMan.php,v 4.55 2007/09/05 04:42:51 chedong Exp $ Author: Che Dong
On Apache/1.3.41 (Unix) PHP/5.2.5 mod_perl/1.30 mod_gzip/1.3.26.1a
Under GNU General Public License
2009-01-08 06:12 @38.103.63.58 CrawledBy CCBot/1.0 (+http://www.commoncrawl.org/bot.html)