pkgtools/pkg_install/files/info/pkg_info.1

   1 .\" $NetBSD: pkg_info.1,v 1.25 2010/01/20 22:34:47 jmmv Exp $
   2 .\"
   3 .\" FreeBSD install - a package for the installation and maintenance
   4 .\" of non-core utilities.
   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 .\" Jordan K. Hubbard
  16 .\"
  17 .\"
  18 .\"     @(#)pkg_info.1
  19 .\"
  20 .Dd January 20, 2010
  21 .Dt PKG_INFO 1
  22 .Os
  23 .Sh NAME
  24 .Nm pkg_info
  25 .Nd a utility for displaying information on software packages
  26 .Sh SYNOPSIS
  27 .Nm
  28 .Op Fl BbcDdFfhIikLmNnpqrRSsVvX
  29 .Op Fl e Ar package
  30 .Op Fl E Ar package
  31 .Op Fl K Ar pkg_dbdir
  32 .Op Fl l Ar prefix
  33 .Ar pkg-name ...
  34 .Nm
  35 .Op Fl a | Fl u
  36 .Op flags
  37 .Nm
  38 .Op Fl Q Ar variable
  39 .Ar pkg-name ...
  40 .Sh DESCRIPTION
  41 The
  42 .Nm
  43 command is used to dump out information for packages, which may be either
  44 packed up in files or already installed on the system with the
  45 .Xr pkg_create 1
  46 command.
  47 .Pp
  48 The
  49 .Ar pkg-name
  50 may be the name of an installed package (with our without version), a
  51 pattern matching several installed packages (see the
  52 .Sx PACKAGE WILDCARDS
  53 section for a description of possible patterns),
  54 the pathname to a
  55 binary package, a filename belonging to an installed
  56 package (if
  57 .Fl F
  58 is also given), or a URL to an ftp-available package.
  59 .Pp
  60 The following command-line options are supported:
  61 .Bl -tag -width indent
  62 .It Fl a
  63 Show information for all currently installed packages.
  64 See also
  65 .Fl u .
  66 .It Fl B
  67 Show some of the important definitions used when building
  68 the binary package (the
  69 .Dq Build information )
  70 for each package.
  71 Additionally, any installation information variables
  72 (lowercase) can be queried, too.
  73 In particular,
  74 .Ar automatic
  75 tells if a package was installed automatically
  76 as a dependency of another package.
  77 .It Fl b
  78 Show the
  79 .Nx
  80 RCS Id strings from the files used in the construction
  81 of the binary package (the "Build version") for each package.
  82 These files are the package Makefile, any patch files, any checksum
  83 files, and the packing list file.
  84 .It Fl c
  85 Show the one-line comment field for each package.
  86 .It Fl D
  87 Show the install-message file (if any) for each package.
  88 .It Fl d
  89 Show the long-description field for each package.
  90 .It Fl E Ar pkg-name
  91 This option
  92 allows you to test for the existence of a given package.
  93 If a package identified by
  94 .Ar pkg-name
  95 is currently installed, return code is 0, otherwise 1.
  96 The name of the best matching package found installed is printed to
  97 stdout unless turned off using the
  98 .Fl q
  99 option.
 100 .Ar pkg-name
 101 can contain wildcards (see the
 102 .Sx PACKAGE WILDCARDS
 103 section below).
 104 .It Fl e Ar pkg-name
 105 This option
 106 allows you to test for the existence of a given package.
 107 If a package identified by
 108 .Ar pkg-name
 109 is currently installed, return code is 0, otherwise 1.
 110 The names of any package(s) found installed are printed to
 111 stdout unless turned off using the
 112 .Fl q
 113 option.
 114 .Ar pkg-name
 115 can contain wildcards (see the
 116 .Sx PACKAGE WILDCARDS
 117 section below).
 118 .It Fl F
 119 Interpret any pkg-name given as filename, and translate it to a
 120 package name using the Package Database.
 121 This can be used to query information on a per-file basis, e.g. in
 122 conjunction with the
 123 .Fl e
 124 flag to find out which package a file belongs to.
 125 .It Fl f
 126 Show the packing list instructions for each package.
 127 .It Fl I
 128 Show the index entry for each package.
 129 .It Fl i
 130 Show the install script (if any) for each package.
 131 .It Fl K Ar pkg_dbdir
 132 Set
 133 .Ar pkg_dbdir
 134 as the package database directory.
 135 See the
 136 .Sx ENVIRONMENT
 137 section below for details on how the default value is calculated.
 138 .It Fl k
 139 Show the de-install script (if any) for each package.
 140 .It Fl L
 141 Show the files within each package.
 142 This is different from just viewing the packing list, since full pathnames
 143 for everything are generated.
 144 Files that were created dynamically during installation of the package
 145 are not listed.
 146 .It Fl l Ar str
 147 Prefix each information category header (see
 148 .Fl q )
 149 shown with
 150 .Ar str .
 151 This is primarily of use to front-end programs that want to request a
 152 lot of different information fields at once for a package, but don't
 153 necessary want the output intermingled in such a way that they can't
 154 organize it.
 155 This lets you add a special token to the start of each field.
 156 .It Fl m
 157 Show the mtree file (if any) for each package.
 158 .It Fl N
 159 Show which packages each package was built with (exact dependencies), if any.
 160 .It Fl n
 161 Show which packages each package needs (depends upon), if any.
 162 .It Fl p
 163 Show the installation prefix for each package.
 164 .It Fl Q
 165 Show the definition of
 166 .Ar variable
 167 from the build information for each package.
 168 An empty string is returned if no such variable definition is found for
 169 the package(s).
 170 .It Fl q
 171 Be
 172 .Dq quiet
 173 in emitting report headers and such, just dump the
 174 raw info (basically, assume a non-human reading).
 175 .It Fl R
 176 For each package, show the packages that require it.
 177 .It Fl r
 178 For each package, show the packages that require it.
 179 Continue recursively to show all dependents.
 180 .It Fl S
 181 Show the size of this package and all the packages it requires,
 182 in bytes.
 183 .It Fl s
 184 Show the size of this package in bytes.
 185 The size is calculated by adding up the size of each file of the package.
 186 .It Fl u
 187 Show information for all user-installed packages.
 188 Automatically installed packages (as dependencies
 189 of other packages) are not displayed.
 190 See also
 191 .Fl a .
 192 .It Fl V
 193 Print version number and exit.
 194 .It Fl v
 195 Turn on verbose output.
 196 .It Fl X
 197 Print summary information for each package.
 198 The summary format is
 199 described in
 200 .Xr pkg_summary 5 .
 201 Its primary use is to contain all information about the contents of a
 202 (remote) binary package repository needed by package managing software.
 203 .El
 204 .Sh TECHNICAL DETAILS
 205 Package info is either extracted from package files named on the
 206 command line, or from already installed package information
 207 in
 208 .Pa /var/db/pkg/\*[Lt]pkg-name\*[Gt] .
 209 .Pp
 210 A filename can be given instead of a (installed) package name to query
 211 information on the package this file belongs to.
 212 This filename is then resolved to a package name using the Package Database.
 213 For this translation to take place, the
 214 .Fl F
 215 flag must be given.
 216 The filename must be absolute, compare the output of pkg_info
 217 .Fl aF .
 218 .Sh PACKAGE WILDCARDS
 219 In the places where a package name/version is expected, e.g. for the
 220 .Fl e
 221 switch, several forms can be used.
 222 Either use a package name with or without version, or specify a
 223 package wildcard that gets matched against all installed packages.
 224 .Pp
 225 Package wildcards use
 226 .Xr fnmatch 3 .
 227 In addition,
 228 .Xr csh 1
 229 style {,} alternates have been implemented.
 230 Package version numbers can also be matched in a relational manner
 231 using the
 232 .Pa \*[Ge] , \*[Le] , \*[Gt] ,
 233 and
 234 .Pa \*[Lt]
 235 operators.
 236 For example,
 237 .Pa pkg_info -e 'name\*[Ge]1.3'
 238 will match versions 1.3 and later of the
 239 .Pa name
 240 package.
 241 Additionally, ranges can be defined by giving a lower bound with
 242 \*[Gt] or \*[Ge] and an upper bound with \*[Lt] or \*[Le].
 243 The lower bound has to come first.
 244 For example,
 245 .Pa pkg_info -e 'name\*[Ge]1.3\*[Lt]2.0'
 246 will match versions 1.3 (inclusive) to 2.0 (exclusive)
 247 of package
 248 .Pa name .
 249 .Pp
 250 The collating sequence of the various package version numbers is
 251 unusual, but strives to be consistent.
 252 The magic string
 253 .Dq alpha
 254 equates to
 255 .Pa alpha version
 256 and sorts before a beta version.
 257 The magic string
 258 .Dq beta
 259 equates to
 260 .Pa beta version
 261 and sorts before a release candidate.
 262 The magic string
 263 .Dq rc
 264 equates to
 265 .Pa release candidate
 266 and sorts before a release.
 267 The magic string
 268 .Dq pre ,
 269 short for
 270 .Dq pre-release ,
 271 is a synonym for
 272 .Dq rc .
 273 For example,
 274 .Pa name-1.3rc3
 275 will sort before
 276 .Pa name-1.3
 277 and after
 278 .Pa name-1.2.9 .
 279 Similarly
 280 .Pa name-1.3alpha2
 281 will sort before
 282 .Pa name-1.3beta1
 283 and they both sort before
 284 .Pa name-1.3rc1 .
 285 In addition, alphabetic characters sort in the same place as
 286 their numeric counterparts, so that
 287 .Pa name-1.2e
 288 has the same sorting value as
 289 .Pa name-1.2.5
 290 The magic string
 291 .Dq pl
 292 equates to a
 293 .Pa patch level
 294 and has the same value as a dot in the dewey-decimal ordering schemes.
 295 .Sh ENVIRONMENT
 296 .Bl -tag -width PKG_DBDIR
 297 .It Ev PKG_DBDIR
 298 If the
 299 .Fl K
 300 flag isn't given, then the value of the
 301 .Ev PKG_DBDIR
 302 variable overrides the
 303 .Xr pkg_install.conf 5
 304 variable of the same name.
 305 If all of this fails to locate a value, then it typically defaults to
 306 .Pa /var/db/pkg .
 307 .El
 308 .Sh SEE ALSO
 309 .Xr pkg_add 1 ,
 310 .Xr pkg_admin 1 ,
 311 .Xr pkg_create 1 ,
 312 .Xr pkg_delete 1 ,
 313 .Xr mktemp 3 ,
 314 .Xr pkgsrc 7 ,
 315 .Xr mtree 8
 316 .Sh AUTHORS
 317 .Bl -tag -width indent -compact
 318 .It "Jordan Hubbard"
 319 most of the work
 320 .It "John Kohl"
 321 refined it for
 322 .Nx
 323 .It "Hubert Feyrer"
 324 .Nx
 325 wildcard dependency processing, pkgdb, depends displaying,
 326 pkg size display etc.
 327 .El