| blob | b6e2a5a29ef0d7868398dc1d83b8f167172a05da |
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.