xref: /netbsd-src/usr.bin/xinstall/install.1 (revision 9fbd88883c38d0c0fbfcbe66d76fe6b0fab3f9de) 
1.\"	$NetBSD: install.1,v 1.28 2001/12/08 19:27:33 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. 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 October 26, 2001
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 m Ar mode
59.Ek
60.Bk -words
61.Op Fl o Ar owner
62.Ek
63.Bk -words
64.Op Fl g Ar group
65.Ek
66.Bk -words
67.Op Fl l Ar linkflags
68.Ek
69.Bk -words
70.Op Fl S Ar stripflag
71.Ek
72.Ar file1 file2
73.Nm ""
74.Op Fl Ubcprs
75.Bk -words
76.Op Fl B Ar suffix
77.Ek
78.Bk -words
79.Op Fl f Ar flags
80.Ek
81.Bk -words
82.Op Fl M Ar metalog
83.Ek
84.Bk -words
85.Op Fl T Ar tags
86.Ek
87.Bk -words
88.Op Fl m Ar mode
89.Ek
90.Bk -words
91.Op Fl o Ar owner
92.Ek
93.Bk -words
94.Op Fl g Ar group
95.Ek
96.Bk -words
97.Op Fl l Ar linkflags
98.Ek
99.Bk -words
100.Op Fl S Ar stripflag
101.Ek
102.Ar file1 ...\&
103.Ar fileN directory
104.Nm ""
105.Op Fl Up
106.Fl d
107.Bk -words
108.Op Fl M Ar metalog
109.Ek
110.Bk -words
111.Op Fl T Ar tags
112.Ek
113.Bk -words
114.Op Fl m Ar mode
115.Ek
116.Bk -words
117.Op Fl o Ar owner
118.Ek
119.Bk -words
120.Op Fl g Ar group
121.Ek
122.Ar directory ...\&
123.Sh DESCRIPTION
124The file(s) are moved (copied if the
125.Fl c
126option is specified, or linked if the
127.Fl l
128option is specified) to the target file or directory.
129If the destination is a directory, then the
130.Ar file
131is moved into
132.Ar directory
133with its original filename.
134If the target file already exists, it is
135either renamed to
136.Ar file.old
137if the
138.Fl b
139option is given
140or overwritten
141if permissions allow, An alternate backup suffix may be specified via the
142.Fl B
143option's argument.
144.Pp
145.Bl -tag -width Ds
146.It Fl b
147Backup any existing files before overwriting them by renaming
148them to
149.Ar file.old . See
150.Fl B
151for specifying a different backup suffix.
152.It Fl B Ar suffix
153Use
154.Ar suffix
155as the backup suffix if
156.Fl b
157is given. If
158.Ar suffix
159contains a '%' sign, a numbered backup will be performed, and the
160%-pattern will be expanded using
161.Xr sprintf 3 ,
162given an integer counter as the backup number.
163The counter used starts from 0, and the first available name resulting
164from the expansion is used.
165.It Fl c
166Copy the file.
167This flag turns off the default behavior of
168.Nm
169where it deletes the original file after creating the target.
170.It Fl f
171Specify the target's file flags.
172(See
173.Xr chflags 1
174for a list of possible flags and their meanings.)
175.It Fl g
176Specify a group.
177.It Fl M Ar metalog
178Write the metadata associated with each item installed to
179.Ar metalog
180in an
181.Xr mtree 8
182.Dq full path
183specification line.
184The metadata includes: the file name and file type, and depending upon
185other options, the owner, group, file flags, modification time, and tags.
186.It Fl m
187Specify an alternative mode.
188The default mode is set to rwxr-xr-x (0755).
189The specified mode may be either an octal or symbolic value; see
190.Xr chmod  1
191for a description of possible mode values.
192.It Fl l Ar linkflags
193Instead of copying the file make a link to the source. The type of the
194link is determined by the
195.Ar linkflags
196argument. Valid
197.Ar linkflags
198are:
199.Ar a
200(absolute),
201.Ar r
202(relative),
203.Ar h
204(hard),
205.Ar s
206(symbolic),
207.Ar m
208(mixed). Absolute and relative have effect only for symbolic links. Mixed links
209are hard links for files on the same filesystem, symbolic otherwise.
210.It Fl o
211Specify an owner.
212.It Fl p
213Preserve the source files access and modification times.
214.It Fl r
215Install to a temporary file and then rename the file to its final destination
216name. This can be used for precious files, to avoid truncation of the original
217when error conditions (filesystem full etc.) occur.
218.It Fl s
219.Nm
220exec's the command
221.Xr strip  1
222to strip binaries so that install can be portable over a large
223number of systems and binary types.  If the environment variable
224.Ev STRIP
225is set, it is used as the
226.Xr strip 1
227program.
228.It Fl S Ar stripflags
229.Nm
230passes
231.Ar stripflags
232as option arguments to
233.Xr strip  1 .
234When
235.Fl S
236is used,
237.Xr strip  1
238is invoked via the
239.Xr sh  1
240shell, allowing a single
241Fl S
242argument be to specified to
243.Nm
244which the shell can then tokenize. Normally,
245.Nm
246invokes
247.Xr strip  1
248directly. This flag implies
249.Fl s .
250.It Fl T Ar tags
251Specify the
252.Xr mtree 8
253tags to write out for the file when using
254.Fl M Ar metalog .
255.It Fl d
256Create directories.
257Missing parent directories are created as required.
258.It Fl U
259Indicate that install is running unprivileged, and that it should not
260try to change the owner, the group, or the file flags of the destination.
261The information that would have been updated can be stored in a log
262file with
263.Fl M Ar metalog .
264.El
265.Pp
266By default,
267.Nm
268preserves all file flags, with the exception of the ``nodump'' flag.
269.Pp
270The
271.Nm
272utility attempts to prevent moving a file onto itself.
273.Pp
274Installing
275.Pa /dev/null
276creates an empty file.
277.Sh EXIT STATUS
278The
279.Nm
280utility exits 0 on success,
281and >0 if an error occurs.
282.Sh ENVIRONMENT
283.Bl -tag -width Fl
284.It Ev STRIP
285The program used to strip installed binaries when the
286.Fl s
287option is used.  If unspecified,
288.Pa /usr/bin/strip
289is used.
290.El
291.Sh SEE ALSO
292.Xr chflags 1 ,
293.Xr chgrp 1 ,
294.Xr chmod 1 ,
295.Xr cp 1 ,
296.Xr mv 1 ,
297.Xr strip 1 ,
298.Xr chown 8 ,
299.Xr mtree 8
300.Sh HISTORY
301The
302.Nm
303utility appeared in
304.Bx 4.2 .
305