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