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 .\" $DragonFly: src/usr.bin/xinstall/install.1,v 1.6 2007/05/17 08:19:02 swildner Exp $
  35 .\"
  36 .Dd September 7, 2011
  37 .Dt INSTALL 1
  38 .Os
  39 .Sh NAME
  40 .Nm install
  41 .Nd install binaries
  42 .Sh SYNOPSIS
  43 .Nm
  44 .Op Fl bCclMpSsv
  45 .Op Fl L Ar etcdir
  46 .Op Fl B Ar suffix
  47 .Op Fl D Ar destdir
  48 .Op Fl f Ar flags
  49 .Op Fl g Ar group
  50 .Op Fl m Ar mode
  51 .Op Fl o Ar owner
  52 .Ar file1 file2
  53 .Nm
  54 .Op Fl bCclMpSsv
  55 .Op Fl L Ar etcdir
  56 .Op Fl B Ar suffix
  57 .Op Fl D Ar destdir
  58 .Op Fl f Ar flags
  59 .Op Fl g Ar group
  60 .Op Fl m Ar mode
  61 .Op Fl o Ar owner
  62 .Ar file1 ... fileN directory
  63 .Nm
  64 .Fl d
  65 .Op Fl D Ar destdir
  66 .Op Fl vl
  67 .Op Fl L Ar etcdir
  68 .Op Fl g Ar group
  69 .Op Fl m Ar mode
  70 .Op Fl o Ar owner
  71 .Ar directory ...
  72 .Sh DESCRIPTION
  73 The file(s) are copied
  74 to the target file or directory.
  75 If the destination is a directory, then the
  76 .Ar file
  77 is copied into
  78 .Ar directory
  79 with its original filename.
  80 If the target file already exists, it is
  81 either renamed to
  82 .Ar file Ns Pa .old
  83 if the
  84 .Fl b
  85 option is given
  86 or overwritten
  87 if permissions allow.
  88 An alternate backup suffix may be specified via the
  89 .Fl B
  90 option's argument.
  91 .Pp
  92 The options are as follows:
  93 .Bl -tag -width indent
  94 .It Fl b
  95 Back up any existing files before overwriting them by renaming
  96 them to
  97 .Ar file Ns Pa .old .
  98 See
  99 .Fl B
 100 for specifying a different backup suffix.
 101 .It Fl L Ar etcdir
 102 Specify the location of the /etc directory containing the group and password
 103 files.  The default is "/etc".  If an alternative directory is specified
 104 group and username lookups will be made from the alternative group and
 105 password files rather than the system group and password files.
 106 .It Fl B Ar suffix
 107 Use
 108 .Ar suffix
 109 as the backup suffix if
 110 .Fl b
 111 is given.
 112 .It Fl C
 113 Copy the file.
 114 If the target file already exists and the files are the same,
 115 then don't change the modification time of the target.
 116 .It Fl c
 117 Copy the file.
 118 This is actually the default.
 119 The
 120 .Fl c
 121 option is only included for backwards compatibility.
 122 .It Fl d
 123 Create directories.
 124 Missing parent directories are created as required.
 125 .It Fl D Ar destdir
 126 Specify the
 127 .Ev DESTDIR
 128 (top of the file hierarchy) that the items are installed in to.
 129 This option is implemented for compatibility with the NetBSD version
 130 of
 131 .Nm install
 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.