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