Commit | Line | Data |
---|---|---|
7cfd531a | 1 | .\"- |
984263bc MD |
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. | |
dc71b7ab | 16 | .\" 3. Neither the name of the University nor the names of its contributors |
984263bc MD |
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 | .\" @(#)cp.1 8.3 (Berkeley) 4/18/94 | |
7cfd531a | 33 | .\" $FreeBSD$ |
984263bc | 34 | .\" |
2458c6f4 | 35 | .Dd December 31, 2017 |
984263bc MD |
36 | .Dt CP 1 |
37 | .Os | |
38 | .Sh NAME | |
39 | .Nm cp | |
40 | .Nd copy files | |
41 | .Sh SYNOPSIS | |
42 | .Nm | |
43 | .Oo | |
44 | .Fl R | |
45 | .Op Fl H | Fl L | Fl P | |
46 | .Oc | |
47 | .Op Fl f | i | n | |
7cfd531a | 48 | .Op Fl alpvx |
984263bc MD |
49 | .Ar source_file target_file |
50 | .Nm | |
51 | .Oo | |
52 | .Fl R | |
53 | .Op Fl H | Fl L | Fl P | |
54 | .Oc | |
55 | .Op Fl f | i | n | |
7cfd531a | 56 | .Op Fl alpvx |
984263bc MD |
57 | .Ar source_file ... target_directory |
58 | .Sh DESCRIPTION | |
59 | In the first synopsis form, the | |
60 | .Nm | |
61 | utility copies the contents of the | |
62 | .Ar source_file | |
63 | to the | |
64 | .Ar target_file . | |
65 | In the second synopsis form, | |
66 | the contents of each named | |
67 | .Ar source_file | |
68 | is copied to the destination | |
69 | .Ar target_directory . | |
70 | The names of the files themselves are not changed. | |
71 | If | |
72 | .Nm | |
73 | detects an attempt to copy a file to itself, the copy will fail. | |
74 | .Pp | |
75 | The following options are available: | |
76 | .Bl -tag -width flag | |
77 | .It Fl H | |
78 | If the | |
79 | .Fl R | |
80 | option is specified, symbolic links on the command line are followed. | |
81 | (Symbolic links encountered in the tree traversal are not followed.) | |
82 | .It Fl L | |
83 | If the | |
84 | .Fl R | |
85 | option is specified, all symbolic links are followed. | |
86 | .It Fl P | |
87 | If the | |
88 | .Fl R | |
89 | option is specified, no symbolic links are followed. | |
90 | This is the default. | |
91 | .It Fl R | |
92 | If | |
93 | .Ar source_file | |
94 | designates a directory, | |
95 | .Nm | |
96 | copies the directory and the entire subtree connected at that point. | |
779388d9 SS |
97 | If the |
98 | .Ar source_file | |
99 | ends in a | |
100 | .Pa / , | |
101 | the contents of the directory are copied rather than the | |
102 | directory itself. | |
984263bc MD |
103 | This option also causes symbolic links to be copied, rather than |
104 | indirected through, and for | |
105 | .Nm | |
106 | to create special files rather than copying them as normal files. | |
107 | Created directories have the same mode as the corresponding source | |
108 | directory, unmodified by the process' umask. | |
109 | .Pp | |
110 | Note that | |
111 | .Nm | |
112 | copies hard linked files as separate files. | |
113 | If you need to preserve hard links, consider using | |
114 | .Xr tar 1 , | |
115 | .Xr cpio 1 , | |
116 | or | |
117 | .Xr pax 1 | |
118 | instead. | |
7cfd531a JM |
119 | .It Fl a |
120 | Archive mode. | |
121 | Same as | |
122 | .Fl RpP . | |
984263bc MD |
123 | .It Fl f |
124 | For each existing destination pathname, remove it and | |
125 | create a new file, without prompting for confirmation | |
126 | regardless of its permissions. | |
127 | (The | |
128 | .Fl f | |
129 | option overrides any previous | |
130 | .Fl i | |
131 | or | |
132 | .Fl n | |
133 | options.) | |
134 | .It Fl i | |
135 | Cause | |
136 | .Nm | |
137 | to write a prompt to the standard error output before copying a file | |
138 | that would overwrite an existing file. | |
139 | If the response from the standard input begins with the character | |
140 | .Sq Li y | |
141 | or | |
142 | .Sq Li Y , | |
143 | the file copy is attempted. | |
144 | (The | |
145 | .Fl i | |
146 | option overrides any previous | |
147 | .Fl f | |
148 | or | |
149 | .Fl n | |
150 | options.) | |
7cfd531a JM |
151 | .It Fl l |
152 | Create hard links to regular files in a hierarchy instead of copying. | |
984263bc MD |
153 | .It Fl n |
154 | Do not overwrite an existing file. | |
155 | (The | |
156 | .Fl n | |
157 | option overrides any previous | |
158 | .Fl f | |
159 | or | |
160 | .Fl i | |
161 | options.) | |
162 | .It Fl p | |
163 | Cause | |
164 | .Nm | |
3abc2185 CP |
165 | to preserve the following attributes of each source |
166 | file in the copy: modification time, access time, | |
167 | file flags, file mode, user ID, and group ID, as allowed by permissions. | |
984263bc MD |
168 | .Pp |
169 | If the user ID and group ID cannot be preserved, no error message | |
170 | is displayed and the exit value is not altered. | |
171 | .Pp | |
3abc2185 CP |
172 | If the source file has its set-user-ID bit on and the user ID cannot |
173 | be preserved, the set-user-ID bit is not preserved | |
984263bc | 174 | in the copy's permissions. |
3abc2185 CP |
175 | If the source file has its set-group-ID bit on and the group ID cannot |
176 | be preserved, the set-group-ID bit is not preserved | |
984263bc | 177 | in the copy's permissions. |
3abc2185 | 178 | If the source file has both its set-user-ID and set-group-ID bits on, |
984263bc | 179 | and either the user ID or group ID cannot be preserved, neither |
3abc2185 | 180 | the set-user-ID nor set-group-ID bits are preserved in the copy's |
984263bc MD |
181 | permissions. |
182 | .It Fl v | |
183 | Cause | |
184 | .Nm | |
185 | to be verbose, showing files as they are copied. | |
7cfd531a JM |
186 | .It Fl x |
187 | File system mount points are not traversed. | |
984263bc MD |
188 | .El |
189 | .Pp | |
190 | For each destination file that already exists, its contents are | |
3abc2185 CP |
191 | overwritten if permissions allow. |
192 | Its mode, user ID, and group | |
984263bc MD |
193 | ID are unchanged unless the |
194 | .Fl p | |
195 | option was specified. | |
196 | .Pp | |
197 | In the second synopsis form, | |
198 | .Ar target_directory | |
199 | must exist unless there is only one named | |
200 | .Ar source_file | |
201 | which is a directory and the | |
202 | .Fl R | |
203 | flag is specified. | |
204 | .Pp | |
205 | If the destination file does not exist, the mode of the source file is | |
206 | used as modified by the file mode creation mask | |
207 | .Pf ( Ic umask , | |
208 | see | |
209 | .Xr csh 1 ) . | |
3abc2185 | 210 | If the source file has its set-user-ID bit on, that bit is removed |
984263bc MD |
211 | unless both the source file and the destination file are owned by the |
212 | same user. | |
3abc2185 | 213 | If the source file has its set-group-ID bit on, that bit is removed |
984263bc MD |
214 | unless both the source file and the destination file are in the same |
215 | group and the user is a member of that group. | |
3abc2185 | 216 | If both the set-user-ID and set-group-ID bits are set, all of the above |
984263bc MD |
217 | conditions must be fulfilled or both bits are removed. |
218 | .Pp | |
219 | Appropriate permissions are required for file creation or overwriting. | |
220 | .Pp | |
221 | Symbolic links are always followed unless the | |
222 | .Fl R | |
223 | flag is set, in which case symbolic links are not followed, by default. | |
224 | The | |
225 | .Fl H | |
226 | or | |
227 | .Fl L | |
228 | flags (in conjunction with the | |
229 | .Fl R | |
230 | flag) cause symbolic links to be followed as described above. | |
231 | The | |
232 | .Fl H , | |
233 | .Fl L | |
234 | and | |
235 | .Fl P | |
236 | options are ignored unless the | |
237 | .Fl R | |
238 | option is specified. | |
239 | In addition, these options override each other and the | |
240 | command's actions are determined by the last one specified. | |
779388d9 SS |
241 | .Pp |
242 | If | |
243 | .Nm | |
244 | receives a | |
245 | .Dv SIGINFO | |
246 | (see the | |
247 | .Cm status | |
248 | argument for | |
249 | .Xr stty 1 ) | |
250 | signal, the current input and output file and the percentage complete | |
7cfd531a | 251 | will be written to the standard output. |
19fe1c42 | 252 | .Sh EXIT STATUS |
984263bc MD |
253 | .Ex -std |
254 | .Sh COMPATIBILITY | |
255 | Historic versions of the | |
256 | .Nm | |
257 | utility had a | |
258 | .Fl r | |
259 | option. | |
7cfd531a JM |
260 | This implementation supports that option, however, its behavior |
261 | is different from historical | |
262 | .Dx | |
263 | behavior. | |
264 | Use of this option | |
265 | is strongly discouraged as the behavior is | |
266 | implementation-dependent. | |
267 | In | |
268 | .Dx , | |
269 | .Fl r | |
270 | is a synonym for | |
271 | .Fl RL | |
272 | and works the same unless modified by other flags. | |
273 | Historical implementations | |
274 | of | |
275 | .Fl r | |
276 | differ as they copy special files as normal | |
277 | files while recreating a hierarchy. | |
984263bc MD |
278 | .Pp |
279 | The | |
280 | .Fl v | |
281 | and | |
282 | .Fl n | |
283 | options are non-standard and their use in scripts is not recommended. | |
284 | .Sh SEE ALSO | |
285 | .Xr mv 1 , | |
2458c6f4 | 286 | .Xr rcp 1 Pq Pa net/bsdrcmds , |
984263bc MD |
287 | .Xr umask 2 , |
288 | .Xr fts 3 , | |
289 | .Xr symlink 7 | |
290 | .Sh STANDARDS | |
291 | The | |
292 | .Nm | |
293 | command is expected to be | |
294 | .St -p1003.2 | |
295 | compatible. | |
296 | .Sh HISTORY | |
297 | A | |
298 | .Nm | |
299 | command appeared in | |
300 | .At v1 . |