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.2 2003/06/17 04:29:34 dillon Exp $
  35 .\"
  36 .Dd May 7, 2001
  37 .Dt INSTALL 1
  38 .Os
  39 .Sh NAME
  40 .Nm install
  41 .Nd install binaries
  42 .Sh SYNOPSIS
  43 .Nm
  44 .Op Fl bCcMpSsv
  45 .Op Fl B Ar suffix
  46 .Op Fl f Ar flags
  47 .Op Fl g Ar group
  48 .Op Fl m Ar mode
  49 .Op Fl o Ar owner
  50 .Ar file1 file2
  51 .Nm
  52 .Op Fl bCcMpSsv
  53 .Op Fl B Ar suffix
  54 .Op Fl f Ar flags
  55 .Op Fl g Ar group
  56 .Op Fl m Ar mode
  57 .Op Fl o Ar owner
  58 .Ar file1 ... fileN directory
  59 .Nm
  60 .Fl d
  61 .Op Fl v
  62 .Op Fl g Ar group
  63 .Op Fl m Ar mode
  64 .Op Fl o Ar owner
  65 .Ar directory ...
  66 .Sh DESCRIPTION
  67 The file(s) are copied
  68 to the target file or directory.
  69 If the destination is a directory, then the
  70 .Ar file
  71 is copied into
  72 .Ar directory
  73 with its original filename.
  74 If the target file already exists, it is
  75 either renamed to
  76 .Ar file Ns Pa .old
  77 if the
  78 .Fl b
  79 option is given
  80 or overwritten
  81 if permissions allow.
  82 An alternate backup suffix may be specified via the
  83 .Fl B
  84 option's argument.
  85 .Pp
  86 The options are as follows:
  87 .Bl -tag -width indent
  88 .It Fl b
  89 Back up any existing files before overwriting them by renaming
  90 them to
  91 .Ar file Ns Pa .old .
  92 See
  93 .Fl B
  94 for specifying a different backup suffix.
  95 .It Fl B Ar suffix
  96 Use
  97 .Ar suffix
  98 as the backup suffix if
  99 .Fl b
 100 is given.
 101 .It Fl C
 102 Copy the file.
 103 If the target file already exists and the files are the same,
 104 then don't change the modification time of the target.
 105 .It Fl c
 106 Copy the file.
 107 This is actually the default.
 108 The
 109 .Fl c
 110 option is only included for backwards compatibility.
 111 .It Fl d
 112 Create directories.
 113 Missing parent directories are created as required.
 114 .It Fl f
 115 Specify the target's file flags; see
 116 .Xr chflags 1
 117 for a list of possible flags and their meanings.
 118 .It Fl g
 119 Specify a group.
 120 A numeric GID is allowed.
 121 .It Fl M
 122 Disable all use of
 123 .Xr mmap 2 .
 124 .It Fl m
 125 Specify an alternate mode.
 126 The default mode is set to rwxr-xr-x (0755).
 127 The specified mode may be either an octal or symbolic value; see
 128 .Xr chmod 1
 129 for a description of possible mode values.
 130 .It Fl o
 131 Specify an owner.
 132 A numeric UID is allowed.
 133 .It Fl p
 134 Preserve the modification time.
 135 Copy the file, as if the
 136 .Fl C
 137 (compare and copy) option is specified,
 138 except if the target file doesn't already exist or is different,
 139 then preserve the modification time of the file.
 140 .It Fl S
 141 Safe copy.
 142 Normally,
 143 .Nm
 144 unlinks an existing target before installing the new file.
 145 With the
 146 .Fl S
 147 flag a temporary file is used and then renamed to be
 148 the target.
 149 The reason this is safer is that if the copy or
 150 rename fails, the existing target is left untouched.
 151 .It Fl s
 152 .Nm
 153 exec's the command
 154 .Xr strip 1
 155 to strip binaries so that
 156 .Nm
 157 can be portable over a large
 158 number of systems and binary types.
 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 DIAGNOSTICS
 180 .Ex -std
 181 .Sh FILES
 182 .Bl -tag -width INS@XXXX -compact
 183 .It Pa INS@XXXX
 184 If either
 185 .Fl S
 186 option is specified, or the
 187 .Fl C
 188 or
 189 .Fl p
 190 option is used in conjuction with the
 191 .Fl s
 192 option, temporary files named
 193 .Pa INS@XXXX ,
 194 where
 195 .Pa XXXX
 196 is decided by
 197 .Xr mkstemp 3 ,
 198 are created in the target directory.
 199 .El
 200 .Sh COMPATIBILITY
 201 Historically
 202 .Nm
 203 moved files by default.
 204 The default was changed to copy in
 205 .Fx 4.4 .
 206 .Sh SEE ALSO
 207 .Xr chflags 1 ,
 208 .Xr chgrp 1 ,
 209 .Xr chmod 1 ,
 210 .Xr cp 1 ,
 211 .Xr mv 1 ,
 212 .Xr strip 1 ,
 213 .Xr mmap 2 ,
 214 .Xr chown 8
 215 .Sh HISTORY
 216 The
 217 .Nm
 218 utility appeared in
 219 .Bx 4.2 .
 220 .Sh BUGS
 221 Temporary files may be left in the target directory if
 222 .Nm
 223 exits abnormally.
 224 .Pp
 225 File flags cannot be set by
 226 .Xr fchflags 2
 227 over a NFS filesystem.  Other filesystems do not have a concept of flags.
 228 The
 229 .Nm
 230 utility will only warn when flags could not be set on a filesystem
 231 that does not support them.
 232 .Pp
 233 The
 234 .Nm
 235 utility with
 236 .Fl v
 237 falsely says a file is copied when
 238 .Fl C
 239 snaps hard links.