NetBSD/usr.bin/xinstall/install.1

.\"	$NetBSD: install.1,v 1.33 2002/12/19 09:17:01 wiz Exp $
.\"
.\" Copyright (c) 1987, 1990, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)install.1	8.1 (Berkeley) 6/6/93
.\"
.Dd December 19, 2002
.Dt INSTALL 1
.Os
.Sh NAME
.Nm install
.Nd install binaries
.Sh SYNOPSIS
.Nm ""
.Op Fl Ubcprs
.Bk -words
.Op Fl B Ar suffix
.Ek
.Bk -words
.Op Fl f Ar flags
.Ek
.Bk -words
.Op Fl M Ar metalog
.Ek
.Bk -words
.Op Fl T Ar tags
.Ek
.Bk -words
.Op Fl a Ar command
.Ek
.Bk -words
.Op Fl m Ar mode
.Ek
.Bk -words
.Op Fl N Ar dbdir
.Ek
.Bk -words
.Op Fl o Ar owner
.Ek
.Bk -words
.Op Fl g Ar group
.Ek
.Bk -words
.Op Fl l Ar linkflags
.Ek
.Bk -words
.Op Fl S Ar stripflag
.Ek
.Ar file1 file2
.Nm ""
.Op Fl Ubcprs
.Bk -words
.Op Fl B Ar suffix
.Ek
.Bk -words
.Op Fl f Ar flags
.Ek
.Bk -words
.Op Fl M Ar metalog
.Ek
.Bk -words
.Op Fl T Ar tags
.Ek
.Bk -words
.Op Fl a Ar command
.Ek
.Bk -words
.Op Fl m Ar mode
.Ek
.Bk -words
.Op Fl N Ar dbdir
.Ek
.Bk -words
.Op Fl o Ar owner
.Ek
.Bk -words
.Op Fl g Ar group
.Ek
.Bk -words
.Op Fl l Ar linkflags
.Ek
.Bk -words
.Op Fl S Ar stripflag
.Ek
.Ar file1 ...\&
.Ar fileN directory
.Nm ""
.Fl d
.Op Fl Up
.Bk -words
.Op Fl M Ar metalog
.Ek
.Bk -words
.Op Fl T Ar tags
.Ek
.Bk -words
.Op Fl a Ar command
.Ek
.Bk -words
.Op Fl m Ar mode
.Ek
.Bk -words
.Op Fl N Ar dbdir
.Ek
.Bk -words
.Op Fl o Ar owner
.Ek
.Bk -words
.Op Fl g Ar group
.Ek
.Ar directory ...\&
.Sh DESCRIPTION
The file(s) are moved (copied if the
.Fl c
option is specified, or linked if the
.Fl l
option is specified) to the target file or directory.
If the destination is a directory, then the
.Ar file
is moved into
.Ar directory
with its original filename.
If the target file already exists, it is
either renamed to
.Ar file.old
if the
.Fl b
option is given
or overwritten
if permissions allow, An alternate backup suffix may be specified via the
.Fl B
option's argument.
.Pp
.Bl -tag -width Ds
.It Fl a Ar command
Run
.Ar command
on the target after installation and stripping
.Pq Fl s ,
but before
ownership, permissions or timestamps are set and before renaming
.Pq Fl r
occurs.
.Ar command
is invoked via the
.Xr sh  1
shell, allowing a single
.Fl a
argument be to specified to
.Nm
which the shell can then tokenize.
.It Fl b
Backup any existing files before overwriting them by renaming
them to
.Ar file.old . See
.Fl B
for specifying a different backup suffix.
.It Fl B Ar suffix
Use
.Ar suffix
as the backup suffix if
.Fl b
is given.
If
.Ar suffix
contains a '%' sign, a numbered backup will be performed, and the
%-pattern will be expanded using
.Xr sprintf 3 ,
given an integer counter as the backup number.
The counter used starts from 0, and the first available name resulting
from the expansion is used.
.It Fl c
Copy the file.
This flag turns off the default behavior of
.Nm
where it deletes the original file after creating the target.
.It Fl d
Create directories.
Missing parent directories are created as required.
.It Fl f Ar flags
Specify the target's file flags.
(See
.Xr chflags 1
for a list of possible flags and their meanings.)
.It Fl g Ar group
Specify a group.
.It Fl l Ar linkflags
Instead of copying the file make a link to the source.
The type of the link is determined by the
.Ar linkflags
argument.
Valid
.Ar linkflags
are:
.Ar a
(absolute),
.Ar r
(relative),
.Ar h
(hard),
.Ar s
(symbolic),
.Ar m
(mixed).
Absolute and relative have effect only for symbolic links.
Mixed links
are hard links for files on the same filesystem, symbolic otherwise.
.It Fl M Ar metalog
Write the metadata associated with each item installed to
.Ar metalog
in an
.Xr mtree 8
.Dq full path
specification line.
The metadata includes: the file name and file type, and depending upon
other options, the owner, group, file flags, modification time, and tags.
.It Fl m Ar mode
Specify an alternative mode.
The default mode is set to rwxr-xr-x (0755).
The specified mode may be either an octal or symbolic value; see
.Xr chmod  1
for a description of possible mode values.
.It Fl N Ar dbdir
Use the user database text file
.Pa master.passwd
and group database text file
.Pa group
from
.Ar dbdir ,
rather than using the results from the system's
.Xr getpwnam 3
and
.Xr getgrnam 3
(and related) library calls.
.It Fl o Ar owner
Specify an owner.
.It Fl p
Preserve the source files access and modification times.
.It Fl r
Install to a temporary file and then rename the file to its final destination
name.
This can be used for precious files, to avoid truncation of the original
when error conditions (filesystem full etc.) occur.
.It Fl s
.Nm
exec's the command
.Xr strip  1
to strip binaries so that install can be portable over a large
number of systems and binary types.
If the environment variable
.Ev STRIP
is set, it is used as the
.Xr strip 1
program.
.It Fl S Ar stripflags
.Nm
passes
.Ar stripflags
as option arguments to
.Xr strip  1 .
When
.Fl S
is used,
.Xr strip  1
is invoked via the
.Xr sh  1
shell, allowing a single
.Fl S
argument be to specified to
.Nm
which the shell can then tokenize.
Normally,
.Nm
invokes
.Xr strip  1
directly.
This flag implies
.Fl s .
.It Fl T Ar tags
Specify the
.Xr mtree 8
tags to write out for the file when using
.Fl M Ar metalog .
.It Fl U
Indicate that install is running unprivileged, and that it should not
try to change the owner, the group, or the file flags of the destination.
The information that would have been updated can be stored in a log
file with
.Fl M Ar metalog .
.El
.Pp
By default,
.Nm
preserves all file flags, with the exception of the ``nodump'' flag.
.Pp
The
.Nm
utility attempts to prevent moving a file onto itself.
.Pp
Installing
.Pa /dev/null
creates an empty file.
.Sh EXIT STATUS
The
.Nm
utility exits 0 on success,
and \*[Gt]0 if an error occurs.
.Sh ENVIRONMENT
.Bl -tag -width Fl
.It Ev STRIP
The program used to strip installed binaries when the
.Fl s
option is used.
If unspecified,
.Pa /usr/bin/strip
is used.
.El
.Sh SEE ALSO
.Xr chflags 1 ,
.Xr chgrp 1 ,
.Xr chmod 1 ,
.Xr cp 1 ,
.Xr mv 1 ,
.Xr strip 1 ,
.Xr chown 8 ,
.Xr mtree 8
.Sh HISTORY
The
.Nm
utility appeared in
.Bx 4.2 .