usr.sbin/pkg_install/version/pkg_version.1

   1 .\"
   2 .\" Copyright 1998 Bruce A. Mah
   3 .\"
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
  16 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  17 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  18 .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
  19 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  20 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  21 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  22 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  23 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  24 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD: src/usr.sbin/pkg_install/version/pkg_version.1,v 1.27 2004/07/02 23:12:53 ru Exp $
  27 .\" $DragonFly: src/usr.sbin/pkg_install/version/Attic/pkg_version.1,v 1.3 2004/07/30 04:46:14 dillon Exp $
  28 .Dd June 29, 2004
  29 .Dt PKG_VERSION 1
  30 .Os
  31 .Sh NAME
  32 .Nm pkg_version
  33 .Nd summarize installed versions of packages
  34 .Sh SYNOPSIS
  35 .Nm
  36 .Op Fl hv
  37 .Op Fl l Ar limchar
  38 .Op Fl L Ar limchar
  39 .Oo
  40 .Op Fl X
  41 .Fl s Ar string
  42 .Oc
  43 .Op Ar index
  44 .Nm
  45 .Op Fl t Ar version1 version2
  46 .Nm
  47 .Op Fl T Ar pkgname pattern
  48 .Sh DESCRIPTION
  49 The
  50 .Nm
  51 command is used to produce a report of non-base software packages
  52 installed using the
  53 .Xr pkg_add 1
  54 command.
  55 .Pp
  56 Each package's version number is checked against one of two sources to
  57 see if that package may require updating.
  58 If the package contains
  59 information about its origin in the
  60 .Fx
  61 ports tree, and a version number can be determined from the port's
  62 .Pa Makefile ,
  63 then the version number from the
  64 .Pa Makefile
  65 will be used to determine whether the installed package is up-to-date
  66 or requires updating.
  67 .Pp
  68 If no origin for a package can be found, or if the port's
  69 .Pa Makefile
  70 cannot be located,
  71 .Nm
  72 will search for the package in the ports collection index file
  73 (typically
  74 .Pa /usr/ports/INDEX-5 ) .
  75 Any matching version number(s) there will be used to determine whether
  76 the installed package is up-to-date or requires updating.
  77 .Pp
  78 Generally, using the version number from a port's
  79 .Pa Makefile
  80 will provide a more accurate result, since, unlike the index file, it
  81 provides an unambiguous current version number, even when multiple
  82 versions of a port exist in the ports collection.
  83 Moreover, the ports collection index file is only updated at
  84 intervals, meaning that it may not completely reflect the version
  85 numbers of the software contained in the ports collection.
  86 .Pp
  87 Each package name is printed, along with a one-character status flag:
  88 .Bl -tag -width indent
  89 .It Li =
  90 The installed version of the package is current.
  91 .It Li \&<
  92 The installed version of the package is older than the current version.
  93 .It Li \&>
  94 The installed version of the package is newer than the current version.
  95 This situation can arise with an out-of-date index file, or when
  96 testing new ports.
  97 .It Li \&?
  98 The installed package does not appear in the index.
  99 This could be due to an out of date index or a package taken from a PR
 100 that has not yet been committed.
 101 .It Li *
 102 There are multiple versions of a particular software package
 103 listed in the index file.
 104 Examples from the
 105 .Fx
 106 ports collection are the Tcl toolkit or the
 107 .Tn EMACS
 108 editor.
 109 .It Li \&!
 110 The installed package exists in the index but for some reason,
 111 .Nm
 112 was unable to compare the version number of the installed package
 113 with the corresponding entry in the index.
 114 .El
 115 .Sh OPTIONS
 116 The
 117 .Nm
 118 utility supports several command-line arguments:
 119 .Bl -tag -width indent
 120 .It Fl h
 121 Print help message.
 122 .It Fl l
 123 Limit the output to those packages whose status flag matches the
 124 character(s) in
 125 .Ar limchar .
 126 More than one character can be specified in
 127 .Ar limchar .
 128 Note that because some of the status flag characters are also special
 129 to the shell, it is best to quote
 130 .Ar limchar
 131 with single quotes.
 132 .It Fl L
 133 Limit the output to those packages whose status flag doesn't match
 134 .Ar limchar .
 135 You may specify more than one character to match in
 136 .Ar limchar .
 137 Note that because some of the status flag characters are also special
 138 to the shell, it is best to quote
 139 .Ar limchar
 140 with single quotes.
 141 .It Fl s
 142 Limit the output to those packages whose names match a given
 143 .Ar string .
 144 .It Fl X
 145 Interpret
 146 .Ar string
 147 as a extended regular expression.
 148 .It Fl t
 149 Test a pair of version number strings and exit.
 150 The output consists of one of the single characters
 151 .Li =
 152 (equal),
 153 .Li \&<
 154 (right-hand number greater), or
 155 .Li \&>
 156 (left-hand number greater) on standard output.
 157 This flag is mostly useful for scripts or for testing.
 158 .It Fl T
 159 Test whether
 160 .Ar pkgname
 161 is matched by
 162 .Ar pattern
 163 and set the exit code accordingly.
 164 .Fl T
 165 can also be used in `filter mode':
 166 When one of the arguments is `-', standard input is used, and lines
 167 with matching package names/patterns are echoed to standard output.
 168 .It Fl v
 169 Enable verbose output.
 170 Verbose output includes some English-text
 171 interpretations of the version number comparisons, as well as the
 172 version numbers compared for each package.
 173 Non-verbose output is
 174 probably easier for programs or scripts to parse.
 175 .It Ar index
 176 Specify the index to be used as a basis of comparison.
 177 This index can
 178 be specified as a filename (in the local file system) or a URL.
 179 Any
 180 URL understandable by
 181 .Xr fetch 1
 182 can be used here.
 183 If no
 184 .Ar index
 185 file is specified on the command line,
 186 .Pa /usr/ports/INDEX-5
 187 is used.
 188 .El
 189 .Sh COMPATIBILITY
 190 The
 191 .Fl c
 192 option has been deprecated and is no longer supported.
 193 .Sh SEE ALSO
 194 .Xr fetch 1 ,
 195 .Xr pkg_add 1 ,
 196 .Xr pkg_create 1 ,
 197 .Xr pkg_delete 1 ,
 198 .Xr pkg_info 1
 199 .Sh FILES
 200 .Bl -tag -width /usr/ports/INDEX-5 -compact
 201 .It Pa /usr/ports/INDEX-5
 202 Default index file.
 203 .El
 204 .Sh EXAMPLES
 205 The following is a typical invocation of the
 206 .Nm
 207 command, which checks the installed packages against the local ports
 208 index file:
 209 .Pp
 210 .Dl % pkg_version -v
 211 .Pp
 212 The command below generates a report against
 213 the version numbers in the on-line ports collection:
 214 .Pp
 215 .Dl % pkg_version http://www.FreeBSD.org/ports/INDEX-5
 216 .Pp
 217 The following command compares two package version strings:
 218 .Pp
 219 .Dl % pkg_version -t 1.5 1.5.1
 220 .Sh AUTHORS
 221 The
 222 .Nm
 223 utility was written by
 224 .An Jeremy D. Lea Aq reg@FreeBSD.org ,
 225 partially based on a Perl script written by
 226 .An Bruce A. Mah Aq bmah@FreeBSD.org .
 227 .Sh CONTRIBUTORS
 228 .An Nik Clayton Aq nik@FreeBSD.org ,
 229 .An Dominic Mitchell Aq dom@palmerharvey.co.uk ,
 230 .An Mark Ovens Aq marko@FreeBSD.org ,
 231 .An Doug Barton Aq DougB@gorean.org ,
 232 .An Akinori MUSHA Aq knu@FreeBSD.org ,
 233 .An Oliver Eikemeier Aq eik@FreeBSD.org