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