1 CP(1) User Commands CP(1)
2
3
4
5 NAME
6 cp - copy files
7
8 SYNOPSIS
9 /usr/bin/cp [-afip@/] source_file target_file
10
11
12 /usr/bin/cp [-afip@/] source_file... target
13
14
15 /usr/bin/cp [-r | -R [-H | -L | -P]] [-afip@/] source_dir... target
16
17
18 /usr/bin/cp [-R | -R [-H | -L | -P]] [-afip@/] source_dir... target
19
20
21 /usr/xpg4/bin/cp [-afip@/] source_file target_file
22
23
24 /usr/xpg4/bin/cp [-afip@/] source_file... target
25
26
27 /usr/xpg4/bin/cp [-r | -R [-H | -L | -P]] [-afip@/] source_dir... target
28
29
30 /usr/xpg4/bin/cp [-R | -R [-H | -L | -P]] [-afip@/] source_dir... target
31
32
33 DESCRIPTION
34 In the first synopsis form, neither source_file nor target_file are
35 directory files, nor can they have the same name. The cp utility copies
36 the contents of source_file to the destination path named by
37 target_file. If target_file exists, cp overwrites its contents, but the
38 mode (and ACL if applicable), owner, and group associated with it are
39 not changed. The last modification time of target_file and the last
40 access time of source_file are set to the time the copy was made. If
41 target_file does not exist, cp creates a new file named target_file
42 that has the same mode as source_file except that the sticky bit is not
43 set unless the user is super-user. In this case, the owner and group of
44 target_file are those of the user, unless the setgid bit is set on the
45 directory containing the newly created file. If the directory's setgid
46 bit is set, the newly created file has the group of the containing
47 directory rather than of the creating user. If target_file is a link to
48 another file, cp overwrites the link destination with the contents of
49 source_file; the link(s) from target_file remains.
50
51
52 In the second synopsis form, one or more source_files are copied to the
53 directory specified by target. It is an error if any source_file is a
54 file of type directory, if target either does not exist or is not a
55 directory.
56
57
58 In the third or fourth synopsis forms, one or more directories
59 specified by source_dir are copied to the directory specified by
60 target. Either the -r or -R must be specified. For each source_dir, cp
61 copies all files and subdirectories.
62
63 OPTIONS
64 The following options are supported for both /usr/bin/cp and
65 /usr/xpg4/bin/cp:
66
67 -a
68 Archive mode. Same as -RpP.
69
70
71 -f
72 Unlink. If a file descriptor for a destination file cannot be
73 obtained, this option attempts to unlink the destination file and
74 proceed.
75
76
77 -H
78 Takes actions based on the type and contents of the file
79 referenced by any symbolic link specified as a source_file
80 operand.
81
82 If the source_file operand is a symbolic link, then cp copies the
83 file referenced by the symbolic link for the source_file operand.
84 All other symbolic links encountered during traversal of a file
85 hierarchy are preserved.
86
87
88 -i
89 Interactive. cp prompts for confirmation whenever the copy would
90 overwrite an existing target. An affirmative response means that
91 the copy should proceed. Any other answer prevents cp from
92 overwriting target.
93
94
95 -L
96 Takes actions based on the type and contents of the file
97 referenced by any symbolic link specified as a source_file
98 operand or any symbolic links encountered during traversal of a
99 file hierarchy.
100
101 Copies files referenced by symbolic links. Symbolic links
102 encountered during traversal of a file hierarchy are not
103 preserved.
104
105
106 -p
107 Preserve. The cp utility duplicates not only the contents of
108 source_file, but also attempts to preserve its ACL, access and
109 modification times, extended attributes, extended system
110 attributes, file mode, and owner and group ids.
111
112 If cp is unable to preserve the access and modification times,
113 extended attributes, or the file mode, cp does not consider it a
114 failure. If cp is unable to preserve the owner and group id, the
115 copy does not fail, but cp silently clears the S_ISUID and
116 S_ISGID bits from the file mode of the target. The copy fails if
117 cp is unable to clear these bits. If cp is unable to preserve the
118 ACL or extended system attributes, the copy fails. If the copy
119 fails, then a diagnostic message is written to stderr and (after
120 processing any remaining operands) cp exits with a non-zero exit
121 status.
122
123
124 -P
125 Takes actions on any symbolic link specified as a source_file
126 operand or any symbolic link encountered during traversal of a
127 file hierarchy.
128
129 Copies symbolic links. Symbolic links encountered during
130 traversal of a file hierarchy are preserved.
131
132
133 -r
134 Recursive. cp copies the directory and all its files, including
135 any subdirectories and their files to target. Unless the -H, -L,
136 or -P option is specified, the -L option is used as the default
137 mode.
138
139
140 -R
141 Same as -r, except pipes are replicated, not read from.
142
143
144 -@
145 Preserves extended attributes. cp attempts to copy all of the
146 source file's extended attributes along with the file data to the
147 destination file.
148
149
150 -/
151 Preserves extended attributes and extended system attributes.
152 Along with the file's data, the cp utility attempts to copy
153 extended attributes and extended system attributes from each
154 source file, and extended system attributes associated with
155 extended attributes to the destination file. If cp is unable to
156 copy extended attributes or extended system attributes, then a
157 diagnostic message is written to stderr and (after processing any
158 remaining operands) exits with a non-zero exit status.
159
160
161
162 Specifying more than one of the mutually-exclusive options -H, -L, and
163 -P is not considered an error. The last option specified determines the
164 behavior of the utility.
165
166 /usr/bin/cp
167 If the -p option is specified with either the -@ option or the -/
168 option, /usr/bin/cp behaves as follows
169
170 o When both -p and -@ are specified in any order, the copy
171 fails if extended attributes cannot be copied.
172
173 o When both -p and -/ are specified in any order, the copy
174 fails if extended system attributes cannot be copied.
175
176 /usr/xpg4/bin/cp
177 If the -p option is specified with either the -@ option or the -/
178 option, /usr/xpg4/bin/cp behaves as follows:
179
180 o When both -p and -@ are specified, the last option specified
181 determines whether the copy fails if extended attributes
182 cannot be preserved.
183
184 o When both -p and -/ are specified, the last option specified
185 determines whether the copy fails if extended system
186 attributes cannot be preserved.
187
188 OPERANDS
189 The following operands are supported:
190
191 source_file
192 A pathname of a regular file to be copied.
193
194
195 source_dir
196 A pathname of a directory to be copied.
197
198
199 target_file
200 A pathname of an existing or non-existing file, used for
201 the output when a single file is copied.
202
203
204 target
205 A pathname of a directory to contain the copied files.
206
207
208 USAGE
209 See largefile(5) for the description of the behavior of cp when
210 encountering files greater than or equal to 2 Gbyte ( 2^31 bytes).
211
212 EXAMPLES
213 Example 1 Copying a File
214
215
216 The following example copies a file:
217
218
219 example% cp goodies goodies.old
220
221 example% ls goodies*
222 goodies goodies.old
223
224
225
226 Example 2 Copying a List of Files
227
228
229 The following example copies a list of files to a destination
230 directory:
231
232
233 example% cp ~/src/* /tmp
234
235
236
237 Example 3 Copying a Directory
238
239
240 The following example copies a directory, first to a new, and then to
241 an existing destination directory
242
243
244 example% ls ~/bkup
245 /usr/example/fred/bkup not found
246
247 example% cp -r ~/src ~/bkup
248
249 example% ls -R ~/bkup
250 x.c y.c z.sh
251
252 example% cp -r ~/src ~/bkup
253
254 example% ls -R ~/bkup
255 src x.c y.c z.sh
256 src:
257 x.c y.c z.s
258
259
260
261 Example 4 Copying Extended File System Attributes
262
263
264 The following example copies extended file system attributes:
265
266
267 $ ls -/ c file1
268 -rw-r--r-- 1 foo staff 0 Oct 29 20:04 file1
269 {AH-----m--}
270
271 $ cp -/ file1 file2
272 $ ls -/c file2
273 -rw-r--r-- 1 foo staff 0 Oct 29 20:17 file2
274 {AH-----m--}
275
276
277
278 Example 5 Failing to Copy Extended System Attributes
279
280
281 The following example fails to copy extended system attributes:
282
283
284 $ ls -/c file1
285 -rw-r--r-- 1 foo staff 0 Oct 29 20:04 file1
286 {AH-----m--}
287
288 $ cp -/ file1 /tmp
289 cp: Failed to copy extended system attributes from file1 to /tmp/file1
290
291
292 $ ls -/c /tmp/file1
293 -rw-r--r-- 1 foo staff 0 Oct 29 20:09 /tmp/file1
294 {}
295
296
297
298 ENVIRONMENT VARIABLES
299 See environ(5) for descriptions of the following environment variables
300 that affect the execution of cp: LANG, LC_ALL, LC_COLLATE, LC_CTYPE,
301 LC_MESSAGES, and NLSPATH.
302
303
304 Affirmative responses are processed using the extended regular
305 expression defined for the yesexpr keyword in the LC_MESSAGES category
306 of the user's locale. The locale specified in the LC_COLLATE category
307 defines the behavior of ranges, equivalence classes, and multi-
308 character collating elements used in the expression defined for
309 yesexpr. The locale specified in LC_CTYPE determines the locale for
310 interpretation of sequences of bytes of text data a characters, the
311 behavior of character classes used in the expression defined for the
312 yesexpr. See locale(5).
313
314 EXIT STATUS
315 The following exit values are returned:
316
317 0
318 All files were copied successfully.
319
320
321 >0
322 An error occurred.
323
324
325 ATTRIBUTES
326 See attributes(5) for descriptions of the following attributes:
327
328 /usr/bin/cp
329
330 +--------------------+-----------------+
331 | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
332 +--------------------+-----------------+
333 |CSI | Enabled |
334 +--------------------+-----------------+
335 |Interface Stability | Committed |
336 +--------------------+-----------------+
337
338 /usr/xpg4/bin/cp
339
340 +--------------------+-----------------+
341 | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
342 +--------------------+-----------------+
343 |CSI | Enabled |
344 +--------------------+-----------------+
345 |Interface Stability | Committed |
346 +--------------------+-----------------+
347
348 SEE ALSO
349 chmod(1), chown(1), setfacl(1), utime(2), fgetattr(3C), attributes(5),
350 environ(5), fsattr(5), largefile(5), locale(5), standards(5)
351
352 NOTES
353 The permission modes of the source file are preserved in the copy.
354
355
356 A -- permits the user to mark the end of any command line options
357 explicitly, thus allowing cp to recognize filename arguments that begin
358 with a -.
359
360
361
362 May 17, 2020 CP(1)