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