man/dpkg-query.pod

   1 # dpkg manual page - dpkg-query(1)
   2 #
   3 # Copyright © 2001 Wichert Akkerman <wakkerma@debian.org>
   4 # Copyright © 2006-2007 Frank Lichtenheld <djpig@debian.org>
   5 # Copyright © 2006-2015 Guillem Jover <guillem@debian.org>
   6 # Copyright © 2008-2011 Raphaël Hertzog <hertzog@debian.org>
   7 #
   8 # This is free software; you can redistribute it and/or modify
   9 # it under the terms of the GNU General Public License as published by
  10 # the Free Software Foundation; either version 2 of the License, or
  11 # (at your option) any later version.
  12 #
  13 # This is distributed in the hope that it will be useful,
  14 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16 # GNU General Public License for more details.
  17 #
  18 # You should have received a copy of the GNU General Public License
  19 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
  20
  21 =encoding utf8
  22
  23 =head1 NAME
  24
  25 dpkg-query - a tool to query the dpkg database
  26
  27 =head1 SYNOPSIS
  28
  29 B<dpkg-query>
  30 [I<option>...] I<command>
  31
  32 =head1 DESCRIPTION
  33
  34 B<dpkg-query> is a tool to show information about packages listed in
  35 the B<dpkg> database.
  36
  37 =head1 COMMANDS
  38
  39 =over
  40
  41 =item B<-l>, B<--list> [I<package-name-pattern>...]
  42
  43 List all known packages matching one or more patterns, regardless of their
  44 status, which includes any real or virtual package referenced in any
  45 dependency relationship field (such as B<Breaks>, B<Enhances>, etc.).
  46 If no I<package-name-pattern> is given, list all packages in
  47 I<%ADMINDIR%/status>, excluding the ones marked as not-installed (i.e.
  48 those which have been previously purged).
  49 Normal shell wildcard characters are allowed in I<package-name-pattern>.
  50 Please note you will probably have to quote I<package-name-pattern> to
  51 prevent the shell from performing filename expansion.
  52 For example this will list all package names starting with “libc6”:
  53
  54 =over
  55
  56  dpkg-query -l 'libc6*'
  57
  58 =back
  59
  60 The first three columns of the output show the desired action, the package
  61 status, and errors, in that order.
  62
  63 Desired action:
  64
  65 =over
  66
  67 =item u = Unknown
  68
  69 =item i = Install
  70
  71 =item h = Hold
  72
  73 =item r = Remove
  74
  75 =item p = Purge
  76
  77 =back
  78
  79 Package status:
  80
  81 =over
  82
  83 =item n = Not-installed
  84
  85 =item c = Config-files
  86
  87 =item H = Half-installed
  88
  89 =item U = Unpacked
  90
  91 =item F = Half-configured
  92
  93 =item W = Triggers-awaiting
  94
  95 =item t = Triggers-pending
  96
  97 =item i = Installed
  98
  99 =back
 100
 101 Error flags:
 102
 103 =over
 104
 105 =item E<lt>emptyE<gt> = (none)
 106
 107 =item R = Reinst-required
 108
 109 =back
 110
 111 An uppercase status or error letter indicates the package is likely to
 112 cause severe problems. Please refer to B<dpkg>(1) for information
 113 about the above states and flags.
 114
 115 The output format of this option is not configurable, but varies
 116 automatically to fit the terminal width. It is intended for human
 117 readers, and is not easily machine-readable. See B<-W> (B<--show>)
 118 and B<--showformat> for a way to configure the output format.
 119
 120 =item B<-W>, B<--show> [I<package-name-pattern>...]
 121
 122 Just like the B<--list> option this will list all packages matching
 123 the given patterns. However the output can be customized using the
 124 B<--showformat> option.
 125
 126 The default output format gives one line per matching package,
 127 each line consisting of the package name and its installed version,
 128 separated by a tab.
 129 The package name will be architecture qualified for packages with a
 130 B<Multi-Arch> field with the value B<same> or with a foreign architecture,
 131 which is an architecture that is neither the native one nor B<all>.
 132
 133 =item B<-s>, B<--status> [I<package-name>...]
 134
 135 Report status of specified packages. This just displays the entry in
 136 the installed package status database.
 137 If no I<package-name> is specified it will display all package entries
 138 in the status database (since dpkg 1.19.1).
 139 When multiple I<package-name> entries are listed, the requested status
 140 entries are separated by an empty line, with the same order as specified
 141 on the argument list.
 142
 143 =item B<-L>, B<--listfiles> I<package-name>...
 144
 145 List files installed to your system from I<package-name>. When multiple
 146 I<package-name>s are listed, the requested lists of files are separated
 147 by an empty line, with the same order as specified on the argument list.
 148
 149 Each file diversion is printed on its own line after its diverted file,
 150 prefixed with one of the following localized strings:
 151
 152 Z<>
 153   locally diverted to: I<diverted-to>
 154   package diverts others to: I<diverted-to>
 155   diverted by I<pkg> to: I<diverted-to>
 156
 157 B<Hint>: When machine parsing the output, it is customary to set the locale to
 158 B<C.UTF-8> to get reproducible results. On some systems this might also
 159 require adapting the B<LANGUAGE> environment variable appropriately if it
 160 is already set (see L<locale(7)>).
 161
 162 This command will not list extra files created by maintainer scripts,
 163 nor will it list alternatives.
 164
 165 =item B<--control-list> I<package-name>
 166
 167 List control files installed to your system from I<package-name>
 168 (since dpkg 1.16.5).
 169 These can be used as input arguments to B<--control-show>.
 170
 171 =item B<--control-show> I<package-name> I<control-file>
 172
 173 Print the I<control-file> installed to your system from I<package-name>
 174 to the standard output (since dpkg 1.16.5).
 175
 176 =item B<-c>, B<--control-path> I<package-name> [I<control-file>]
 177
 178 List paths for control files installed to your system from I<package-name>
 179 (since dpkg 1.15.4).
 180 If I<control-file> is specified then only list the path for that control
 181 file if it is present.
 182
 183 B<Warning>: this command is deprecated as it gives direct access to the
 184 internal dpkg database, please switch to use B<--control-list> and
 185 B<--control-show> instead for all cases where those commands might
 186 give the same end result. Although, as long as there is still at least
 187 one case where this command is needed (i.e. when having to remove a
 188 damaging postrm maintainer script), and while there is no good solution
 189 for that, this command will not get removed.
 190
 191 =item B<-S>, B<--search> I<filename-search-pattern>...
 192
 193 Search for packages that own files corresponding to the given patterns.
 194 Standard shell wildcard characters can be used in the pattern, where
 195 asterisk (B<*>) and question mark (B<?>) will match a slash,
 196 and backslash (B<\>) will be used as an escape character.
 197
 198 If the first character in the I<filename-search-pattern> is none of
 199 ‘B<*[?/>’ then it will be considered a substring match and will be
 200 implicitly surrounded by ‘B<*>’ (as in
 201 B<*>I<filename-search-pattern>B<*>).
 202 If the subsequent string contains any of ‘B<*[?\>’, then it will
 203 handled like a glob pattern, otherwise any trailing ‘B</>’ or
 204 ‘B</.>’ will be removed and a literal path lookup will be performed.
 205
 206 This command will not list extra files created by maintainer scripts,
 207 nor will it list alternatives.
 208
 209 The output format consists of one line per matching pattern, with a list
 210 of packages owning the pathname separated by a comma (U+002C ‘B<,>’) and
 211 a space (U+0020 ‘B< >’), followed by a colon (U+003A ‘B<:>’) and a space,
 212 followed by the pathname. As in:
 213
 214   pkgname1, pkgname2: pathname1
 215   pkgname3: pathname2
 216
 217 File diversions are printed with the following localized strings:
 218
 219 Z<>
 220   diversion by I<pkgname> from: I<diverted-from>
 221   diversion by I<pkgname> to: I<diverted-to>
 222
 223 or for local diversions:
 224
 225 Z<>
 226   local diversion from: I<diverted-from>
 227   local diversion to: I<diverted-to>
 228
 229 B<Hint>: When machine parsing the output, it is customary to set the locale to
 230 B<C.UTF-8> to get reproducible results.
 231
 232 =item B<-p>, B<--print-avail> [I<package-name>...]
 233
 234 Display details about packages, as found in I<%ADMINDIR%/available>.
 235 If no I<package-name> is specified, it will display all package entries
 236 in the I<available> database (since dpkg 1.19.1).
 237 When multiple I<package-name> are listed, the requested I<available>
 238 entries are separated by an empty line, with the same order as specified
 239 on the argument list.
 240
 241 Users of APT-based frontends
 242 should use B<apt show> I<package-name> instead
 243 as the I<available> file is only kept up-to-date when
 244 using B<dselect>.
 245
 246 =item B<-?>, B<--help>
 247
 248 Show the usage message and exit.
 249
 250 =item B<--version>
 251
 252 Show the version and exit.
 253
 254 =back
 255
 256 =head1 OPTIONS
 257
 258 =over
 259
 260 =item B<--admindir=>I<dir>
 261
 262 Change the location of the B<dpkg> database. The default location is
 263 I<%ADMINDIR%>.
 264
 265 =item B<--root=>I<directory>
 266
 267 Set the root directory to I<directory>, which sets the administrative
 268 directory to «I<directory>%ADMINDIR%» (since dpkg 1.21.0).
 269
 270 =item B<--load-avail>
 271
 272 Also load the available file when using the B<--show> and B<--list>
 273 commands, which now default to only querying the status file
 274 (since dpkg 1.16.2).
 275
 276 =item B<--no-pager>
 277
 278 Disables the use of any pager when showing information (since dpkg 1.19.2).
 279
 280 =item B<-f>, B<--showformat=>I<format>
 281
 282 This option is used to specify the format of the output B<--show>
 283 will produce (short option since dpkg 1.13.1).
 284 The format is a string that will be output for each package listed.
 285
 286 In the format string, “B<\>” introduces escapes:
 287
 288 =over
 289
 290 =item B<\n> newline
 291
 292 =item B<\r> carriage return
 293
 294 =item B<\t> tab
 295
 296 =back
 297
 298 “B<\>” before any other character suppresses any special
 299 meaning of the following character, which is useful for “B<\>”
 300 and “B<$>”.
 301
 302 Package information can be included by inserting
 303 variable references to package fields using the syntax
 304 “B<${>I<field>[B<;>I<width>]B<}>”. Fields are
 305 printed right-aligned unless the width is negative in which case left
 306 alignment will be used. The following I<field>s are recognized but
 307 they are not necessarily available in the status file (only internal
 308 fields or fields stored in the binary package end up in it):
 309
 310 =over
 311
 312 =item B<Architecture>
 313
 314 =item B<Bugs>
 315
 316 =item B<Conffiles> (internal)
 317
 318 =item B<Config-Version> (internal)
 319
 320 =item B<Conflicts>
 321
 322 =item B<Breaks>
 323
 324 =item B<Depends>
 325
 326 =item B<Description>
 327
 328 =item B<Enhances>
 329
 330 =item B<Protected>
 331
 332 =item B<Essential>
 333
 334 =item B<Filename> (internal, front-end related)
 335
 336 =item B<Homepage>
 337
 338 =item B<Installed-Size>
 339
 340 =item B<MD5sum> (internal, front-end related)
 341
 342 =item B<MSDOS-Filename> (internal, front-end related)
 343
 344 =item B<Maintainer>
 345
 346 =item B<Origin>
 347
 348 =item B<Package>
 349
 350 =item B<Pre-Depends>
 351
 352 =item B<Priority>
 353
 354 =item B<Provides>
 355
 356 =item B<Recommends>
 357
 358 =item B<Replaces>
 359
 360 =item B<Revision> (obsolete)
 361
 362 =item B<Section>
 363
 364 =item B<Size> (internal, front-end related)
 365
 366 =item B<Source>
 367
 368 =item B<Status> (internal)
 369
 370 =item B<Suggests>
 371
 372 =item B<Tag> (usually not in .deb but in repository Packages files)
 373
 374 =item B<Triggers-Awaited> (internal)
 375
 376 =item B<Triggers-Pending> (internal)
 377
 378 =item B<Version>
 379
 380 =back
 381
 382 The following are virtual fields, generated by B<dpkg-query> from
 383 values from other fields (note that these do not use valid names for
 384 fields in control files):
 385
 386 =over
 387
 388 =item B<binary:Package>
 389
 390 It contains the binary package name with a possible architecture qualifier
 391 like “libc6:amd64” (since dpkg 1.16.2).
 392 An architecture qualifier will be present to make the package name unambiguous,
 393 for packages with a B<Multi-Arch> field with the value B<same> or
 394 with a foreign architecture, which is an architecture that is neither
 395 the native one nor B<all>.
 396
 397 =item B<binary:Synopsis>
 398
 399 It contains the package short description (since dpkg 1.19.1).
 400
 401 =item B<binary:Summary>
 402
 403 This is an alias for B<binary:Synopsis> (since dpkg 1.16.2).
 404
 405 =item B<db:Status-Abbrev>
 406
 407 It contains the abbreviated package status (as three characters),
 408 such as “ii ” or “iHR” (since dpkg 1.16.2).
 409 See the B<--list> command description for more details.
 410
 411 =item B<db:Status-Want>
 412
 413 It contains the package wanted status, part of the Status field
 414 (since dpkg 1.17.11).
 415
 416 =item B<db:Status-Status>
 417
 418 It contains the package status word, part of the Status field
 419 (since dpkg 1.17.11).
 420
 421 =item B<db:Status-Eflag>
 422
 423 It contains the package status error flag, part of the Status field
 424 (since dpkg 1.17.11).
 425
 426 =item B<db-fsys:Files>
 427
 428 It contains the list of the package filesystem entries separated by newlines
 429 (since dpkg 1.19.3).
 430
 431 =item B<db-fsys:Last-Modified>
 432
 433 It contains the timestamp in seconds of the last time the package filesystem
 434 entries were modified (since dpkg 1.19.3).
 435
 436 =item B<source:Package>
 437
 438 It contains the source package name for this binary package
 439 (since dpkg 1.16.2).
 440
 441 =item B<source:Version>
 442
 443 It contains the source package version for this binary package
 444 (since dpkg 1.16.2)
 445
 446 =item B<source:Upstream-Version>
 447
 448 It contains the source package upstream version for this binary package
 449 (since dpkg 1.18.16)
 450
 451 =back
 452
 453 The default format string is “B<${binary:Package}\t${Version}\n>”.
 454 Actually, all other fields found in the status file (i.e. user defined
 455 fields) can be requested, too. They will be printed as-is, though, no
 456 conversion nor error checking is done on them. To get the name of the
 457 B<dpkg> maintainer and the installed version, you could run:
 458
 459 =over
 460
 461  dpkg-query -f='${binary:Package} ${Version}\t${Maintainer}\n' \
 462   -W dpkg
 463
 464 =back
 465
 466 =back
 467
 468 =head1 EXIT STATUS
 469
 470 =over
 471
 472 =item B<0>
 473
 474 The requested query was successfully performed.
 475
 476 =item B<1>
 477
 478 The requested query failed either fully or partially, due to no file or
 479 package being found (except for B<--control-path>,
 480 B<--control-list> and B<--control-show> were such errors are
 481 fatal).
 482
 483 =item B<2>
 484
 485 Fatal or unrecoverable error due to invalid command-line usage, or
 486 interactions with the system, such as accesses to the database,
 487 memory allocations, etc.
 488
 489 =back
 490
 491 =head1 ENVIRONMENT
 492
 493 =head2 External environment
 494
 495 =over
 496
 497 =item B<SHELL>
 498
 499 Sets the program to execute when spawning a command via a shell
 500 (since dpkg 1.19.2).
 501
 502 =item B<PAGER>
 503
 504 =item B<DPKG_PAGER>
 505
 506 Sets the pager command to use (since dpkg 1.19.1), which will be executed
 507 with «B<$SHELL -c>».
 508 If B<SHELL> is not set, «B<sh>» will be used instead.
 509 The B<DPKG_PAGER> overrides the B<PAGER> environment variable
 510 (since dpkg 1.19.2).
 511
 512 =item B<DPKG_ROOT>
 513
 514 If set and the B<--root> option has not been specified, it will
 515 be used as the filesystem root directory (since dpkg 1.21.0).
 516
 517 =item B<DPKG_ADMINDIR>
 518
 519 If set and the B<--admindir> option has not been specified, it will
 520 be used as the B<dpkg> data directory.
 521
 522 =item B<DPKG_DEBUG>
 523
 524 Sets the debug mask (since dpkg 1.21.10) from an octal value.
 525 The currently accepted flags are described in the B<dpkg --debug> option,
 526 but not all these flags might have an effect on this program.
 527
 528 =item B<DPKG_COLORS>
 529
 530 Sets the color mode (since dpkg 1.18.5).
 531 The currently accepted values are: B<auto> (default), B<always> and
 532 B<never>.
 533
 534 =back
 535
 536 =head2 Internal environment
 537
 538 =over
 539
 540 =item B<LESS>
 541
 542 Defined by B<dpkg-query> to “B<-FRSXMQ>”, if not already set, when
 543 spawning a pager (since dpkg 1.19.2).
 544 To change the default behavior, this variable can be preset to some other
 545 value including an empty string, or the B<PAGER> or B<DPKG_PAGER>
 546 variables can be set to disable specific options with «B<-+>», for
 547 example B<DPKG_PAGER="less -+F">.
 548
 549 =back
 550
 551 =head1 SECURITY
 552
 553 Query operations should never require root, and delegating their execution
 554 to unprivileged users via some gain-root command can have security
 555 implications (such as privilege escalation), for example when a pager is
 556 automatically invoked by the tool.
 557
 558 =head1 SEE ALSO
 559
 560 B<dpkg>(1).
 561