Un outil pour savoir si une commande est posix - retour accueil
git clone git://bebou.netlib.re/isposix
Log | Files | Refs | README |
cp.html (32722B)
1 <!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved -->
2 <!DOCTYPE HTML>
3 <html lang="en">
4 <head>
5 <meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0">
6 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
7 <link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 -->
8 <!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved -->
9 <title>cp</title>
10 </head>
11 <body bgcolor="white">
12 <div class="NAVHEADER">
13 <table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0">
14 <tr class="nav">
15 <td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/compress.html" accesskey="P"><<<
16 Previous</a></td>
17 <td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td>
18 <td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/crontab.html" accesskey="N">Next
19 >>></a></td>
20 </tr>
21 </table>
22 <hr align="left" width="100%"></div>
23 <script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3">
24 <center><font size="2">The Open Group Base Specifications Issue 8<br>
25 IEEE Std 1003.1-2024<br>
26 Copyright © 2001-2024 The IEEE and The Open Group</font></center>
27 <hr size="2" noshade>
28 <a name="top" id="top"></a> <a name="cp" id="cp"></a> <a name="tag_20_24" id="tag_20_24"></a><!-- cp -->
29 <h4 class="mansect"><a name="tag_20_24_01" id="tag_20_24_01"></a>NAME</h4>
30 <blockquote>cp — copy files</blockquote>
31 <h4 class="mansect"><a name="tag_20_24_02" id="tag_20_24_02"></a>SYNOPSIS</h4>
32 <blockquote class="synopsis">
33 <p><code><tt>cp</tt> <b>[</b><tt>-Pfip</tt><b>]</b> <i>source_file target_file</i> <tt><br>
34 <br>
35 cp</tt> <b>[</b><tt>-Pfip</tt><b>]</b> <i>source_file</i><tt>...</tt> <i>target</i> <tt><br>
36 <br>
37 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></tt></code></p>
38 </blockquote>
39 <h4 class="mansect"><a name="tag_20_24_03" id="tag_20_24_03"></a>DESCRIPTION</h4>
40 <blockquote>
41 <p>The first synopsis form is denoted by two operands, neither of which are existing files of type directory. The <i>cp</i> utility
42 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
43 referenced by <i>source_file</i>) to the destination path named by <i>target_file.</i></p>
44 <p>The second synopsis form is denoted by two or more operands where the <b>-R</b> option is not specified and the first synopsis
45 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
46 exist, or if <i>target</i> does not name a directory. The <i>cp</i> utility shall copy the contents of each <i>source_file</i> (or,
47 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
48 destination path named by the concatenation of <i>target</i>, a single <slash> character if <i>target</i> did not end in a
49 <slash>, and the last component of <i>source_file</i>.</p>
50 <p>The third synopsis form is denoted by two or more operands where the <b>-R</b> option is specified. The <i>cp</i> utility shall
51 copy each file in the file hierarchy rooted in each <i>source_file</i> to a destination path named as follows:</p>
52 <ul>
53 <li>
54 <p>If <i>target</i> exists and names an existing directory, the name of the corresponding destination path for each file in the
55 file hierarchy shall be the concatenation of <i>target</i>, a single <slash> character if <i>target</i> did not end in a
56 <slash>, and the pathname of the file relative to the directory containing <i>source_file</i>.</p>
57 </li>
58 <li>
59 <p>If <i>target</i> does not exist and two operands are specified, the name of the corresponding destination path for
60 <i>source_file</i> shall be <i>target</i>; the name of the corresponding destination path for all other files in the file hierarchy
61 shall be the concatenation of <i>target</i>, a <slash> character, and the pathname of the file relative to
62 <i>source_file</i>.</p>
63 </li>
64 </ul>
65 <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
66 does not name a directory.</p>
67 <p>In the following description, the term <i>dest_file</i> refers to the file named by the destination path. The term
68 <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
69 a <i>source_file</i> operand. If <i>source_file</i> is a file of type symbolic link:</p>
70 <ul>
71 <li>
72 <p>If the <b>-R</b> option was not specified, <i>cp</i> shall take actions based on the type and contents of the file referenced by
73 the symbolic link, and not by the symbolic link itself, unless the <b>-P</b> option was specified.</p>
74 </li>
75 <li>
76 <p>If the <b>-R</b> option was specified:</p>
77 <ul>
78 <li>
79 <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
80 <b>-P</b> will be used as a default.</p>
81 </li>
82 <li>
83 <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
84 symbolic link specified as a <i>source_file</i> operand.</p>
85 </li>
86 <li>
87 <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
88 symbolic link specified as a <i>source_file</i> operand or any symbolic links encountered during traversal of a file hierarchy.</p>
89 </li>
90 <li>
91 <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
92 symbolic links encountered during traversal of a file hierarchy, and shall not follow any symbolic links.</p>
93 </li>
94 </ul>
95 </li>
96 </ul>
97 <p>For each <i>source_file</i>, the following steps shall be taken:</p>
98 <ol>
99 <li>
100 <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;
101 it shall do nothing more with <i>source_file</i> and shall go on to any remaining files.</p>
102 </li>
103 <li>
104 <p>If <i>source_file</i> is of type directory, the following steps shall be taken:</p>
105 <ol type="a">
106 <li>
107 <p>If the <b>-R</b> option was not specified, <i>cp</i> shall write a diagnostic message to standard error, do nothing more with
108 <i>source_file</i>, and go on to any remaining files.</p>
109 </li>
110 <li>
111 <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
112 with <i>source_file</i> and go on to any remaining files.</p>
113 </li>
114 <li>
115 <p>If <i>dest_file</i> exists and it is a file type not specified by the System Interfaces volume of POSIX.1-2024, the behavior is
116 implementation-defined.</p>
117 </li>
118 <li>
119 <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
120 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
121 files.</p>
122 </li>
123 <li>
124 <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
125 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
126 bitwise-inclusively OR'ed with S_IRWXU. If <i>dest_file</i> cannot be created, <i>cp</i> shall write a diagnostic message to
127 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
128 to copy files in the file hierarchy rooted in <i>source_file</i>.</p>
129 </li>
130 <li>
131 <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)
132 listed here with the files as <i>source_file</i>s.</p>
133 </li>
134 <li>
135 <p>If <i>dest_file</i> was created, its file permission bits shall be changed (if necessary) to be the same as those of
136 <i>source_file</i>, modified by the file creation mask of the user if the <b>-p</b> option was not specified.</p>
137 </li>
138 <li>
139 <p>The <i>cp</i> utility shall do nothing more with <i>source_file</i> and go on to any remaining files.</p>
140 </li>
141 </ol>
142 </li>
143 <li>
144 <p>If <i>source_file</i> is of type regular file, the following steps shall be taken:</p>
145 <ol type="a">
146 <li>
147 <p>The behavior is unspecified if <i>dest_file</i> exists and was written by a previous step. Otherwise, if <i>dest_file</i>
148 exists, the following steps shall be taken:</p>
149 <ol type="i">
150 <li>
151 <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
152 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
153 remaining files.</p>
154 </li>
155 <li>
156 <p>A file descriptor for <i>dest_file</i> shall be obtained by performing actions equivalent to the <a href=
157 "../functions/open.html"><i>open</i>()</a> function defined in the System Interfaces volume of POSIX.1-2024 called using
158 <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>
159 argument.</p>
160 </li>
161 <li>
162 <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
163 file by performing actions equivalent to the <a href="../functions/unlink.html"><i>unlink</i>()</a> function defined in the System
164 Interfaces volume of POSIX.1-2024 called using <i>dest_file</i> as the <i>path</i> argument. If this attempt succeeds, <i>cp</i>
165 shall continue with step 3b.</p>
166 </li>
167 </ol>
168 </li>
169 <li>
170 <p>If <i>dest_file</i> does not exist, a file descriptor shall be obtained by performing actions equivalent to the <a href=
171 "../functions/open.html"><i>open</i>()</a> function defined in the System Interfaces volume of POSIX.1-2024 called using
172 <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.
173 The file permission bits of <i>source_file</i> shall be the <i>mode</i> argument.</p>
174 </li>
175 <li>
176 <p>If the attempt to obtain a file descriptor fails, <i>cp</i> shall write a diagnostic message to standard error, do nothing more
177 with <i>source_file</i>, and go on to any remaining files.</p>
178 </li>
179 <li>
180 <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
181 diagnostic message to standard error and continue to step 3e.</p>
182 </li>
183 <li>
184 <p>The file descriptor shall be closed.</p>
185 </li>
186 <li>
187 <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
188 <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
189 files.</p>
190 </li>
191 </ol>
192 </li>
193 <li>
194 <p>Otherwise, the <b>-R</b> option was specified, and the following steps shall be taken:</p>
195 <ol type="a">
196 <li>
197 <p>The <i>dest_file</i> shall be created with the same file type as <i>source_file</i>.</p>
198 </li>
199 <li>
200 <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>
201 modified by the file creation mask of the user if the <b>-p</b> option was not specified. Otherwise, the permissions, owner ID, and
202 group ID of <i>dest_file</i> are implementation-defined.</p>
203 <p>If this creation fails for any reason, <i>cp</i> shall write a diagnostic message to standard error, do nothing more with
204 <i>source_file</i>, and go on to any remaining files.</p>
205 </li>
206 <li>
207 <p>If <i>source_file</i> is a file of type symbolic link, and the options require the symbolic link itself to be acted upon, the
208 pathname contained in <i>dest_file</i> shall be the same as the pathname contained in <i>source_file</i>.</p>
209 <p>If this fails for any reason, <i>cp</i> shall write a diagnostic message to standard error, do nothing more with
210 <i>source_file</i>, and go on to any remaining files.</p>
211 </li>
212 </ol>
213 </li>
214 </ol>
215 <p>If the implementation provides additional or alternate access control mechanisms (see XBD <a href=
216 "../basedefs/V1_chap04.html#tag_04_07"><i>4.7 File Access Permissions</i></a> ), their effect on copies of files is
217 implementation-defined.</p>
218 </blockquote>
219 <h4 class="mansect"><a name="tag_20_24_04" id="tag_20_24_04"></a>OPTIONS</h4>
220 <blockquote>
221 <p>The <i>cp</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax
222 Guidelines</i></a> .</p>
223 <p>The following options shall be supported:</p>
224 <dl compact>
225 <dd></dd>
226 <dt><b>-f</b></dt>
227 <dd>If a file descriptor for a destination file cannot be obtained, as described in step 3.a.ii., attempt to unlink the destination
228 file and proceed.</dd>
229 <dt><b>-H</b></dt>
230 <dd>Take actions based on the type and contents of the file referenced by any symbolic link specified as a <i>source_file</i>
231 operand.</dd>
232 <dt><b>-i</b></dt>
233 <dd>Write a prompt to standard error before copying to any existing non-directory destination file. If the response from the
234 standard input is affirmative, the copy shall be attempted; otherwise, it shall not.</dd>
235 <dt><b>-L</b></dt>
236 <dd>Take actions based on the type and contents of the file referenced by any symbolic link specified as a <i>source_file</i>
237 operand or any symbolic links encountered during traversal of a file hierarchy.</dd>
238 <dt><b>-P</b></dt>
239 <dd>Take actions on any symbolic link specified as a <i>source_file</i> operand or any symbolic link encountered during traversal
240 of a file hierarchy.</dd>
241 <dt><b>-p</b></dt>
242 <dd>Duplicate the following characteristics of each source file in the corresponding destination file:
243 <ol>
244 <li>
245 <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
246 diagnostic message to standard error.</p>
247 </li>
248 <li>
249 <p>The user ID and group ID. If this duplication fails for any reason, it is unspecified whether <i>cp</i> writes a diagnostic
250 message to standard error.</p>
251 </li>
252 <li>
253 <p>The file permission bits and the S_ISUID and S_ISGID bits. Other, implementation-defined, bits may be duplicated as well. If
254 this duplication fails for any reason, <i>cp</i> shall write a diagnostic message to standard error.</p>
255 </li>
256 </ol>
257 <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
258 bits are present in the source file but are not duplicated in the destination file, it is unspecified whether <i>cp</i> writes a
259 diagnostic message to standard error.</p>
260 <p>The order in which the preceding characteristics are duplicated is unspecified. The <i>dest_file</i> shall not be deleted if
261 these characteristics cannot be preserved.</p>
262 </dd>
263 <dt><b>-R</b></dt>
264 <dd>Copy file hierarchies.</dd>
265 </dl>
266 <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.
267 The last option specified shall determine the behavior of the utility.</p>
268 </blockquote>
269 <h4 class="mansect"><a name="tag_20_24_05" id="tag_20_24_05"></a>OPERANDS</h4>
270 <blockquote>
271 <p>The following operands shall be supported:</p>
272 <dl compact>
273 <dd></dd>
274 <dt><i>source_file</i></dt>
275 <dd>A pathname of a file to be copied. If a <i>source_file</i> operand is <tt>'-'</tt>, it shall refer to a file named <b>-</b>;
276 implementations shall not treat it as meaning standard input.</dd>
277 <dt><i>target_file</i></dt>
278 <dd>A pathname of an existing or nonexistent file, used for the output when a single file is copied. If a <i>target_file</i>
279 operand is <tt>'-'</tt>, it shall refer to a file named <b>-</b>; implementations shall not treat it as meaning standard
280 output.</dd>
281 <dt><i>target</i></dt>
282 <dd>A pathname of a directory to contain the copied files.</dd>
283 </dl>
284 </blockquote>
285 <h4 class="mansect"><a name="tag_20_24_06" id="tag_20_24_06"></a>STDIN</h4>
286 <blockquote>
287 <p>The standard input shall be used to read an input line in response to each prompt specified in the STDERR section. Otherwise,
288 the standard input shall not be used.</p>
289 </blockquote>
290 <h4 class="mansect"><a name="tag_20_24_07" id="tag_20_24_07"></a>INPUT FILES</h4>
291 <blockquote>
292 <p>The input files specified as operands may be of any file type.</p>
293 </blockquote>
294 <h4 class="mansect"><a name="tag_20_24_08" id="tag_20_24_08"></a>ENVIRONMENT VARIABLES</h4>
295 <blockquote>
296 <p>The following environment variables shall affect the execution of <i>cp</i>:</p>
297 <dl compact>
298 <dd></dd>
299 <dt><i>LANG</i></dt>
300 <dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href=
301 "../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization
302 variables used to determine the values of locale categories.)</dd>
303 <dt><i>LC_ALL</i></dt>
304 <dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd>
305 <dt><i>LC_COLLATE</i></dt>
306 <dd><br>
307 Determine the locale for the behavior of ranges, equivalence classes, and multi-character collating elements used in the extended
308 regular expression defined for the <b>yesexpr</b> locale keyword in the <i>LC_MESSAGES</i> category.</dd>
309 <dt><i>LC_CTYPE</i></dt>
310 <dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as
311 opposed to multi-byte characters in arguments and input files) and the behavior of character classes used in the extended regular
312 expression defined for the <b>yesexpr</b> locale keyword in the <i>LC_MESSAGES</i> category.</dd>
313 <dt><i>LC_MESSAGES</i></dt>
314 <dd><br>
315 Determine the locale used to process affirmative responses, and the locale used to affect the format and contents of diagnostic
316 messages and prompts written to standard error.</dd>
317 <dt><i>NLSPATH</i></dt>
318 <dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
319 Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border=
320 "0"></dd>
321 </dl>
322 </blockquote>
323 <h4 class="mansect"><a name="tag_20_24_09" id="tag_20_24_09"></a>ASYNCHRONOUS EVENTS</h4>
324 <blockquote>
325 <p>Default.</p>
326 </blockquote>
327 <h4 class="mansect"><a name="tag_20_24_10" id="tag_20_24_10"></a>STDOUT</h4>
328 <blockquote>
329 <p>Not used.</p>
330 </blockquote>
331 <h4 class="mansect"><a name="tag_20_24_11" id="tag_20_24_11"></a>STDERR</h4>
332 <blockquote>
333 <p>A prompt shall be written to standard error under the conditions specified in the DESCRIPTION section. The prompt shall contain
334 the destination pathname, but its format is otherwise unspecified. Otherwise, the standard error shall be used only for diagnostic
335 messages.</p>
336 </blockquote>
337 <h4 class="mansect"><a name="tag_20_24_12" id="tag_20_24_12"></a>OUTPUT FILES</h4>
338 <blockquote>
339 <p>The output files may be of any type.</p>
340 </blockquote>
341 <h4 class="mansect"><a name="tag_20_24_13" id="tag_20_24_13"></a>EXTENDED DESCRIPTION</h4>
342 <blockquote>
343 <p>None.</p>
344 </blockquote>
345 <h4 class="mansect"><a name="tag_20_24_14" id="tag_20_24_14"></a>EXIT STATUS</h4>
346 <blockquote>
347 <p>The following exit values shall be returned:</p>
348 <dl compact>
349 <dd></dd>
350 <dt> 0</dt>
351 <dd>All requested files (excluding files where a non-affirmative response was given to a request for confirmation) were
352 successfully copied.</dd>
353 <dt>>0</dt>
354 <dd>An error occurred.</dd>
355 </dl>
356 </blockquote>
357 <h4 class="mansect"><a name="tag_20_24_15" id="tag_20_24_15"></a>CONSEQUENCES OF ERRORS</h4>
358 <blockquote>
359 <p>If <i>cp</i> is prematurely terminated by a signal or error, files or file hierarchies may be only partially copied and files
360 and directories may have incorrect permissions or access and modification times.</p>
361 </blockquote>
362 <hr>
363 <div class="box"><em>The following sections are informative.</em></div>
364 <h4 class="mansect"><a name="tag_20_24_16" id="tag_20_24_16"></a>APPLICATION USAGE</h4>
365 <blockquote>
366 <p>The set-user-ID and set-group-ID bits are explicitly cleared when files are created. This is to prevent users from creating
367 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
368 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
369 users has execute permission to a set-user-ID program than did previously. In particular, this is a problem for superusers copying
370 users' trees.</p>
371 </blockquote>
372 <h4 class="mansect"><a name="tag_20_24_17" id="tag_20_24_17"></a>EXAMPLES</h4>
373 <blockquote>
374 <p>None.</p>
375 </blockquote>
376 <h4 class="mansect"><a name="tag_20_24_18" id="tag_20_24_18"></a>RATIONALE</h4>
377 <blockquote>
378 <p>The <b>-i</b> option exists on BSD systems, giving applications and users a way to avoid accidentally removing files when
379 copying. Although the 4.3 BSD version does not prompt if the standard input is not a terminal, the standard developers decided that
380 use of <b>-i</b> is a request for interaction, so when the destination path exists, the utility takes instructions from whatever
381 responds on standard input.</p>
382 <p>The exact format of the interactive prompts is unspecified. Only the general nature of the contents of prompts are specified
383 because implementations may desire more descriptive prompts than those used on historical implementations. Therefore, an
384 application using the <b>-i</b> option relies on the system to provide the most suitable dialog directly with the user, based on
385 the behavior specified.</p>
386 <p>The <b>-p</b> option is historical practice on BSD systems, duplicating the time of last data modification and time of last
387 access. This volume of POSIX.1-2024 extends it to preserve the user and group IDs, as well as the file permissions. This
388 requirement has obvious problems in that the directories are almost certainly modified after being copied. This volume of
389 POSIX.1-2024 requires that the modification times be preserved. The statement that the order in which the characteristics are
390 duplicated is unspecified is to permit implementations to provide the maximum amount of security for the user. Implementations
391 should take into account the obvious security issues involved in setting the owner, group, and mode in the wrong order or creating
392 files with an owner, group, or mode different from the final value.</p>
393 <p>It is unspecified whether <i>cp</i> writes diagnostic messages when the user and group IDs cannot be set due to the widespread
394 practice of users using <b>-p</b> to duplicate some portion of the file characteristics, indifferent to the duplication of others.
395 Historic implementations only write diagnostic messages on errors other than [EPERM].</p>
396 <p>Earlier versions of this standard included support for the <b>-r</b> option to copy file hierarchies. The <b>-r</b> option is
397 historical practice on BSD and BSD-derived systems. This option is no longer specified by POSIX.1-2024 but may be present in some
398 implementations. The <b>-R</b> option was added as a close synonym to the <b>-r</b> option, selected for consistency with all other
399 options in this volume of POSIX.1-2024 that do recursive directory descent.</p>
400 <p>The difference between <b>-R</b> and the removed <b>-r</b> option is in the treatment by <i>cp</i> of file types other than
401 regular and directory. It was implementation-defined how the <b>-</b> option treated special files to allow both historical
402 implementations and those that chose to support <b>-r</b> with the same abilities as <b>-R</b> defined by this volume of
403 POSIX.1-2024. The original <b>-r</b> flag, for historic reasons, did not handle special files any differently from regular files,
404 but always read the file and copied its contents. This had obvious problems in the presence of special file types; for example,
405 character devices, FIFOs, and sockets.</p>
406 <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
407 same level in the hierarchy or above the file where the failure occurred. It is unspecified if <i>cp</i> shall attempt to copy
408 files below the file where the failure occurred (which cannot succeed in any case).</p>
409 <p>Permissions, owners, and groups of created special file types have been deliberately left as implementation-defined. This is to
410 allow systems to satisfy special requirements (for example, allowing users to create character special devices, but requiring them
411 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
412 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
413 also probable that additional privileges are required to create block, character, or other implementation-defined special file
414 types.</p>
415 <p>Additionally, the <b>-p</b> option explicitly requires that all set-user-ID and set-group-ID permissions be discarded if any of
416 the owner or group IDs cannot be set. This is to keep users from unintentionally giving away special privilege when copying
417 programs.</p>
418 <p>When creating regular files, historical versions of <i>cp</i> use the mode of the source file as modified by the file mode
419 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
420 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
421 file mode creation mask. In the absence of any strong reason to change historic practice, it was in large part retained.</p>
422 <p>When creating directories, historical versions of <i>cp</i> use the mode of the source directory, plus read, write, and search
423 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
424 read permission, but the owner does not. A side-effect is that if the file creation mask denies the owner permissions, <i>cp</i>
425 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
426 the source directory, unmodified by the file creation mask.</p>
427 <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
428 creation mask. After the copy is done, the permissions are set to be the same as the source directory, as modified by the file
429 creation mask. This latter change from historical behavior is to prevent users from accidentally creating directories with
430 permissions beyond those they would normally set and for consistency with the behavior of <i>cp</i> in creating files.</p>
431 <p>It is not a requirement that <i>cp</i> detect attempts to copy a file to itself; however, implementations are strongly
432 encouraged to do so. Historical implementations have detected the attempt in most cases.</p>
433 <p>There are two methods of copying subtrees in this volume of POSIX.1-2024. The other method is described as part of the <a href=
434 "../utilities/pax.html"><i>pax</i></a> utility (see <a href="../utilities/pax.html#"><i>pax</i></a> ). Both methods are historical
435 practice. The <i>cp</i> utility provides a simpler, more intuitive interface, while <a href="../utilities/pax.html"><i>pax</i></a>
436 offers a finer granularity of control. Each provides additional functionality to the other; in particular, <a href=
437 "../utilities/pax.html"><i>pax</i></a> maintains the hard-link structure of the hierarchy, while <i>cp</i> does not. It is the
438 intention of the standard developers that the results be similar (using appropriate option combinations in both utilities). The
439 results are not required to be identical; there seemed insufficient gain to applications to balance the difficulty of
440 implementations having to guarantee that the results would be exactly identical.</p>
441 <p>The wording allowing <i>cp</i> to copy a directory to implementation-defined file types not specified by the System Interfaces
442 volume of POSIX.1-2024 is provided so that implementations supporting symbolic links are not required to prohibit copying
443 directories to symbolic links. Other extensions to the System Interfaces volume of POSIX.1-2024 file types may need to use this
444 loophole as well.</p>
445 </blockquote>
446 <h4 class="mansect"><a name="tag_20_24_19" id="tag_20_24_19"></a>FUTURE DIRECTIONS</h4>
447 <blockquote>
448 <p>If this utility is directed to create a new directory entry that contains any bytes that have the encoded value of a
449 <newline> character, implementations are encouraged to treat this as an error. A future version of this standard may require
450 implementations to treat this as an error.</p>
451 </blockquote>
452 <h4 class="mansect"><a name="tag_20_24_20" id="tag_20_24_20"></a>SEE ALSO</h4>
453 <blockquote>
454 <p><a href="../utilities/mv.html#"><i>mv</i></a> , <a href="../utilities/find.html#"><i>find</i></a> , <a href=
455 "../utilities/ln.html#"><i>ln</i></a> , <a href="../utilities/pax.html#"><i>pax</i></a></p>
456 <p>XBD <a href="../basedefs/V1_chap04.html#tag_04_07"><i>4.7 File Access Permissions</i></a> , <a href=
457 "../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2
458 Utility Syntax Guidelines</i></a></p>
459 <p>XSH <a href="../functions/open.html#"><i>open</i></a> , <a href="../functions/unlink.html#tag_17_649"><i>unlink</i></a></p>
460 </blockquote>
461 <h4 class="mansect"><a name="tag_20_24_21" id="tag_20_24_21"></a>CHANGE HISTORY</h4>
462 <blockquote>
463 <p>First released in Issue 2.</p>
464 </blockquote>
465 <h4 class="mansect"><a name="tag_20_24_22" id="tag_20_24_22"></a>Issue 6</h4>
466 <blockquote>
467 <p>The <b>-r</b> option is marked obsolescent.</p>
468 <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
469 affect the processing of symbolic links.</p>
470 <p>IEEE PASC Interpretation 1003.2 #194 is applied, adding a description of the <b>-P</b> option.</p>
471 <p>IEEE Std 1003.1-2001/Cor 1-2002, item XCU/TC1/D6/18 is applied, correcting an error in the SEE ALSO section.</p>
472 </blockquote>
473 <h4 class="mansect"><a name="tag_20_24_23" id="tag_20_24_23"></a>Issue 7</h4>
474 <blockquote>
475 <p>Austin Group Interpretation 1003.1-2001 #126 is applied, changing the description of the <i>LC_MESSAGES</i> environment
476 variable.</p>
477 <p>Austin Group Interpretations 1003.1-2001 #092, #164, #165, and #168 are applied.</p>
478 <p>SD5-XCU-ERN-31 and SD5-XCU-ERN-42 are applied, updating the DESCRIPTION.</p>
479 <p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p>
480 <p>SD5-XCU-ERN-102 is applied, clarifying the <b>-i</b> option within the OPTIONS section.</p>
481 <p>The obsolescent <b>-r</b> option is removed.</p>
482 <p>The <b>-P</b> option is added to the SYNOPSIS and to the DESCRIPTION with respect to the <b>-R</b> option.</p>
483 </blockquote>
484 <h4 class="mansect"><a name="tag_20_24_24" id="tag_20_24_24"></a>Issue 8</h4>
485 <blockquote>
486 <p>Austin Group Defect 251 is applied, encouraging implementations to disallow the creation of filenames containing any bytes that
487 have the encoded value of a <newline> character.</p>
488 <p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p>
489 <p>Austin Group Defect 1732 is applied, changing the EXIT STATUS section.</p>
490 </blockquote>
491 <div class="box"><em>End of informative text.</em></div>
492 <hr>
493 <p> </p>
494 <a href="#top"><span class="topOfPage">return to top of page</span></a><br>
495 <hr size="2" noshade>
496 <center><font size="2">UNIX® is a registered Trademark of The Open Group.<br>
497 POSIX™ is a Trademark of The IEEE.<br>
498 Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br>
499 [ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
500 "../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a>
501 ]</font></center>
502 <hr size="2" noshade>
503 <div class="NAVHEADER">
504 <table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0">
505 <tr class="nav">
506 <td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/compress.html" accesskey="P"><<<
507 Previous</a></td>
508 <td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td>
509 <td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/crontab.html" accesskey="N">Next
510 >>></a></td>
511 </tr>
512 </table>
513 <hr align="left" width="100%"></div>
514 </body>
515 </html>