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
13 cp — copy files
14
16 cp [−Pfip] source_file target_file
17 cp [−Pfip] source_file... target
19 cp −R [−H|−L|−P] [−fip] source_file... target
21
23 The first synopsis form is denoted by two operands, neither of which
24 are existing files of type directory. The cp utility shall copy the
25 contents of source_file (or, if source_file is a file of type symbolic
26 link, the contents of the file referenced by source_file) to the desti‐
27 nation path named by target_file.
28 The second synopsis form is denoted by two or more operands where the
30 −R option is not specified and the first synopsis form is not applica‐
31 ble. It shall be an error if any source_file is a file of type direc‐
32 tory, if target does not exist, or if target does not name a directory.
33 The cp utility shall copy the contents of each source_file (or, if
34 source_file is a file of type symbolic link, the contents of the file
35 referenced by source_file) to the destination path named by the con‐
36 catenation of target, a single <slash> character if target did not end
37 in a <slash>, and the last component of source_file.
38 The third synopsis form is denoted by two or more operands where the −R
40 option is specified. The cp utility shall copy each file in the file
41 hierarchy rooted in each source_file to a destination path named as
42 follows:
43 * If target exists and names an existing directory, the name of the
45 corresponding destination path for each file in the file hierarchy
46 shall be the concatenation of target, a single <slash> character if
47 target did not end in a <slash>, and the pathname of the file rela‐
48 tive to the directory containing source_file.
49 * If target does not exist and two operands are specified, the name
51 of the corresponding destination path for source_file shall be tar‐
52 get; the name of the corresponding destination path for all other
53 files in the file hierarchy shall be the concatenation of target, a
54 <slash> character, and the pathname of the file relative to
55 source_file.
56 It shall be an error if target does not exist and more than two oper‐
58 ands are specified, or if target exists and does not name a directory.
59 In the following description, the term dest_file refers to the file
61 named by the destination path. The term source_file refers to the file
62 that is being copied, whether specified as an operand or a file in a
63 file hierarchy rooted in a source_file operand. If source_file is a
64 file of type symbolic link:
65 * If the −R option was not specified, cp shall take actions based on
67 the type and contents of the file referenced by the symbolic link,
68 and not by the symbolic link itself, unless the −P option was spec‐
69 ified.
70 * If the −R option was specified:
72 -- If none of the options −H, −L, nor −P were specified, it is
74 unspecified which of −H, −L, or −P will be used as a default.
75 -- If the −H option was specified, cp shall take actions based on
77 the type and contents of the file referenced by any symbolic
78 link specified as a source_file operand.
79 -- If the −L option was specified, cp shall take actions based on
81 the type and contents of the file referenced by any symbolic
82 link specified as a source_file operand or any symbolic links
83 encountered during traversal of a file hierarchy.
84 -- If the −P option was specified, cp shall copy any symbolic link
86 specified as a source_file operand and any symbolic links
87 encountered during traversal of a file hierarchy, and shall not
88 follow any symbolic links.
89 For each source_file, the following steps shall be taken:
91 1. If source_file references the same file as dest_file, cp may write
93 a diagnostic message to standard error; it shall do nothing more
94 with source_file and shall go on to any remaining files.
95 2. If source_file is of type directory, the following steps shall be
97 taken:
98 a. If the −R option was not specified, cp shall write a diagnostic
100 message to standard error, do nothing more with source_file,
101 and go on to any remaining files.
102 b. If source_file was not specified as an operand and source_file
104 is dot or dot-dot, cp shall do nothing more with source_file
105 and go on to any remaining files.
106 c. If dest_file exists and it is a file type not specified by the
108 System Interfaces volume of POSIX.1‐2008, the behavior is
109 implementation-defined.
110 d. If dest_file exists and it is not of type directory, cp shall
112 write a diagnostic message to standard error, do nothing more
113 with source_file or any files below source_file in the file
114 hierarchy, and go on to any remaining files.
115 e. If the directory dest_file does not exist, it shall be created
117 with file permission bits set to the same value as those of
118 source_file, modified by the file creation mask of the user if
119 the −p option was not specified, and then bitwise-inclusively
120 OR'ed with S_IRWXU. If dest_file cannot be created, cp shall
121 write a diagnostic message to standard error, do nothing more
122 with source_file, and go on to any remaining files. It is
123 unspecified if cp attempts to copy files in the file hierarchy
124 rooted in source_file.
125 f. The files in the directory source_file shall be copied to the
127 directory dest_file, taking the four steps (1 to 4) listed here
128 with the files as source_files.
129 g. If dest_file was created, its file permission bits shall be
131 changed (if necessary) to be the same as those of source_file,
132 modified by the file creation mask of the user if the −p option
133 was not specified.
134 h. The cp utility shall do nothing more with source_file and go on
136 to any remaining files.
137 3. If source_file is of type regular file, the following steps shall
139 be taken:
140 a. The behavior is unspecified if dest_file exists and was written
142 by a previous step. Otherwise, if dest_file exists, the follow‐
143 ing steps shall be taken:
144 i. If the −i option is in effect, the cp utility shall write
146 a prompt to the standard error and read a line from the
147 standard input. If the response is not affirmative, cp
148 shall do nothing more with source_file and go on to any
149 remaining files.
150 ii. A file descriptor for dest_file shall be obtained by per‐
152 forming actions equivalent to the open() function defined
153 in the System Interfaces volume of POSIX.1‐2008 called
154 using dest_file as the path argument, and the bitwise-
155 inclusive OR of O_WRONLY and O_TRUNC as the oflag argu‐
156 ment.
157 iii. If the attempt to obtain a file descriptor fails and the
159 −f option is in effect, cp shall attempt to remove the
160 file by performing actions equivalent to the unlink()
161 function defined in the System Interfaces volume of
162 POSIX.1‐2008 called using dest_file as the path argument.
163 If this attempt succeeds, cp shall continue with step 3b.
164 b. If dest_file does not exist, a file descriptor shall be
166 obtained by performing actions equivalent to the open() func‐
167 tion defined in the System Interfaces volume of POSIX.1‐2008
168 called using dest_file as the path argument, and the bitwise-
169 inclusive OR of O_WRONLY and O_CREAT as the oflag argument. The
170 file permission bits of source_file shall be the mode argument.
171 c. If the attempt to obtain a file descriptor fails, cp shall
173 write a diagnostic message to standard error, do nothing more
174 with source_file, and go on to any remaining files.
175 d. The contents of source_file shall be written to the file
177 descriptor. Any write errors shall cause cp to write a diagnos‐
178 tic message to standard error and continue to step 3e.
179 e. The file descriptor shall be closed.
181 f. The cp utility shall do nothing more with source_file. If a
183 write error occurred in step 3d, it is unspecified if cp con‐
184 tinues with any remaining files. If no write error occurred in
185 step 3d, cp shall go on to any remaining files.
186 4. Otherwise, the −R option was specified, and the following steps
188 shall be taken:
189 a. The dest_file shall be created with the same file type as
191 source_file.
192 b. If source_file is a file of type FIFO, the file permission bits
194 shall be the same as those of source_file, modified by the file
195 creation mask of the user if the −p option was not specified.
196 Otherwise, the permissions, owner ID, and group ID of dest_file
197 are implementation-defined.
198 If this creation fails for any reason, cp shall write a diag‐
200 nostic message to standard error, do nothing more with
201 source_file, and go on to any remaining files.
202 c. If source_file is a file of type symbolic link, and the options
204 require the symbolic link itself to be acted upon, the pathname
205 contained in dest_file shall be the same as the pathname con‐
206 tained in source_file.
207 If this fails for any reason, cp shall write a diagnostic mes‐
209 sage to standard error, do nothing more with source_file, and
210 go on to any remaining files.
211 If the implementation provides additional or alternate access control
213 mechanisms (see the Base Definitions volume of POSIX.1‐2008, Section
214 4.4, File Access Permissions), their effect on copies of files is
215 implementation-defined.
216
218 The cp utility shall conform to the Base Definitions volume of
219 POSIX.1‐2008, Section 12.2, Utility Syntax Guidelines.
220 The following options shall be supported:
222 −f If a file descriptor for a destination file cannot be
224 obtained, as described in step 3.a.ii., attempt to unlink the
225 destination file and proceed.
226 −H Take actions based on the type and contents of the file ref‐
228 erenced by any symbolic link specified as a source_file oper‐
229 and.
230 −i Write a prompt to standard error before copying to any exist‐
232 ing non-directory destination file. If the response from the
233 standard input is affirmative, the copy shall be attempted;
234 otherwise, it shall not.
235 −L Take actions based on the type and contents of the file ref‐
237 erenced by any symbolic link specified as a source_file oper‐
238 and or any symbolic links encountered during traversal of a
239 file hierarchy.
240 −P Take actions on any symbolic link specified as a source_file
242 operand or any symbolic link encountered during traversal of
243 a file hierarchy.
244 −p Duplicate the following characteristics of each source file
246 in the corresponding destination file:
247 1. The time of last data modification and time of last
249 access. If this duplication fails for any reason, cp
250 shall write a diagnostic message to standard error.
251 2. The user ID and group ID. If this duplication fails for
253 any reason, it is unspecified whether cp writes a diag‐
254 nostic message to standard error.
255 3. The file permission bits and the S_ISUID and S_ISGID
257 bits. Other, implementation-defined, bits may be dupli‐
258 cated as well. If this duplication fails for any reason,
259 cp shall write a diagnostic message to standard error.
260 If the user ID or the group ID cannot be duplicated, the file
262 permission bits S_ISUID and S_ISGID shall be cleared. If
263 these bits are present in the source file but are not dupli‐
264 cated in the destination file, it is unspecified whether cp
265 writes a diagnostic message to standard error.
266 The order in which the preceding characteristics are dupli‐
268 cated is unspecified. The dest_file shall not be deleted if
269 these characteristics cannot be preserved.
270 −R Copy file hierarchies.
272 Specifying more than one of the mutually-exclusive options −H, −L, and
274 −P shall not be considered an error. The last option specified shall
275 determine the behavior of the utility.
276
278 The following operands shall be supported:
279 source_file
281 A pathname of a file to be copied. If a source_file operand
282 is '−', it shall refer to a file named −; implementations
283 shall not treat it as meaning standard input.
284 target_file
286 A pathname of an existing or nonexistent file, used for the
287 output when a single file is copied. If a target_file operand
288 is '−', it shall refer to a file named −; implementations
289 shall not treat it as meaning standard output.
290 target A pathname of a directory to contain the copied files.
292
294 The standard input shall be used to read an input line in response to
295 each prompt specified in the STDERR section. Otherwise, the standard
296 input shall not be used.
297
299 The input files specified as operands may be of any file type.
300
302 The following environment variables shall affect the execution of cp:
303 LANG Provide a default value for the internationalization vari‐
305 ables that are unset or null. (See the Base Definitions vol‐
306 ume of POSIX.1‐2008, Section 8.2, Internationalization Vari‐
307 ables for the precedence of internationalization variables
308 used to determine the values of locale categories.)
309 LC_ALL If set to a non-empty string value, override the values of
311 all the other internationalization variables.
312 LC_COLLATE
314 Determine the locale for the behavior of ranges, equivalence
315 classes, and multi-character collating elements used in the
316 extended regular expression defined for the yesexpr locale
317 keyword in the LC_MESSAGES category.
318 LC_CTYPE Determine the locale for the interpretation of sequences of
320 bytes of text data as characters (for example, single-byte as
321 opposed to multi-byte characters in arguments and input
322 files) and the behavior of character classes used in the
323 extended regular expression defined for the yesexpr locale
324 keyword in the LC_MESSAGES category.
325 LC_MESSAGES
327 Determine the locale used to process affirmative responses,
328 and the locale used to affect the format and contents of
329 diagnostic messages and prompts written to standard error.
330 NLSPATH Determine the location of message catalogs for the processing
332 of LC_MESSAGES.
333
335 Default.
336
338 Not used.
339
341 A prompt shall be written to standard error under the conditions speci‐
342 fied in the DESCRIPTION section. The prompt shall contain the destina‐
343 tion pathname, but its format is otherwise unspecified. Otherwise, the
344 standard error shall be used only for diagnostic messages.
345
347 The output files may be of any type.
348
350 None.
351
353 The following exit values shall be returned:
354 0 All files were copied successfully.
356 >0 An error occurred.
358
360 If cp is prematurely terminated by a signal or error, files or file
361 hierarchies may be only partially copied and files and directories may
362 have incorrect permissions or access and modification times.
363 The following sections are informative.
365
367 The set-user-ID and set-group-ID bits are explicitly cleared when files
368 are created. This is to prevent users from creating programs that are
369 set-user-ID or set-group-ID to them when copying files or to make set-
370 user-ID or set-group-ID files accessible to new groups of users. For
371 example, if a file is set-user-ID and the copy has a different group ID
372 than the source, a new group of users has execute permission to a set-
373 user-ID program than did previously. In particular, this is a problem
374 for superusers copying users' trees.
375
377 None.
378
380 The −i option exists on BSD systems, giving applications and users a
381 way to avoid accidentally removing files when copying. Although the 4.3
382 BSD version does not prompt if the standard input is not a terminal,
383 the standard developers decided that use of −i is a request for inter‐
384 action, so when the destination path exists, the utility takes instruc‐
385 tions from whatever responds on standard input.
386 The exact format of the interactive prompts is unspecified. Only the
388 general nature of the contents of prompts are specified because imple‐
389 mentations may desire more descriptive prompts than those used on his‐
390 torical implementations. Therefore, an application using the −i option
391 relies on the system to provide the most suitable dialog directly with
392 the user, based on the behavior specified.
393 The −p option is historical practice on BSD systems, duplicating the
395 time of last data modification and time of last access. This volume of
396 POSIX.1‐2008 extends it to preserve the user and group IDs, as well as
397 the file permissions. This requirement has obvious problems in that the
398 directories are almost certainly modified after being copied. This vol‐
399 ume of POSIX.1‐2008 requires that the modification times be preserved.
400 The statement that the order in which the characteristics are dupli‐
401 cated is unspecified is to permit implementations to provide the maxi‐
402 mum amount of security for the user. Implementations should take into
403 account the obvious security issues involved in setting the owner,
404 group, and mode in the wrong order or creating files with an owner,
405 group, or mode different from the final value.
406 It is unspecified whether cp writes diagnostic messages when the user
408 and group IDs cannot be set due to the widespread practice of users
409 using −p to duplicate some portion of the file characteristics, indif‐
410 ferent to the duplication of others. Historic implementations only
411 write diagnostic messages on errors other than [EPERM].
412 Earlier versions of this standard included support for the −r option to
414 copy file hierarchies. The −r option is historical practice on BSD and
415 BSD-derived systems. This option is no longer specified by POSIX.1‐2008
416 but may be present in some implementations. The −R option was added as
417 a close synonym to the −r option, selected for consistency with all
418 other options in this volume of POSIX.1‐2008 that do recursive direc‐
419 tory descent.
420 The difference between −R and the removed −r option is in the treatment
422 by cp of file types other than regular and directory. It was implemen‐
423 tation-defined how the − option treated special files to allow both
424 historical implementations and those that chose to support −r with the
425 same abilities as −R defined by this volume of POSIX.1‐2008. The origi‐
426 nal −r flag, for historic reasons, did not handle special files any
427 differently from regular files, but always read the file and copied its
428 contents. This had obvious problems in the presence of special file
429 types; for example, character devices, FIFOs, and sockets.
430 When a failure occurs during the copying of a file hierarchy, cp is
432 required to attempt to copy files that are on the same level in the
433 hierarchy or above the file where the failure occurred. It is unspeci‐
434 fied if cp shall attempt to copy files below the file where the failure
435 occurred (which cannot succeed in any case).
436 Permissions, owners, and groups of created special file types have been
438 deliberately left as implementation-defined. This is to allow systems
439 to satisfy special requirements (for example, allowing users to create
440 character special devices, but requiring them to be owned by a certain
441 group). In general, it is strongly suggested that the permissions,
442 owner, and group be the same as if the user had run the historical
443 mknod, ln, or other utility to create the file. It is also probable
444 that additional privileges are required to create block, character, or
445 other implementation-defined special file types.
446 Additionally, the −p option explicitly requires that all set-user-ID
448 and set-group-ID permissions be discarded if any of the owner or group
449 IDs cannot be set. This is to keep users from unintentionally giving
450 away special privilege when copying programs.
451 When creating regular files, historical versions of cp use the mode of
453 the source file as modified by the file mode creation mask. Other
454 choices would have been to use the mode of the source file unmodified
455 by the creation mask or to use the same mode as would be given to a new
456 file created by the user (plus the execution bits of the source file)
457 and then modify it by the file mode creation mask. In the absence of
458 any strong reason to change historic practice, it was in large part
459 retained.
460 When creating directories, historical versions of cp use the mode of
462 the source directory, plus read, write, and search bits for the owner,
463 as modified by the file mode creation mask. This is done so that cp can
464 copy trees where the user has read permission, but the owner does not.
465 A side-effect is that if the file creation mask denies the owner per‐
466 missions, cp fails. Also, once the copy is done, historical versions of
467 cp set the permissions on the created directory to be the same as the
468 source directory, unmodified by the file creation mask.
469 This behavior has been modified so that cp is always able to create the
471 contents of the directory, regardless of the file creation mask. After
472 the copy is done, the permissions are set to be the same as the source
473 directory, as modified by the file creation mask. This latter change
474 from historical behavior is to prevent users from accidentally creating
475 directories with permissions beyond those they would normally set and
476 for consistency with the behavior of cp in creating files.
477 It is not a requirement that cp detect attempts to copy a file to
479 itself; however, implementations are strongly encouraged to do so. His‐
480 torical implementations have detected the attempt in most cases.
481 There are two methods of copying subtrees in this volume of
483 POSIX.1‐2008. The other method is described as part of the pax utility
484 (see pax). Both methods are historical practice. The cp utility pro‐
485 vides a simpler, more intuitive interface, while pax offers a finer
486 granularity of control. Each provides additional functionality to the
487 other; in particular, pax maintains the hard-link structure of the
488 hierarchy, while cp does not. It is the intention of the standard
489 developers that the results be similar (using appropriate option combi‐
490 nations in both utilities). The results are not required to be identi‐
491 cal; there seemed insufficient gain to applications to balance the dif‐
492 ficulty of implementations having to guarantee that the results would
493 be exactly identical.
494 The wording allowing cp to copy a directory to implementation-defined
496 file types not specified by the System Interfaces volume of
497 POSIX.1‐2008 is provided so that implementations supporting symbolic
498 links are not required to prohibit copying directories to symbolic
499 links. Other extensions to the System Interfaces volume of POSIX.1‐2008
500 file types may need to use this loophole as well.
501
503 None.
504
506 mv, find, ln, pax
507 The Base Definitions volume of POSIX.1‐2008, Section 4.4, File Access
509 Permissions, Chapter 8, Environment Variables, Section 12.2, Utility
510 Syntax Guidelines
511 The System Interfaces volume of POSIX.1‐2008, open(), unlink()
513
515 Portions of this text are reprinted and reproduced in electronic form
516 from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
517 -- Portable Operating System Interface (POSIX), The Open Group Base
518 Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
519 cal and Electronics Engineers, Inc and The Open Group. (This is
520 POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
521 event of any discrepancy between this version and the original IEEE and
522 The Open Group Standard, the original IEEE and The Open Group Standard
523 is the referee document. The original Standard can be obtained online
524 at http://www.unix.org/online.html .
525 Any typographical or formatting errors that appear in this page are
527 most likely to have been introduced during the conversion of the source
528 files to man page format. To report such errors, see https://www.ker‐
529 nel.org/doc/man-pages/reporting_bugs.html .
530IEEE/The Open Group 2013 CP(1P)