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