xref: /netbsd/usr.bin/xinstall/install.1 (revision c4a72b64) 
1.\"	$NetBSD: install.1,v 1.31 2002/09/30 11:09:18 grant 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. All advertising materials mentioning features or use of this software
15.\"    must display the following acknowledgement:
16.\"	This product includes software developed by the University of
17.\"	California, Berkeley and its contributors.
18.\" 4. Neither the name of the University nor the names of its contributors
19.\"    may be used to endorse or promote products derived from this software
20.\"    without specific prior written permission.
21.\"
22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32.\" SUCH DAMAGE.
33.\"
34.\"     @(#)install.1	8.1 (Berkeley) 6/6/93
35.\"
36.Dd March 20, 2002
37.Dt INSTALL 1
38.Os
39.Sh NAME
40.Nm install
41.Nd install binaries
42.Sh SYNOPSIS
43.Nm ""
44.Op Fl Ubcprs
45.Bk -words
46.Op Fl B Ar suffix
47.Ek
48.Bk -words
49.Op Fl f Ar flags
50.Ek
51.Bk -words
52.Op Fl M Ar metalog
53.Ek
54.Bk -words
55.Op Fl T Ar tags
56.Ek
57.Bk -words
58.Op Fl a Ar command
59.Ek
60.Bk -words
61.Op Fl m Ar mode
62.Ek
63.Bk -words
64.Op Fl o Ar owner
65.Ek
66.Bk -words
67.Op Fl g Ar group
68.Ek
69.Bk -words
70.Op Fl l Ar linkflags
71.Ek
72.Bk -words
73.Op Fl S Ar stripflag
74.Ek
75.Ar file1 file2
76.Nm ""
77.Op Fl Ubcprs
78.Bk -words
79.Op Fl B Ar suffix
80.Ek
81.Bk -words
82.Op Fl f Ar flags
83.Ek
84.Bk -words
85.Op Fl M Ar metalog
86.Ek
87.Bk -words
88.Op Fl T Ar tags
89.Ek
90.Bk -words
91.Op Fl a Ar command
92.Ek
93.Bk -words
94.Op Fl m Ar mode
95.Ek
96.Bk -words
97.Op Fl o Ar owner
98.Ek
99.Bk -words
100.Op Fl g Ar group
101.Ek
102.Bk -words
103.Op Fl l Ar linkflags
104.Ek
105.Bk -words
106.Op Fl S Ar stripflag
107.Ek
108.Ar file1 ...\&
109.Ar fileN directory
110.Nm ""
111.Fl d
112.Op Fl Up
113.Bk -words
114.Op Fl M Ar metalog
115.Ek
116.Bk -words
117.Op Fl T Ar tags
118.Ek
119.Bk -words
120.Op Fl a Ar command
121.Ek
122.Bk -words
123.Op Fl m Ar mode
124.Ek
125.Bk -words
126.Op Fl o Ar owner
127.Ek
128.Bk -words
129.Op Fl g Ar group
130.Ek
131.Ar directory ...\&
132.Sh DESCRIPTION
133The file(s) are moved (copied if the
134.Fl c
135option is specified, or linked if the
136.Fl l
137option is specified) to the target file or directory.
138If the destination is a directory, then the
139.Ar file
140is moved into
141.Ar directory
142with its original filename.
143If the target file already exists, it is
144either renamed to
145.Ar file.old
146if the
147.Fl b
148option is given
149or overwritten
150if permissions allow, An alternate backup suffix may be specified via the
151.Fl B
152option's argument.
153.Pp
154.Bl -tag -width Ds
155.It Fl a Ar command
156Run
157.Ar command
158on the target after installation and stripping
159.Pq Fl s ,
160but before
161ownership, permissions or timestamps are set and before renaming
162.Pq Fl r
163occurs.
164.Ar command
165is invoked via the
166.Xr sh  1
167shell, allowing a single
168.Fl a
169argument be to specified to
170.Nm
171which the shell can then tokenize.
172.It Fl b
173Backup any existing files before overwriting them by renaming
174them to
175.Ar file.old . See
176.Fl B
177for specifying a different backup suffix.
178.It Fl B Ar suffix
179Use
180.Ar suffix
181as the backup suffix if
182.Fl b
183is given.
184If
185.Ar suffix
186contains a '%' sign, a numbered backup will be performed, and the
187%-pattern will be expanded using
188.Xr sprintf 3 ,
189given an integer counter as the backup number.
190The counter used starts from 0, and the first available name resulting
191from the expansion is used.
192.It Fl c
193Copy the file.
194This flag turns off the default behavior of
195.Nm
196where it deletes the original file after creating the target.
197.It Fl d
198Create directories.
199Missing parent directories are created as required.
200.It Fl f Ar flags
201Specify the target's file flags.
202(See
203.Xr chflags 1
204for a list of possible flags and their meanings.)
205.It Fl g Ar group
206Specify a group.
207.It Fl M Ar metalog
208Write the metadata associated with each item installed to
209.Ar metalog
210in an
211.Xr mtree 8
212.Dq full path
213specification line.
214The metadata includes: the file name and file type, and depending upon
215other options, the owner, group, file flags, modification time, and tags.
216.It Fl m Ar mode
217Specify an alternative mode.
218The default mode is set to rwxr-xr-x (0755).
219The specified mode may be either an octal or symbolic value; see
220.Xr chmod  1
221for a description of possible mode values.
222.It Fl l Ar linkflags
223Instead of copying the file make a link to the source.
224The type of the link is determined by the
225.Ar linkflags
226argument.
227Valid
228.Ar linkflags
229are:
230.Ar a
231(absolute),
232.Ar r
233(relative),
234.Ar h
235(hard),
236.Ar s
237(symbolic),
238.Ar m
239(mixed).
240Absolute and relative have effect only for symbolic links.
241Mixed links
242are hard links for files on the same filesystem, symbolic otherwise.
243.It Fl o Ar owner
244Specify an owner.
245.It Fl p
246Preserve the source files access and modification times.
247.It Fl r
248Install to a temporary file and then rename the file to its final destination
249name.
250This can be used for precious files, to avoid truncation of the original
251when error conditions (filesystem full etc.) occur.
252.It Fl s
253.Nm
254exec's the command
255.Xr strip  1
256to strip binaries so that install can be portable over a large
257number of systems and binary types.
258If the environment variable
259.Ev STRIP
260is set, it is used as the
261.Xr strip 1
262program.
263.It Fl S Ar stripflags
264.Nm
265passes
266.Ar stripflags
267as option arguments to
268.Xr strip  1 .
269When
270.Fl S
271is used,
272.Xr strip  1
273is invoked via the
274.Xr sh  1
275shell, allowing a single
276.Fl S
277argument be to specified to
278.Nm
279which the shell can then tokenize.
280Normally,
281.Nm
282invokes
283.Xr strip  1
284directly.
285This flag implies
286.Fl s .
287.It Fl T Ar tags
288Specify the
289.Xr mtree 8
290tags to write out for the file when using
291.Fl M Ar metalog .
292.It Fl U
293Indicate that install is running unprivileged, and that it should not
294try to change the owner, the group, or the file flags of the destination.
295The information that would have been updated can be stored in a log
296file with
297.Fl M Ar metalog .
298.El
299.Pp
300By default,
301.Nm
302preserves all file flags, with the exception of the ``nodump'' flag.
303.Pp
304The
305.Nm
306utility attempts to prevent moving a file onto itself.
307.Pp
308Installing
309.Pa /dev/null
310creates an empty file.
311.Sh EXIT STATUS
312The
313.Nm
314utility exits 0 on success,
315and \*[Gt]0 if an error occurs.
316.Sh ENVIRONMENT
317.Bl -tag -width Fl
318.It Ev STRIP
319The program used to strip installed binaries when the
320.Fl s
321option is used.
322If unspecified,
323.Pa /usr/bin/strip
324is used.
325.El
326.Sh SEE ALSO
327.Xr chflags 1 ,
328.Xr chgrp 1 ,
329.Xr chmod 1 ,
330.Xr cp 1 ,
331.Xr mv 1 ,
332.Xr strip 1 ,
333.Xr chown 8 ,
334.Xr mtree 8
335.Sh HISTORY
336The
337.Nm
338utility appeared in
339.Bx 4.2 .
340