640 lines
29 KiB
HTML
640 lines
29 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta name="generator" content="HTML Tidy, see www.w3.org">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group's rhtm tool v1.2.1 -->
|
|
<!-- Copyright (c) 2001 The Open Group, All Rights Reserved -->
|
|
<title>cp</title>
|
|
</head>
|
|
<body bgcolor="white">
|
|
<script type="text/javascript" language="JavaScript" src="../jscript/codes.js">
|
|
</script>
|
|
|
|
<basefont size="3"> <a name="cp"></a> <a name="tag_04_27"></a><!-- cp -->
|
|
<!--header start-->
|
|
<center><font size="2">The Open Group Base Specifications Issue 6<br>
|
|
IEEE Std 1003.1-2001<br>
|
|
Copyright © 2001 The IEEE and The Open Group, All Rights reserved.</font></center>
|
|
|
|
<!--header end-->
|
|
<hr size="2" noshade>
|
|
<h4><a name="tag_04_27_01"></a>NAME</h4>
|
|
|
|
<blockquote>cp - copy files</blockquote>
|
|
|
|
<h4><a name="tag_04_27_02"></a>SYNOPSIS</h4>
|
|
|
|
<blockquote class="synopsis">
|
|
<p><code><tt>cp</tt> <b>[</b><tt>-fip</tt><b>]</b> <i>source_file target_file</i><tt><br>
|
|
<br>
|
|
cp</tt> <b>[</b><tt>-fip</tt><b>]</b> <i>source_file</i> <tt>...</tt> <i>target</i><tt><br>
|
|
<br>
|
|
cp -R</tt> <b>[</b><tt>-H | -L | -P</tt><b>][</b><tt>-fip</tt><b>]</b> <i>source_file</i> <tt>...</tt> <i>target</i><tt><br>
|
|
<br>
|
|
<sup>[<a href="javascript:open_code('OB')">OB</a>]</sup> cp <img src="../images/opt-start.gif" border="0">-r<img src=
|
|
"../images/opt-end.gif" border="0"></tt> <b>[</b><tt>-H | -L | -P</tt><b>][</b><tt>-fip</tt><b>]</b> <i>source_file</i>
|
|
<tt>...</tt> <i>target</i><tt><br>
|
|
</tt></code></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_27_03"></a>DESCRIPTION</h4>
|
|
|
|
<blockquote>
|
|
<p>The first synopsis form is denoted by two operands, neither of which are existing files of type directory. The <i>cp</i> utility
|
|
shall copy the contents of <i>source_file</i> (or, if <i>source_file</i> is a file of type symbolic link, the contents of the file
|
|
referenced by <i>source_file</i>) to the destination path named by <i>target_file.</i></p>
|
|
|
|
<p>The second synopsis form is denoted by two or more operands where the <b>-R</b> or <b>-r</b> options are not specified and the
|
|
first synopsis form is not applicable. It shall be an error if any <i>source_file</i> is a file of type directory, if <i>target</i>
|
|
does not exist, or if <i>target</i> 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 <i>cp</i> utility shall copy the contents of each <i>source_file</i> (or, if
|
|
<i>source_file</i> is a file of type symbolic link, the contents of the file referenced by <i>source_file</i>) to the destination
|
|
path named by the concatenation of <i>target</i>, a slash character, and the last component of <i>source_file</i>.</p>
|
|
|
|
<p>The third and fourth synopsis forms are denoted by two or more operands where the <b>-R</b> or <b>-r</b> options are specified.
|
|
The <i>cp</i> utility shall copy each file in the file hierarchy rooted in each <i>source_file</i> to a destination path named as
|
|
follows:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>If <i>target</i> 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 <i>target</i>, a slash character, and the pathname of the file relative to the
|
|
directory containing <i>source_file</i>.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If <i>target</i> does not exist and two operands are specified, the name of the corresponding destination path for
|
|
<i>source_file</i> shall be <i>target</i>; the name of the corresponding destination path for all other files in the file hierarchy
|
|
shall be the concatenation of <i>target</i>, a slash character, and the pathname of the file relative to <i>source_file</i>.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>It shall be an error if <i>target</i> does not exist and more than two operands are specified, or if <i>target</i> 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.</p>
|
|
|
|
<p>In the following description, the term <i>dest_file</i> refers to the file named by the destination path. The term
|
|
<i>source_file</i> refers to the file that is being copied, whether specified as an operand or a file in a file hierarchy rooted in
|
|
a <i>source_file</i> operand. If <i>source_file</i> is a file of type symbolic link:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>If neither the <b>-R</b> nor <b>-r</b> options were specified, <i>cp</i> shall take actions based on the type and contents of
|
|
the file referenced by the symbolic link, and not by the symbolic link itself.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If the <b>-R</b> option was specified:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>If none of the options <b>-H</b>, <b>-L</b>, nor <b>-P</b> were specified, it is unspecified which of <b>-H</b>, <b>-L</b>, or
|
|
<b>-P</b> will be used as a default.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If the <b>-H</b> option was specified, <i>cp</i> shall take actions based on the type and contents of the file referenced by any
|
|
symbolic link specified as a <i>source_file</i> operand.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If the <b>-L</b> option was specified, <i>cp</i> shall take actions based on the type and contents of the file referenced by any
|
|
symbolic link specified as a <i>source_file</i> operand or any symbolic links encountered during traversal of a file hierarchy.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If the <b>-P</b> option was specified, <i>cp</i> shall copy any symbolic link specified as a <i>source_file</i> operand and any
|
|
symbolic links encountered during traversal of a file hierarchy, and shall not follow any symbolic links.</p>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If the <b>-r</b> option was specified, the behavior is implementation-defined.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>For each <i>source_file</i>, the following steps shall be taken:</p>
|
|
|
|
<ol>
|
|
<li>
|
|
<p>If <i>source_file</i> references the same file as <i>dest_file</i>, <i>cp</i> may write a diagnostic message to standard error;
|
|
it shall do nothing more with <i>source_file</i> and shall go on to any remaining files.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If <i>source_file</i> is of type directory, the following steps shall be taken:</p>
|
|
|
|
<ol type="a">
|
|
<li>
|
|
<p>If neither the <b>-R</b> or <b>-r</b> options were specified, <i>cp</i> shall write a diagnostic message to standard error, do
|
|
nothing more with <i>source_file</i>, and go on to any remaining files.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If <i>source_file</i> was not specified as an operand and <i>source_file</i> is dot or dot-dot, <i>cp</i> shall do nothing more
|
|
with <i>source_file</i> and go on to any remaining files.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If <i>dest_file</i> 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.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If <i>dest_file</i> exists and it is not of type directory, <i>cp</i> shall write a diagnostic message to standard error, do
|
|
nothing more with <i>source_file</i> or any files below <i>source_file</i> in the file hierarchy, and go on to any remaining
|
|
files.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If the directory <i>dest_file</i> does not exist, it shall be created with file permission bits set to the same value as those
|
|
of <i>source_file</i>, modified by the file creation mask of the user if the <b>-p</b> option was not specified, and then
|
|
bitwise-inclusively OR'ed with S_IRWXU. If <i>dest_file</i> cannot be created, <i>cp</i> shall write a diagnostic message to
|
|
standard error, do nothing more with <i>source_file</i>, and go on to any remaining files. It is unspecified if <i>cp</i> attempts
|
|
to copy files in the file hierarchy rooted in <i>source_file</i>.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>The files in the directory <i>source_file</i> shall be copied to the directory <i>dest_file</i>, taking the four steps (1 to 4)
|
|
listed here with the files as <i>source_file</i>s.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If <i>dest_file</i> was created, its file permission bits shall be changed (if necessary) to be the same as those of
|
|
<i>source_file</i>, modified by the file creation mask of the user if the <b>-p</b> option was not specified.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>The <i>cp</i> utility shall do nothing more with <i>source_file</i> and go on to any remaining files.</p>
|
|
</li>
|
|
</ol>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If <i>source_file</i> is of type regular file, the following steps shall be taken:</p>
|
|
|
|
<ol type="a">
|
|
<li>
|
|
<p>If <i>dest_file</i> exists, the following steps shall be taken:</p>
|
|
|
|
<ol type="i">
|
|
<li>
|
|
<p>If the <b>-i</b> option is in effect, the <i>cp</i> utility shall write a prompt to the standard error and read a line from the
|
|
standard input. If the response is not affirmative, <i>cp</i> shall do nothing more with <i>source_file</i> and go on to any
|
|
remaining files.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>A file descriptor for <i>dest_file</i> shall be obtained by performing actions equivalent to the <a href=
|
|
"../functions/open.html"><i>open</i>()</a> function defined in the System Interfaces volume of IEEE Std 1003.1-2001
|
|
called using <i>dest_file</i> as the <i>path</i> argument, and the bitwise-inclusive OR of O_WRONLY and O_TRUNC as the <i>oflag</i>
|
|
argument.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If the attempt to obtain a file descriptor fails and the <b>-f</b> option is in effect, <i>cp</i> shall attempt to remove the
|
|
file by performing actions equivalent to the <a href="../functions/unlink.html"><i>unlink</i>()</a> function defined in the System
|
|
Interfaces volume of IEEE Std 1003.1-2001 called using <i>dest_file</i> as the <i>path</i> argument. If this attempt
|
|
succeeds, <i>cp</i> shall continue with step 3b.</p>
|
|
</li>
|
|
</ol>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If <i>dest_file</i> does not exist, a file descriptor shall be obtained by performing actions equivalent to the <a href=
|
|
"../functions/open.html"><i>open</i>()</a> function defined in the System Interfaces volume of IEEE Std 1003.1-2001
|
|
called using <i>dest_file</i> as the <i>path</i> argument, and the bitwise-inclusive OR of O_WRONLY and O_CREAT as the <i>oflag</i>
|
|
argument. The file permission bits of <i>source_file</i> shall be the <i>mode</i> argument.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If the attempt to obtain a file descriptor fails, <i>cp</i> shall write a diagnostic message to standard error, do nothing more
|
|
with <i>source_file</i>, and go on to any remaining files.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>The contents of <i>source_file</i> shall be written to the file descriptor. Any write errors shall cause <i>cp</i> to write a
|
|
diagnostic message to standard error and continue to step 3e.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>The file descriptor shall be closed.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>The <i>cp</i> utility shall do nothing more with <i>source_file</i>. If a write error occurred in step 3d, it is unspecified if
|
|
<i>cp</i> continues with any remaining files. If no write error occurred in step 3d, <i>cp</i> shall go on to any remaining
|
|
files.</p>
|
|
</li>
|
|
</ol>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Otherwise, the following steps shall be taken:</p>
|
|
|
|
<ol type="a">
|
|
<li>
|
|
<p>If the <b>-r</b> option was specified, the behavior is implementation-defined.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If the <b>-R</b> option was specified, the following steps shall be taken:</p>
|
|
|
|
<ol type="i">
|
|
<li>
|
|
<p>The <i>dest_file</i> shall be created with the same file type as <i>source_file</i>.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If <i>source_file</i> is a file of type FIFO, the file permission bits shall be the same as those of <i>source_file,</i>
|
|
modified by the file creation mask of the user if the <b>-p</b> option was not specified. Otherwise, the permissions, owner ID, and
|
|
group ID of <i>dest_file</i> are implementation-defined.</p>
|
|
|
|
<p>If this creation fails for any reason, <i>cp</i> shall write a diagnostic message to standard error, do nothing more with
|
|
<i>source_file</i>, and go on to any remaining files.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If <i>source_file</i> is a file of type symbolic link, the pathname contained in <i>dest_file</i> shall be the same as the
|
|
pathname contained in <i>source_file</i>.</p>
|
|
|
|
<p>If this fails for any reason, <i>cp</i> shall write a diagnostic message to standard error, do nothing more with
|
|
<i>source_file</i>, and go on to any remaining files.</p>
|
|
</li>
|
|
</ol>
|
|
</li>
|
|
</ol>
|
|
</li>
|
|
</ol>
|
|
|
|
<p>If the implementation provides additional or alternate access control mechanisms (see the Base Definitions volume of
|
|
IEEE Std 1003.1-2001, <a href="../basedefs/xbd_chap04.html#tag_04_04">Section 4.4, File Access Permissions</a>), their
|
|
effect on copies of files is implementation-defined.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_27_04"></a>OPTIONS</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>cp</i> utility shall conform to the Base Definitions volume of IEEE Std 1003.1-2001, <a href=
|
|
"../basedefs/xbd_chap12.html#tag_12_02">Section 12.2, Utility Syntax Guidelines</a>.</p>
|
|
|
|
<p>The following options shall be supported:</p>
|
|
|
|
<dl compact>
|
|
<dt><b>-f</b></dt>
|
|
|
|
<dd>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.</dd>
|
|
|
|
<dt><b>-H</b></dt>
|
|
|
|
<dd>Take actions based on the type and contents of the file referenced by any symbolic link specified as a <i>source_file</i>
|
|
operand.</dd>
|
|
|
|
<dt><b>-i</b></dt>
|
|
|
|
<dd>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.</dd>
|
|
|
|
<dt><b>-L</b></dt>
|
|
|
|
<dd>Take actions based on the type and contents of the file referenced by any symbolic link specified as a <i>source_file</i>
|
|
operand or any symbolic links encountered during traversal of a file hierarchy.</dd>
|
|
|
|
<dt><b>-P</b></dt>
|
|
|
|
<dd>Take actions on any symbolic link specified as a <i>source_file</i> operand or any symbolic link encountered during traversal
|
|
of a file hierarchy.</dd>
|
|
|
|
<dt><b>-p</b></dt>
|
|
|
|
<dd>Duplicate the following characteristics of each source file in the corresponding destination file:
|
|
|
|
<ol>
|
|
<li>
|
|
<p>The time of last data modification and time of last access. If this duplication fails for any reason, <i>cp</i> shall write a
|
|
diagnostic message to standard error.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>The user ID and group ID. If this duplication fails for any reason, it is unspecified whether <i>cp</i> writes a diagnostic
|
|
message to standard error.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>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, <i>cp</i> shall write a diagnostic message to standard error.</p>
|
|
</li>
|
|
</ol>
|
|
|
|
<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 <i>cp</i> writes a
|
|
diagnostic message to standard error.</p>
|
|
|
|
<p>The order in which the preceding characteristics are duplicated is unspecified. The <i>dest_file</i> shall not be deleted if
|
|
these characteristics cannot be preserved.</p>
|
|
</dd>
|
|
|
|
<dt><b>-R</b></dt>
|
|
|
|
<dd>Copy file hierarchies.</dd>
|
|
|
|
<dt><b>-r</b></dt>
|
|
|
|
<dd><sup>[<a href="javascript:open_code('OB')">OB</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
Copy file hierarchies. The treatment of special files is implementation-defined. <img src="../images/opt-end.gif" alt=
|
|
"[Option End]" border="0"></dd>
|
|
</dl>
|
|
|
|
<p>Specifying more than one of the mutually-exclusive options <b>-H</b>, <b>-L</b>, and <b>-P</b> shall not be considered an error.
|
|
The last option specified shall determine the behavior of the utility.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_27_05"></a>OPERANDS</h4>
|
|
|
|
<blockquote>
|
|
<p>The following operands shall be supported:</p>
|
|
|
|
<dl compact>
|
|
<dt><i>source_file</i></dt>
|
|
|
|
<dd>A pathname of a file to be copied.</dd>
|
|
|
|
<dt><i>target_file</i></dt>
|
|
|
|
<dd>A pathname of an existing or nonexistent file, used for the output when a single file is copied.</dd>
|
|
|
|
<dt><i>target</i></dt>
|
|
|
|
<dd>A pathname of a directory to contain the copied files.</dd>
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_27_06"></a>STDIN</h4>
|
|
|
|
<blockquote>
|
|
<p>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.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_27_07"></a>INPUT FILES</h4>
|
|
|
|
<blockquote>
|
|
<p>The input files specified as operands may be of any file type.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_27_08"></a>ENVIRONMENT VARIABLES</h4>
|
|
|
|
<blockquote>
|
|
<p>The following environment variables shall affect the execution of <i>cp</i>:</p>
|
|
|
|
<dl compact>
|
|
<dt><i>LANG</i></dt>
|
|
|
|
<dd>Provide a default value for the internationalization variables that are unset or null. (See the Base Definitions volume of
|
|
IEEE Std 1003.1-2001, <a href="../basedefs/xbd_chap08.html#tag_08_02">Section 8.2, Internationalization Variables</a> for
|
|
the precedence of internationalization variables used to determine the values of locale categories.)</dd>
|
|
|
|
<dt><i>LC_ALL</i></dt>
|
|
|
|
<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd>
|
|
|
|
<dt><i>LC_COLLATE</i></dt>
|
|
|
|
<dd><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 <b>yesexpr</b> locale keyword in the <i>LC_MESSAGES</i> category.</dd>
|
|
|
|
<dt><i>LC_CTYPE</i></dt>
|
|
|
|
<dd>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 <b>yesexpr</b> locale keyword in the <i>LC_MESSAGES</i> category.</dd>
|
|
|
|
<dt><i>LC_MESSAGES</i></dt>
|
|
|
|
<dd>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.</dd>
|
|
|
|
<dt><i>NLSPATH</i></dt>
|
|
|
|
<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
Determine the location of message catalogs for the processing of <i>LC_MESSAGES .</i> <img src="../images/opt-end.gif" alt=
|
|
"[Option End]" border="0"></dd>
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_27_09"></a>ASYNCHRONOUS EVENTS</h4>
|
|
|
|
<blockquote>
|
|
<p>Default.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_27_10"></a>STDOUT</h4>
|
|
|
|
<blockquote>
|
|
<p>Not used.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_27_11"></a>STDERR</h4>
|
|
|
|
<blockquote>
|
|
<p>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.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_27_12"></a>OUTPUT FILES</h4>
|
|
|
|
<blockquote>
|
|
<p>The output files may be of any type.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_27_13"></a>EXTENDED DESCRIPTION</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_27_14"></a>EXIT STATUS</h4>
|
|
|
|
<blockquote>
|
|
<p>The following exit values shall be returned:</p>
|
|
|
|
<dl compact>
|
|
<dt> 0</dt>
|
|
|
|
<dd>All files were copied successfully.</dd>
|
|
|
|
<dt>>0</dt>
|
|
|
|
<dd>An error occurred.</dd>
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_27_15"></a>CONSEQUENCES OF ERRORS</h4>
|
|
|
|
<blockquote>
|
|
<p>If <i>cp</i> 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.</p>
|
|
</blockquote>
|
|
|
|
<hr>
|
|
<div class="box"><em>The following sections are informative.</em></div>
|
|
|
|
<h4><a name="tag_04_27_16"></a>APPLICATION USAGE</h4>
|
|
|
|
<blockquote>
|
|
<p>The difference between <b>-R</b> and <b>-r</b> is in the treatment by <i>cp</i> of file types other than regular and directory.
|
|
The original <b>-r</b> 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 <b>-R</b> option is intended to recreate the file hierarchy and the <b>-r</b> option supports
|
|
historical practice. It was anticipated that a future version of this volume of IEEE Std 1003.1-2001 would deprecate the
|
|
<b>-r</b> 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 <b>-r</b> with the same abilities as the <b>-R</b>
|
|
defined in this volume of IEEE Std 1003.1-2001. To accommodate them as well as systems that do not, the differences
|
|
between <b>-r</b> and <b>-R</b> are implementation-defined. Implementations may make them identical. The <b>-r</b> option is marked
|
|
obsolescent.</p>
|
|
|
|
<p>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.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_27_17"></a>EXAMPLES</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_27_18"></a>RATIONALE</h4>
|
|
|
|
<blockquote>
|
|
<p>The <b>-i</b> 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 <b>-i</b> is a request for interaction, so when the destination path exists, the utility takes instructions from whatever
|
|
responds on standard input.</p>
|
|
|
|
<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 <b>-i</b> option relies on the system to provide the most suitable dialog directly with the user, based on
|
|
the behavior specified.</p>
|
|
|
|
<p>The <b>-p</b> 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.</p>
|
|
|
|
<p>It is unspecified whether <i>cp</i> writes diagnostic messages when the user and group IDs cannot be set due to the widespread
|
|
practice of users using <b>-p</b> 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].</p>
|
|
|
|
<p>The <b>-r</b> 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 <b>-R</b>
|
|
option was added as a close synonym to the <b>-r</b> option, selected for consistency with all other options in this volume of
|
|
IEEE Std 1003.1-2001 that do recursive directory descent.</p>
|
|
|
|
<p>When a failure occurs during the copying of a file hierarchy, <i>cp</i> 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 <i>cp</i> shall attempt to copy
|
|
files below the file where the failure occurred (which cannot succeed in any case).</p>
|
|
|
|
<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 <i>mknod</i>, <a href="../utilities/ln.html"><i>ln</i></a>, 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>
|
|
|
|
<p>Additionally, the <b>-p</b> 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>
|
|
|
|
<p>When creating regular files, historical versions of <i>cp</i> 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>
|
|
|
|
<p>When creating directories, historical versions of <i>cp</i> 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 <i>cp</i> 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, <i>cp</i>
|
|
fails. Also, once the copy is done, historical versions of <i>cp</i> set the permissions on the created directory to be the same as
|
|
the source directory, unmodified by the file creation mask.</p>
|
|
|
|
<p>This behavior has been modified so that <i>cp</i> 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 <i>cp</i> in creating files.</p>
|
|
|
|
<p>It is not a requirement that <i>cp</i> 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>
|
|
|
|
<p>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 <a href="../utilities/pax.html"><i>pax</i></a> utility (see <a href="pax.html"><i>pax</i></a> ). Both methods are
|
|
historical practice. The <i>cp</i> utility provides a simpler, more intuitive interface, while <a href=
|
|
"../utilities/pax.html"><i>pax</i></a> offers a finer granularity of control. Each provides additional functionality to the other;
|
|
in particular, <a href="../utilities/pax.html"><i>pax</i></a> maintains the hard-link structure of the hierarchy, while <i>cp</i>
|
|
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>
|
|
|
|
<p>The wording allowing <i>cp</i> 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.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_27_19"></a>FUTURE DIRECTIONS</h4>
|
|
|
|
<blockquote>
|
|
<p>The <b>-r</b> option may be removed; use <b>-R</b> instead.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_27_20"></a>SEE ALSO</h4>
|
|
|
|
<blockquote>
|
|
<p><a href="mv.html"><i>mv</i></a> , <a href="find.html"><i>find</i></a> , <a href="ln.html"><i>ln</i></a> , <a href=
|
|
"pax.html"><i>pax</i></a> , the *(Zy, <a href="../functions/open.html"><i>open</i>()</a>, <a href=
|
|
"../functions/unlink.html"><i>unlink</i>()</a></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_27_21"></a>CHANGE HISTORY</h4>
|
|
|
|
<blockquote>
|
|
<p>First released in Issue 2.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_27_22"></a>Issue 6</h4>
|
|
|
|
<blockquote>
|
|
<p>The <b>-r</b> option is marked obsolescent.</p>
|
|
|
|
<p>The new options <b>-H</b>, <b>-L</b>, and <b>-P</b> are added to align with the IEEE P1003.2b draft standard. These options
|
|
affect the processing of symbolic links.</p>
|
|
|
|
<p>IEEE PASC Interpretation 1003.2 #194 is applied, adding a description of the <b>-P</b> option.</p>
|
|
</blockquote>
|
|
|
|
<div class="box"><em>End of informative text.</em></div>
|
|
|
|
<hr>
|
|
<hr size="2" noshade>
|
|
<center><font size="2"><!--footer start-->
|
|
UNIX ® is a registered Trademark of The Open Group.<br>
|
|
POSIX ® is a registered Trademark of The IEEE.<br>
|
|
[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
|
|
"../utilities/contents.html">XCU</a> | <a href="../functions/contents.html">XSH</a> | <a href="../xrat/contents.html">XRAT</a>
|
|
]</font></center>
|
|
|
|
<!--footer end-->
|
|
<hr size="2" noshade>
|
|
</body>
|
|
</html>
|
|
|