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 18, 2013
  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 hIoqv
  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 Fl O Ar origin
  44 .Op Ar index
  45 .Nm
  46 .Fl t Ar version1 version2
  47 .Nm
  48 .Fl T Ar pkgname pattern
  49 .Sh DESCRIPTION
  50 The
  51 .Nm
  52 command is used to produce a report of non-base software packages
  53 installed using the
  54 .Xr pkg_add 1
  55 command.
  56 .Pp
  57 Each package's version number is checked against one of two sources to
  58 see if that package may require updating.
  59 If the package contains
  60 information about its origin in the
  61 .Fx
  62 ports tree, and a version number can be determined from the port's
  63 .Pa Makefile ,
  64 then the version number from the
  65 .Pa Makefile
  66 will be used to determine whether the installed package is up-to-date
  67 or requires updating.
  68 .Pp
  69 If no origin for a package can be found, or if the port's
  70 .Pa Makefile
  71 cannot be located,
  72 .Nm
  73 will search for the package in the ports collection index file
  74 (typically
  75 .Pa /usr/ports/INDEX-10 ) .
  76 Any matching version number(s) there will be used to determine whether
  77 the installed package is up-to-date or requires updating.
  78 .Pp
  79 Generally, using the version number from a port's
  80 .Pa Makefile
  81 will provide a more accurate result, since, unlike the index file, it
  82 provides an unambiguous current version number, even when multiple
  83 versions of a port exist in the ports collection.
  84 Moreover, the ports collection index file is only updated at
  85 intervals, meaning that it may not completely reflect the version
  86 numbers of the software contained in the ports collection.
  87 .Pp
  88 Each package name is printed, along with a one-character status flag:
  89 .Bl -tag -width indent
  90 .It Li =
  91 The installed version of the package is current.
  92 .It Li \&<
  93 The installed version of the package is older than the current version.
  94 .It Li \&>
  95 The installed version of the package is newer than the current version.
  96 This situation can arise with an out-of-date index file, or when
  97 testing new ports.
  98 .It Li \&?
  99 The installed package does not appear in the index.
 100 This could be due to an out of date index or a package taken from a PR
 101 that has not yet been committed.
 102 .It Li *
 103 There are multiple versions of a particular software package
 104 listed in the index file.
 105 Examples from the
 106 .Fx
 107 ports collection are the Tcl toolkit or the
 108 .Tn EMACS
 109 editor.
 110 .It Li \&!
 111 The installed package exists in the index but for some reason,
 112 .Nm
 113 was unable to compare the version number of the installed package
 114 with the corresponding entry in the index.
 115 .El
 116 .Sh OPTIONS
 117 The
 118 .Nm
 119 utility supports several command-line arguments:
 120 .Bl -tag -width indent
 121 .It Fl h , -help
 122 Print help message.
 123 .It Fl I , -index-only
 124 Use only the index file for determining if a package is out of date.
 125 This is much faster than using the version number from a port's
 126 Makefile, at the expense of potentially giving an incorrect result if
 127 the index file is out of date.
 128 .It Fl l , -status Ar limchar
 129 Limit the output to those packages whose status flag matches the
 130 character(s) in
 131 .Ar limchar .
 132 More than one character can be specified in
 133 .Ar limchar .
 134 Note that because some of the status flag characters are also special
 135 to the shell, it is best to quote
 136 .Ar limchar
 137 with single quotes.
 138 .It Fl L , -no-status Ar limchar
 139 Limit the output to those packages whose status flag does not match
 140 .Ar limchar .
 141 You may specify more than one character to match in
 142 .Ar limchar .
 143 Note that because some of the status flag characters are also special
 144 to the shell, it is best to quote
 145 .Ar limchar
 146 with single quotes.
 147 .It Fl o , -show-origin
 148 Show the origin recorded on package generation instead of the package
 149 name.
 150 .It Fl O , -origin Ar origin
 151 Only list packages whose registered origin is
 152 .Ar origin .
 153 .It Fl q , -quiet
 154 Enable quiet output.
 155 Quiet output precludes printing the
 156 .Ar limchar
 157 when used with
 158 .Fl l
 159 or
 160 .Fl L .
 161 This is useful when used as the input to
 162 .Xr portupgrade 8 .
 163 .It Fl s , -match Ar string
 164 Limit the output to those packages whose names match a given
 165 .Ar string .
 166 .It Fl X , -extended
 167 Interpret
 168 .Ar string
 169 as a extended regular expression.
 170 .It Fl t
 171 Test a pair of version number strings and exit.
 172 The output consists of one of the single characters
 173 .Li =
 174 (equal),
 175 .Li \&<
 176 (right-hand number greater), or
 177 .Li \&>
 178 (left-hand number greater) on standard output.
 179 This flag is mostly useful for scripts or for testing.
 180 .It Fl T
 181 Test whether
 182 .Ar pkgname
 183 is matched by
 184 .Ar pattern
 185 and set the exit code accordingly.
 186 .Fl T
 187 can also be used in `filter mode':
 188 When one of the arguments is `-', standard input is used, and lines
 189 with matching package names/patterns are echoed to standard output.
 190 .It Fl v
 191 Enable verbose output.
 192 Verbose output includes some English-text
 193 interpretations of the version number comparisons, as well as the
 194 version numbers compared for each package.
 195 Non-verbose output is
 196 probably easier for programs or scripts to parse.
 197 .It Ar index
 198 Specify the index to be used as a basis of comparison.
 199 This index can
 200 be specified as a filename (in the local file system) or a URL.
 201 Any
 202 URL understandable by
 203 .Xr fetch 1
 204 can be used here.
 205 If no
 206 .Ar index
 207 file is specified on the command line,
 208 .Pa /usr/ports/INDEX-10
 209 is used.
 210 .El
 211 .Sh FILES
 212 .Bl -tag -width /usr/ports/INDEX-10 -compact
 213 .It Pa /usr/ports/INDEX-10
 214 Default index file.
 215 .El
 216 .Sh EXAMPLES
 217 The following is a typical invocation of the
 218 .Nm
 219 command, which checks the installed packages against the local ports
 220 index file:
 221 .Pp
 222 .Dl % pkg_version -v
 223 .Pp
 224 The command below generates a report against
 225 the version numbers in the on-line ports collection:
 226 .Pp
 227 .Dl % pkg_version http://www.FreeBSD.org/ports/INDEX-10
 228 .Pp
 229 The following command compares two package version strings:
 230 .Pp
 231 .Dl % pkg_version -t 1.5 1.5.1
 232 .Sh COMPATIBILITY
 233 The
 234 .Fl c
 235 option has been deprecated and is no longer supported.
 236 .Sh ENVRIOMENT
 237 .Bl -tag -width indent
 238 .It Ev PKG_OLD_NOWARN
 239 If set
 240 .Nm
 241 will not warn about its use in the presence of pkgng databases.
 242 .El
 243 .Sh SEE ALSO
 244 .Xr fetch 1 ,
 245 .Xr pkg_add 1 ,
 246 .Xr pkg_create 1 ,
 247 .Xr pkg_delete 1 ,
 248 .Xr pkg_info 1 ,
 249 .Xr portupgrade 8
 250 .Sh AUTHORS
 251 The
 252 .Nm
 253 utility was written by
 254 .An Jeremy D. Lea Aq reg@FreeBSD.org ,
 255 partially based on a Perl script written by
 256 .An Bruce A. Mah Aq bmah@FreeBSD.org .
 257 .Sh CONTRIBUTORS
 258 .An Nik Clayton Aq nik@FreeBSD.org ,
 259 .An Dominic Mitchell Aq dom@palmerharvey.co.uk ,
 260 .An Mark Ovens Aq marko@FreeBSD.org ,
 261 .An Doug Barton Aq DougB@gorean.org ,
 262 .An Akinori MUSHA Aq knu@FreeBSD.org ,
 263 .An Oliver Eikemeier Aq eik@FreeBSD.org