usr.bin/xinstall/install.1

   1 .\"     $NetBSD: install.1,v 1.47 2012/04/08 22:00:40 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 1987, 1990, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. Neither the name of the University nor the names of its contributors
  15 .\"    may be used to endorse or promote products derived from this software
  16 .\"    without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\"     @(#)install.1   8.1 (Berkeley) 6/6/93
  31 .\"
  32 .Dd May 1, 2009
  33 .Dt INSTALL 1
  34 .Os
  35 .Sh NAME
  36 .Nm install
  37 .Nd install binaries
  38 .Sh SYNOPSIS
  39 .Nm
  40 .Op Fl bcprsU
  41 .Op Fl a Ar command
  42 .Op Fl B Ar suffix
  43 .Op Fl D Ar destdir
  44 .Op Fl f Ar flags
  45 .Op Fl g Ar group
  46 .Op Fl h Ar hash
  47 .Op Fl l Ar linkflags
  48 .Op Fl M Ar metalog
  49 .Op Fl m Ar mode
  50 .Op Fl N Ar dbdir
  51 .Op Fl o Ar owner
  52 .Op Fl S Ar stripflag
  53 .Op Fl T Ar tags
  54 .Ar file1 file2
  55 .Nm
  56 .Op Fl bcprsU
  57 .Op Fl a Ar command
  58 .Op Fl B Ar suffix
  59 .Op Fl D Ar destdir
  60 .Op Fl f Ar flags
  61 .Op Fl g Ar group
  62 .Op Fl h Ar hash
  63 .Op Fl l Ar linkflags
  64 .Op Fl M Ar metalog
  65 .Op Fl m Ar mode
  66 .Op Fl N Ar dbdir
  67 .Op Fl o Ar owner
  68 .Op Fl S Ar stripflag
  69 .Op Fl T Ar tags
  70 .Ar file1 ...\&
  71 .Ar fileN directory
  72 .Nm
  73 .Fl d
  74 .Op Fl pU
  75 .Op Fl a Ar command
  76 .Op Fl D Ar destdir
  77 .Op Fl g Ar group
  78 .Op Fl M Ar metalog
  79 .Op Fl m Ar mode
  80 .Op Fl N Ar dbdir
  81 .Op Fl o Ar owner
  82 .Op Fl T Ar tags
  83 .Ar directory ...\&
  84 .Sh DESCRIPTION
  85 The file(s) are copied
  86 (or linked if the
  87 .Fl l
  88 option is specified) to the target file or directory.
  89 If the destination is a directory, then the
  90 .Ar file
  91 is copied into
  92 .Ar directory
  93 with its original filename.
  94 If the target file already exists, it is
  95 either renamed to
  96 .Ar file.old
  97 if the
  98 .Fl b
  99 option is given
 100 or overwritten
 101 if permissions allow; an alternate backup suffix may be specified via the
 102 .Fl B
 103 option's argument.
 104 .Pp
 105 .Bl -tag -width XsXXstripflagsXX
 106 .It Fl a Ar command
 107 Run
 108 .Ar command
 109 on the target after installation and stripping
 110 .Pq Fl s ,
 111 but before
 112 ownership, permissions or timestamps are set and before renaming
 113 .Pq Fl r
 114 occurs.
 115 .Ar command
 116 is invoked via the
 117 .Xr sh 1
 118 shell, allowing a single
 119 .Fl a
 120 argument be to specified to
 121 .Nm
 122 which the shell can then tokenize.
 123 .It Fl B Ar suffix
 124 Use
 125 .Ar suffix
 126 as the backup suffix if
 127 .Fl b
 128 is given.
 129 If
 130 .Ar suffix
 131 contains a '%' sign, a numbered backup will be performed, and the
 132 %-pattern will be expanded using
 133 .Xr sprintf 3 ,
 134 given an integer counter as the backup number.
 135 The counter used starts from 0, and the first available name resulting
 136 from the expansion is used.
 137 .It Fl b
 138 Backup any existing files before overwriting them by renaming
 139 them to
 140 .Ar file.old . See
 141 .Fl B
 142 for specifying a different backup suffix.
 143 .It Fl c
 144 Copy the file.
 145 This is the default behavior; the flag is maintained for backwards
 146 compatibility only.
 147 .It Fl D Ar destdir
 148 Specify the
 149 .Ev DESTDIR
 150 (top of the file hierarchy) that the items are installed in to.
 151 If
 152 .Fl M Ar metalog
 153 is in use, a leading string of
 154 .Dq Ar destdir
 155 will be removed from the file names logged to the
 156 .Ar metalog .
 157 This option does not affect where the actual files are installed.
 158 .It Fl d
 159 Create directories.
 160 Missing parent directories are created as required.
 161 .It Fl f Ar flags
 162 Specify the target's file flags.
 163 (See
 164 .Xr chflags 1
 165 for a list of possible flags and their meanings.)
 166 .It Fl g Ar group
 167 Specify a group.
 168 .It Fl h Ar hash
 169 When copying, calculate the digest of the files with
 170 .Ar hash
 171 to store in the
 172 .Fl M Ar metalog .
 173 Supported digests:
 174 .Bl -tag -width rmd160 -offset indent
 175 .It Sy none
 176 No hash.
 177 This is the default.
 178 .It Sy md5
 179 The MD5 cryptographic message digest.
 180 .It Sy rmd160
 181 The RMD-160 cryptographic message digest.
 182 .It Sy sha1
 183 The SHA-1 cryptographic message digest.
 184 .It Sy sha256
 185 The 256-bits
 186 .Tn SHA-2
 187 cryptographic message digest of the file.
 188 .It Sy sha384
 189 The 384-bits
 190 .Tn SHA-2
 191 cryptographic message digest of the file.
 192 .It Sy sha512
 193 The 512-bits
 194 .Tn SHA-2
 195 cryptographic message digest of the file.
 196 .El
 197 .It Fl l Ar linkflags
 198 Instead of copying the file make a link to the source.
 199 The type of the link is determined by the
 200 .Ar linkflags
 201 argument.
 202 Valid
 203 .Ar linkflags
 204 are:
 205 .Ar a
 206 (absolute),
 207 .Ar r
 208 (relative),
 209 .Ar h
 210 (hard),
 211 .Ar s
 212 (symbolic),
 213 .Ar m
 214 (mixed).
 215 Absolute and relative have effect only for symbolic links.
 216 Mixed links
 217 are hard links for files on the same filesystem, symbolic otherwise.
 218 .It Fl M Ar metalog
 219 Write the metadata associated with each item installed to
 220 .Ar metalog
 221 in an
 222 .Xr mtree 8
 223 .Dq full path
 224 specification line.
 225 The metadata includes: the file name and file type, and depending upon
 226 other options, the owner, group, file flags, modification time, and tags.
 227 .It Fl m Ar mode
 228 Specify an alternative mode.
 229 The default mode is set to rwxr-xr-x (0755).
 230 The specified mode may be either an octal or symbolic value; see
 231 .Xr chmod 1
 232 for a description of possible mode values.
 233 .It Fl N Ar dbdir
 234 Use the user database text file
 235 .Pa master.passwd
 236 and group database text file
 237 .Pa group
 238 from
 239 .Ar dbdir ,
 240 rather than using the results from the system's
 241 .Xr getpwnam 3
 242 and
 243 .Xr getgrnam 3
 244 (and related) library calls.
 245 .It Fl o Ar owner
 246 Specify an owner.
 247 .It Fl p
 248 Preserve the source files access and modification times.
 249 .It Fl r
 250 Install to a temporary file and then rename the file to its final destination
 251 name.
 252 This can be used for precious files, to avoid truncation of the original
 253 when error conditions (filesystem full etc.) occur.
 254 .It Fl S Ar stripflags
 255 .Nm
 256 passes
 257 .Ar stripflags
 258 as option arguments to
 259 .Xr strip 1 .
 260 When
 261 .Fl S
 262 is used,
 263 .Xr strip 1
 264 is invoked via the
 265 .Xr sh 1
 266 shell, allowing a single
 267 .Fl S
 268 argument be to specified to
 269 .Nm
 270 which the shell can then tokenize.
 271 Normally,
 272 .Nm
 273 invokes
 274 .Xr strip 1
 275 directly.
 276 This flag implies
 277 .Fl s .
 278 .It Fl s
 279 .Nm
 280 exec's the command
 281 .Xr strip 1
 282 to strip binaries so that install can be portable over a large
 283 number of systems and binary types.
 284 If the environment variable
 285 .Ev STRIP
 286 is set, it is used as the
 287 .Xr strip 1
 288 program.
 289 .It Fl T Ar tags
 290 Specify the
 291 .Xr mtree 8
 292 tags to write out for the file when using
 293 .Fl M Ar metalog .
 294 .It Fl U
 295 Indicate that install is running unprivileged, and that it should not
 296 try to change the owner, the group, or the file flags of the destination.
 297 The information that would have been updated can be stored in a log
 298 file with
 299 .Fl M Ar metalog .
 300 .El
 301 .Pp
 302 By default,
 303 .Nm
 304 preserves all file flags, with the exception of the ``nodump'' flag.
 305 .Pp
 306 The
 307 .Nm
 308 utility attempts to prevent copying a file onto itself.
 309 .Pp
 310 Installing
 311 .Pa /dev/null
 312 creates an empty file.
 313 .Sh ENVIRONMENT
 314 .Bl -tag -width Fl
 315 .It Ev STRIP
 316 The program used to strip installed binaries when the
 317 .Fl s
 318 option is used.
 319 If unspecified,
 320 .Pa /usr/bin/strip
 321 is used.
 322 .El
 323 .Sh EXIT STATUS
 324 .Ex -std
 325 .Sh SEE ALSO
 326 .Xr chflags 1 ,
 327 .Xr chgrp 1 ,
 328 .Xr chmod 1 ,
 329 .Xr cp 1 ,
 330 .Xr mv 1 ,
 331 .Xr strip 1 ,
 332 .Xr chown 8 ,
 333 .Xr mtree 8
 334 .Sh HISTORY
 335 The
 336 .Nm
 337 utility appeared in
 338 .Bx 4.2 .