.\" .\" 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: src/usr.sbin/pkg_install/version/pkg_version.1,v 1.16 2001/04/04 11:19:09 ru Exp $ .Dd July 17, 1998 .Dt PKG_VERSION 1 .Os FreeBSD .Sh NAME .Nm pkg_version .Nd summarize installed versions of packages .Sh SYNOPSIS .Nm .Op Fl cdhv .Op Fl l Ar limchar .Op Fl L Ar limchar .Op Ar index .Nm .Op Fl t Ar version1 version2 .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 ) . 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 .Nm supports several command-line arguments: .Bl -tag -width indent .It Fl c Enable commands output. Commands output includes the commands you should type to update your installed packages to the latest versions in the ports system. This feature does .Bf Em not .Ef constitute an automated packages updating system. The output of this command .Bf Em must .Ef be edited, in order to avoid destroying dependencies between installed packages. .It Fl d Enable debugging output. .It Fl h Print help message. .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 doesn't 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 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 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 filesystem) 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 is used. .El .Sh SEE ALSO .Xr fetch 1 , .Xr pkg_add 1 , .Xr pkg_create 1 , .Xr pkg_delete 1 , .Xr pkg_info 1 .Sh FILES .Bl -tag -width /usr/ports/INDEX -compact .It Pa /usr/ports/INDEX 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 ftp://ftp.FreeBSD.org/pub/FreeBSD/branches/-current/ports/INDEX .Pp The command below generates a file of commands to run to update the installed files. These commands must .Bf Em not .Ef be run without suitable editing. They should be treated as suggestions, and may need to be reordered to account for dependencies between installed packages, or may need to be disregarded if multiple versions of an installed package can coexist. Blindly running the output of this command may leave a system in an unusable state. .Pp .Dl % pkg_version -c > do_update .Pp The following command compares two package version strings: .Pp .Dl % pkg_version -t 1.5 1.5.1 .Sh AUTHORS .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 .Sh BUGS .Pp The commands output feature is .Bf Em not .Ef an automated ports/packages updating system. It does not even attempt to handle dependencies between installed packages correctly, and can produce incorrect results if multiple versions of a package can coexist on a system. .Pp Commands output assumes you install new software using the ports system, rather than using .Xr pkg_add 1 .