pkg_version(1)

NAME

pkg_version - summarize installed versions of packages

SYNOPSIS

pkg_version [-hIoqv] [-l  limchar]  [-L  limchar]  [[-X]  -s
string]
            [-O origin] [index]
pkg_version -t version1 version2
pkg_version -T pkgname pattern

DESCRIPTION

The pkg_version command is used to produce a report of non

base software
packages installed using the pkg_add(1) 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 FreeBSD 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, pkg_version will search for the package in the

ports collection index file (typically /usr/ports/INDEX-6). Any match

ing version
number(s) there will be used to determine whether the in

stalled 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 pro

vides an unambiguous current version number, even when multiple versions

of a port
exist in the ports collection. Moreover, the ports collec

tion index file
is only updated at intervals, meaning that it may not com

pletely 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 FreeBSD

ports collection are the Tcl toolkit or the EMACS editor.

! The installed package exists in the index but for

some reason,

pkg_version was unable to compare the version number

of the
installed package with the corresponding entry in

the index.

OPTIONS

The pkg_version utility supports several command-line argu

ments:

-h Print help message.

-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 giv

ing an incorrect result if the index file is out of date.

-l 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 sta

tus flag characters are also special to the shell, it is best to

quote limchar
with single quotes.

-L Limit the output to those packages whose status flag

does not

match limchar. You may specify more than one char

acter 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 the origin recorded on package generation in

stead of the

package name.

-O Only list packages whose registered origin is

origin.

-q Enable quiet output. Quiet output precludes print

ing the limchar

when used with -l or -L. This is useful when used

as the input
to portupgrade(8).

-s Limit the output to those packages whose names match

a given

string.

-X Interpret string as a extended regular expression.

-t Test a pair of version number strings and exit. The

output con

sists 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 stan

dard 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-ver

bose output is
probably easier for programs or scripts to parse.

index Specify the index to be used as a basis of compari

son. 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-6 is used.

FILES

/usr/ports/INDEX-6 Default index file.

EXAMPLES

The following is a typical invocation of the pkg_version

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:

% pkg_version http://www.FreeBSD.org/ports/INDEX-6

The following command compares two package version strings:

% pkg_version -t 1.5 1.5.1

COMPATIBILITY

The -c option has been deprecated and is no longer support

ed.

SEE ALSO

fetch(1), pkg_add(1), pkg_create(1), pkg_delete(1), pkg_in

fo(1),
portupgrade(8)

AUTHORS

The pkg_version utility was written by Jeremy D. Lea

<reg@FreeBSD.org>,
partially based on a Perl script written by
Bruce A. Mah <bmah@FreeBSD.org>.

CONTRIBUTORS

Nik Clayton <nik@FreeBSD.org>, Dominic Mitchell <dom@palmer

harvey.co.uk>,
Mark Ovens <marko@FreeBSD.org>, Doug Barton <DougB@gore

an.org>, Akinori
MUSHA <knu@FreeBSD.org>, Oliver Eikemeier <eik@FreeBSD.org>

BSD Jul 27, 2005

BSD