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$
  27 .\"
  28 .Dd May 24, 2005
  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 hIqv
  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 .Fl t Ar version1 version2
  46 .Nm
  47 .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-6 ) .
  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 I
 123 Use only the index file for determining if a package is out of date.
 124 This is much faster than using the version number from a port's
 125 Makefile, at the expense of potentially giving an incorrect result if
 126 the index file is out of date.
 127 .It Fl l
 128 Limit the output to those packages whose status flag matches the
 129 character(s) in
 130 .Ar limchar .
 131 More than one character can be specified in
 132 .Ar limchar .
 133 Note that because some of the status flag characters are also special
 134 to the shell, it is best to quote
 135 .Ar limchar
 136 with single quotes.
 137 .It Fl L
 138 Limit the output to those packages whose status flag does not match
 139 .Ar limchar .
 140 You may specify more than one character to match in
 141 .Ar limchar .
 142 Note that because some of the status flag characters are also special
 143 to the shell, it is best to quote
 144 .Ar limchar
 145 with single quotes.
 146 .It Fl q
 147 Enable quiet output.
 148 Quiet output precludes printing the
 149 .Ar limchar
 150 when used with
 151 .Fl l
 152 or
 153 .Fl L .
 154 This is useful when used as the input to
 155 .Xr portupgrade 8 .
 156 .It Fl s
 157 Limit the output to those packages whose names match a given
 158 .Ar string .
 159 .It Fl X
 160 Interpret
 161 .Ar string
 162 as a extended regular expression.
 163 .It Fl t
 164 Test a pair of version number strings and exit.
 165 The output consists of one of the single characters
 166 .Li =
 167 (equal),
 168 .Li \&<
 169 (right-hand number greater), or
 170 .Li \&>
 171 (left-hand number greater) on standard output.
 172 This flag is mostly useful for scripts or for testing.
 173 .It Fl T
 174 Test whether
 175 .Ar pkgname
 176 is matched by
 177 .Ar pattern
 178 and set the exit code accordingly.
 179 .Fl T
 180 can also be used in `filter mode':
 181 When one of the arguments is `-', standard input is used, and lines
 182 with matching package names/patterns are echoed to standard output.
 183 .It Fl v
 184 Enable verbose output.
 185 Verbose output includes some English-text
 186 interpretations of the version number comparisons, as well as the
 187 version numbers compared for each package.
 188 Non-verbose output is
 189 probably easier for programs or scripts to parse.
 190 .It Ar index
 191 Specify the index to be used as a basis of comparison.
 192 This index can
 193 be specified as a filename (in the local file system) or a URL.
 194 Any
 195 URL understandable by
 196 .Xr fetch 1
 197 can be used here.
 198 If no
 199 .Ar index
 200 file is specified on the command line,
 201 .Pa /usr/ports/INDEX-6
 202 is used.
 203 .El
 204 .Sh FILES
 205 .Bl -tag -width /usr/ports/INDEX-6 -compact
 206 .It Pa /usr/ports/INDEX-6
 207 Default index file.
 208 .El
 209 .Sh EXAMPLES
 210 The following is a typical invocation of the
 211 .Nm
 212 command, which checks the installed packages against the local ports
 213 index file:
 214 .Pp
 215 .Dl % pkg_version -v
 216 .Pp
 217 The command below generates a report against
 218 the version numbers in the on-line ports collection:
 219 .Pp
 220 .Dl % pkg_version http://www.FreeBSD.org/ports/INDEX-6
 221 .Pp
 222 The following command compares two package version strings:
 223 .Pp
 224 .Dl % pkg_version -t 1.5 1.5.1
 225 .Sh COMPATIBILITY
 226 The
 227 .Fl c
 228 option has been deprecated and is no longer supported.
 229 .Sh SEE ALSO
 230 .Xr fetch 1 ,
 231 .Xr pkg_add 1 ,
 232 .Xr pkg_create 1 ,
 233 .Xr pkg_delete 1 ,
 234 .Xr pkg_info 1 ,
 235 .Xr portupgrade 8
 236 .Sh AUTHORS
 237 The
 238 .Nm
 239 utility was written by
 240 .An Jeremy D. Lea Aq reg@FreeBSD.org ,
 241 partially based on a Perl script written by
 242 .An Bruce A. Mah Aq bmah@FreeBSD.org .
 243 .Sh CONTRIBUTORS
 244 .An Nik Clayton Aq nik@FreeBSD.org ,
 245 .An Dominic Mitchell Aq dom@palmerharvey.co.uk ,
 246 .An Mark Ovens Aq marko@FreeBSD.org ,
 247 .An Doug Barton Aq DougB@gorean.org ,
 248 .An Akinori MUSHA Aq knu@FreeBSD.org ,
 249 .An Oliver Eikemeier Aq eik@FreeBSD.org