257 lines
7.4 KiB
Groff
257 lines
7.4 KiB
Groff
.\"
|
|
.\" 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 July 27, 2005
|
|
.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-6 ) .
|
|
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
|
|
Print help message.
|
|
.It Fl I
|
|
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
|
|
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
|
|
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 the origin recorded on package generation instead of the package
|
|
name.
|
|
.It Fl O
|
|
Only list packages whose registered origin is
|
|
.Ar origin .
|
|
.It Fl q
|
|
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
|
|
Limit the output to those packages whose names match a given
|
|
.Ar string .
|
|
.It Fl X
|
|
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-6
|
|
is used.
|
|
.El
|
|
.Sh FILES
|
|
.Bl -tag -width /usr/ports/INDEX-6 -compact
|
|
.It Pa /usr/ports/INDEX-6
|
|
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-6
|
|
.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 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
|