usr.bin/xinstall/install.1

   1 .\" Copyright (c) 1987, 1990, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .Dd April 10, 2024
  29 .Dt INSTALL 1
  30 .Os
  31 .Sh NAME
  32 .Nm install
  33 .Nd install binaries
  34 .Sh SYNOPSIS
  35 .Nm
  36 .Op Fl bCcpSsUv
  37 .Op Fl B Ar suffix
  38 .Op Fl D Ar destdir
  39 .Op Fl f Ar flags
  40 .Op Fl g Ar group
  41 .Op Fl h Ar hash
  42 .Op Fl l Ar linkflags
  43 .Op Fl M Ar metalog
  44 .Op Fl m Ar mode
  45 .Op Fl N Ar dbdir
  46 .Op Fl o Ar owner
  47 .Op Fl T Ar tags
  48 .Ar file1 file2
  49 .Nm
  50 .Op Fl bCcpSsUv
  51 .Op Fl B Ar suffix
  52 .Op Fl D Ar destdir
  53 .Op Fl f Ar flags
  54 .Op Fl g Ar group
  55 .Op Fl h Ar hash
  56 .Op Fl l Ar linkflags
  57 .Op Fl M Ar metalog
  58 .Op Fl m Ar mode
  59 .Op Fl N Ar dbdir
  60 .Op Fl o Ar owner
  61 .Op Fl T Ar tags
  62 .Ar file1 ... fileN directory
  63 .Nm
  64 .Fl d
  65 .Op Fl Uv
  66 .Op Fl D Ar destdir
  67 .Op Fl g Ar group
  68 .Op Fl h Ar hash
  69 .Op Fl M Ar metalog
  70 .Op Fl m Ar mode
  71 .Op Fl N Ar dbdir
  72 .Op Fl o Ar owner
  73 .Op Fl T Ar tags
  74 .Ar directory ...
  75 .Sh DESCRIPTION
  76 The file(s) are copied
  77 (or linked if the
  78 .Fl l
  79 option is specified) to the target file or directory.
  80 If the destination is a directory, then the
  81 .Ar file
  82 is copied into
  83 .Ar directory
  84 with its original filename.
  85 If the target file already exists, it is
  86 either renamed to
  87 .Ar file Ns Pa .old
  88 if the
  89 .Fl b
  90 option is given
  91 or overwritten
  92 if permissions allow.
  93 An alternate backup suffix may be specified via the
  94 .Fl B
  95 option's argument.
  96 .Pp
  97 The options are as follows:
  98 .Bl -tag -width indent
  99 .It Fl B Ar suffix
 100 Use
 101 .Ar suffix
 102 as the backup suffix if
 103 .Fl b
 104 is given.
 105 .It Fl b
 106 Back up any existing files before overwriting them by renaming
 107 them to
 108 .Ar file Ns Pa .old .
 109 See
 110 .Fl B
 111 for specifying a different backup suffix.
 112 .It Fl C
 113 Copy the file.
 114 If the target file already exists and the files are the same,
 115 then do not change the modification time of the target.
 116 If the target's file flags and mode need not to be changed,
 117 the target's inode change time is also unchanged.
 118 .It Fl c
 119 Copy the file.
 120 This is actually the default.
 121 The
 122 .Fl c
 123 option is only included for backwards compatibility.
 124 .It Fl D Ar destdir
 125 Specify the
 126 .Ev DESTDIR
 127 (top of the file hierarchy) that the items are installed in to.
 128 If
 129 .Fl M Ar metalog
 130 is in use, a leading string of
 131 .Dq Ar destdir
 132 will be removed from the file names logged to the
 133 .Ar metalog .
 134 This option does not affect where the actual files are installed.
 135 .It Fl d
 136 Create directories.
 137 Missing parent directories are created as required.
 138 .It Fl f Ar flags
 139 Specify the target's file flags; see
 140 .Xr chflags 1
 141 for a list of possible flags and their meanings.
 142 .It Fl g Ar group
 143 Specify a group.
 144 A numeric GID is allowed.
 145 .It Fl h Ar hash
 146 When copying, calculate the digest of the files with
 147 .Ar hash
 148 to store in the
 149 .Fl M Ar metalog .
 150 When
 151 .Fl d
 152 is given no hash is emitted.
 153 Supported digests:
 154 .Bl -tag -width rmd160 -offset indent
 155 .It Sy none
 156 No hash.
 157 This is the default.
 158 .It Sy md5
 159 The MD5 cryptographic message digest.
 160 .It Sy rmd160
 161 The RMD-160 cryptographic message digest.
 162 .It Sy sha1
 163 The SHA-1 cryptographic message digest.
 164 .It Sy sha256
 165 The 256-bits SHA-2 cryptographic message digest of the file.
 166 .It Sy sha512
 167 The 512-bits SHA-2 cryptographic message digest of the file.
 168 .El
 169 .It Fl l Ar linkflags
 170 Instead of copying the file make a link to the source.
 171 The type of the link is determined by the
 172 .Ar linkflags
 173 argument.
 174 Valid
 175 .Ar linkflags
 176 are:
 177 .Ar a
 178 (absolute),
 179 .Ar r
 180 (relative),
 181 .Ar h
 182 (hard),
 183 .Ar s
 184 (symbolic),
 185 .Ar m
 186 (mixed).
 187 Absolute and relative have effect only for symbolic links.
 188 Mixed links
 189 are hard links for files on the same filesystem, symbolic otherwise.
 190 .It Fl M Ar metalog
 191 Write the metadata associated with each item installed to
 192 .Ar metalog
 193 in an
 194 .Xr mtree 8
 195 .Dq full path
 196 specification line.
 197 The metadata includes: the file name and file type, and depending upon
 198 other options, the owner, group, file flags, modification time, and tags.
 199 .It Fl m Ar mode
 200 Specify an alternate mode.
 201 The default mode is set to rwxr-xr-x (0755).
 202 The specified mode may be either an octal or symbolic value; see
 203 .Xr chmod 1
 204 for a description of possible mode values.
 205 .It Fl N Ar dbdir
 206 Use the user database text file
 207 .Pa master.passwd
 208 and group database text file
 209 .Pa group
 210 from
 211 .Ar dbdir ,
 212 rather than using the results from the system's
 213 .Xr getpwnam 3
 214 and
 215 .Xr getgrnam 3
 216 (and related) library calls.
 217 .It Fl o Ar owner
 218 Specify an owner.
 219 A numeric UID is allowed.
 220 .It Fl p
 221 Preserve the access and modification times.
 222 Copy the file, as if the
 223 .Fl C
 224 (compare and copy) option is specified,
 225 except if the target file does not already exist or is different,
 226 then preserve the access and modification times of the source file.
 227 .It Fl S
 228 Flush each file to disk after copying.
 229 This has a non-negligible impact on performance, but reduces the risk
 230 of being left with a partial file if the system crashes or loses power
 231 shortly after
 232 .Nm
 233 runs.
 234 .Pp
 235 Historically,
 236 .Fl S
 237 also enabled the use of temporary files to ensure atomicity when
 238 replacing an existing target.
 239 Temporary files are no longer optional.
 240 .It Fl s
 241 .Nm
 242 exec's the command
 243 .Xr strip 1
 244 to strip binaries so that
 245 .Nm
 246 can be portable over a large
 247 number of systems and binary types.
 248 See below for how
 249 .Nm
 250 can be instructed to use another program to strip binaries.
 251 .It Fl T Ar tags
 252 Specify the
 253 .Xr mtree 8
 254 tags to write out for the file when using
 255 .Fl M Ar metalog .
 256 .It Fl U
 257 Indicate that install is running unprivileged, and that it should not
 258 try to change the owner, the group, or the file flags of the destination.
 259 The information that would have been updated can be stored in a log
 260 file with
 261 .Fl M Ar metalog .
 262 .It Fl v
 263 Cause
 264 .Nm
 265 to be verbose,
 266 showing files as they are installed or backed up.
 267 .El
 268 .Pp
 269 By default,
 270 .Nm
 271 preserves all file flags, with the exception of the
 272 .Dq nodump
 273 flag.
 274 .Pp
 275 The
 276 .Nm
 277 utility attempts to prevent moving a file onto itself.
 278 .Pp
 279 Installing
 280 .Pa /dev/null
 281 creates an empty file.
 282 .Sh ENVIRONMENT
 283 The
 284 .Nm
 285 utility checks for the presence of the
 286 .Ev STRIPBIN
 287 environment variable and if present,
 288 uses the assigned value as the program to run if and when the
 289 .Fl s
 290 option has been specified.
 291 .Pp
 292 If the
 293 .Ev DONTSTRIP
 294 environment variable is present,
 295 .Nm
 296 will ignore any specification of the
 297 .Fl s
 298 option.
 299 This is mainly for use in debugging the
 300 .Fx
 301 Ports Collection.
 302 .Sh FILES
 303 .Bl -tag -width "INS@XXXXXX" -compact
 304 .It Pa INS@XXXXXX
 305 Temporary files named
 306 .Pa INS@XXXXXX ,
 307 where
 308 .Pa XXXXXX
 309 is decided by
 310 .Xr mkstemp 3 ,
 311 are created in the target directory.
 312 .El
 313 .Sh EXIT STATUS
 314 .Ex -std
 315 .Sh COMPATIBILITY
 316 Historically
 317 .Nm
 318 moved files by default.
 319 The default was changed to copy in
 320 .Fx 4.4 .
 321 .Sh SEE ALSO
 322 .Xr chflags 1 ,
 323 .Xr chgrp 1 ,
 324 .Xr chmod 1 ,
 325 .Xr cp 1 ,
 326 .Xr mv 1 ,
 327 .Xr strip 1 ,
 328 .Xr mmap 2 ,
 329 .Xr getgrnam 3 ,
 330 .Xr getpwnam 3 ,
 331 .Xr chown 8
 332 .Sh HISTORY
 333 The
 334 .Nm
 335 utility appeared in
 336 .Bx 4.2 .
 337 .Sh BUGS
 338 The meaning of the
 339 .Fl M
 340 option has changed as of
 341 .Fx 9.2
 342 and it now takes an argument.
 343 Command lines that used the old
 344 .Fl M
 345 will get an error or in rare cases will append logs to the first of
 346 multiple source files rather than installing it.
 347 .Pp
 348 Temporary files may be left in the target directory if
 349 .Nm
 350 exits abnormally.
 351 .Pp
 352 File flags cannot be set by
 353 .Xr fchflags 2
 354 over a NFS file system.
 355 Other file systems do not have a concept of flags.
 356 The
 357 .Nm
 358 utility will only warn when flags could not be set on a file system
 359 that does not support them.
 360 .Pp
 361 The
 362 .Nm
 363 utility with
 364 .Fl v
 365 falsely says a file is copied when
 366 .Fl C
 367 snaps hard links.