1.\"	$NetBSD: install.1,v 1.47 2012/04/08 22:00:40 wiz 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 bcprsU
41.Op Fl a Ar command
42.Op Fl B Ar suffix
43.Op Fl D Ar destdir
44.Op Fl f Ar flags
45.Op Fl g Ar group
46.Op Fl h Ar hash
47.Op Fl l Ar linkflags
48.Op Fl M Ar metalog
49.Op Fl m Ar mode
50.Op Fl N Ar dbdir
51.Op Fl o Ar owner
52.Op Fl S Ar stripflag
53.Op Fl T Ar tags
54.Ar file1 file2
55.Nm
56.Op Fl bcprsU
57.Op Fl a Ar command
58.Op Fl B Ar suffix
59.Op Fl D Ar destdir
60.Op Fl f Ar flags
61.Op Fl g Ar group
62.Op Fl h Ar hash
63.Op Fl l Ar linkflags
64.Op Fl M Ar metalog
65.Op Fl m Ar mode
66.Op Fl N Ar dbdir
67.Op Fl o Ar owner
68.Op Fl S Ar stripflag
69.Op Fl T Ar tags
70.Ar file1 ...\&
71.Ar fileN directory
72.Nm
73.Fl d
74.Op Fl pU
75.Op Fl a Ar command
76.Op Fl D Ar destdir
77.Op Fl g Ar group
78.Op Fl M Ar metalog
79.Op Fl m Ar mode
80.Op Fl N Ar dbdir
81.Op Fl o Ar owner
82.Op Fl T Ar tags
83.Ar directory ...\&
84.Sh DESCRIPTION
85The file(s) are copied
86(or linked if the
87.Fl l
88option is specified) to the target file or directory.
89If the destination is a directory, then the
90.Ar file
91is copied into
92.Ar directory
93with its original filename.
94If the target file already exists, it is
95either renamed to
96.Ar file.old
97if the
98.Fl b
99option is given
100or overwritten
101if permissions allow; an alternate backup suffix may be specified via the
102.Fl B
103option's argument.
104.Pp
105.Bl -tag -width XsXXstripflagsXX
106.It Fl a Ar command
107Run
108.Ar command
109on the target after installation and stripping
110.Pq Fl s ,
111but before
112ownership, permissions or timestamps are set and before renaming
113.Pq Fl r
114occurs.
115.Ar command
116is invoked via the
117.Xr sh 1
118shell, allowing a single
119.Fl a
120argument be to specified to
121.Nm
122which the shell can then tokenize.
123.It Fl B Ar suffix
124Use
125.Ar suffix
126as the backup suffix if
127.Fl b
128is given.
129If
130.Ar suffix
131contains a '%' sign, a numbered backup will be performed, and the
132%-pattern will be expanded using
133.Xr sprintf 3 ,
134given an integer counter as the backup number.
135The counter used starts from 0, and the first available name resulting
136from the expansion is used.
137.It Fl b
138Backup any existing files before overwriting them by renaming
139them to
140.Ar file.old . See
141.Fl B
142for specifying a different backup suffix.
143.It Fl c
144Copy the file.
145This is the default behavior; the flag is maintained for backwards
146compatibility only.
147.It Fl D Ar destdir
148Specify the
149.Ev DESTDIR
150(top of the file hierarchy) that the items are installed in to.
151If
152.Fl M Ar metalog
153is in use, a leading string of
154.Dq Ar destdir
155will be removed from the file names logged to the
156.Ar metalog .
157This option does not affect where the actual files are installed.
158.It Fl d
159Create directories.
160Missing parent directories are created as required.
161.It Fl f Ar flags
162Specify the target's file flags.
163(See
164.Xr chflags 1
165for a list of possible flags and their meanings.)
166.It Fl g Ar group
167Specify a group.
168.It Fl h Ar hash
169When copying, calculate the digest of the files with
170.Ar hash
171to store in the
172.Fl M Ar metalog .
173Supported digests:
174.Bl -tag -width rmd160 -offset indent
175.It Sy none
176No hash.
177This is the default.
178.It Sy md5
179The MD5 cryptographic message digest.
180.It Sy rmd160
181The RMD-160 cryptographic message digest.
182.It Sy sha1
183The SHA-1 cryptographic message digest.
184.It Sy sha256
185The 256-bits
186.Tn SHA-2
187cryptographic message digest of the file.
188.It Sy sha384
189The 384-bits
190.Tn SHA-2
191cryptographic message digest of the file.
192.It Sy sha512
193The 512-bits
194.Tn SHA-2
195cryptographic message digest of the file.
196.El
197.It Fl l Ar linkflags
198Instead of copying the file make a link to the source.
199The type of the link is determined by the
200.Ar linkflags
201argument.
202Valid
203.Ar linkflags
204are:
205.Ar a
206(absolute),
207.Ar r
208(relative),
209.Ar h
210(hard),
211.Ar s
212(symbolic),
213.Ar m
214(mixed).
215Absolute and relative have effect only for symbolic links.
216Mixed links
217are hard links for files on the same filesystem, symbolic otherwise.
218.It Fl M Ar metalog
219Write the metadata associated with each item installed to
220.Ar metalog
221in an
222.Xr mtree 8
223.Dq full path
224specification line.
225The metadata includes: the file name and file type, and depending upon
226other options, the owner, group, file flags, modification time, and tags.
227.It Fl m Ar mode
228Specify an alternative mode.
229The default mode is set to rwxr-xr-x (0755).
230The specified mode may be either an octal or symbolic value; see
231.Xr chmod 1
232for a description of possible mode values.
233.It Fl N Ar dbdir
234Use the user database text file
235.Pa master.passwd
236and group database text file
237.Pa group
238from
239.Ar dbdir ,
240rather than using the results from the system's
241.Xr getpwnam 3
242and
243.Xr getgrnam 3
244(and related) library calls.
245.It Fl o Ar owner
246Specify an owner.
247.It Fl p
248Preserve the source files access and modification times.
249.It Fl r
250Install to a temporary file and then rename the file to its final destination
251name.
252This can be used for precious files, to avoid truncation of the original
253when error conditions (filesystem full etc.) occur.
254.It Fl S Ar stripflags
255.Nm
256passes
257.Ar stripflags
258as option arguments to
259.Xr strip 1 .
260When
261.Fl S
262is used,
263.Xr strip 1
264is invoked via the
265.Xr sh 1
266shell, allowing a single
267.Fl S
268argument be to specified to
269.Nm
270which the shell can then tokenize.
271Normally,
272.Nm
273invokes
274.Xr strip 1
275directly.
276This flag implies
277.Fl s .
278.It Fl s
279.Nm
280exec's the command
281.Xr strip 1
282to strip binaries so that install can be portable over a large
283number of systems and binary types.
284If the environment variable
285.Ev STRIP
286is set, it is used as the
287.Xr strip 1
288program.
289.It Fl T Ar tags
290Specify the
291.Xr mtree 8
292tags to write out for the file when using
293.Fl M Ar metalog .
294.It Fl U
295Indicate that install is running unprivileged, and that it should not
296try to change the owner, the group, or the file flags of the destination.
297The information that would have been updated can be stored in a log
298file with
299.Fl M Ar metalog .
300.El
301.Pp
302By default,
303.Nm
304preserves all file flags, with the exception of the ``nodump'' flag.
305.Pp
306The
307.Nm
308utility attempts to prevent copying a file onto itself.
309.Pp
310Installing
311.Pa /dev/null
312creates an empty file.
313.Sh ENVIRONMENT
314.Bl -tag -width Fl
315.It Ev STRIP
316The program used to strip installed binaries when the
317.Fl s
318option is used.
319If unspecified,
320.Pa /usr/bin/strip
321is used.
322.El
323.Sh EXIT STATUS
324.Ex -std
325.Sh SEE ALSO
326.Xr chflags 1 ,
327.Xr chgrp 1 ,
328.Xr chmod 1 ,
329.Xr cp 1 ,
330.Xr mv 1 ,
331.Xr strip 1 ,
332.Xr chown 8 ,
333.Xr mtree 8
334.Sh HISTORY
335The
336.Nm
337utility appeared in
338.Bx 4.2 .
339