Annotation of src/usr.bin/xinstall/install.1, Revision 1.19
1.19 ! jmc 1: .\" $OpenBSD: install.1,v 1.18 2003/06/03 02:56:24 millert Exp $
1.1 deraadt 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.
1.18 millert 15: .\" 3. Neither the name of the University nor the names of its contributors
1.1 deraadt 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: .Dd June 6, 1993
34: .Dt INSTALL 1
1.9 aaron 35: .Os
1.1 deraadt 36: .Sh NAME
37: .Nm install
38: .Nd install binaries
39: .Sh SYNOPSIS
40: .Nm install
1.8 millert 41: .Op Fl bCcpSs
42: .Op Fl B Ar suffix
1.1 deraadt 43: .Op Fl f Ar flags
44: .Op Fl g Ar group
45: .Op Fl m Ar mode
46: .Op Fl o Ar owner
47: .Ar file1 file2
48: .Nm install
1.8 millert 49: .Op Fl bCcpSs
50: .Op Fl B Ar suffix
1.1 deraadt 51: .Op Fl f Ar flags
52: .Op Fl g Ar group
53: .Op Fl m Ar mode
54: .Op Fl o Ar owner
55: .Ar file1
56: \&...
57: .Ar fileN directory
58: .Nm install
59: .Fl d
1.4 millert 60: .Op Fl g Ar group
1.1 deraadt 61: .Op Fl m Ar mode
62: .Op Fl o Ar owner
63: .Ar directory
64: \&...
65: .Sh DESCRIPTION
66: The file(s) are moved (or copied if the
67: .Fl c
68: option is specified) to the target file or directory.
69: If the destination is a directory, then the
70: .Ar file
71: is moved into
72: .Ar directory
73: with its original filename.
1.9 aaron 74: If the target file already exists, it is
1.8 millert 75: either renamed to
76: .Ar file.old
1.9 aaron 77: if the
1.8 millert 78: .Fl b
79: option is given
80: or overwritten
81: if permissions allow, An alternate backup suffix may be specified via the
82: .Fl B
83: option's argument.
84: .Pp
1.10 aaron 85: The options are as follows:
1.1 deraadt 86: .Bl -tag -width Ds
1.8 millert 87: .It Fl b
88: Backup any existing files before overwriting them by renaming
1.9 aaron 89: them to
1.12 aaron 90: .Ar file.old .
91: See
1.8 millert 92: .Fl B
93: for specifying a different backup suffix.
94: .It Fl B Ar suffix
1.9 aaron 95: Use
1.8 millert 96: .Ar suffix
1.9 aaron 97: as the backup suffix if
1.8 millert 98: .Fl b
99: is given.
1.3 millert 100: .It Fl C
101: Copy the file.
102: If the target file already exists and the files are the same,
103: then don't change the modification time of the target.
1.1 deraadt 104: .It Fl c
1.11 aaron 105: Copy the file.
106: This is actually the default.
107: The
1.3 millert 108: .Fl c
109: option is only included for backwards compatibility.
110: .It Fl d
1.9 aaron 111: Create directories.
1.3 millert 112: Missing parent directories are created as required.
1.1 deraadt 113: .It Fl f
114: Specify the target's file flags.
115: (See
116: .Xr chflags 1
117: for a list of possible flags and their meanings.)
118: .It Fl g
1.11 aaron 119: Specify a group.
120: A numeric GID is allowed.
1.1 deraadt 121: .It Fl m
122: Specify an alternate mode.
123: The default mode is set to rwxr-xr-x (0755).
124: The specified mode may be either an octal or symbolic value; see
1.11 aaron 125: .Xr chmod 1
1.1 deraadt 126: for a description of possible mode values.
127: .It Fl o
1.11 aaron 128: Specify an owner.
129: A numeric UID is allowed.
1.3 millert 130: .It Fl p
131: Preserve the modification time.
132: Copy the file, as if the
133: .Fl C
1.6 aaron 134: (compare and copy) option is specified,
1.3 millert 135: except if the target file doesn't already exist or is different,
136: then preserve the modification time of the file.
137: .It Fl S
1.11 aaron 138: Safe copy.
139: Normally,
140: .Nm
141: unlinks an existing target before installing the new file.
142: With the
1.3 millert 143: .Fl S
144: flag a temporary file is used and then renamed to be
1.11 aaron 145: the target.
146: The reason this is safer is that if the copy or
1.3 millert 147: rename fails, the existing target is left untouched.
1.1 deraadt 148: .It Fl s
1.11 aaron 149: .Nm
1.1 deraadt 150: exec's the command
1.5 millert 151: .Pa /usr/bin/strip
1.1 deraadt 152: to strip binaries so that install can be portable over a large
1.11 aaron 153: number of systems and binary types.
154: If the environment variable
1.5 millert 155: .Ev STRIP
156: is set, it is used instead.
1.1 deraadt 157: .El
158: .Pp
159: By default,
1.11 aaron 160: .Nm
161: preserves all file flags, with the exception of the
162: .Dq nodump
163: flag.
1.1 deraadt 164: .Pp
165: The
1.11 aaron 166: .Nm
1.1 deraadt 167: utility attempts to prevent moving a file onto itself.
168: .Pp
169: Installing
170: .Pa /dev/null
171: creates an empty file.
172: .Pp
173: Upon successful completion a value of 0 is returned.
1.13 ericj 174: Otherwise, a value >0 is returned.
1.19 ! jmc 175: .Sh ENVIRONMENT
! 176: .Bl -tag -width "STRIP"
! 177: .It Ev STRIP
! 178: For an alternate
! 179: .Xr strip 1
! 180: program to run.
! 181: Default is
! 182: .Pa /usr/bin/strip .
! 183: .El
1.3 millert 184: .Sh FILES
185: .Bl -tag -width INS@XXXXXX -compact
186: .It Pa INS@XXXXXX
187: If either
188: .Fl S
189: option is specified, or the
190: .Fl C
191: or
192: .Fl p
1.16 avsm 193: option is used in conjunction with the
1.3 millert 194: .Fl s
195: option, temporary files named INS@XXXXXX,
196: where XXXXXX is decided by
197: .Xr mkstemp 3 ,
198: are created in the target directory.
1.15 mpech 199: .El
1.1 deraadt 200: .Sh SEE ALSO
201: .Xr chflags 1 ,
202: .Xr chgrp 1 ,
203: .Xr chmod 1 ,
204: .Xr cp 1 ,
205: .Xr mv 1 ,
206: .Xr strip 1 ,
207: .Xr chown 8
208: .Sh HISTORY
209: The
1.11 aaron 210: .Nm
1.1 deraadt 211: utility appeared in
212: .Bx 4.2 .
1.3 millert 213: .Sh CAVEATS
214: The
215: .Fl C ,
216: .Fl p ,
217: and
218: .Fl S
219: flags are non-standard and should not relied upon for portability.
1.6 aaron 220: .Pp
1.3 millert 221: Temporary files may be left in the target directory if
1.11 aaron 222: .Nm
1.3 millert 223: exits abnormally.