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 August 4, 2022 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 230Safe copy. 231Normally, 232.Nm 233unlinks an existing target before installing the new file. 234With the 235.Fl S 236flag a temporary file is used and then renamed to be 237the target. 238The reason this is safer is that if the copy or 239rename fails, the existing target is left untouched. 240.It Fl s 241.Nm 242exec's the command 243.Xr strip 1 244to strip binaries so that 245.Nm 246can be portable over a large 247number of systems and binary types. 248See below for how 249.Nm 250can be instructed to use another program to strip binaries. 251.It Fl T Ar tags 252Specify the 253.Xr mtree 8 254tags to write out for the file when using 255.Fl M Ar metalog . 256.It Fl U 257Indicate that install is running unprivileged, and that it should not 258try to change the owner, the group, or the file flags of the destination. 259The information that would have been updated can be stored in a log 260file with 261.Fl M Ar metalog . 262.It Fl v 263Cause 264.Nm 265to be verbose, 266showing files as they are installed or backed up. 267.El 268.Pp 269By default, 270.Nm 271preserves all file flags, with the exception of the 272.Dq nodump 273flag. 274.Pp 275The 276.Nm 277utility attempts to prevent moving a file onto itself. 278.Pp 279Installing 280.Pa /dev/null 281creates an empty file. 282.Sh ENVIRONMENT 283The 284.Nm 285utility checks for the presence of the 286.Ev STRIPBIN 287environment variable and if present, 288uses the assigned value as the program to run if and when the 289.Fl s 290option has been specified. 291.Pp 292If the 293.Ev DONTSTRIP 294environment variable is present, 295.Nm 296will ignore any specification of the 297.Fl s 298option. 299This is mainly for use in debugging the 300.Fx 301Ports Collection. 302.Sh FILES 303.Bl -tag -width "INS@XXXXXX" -compact 304.It Pa INS@XXXXXX 305If either 306.Fl S 307option is specified, or the 308.Fl C 309or 310.Fl p 311option is used in conjunction with the 312.Fl s 313option, temporary files named 314.Pa INS@XXXXXX , 315where 316.Pa XXXXXX 317is decided by 318.Xr mkstemp 3 , 319are created in the target directory. 320.El 321.Sh EXIT STATUS 322.Ex -std 323.Sh COMPATIBILITY 324Historically 325.Nm 326moved files by default. 327The default was changed to copy in 328.Fx 4.4 . 329.Sh SEE ALSO 330.Xr chflags 1 , 331.Xr chgrp 1 , 332.Xr chmod 1 , 333.Xr cp 1 , 334.Xr mv 1 , 335.Xr strip 1 , 336.Xr mmap 2 , 337.Xr getgrnam 3 , 338.Xr getpwnam 3 , 339.Xr chown 8 340.Sh HISTORY 341The 342.Nm 343utility appeared in 344.Bx 4.2 . 345.Sh BUGS 346The meaning of the 347.Fl M 348option has changed as of 349.Fx 9.2 350and it now takes an argument. 351Command lines that used the old 352.Fl M 353will get an error or in rare cases will append logs to the first of 354multiple source files rather than installing it. 355.Pp 356Temporary files may be left in the target directory if 357.Nm 358exits abnormally. 359.Pp 360File flags cannot be set by 361.Xr fchflags 2 362over a NFS file system. 363Other file systems do not have a concept of flags. 364The 365.Nm 366utility will only warn when flags could not be set on a file system 367that does not support them. 368.Pp 369The 370.Nm 371utility with 372.Fl v 373falsely says a file is copied when 374.Fl C 375snaps hard links. 376