'\" te
.\"  Copyright 1989 AT&T Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH INSTALLF 1M "Oct 30, 2007"
.SH NAME
installf \- add a file to the software installation database
.SH SYNOPSIS
.LP
.nf
\fBinstallf\fR [\fB-c\fR \fIclass\fR] [ [\fB-M\fR] \fB-R\fR \fIroot_path\fR] [\fB-V\fR \fIfs_file\fR] \fIpkginst\fR \fIpathname\fR
     [\fIftype\fR [\fImajor\fR \fIminor\fR] [\fImode\fR \fIowner\fR \fIgroup\fR]]
.fi

.LP
.nf
\fBinstallf\fR [\fB-c\fR \fIclass\fR] [ [\fB-M\fR] \fB-R\fR \fIroot_path\fR] [\fB-V\fR \fIfs_file\fR] \fIpkginst\fR -
.fi

.LP
.nf
\fBinstallf\fR \fB-f\fR [\fB-c\fR \fIclass\fR] [ [\fB-M\fR] \fB-R\fR \fIroot_path\fR] [\fB-V\fR \fIfs_file\fR] \fIpkginst\fR
.fi

.SH DESCRIPTION
.sp
.LP
\fBinstallf\fR informs the system that a pathname not listed in the
\fBpkgmap\fR(4) file is being created or modified. It should be invoked before
any file modifications have occurred.
.sp
.LP
When the second synopsis is used, the pathname descriptions will be read from
standard input. These descriptions are the same as would be given in the first
synopsis but the information is given in the form of a list. The descriptions
should be in the form:
.sp
.LP
\fIpathname\fR [ \fIftype\fR [\| \fImajor\fR \fIminor\fR ] [ \fImode\fR
\fIowner\fR \fIgroup\fR ]\|]
.sp
.LP
After all files have been appropriately created and/or modified, \fBinstallf\fR
should be invoked with the \fB-f\fR synopsis to indicate that installation is
final. Links will be created at this time and, if attribute information for a
pathname was not specified during the original invocation of \fBinstallf\fR, or
was not already stored on the system, the current attribute values for the
pathname will be stored. Otherwise, \fBinstallf\fR verifies that attribute
values match those given on the command line, making corrections as necessary.
In all cases, the current content information is calculated and stored
appropriately.
.sp
.LP
Package commands are \fBlargefile\fR(5)-aware. They handle files larger than 2
GB in the same way they handle smaller files. In their current implementations,
\fBpkgadd\fR(1M), \fBpkgtrans\fR(1) and other package commands can process a
datastream of  up to 4 GB.
.SH OPTIONS
.sp
.ne 2
.na
\fB\fB-c\fR \fIclass\fR\fR
.ad
.RS 16n
Class to which installed objects should be associated. Default class is
\fBnone\fR.
.RE

.sp
.ne 2
.na
\fB\fB-f\fR\fR
.ad
.RS 16n
Indicates that installation is complete. This option is used with the final
invocation of \fBinstallf\fR (for all files of a given class).
.RE

.sp
.ne 2
.na
\fB\fB-M\fR\fR
.ad
.RS 16n
Instruct \fBinstallf\fR not to use the \fB$\fR\fIroot_path\fR\fB/etc/vfstab\fR
file for determining the client's mount points. This option assumes the mount
points are correct on the server and it behaves consistently with Solaris 2.5
and earlier releases.
.RE

.sp
.ne 2
.na
\fB\fB\fR\fB-R\fR \fIroot_path\fR\fR
.ad
.RS 16n
Define the full path name of a directory to use as the \fIroot_path\fR. All
files, including package system information files, are relocated to a directory
tree starting in the specified \fIroot_path\fR. The \fIroot_path\fR can be
specified when installing to a client from a server (for example,
\fB/export/root/client1\fR).
.sp
\fBinstallf\fR inherits the value of the \fBPKG_INSTALL_ROOT\fR environment
variable. (See ENVIRONMENT VARIABLES, below.) If \fBPKG_INSTALL_ROOT\fR is set,
such as when the \fB-R\fR option is used with \fBpkgadd\fR(1M) or
\fBpkgrm\fR(1M), there is no need to use the \fBinstallf\fR \fB-R\fR option.
.LP
Note -
.sp
.RS 2
The root file system of any non-global zones must not be referenced with the
\fB-R\fR option. Doing so might damage the global zone's file system, might
compromise the security of the global zone, and might damage the non-global
zone's file system. See \fBzones\fR(5).
.RE
.RE

