1.\" $OpenBSD: cp.1,v 1.41 2019/09/02 21:18:41 deraadt Exp $ 2.\" $NetBSD: cp.1,v 1.9 1995/07/25 19:36:45 jtc Exp $ 3.\" 4.\" Copyright (c) 1989, 1990, 1993, 1994 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" This code is derived from software contributed to Berkeley by 8.\" the Institute of Electrical and Electronics Engineers, Inc. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 3. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" @(#)cp.1 8.3 (Berkeley) 4/18/94 35.\" 36.Dd $Mdocdate: September 2 2019 $ 37.Dt CP 1 38.Os 39.Sh NAME 40.Nm cp 41.Nd copy files 42.Sh SYNOPSIS 43.Nm cp 44.Op Fl afipv 45.Oo 46.Fl R 47.Op Fl H | L | P 48.Oc 49.Ar source target 50.Nm cp 51.Op Fl afipv 52.Oo 53.Fl R 54.Op Fl H | L | P 55.Oc 56.Ar source ... directory 57.Sh DESCRIPTION 58In the first synopsis form, the 59.Nm 60utility copies the contents of the 61.Ar source 62file to the 63.Ar target 64file. 65In the second synopsis form, 66the contents of each named 67.Ar source 68file are copied to the destination 69.Ar 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 options are as follows: 76.Bl -tag -width Ds 77.It Fl a 78Archive mode. 79Same as 80.Fl RpP . 81.It Fl f 82For each existing destination pathname, remove it and 83create a new file, without prompting for confirmation, 84regardless of its permissions. 85The 86.Fl f 87option overrides any previous 88.Fl i 89options. 90.It Fl H 91If the 92.Fl R 93option is also specified, symbolic links on the command line are followed. 94Symbolic links encountered in the tree traversal are not followed. 95.It Fl i 96Write a prompt to the standard error output before copying a file 97that would overwrite an existing file. 98If the response from the standard input begins with the character 99.Sq Li y , 100the file copy is attempted. 101The 102.Fl i 103option overrides any previous 104.Fl f 105options. 106.It Fl L 107If the 108.Fl R 109option is also specified, all symbolic links are followed. 110.It Fl P 111If the 112.Fl R 113option is also specified, no symbolic links are followed. 114.It Fl p 115Preserve in the copy as many of the modification time, access time, 116file flags, file mode, user ID, and group ID as allowed by permissions. 117.Pp 118If the user ID and group ID cannot be preserved, no error message 119is displayed and the exit value is not altered. 120.Pp 121If the source file has its set-user-ID bit on and the user ID cannot 122be preserved, the set-user-ID bit is not preserved 123in the copy's permissions. 124If the source file has its set-group-ID bit on and the group ID cannot 125be preserved, the set-group-ID bit is not preserved 126in the copy's permissions. 127If the source file has both its set-user-ID and set-group-ID bits on, 128and either the user ID or group ID cannot be preserved, neither 129the set-user-ID nor set-group-ID bits are preserved in the copy's 130permissions. 131.It Fl R 132If 133.Ar source 134designates a directory, 135.Nm 136copies the directory and the entire subtree connected at that point. 137Created directories have the same mode as the corresponding source 138directory, unmodified by the process's umask. 139.Pp 140This option also causes symbolic links to be copied, rather than 141followed, and 142special files to be created, rather than being copied as normal files. 143However, 144.Nm 145copies hard linked files as separate files. 146To preserve hard links, 147use a utility such as 148.Xr pax 1 149or 150.Xr tar 1 151instead. 152.It Fl v 153Display the source and destination after each copy. 154.El 155.Pp 156For each destination file that already exists, its contents are 157overwritten if permissions allow, but its mode, user ID, and group 158ID are unchanged. 159.Pp 160In the second synopsis form, 161the destination specified by the 162.Ar directory 163operand must exist unless there is only one named 164.Ar source 165which is a directory and the 166.Fl R 167flag is specified. 168.Pp 169If the destination file does not exist, the mode of the source file is 170used as modified by the file mode creation mask 171.Pf ( Ic umask , 172see 173.Xr csh 1 ) . 174If the source file has its set-user-ID bit on, that bit is removed 175unless both the source file and the destination file are owned by the 176same user. 177If the source file has its set-group-ID bit on, that bit is removed 178unless both the source file and the destination file are in the same 179group and the user is a member of that group. 180If both the set-user-ID and set-group-ID bits are set, all of the above 181conditions must be fulfilled or both bits are removed. 182.Pp 183Appropriate permissions are required for file creation or overwriting. 184.Pp 185When a file containing large blocks of zero-valued bytes is copied, 186.Nm 187will attempt to create a sparse file. 188.Pp 189Symbolic links are always followed unless the 190.Fl R 191flag is set, in which case symbolic links are not followed, by default. 192The 193.Fl H 194or 195.Fl L 196flags (in conjunction with the 197.Fl R 198flag) cause symbolic links to be followed as described above. 199The 200.Fl H , 201.Fl L , 202and 203.Fl P 204options are ignored unless the 205.Fl R 206option is specified. 207In addition, these options override each other and the 208command's actions are determined by the last one specified. 209.Sh EXIT STATUS 210.Ex -std cp 211.Sh EXAMPLES 212Make a copy of file 213.Pa foo 214named 215.Pa bar : 216.Pp 217.Dl $ cp foo bar 218.Pp 219Copy a group of files to the 220.Pa /tmp 221directory: 222.Pp 223.Dl $ cp *.txt /tmp 224.Pp 225Copy the directory 226.Pa junk 227and all of its contents (including any subdirectories) to the 228.Pa /tmp 229directory: 230.Pp 231.Dl $ cp -R junk /tmp 232.Sh SEE ALSO 233.Xr mv 1 , 234.Xr umask 2 , 235.Xr fts_open 3 , 236.Xr symlink 7 237.Sh STANDARDS 238The 239.Nm 240utility is compliant with the 241.St -p1003.1-2008 242specification. 243.Pp 244The flags 245.Op Fl av 246are extensions to that specification. 247.Pp 248Historic versions of the 249.Nm 250utility had an 251.Fl r 252option. 253This implementation supports that option; however, its use is strongly 254discouraged, as it does not correctly copy special files, symbolic links 255or FIFOs. 256.Sh HISTORY 257A 258.Nm 259command appeared in 260.At v1 . 261