1CP(1P)                     POSIX Programmer's Manual                    CP(1P)
2
3
4

PROLOG

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

NAME

12       cp — copy files
13

SYNOPSIS

15       cp [-Pfip] source_file target_file
16
17       cp [-Pfip] source_file... target
18
19       cp -R [-H|-L|-P] [-fip] source_file... target
20

DESCRIPTION

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
28       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
38       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
43        *  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
49        *  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
56       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
59       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
65        *  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
70        *  If the -R option was specified:
71
72           --  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
75           --  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
79           --  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
84           --  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
89       For each source_file, the following steps shall be taken:
90
91        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
95        2. If  source_file  is of type directory, the following steps shall be
96           taken:
97
98            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
102            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
106            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
110            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
115            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
125            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
129            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
134            h. The cp utility shall do nothing more with source_file and go on
135               to any remaining files.
136
137        3. If  source_file  is of type regular file, the following steps shall
138           be taken:
139
140            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
144                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
150               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
157               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
164            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
171            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
175            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
179            e. The file descriptor shall be closed.
180
181            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
186        4. Otherwise, the -R option was specified,  and  the  following  steps
187           shall be taken:
188
189            a. The  dest_file  shall  be  created  with  the same file type as
190               source_file.
191
192            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
198               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
202            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
207               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
211       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

OPTIONS

217       The cp  utility  shall  conform  to  the  Base  Definitions  volume  of
218       POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines.
219
220       The following options shall be supported:
221
222       -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
226       -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
230       -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
235       -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
240       -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
244       -p        Duplicate  the  following characteristics of each source file
245                 in the corresponding destination file:
246
247                  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
251                  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
255                  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
260                 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
266                 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
270       -R        Copy file hierarchies.
271
272       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

OPERANDS

277       The following operands shall be supported:
278
279       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
284       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
290       target    A pathname of a directory to contain the copied files.
291

STDIN

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

INPUT FILES

298       The input files specified as operands may be of any file type.
299

ENVIRONMENT VARIABLES

301       The following environment variables shall affect the execution of cp:
302
303       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
309       LC_ALL    If set to a non-empty string value, override  the  values  of
310                 all the other internationalization variables.
311
312       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
318       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
325       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
330       NLSPATH   Determine the location of message catalogs for the processing
331                 of LC_MESSAGES.
332

ASYNCHRONOUS EVENTS

334       Default.
335

STDOUT

337       Not used.
338

STDERR

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

OUTPUT FILES

346       The output files may be of any type.
347

EXTENDED DESCRIPTION

349       None.
350

EXIT STATUS

352       The following exit values shall be returned:
353
354        0    All files were copied successfully.
355
356       >0    An error occurred.
357

CONSEQUENCES OF ERRORS

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
363       The following sections are informative.
364

APPLICATION USAGE

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

EXAMPLES

376       None.
377

RATIONALE

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
386       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
393       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
406       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
412       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
420       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
430       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
436       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
446       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
451       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
460       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
469       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
477       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
481       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
494       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

FUTURE DIRECTIONS

502       None.
503

SEE ALSO

505       mv, find, ln, pax
506
507       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
511       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
524       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 .
528
529
530
531IEEE/The Open Group                  2017                               CP(1P)
Impressum