Add manpages, with a few minor changes from old ones.

ok pval

1 files changed, 426 insertions, 0 deletions

diff --git a/usr.sbin/pkg_add/pkg_add.1 b/usr.sbin/pkg_add/pkg_add.1
new file mode 100644
index 00000000000..711a969f055
--- /dev/null
+++ b/usr.sbin/pkg_add/pkg_add.1
@@ -0,0 +1,426 @@
+.\"	$OpenBSD: pkg_add.1,v 1.1 2003/10/19 18:38:06 espie Exp $
+.\"
+.\" FreeBSD install - a package for the installation and maintenance
+.\" of non-core utilities.
+.\"
+.\" 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.
+.\"
+.\" Jordan K. Hubbard
+.\"
+.\"
+.\"     @(#)pkg_add.1
+.\"
+.Dd November 25, 1994
+.Dt PKG_ADD 1
+.Os
+.Sh NAME
+.Nm pkg_add
+.Nd install software package distributions
+.Sh SYNOPSIS
+.Nm pkg_add
+.Op Fl vInfRMS
+.Op Fl t Ar template
+.Op Fl p Ar prefix
+.Ar pkg-name Op Ar ...
+.Sh DESCRIPTION
+The
+.Nm
+command is used to extract packages that have been previously created
+with the
+.Xr pkg_create 1
+command.
+Selected packages containing pre-compiled applications from the
+.Pa /usr/ports
+tree can be found on the
+.Ox
+FTP site or on the official
+.Ox
+CD.
+These packages are provided as a convenience for quickly installing software
+that would otherwise need to be built manually.
+.Bd -filled -offset indent
+.Em Note :
+System distribution files, e.g. base28.tgz, comp28.tgz, etc., are
+.Em not
+packages and may not be installed using
+.Nm pkg_add .
+.Ed
+.Pp
+Package names may be specified as filenames (which normally consist of the
+package name itself plus the
+.Dq .tgz ,
+.Dq .tar.gz ,
+or
+.Dq .tar
+suffix) or an FTP location in the form of an URL.
+For example, the following is valid:
+.Pp
+.Ic pkg_add -v ftp://ftp.openbsd.org/pub/OpenBSD/2.7/packages/i386/m4-1.4.tgz
+.Pp
+If the given package names are not found in the current working directory,
+.Nm
+will search for them in each directory named by the
+.Ev PKG_PATH
+environment variable.
+Specifying
+.Ql -
+as a package name causes
+.Nm
+to read from the standard input.
+.Pp
+Alternatively, it is possible to add packages interactively from within
+the ftp client.
+For example, the following works:
+.Bd -literal
+	$ ftp ftp://ftp.openbsd.org/pub/OpenBSD/2.7/packages/i386/
+	250 CWD command successful
+	ftp> ls m*
+	227 Entering Passive Mode (129,128,5,191,164,73)
+	150 Opening ASCII mode data connection for m*.
+	m4-1.4.tgz
+	metamail-2.7.tgz
+	mh-6.8.4.tgz
+	mm-1.0.12.tgz
+	mpeg_lib-1.2.1.tgz
+	mpeg_play-2.4.tgz
+	mpg123-0.59q.tgz
+	mutt-0.95.7i.tgz
+	226 Transfer complete.
+	ftp> get m4-1.4.tgz "|pkg_add -v -"
+.Ed
+.Pp
+.Sy Warning:
+Since the
+.Nm
+command may execute scripts or programs contained within a package file,
+your system may be susceptible to
+.Dq trojan horses
+or other subtle attacks from miscreants who create dangerous packages.
+Be sure the specified package(s) are from trusted sources.
+.Pp
+The options are as follows:
+.Bl -tag -width Ds
+.It Fl v
+Turn on verbose output.
+.It Fl I
+If an installation script exists for a given package, do not execute it.
+.It Fl n
+Don't actually install a package, just report the steps that
+would be taken if it was.
+.It Fl R
+Do not record the installation of a package.
+This means that you cannot deinstall it later, so only use this option if
+you know what you are doing!
+.It Fl f
+Force installation to proceed even if prerequisite packages are not
+installed or the requirements script fails.
+Although
+.Nm
+will still try to find and auto-install missing prerequisite packages,
+a failure to find one will not be fatal.
+.It Fl p Ar prefix
+Set
+.Ar prefix
+as the directory in which to extract files from a package.
+If a package has set its default directory, it will be overridden
+by this flag.
+Note that only the first
+.Cm @cwd
+directive will be replaced, since
+.Nm
+has no way of knowing which directory settings are relative and
+which are absolute.
+It is rare in any case to see more than one
+directory transition made, but when such does happen and you wish
+to have control over
+.Em all
+directory transitions, then you may then wish to look into the use of
+.Cm MASTER
+and
+.Cm SLAVE
+modes (see the
+.Fl M
+and
+.Fl S
+options).
+.It Fl t Ar template
+Use
+.Ar template
+as the input to
+.Xr mkdtemp 3
+when creating a
+.Dq staging area .
+By default, this is the string
+.Pa /var/tmp/instmp.XXXXXX ,
+but it may be necessary to override it (see CAVEATS).
+Be sure to leave some number of
+.Dq X
+characters for
+.Xr mkdtemp 3
+to fill in with a unique ID.
+.Pp
+You can get a performance boost by setting the staging area
+.Ar template
+to reside on the same disk partition as target directories for package
+file installation; often this is
+.Pa /usr .
+.It Fl M
+Run in
+.Cm MASTER
+mode.
+This is a very specialized mode for running
+.Nm
+and is meant to be run in conjunction with
+.Cm SLAVE
+mode.
+When run in this mode,
+.Nm
+does no work beyond extracting the package into a temporary staging
+area (see the
+.Fl t
+option), reading in the packing list, and then dumping it (prefaced by
+the current staging area) to the standard output where it may be filtered by a
+program such as
+.Xr sed 1 .
+When used in conjunction with
+.Cm SLAVE
+mode, it allows you to make radical changes to the package structure
+before acting on its contents.
+.It Fl S
+Run in
+.Cm SLAVE
+mode.
+This is a very specialized mode for running
+.Nm
+and is meant to be run in conjunction with
+.Cm MASTER
+mode.
+When run in this mode,
+.Nm
+expects the release contents to be already extracted and waiting
+in the staging area, the location of which is read as a string
+from the standard input.
+The complete packing list is also read from stdin,
+and the contents then acted on as normal.
+.El
+.Pp
+By default, when adding packages via FTP, the
+.Xr ftp 1
+program operates in
+.Dq passive
+mode.
+If you wish to use active mode instead, set the
+.Ev FTPMODE
+environment variable to
+.Qq active .
+If
+.Nm
+consistently fails to fetch a package from a site known to work,
+it may be because the site does not support
+passive mode ftp correctly.
+This is very rare since
+.Nm
+will try active mode ftp if the server refuses a passive mode
+connection.
+.Ss Technical details
+.Nm
+extracts each package's
+.Dq packing list
+into a special staging directory in
+.Pa /var/tmp
+(or
+.Ev PKG_TMPDIR
+if set - see CAVEATS section)
+and then runs through the following sequence to fully extract the contents
+of the package:
+.Bl -enum
+.It
+A check is made to determine if the package is already recorded as installed.
+If it is,
+installation is terminated.
+.It
+A check is made to determine if the package conflicts (from
+.Cm @pkgcfl
+directives, see
+.Xr pkg_create 1 )
+with an already recorded as installed package.
+If it is, installation is terminated.
+.It
+All package dependencies (from
+.Cm @pkgdep
+directives, see
+.Xr pkg_create 1 )
+are read from the packing list.
+If any of these required packages are not currently installed,
+an attempt is made to find and install it;
+if the missing package cannot be found or installed,
+the installation is terminated.
+.It
+A staging area is created under
+.Pa /var/tmp ,
+and the package is extracted into the staging area.
+.It
+If the package contains a
+.Ar require
+script (see
+.Xr pkg_create 1 ) ,
+it is executed with the following arguments:
+.Bl -tag -width indentindent
+.It Ar pkg-name
+The name of the package being installed
+.It Cm INSTALL
+Keyword denoting to the script that it is to run an installation requirements
+check
+(the keyword is useful only to scripts which serve multiple functions).
+.El
+.Pp
+If the
+.Ar require
+script exits with a non-zero status code, the installation is terminated.
+.It
+If the package contains an
+.Ar install
+script, it is executed with the following arguments:
+.Bl -tag -width indentindent
+.It Ar pkg-name
+The name of the package being installed.
+.It Cm PRE-INSTALL
+Keyword denoting that the script is to perform any actions needed before
+the package is installed.
+.El
+.Pp
+If the
+.Ar install
+script exits with a non-zero status code, the installation is terminated.
+.It
+The packing list is used as a guide for moving (or copying, as necessary)
+files from the staging area into their final locations.
+.It
+If the package contains an
+.Ar mtreefile
+file (see
+.Xr pkg_create 1 ) ,
+then mtree is invoked as:
+.Pp
+.Bd -filled -offset indent -compact
+.Cm mtree
+.Fl u
+.Fl f
+.Ar mtreefile
+.Fl d
+.Fl e
+.Fl p
+.Pa prefix
+.Ed
+.Pp
+where
+.Pa prefix
+is either the prefix specified with the
+.Fl p
+flag or, if no
+.Fl p
+flag was specified, the name of the first directory named by a
+.Cm @cwd
+directive within this package.
+.It
+If an
+.Ar install
+script exists for the package, it is executed with the following arguments:
+.Bl -tag -width indentindent
+.It Ar pkg_name
+The name of the package being installed.
+.It Cm POST-INSTALL
+Keyword denoting that the script is to perform any actions needed
+after the package has been installed.
+.El
+.It
+After installation is complete, a copy of the packing list,
+.Ar deinstall
+script, description, and display files are copied into
+.Pa /var/db/pkg/<pkg-name>
+for subsequent possible use by
+.Xr pkg_delete 1 .
+Any package dependencies are recorded in the other packages'
+.Pa /var/db/pkg/<other-pkg>/+REQUIRED_BY
+file
+(if the environment variable
+.Ev PKG_DBDIR
+is set, this overrides the
+.Pa /var/db/pkg/
+path shown above).
+.It
+Finally, the staging area is deleted and the program terminates.
+.El
+.Pp
+The
+.Ar install
+and
+.Ar require
+scripts are called with the environment variable
+.Ev PKG_PREFIX
+set to the installation prefix (see the
+.Fl p
+option above).
+This allows a package author to write a script
+that reliably performs some action on the directory where the package
+is installed, even if the user might change it with the
+.Fl p
+flag to
+.Cm pkg_add .
+.Sh ENVIRONMENT
+.Bl -tag -width PKG_TMPDIR
+.It Ev PKG_PATH
+If a given package name cannot be found,
+the directories named by
+.Ev PKG_PATH
+are searched.
+It should contain a series of entries separated by colons.
+Each entry consists of a directory name.
+The current directory may be indicated
+implicitly by an empty directory name, or explicitly by a single
+period
+.Pq Ql \&. .
+.It Ev PKG_DBDIR
+Where to register packages instead of
+.Pa /var/db/pkg .
+.It Ev PKG_TMPDIR
+Temporary area where packages will be extracted, instead of
+.Pa /var/tmp .
+.El
+.Sh SEE ALSO
+.Xr pkg_create 1 ,
+.Xr pkg_delete 1 ,
+.Xr pkg_info 1 ,
+.Xr mkdtemp 3 ,
+.Xr sysconf 3 ,
+.Xr mtree 8
+.Sh AUTHORS
+.Bl -tag -width indent -compact
+.It "Jordan Hubbard"
+Initial design.
+.It "Marc Espie"
+Complete rewrite.
+.El
+.Sh CAVEATS
+Package extraction does need a temporary area that
+.Bl -bullet -compact
+.It
+can hold executable scripts.
+.El
+.Pp
+.Nm
+looks through ${PKG_TMPDIR}, ${TMPDIR}, /var/tmp, /tmp, /usr/tmp
+for such an area, in sequence.
+.Pp
+If ${TMPDIR} and /var/tmp are mounted noexec, you must set PKG_TMPDIR
+to a suitable area, as
+.Nm
+has no way to check for noexec status except by failing to run installation
+scripts.