1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
|
cp(P) cp(P)
NAME
cp - copy files
SYNOPSIS
cp [-fip] source_file target_file
cp [-fip] source_file ... target
cp -R [-H | -L | -P][-fip] source_file ... target
cp -r [-H | -L | -P][-fip] source_file ... target
DESCRIPTION
The first synopsis form is denoted by two operands, nei-
ther of which are existing files of type directory. The
cp utility shall copy the contents of source_file (or,
if source_file is a file of type symbolic link, the con-
tents of the file referenced by source_file) to the des-
tination path named by target_file.
The second synopsis form is denoted by two or more oper-
ands where the -R or -r options are not specified and
the first synopsis form is not applicable. It shall be
an error if any source_file is a file of type directory,
if target does not exist, or if target is a file of a
type defined by the System Interfaces volume of
IEEE Std 1003.1-2001, but is not a file of type direc-
tory. The cp utility shall copy the contents of each
source_file (or, if source_file is a file of type sym-
bolic link, the contents of the file referenced by
source_file) to the destination path named by the con-
catenation of target, a slash character, and the last
component of source_file.
The third and fourth synopsis forms are denoted by two
or more operands where the -R or -r options are speci-
fied. The cp utility shall copy each file in the file
hierarchy rooted in each source_file to a destination
path named as follows:
If target exists and is a file of type directory,
the name of the corresponding destination path
for each file in the file hierarchy shall be the
concatenation of target, a slash character, and
the pathname of the file relative to the direc-
tory containing source_file.
If target does not exist and two operands are
specified, the name of the corresponding destina-
tion path for source_file shall be target; the
name of the corresponding destination path for
all other files in the file hierarchy shall be
the concatenation of target, a slash character,
and the pathname of the file relative to
source_file.
It shall be an error if target does not exist and more
than two operands are specified, or if target exists and
is a file of a type defined by the System Interfaces
volume of IEEE Std 1003.1-2001, but is not a file of
type directory.
In the following description, the term dest_file refers
to the file named by the destination path. The term
source_file refers to the file that is being copied,
whether specified as an operand or a file in a file
hierarchy rooted in a source_file operand. If
source_file is a file of type symbolic link:
If neither the -R nor -r options were specified,
cp shall take actions based on the type and con-
tents of the file referenced by the symbolic
link, and not by the symbolic link itself.
If the -R option was specified:
If none of the options -H, -L, nor -P were
specified, it is unspecified which of -H,
-L, or -P will be used as a default.
If the -H option was specified, cp shall
take actions based on the type and con-
tents of the file referenced by any sym-
bolic link specified as a source_file op-
erand.
If the -L option was specified, cp shall
take actions based on the type and con-
tents of the file referenced by any sym-
bolic link specified as a source_file op-
erand or any symbolic links encountered
during traversal of a file hierarchy.
If the -P option was specified, cp shall
copy any symbolic link specified as a
source_file operand and any symbolic links
encountered during traversal of a file
hierarchy, and shall not follow any sym-
bolic links.
If the -r option was specified, the behavior is
implementation-defined.
For each source_file, the following steps shall be
taken:
If source_file references the same file as dest_file, cp
may write a diagnostic message to standard error; it
shall do nothing more with source_file and shall go on
to any remaining files.
If source_file is of type directory, the following steps
shall be taken: <ol type="a">
If neither the -R or -r options were specified, cp shall
write a diagnostic message to standard error, do nothing
more with source_file, and go on to any remaining files.
If source_file was not specified as an operand and
source_file is dot or dot-dot, cp shall do nothing more
with source_file and go on to any remaining files.
If dest_file exists and it is a file type not specified
by the System Interfaces volume of IEEE Std 1003.1-2001,
the behavior is implementation-defined.
If dest_file exists and it is not of type directory, cp
shall write a diagnostic message to standard error, do
nothing more with source_file or any files below
source_file in the file hierarchy, and go on to any
remaining files.
If the directory dest_file does not exist, it shall be
created with file permission bits set to the same value
as those of source_file, modified by the file creation
mask of the user if the -p option was not specified, and
then bitwise-inclusively OR'ed with S_IRWXU. If
dest_file cannot be created, cp shall write a diagnostic
message to standard error, do nothing more with
source_file, and go on to any remaining files. It is
unspecified if cp attempts to copy files in the file
hierarchy rooted in source_file.
The files in the directory source_file shall be copied
to the directory dest_file, taking the four steps (1 to
4) listed here with the files as source_files.
If dest_file was created, its file permission bits shall
be changed (if necessary) to be the same as those of
source_file, modified by the file creation mask of the
user if the -p option was not specified.
The cp utility shall do nothing more with source_file
and go on to any remaining files.
If source_file is of type regular file, the following
steps shall be taken: <ol type="a">
If dest_file exists, the following steps shall be taken:
<ol type="i">
If the -i option is in effect, the cp utility shall
write a prompt to the standard error and read a line
from the standard input. If the response is not affirma-
tive, cp shall do nothing more with source_file and go
on to any remaining files.
A file descriptor for dest_file shall be obtained by
performing actions equivalent to the open() function
defined in the System Interfaces volume of
IEEE Std 1003.1-2001 called using dest_file as the path
argument, and the bitwise-inclusive OR of O_WRONLY and
O_TRUNC as the oflag argument.
If the attempt to obtain a file descriptor fails and the
-f option is in effect, cp shall attempt to remove the
file by performing actions equivalent to the unlink()
function defined in the System Interfaces volume of
IEEE Std 1003.1-2001 called using dest_file as the path
argument. If this attempt succeeds, cp shall continue
with step 3b.
If dest_file does not exist, a file descriptor shall be
obtained by performing actions equivalent to the open()
function defined in the System Interfaces volume of
IEEE Std 1003.1-2001 called using dest_file as the path
argument, and the bitwise-inclusive OR of O_WRONLY and
O_CREAT as the oflag argument. The file permission bits
of source_file shall be the mode argument.
If the attempt to obtain a file descriptor fails, cp
shall write a diagnostic message to standard error, do
nothing more with source_file, and go on to any remain-
ing files.
The contents of source_file shall be written to the file
descriptor. Any write errors shall cause cp to write a
diagnostic message to standard error and continue to
step 3e.
The file descriptor shall be closed.
The cp utility shall do nothing more with source_file.
If a write error occurred in step 3d, it is unspecified
if cp continues with any remaining files. If no write
error occurred in step 3d, cp shall go on to any remain-
ing files.
Otherwise, the following steps shall be taken: <ol
type="a">
If the -r option was specified, the behavior is imple-
mentation-defined.
If the -R option was specified, the following steps
shall be taken: <ol type="i">
The dest_file shall be created with the same file type
as source_file.
If source_file is a file of type FIFO, the file permis-
sion bits shall be the same as those of source_file,
modified by the file creation mask of the user if the -p
option was not specified. Otherwise, the permissions,
owner ID, and group ID of dest_file are implementation-
defined.
If this creation fails for any reason, cp shall write a
diagnostic message to standard error, do nothing more
with source_file, and go on to any remaining files.
If source_file is a file of type symbolic link, the
pathname contained in dest_file shall be the same as the
pathname contained in source_file.
If this fails for any reason, cp shall write a diagnos-
tic message to standard error, do nothing more with
source_file, and go on to any remaining files.
If the implementation provides additional or alternate
access control mechanisms (see the Base Definitions vol-
ume of IEEE Std 1003.1-2001, Section 4.4, File Access
Permissions), their effect on copies of files is imple-
mentation-defined.
OPTIONS
The cp utility shall conform to the Base Definitions
volume of IEEE Std 1003.1-2001, Section 12.2, Utility
Syntax Guidelines.
The following options shall be supported:
-f If a file descriptor for a destination file can-
not be obtained, as described in step 3.a.ii.,
attempt to unlink the destination file and pro-
ceed.
-H Take actions based on the type and contents of
the file referenced by any symbolic link speci-
fied as a source_file operand.
-i Write a prompt to standard error before copying
to any existing destination file. If the response
from the standard input is affirmative, the copy
shall be attempted; otherwise, it shall not.
-L Take actions based on the type and contents of
the file referenced by any symbolic link speci-
fied as a source_file operand or any symbolic
links encountered during traversal of a file
hierarchy.
-P Take actions on any symbolic link specified as a
source_file operand or any symbolic link encoun-
tered during traversal of a file hierarchy.
-p Duplicate the following characteristics of each
source file in the corresponding destination
file:
The time of last data modification and time of last
access. If this duplication fails for any reason, cp
shall write a diagnostic message to standard error.
The user ID and group ID. If this duplication fails for
any reason, it is unspecified whether cp writes a diag-
nostic message to standard error.
The file permission bits and the S_ISUID and S_ISGID
bits. Other, implementation-defined, bits may be dupli-
cated as well. If this duplication fails for any reason,
cp shall write a diagnostic message to standard error.
If the user ID or the group ID cannot be duplicated, the
file permission bits S_ISUID and S_ISGID shall be
cleared. If these bits are present in the source file
but are not duplicated in the destination file, it is
unspecified whether cp writes a diagnostic message to
standard error.
The order in which the preceding characteristics are
duplicated is unspecified. The dest_file shall not be
deleted if these characteristics cannot be preserved.
-R Copy file hierarchies.
-r Copy file hierarchies. The treatment of special
files is implementation-defined.
Specifying more than one of the mutually-exclusive
options -H, -L, and -P shall not be considered an error.
The last option specified shall determine the behavior
of the utility.
OPERANDS
The following operands shall be supported:
source_file
A pathname of a file to be copied.
target_file
A pathname of an existing or nonexistent file,
used for the output when a single file is copied.
target A pathname of a directory to contain the copied
files.
STDIN
The standard input shall be used to read an input line
in response to each prompt specified in the STDERR sec-
tion. Otherwise, the standard input shall not be used.
INPUT FILES
The input files specified as operands may be of any file
type.
ENVIRONMENT VARIABLES
The following environment variables shall affect the
execution of cp:
LANG Provide a default value for the
internationalization variables that are unset or
null. (See the Base Definitions volume of
IEEE Std 1003.1-2001, Section 8.2, International-
ization Variables for the precedence of interna-
tionalization variables used to determine the
values of locale categories.)
LC_ALL If set to a non-empty string value, override the
values of all the other internationalization
variables.
LC_COLLATE
Determine the locale for the behavior of ranges,
equivalence classes, and multi-character collat-
ing elements used in the extended regular expres-
sion defined for the yesexpr locale keyword in
the LC_MESSAGES category.
LC_CTYPE
Determine the locale for the interpretation of
sequences of bytes of text data as characters
(for example, single-byte as opposed to multi-
byte characters in arguments and input files) and
the behavior of character classes used in the
extended regular expression defined for the
yesexpr locale keyword in the LC_MESSAGES cate-
gory.
LC_MESSAGES
Determine the locale for the processing of affir-
mative responses that should be used to affect
the format and contents of diagnostic messages
written to standard error.
NLSPATH
Determine the location of message catalogs for
the processing of LC_MESSAGES .
ASYNCHRONOUS EVENTS
Default.
STDOUT
Not used.
STDERR
A prompt shall be written to standard error under the
conditions specified in the DESCRIPTION section. The
prompt shall contain the destination pathname, but its
format is otherwise unspecified. Otherwise, the stan-
dard error shall be used only for diagnostic messages.
OUTPUT FILES
The output files may be of any type.
EXTENDED DESCRIPTION
None.
EXIT STATUS
The following exit values shall be returned:
0 All files were copied successfully.
>0 An error occurred.
CONSEQUENCES OF ERRORS
If cp is prematurely terminated by a signal or error,
files or file hierarchies may be only partially copied
and files and directories may have incorrect permissions
or access and modification times.
The following sections are informative.
APPLICATION USAGE
The difference between -R and -r is in the treatment by
cp of file types other than regular and directory. The
original -r flag, for historic reasons, does not handle
special files any differently from regular files, but
always reads the file and copies its contents. This has
obvious problems in the presence of special file types;
for example, character devices, FIFOs, and sockets. The
-R option is intended to recreate the file hierarchy and
the -r option supports historical practice. It was
anticipated that a future version of this volume of
IEEE Std 1003.1-2001 would deprecate the -r option, and
for that reason, there has been no attempt to fix its
behavior with respect to FIFOs or other file types where
copying the file is clearly wrong. However, some imple-
mentations support -r with the same abilities as the -R
defined in this volume of IEEE Std 1003.1-2001. To
accommodate them as well as systems that do not, the
differences between -r and -R are implementation-
defined. Implementations may make them identical. The -r
option is marked obsolescent.
The set-user-ID and set-group-ID bits are explicitly
cleared when files are created. This is to prevent users
from creating programs that are set-user-ID or set-
group-ID to them when copying files or to make set-user-
ID or set-group-ID files accessible to new groups of
users. For example, if a file is set-user-ID and the
copy has a different group ID than the source, a new
group of users has execute permission to a set-user-ID
program than did previously. In particular, this is a
problem for superusers copying users' trees.
EXAMPLES
None.
RATIONALE
The -i option exists on BSD systems, giving applications
and users a way to avoid accidentally removing files
when copying. Although the 4.3 BSD version does not
prompt if the standard input is not a terminal, the
standard developers decided that use of -i is a request
for interaction, so when the destination path exists,
the utility takes instructions from whatever responds on
standard input.
The exact format of the interactive prompts is unspeci-
fied. Only the general nature of the contents of prompts
are specified because implementations may desire more
descriptive prompts than those used on historical imple-
mentations. Therefore, an application using the -i
option relies on the system to provide the most suitable
dialog directly with the user, based on the behavior
specified.
The -p option is historical practice on BSD systems,
duplicating the time of last data modification and time
of last access. This volume of IEEE Std 1003.1-2001
extends it to preserve the user and group IDs, as well
as the file permissions. This requirement has obvious
problems in that the directories are almost certainly
modified after being copied. This volume of
IEEE Std 1003.1-2001 requires that the modification
times be preserved. The statement that the order in
which the characteristics are duplicated is unspecified
is to permit implementations to provide the maximum
amount of security for the user. Implementations should
take into account the obvious security issues involved
in setting the owner, group, and mode in the wrong order
or creating files with an owner, group, or mode differ-
ent from the final value.
It is unspecified whether cp writes diagnostic messages
when the user and group IDs cannot be set due to the
widespread practice of users using -p to duplicate some
portion of the file characteristics, indifferent to the
duplication of others. Historic implementations only
write diagnostic messages on errors other than [EPERM].
The -r option is historical practice on BSD and BSD-
derived systems, copying file hierarchies as opposed to
single files. This functionality is used heavily in
historical applications, and its loss would signifi-
cantly decrease consensus. The -R option was added as a
close synonym to the -r option, selected for consistency
with all other options in this volume of
IEEE Std 1003.1-2001 that do recursive directory
descent.
When a failure occurs during the copying of a file hier-
archy, cp is required to attempt to copy files that are
on the same level in the hierarchy or above the file
where the failure occurred. It is unspecified if cp
shall attempt to copy files below the file where the
failure occurred (which cannot succeed in any case).
Permissions, owners, and groups of created special file
types have been deliberately left as implementation-
defined. This is to allow systems to satisfy special
requirements (for example, allowing users to create
character special devices, but requiring them to be
owned by a certain group). In general, it is strongly
suggested that the permissions, owner, and group be the
same as if the user had run the historical mknod, ln, or
other utility to create the file. It is also probable
that additional privileges are required to create block,
character, or other implementation-defined special file
types.
Additionally, the -p option explicitly requires that all
set-user-ID and set-group-ID permissions be discarded if
any of the owner or group IDs cannot be set. This is to
keep users from unintentionally giving away special
privilege when copying programs.
When creating regular files, historical versions of cp
use the mode of the source file as modified by the file
mode creation mask. Other choices would have been to use
the mode of the source file unmodified by the creation
mask or to use the same mode as would be given to a new
file created by the user (plus the execution bits of the
source file) and then modify it by the file mode cre-
ation mask. In the absence of any strong reason to
change historic practice, it was in large part retained.
When creating directories, historical versions of cp use
the mode of the source directory, plus read, write, and
search bits for the owner, as modified by the file mode
creation mask. This is done so that cp can copy trees
where the user has read permission, but the owner does
not. A side effect is that if the file creation mask
denies the owner permissions, cp fails. Also, once the
copy is done, historical versions of cp set the permis-
sions on the created directory to be the same as the
source directory, unmodified by the file creation mask.
This behavior has been modified so that cp is always
able to create the contents of the directory, regardless
of the file creation mask. After the copy is done, the
permissions are set to be the same as the source direc-
tory, as modified by the file creation mask. This latter
change from historical behavior is to prevent users from
accidentally creating directories with permissions
beyond those they would normally set and for consistency
with the behavior of cp in creating files.
It is not a requirement that cp detect attempts to copy
a file to itself; however, implementations are strongly
encouraged to do so. Historical implementations have
detected the attempt in most cases.
There are two methods of copying subtrees in this volume
of IEEE Std 1003.1-2001. The other method is described
as part of the pax utility (see pax ). Both methods are
historical practice. The cp utility provides a simpler,
more intuitive interface, while pax offers a finer gran-
ularity of control. Each provides additional functional-
ity to the other; in particular, pax maintains the hard-
link structure of the hierarchy, while cp does not. It
is the intention of the standard developers that the
results be similar (using appropriate option combina-
tions in both utilities). The results are not required
to be identical; there seemed insufficient gain to
applications to balance the difficulty of implementa-
tions having to guarantee that the results would be
exactly identical.
The wording allowing cp to copy a directory to implemen-
tation-defined file types not specified by the System
Interfaces volume of IEEE Std 1003.1-2001 is provided so
that implementations supporting symbolic links are not
required to prohibit copying directories to symbolic
links. Other extensions to the System Interfaces volume
of IEEE Std 1003.1-2001 file types may need to use this
loophole as well.
FUTURE DIRECTIONS
The -r option may be removed; use -R instead.
SEE ALSO
mv , find , ln , pax , the System Interfaces volume of
IEEE Std 1003.1-2001, open(), unlink()
COPYRIGHT
Portions of this text are reprinted and reproduced in
electronic form from IEEE Std 1003.1, 2003 Edition,
Standard for Information Technology -- Portable Operat-
ing System Interface (POSIX), The Open Group Base Speci-
fications Issue 6, Copyright (C) 2001-2003 by the Insti-
tute of Electrical and Electronics Engineers, Inc and
The Open Group. In the event of any discrepancy between
this version and the original IEEE and The Open Group
Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be
obtained online at http://www.open-
group.org/unix/online.html .
POSIX 2003 cp(P)
|
