bin/cp/cp.1

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