.sp
.ne 2
.na
\fB\fB-V\fR \fIfs_file\fR\fR
.ad
.RS 16n
Specify an alternative \fIfs_file\fR to map the client's file systems. For
example, used in situations where the \fB$\fR\fIroot_path\fR\fB/etc/vfstab\fR
file is non-existent or unreliable.
.RE

.SH OPERANDS
.sp
.ne 2
.na
\fB\fIpkginst\fR\fR
.ad
.RS 12n
Name of package instance with which the pathname should be associated.
.RE

.sp
.ne 2
.na
\fB\fIpathname\fR\fR
.ad
.RS 12n
Pathname that is being created or modified.
.RE

.sp
.ne 2
.na
\fB\fIftype\fR\fR
.ad
.RS 12n
A one-character field that indicates the file type. Possible file types
include:
.sp
.ne 2
.na
\fB\fBb\fR\fR
.ad
.RS 5n
block special device
.RE

.sp
.ne 2
.na
\fB\fBc\fR\fR
.ad
.RS 5n
character special device
.RE

.sp
.ne 2
.na
\fB\fBd\fR\fR
.ad
.RS 5n
directory
.RE

.sp
.ne 2
.na
\fB\fBe\fR\fR
.ad
.RS 5n
a file to be edited upon installation or removal
.RE

.sp
.ne 2
.na
\fB\fBf\fR\fR
.ad
.RS 5n
a standard executable or data file
.RE

.sp
.ne 2
.na
\fB\fBl\fR\fR
.ad
.RS 5n
linked file
.RE

.sp
.ne 2
.na
\fB\fBp\fR\fR
.ad
.RS 5n
named pipe
.RE

.sp
.ne 2
.na
\fB\fBs\fR\fR
.ad
.RS 5n
symbolic link
.RE

.sp
.ne 2
.na
\fB\fBv\fR\fR
.ad
.RS 5n
volatile file (one whose contents are expected to change)
.RE

.sp
.ne 2
.na
\fB\fBx\fR\fR
.ad
.RS 5n
an exclusive directory
.RE

.RE

.sp
.ne 2
.na
\fB\fImajor\fR\fR
.ad
.RS 12n
The major device number. The field is only specified for block or character
special devices.
.RE

.sp
.ne 2
.na
\fB\fIminor\fR\fR
.ad
.RS 12n
The minor device number. The field is only specified for block or character
special devices.
.RE

.sp
.ne 2
.na
\fB\fImode\fR\fR
.ad
.RS 12n
The octal mode of the file (for example, 0664). A question mark (\fB?\fR)
indicates that the mode will be left unchanged, implying that the file already
exists on the target machine. This field is not used for linked or symbolically
linked files.
.RE

.sp
.ne 2
.na
\fB\fIowner\fR\fR
.ad
.RS 12n
The owner of the file (for example, \fBbin\fR or \fBroot\fR). The field is
limited to 14 characters in length. A question mark (\fB?\fR) indicates that
the owner will be left unchanged, implying that the file already exists on the
target machine. This field is not used for linked or symbolically linked files.
.RE

.sp
.ne 2
.na
\fB\fIgroup\fR\fR
.ad
.RS 12n
The group to which the file belongs (for example, \fBbin\fR or \fBsys\fR). The
field is limited to 14 characters in length. A question mark (\fB?\fR)
indicates that the group will be left unchanged, implying that the file already
exists on the target machine. This field is not used for linked or symbolically
linked files.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRBasic Usage
.sp
.LP
The following example shows the use of \fBinstallf\fR, invoked from an optional
pre-install or post-install script:

