1.\" $NetBSD: cp.1,v 1.46 2018/12/23 01:29:23 gutteridge Exp $ 2.\" 3.\" Copyright (c) 1989, 1990, 1993, 1994 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" This code is derived from software contributed to Berkeley by 7.\" the Institute of Electrical and Electronics Engineers, Inc. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. Neither the name of the University nor the names of its contributors 18.\" may be used to endorse or promote products derived from this software 19.\" without specific prior written permission. 20.\" 21.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 22.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 23.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 24.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 25.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 26.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 27.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 28.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 29.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 30.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 31.\" SUCH DAMAGE. 32.\" 33.\" @(#)cp.1 8.3 (Berkeley) 4/18/94 34.\" 35.Dd December 22, 2018 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 48.Op Fl alNpv 49.Ar source_file target_file 50.Nm cp 51.Oo 52.Fl R 53.Op Fl H | Fl L | Fl P 54.Oc 55.Op Fl f | i 56.Op Fl alNpv 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 a 78Archive mode. 79Same as 80.Fl RpP . 81.It Fl f 82For each existing destination pathname, attempt to overwrite it. 83If permissions do not allow copy to succeed, remove it and create a new 84file, without prompting for confirmation. 85(The 86.Fl i 87option is ignored if the 88.Fl f 89option is specified.) 90.It Fl H 91If the 92.Fl R 93option is specified, symbolic links on the command line are followed. 94(Symbolic links encountered in the tree traversal are not followed.) 95.It Fl i 96Causes 97.Nm 98to write a prompt to the standard error output before copying a file 99that would overwrite an existing file. 100If the response from the standard input begins with the character 101.Sq Li y , 102the file copy is attempted. 103.It Fl L 104If the 105.Fl R 106option is specified, all symbolic links are followed. 107.It Fl l 108Create hard links to regular files in a hierarchy instead of copying. 109.It Fl N 110When used with 111.Fl p , 112don't copy file flags. 113.It Fl P 114No symbolic links are followed. 115This is the default. 116.It Fl p 117Causes 118.Nm 119to preserve in the copy as many of the modification time, access time, 120file flags, file mode, user ID, group ID, and extended attributes, 121as allowed by permissions. 122.Pp 123If the user ID and group ID cannot be preserved due to insufficient 124permissions, no error message is displayed and the exit value is not 125altered. 126.Pp 127If the source file has its set user ID bit on and the user ID cannot 128be preserved, the set user ID bit is not preserved 129in the copy's permissions. 130If the source file has its set group ID bit on and the group ID cannot 131be preserved, the set group ID bit is not preserved 132in the copy's permissions. 133If the source file has both its set user ID and set group ID bits on, 134and either the user ID or group ID cannot be preserved, neither 135the set user ID or set group ID bits are preserved in the copy's 136permissions. 137.Pp 138Extended attributes from all accessible namespaces are copied; 139others are ignored. 140If an error occurs during this copy, a message is displayed and 141.Nm 142skips the other extended attributes for that file. 143.It Fl R 144If 145.Ar source_file 146designates a directory, 147.Nm 148copies the directory and the entire subtree connected at that point. 149This option also causes symbolic links to be copied, rather than 150followed, and for 151.Nm 152to create special files rather than copying them as normal files. 153Created directories have the same mode as the corresponding source 154directory, unmodified by the process's umask. 155.Pp 156Note that 157.Nm 158copies hard linked files as separate files. 159If you need to preserve hard links, consider using a utility like 160.Xr pax 1 161instead. 162.It Fl v 163Causes 164.Nm 165to be verbose, showing files as they are copied. 166.El 167.Pp 168For each destination file that already exists, its contents are 169overwritten if permissions allow, but its mode, user ID, and group 170ID are unchanged. 171.Pp 172In the second synopsis form, 173.Ar target_directory 174must exist unless there is only one named 175.Ar source_file 176which is a directory and the 177.Fl R 178flag is specified. 179.Pp 180If the destination file does not exist, the mode of the source file is 181used as modified by the file mode creation mask 182.Ic ( umask , 183see 184.Xr csh 1 ) . 185If the source file has its set user ID bit on, that bit is removed 186unless both the source file and the destination file are owned by the 187same user. 188If the source file has its set group ID bit on, that bit is removed 189unless both the source file and the destination file are in the same 190group and the user is a member of that group. 191If both the set user ID and set group ID bits are set, all of the above 192conditions must be fulfilled or both bits are removed. 193.Pp 194Appropriate permissions are required for file creation or overwriting. 195.Pp 196Symbolic links are always followed unless the 197.Fl R 198flag is set, in which case symbolic links are not followed, by default. 199The 200.Fl H 201or 202.Fl L 203flags (in conjunction with the 204.Fl R 205flag), as well as the 206.Fl P 207flag cause symbolic links to be followed as described above. 208The 209.Fl H 210and 211.Fl L 212options are ignored unless the 213.Fl R 214option is specified. 215In addition, these options override each other and the 216command's actions are determined by the last one specified. 217The default is as if the 218.Fl P 219option had been specified. 220.Sh EXIT STATUS 221.Ex -std cp 222.Sh COMPATIBILITY 223Historic versions of the 224.Nm 225utility had a 226.Fl r 227option. 228This implementation supports that option, however, its use is strongly 229discouraged, as it does not correctly copy special files, symbolic links, 230or FIFOs. 231.Sh SEE ALSO 232.Xr mv 1 , 233.Xr pax 1 , 234.Xr rcp 1 , 235.Xr umask 2 , 236.Xr fts 3 , 237.Xr symlink 7 238.Sh STANDARDS 239The 240.Nm 241utility is expected to be 242.St -p1003.2 243compatible. 244.Pp 245The 246.Fl a 247and 248.Fl l 249flags are non-standard extensions. 250They are intended to be compatible with the same options which 251other implementations, namely GNU coreutils and 252.Fx , 253of this utility have. 254.Pp 255The 256.Fl v 257option is an extension to 258.St -p1003.2 . 259.Sh HISTORY 260A 261.Nm 262utility appeared in 263.At v1 . 264