diff options
Diffstat (limited to 'usr.sbin/pkg_install/version/pkg_version.1')
| -rw-r--r-- | usr.sbin/pkg_install/version/pkg_version.1 | 263 |
1 files changed, 263 insertions, 0 deletions
diff --git a/usr.sbin/pkg_install/version/pkg_version.1 b/usr.sbin/pkg_install/version/pkg_version.1 new file mode 100644 index 0000000..26caf8c --- /dev/null +++ b/usr.sbin/pkg_install/version/pkg_version.1 @@ -0,0 +1,263 @@ +.\" +.\" Copyright 1998 Bruce A. Mah +.\" +.\" 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. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``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 DEVELOPERS 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. +.\" +.\" $FreeBSD$ +.\" +.Dd November 9, 2012 +.Dt PKG_VERSION 1 +.Os +.Sh NAME +.Nm pkg_version +.Nd summarize installed versions of packages +.Sh SYNOPSIS +.Nm +.Op Fl hIoqv +.Op Fl l Ar limchar +.Op Fl L Ar limchar +.Oo +.Op Fl X +.Fl s Ar string +.Oc +.Op Fl O Ar origin +.Op Ar index +.Nm +.Fl t Ar version1 version2 +.Nm +.Fl T Ar pkgname pattern +.Sh DESCRIPTION +The +.Nm +command is used to produce a report of non-base software packages +installed using the +.Xr pkg_add 1 +command. +.Pp +Each package's version number is checked against one of two sources to +see if that package may require updating. +If the package contains +information about its origin in the +.Fx +ports tree, and a version number can be determined from the port's +.Pa Makefile , +then the version number from the +.Pa Makefile +will be used to determine whether the installed package is up-to-date +or requires updating. +.Pp +If no origin for a package can be found, or if the port's +.Pa Makefile +cannot be located, +.Nm +will search for the package in the ports collection index file +(typically +.Pa /usr/ports/INDEX-8 ) . +Any matching version number(s) there will be used to determine whether +the installed package is up-to-date or requires updating. +.Pp +Generally, using the version number from a port's +.Pa Makefile +will provide a more accurate result, since, unlike the index file, it +provides an unambiguous current version number, even when multiple +versions of a port exist in the ports collection. +Moreover, the ports collection index file is only updated at +intervals, meaning that it may not completely reflect the version +numbers of the software contained in the ports collection. +.Pp +Each package name is printed, along with a one-character status flag: +.Bl -tag -width indent +.It Li = +The installed version of the package is current. +.It Li \&< +The installed version of the package is older than the current version. +.It Li \&> +The installed version of the package is newer than the current version. +This situation can arise with an out-of-date index file, or when +testing new ports. +.It Li \&? +The installed package does not appear in the index. +This could be due to an out of date index or a package taken from a PR +that has not yet been committed. +.It Li * +There are multiple versions of a particular software package +listed in the index file. +Examples from the +.Fx +ports collection are the Tcl toolkit or the +.Tn EMACS +editor. +.It Li \&! +The installed package exists in the index but for some reason, +.Nm +was unable to compare the version number of the installed package +with the corresponding entry in the index. +.El +.Sh OPTIONS +The +.Nm +utility supports several command-line arguments: +.Bl -tag -width indent +.It Fl h , -help +Print help message. +.It Fl I , -index-only +Use only the index file for determining if a package is out of date. +This is much faster than using the version number from a port's +Makefile, at the expense of potentially giving an incorrect result if +the index file is out of date. +.It Fl l , -status Ar limchar +Limit the output to those packages whose status flag matches the +character(s) in +.Ar limchar . +More than one character can be specified in +.Ar limchar . +Note that because some of the status flag characters are also special +to the shell, it is best to quote +.Ar limchar +with single quotes. +.It Fl L , -no-status Ar limchar +Limit the output to those packages whose status flag does not match +.Ar limchar . +You may specify more than one character to match in +.Ar limchar . +Note that because some of the status flag characters are also special +to the shell, it is best to quote +.Ar limchar +with single quotes. +.It Fl o , -show-origin +Show the origin recorded on package generation instead of the package +name. +.It Fl O , -origin Ar origin +Only list packages whose registered origin is +.Ar origin . +.It Fl q , -quiet +Enable quiet output. +Quiet output precludes printing the +.Ar limchar +when used with +.Fl l +or +.Fl L . +This is useful when used as the input to +.Xr portupgrade 8 . +.It Fl s , -match Ar string +Limit the output to those packages whose names match a given +.Ar string . +.It Fl X , -extended +Interpret +.Ar string +as a extended regular expression. +.It Fl t +Test a pair of version number strings and exit. +The output consists of one of the single characters +.Li = +(equal), +.Li \&< +(right-hand number greater), or +.Li \&> +(left-hand number greater) on standard output. +This flag is mostly useful for scripts or for testing. +.It Fl T +Test whether +.Ar pkgname +is matched by +.Ar pattern +and set the exit code accordingly. +.Fl T +can also be used in `filter mode': +When one of the arguments is `-', standard input is used, and lines +with matching package names/patterns are echoed to standard output. +.It Fl v +Enable verbose output. +Verbose output includes some English-text +interpretations of the version number comparisons, as well as the +version numbers compared for each package. +Non-verbose output is +probably easier for programs or scripts to parse. +.It Ar index +Specify the index to be used as a basis of comparison. +This index can +be specified as a filename (in the local file system) or a URL. +Any +URL understandable by +.Xr fetch 1 +can be used here. +If no +.Ar index +file is specified on the command line, +.Pa /usr/ports/INDEX-8 +is used. +.El +.Sh FILES +.Bl -tag -width /usr/ports/INDEX-8 -compact +.It Pa /usr/ports/INDEX-8 +Default index file. +.El +.Sh EXAMPLES +The following is a typical invocation of the +.Nm +command, which checks the installed packages against the local ports +index file: +.Pp +.Dl % pkg_version -v +.Pp +The command below generates a report against +the version numbers in the on-line ports collection: +.Pp +.Dl % pkg_version http://www.FreeBSD.org/ports/INDEX-8 +.Pp +The following command compares two package version strings: +.Pp +.Dl % pkg_version -t 1.5 1.5.1 +.Sh COMPATIBILITY +The +.Fl c +option has been deprecated and is no longer supported. +.Sh ENVRIOMENT +.Bl -tag -width indent +.It Ev PKG_OLD_NOWARN +If set +.Nm +will not warn about its use in the presence of pkgng databases. +.El +.Sh SEE ALSO +.Xr fetch 1 , +.Xr pkg_add 1 , +.Xr pkg_create 1 , +.Xr pkg_delete 1 , +.Xr pkg_info 1 , +.Xr portupgrade 8 +.Sh AUTHORS +The +.Nm +utility was written by +.An Jeremy D. Lea Aq reg@FreeBSD.org , +partially based on a Perl script written by +.An Bruce A. Mah Aq bmah@FreeBSD.org . +.Sh CONTRIBUTORS +.An Nik Clayton Aq nik@FreeBSD.org , +.An Dominic Mitchell Aq dom@palmerharvey.co.uk , +.An Mark Ovens Aq marko@FreeBSD.org , +.An Doug Barton Aq DougB@gorean.org , +.An Akinori MUSHA Aq knu@FreeBSD.org , +.An Oliver Eikemeier Aq eik@FreeBSD.org |
