install(1): Add -U option from FreeBSD
[dragonfly.git] / usr.bin / xinstall / install.1
CommitLineData
984263bc
MD
1.\" Copyright (c) 1987, 1990, 1993
2.\" The Regents of the University of California. All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\" notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\" notice, this list of conditions and the following disclaimer in the
11.\" documentation and/or other materials provided with the distribution.
dc71b7ab 12.\" 3. Neither the name of the University nor the names of its contributors
984263bc
MD
13.\" may be used to endorse or promote products derived from this software
14.\" without specific prior written permission.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26.\" SUCH DAMAGE.
27.\"
28.\" From: @(#)install.1 8.1 (Berkeley) 6/6/93
29.\" $FreeBSD: src/usr.bin/xinstall/install.1,v 1.16.2.9 2002/07/01 21:01:23 des Exp $
30.\"
60af0858 31.Dd January 22, 2016
984263bc
MD
32.Dt INSTALL 1
33.Os
34.Sh NAME
35.Nm install
36.Nd install binaries
37.Sh SYNOPSIS
38.Nm
60af0858 39.Op Fl bCclMpSsUv
984263bc 40.Op Fl B Ar suffix
a2bc4e56 41.Op Fl D Ar destdir
984263bc
MD
42.Op Fl f Ar flags
43.Op Fl g Ar group
60af0858 44.Op Fl L Ar etcdir
984263bc
MD
45.Op Fl m Ar mode
46.Op Fl o Ar owner
47.Ar file1 file2
48.Nm
60af0858 49.Op Fl bCclMpSsUv
984263bc 50.Op Fl B Ar suffix
a2bc4e56 51.Op Fl D Ar destdir
984263bc
MD
52.Op Fl f Ar flags
53.Op Fl g Ar group
60af0858 54.Op Fl L Ar etcdir
984263bc
MD
55.Op Fl m Ar mode
56.Op Fl o Ar owner
57.Ar file1 ... fileN directory
58.Nm
59.Fl d
60af0858 60.Op Fl lUv
4cd7e9fc 61.Op Fl D Ar destdir
984263bc 62.Op Fl g Ar group
60af0858 63.Op Fl L Ar etcdir
984263bc
MD
64.Op Fl m Ar mode
65.Op Fl o Ar owner
66.Ar directory ...
67.Sh DESCRIPTION
68The file(s) are copied
69to the target file or directory.
70If the destination is a directory, then the
71.Ar file
72is copied into
73.Ar directory
74with its original filename.
75If the target file already exists, it is
76either renamed to
77.Ar file Ns Pa .old
78if the
79.Fl b
80option is given
81or overwritten
82if permissions allow.
83An alternate backup suffix may be specified via the
84.Fl B
85option's argument.
86.Pp
87The options are as follows:
88.Bl -tag -width indent
89.It Fl b
90Back up any existing files before overwriting them by renaming
91them to
92.Ar file Ns Pa .old .
93See
94.Fl B
95for specifying a different backup suffix.
4e72d2de
MD
96.It Fl L Ar etcdir
97Specify the location of the /etc directory containing the group and password
98files. The default is "/etc". If an alternative directory is specified
99group and username lookups will be made from the alternative group and
23265324 100password files rather than the system group and password files.
984263bc
MD
101.It Fl B Ar suffix
102Use
103.Ar suffix
104as the backup suffix if
105.Fl b
106is given.
107.It Fl C
108Copy the file.
109If the target file already exists and the files are the same,
110then don't change the modification time of the target.
111.It Fl c
112Copy the file.
113This is actually the default.
114The
115.Fl c
116option is only included for backwards compatibility.
117.It Fl d
118Create directories.
119Missing parent directories are created as required.
a2bc4e56
FT
120.It Fl D Ar destdir
121Specify the
122.Ev DESTDIR
86a8591e 123(top of the file hierarchy) that the items are installed into.
534c03f0
SW
124This option is implemented for compatibility with the
125.Nx
126version of
4cd7e9fc 127.Nm
a2bc4e56 128and does nothing.
984263bc
MD
129.It Fl f
130Specify the target's file flags; see
131.Xr chflags 1
132for a list of possible flags and their meanings.
133.It Fl g
134Specify a group.
135A numeric GID is allowed.
4e72d2de
MD
136.It Fl l
137When the
138.Fl L
139option is specified and the owner or group cannot be found, fallback to
140system files.
984263bc
MD
141.It Fl M
142Disable all use of
143.Xr mmap 2 .
144.It Fl m
145Specify an alternate mode.
146The default mode is set to rwxr-xr-x (0755).
147The specified mode may be either an octal or symbolic value; see
148.Xr chmod 1
149for a description of possible mode values.
150.It Fl o
151Specify an owner.
152A numeric UID is allowed.
153.It Fl p
154Preserve the modification time.
155Copy the file, as if the
156.Fl C
157(compare and copy) option is specified,
158except if the target file doesn't already exist or is different,
159then preserve the modification time of the file.
160.It Fl S
161Safe copy.
162Normally,
163.Nm
164unlinks an existing target before installing the new file.
165With the
166.Fl S
167flag a temporary file is used and then renamed to be
168the target.
169The reason this is safer is that if the copy or
170rename fails, the existing target is left untouched.
171.It Fl s
172.Nm
173exec's the command
174.Xr strip 1
175to strip binaries so that
176.Nm
177can be portable over a large
178number of systems and binary types.
60af0858 179.It Fl U
180Indicate that
181.Nm
182is running unprivileged, and that it should not try to change
183the owner, the group, or the file flags of the destination.
984263bc
MD
184.It Fl v
185Cause
186.Nm
187to be verbose,
188showing files as they are installed or backed up.
189.El
190.Pp
191By default,
192.Nm
193preserves all file flags, with the exception of the
194.Dq nodump
195flag.
196.Pp
197The
198.Nm
199utility attempts to prevent moving a file onto itself.
200.Pp
201Installing
202.Pa /dev/null
203creates an empty file.
984263bc
MD
204.Sh FILES
205.Bl -tag -width INS@XXXX -compact
206.It Pa INS@XXXX
207If either
208.Fl S
209option is specified, or the
210.Fl C
211or
212.Fl p
3f5e28f4 213option is used in conjunction with the
984263bc
MD
214.Fl s
215option, temporary files named
216.Pa INS@XXXX ,
217where
218.Pa XXXX
219is decided by
220.Xr mkstemp 3 ,
221are created in the target directory.
222.El
19fe1c42 223.Sh EXIT STATUS
1847e88f 224.Ex -std
984263bc
MD
225.Sh COMPATIBILITY
226Historically
227.Nm
228moved files by default.
229The default was changed to copy in
230.Fx 4.4 .
231.Sh SEE ALSO
232.Xr chflags 1 ,
233.Xr chgrp 1 ,
234.Xr chmod 1 ,
235.Xr cp 1 ,
236.Xr mv 1 ,
237.Xr strip 1 ,
238.Xr mmap 2 ,
239.Xr chown 8
240.Sh HISTORY
241The
242.Nm
243utility appeared in
244.Bx 4.2 .
245.Sh BUGS
246Temporary files may be left in the target directory if
247.Nm
248exits abnormally.
249.Pp
250File flags cannot be set by
251.Xr fchflags 2
252over a NFS filesystem. Other filesystems do not have a concept of flags.
253The
254.Nm
255utility will only warn when flags could not be set on a filesystem
256that does not support them.
257.Pp
258The
259.Nm
260utility with
261.Fl v
262falsely says a file is copied when
263.Fl C
264snaps hard links.