bin/xinstall/install.1

   1 .\"     $OpenBSD: install.1,v 1.30 2016/05/13 17:51:15 jmc Exp $
   2 .\"     $NetBSD: install.1,v 1.4 1994/11/14 04:57:17 jtc Exp $
   3 .\"
   4 .\" Copyright (c) 1987, 1990, 1993
   5 .\"     The Regents of the University of California.  All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\" 3. Neither the name of the University nor the names of its contributors
  16 .\"    may be used to endorse or promote products derived from this software
  17 .\"    without specific prior written permission.
  18 .\"
  19 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  20 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  21 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  22 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  23 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  24 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  25 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  26 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  27 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  28 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  29 .\" SUCH DAMAGE.
  30 .\"
  31 .\"     @(#)install.1   8.1 (Berkeley) 6/6/93
  32 .\"
  33 .Dd $Mdocdate: May 13 2016 $
  34 .Dt INSTALL 1
  35 .Os
  36 .Sh NAME
  37 .Nm install
  38 .Nd install binaries
  39 .Sh SYNOPSIS
  40 .Nm install
  41 .Op Fl bCcDdFpSs
  42 .Op Fl B Ar suffix
  43 .Op Fl g Ar group
  44 .Op Fl m Ar mode
  45 .Op Fl o Ar owner
  46 .Ar source ... target ...
  47 .Sh DESCRIPTION
  48 The
  49 .Ar source
  50 file(s) are copied to the
  51 .Ar target
  52 file or directory.
  53 If the
  54 .Ar target
  55 file already exists, it is either renamed to
  56 .Ar file.old
  57 if the
  58 .Fl b
  59 option is given
  60 or overwritten
  61 if permissions allow.
  62 An alternate backup suffix may be specified via the
  63 .Fl B
  64 option's argument.
  65 If the
  66 .Fl d
  67 option is given,
  68 .Ar target
  69 directories are created, and no files are copied.
  70 .Pp
  71 The options are as follows:
  72 .Bl -tag -width "-B suffix"
  73 .It Fl B Ar suffix
  74 Use
  75 .Ar suffix
  76 as the backup suffix if
  77 .Fl b
  78 is given.
  79 .It Fl b
  80 Backup any existing files before overwriting them by renaming
  81 them to
  82 .Ar file.old .
  83 See
  84 .Fl B
  85 for specifying a different backup suffix.
  86 .It Fl C
  87 Copy the file.
  88 If the target file already exists and the files are the same,
  89 then don't change the modification time of the target.
  90 .It Fl c
  91 Copy the file.
  92 This is actually the default.
  93 The
  94 .Fl c
  95 option is only included for backwards compatibility.
  96 .It Fl D
  97 Create all leading components of the target before installing into it.
  98 .It Fl d
  99 Create directories.
 100 Missing parent directories are created as required.
 101 This option cannot be used with the
 102 .Fl B , b , C , c ,
 103 .Fl p , S ,
 104 or
 105 .Fl s
 106 options.
 107 .It Fl F
 108 Flush the file's contents to disk.
 109 When copying a file, use the
 110 .Xr fsync 2
 111 function to synchronize the installed file's contents with the
 112 on-disk version.
 113 .It Fl g Ar group
 114 Specify a
 115 .Ar group .
 116 A numeric GID is allowed.
 117 .It Fl m Ar mode
 118 Specify an alternate
 119 .Ar mode .
 120 The default mode is set to 0755.
 121 The specified mode must be an octal value; see
 122 .Xr chmod 1
 123 for a description of possible mode values.
 124 .It Fl o Ar owner
 125 Specify an
 126 .Ar owner .
 127 A numeric UID is allowed.
 128 .It Fl p
 129 Preserve the modification time.
 130 Copy the file, as if the
 131 .Fl C
 132 (compare and copy) option is specified,
 133 except if the target file doesn't already exist or is different,
 134 then preserve the modification time of the file.
 135 .It Fl S
 136 Safe copy.
 137 Normally,
 138 .Nm
 139 unlinks an existing target before installing the new file.
 140 With the
 141 .Fl S
 142 flag a temporary file is used and then renamed to be
 143 the target.
 144 The reason this is safer is that if the copy or
 145 rename fails, the existing target is left untouched.
 146 .It Fl s
 147 .Nm
 148 exec's the command
 149 .Pa /usr/bin/strip
 150 to strip binaries so that install can be portable over a large
 151 number of systems and binary types.
 152 If the environment variable
 153 .Ev STRIP
 154 is set, it is used instead.
 155 .El
 156 .Pp
 157 The
 158 .Nm
 159 utility attempts to prevent moving a file onto itself.
 160 .Pp
 161 Installing
 162 .Pa /dev/null
 163 creates an empty file.
 164 .Sh ENVIRONMENT
 165 .Bl -tag -width "STRIP"
 166 .It Ev STRIP
 167 For an alternate
 168 .Xr strip 1
 169 program to run.
 170 Default is
 171 .Pa /usr/bin/strip .
 172 .El
 173 .Sh FILES
 174 .Bl -tag -width INS@XXXXXXXXXX -compact
 175 .It Pa INS@XXXXXXXXXX
 176 If either
 177 .Fl S
 178 option is specified, or the
 179 .Fl C
 180 or
 181 .Fl p
 182 option is used in conjunction with the
 183 .Fl s
 184 option, temporary files named INS@XXXXXXXXXX,
 185 where XXXXXXXXXX is decided by
 186 .Xr mkstemp 3 ,
 187 are created in the target directory.
 188 .El
 189 .Sh EXIT STATUS
 190 .Ex -std install
 191 .Sh SEE ALSO
 192 .Xr chgrp 1 ,
 193 .Xr chmod 1 ,
 194 .Xr cp 1 ,
 195 .Xr mv 1 ,
 196 .Xr strip 1 ,
 197 .Xr chown 8
 198 .Sh HISTORY
 199 The
 200 .Nm
 201 utility appeared in
 202 .Bx 4.2 .
 203 .Sh CAVEATS
 204 The
 205 .Fl C ,
 206 .Fl D ,
 207 .Fl F ,
 208 .Fl p ,
 209 and
 210 .Fl S
 211 flags are non-standard and should not be relied upon for portability.
 212 .Pp
 213 Temporary files may be left in the target directory if
 214 .Nm
 215 exits abnormally.