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. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. 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 .\"     From: @(#)install.1     8.1 (Berkeley) 6/6/93
  33 .\" $FreeBSD: src/usr.bin/xinstall/install.1,v 1.16.2.9 2002/07/01 21:01:23 des Exp $
  34 .\"
  35 .Dd September 7, 2011
  36 .Dt INSTALL 1
  37 .Os
  38 .Sh NAME
  39 .Nm install
  40 .Nd install binaries
  41 .Sh SYNOPSIS
  42 .Nm
  43 .Op Fl bCclMpSsv
  44 .Op Fl B Ar suffix
  45 .Op Fl D Ar destdir
  46 .Op Fl L Ar etcdir
  47 .Op Fl f Ar flags
  48 .Op Fl g Ar group
  49 .Op Fl m Ar mode
  50 .Op Fl o Ar owner
  51 .Ar file1 file2
  52 .Nm
  53 .Op Fl bCclMpSsv
  54 .Op Fl B Ar suffix
  55 .Op Fl D Ar destdir
  56 .Op Fl L Ar etcdir
  57 .Op Fl f Ar flags
  58 .Op Fl g Ar group
  59 .Op Fl m Ar mode
  60 .Op Fl o Ar owner
  61 .Ar file1 ... fileN directory
  62 .Nm
  63 .Fl d
  64 .Op Fl vl
  65 .Op Fl D Ar destdir
  66 .Op Fl L Ar etcdir
  67 .Op Fl g Ar group
  68 .Op Fl m Ar mode
  69 .Op Fl o Ar owner
  70 .Ar directory ...
  71 .Sh DESCRIPTION
  72 The file(s) are copied
  73 to the target file or directory.
  74 If the destination is a directory, then the
  75 .Ar file
  76 is copied into
  77 .Ar directory
  78 with its original filename.
  79 If the target file already exists, it is
  80 either renamed to
  81 .Ar file Ns Pa .old
  82 if the
  83 .Fl b
  84 option is given
  85 or overwritten
  86 if permissions allow.
  87 An alternate backup suffix may be specified via the
  88 .Fl B
  89 option's argument.
  90 .Pp
  91 The options are as follows:
  92 .Bl -tag -width indent
  93 .It Fl b
  94 Back up any existing files before overwriting them by renaming
  95 them to
  96 .Ar file Ns Pa .old .
  97 See
  98 .Fl B
  99 for specifying a different backup suffix.
 100 .It Fl L Ar etcdir
 101 Specify the location of the /etc directory containing the group and password
 102 files.  The default is "/etc".  If an alternative directory is specified
 103 group and username lookups will be made from the alternative group and
 104 password files rather than the system group and password files.
 105 .It Fl B Ar suffix
 106 Use
 107 .Ar suffix
 108 as the backup suffix if
 109 .Fl b
 110 is given.
 111 .It Fl C
 112 Copy the file.
 113 If the target file already exists and the files are the same,
 114 then don't change the modification time of the target.
 115 .It Fl c
 116 Copy the file.
 117 This is actually the default.
 118 The
 119 .Fl c
 120 option is only included for backwards compatibility.
 121 .It Fl d
 122 Create directories.
 123 Missing parent directories are created as required.
 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 This option is implemented for compatibility with the
 129 .Nx
 130 version of
 131 .Nm
 132 and does nothing.
 133 .It Fl f
 134 Specify the target's file flags; see
 135 .Xr chflags 1
 136 for a list of possible flags and their meanings.
 137 .It Fl g
 138 Specify a group.
 139 A numeric GID is allowed.
 140 .It Fl l
 141 When the
 142 .Fl L
 143 option is specified and the owner or group cannot be found, fallback to
 144 system files.
 145 .It Fl M
 146 Disable all use of
 147 .Xr mmap 2 .
 148 .It Fl m
 149 Specify an alternate mode.
 150 The default mode is set to rwxr-xr-x (0755).
 151 The specified mode may be either an octal or symbolic value; see
 152 .Xr chmod 1
 153 for a description of possible mode values.
 154 .It Fl o
 155 Specify an owner.
 156 A numeric UID is allowed.
 157 .It Fl p
 158 Preserve the modification time.
 159 Copy the file, as if the
 160 .Fl C
 161 (compare and copy) option is specified,
 162 except if the target file doesn't already exist or is different,
 163 then preserve the modification time of the file.
 164 .It Fl S
 165 Safe copy.
 166 Normally,
 167 .Nm
 168 unlinks an existing target before installing the new file.
 169 With the
 170 .Fl S
 171 flag a temporary file is used and then renamed to be
 172 the target.
 173 The reason this is safer is that if the copy or
 174 rename fails, the existing target is left untouched.
 175 .It Fl s
 176 .Nm
 177 exec's the command
 178 .Xr strip 1
 179 to strip binaries so that
 180 .Nm
 181 can be portable over a large
 182 number of systems and binary types.
 183 .It Fl v
 184 Cause
 185 .Nm
 186 to be verbose,
 187 showing files as they are installed or backed up.
 188 .El
 189 .Pp
 190 By default,
 191 .Nm
 192 preserves all file flags, with the exception of the
 193 .Dq nodump
 194 flag.
 195 .Pp
 196 The
 197 .Nm
 198 utility attempts to prevent moving a file onto itself.
 199 .Pp
 200 Installing
 201 .Pa /dev/null
 202 creates an empty file.
 203 .Sh FILES
 204 .Bl -tag -width INS@XXXX -compact
 205 .It Pa INS@XXXX
 206 If either
 207 .Fl S
 208 option is specified, or the
 209 .Fl C
 210 or
 211 .Fl p
 212 option is used in conjunction with the
 213 .Fl s
 214 option, temporary files named
 215 .Pa INS@XXXX ,
 216 where
 217 .Pa XXXX
 218 is decided by
 219 .Xr mkstemp 3 ,
 220 are created in the target directory.
 221 .El
 222 .Sh EXIT STATUS
 223 .Ex -std
 224 .Sh COMPATIBILITY
 225 Historically
 226 .Nm
 227 moved files by default.
 228 The default was changed to copy in
 229 .Fx 4.4 .
 230 .Sh SEE ALSO
 231 .Xr chflags 1 ,
 232 .Xr chgrp 1 ,
 233 .Xr chmod 1 ,
 234 .Xr cp 1 ,
 235 .Xr mv 1 ,
 236 .Xr strip 1 ,
 237 .Xr mmap 2 ,
 238 .Xr chown 8
 239 .Sh HISTORY
 240 The
 241 .Nm
 242 utility appeared in
 243 .Bx 4.2 .
 244 .Sh BUGS
 245 Temporary files may be left in the target directory if
 246 .Nm
 247 exits abnormally.
 248 .Pp
 249 File flags cannot be set by
 250 .Xr fchflags 2
 251 over a NFS filesystem.  Other filesystems do not have a concept of flags.
 252 The
 253 .Nm
 254 utility will only warn when flags could not be set on a filesystem
 255 that does not support them.
 256 .Pp
 257 The
 258 .Nm
 259 utility with
 260 .Fl v
 261 falsely says a file is copied when
 262 .Fl C
 263 snaps hard links.