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