| blob | d37776dda4d332e328b43406a600839a2dc25fd2 |
1 .\"-
2 .\" Copyright (c) 1989, 1990, 1993, 1994
3 .\" The Regents of the University of California. All rights reserved.
4 .\"
5 .\" This code is derived from software contributed to Berkeley by
6 .\" the Institute of Electrical and Electronics Engineers, Inc.
7 .\"
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
10 .\" are met:
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\" 2. Redistributions in binary form must reproduce the above copyright
14 .\" notice, this list of conditions and the following disclaimer in the
15 .\" documentation and/or other materials provided with the distribution.
16 .\" 3. Neither the name of the University nor the names of its contributors
17 .\" may be used to endorse or promote products derived from this software
18 .\" without specific prior written permission.
19 .\"
20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30 .\" SUCH DAMAGE.
31 .\"
32 .Dd March 28, 2024
33 .Dt CP 1
34 .Os
35 .Sh NAME
36 .Nm cp
37 .Nd copy files
38 .Sh SYNOPSIS
39 .Nm
40 .Oo
41 .Fl R
42 .Op Fl H | Fl L | Fl P
43 .Oc
44 .Op Fl f | i | n
45 .Op Fl alNpsvx
46 .Ar source_file target_file
47 .Nm
48 .Oo
49 .Fl R
50 .Op Fl H | Fl L | Fl P
51 .Oc
52 .Op Fl f | i | n
53 .Op Fl alNpsvx
54 .Ar source_file ... target_directory
55 .Nm
56 .Op Fl f | i | n
57 .Op Fl alNPpsvx
58 .Ar source_file target_file
59 .Nm
60 .Op Fl f | i | n
61 .Op Fl alNPpsvx
62 .Ar source_file ... target_directory
63 .Sh DESCRIPTION
64 In the first synopsis form, the
65 .Nm
66 utility copies the contents of the
67 .Ar source_file
68 to the
69 .Ar target_file .
70 In the second synopsis form,
71 the contents of each named
72 .Ar source_file
73 is copied to the destination
74 .Ar target_directory .
75 The names of the files themselves are not changed.
76 If
77 .Nm
78 detects an attempt to copy a file to itself, the copy will fail.
79 .Pp
80 The following options are available:
81 .Bl -tag -width flag
82 .It Fl H
83 If the
84 .Fl R
85 option is specified, symbolic links on the command line are followed.
86 (Symbolic links encountered in the tree traversal are not followed.)
87 .It Fl L
88 If the
89 .Fl R
90 option is specified, all symbolic links are followed.
91 .It Fl P
92 No symbolic links are followed.
93 This is the default if the
94 .Fl R
95 option is specified.
96 .It Fl R
97 If
98 .Ar source_file
99 designates a directory,
100 .Nm
101 copies the directory and the entire subtree connected at that point.
102 If the
103 .Ar source_file
104 ends in a
105 .Pa / ,
106 the contents of the directory are copied rather than the
107 directory itself.
108 This option also causes symbolic links to be copied, rather than
109 indirected through, and for
110 .Nm
111 to create special files rather than copying them as normal files.
112 Created directories have the same mode as the corresponding source
113 directory, unmodified by the process' umask.
114 .Pp
115 Note that
116 .Nm
117 copies hard linked files as separate files.
118 If you need to preserve hard links, consider using
119 .Xr tar 1 ,
120 .Xr cpio 1 ,
121 or
122 .Xr pax 1
123 instead.
124 .It Fl a
125 Archive mode.
126 Same as
127 .Fl RpP .
128 .It Fl f
129 For each existing destination pathname, remove it and
130 create a new file, without prompting for confirmation
131 regardless of its permissions.
132 (The
133 .Fl f
134 option overrides any previous
135 .Fl i
136 or
137 .Fl n
138 options.)
139 .It Fl i
140 Cause
141 .Nm
142 to write a prompt to the standard error output before copying a file
143 that would overwrite an existing file.
144 If the response from the standard input begins with the character
145 .Sq Li y
146 or
147 .Sq Li Y ,
148 the file copy is attempted.
149 (The
150 .Fl i
151 option overrides any previous
152 .Fl f
153 or
154 .Fl n
155 options.)
156 .It Fl l
157 Create hard links to regular files in a hierarchy instead of copying.
158 .It Fl N
159 When used with
160 .Fl p ,
161 suppress copying file flags.
162 .It Fl n
163 Do not overwrite an existing file.
164 (The
165 .Fl n
166 option overrides any previous
167 .Fl f
168 or
169 .Fl i
170 options.)
171 .It Fl p
172 Cause
173 .Nm
174 to preserve the following attributes of each source
175 file in the copy: modification time, access time,
176 file flags, file mode, ACL, user ID, and group ID, as allowed by permissions.
177 .Pp
178 If the user ID and group ID cannot be preserved, no error message
179 is displayed and the exit value is not altered.
180 .Pp
181 If the source file has its set-user-ID bit on and the user ID cannot
182 be preserved, the set-user-ID bit is not preserved
183 in the copy's permissions.
184 If the source file has its set-group-ID bit on and the group ID cannot
185 be preserved, the set-group-ID bit is not preserved
186 in the copy's permissions.
187 If the source file has both its set-user-ID and set-group-ID bits on,
188 and either the user ID or group ID cannot be preserved, neither
189 the set-user-ID nor set-group-ID bits are preserved in the copy's
190 permissions.
191 .It Fl s
192 Create symbolic links to regular files in a hierarchy instead of copying.
193 .It Fl v
194 Cause
195 .Nm
196 to be verbose, showing files as they are copied.
197 .It Fl x
198 File system mount points are not traversed.
199 .El
200 .Pp
201 For each destination file that already exists, its contents are
202 overwritten if permissions allow.
203 Its mode, user ID, and group
204 ID are unchanged unless the
205 .Fl p
206 option was specified.
207 .Pp
208 In the second synopsis form,
209 .Ar target_directory
210 must exist unless there is only one named
211 .Ar source_file
212 which is a directory and the
213 .Fl R
214 flag is specified.
215 .Pp
216 If the destination file does not exist, the mode of the source file is
217 used as modified by the file mode creation mask
218 .Pf ( Ic umask ,
219 see
220 .Xr csh 1 ) .
221 If the source file has its set-user-ID bit on, that bit is removed
222 unless both the source file and the destination file are owned by the
223 same user.
224 If the source file has its set-group-ID bit on, that bit is removed
225 unless both the source file and the destination file are in the same
226 group and the user is a member of that group.
227 If both the set-user-ID and set-group-ID bits are set, all of the above
228 conditions must be fulfilled or both bits are removed.
229 .Pp
230 Appropriate permissions are required for file creation or overwriting.
231 .Pp
232 Symbolic links are always followed unless the
233 .Fl R
234 flag is set, in which case symbolic links are not followed, by default.
235 The
236 .Fl H
237 or
238 .Fl L
239 flags (in conjunction with the
240 .Fl R
241 flag) cause symbolic links to be followed as described above.
242 The
243 .Fl H ,
244 .Fl L
245 and
246 .Fl P
247 options are ignored unless the
248 .Fl R
249 option is specified.
250 In addition, these options override each other and the
251 command's actions are determined by the last one specified.
252 .Pp
253 If
254 .Nm
255 receives a
256 .Dv SIGINFO
257 (see the
258 .Cm status
259 argument for
260 .Xr stty 1 )
261 signal, the current input and output file and the percentage complete
262 will be written to the standard output.
263 .Sh EXIT STATUS
264 .Ex -std
265 .Sh EXAMPLES
266 Make a copy of file
267 .Pa foo
268 named
269 .Pa bar :
270 .Pp
271 .Dl $ cp foo bar
272 .Pp
273 Copy a group of files to the
274 .Pa /tmp
275 directory:
276 .Pp
277 .Dl $ cp *.txt /tmp
278 .Pp
279 Copy the directory
280 .Pa junk
281 and all of its contents (including any subdirectories) to the
282 .Pa /tmp
283 directory:
284 .Pp
285 .Dl $ cp -R junk /tmp
286 .Sh COMPATIBILITY
287 Historic versions of the
288 .Nm
289 utility had a
290 .Fl r
291 option.
292 This implementation supports that option, however, its behavior
293 is different from historical
294 .Fx
295 behavior.
296 Use of this option
297 is strongly discouraged as the behavior is
298 implementation-dependent.
299 In
300 .Fx ,
301 .Fl r
302 is a synonym for
303 .Fl RL
304 and works the same unless modified by other flags.
305 Historical implementations
306 of
307 .Fl r
308 differ as they copy special files as normal
309 files while recreating a hierarchy.
310 .Pp
311 The
312 .Fl a ,
313 .Fl l ,
314 .Fl N ,
315 .Fl n ,
316 .Fl s ,
317 .Fl v ,
318 and
319 .Fl x
320 options are non-standard and their use in scripts is not recommended.
321 .Sh SEE ALSO
322 .Xr mv 1 ,
323 .Xr rcp 1 ,
324 .Xr umask 2 ,
325 .Xr fts 3 ,
326 .Xr symlink 7
327 .Sh STANDARDS
328 The
329 .Nm
330 command is expected to be
331 .St -p1003.2
332 compatible.
333 .Sh HISTORY
334 A
335 .Nm
336 command appeared in
337 .At v1 .