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