| blob | 15853539f851ac4a6a53d96533d0e19c5e557d11 |
1 .\" $NetBSD: install.1,v 1.43 2009/05/01 20:16:23 apb Exp $
2 .\"
3 .\" Copyright (c) 1987, 1990, 1993
4 .\" The Regents of the University of California. All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .\" @(#)install.1 8.1 (Berkeley) 6/6/93
31 .\"
32 .Dd May 1, 2009
33 .Dt INSTALL 1
34 .Os
35 .Sh NAME
36 .Nm install
37 .Nd install binaries
38 .Sh SYNOPSIS
39 .Nm
40 .Op Fl Ubcprs
41 .Bk -words
42 .Op Fl B Ar suffix
43 .Ek
44 .Bk -words
45 .Op Fl D Ar destdir
46 .Ek
47 .Bk -words
48 .Op Fl f Ar flags
49 .Ek
50 .Bk -words
51 .Op Fl M Ar metalog
52 .Ek
53 .Bk -words
54 .Op Fl T Ar tags
55 .Ek
56 .Bk -words
57 .Op Fl a Ar command
58 .Ek
59 .Bk -words
60 .Op Fl m Ar mode
61 .Ek
62 .Bk -words
63 .Op Fl N Ar dbdir
64 .Ek
65 .Bk -words
66 .Op Fl o Ar owner
67 .Ek
68 .Bk -words
69 .Op Fl g Ar group
70 .Ek
71 .Bk -words
72 .Op Fl l Ar linkflags
73 .Ek
74 .Bk -words
75 .Op Fl h Ar hash
76 .Ek
77 .Bk -words
78 .Op Fl S Ar stripflag
79 .Ek
80 .Ar file1 file2
81 .Nm
82 .Op Fl Ubcprs
83 .Bk -words
84 .Op Fl B Ar suffix
85 .Ek
86 .Bk -words
87 .Op Fl D Ar destdir
88 .Ek
89 .Bk -words
90 .Op Fl f Ar flags
91 .Ek
92 .Bk -words
93 .Op Fl M Ar metalog
94 .Ek
95 .Bk -words
96 .Op Fl T Ar tags
97 .Ek
98 .Bk -words
99 .Op Fl a Ar command
100 .Ek
101 .Bk -words
102 .Op Fl m Ar mode
103 .Ek
104 .Bk -words
105 .Op Fl N Ar dbdir
106 .Ek
107 .Bk -words
108 .Op Fl o Ar owner
109 .Ek
110 .Bk -words
111 .Op Fl g Ar group
112 .Ek
113 .Bk -words
114 .Op Fl l Ar linkflags
115 .Ek
116 .Bk -words
117 .Op Fl h Ar hash
118 .Ek
119 .Bk -words
120 .Op Fl S Ar stripflag
121 .Ek
122 .Ar file1 ...\&
123 .Ar fileN directory
124 .Nm
125 .Fl d
126 .Op Fl Up
127 .Bk -words
128 .Op Fl D Ar destdir
129 .Ek
130 .Bk -words
131 .Op Fl M Ar metalog
132 .Ek
133 .Bk -words
134 .Op Fl T Ar tags
135 .Ek
136 .Bk -words
137 .Op Fl a Ar command
138 .Ek
139 .Bk -words
140 .Op Fl m Ar mode
141 .Ek
142 .Bk -words
143 .Op Fl N Ar dbdir
144 .Ek
145 .Bk -words
146 .Op Fl o Ar owner
147 .Ek
148 .Bk -words
149 .Op Fl g Ar group
150 .Ek
151 .Ar directory ...\&
152 .Sh DESCRIPTION
153 The file(s) are copied
154 (or linked if the
155 .Fl l
156 option is specified) to the target file or directory.
157 If the destination is a directory, then the
158 .Ar file
159 is copied into
160 .Ar directory
161 with its original filename.
162 If the target file already exists, it is
163 either renamed to
164 .Ar file.old
165 if the
166 .Fl b
167 option is given
168 or overwritten
169 if permissions allow; an alternate backup suffix may be specified via the
170 .Fl B
171 option's argument.
172 .Pp
173 .Bl -tag -width Ds
174 .It Fl a Ar command
175 Run
176 .Ar command
177 on the target after installation and stripping
178 .Pq Fl s ,
179 but before
180 ownership, permissions or timestamps are set and before renaming
181 .Pq Fl r
182 occurs.
183 .Ar command
184 is invoked via the
185 .Xr sh 1
186 shell, allowing a single
187 .Fl a
188 argument be to specified to
189 .Nm
190 which the shell can then tokenize.
191 .It Fl b
192 Backup any existing files before overwriting them by renaming
193 them to
194 .Ar file.old . See
195 .Fl B
196 for specifying a different backup suffix.
197 .It Fl B Ar suffix
198 Use
199 .Ar suffix
200 as the backup suffix if
201 .Fl b
202 is given.
203 If
204 .Ar suffix
205 contains a '%' sign, a numbered backup will be performed, and the
206 %-pattern will be expanded using
207 .Xr sprintf 3 ,
208 given an integer counter as the backup number.
209 The counter used starts from 0, and the first available name resulting
210 from the expansion is used.
211 .It Fl c
212 Copy the file.
213 This is the default behavior; the flag is maintained for backwards
214 compatibility only.
215 .It Fl d
216 Create directories.
217 Missing parent directories are created as required.
218 .It Fl D Ar destdir
219 Specify the
220 .Ev DESTDIR
221 (top of the file hierarchy) that the items are installed in to.
222 If
223 .Fl M Ar metalog
224 is in use, a leading string of
225 .Dq Ar destdir
226 will be removed from the file names logged to the
227 .Ar metalog .
228 This option does not affect where the actual files are installed.
229 .It Fl f Ar flags
230 Specify the target's file flags.
231 (See
232 .Xr chflags 1
233 for a list of possible flags and their meanings.)
234 .It Fl g Ar group
235 Specify a group.
236 .It Fl h Ar hash
237 When copying, calculate the digest of the files with
238 .Ar hash
239 to store in the
240 .Fl M Ar metalog .
241 Supported digests:
242 .Bl -tag -width rmd160 -offset indent
243 .It Sy none
244 No hash.
245 This is the default.
246 .It Sy md5
247 The MD5 cryptographic message digest.
248 .It Sy rmd160
249 The RMD-160 cryptographic message digest.
250 .It Sy sha1
251 The SHA-1 cryptographic message digest.
252 .It Sy sha256
253 The 256-bits
254 .Tn SHA-2
255 cryptographic message digest of the file.
256 .It Sy sha384
257 The 384-bits
258 .Tn SHA-2
259 cryptographic message digest of the file.
260 .It Sy sha512
261 The 512-bits
262 .Tn SHA-2
263 cryptographic message digest of the file.
264 .El
265 .It Fl l Ar linkflags
266 Instead of copying the file make a link to the source.
267 The type of the link is determined by the
268 .Ar linkflags
269 argument.
270 Valid
271 .Ar linkflags
272 are:
273 .Ar a
274 (absolute),
275 .Ar r
276 (relative),
277 .Ar h
278 (hard),
279 .Ar s
280 (symbolic),
281 .Ar m
282 (mixed).
283 Absolute and relative have effect only for symbolic links.
284 Mixed links
285 are hard links for files on the same filesystem, symbolic otherwise.
286 .It Fl M Ar metalog
287 Write the metadata associated with each item installed to
288 .Ar metalog
289 in an
290 .Xr mtree 8
291 .Dq full path
292 specification line.
293 The metadata includes: the file name and file type, and depending upon
294 other options, the owner, group, file flags, modification time, and tags.
295 .It Fl m Ar mode
296 Specify an alternative mode.
297 The default mode is set to rwxr-xr-x (0755).
298 The specified mode may be either an octal or symbolic value; see
299 .Xr chmod 1
300 for a description of possible mode values.
301 .It Fl N Ar dbdir
302 Use the user database text file
303 .Pa master.passwd
304 and group database text file
305 .Pa group
306 from
307 .Ar dbdir ,
308 rather than using the results from the system's
309 .Xr getpwnam 3
310 and
311 .Xr getgrnam 3
312 (and related) library calls.
313 .It Fl o Ar owner
314 Specify an owner.
315 .It Fl p
316 Preserve the source files access and modification times.
317 .It Fl r
318 Install to a temporary file and then rename the file to its final destination
319 name.
320 This can be used for precious files, to avoid truncation of the original
321 when error conditions (filesystem full etc.) occur.
322 .It Fl s
323 .Nm
324 exec's the command
325 .Xr strip 1
326 to strip binaries so that install can be portable over a large
327 number of systems and binary types.
328 If the environment variable
329 .Ev STRIP
330 is set, it is used as the
331 .Xr strip 1
332 program.
333 .It Fl S Ar stripflags
334 .Nm
335 passes
336 .Ar stripflags
337 as option arguments to
338 .Xr strip 1 .
339 When
340 .Fl S
341 is used,
342 .Xr strip 1
343 is invoked via the
344 .Xr sh 1
345 shell, allowing a single
346 .Fl S
347 argument be to specified to
348 .Nm
349 which the shell can then tokenize.
350 Normally,
351 .Nm
352 invokes
353 .Xr strip 1
354 directly.
355 This flag implies
356 .Fl s .
357 .It Fl T Ar tags
358 Specify the
359 .Xr mtree 8
360 tags to write out for the file when using
361 .Fl M Ar metalog .
362 .It Fl U
363 Indicate that install is running unprivileged, and that it should not
364 try to change the owner, the group, or the file flags of the destination.
365 The information that would have been updated can be stored in a log
366 file with
367 .Fl M Ar metalog .
368 .El
369 .Pp
370 By default,
371 .Nm
372 preserves all file flags, with the exception of the ``nodump'' flag.
373 .Pp
374 The
375 .Nm
376 utility attempts to prevent copying a file onto itself.
377 .Pp
378 Installing
379 .Pa /dev/null
380 creates an empty file.
381 .Sh EXIT STATUS
382 The
383 .Nm
384 utility exits 0 on success,
385 and \*[Gt]0 if an error occurs.
386 .Sh ENVIRONMENT
387 .Bl -tag -width Fl
388 .It Ev STRIP
389 The program used to strip installed binaries when the
390 .Fl s
391 option is used.
392 If unspecified,
393 .Pa /usr/bin/strip
394 is used.
395 .El
396 .Sh SEE ALSO
397 .Xr chflags 1 ,
398 .Xr chgrp 1 ,
399 .Xr chmod 1 ,
400 .Xr cp 1 ,
401 .Xr mv 1 ,
402 .Xr strip 1 ,
403 .Xr chown 8 ,
404 .Xr mtree 8
405 .Sh HISTORY
406 The
407 .Nm
408 utility appeared in
409 .Bx 4.2 .