1CP(1P) POSIX Programmer's Manual CP(1P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 cp - copy files
13
15 cp [-fip] source_file target_file
16 cp [-fip] source_file ... target
18 cp -R [-H | -L | -P][-fip] source_file ... target
20 cp -r [-H | -L | -P][-fip] source_file ... target
22
25 The first synopsis form is denoted by two operands, neither of which
26 are existing files of type directory. The cp utility shall copy the
27 contents of source_file (or, if source_file is a file of type symbolic
28 link, the contents of the file referenced by source_file) to the desti‐
29 nation path named by target_file.
30 The second synopsis form is denoted by two or more operands where the
32 -R or -r options are not specified and the first synopsis form is not
33 applicable. It shall be an error if any source_file is a file of type
34 directory, if target does not exist, or if target is a file of a type
35 defined by the System Interfaces volume of IEEE Std 1003.1-2001, but is
36 not a file of type directory. The cp utility shall copy the contents of
37 each source_file (or, if source_file is a file of type symbolic link,
38 the contents of the file referenced by source_file) to the destination
39 path named by the concatenation of target, a slash character, and the
40 last component of source_file.
41 The third and fourth synopsis forms are denoted by two or more operands
43 where the -R or -r options are specified. The cp utility shall copy
44 each file in the file hierarchy rooted in each source_file to a desti‐
45 nation path named as follows:
46 * If target exists and is a file of type directory, the name of the
48 corresponding destination path for each file in the file hierarchy
49 shall be the concatenation of target, a slash character, and the
50 pathname of the file relative to the directory containing
51 source_file.
52 * If target does not exist and two operands are specified, the name of
54 the corresponding destination path for source_file shall be target;
55 the name of the corresponding destination path for all other files
56 in the file hierarchy shall be the concatenation of target, a slash
57 character, and the pathname of the file relative to source_file.
58 It shall be an error if target does not exist and more than two oper‐
60 ands are specified, or if target exists and is a file of a type defined
61 by the System Interfaces volume of IEEE Std 1003.1-2001, but is not a
62 file of type directory.
63 In the following description, the term dest_file refers to the file
65 named by the destination path. The term source_file refers to the file
66 that is being copied, whether specified as an operand or a file in a
67 file hierarchy rooted in a source_file operand. If source_file is a
68 file of type symbolic link:
69 * If neither the -R nor -r options were specified, cp shall take
71 actions based on the type and contents of the file referenced by the
72 symbolic link, and not by the symbolic link itself.
73 * If the -R option was specified:
75 * If none of the options -H, -L, nor -P were specified, it is
77 unspecified which of -H, -L, or -P will be used as a default.
78 * If the -H option was specified, cp shall take actions based on
80 the type and contents of the file referenced by any symbolic link
81 specified as a source_file operand.
82 * If the -L option was specified, cp shall take actions based on
84 the type and contents of the file referenced by any symbolic link
85 specified as a source_file operand or any symbolic links encoun‐
86 tered during traversal of a file hierarchy.
87 * If the -P option was specified, cp shall copy any symbolic link
89 specified as a source_file operand and any symbolic links encoun‐
90 tered during traversal of a file hierarchy, and shall not follow
91 any symbolic links.
92 * If the -r option was specified, the behavior is implementation-
94 defined.
95 For each source_file, the following steps shall be taken:
97 1. If source_file references the same file as dest_file, cp may write
99 a diagnostic message to standard error; it shall do nothing more
100 with source_file and shall go on to any remaining files.
101 2. If source_file is of type directory, the following steps shall be
103 taken:
104 a. If neither the -R or -r options were specified, cp shall write
106 a diagnostic message to standard error, do nothing more with
107 source_file, and go on to any remaining files.
108 b. If source_file was not specified as an operand and source_file
110 is dot or dot-dot, cp shall do nothing more with source_file
111 and go on to any remaining files.
112 c. If dest_file exists and it is a file type not specified by the
114 System Interfaces volume of IEEE Std 1003.1-2001, the behavior
115 is implementation-defined.
116 d. If dest_file exists and it is not of type directory, cp shall
118 write a diagnostic message to standard error, do nothing more
119 with source_file or any files below source_file in the file
120 hierarchy, and go on to any remaining files.
121 e. If the directory dest_file does not exist, it shall be created
123 with file permission bits set to the same value as those of
124 source_file, modified by the file creation mask of the user if
125 the -p option was not specified, and then bitwise-inclusively
126 OR'ed with S_IRWXU. If dest_file cannot be created, cp shall
127 write a diagnostic message to standard error, do nothing more
128 with source_file, and go on to any remaining files. It is
129 unspecified if cp attempts to copy files in the file hierarchy
130 rooted in source_file.
131 f. The files in the directory source_file shall be copied to the
133 directory dest_file, taking the four steps (1 to 4) listed here
134 with the files as source_files.
135 g. If dest_file was created, its file permission bits shall be
137 changed (if necessary) to be the same as those of source_file,
138 modified by the file creation mask of the user if the -p option
139 was not specified.
140 h. The cp utility shall do nothing more with source_file and go on
142 to any remaining files.
143 3. If source_file is of type regular file, the following steps shall
145 be taken:
146 a. If dest_file exists, the following steps shall be taken:
148 i. If the -i option is in effect, the cp utility shall write
150 a prompt to the standard error and read a line from the
151 standard input. If the response is not affirmative, cp
152 shall do nothing more with source_file and go on to any
153 remaining files.
154 ii. A file descriptor for dest_file shall be obtained by per‐
156 forming actions equivalent to the open() function defined
157 in the System Interfaces volume of IEEE Std 1003.1-2001
158 called using dest_file as the path argument, and the bit‐
159 wise-inclusive OR of O_WRONLY and O_TRUNC as the oflag
160 argument.
161 iii. If the attempt to obtain a file descriptor fails and the
163 -f option is in effect, cp shall attempt to remove the
164 file by performing actions equivalent to the unlink()
165 function defined in the System Interfaces volume of
166 IEEE Std 1003.1-2001 called using dest_file as the path
167 argument. If this attempt succeeds, cp shall continue with
168 step 3b.
169 b. If dest_file does not exist, a file descriptor shall be
171 obtained by performing actions equivalent to the open() func‐
172 tion defined in the System Interfaces volume of
173 IEEE Std 1003.1-2001 called using dest_file as the path argu‐
174 ment, and the bitwise-inclusive OR of O_WRONLY and O_CREAT as
175 the oflag argument. The file permission bits of source_file
176 shall be the mode argument.
177 c. If the attempt to obtain a file descriptor fails, cp shall
179 write a diagnostic message to standard error, do nothing more
180 with source_file, and go on to any remaining files.
181 d. The contents of source_file shall be written to the file
183 descriptor. Any write errors shall cause cp to write a diag‐
184 nostic message to standard error and continue to step 3e.
185 e. The file descriptor shall be closed.
187 f. The cp utility shall do nothing more with source_file. If a
189 write error occurred in step 3d, it is unspecified if cp con‐
190 tinues with any remaining files. If no write error occurred in
191 step 3d, cp shall go on to any remaining files.
192 4. Otherwise, the following steps shall be taken:
194 a. If the -r option was specified, the behavior is implementation-
196 defined.
197 b. If the -R option was specified, the following steps shall be
199 taken:
200 i. The dest_file shall be created with the same file type as
202 source_file.
203 ii. If source_file is a file of type FIFO, the file permission
205 bits shall be the same as those of source_file, modified
206 by the file creation mask of the user if the -p option was
207 not specified. Otherwise, the permissions, owner ID, and
208 group ID of dest_file are implementation-defined.
209 If this creation fails for any reason, cp shall write a diag‐
211 nostic message to standard error, do nothing more with
212 source_file, and go on to any remaining files.
213 iii. If source_file is a file of type symbolic link, the path‐
215 name contained in dest_file shall be the same as the path‐
216 name contained in source_file.
217 If this fails for any reason, cp shall write a diagnostic mes‐
219 sage to standard error, do nothing more with source_file, and
220 go on to any remaining files.
221 If the implementation provides additional or alternate access control
223 mechanisms (see the Base Definitions volume of IEEE Std 1003.1-2001,
224 Section 4.4, File Access Permissions), their effect on copies of files
225 is implementation-defined.
226
228 The cp utility shall conform to the Base Definitions volume of
229 IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
230 The following options shall be supported:
232 -f If a file descriptor for a destination file cannot be obtained,
234 as described in step 3.a.ii., attempt to unlink the destination
235 file and proceed.
236 -H Take actions based on the type and contents of the file refer‐
238 enced by any symbolic link specified as a source_file operand.
239 -i Write a prompt to standard error before copying to any existing
241 destination file. If the response from the standard input is
242 affirmative, the copy shall be attempted; otherwise, it shall
243 not.
244 -L Take actions based on the type and contents of the file refer‐
246 enced by any symbolic link specified as a source_file operand or
247 any symbolic links encountered during traversal of a file hier‐
248 archy.
249 -P Take actions on any symbolic link specified as a source_file op‐
251 erand or any symbolic link encountered during traversal of a
252 file hierarchy.
253 -p Duplicate the following characteristics of each source file in
255 the corresponding destination file:
256 1. The time of last data modification and time of last access.
258 If this duplication fails for any reason, cp shall write a
259 diagnostic message to standard error.
260 2. The user ID and group ID. If this duplication fails for any
262 reason, it is unspecified whether cp writes a diagnostic
263 message to standard error.
264 3. The file permission bits and the S_ISUID and S_ISGID bits.
266 Other, implementation-defined, bits may be duplicated as
267 well. If this duplication fails for any reason, cp shall
268 write a diagnostic message to standard error.
269 If the user ID or the group ID cannot be duplicated, the file permis‐
271 sion bits S_ISUID and S_ISGID shall be cleared. If these bits are
272 present in the source file but are not duplicated in the destination
273 file, it is unspecified whether cp writes a diagnostic message to stan‐
274 dard error.
275 The order in which the preceding characteristics are duplicated is
277 unspecified. The dest_file shall not be deleted if these characteris‐
278 tics cannot be preserved.
279 -R Copy file hierarchies.
281 -r Copy file hierarchies. The treatment of special files is imple‐
283 mentation-defined.
284 Specifying more than one of the mutually-exclusive options -H, -L, and
287 -P shall not be considered an error. The last option specified shall
288 determine the behavior of the utility.
289
291 The following operands shall be supported:
292 source_file
294 A pathname of a file to be copied.
295 target_file
297 A pathname of an existing or nonexistent file, used for the out‐
298 put when a single file is copied.
299 target A pathname of a directory to contain the copied files.
301
304 The standard input shall be used to read an input line in response to
305 each prompt specified in the STDERR section. Otherwise, the standard
306 input shall not be used.
307
309 The input files specified as operands may be of any file type.
310
312 The following environment variables shall affect the execution of cp:
313 LANG Provide a default value for the internationalization variables
315 that are unset or null. (See the Base Definitions volume of
316 IEEE Std 1003.1-2001, Section 8.2, Internationalization Vari‐
317 ables for the precedence of internationalization variables used
318 to determine the values of locale categories.)
319 LC_ALL If set to a non-empty string value, override the values of all
321 the other internationalization variables.
322 LC_COLLATE
324 Determine the locale for the behavior of ranges, equivalence
326 classes, and multi-character collating elements used in the
327 extended regular expression defined for the yesexpr locale key‐
328 word in the LC_MESSAGES category.
329 LC_CTYPE
331 Determine the locale for the interpretation of sequences of
332 bytes of text data as characters (for example, single-byte as
333 opposed to multi-byte characters in arguments and input files)
334 and the behavior of character classes used in the extended regu‐
335 lar expression defined for the yesexpr locale keyword in the
336 LC_MESSAGES category.
337 LC_MESSAGES
339 Determine the locale for the processing of affirmative responses
340 that should be used to affect the format and contents of diag‐
341 nostic messages written to standard error.
342 NLSPATH
344 Determine the location of message catalogs for the processing of
345 LC_MESSAGES .
346
349 Default.
350
352 Not used.
353
355 A prompt shall be written to standard error under the conditions speci‐
356 fied in the DESCRIPTION section. The prompt shall contain the destina‐
357 tion pathname, but its format is otherwise unspecified. Otherwise, the
358 standard error shall be used only for diagnostic messages.
359
361 The output files may be of any type.
362
364 None.
365
367 The following exit values shall be returned:
368 0 All files were copied successfully.
370 >0 An error occurred.
372
375 If cp is prematurely terminated by a signal or error, files or file
376 hierarchies may be only partially copied and files and directories may
377 have incorrect permissions or access and modification times.
378 The following sections are informative.
380
382 The difference between -R and -r is in the treatment by cp of file
383 types other than regular and directory. The original -r flag, for his‐
384 toric reasons, does not handle special files any differently from regu‐
385 lar files, but always reads the file and copies its contents. This has
386 obvious problems in the presence of special file types; for example,
387 character devices, FIFOs, and sockets. The -R option is intended to
388 recreate the file hierarchy and the -r option supports historical prac‐
389 tice. It was anticipated that a future version of this volume of
390 IEEE Std 1003.1-2001 would deprecate the -r option, and for that rea‐
391 son, there has been no attempt to fix its behavior with respect to
392 FIFOs or other file types where copying the file is clearly wrong. How‐
393 ever, some implementations support -r with the same abilities as the -R
394 defined in this volume of IEEE Std 1003.1-2001. To accommodate them as
395 well as systems that do not, the differences between -r and -R are
396 implementation-defined. Implementations may make them identical. The -r
397 option is marked obsolescent.
398 The set-user-ID and set-group-ID bits are explicitly cleared when files
400 are created. This is to prevent users from creating programs that are
401 set-user-ID or set-group-ID to them when copying files or to make set-
402 user-ID or set-group-ID files accessible to new groups of users. For
403 example, if a file is set-user-ID and the copy has a different group ID
404 than the source, a new group of users has execute permission to a set-
405 user-ID program than did previously. In particular, this is a problem
406 for superusers copying users' trees.
407
409 None.
410
412 The -i option exists on BSD systems, giving applications and users a
413 way to avoid accidentally removing files when copying. Although the 4.3
414 BSD version does not prompt if the standard input is not a terminal,
415 the standard developers decided that use of -i is a request for inter‐
416 action, so when the destination path exists, the utility takes instruc‐
417 tions from whatever responds on standard input.
418 The exact format of the interactive prompts is unspecified. Only the
420 general nature of the contents of prompts are specified because imple‐
421 mentations may desire more descriptive prompts than those used on his‐
422 torical implementations. Therefore, an application using the -i option
423 relies on the system to provide the most suitable dialog directly with
424 the user, based on the behavior specified.
425 The -p option is historical practice on BSD systems, duplicating the
427 time of last data modification and time of last access. This volume of
428 IEEE Std 1003.1-2001 extends it to preserve the user and group IDs, as
429 well as the file permissions. This requirement has obvious problems in
430 that the directories are almost certainly modified after being copied.
431 This volume of IEEE Std 1003.1-2001 requires that the modification
432 times be preserved. The statement that the order in which the charac‐
433 teristics are duplicated is unspecified is to permit implementations to
434 provide the maximum amount of security for the user. Implementations
435 should take into account the obvious security issues involved in set‐
436 ting the owner, group, and mode in the wrong order or creating files
437 with an owner, group, or mode different from the final value.
438 It is unspecified whether cp writes diagnostic messages when the user
440 and group IDs cannot be set due to the widespread practice of users
441 using -p to duplicate some portion of the file characteristics, indif‐
442 ferent to the duplication of others. Historic implementations only
443 write diagnostic messages on errors other than [EPERM].
444 The -r option is historical practice on BSD and BSD-derived systems,
446 copying file hierarchies as opposed to single files. This functional‐
447 ity is used heavily in historical applications, and its loss would sig‐
448 nificantly decrease consensus. The -R option was added as a close syn‐
449 onym to the -r option, selected for consistency with all other options
450 in this volume of IEEE Std 1003.1-2001 that do recursive directory
451 descent.
452 When a failure occurs during the copying of a file hierarchy, cp is
454 required to attempt to copy files that are on the same level in the
455 hierarchy or above the file where the failure occurred. It is unspeci‐
456 fied if cp shall attempt to copy files below the file where the failure
457 occurred (which cannot succeed in any case).
458 Permissions, owners, and groups of created special file types have been
460 deliberately left as implementation-defined. This is to allow systems
461 to satisfy special requirements (for example, allowing users to create
462 character special devices, but requiring them to be owned by a certain
463 group). In general, it is strongly suggested that the permissions,
464 owner, and group be the same as if the user had run the historical
465 mknod, ln, or other utility to create the file. It is also probable
466 that additional privileges are required to create block, character, or
467 other implementation-defined special file types.
468 Additionally, the -p option explicitly requires that all set-user-ID
470 and set-group-ID permissions be discarded if any of the owner or group
471 IDs cannot be set. This is to keep users from unintentionally giving
472 away special privilege when copying programs.
473 When creating regular files, historical versions of cp use the mode of
475 the source file as modified by the file mode creation mask. Other
476 choices would have been to use the mode of the source file unmodified
477 by the creation mask or to use the same mode as would be given to a new
478 file created by the user (plus the execution bits of the source file)
479 and then modify it by the file mode creation mask. In the absence of
480 any strong reason to change historic practice, it was in large part
481 retained.
482 When creating directories, historical versions of cp use the mode of
484 the source directory, plus read, write, and search bits for the owner,
485 as modified by the file mode creation mask. This is done so that cp can
486 copy trees where the user has read permission, but the owner does not.
487 A side effect is that if the file creation mask denies the owner per‐
488 missions, cp fails. Also, once the copy is done, historical versions of
489 cp set the permissions on the created directory to be the same as the
490 source directory, unmodified by the file creation mask.
491 This behavior has been modified so that cp is always able to create the
493 contents of the directory, regardless of the file creation mask. After
494 the copy is done, the permissions are set to be the same as the source
495 directory, as modified by the file creation mask. This latter change
496 from historical behavior is to prevent users from accidentally creating
497 directories with permissions beyond those they would normally set and
498 for consistency with the behavior of cp in creating files.
499 It is not a requirement that cp detect attempts to copy a file to
501 itself; however, implementations are strongly encouraged to do so. His‐
502 torical implementations have detected the attempt in most cases.
503 There are two methods of copying subtrees in this volume of
505 IEEE Std 1003.1-2001. The other method is described as part of the pax
506 utility (see pax ). Both methods are historical practice. The cp util‐
507 ity provides a simpler, more intuitive interface, while pax offers a
508 finer granularity of control. Each provides additional functionality to
509 the other; in particular, pax maintains the hard-link structure of the
510 hierarchy, while cp does not. It is the intention of the standard
511 developers that the results be similar (using appropriate option combi‐
512 nations in both utilities). The results are not required to be identi‐
513 cal; there seemed insufficient gain to applications to balance the dif‐
514 ficulty of implementations having to guarantee that the results would
515 be exactly identical.
516 The wording allowing cp to copy a directory to implementation-defined
518 file types not specified by the System Interfaces volume of
519 IEEE Std 1003.1-2001 is provided so that implementations supporting
520 symbolic links are not required to prohibit copying directories to sym‐
521 bolic links. Other extensions to the System Interfaces volume of
522 IEEE Std 1003.1-2001 file types may need to use this loophole as well.
523
525 The -r option may be removed; use -R instead.
526
528 mv, find, ln, pax, the System Interfaces volume of
529 IEEE Std 1003.1-2001, open(), unlink()
530
532 Portions of this text are reprinted and reproduced in electronic form
533 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
534 -- Portable Operating System Interface (POSIX), The Open Group Base
535 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
536 Electrical and Electronics Engineers, Inc and The Open Group. In the
537 event of any discrepancy between this version and the original IEEE and
538 The Open Group Standard, the original IEEE and The Open Group Standard
539 is the referee document. The original Standard can be obtained online
540 at http://www.opengroup.org/unix/online.html .
541IEEE/The Open Group 2003 CP(1P)