The
command is used to produce a report of non-base software packages
installed using the
pkg_add1
command.
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
Makefile
then the version number from the
Makefile
will be used to determine whether the installed package is up-to-date
or requires updating.
If no origin for a package can be found, or if the port's
Makefile
cannot be located,
will search for the package in the ports collection index file
(typically
/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.
Generally, using the version number from a port's
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.
Each package name is printed, along with a one-character status flag:
=
The installed version of the package is current.
<
The installed version of the package is older than the current version.
>
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.
?
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.
*
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
EMACS
editor.
!
The installed package exists in the index but for some reason,
was unable to compare the version number of the installed package
with the corresponding entry in the index.
OPTIONS
The
utility supports several command-line arguments:
-h , -help
Print help message.
-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.
-l , -status limchar
Limit the output to those packages whose status flag matches the
character(s) in
limchar
More than one character can be specified in
limchar
Note that because some of the status flag characters are also special
to the shell, it is best to quote
limchar
with single quotes.
-L , -no-status limchar
Limit the output to those packages whose status flag does not match
limchar
You may specify more than one character to match in
limchar
Note that because some of the status flag characters are also special
to the shell, it is best to quote
limchar
with single quotes.
-o , -show-origin
Show the origin recorded on package generation instead of the package
name.
-O , -origin origin
Only list packages whose registered origin is
origin
-q , -quiet
Enable quiet output.
Quiet output precludes printing the
limchar
when used with
-l
or
-L
This is useful when used as the input to
portupgrade(8).
-s , -match string
Limit the output to those packages whose names match a given
string
-X , -extended
Interpret
string
as a extended regular expression.
-t
Test a pair of version number strings and exit.
The output consists of one of the single characters
=
(equal),
<
(right-hand number greater), or
>
(left-hand number greater) on standard output.
This flag is mostly useful for scripts or for testing.
-T
Test whether
pkgname
is matched by
pattern
and set the exit code accordingly.
-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.
-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.
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
fetch(1)
can be used here.
If no
index
file is specified on the command line,
/usr/ports/INDEX-8
is used.
FILES
/usr/ports/INDEX-8
Default index file.
EXAMPLES
The following is a typical invocation of the
command, which checks the installed packages against the local ports
index file:
% pkg_version -v
The command below generates a report against
the version numbers in the on-line ports collection:
