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