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.
 113 Please refer to L<dpkg(1)> for information
 114 about the above states and flags.
 115
 116 The output format of this option is not configurable, but varies
 117 automatically to fit the terminal width.
 118 It is intended for human readers, and is not easily machine-readable.
 119 See B<-W> (B<--show>)
 120 and B<--showformat> for a way to configure the output format.
 121
 122 =item B<-W>, B<--show> [I<package-name-pattern>...]
 123
 124 Just like the B<--list> option this will list all packages matching
 125 the given patterns.
 126 However the output can be customized using the
 127 B<--showformat> option.
 128
 129 The default output format gives one line per matching package,
 130 each line consisting of the package name and its installed version,
 131 separated by a tab.
 132 The package name will be architecture qualified for packages with a
 133 B<Multi-Arch> field with the value B<same> or with a foreign architecture,
 134 which is an architecture that is neither the native one nor B<all>.
 135
 136 =item B<-s>, B<--status> [I<package-name>...]
 137
 138 Report status of specified packages.
 139 This just displays the entry in
 140 the installed package status database.
 141 If no I<package-name> is specified it will display all package entries
 142 in the status database (since dpkg 1.19.1).
 143 When multiple I<package-name> entries are listed, the requested status
 144 entries are separated by an empty line, with the same order as specified
 145 on the argument list.
 146
 147 =item B<-L>, B<--listfiles> I<package-name>...
 148
 149 List files installed to your system from I<package-name>.
 150 When multiple
 151 I<package-name>s are listed, the requested lists of files are separated
 152 by an empty line, with the same order as specified on the argument list.
 153
 154 Each file diversion is printed on its own line after its diverted file,
 155 prefixed with one of the following localized strings:
 156
 157 Z<>
 158   locally diverted to: I<diverted-to>
 159   package diverts others to: I<diverted-to>
 160   diverted by I<pkg> to: I<diverted-to>
 161
 162 B<Hint>: When machine parsing the output, it is customary to set the locale to
 163 B<C.UTF-8> to get reproducible results.
 164 On some systems this might also
 165 require adapting the B<LANGUAGE> environment variable appropriately if it
 166 is already set (see L<locale(7)>).
 167
 168 This command will not list extra files created by maintainer scripts,
 169 nor will it list alternatives.
 170
 171 =item B<--control-list> I<package-name>
 172
 173 List control files installed to your system from I<package-name>
 174 (since dpkg 1.16.5).
 175 These can be used as input arguments to B<--control-show>.
 176
 177 =item B<--control-show> I<package-name> I<control-file>
 178
 179 Print the I<control-file> installed to your system from I<package-name>
 180 to the standard output (since dpkg 1.16.5).
 181
 182 =item B<-c>, B<--control-path> I<package-name> [I<control-file>]
 183
 184 List paths for control files installed to your system from I<package-name>
 185 (since dpkg 1.15.4).
 186 If I<control-file> is specified then only list the path for that control
 187 file if it is present.
 188
 189 B<Warning>: This command is deprecated as it gives direct access to the
 190 internal dpkg database, please switch to use B<--control-list> and
 191 B<--control-show> instead for all cases where those commands might
 192 give the same end result.
 193 Although, as long as there is still at least
 194 one case where this command is needed (i.e. when having to remove a
 195 damaging postrm maintainer script), and while there is no good solution
 196 for that, this command will not get removed.
 197
 198 =item B<-S>, B<--search> I<filename-search-pattern>...
 199
 200 Search for packages that own files corresponding to the given patterns.
 201 Standard shell wildcard characters can be used in the pattern, where
 202 asterisk (B<*>) and question mark (B<?>) will match a slash,
 203 and backslash (B<\>) will be used as an escape character.
 204
 205 If the first character in the I<filename-search-pattern> is none of
 206 ‘B<*[?/>’ then it will be considered a substring match and will be
 207 implicitly surrounded by ‘B<*>’ (as in
 208 B<*>I<filename-search-pattern>B<*>).
 209 If the subsequent string contains any of ‘B<*[?\>’, then it will
 210 handled like a glob pattern, otherwise any trailing ‘B</>’ or
 211 ‘B</.>’ will be removed and a literal path lookup will be performed.
 212
 213 This command will not list extra files created by maintainer scripts,
 214 nor will it list alternatives.
 215
 216 The output format consists of one line per matching pattern, with a list
 217 of packages owning the pathname separated by a comma (U+002C ‘B<,>’) and
 218 a space (U+0020 ‘B< >’), followed by a colon (U+003A ‘B<:>’) and a space,
 219 followed by the pathname.
 220 As in:
 221
 222   pkgname1, pkgname2: pathname1
 223   pkgname3: pathname2
 224
 225 File diversions are printed with the following localized strings:
 226
 227 Z<>
 228   diversion by I<pkgname> from: I<diverted-from>
 229   diversion by I<pkgname> to: I<diverted-to>
 230
 231 or for local diversions:
 232
 233 Z<>
 234   local diversion from: I<diverted-from>
 235   local diversion to: I<diverted-to>
 236
 237 B<Hint>: When machine parsing the output, it is customary to set the locale to
 238 B<C.UTF-8> to get reproducible results.
 239
 240 =item B<-p>, B<--print-avail> [I<package-name>...]
 241
 242 Display details about packages, as found in I<%ADMINDIR%/available>.
 243 If no I<package-name> is specified, it will display all package entries
 244 in the I<available> database (since dpkg 1.19.1).
 245 When multiple I<package-name> are listed, the requested I<available>
 246 entries are separated by an empty line, with the same order as specified
 247 on the argument list.
 248
 249 Users of APT-based frontends
 250 should use B<apt show> I<package-name> instead
 251 as the I<available> file is only kept up-to-date when
 252 using B<dselect>.
 253
 254 =item B<-?>, B<--help>
 255
 256 Show the usage message and exit.
 257
 258 =item B<--version>
 259
 260 Show the version and exit.
 261
 262 =back
 263
 264 =head1 OPTIONS
 265
 266 =over
 267
 268 =item B<--admindir=>I<dir>
 269
 270 Change the location of the B<dpkg> database.
 271 The default location is
 272 I<%ADMINDIR%>.
 273
 274 =item B<--root=>I<directory>
 275
 276 Set the root directory to I<directory>, which sets the administrative
 277 directory to «I<directory>%ADMINDIR%» (since dpkg 1.21.0).
 278
 279 =item B<--load-avail>
 280
 281 Also load the available file when using the B<--show> and B<--list>
 282 commands, which now default to only querying the status file
 283 (since dpkg 1.16.2).
 284
 285 =item B<--no-pager>
 286
 287 Disables the use of any pager when showing information (since dpkg 1.19.2).
 288
 289 =item B<-f>, B<--showformat=>I<format>
 290
 291 This option is used to specify the format of the output B<--show>
 292 will produce (short option since dpkg 1.13.1).
 293 The format is a string that will be output for each package listed.
 294
 295 In the format string, “B<\>” introduces escapes:
 296
 297 =over
 298
 299 =item B<\n> newline
 300
 301 =item B<\r> carriage return
 302
 303 =item B<\t> tab
 304
 305 =back
 306
 307 “B<\>” before any other character suppresses any special
 308 meaning of the following character, which is useful for “B<\>”
 309 and “B<$>”.
 310
 311 Package information can be included by inserting
 312 variable references to package fields using the syntax
 313 “B<${>I<field>[B<;>I<width>]B<}>”.
 314 Fields are
 315 printed right-aligned unless the width is negative in which case left
 316 alignment will be used.
 317 The following I<field>s are recognized but
 318 they are not necessarily available in the status file (only internal
 319 fields or fields stored in the binary package end up in it):
 320
 321 =over
 322
 323 =item B<Architecture>
 324
 325 =item B<Bugs>
 326
 327 =item B<Conffiles> (internal)
 328
 329 =item B<Config-Version> (internal)
 330
 331 =item B<Conflicts>
 332
 333 =item B<Breaks>
 334
 335 =item B<Depends>
 336
 337 =item B<Description>
 338
 339 =item B<Description-md5> (internal, front-end related)
 340
 341 =item B<Enhances>
 342
 343 =item B<Protected>
 344
 345 =item B<Essential>
 346
 347 =item B<Filename> (internal, front-end related)
 348
 349 =item B<Homepage>
 350
 351 =item B<Installed-Size>
 352
 353 =item B<MD5sum> (internal, front-end related)
 354
 355 =item B<MSDOS-Filename> (internal, front-end related)
 356
 357 =item B<Maintainer>
 358
 359 =item B<Origin>
 360
 361 =item B<Package>
 362
 363 =item B<Pre-Depends>
 364
 365 =item B<Priority>
 366
 367 =item B<Provides>
 368
 369 =item B<Recommends>
 370
 371 =item B<Replaces>
 372
 373 =item B<Revision> (obsolete)
 374
 375 =item B<Section>
 376
 377 =item B<SHA1> (internal, front-end related)
 378
 379 =item B<SHA256> (internal, front-end related)
 380
 381 =item B<SHA512> (internal, front-end related)
 382
 383 =item B<Size> (internal, front-end related)
 384
 385 =item B<Source>
 386
 387 =item B<Status> (internal)
 388
 389 =item B<Suggests>
 390
 391 =item B<Tag> (usually not in .deb but in repository Packages files)
 392
 393 =item B<Triggers-Awaited> (internal)
 394
 395 =item B<Triggers-Pending> (internal)
 396
 397 =item B<Version>
 398
 399 =back
 400
 401 The following are virtual fields, generated by B<dpkg-query> from
 402 values from other fields (note that these do not use valid names for
 403 fields in control files):
 404
 405 =over
 406
 407 =item B<binary:Package>
 408
 409 It contains the binary package name with a possible architecture qualifier
 410 like “libc6:amd64” (since dpkg 1.16.2).
 411 An architecture qualifier will be present to make the package name unambiguous,
 412 for packages with a B<Multi-Arch> field with the value B<same> or
 413 with a foreign architecture, which is an architecture that is neither
 414 the native one nor B<all>.
 415
 416 =item B<binary:Synopsis>
 417
 418 It contains the package short description (since dpkg 1.19.1).
 419
 420 =item B<binary:Summary>
 421
 422 This is an alias for B<binary:Synopsis> (since dpkg 1.16.2).
 423
 424 =item B<db:Status-Abbrev>
 425
 426 It contains the abbreviated package status (as three characters),
 427 such as “ii ” or “iHR” (since dpkg 1.16.2).
 428 See the B<--list> command description for more details.
 429
 430 =item B<db:Status-Want>
 431
 432 It contains the package wanted status, part of the Status field
 433 (since dpkg 1.17.11).
 434
 435 =item B<db:Status-Status>
 436
 437 It contains the package status word, part of the Status field
 438 (since dpkg 1.17.11).
 439
 440 =item B<db:Status-Eflag>
 441
 442 It contains the package status error flag, part of the Status field
 443 (since dpkg 1.17.11).
 444
 445 =item B<db-fsys:Files>
 446
 447 It contains the list of the package filesystem entries separated by newlines
 448 (since dpkg 1.19.3).
 449
 450 =item B<db-fsys:Last-Modified>
 451
 452 It contains the timestamp in seconds of the last time the package filesystem
 453 entries were modified (since dpkg 1.19.3).
 454
 455 =item B<source:Package>
 456
 457 It contains the source package name for this binary package
 458 (since dpkg 1.16.2).
 459
 460 =item B<source:Version>
 461
 462 It contains the source package version for this binary package
 463 (since dpkg 1.16.2)
 464
 465 =item B<source:Upstream-Version>
 466
 467 It contains the source package upstream version for this binary package
 468 (since dpkg 1.18.16)
 469
 470 =back
 471
 472 The default format string is “B<${binary:Package}\t${Version}\n>”.
 473 Actually, all other fields found in the status file (i.e. user defined
 474 fields) can be requested, too.
 475 They will be printed as-is, though,
 476 no conversion nor error checking is done on them.
 477 To get the name of the
 478 B<dpkg> maintainer and the installed version, you could run:
 479
 480 =over
 481
 482  dpkg-query -f='${binary:Package} ${Version}\t${Maintainer}\n' \
 483   -W dpkg
 484
 485 =back
 486
 487 =back
 488
 489 =head1 EXIT STATUS
 490
 491 =over
 492
 493 =item B<0>
 494
 495 The requested query was successfully performed.
 496
 497 =item B<1>
 498
 499 The requested query failed either fully or partially, due to no file or
 500 package being found (except for B<--control-path>,
 501 B<--control-list> and B<--control-show> were such errors are
 502 fatal).
 503
 504 =item B<2>
 505
 506 Fatal or unrecoverable error due to invalid command-line usage, or
 507 interactions with the system, such as accesses to the database,
 508 memory allocations, etc.
 509
 510 =back
 511
 512 =head1 ENVIRONMENT
 513
 514 =head2 External environment
 515
 516 =over
 517
 518 =item B<SHELL>
 519
 520 Sets the program to execute when spawning a command via a shell
 521 (since dpkg 1.19.2).
 522
 523 =item B<PAGER>
 524
 525 =item B<DPKG_PAGER>
 526
 527 Sets the pager command to use (since dpkg 1.19.1), which will be executed
 528 with «B<$SHELL -c>».
 529 If B<SHELL> is not set, «B<%DPKG_DEFAULT_SHELL%>» will be used instead.
 530 The B<DPKG_PAGER> overrides the B<PAGER> environment variable
 531 (since dpkg 1.19.2).
 532
 533 =item B<DPKG_ROOT>
 534
 535 If set and the B<--root> option has not been specified, it will
 536 be used as the filesystem root directory (since dpkg 1.21.0).
 537
 538 =item B<DPKG_ADMINDIR>
 539
 540 If set and the B<--admindir> option has not been specified, it will
 541 be used as the B<dpkg> data directory.
 542
 543 =item B<DPKG_DEBUG>
 544
 545 Sets the debug mask (since dpkg 1.21.10) from an octal value.
 546 The currently accepted flags are described in the B<dpkg --debug> option,
 547 but not all these flags might have an effect on this program.
 548
 549 =item B<DPKG_COLORS>
 550
 551 Sets the color mode (since dpkg 1.18.5).
 552 The currently accepted values are: B<auto> (default), B<always> and
 553 B<never>.
 554
 555 =item B<DPKG_NLS>
 556
 557 If set, it will be used to decide whether to activate Native Language Support,
 558 also known as internationalization (or i18n) support (since dpkg 1.22.7).
 559 The accepted values are: B<0> and B<1> (default).
 560
 561 =back
 562
 563 =head2 Internal environment
 564
 565 =over
 566
 567 =item B<LESS>
 568
 569 Defined by B<dpkg-query> to “B<-FRSXMQ>”, if not already set, when
 570 spawning a pager (since dpkg 1.19.2).
 571 To change the default behavior, this variable can be preset to some other
 572 value including an empty string, or the B<PAGER> or B<DPKG_PAGER>
 573 variables can be set to disable specific options with «B<-+>», for
 574 example B<DPKG_PAGER="less -+F">.
 575
 576 =back
 577
 578 =head1 SECURITY
 579
 580 Query operations should never require root, and delegating their execution
 581 to unprivileged users via some gain-root command can have security
 582 implications (such as privilege escalation), for example when a pager is
 583 automatically invoked by the tool.
 584
 585 =head1 SEE ALSO
 586
 587 L<dpkg(1)>.
 588