.sp
.in +2
.nf
# create /dev/xt directory
# (needs to be done before drvinstall)
installf $PKGINST /dev/xt d 755 root sys ||
	exit 2
majno=`/usr/sbin/drvinstall \fB-m\fR /etc/master.d/xt
     \fB-d\fR $BASEDIR/data/xt.o \fB-v\fR1.0` ||
	exit 2
i=00
while [ $i \(milt $limit ]
do
    for j in 0 1 2 3 4 5 6 7
    do
        echo /dev/xt$i$j c $majno `expr $i ? 8 + $j`
             644 root sys |
        echo /dev/xt$i$j=/dev/xt/$i$j
    done
    i=`expr $i + 1`
    [ $i \(mile 9 ] && i="0$i" #add leading zero
done | installf $PKGINST \(mi || exit 2
# finalized installation, create links
installf \fB-f\fR $PKGINST || exit 2
.fi
.in -2
.sp

.SH ENVIRONMENT VARIABLES
.sp
.LP
\fBinstallf\fR inherits the value of the following environment variable. This
variable is set when \fBpkgadd\fR(1M) or \fBpkgrm\fR(1M) is invoked with the
\fB-R\fR option.
.sp
.ne 2
.na
\fB\fBPKG_INSTALL_ROOT\fR\fR
.ad
.RS 20n
If present, defines the full path name of a directory to use as the system's
\fBPKG_INSTALL_ROOT\fR path. All product and package information files are then
looked for in the directory tree, starting with the specified
\fBPKG_INSTALL_ROOT\fR path. If not present, the default system path of \fB/\fR
is used.
.RE

.SH EXIT STATUS
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 6n
Successful operation.
.RE

.sp
.ne 2
.na
\fB\fB>0\fR\fR
.ad
.RS 6n
An error occurred.
.RE

.SH SEE ALSO
.sp
.LP
\fBpkginfo\fR(1), \fBpkgmk\fR(1), \fBpkgparam\fR(1), \fBpkgproto\fR(1),
\fBpkgtrans\fR(1), \fBpkgadd\fR(1M), \fBpkgask\fR(1M), \fBpkgchk\fR(1M),
\fBpkgrm\fR(1M), \fBremovef\fR(1M), \fBpkgmap\fR(4), \fBspace\fR(4),
\fBattributes\fR(5), \fBlargefile\fR(5)
.sp
.LP
\fI\fR
.SH NOTES
.sp
.LP
When \fIftype\fR is specified, all applicable fields, as shown below, must be
defined:
.sp

.sp
.TS
box;
l l
l l .
\fIftype\fR	Required Fields
\fBp\fR, \fBx\fR, \fBd\fR, \fBf\fR, \fBv\fR, or \fBe\fR	\fBmode  owner  group\fR
\fBc\fR or \fBb\fR	\fBmajor  minor mode  owner  group\fR
.TE

.sp
.LP
The \fBinstallf\fR command will create directories, named pipes and special
devices on the original invocation. Links are created when \fBinstallf\fR is
invoked with the \fB-f\fR option to indicate installation is complete.
.sp
.LP
Links should be specified as \fIpath1\fR\fB=\fR\fIpath2.\fR \fIpath1\fR
indicates the destination and \fIpath2\fR indicates the source file.
.sp
.LP
Files installed with \fBinstallf\fR will be placed in the class \fBnone\fR,
unless a class is defined with the command. Subsequently, they will be removed
when the associated package is deleted. If this file should not be deleted at
the same time as the package, be certain to assign it to a class which is
ignored at removal time. If special action is required for the file before
removal, a class must be defined with the command and an appropriate class
action script delivered with the package.
.sp
.LP
When classes are used, \fBinstallf\fR must be used in one of the following
forms:
.sp
.in +2
.nf
installf \fB-c\fR class1 .\|.\|.\|
installf \fB-f\fR \fB-c\fR class1 .\|.\|.\|
installf \fB-c\fR class2 .\|.\|.\|
installf \fB-f\fR \fB-c\fR class2 .\|.\|.\|
.fi
.in -2
.sp