1.\" $OpenBSD: cp.1,v 1.31 2009/02/08 17:15:08 jmc 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: February 8 2009 $ 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 fip 45.Oo 46.Fl R 47.Op Fl H | L | P 48.Oc 49.Ar source target 50.Nm cp 51.Op Fl fip 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 f 78For each existing destination pathname, remove it and 79create a new file, without prompting for confirmation, 80regardless of its permissions. 81This option overrides any use of 82.Fl i . 83.It Fl H 84If the 85.Fl R 86option is also specified, symbolic links on the command-line are followed. 87(Symbolic links encountered in the tree traversal are not followed.) 88.It Fl i 89Write a prompt to the standard error output before copying a file 90that would overwrite an existing file. 91If the response from the standard input begins with the character 92.Sq Li y , 93the file copy is attempted. 94.It Fl L 95If the 96.Fl R 97option is also specified, all symbolic links are followed. 98.It Fl P 99If the 100.Fl R 101option is also specified, no symbolic links are followed. 102.It Fl p 103Preserve in the copy as many of the modification time, access time, 104file flags, file mode, user ID, and group ID as allowed by permissions. 105.Pp 106If the user ID and group ID cannot be preserved, no error message 107is displayed and the exit value is not altered. 108.Pp 109If the source file has its set-user-ID bit on and the user ID cannot 110be preserved, the set-user-ID bit is not preserved 111in the copy's permissions. 112If the source file has its set-group-ID bit on and the group ID cannot 113be preserved, the set-group-ID bit is not preserved 114in the copy's permissions. 115If the source file has both its set-user-ID and set-group-ID bits on, 116and either the user ID or group ID cannot be preserved, neither 117the set-user-ID nor set-group-ID bits are preserved in the copy's 118permissions. 119.It Fl R 120If 121.Ar source 122designates a directory, 123.Nm 124copies the directory and the entire subtree connected at that point. 125Created directories have the same mode as the corresponding source 126directory, unmodified by the process's umask. 127.Pp 128This option also causes symbolic links to be copied, rather than 129followed, and 130special files to be created, rather than being copied as normal files. 131However, 132.Nm 133copies hard linked files as separate files. 134To preserve hard links, 135use a utility such as 136.Xr pax 1 137or 138.Xr tar 1 139instead. 140.El 141.Pp 142For each destination file that already exists, its contents are 143overwritten if permissions allow, but its mode, user ID, and group 144ID are unchanged. 145.Pp 146In the second synopsis form, 147the destination specified by the 148.Ar directory 149operand must exist unless there is only one named 150.Ar source 151which is a directory and the 152.Fl R 153flag is specified. 154.Pp 155If the destination file does not exist, the mode of the source file is 156used as modified by the file mode creation mask 157.Pf ( Ic umask , 158see 159.Xr csh 1 ) . 160If the source file has its set-user-ID bit on, that bit is removed 161unless both the source file and the destination file are owned by the 162same user. 163If the source file has its set-group-ID bit on, that bit is removed 164unless both the source file and the destination file are in the same 165group and the user is a member of that group. 166If both the set-user-ID and set-group-ID bits are set, all of the above 167conditions must be fulfilled or both bits are removed. 168.Pp 169Appropriate permissions are required for file creation or overwriting. 170.Pp 171When a file containing large blocks of zero-valued bytes is copied, 172.Nm 173will attempt to create a sparse file. 174.Pp 175Symbolic links are always followed unless the 176.Fl R 177flag is set, in which case symbolic links are not followed, by default. 178The 179.Fl H 180or 181.Fl L 182flags (in conjunction with the 183.Fl R 184flag) cause symbolic links to be followed as described above. 185The 186.Fl H , 187.Fl L , 188and 189.Fl P 190options are ignored unless the 191.Fl R 192option is specified. 193In addition, these options override each other and the 194command's actions are determined by the last one specified. 195.Pp 196.Ex -std cp 197.Sh EXAMPLES 198Make a copy of file 199.Pa foo 200named 201.Pa bar : 202.Pp 203.Dl $ cp foo bar 204.Pp 205Copy a group of files to the 206.Pa /tmp 207directory: 208.Pp 209.Dl $ cp *.txt /tmp 210.Pp 211Copy the directory 212.Pa junk 213and all of its contents (including any subdirectories) to the 214.Pa /tmp 215directory: 216.Pp 217.Dl $ cp -R junk /tmp 218.Sh SEE ALSO 219.Xr mv 1 , 220.Xr rcp 1 , 221.Xr umask 2 , 222.Xr fts 3 , 223.Xr symlink 7 224.Sh STANDARDS 225The 226.Nm 227utility is compliant with the 228.St -p1003.1-2008 229specification. 230.Pp 231Historic versions of the 232.Nm 233utility had a 234.Fl r 235option. 236This implementation supports that option; however, its use is strongly 237discouraged, as it does not correctly copy special files, symbolic links 238or FIFOs. 239.Sh HISTORY 240A 241.Nm 242command appeared in 243.At v1 . 244