1.\"	$OpenBSD: install.1,v 1.21 2004/02/10 07:33:23 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.\"-
34.\" Copyright (c) 2008, 2009, 2010
35.\"	Thorsten “mirabilos” Glaser <tg@mirbsd.org>
36.\"-
37.\" Try to make GNU groff and AT&T nroff more compatible
38.\" * ` generates ‘ in gnroff, so use \`
39.\" * ' generates ’ in gnroff, \' generates ´, so use \*(aq
40.\" * - generates ‐ in gnroff, \- generates −, so .tr it to -
41.\"   thus use - for hyphens and \- for minus signs and option dashes
42.\" * ~ is size-reduced and placed atop in groff, so use \*(TI
43.\" * ^ is size-reduced and placed atop in groff, so use \*(ha
44.\" * \(en does not work in nroff, so use \*(en
45.\" * <>| are problematic, so redefine and use \*(Lt\*(Gt\*(Ba
46.\" Also make sure to use \& especially with two-letter words.
47.\" The section after the "doc" macropackage has been loaded contains
48.\" additional code to convene between the UCB mdoc macropackage (and
49.\" its variant as BSD mdoc in groff) and the GNU mdoc macropackage.
50.\"
51.ie \n(.g \{\
52.	if \*[.T]ascii .tr \-\N'45'
53.	if \*[.T]latin1 .tr \-\N'45'
54.	if \*[.T]utf8 .tr \-\N'45'
55.	ds <= \[<=]
56.	ds >= \[>=]
57.	ds Rq \[rq]
58.	ds Lq \[lq]
59.	ds sL \(aq
60.	ds sR \(aq
61.	if \*[.T]utf8 .ds sL `
62.	if \*[.T]ps .ds sL `
63.	if \*[.T]utf8 .ds sR '
64.	if \*[.T]ps .ds sR '
65.	ds aq \(aq
66.	ds TI \(ti
67.	ds ha \(ha
68.	ds en \(en
69.\}
70.el \{\
71.	ds aq '
72.	ds TI ~
73.	ds ha ^
74.	ds en \(em
75.\}
76.\"
77.\" Implement .Dd with the Mdocdate RCS keyword
78.\"
79.rn Dd xD
80.de Dd
81.ie \\$1$Mdocdate: \{\
82.	xD \\$2 \\$3, \\$4
83.\}
84.el .xD \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8
85..
86.\"
87.\" .Dd must come before definition of .Mx, because when called
88.\" with -mandoc, it might implement .Mx itself, but we want to
89.\" use our own definition. And .Dd must come *first*, always.
90.\"
91.Dd $Mdocdate: June 1 2013 $
92.\"
93.\" Check which macro package we use, and do other -mdoc setup.
94.\"
95.ie \n(.g \{\
96.	if \*[.T]utf8 .tr \[la]\*(Lt
97.	if \*[.T]utf8 .tr \[ra]\*(Gt
98.	ie d volume-ds-1 .ds tT gnu
99.	el .ds tT bsd
100.\}
101.el .ds tT ucb
102.\"
103.\" Implement .Mx (MirBSD)
104.\"
105.ie "\*(tT"gnu" \{\
106.	eo
107.	de Mx
108.	nr curr-font \n[.f]
109.	nr curr-size \n[.ps]
110.	ds str-Mx \f[\n[curr-font]]\s[\n[curr-size]u]
111.	ds str-Mx1 \*[Tn-font-size]\%MirOS\*[str-Mx]
112.	if !\n[arg-limit] \
113.	if \n[.$] \{\
114.	ds macro-name Mx
115.	parse-args \$@
116.	\}
117.	if (\n[arg-limit] > \n[arg-ptr]) \{\
118.	nr arg-ptr +1
119.	ie (\n[type\n[arg-ptr]] == 2) \
120.	as str-Mx1 \~\*[arg\n[arg-ptr]]
121.	el \
122.	nr arg-ptr -1
123.	\}
124.	ds arg\n[arg-ptr] "\*[str-Mx1]
125.	nr type\n[arg-ptr] 2
126.	ds space\n[arg-ptr] "\*[space]
127.	nr num-args (\n[arg-limit] - \n[arg-ptr])
128.	nr arg-limit \n[arg-ptr]
129.	if \n[num-args] \
130.	parse-space-vector
131.	print-recursive
132..
133.	ec
134.	ds sP \s0
135.	ds tN \*[Tn-font-size]
136.\}
137.el \{\
138.	de Mx
139.	nr cF \\n(.f
140.	nr cZ \\n(.s
141.	ds aa \&\f\\n(cF\s\\n(cZ
142.	if \\n(aC==0 \{\
143.		ie \\n(.$==0 \&MirOS\\*(aa
144.		el .aV \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
145.	\}
146.	if \\n(aC>\\n(aP \{\
147.		nr aP \\n(aP+1
148.		ie \\n(C\\n(aP==2 \{\
149.			as b1 \&MirOS\ #\&\\*(A\\n(aP\\*(aa
150.			ie \\n(aC>\\n(aP \{\
151.				nr aP \\n(aP+1
152.				nR
153.			\}
154.			el .aZ
155.		\}
156.		el \{\
157.			as b1 \&MirOS\\*(aa
158.			nR
159.		\}
160.	\}
161..
162.\}
163.\"-
164.Dt INSTALL 1
165.Os
166.Sh NAME
167.Nm install
168.Nd install binaries
169.Sh SYNOPSIS
170.Nm
171.Op Fl bCcdpSs
172.Op Fl B Ar suffix
173.Op Fl f Ar flags
174.Op Fl g Ar group
175.Op Fl m Ar mode
176.Op Fl o Ar owner
177.Ar source Op Ar ...
178.Ar target Op Ar ...
179.Sh DESCRIPTION
180The
181.Ar source
182file(s) are copied to the
183.Ar target
184file or directory.
185If the
186.Ar target
187file already exists, it is either renamed to
188.Ar file.old
189if the
190.Fl b
191option is given
192or overwritten
193if permissions allow.
194An alternate backup suffix may be specified via the
195.Fl B
196option's argument.
197If the
198.Fl d
199option is given,
200.Ar target
201directories are created, and no files are copied.
202.Pp
203The options are as follows:
204.Bl -tag -width "-B suffix"
205.It Fl B Ar suffix
206Use
207.Ar suffix
208as the backup suffix if
209.Fl b
210is given.
211.It Fl b
212Backup any existing files before overwriting them by renaming
213them to
214.Ar file.old .
215See
216.Fl B
217for specifying a different backup suffix.
218.It Fl C
219Copy the file.
220If the target file already exists and the files are the same,
221then don't change the modification time of the target.
222.It Fl c
223Copy the file.
224This is actually the default.
225The
226.Fl c
227option is only included for backwards compatibility.
228.It Fl d
229Create directories.
230Missing parent directories are created as required.
231This option cannot be used with the
232.Fl B , b , C , c ,
233.Fl f , p , S ,
234or
235.Fl s
236options.
237Failure to change ownership or modes does not make the operation unsuccessful.
238.It Fl f Ar flags
239Specify the target's file
240.Ar flags .
241(See
242.Xr chflags 1
243for a list of possible flags and their meanings.)
244.It Fl g Ar group
245Specify a
246.Ar group .
247A numeric GID is allowed.
248.It Fl m Ar mode
249Specify an alternate
250.Ar mode .
251The default mode is set to rwxr\-xr\-x (0755).
252The specified mode may be either an octal or symbolic value; see
253.Xr chmod 1
254for a description of possible mode values.
255.It Fl o Ar owner
256Specify an
257.Ar owner .
258A numeric UID is allowed.
259.It Fl p
260Preserve the modification time.
261Copy the file, as if the
262.Fl C
263(compare and copy) option is specified,
264except if the target file doesn't already exist or is different,
265then preserve the modification time of the file.
266.It Fl S
267Safe copy.
268Normally,
269.Nm
270unlinks an existing target before installing the new file.
271With the
272.Fl S
273flag a temporary file is used and then renamed to be
274the target.
275The reason this is safer is that if the copy or
276rename fails, the existing target is left untouched.
277.It Fl s
278.Nm
279execs the command
280.Pa /usr/bin/strip
281to strip binaries so that install can be portable over a large
282number of systems and binary types.
283If the environment variable
284.Ev STRIP
285is set, it is used instead.
286.El
287.Pp
288By default,
289.Nm
290preserves all file flags, with the exception of the
291.Dq nodump
292flag.
293.Pp
294The
295.Nm
296utility attempts to prevent moving a file onto itself.
297.Pp
298Installing
299.Pa /dev/null
300creates an empty file.
301.Pp
302Upon successful completion a value of 0 is returned.
303Otherwise, a value \*(Gt0 is returned.
304.Sh ENVIRONMENT
305.Bl -tag -width "STRIP"
306.It Ev STRIP
307For an alternate
308.Xr strip 1
309program to run.
310Default is
311.Pa /usr/bin/strip .
312.El
313.Sh FILES
314.Bl -tag -width INS@XXXXXXXXXX -compact
315.It Pa INS@XXXXXXXXXX
316If either
317.Fl S
318option is specified, or the
319.Fl C
320or
321.Fl p
322option is used in conjunction with the
323.Fl s
324option, temporary files named INS@XXXXXXXXXX,
325where XXXXXXXXXX is decided by
326.Xr mkstemp 3 ,
327are created in the target directory.
328.El
329.Sh SEE ALSO
330.Xr chflags 1 ,
331.Xr chgrp 1 ,
332.Xr chmod 1 ,
333.Xr cp 1 ,
334.Xr mv 1 ,
335.Xr strip 1 ,
336.Xr chown 8
337.Sh HISTORY
338The
339.Nm
340utility appeared in
341.Bx 4.2 .
342.Sh CAVEATS
343The
344.Fl C ,
345.Fl p ,
346and
347.Fl S
348flags are non-standard and should not relied upon for portability.
349.Pp
350Temporary files may be left in the target directory if
351.Nm
352exits abnormally.
353