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<Enhances>
 340
 341 =item B<Protected>
 342
 343 =item B<Essential>
 344
 345 =item B<Filename> (internal, front-end related)
 346
 347 =item B<Homepage>
 348
 349 =item B<Installed-Size>
 350
 351 =item B<MD5sum> (internal, front-end related)
 352
 353 =item B<MSDOS-Filename> (internal, front-end related)
 354
 355 =item B<Maintainer>
 356
 357 =item B<Origin>
 358
 359 =item B<Package>
 360
 361 =item B<Pre-Depends>
 362
 363 =item B<Priority>
 364
 365 =item B<Provides>
 366
 367 =item B<Recommends>
 368
 369 =item B<Replaces>
 370
 371 =item B<Revision> (obsolete)
 372
 373 =item B<Section>
 374
 375 =item B<Size> (internal, front-end related)
 376
 377 =item B<Source>
 378
 379 =item B<Status> (internal)
 380
 381 =item B<Suggests>
 382
 383 =item B<Tag> (usually not in .deb but in repository Packages files)
 384
 385 =item B<Triggers-Awaited> (internal)
 386
 387 =item B<Triggers-Pending> (internal)
 388
 389 =item B<Version>
 390
 391 =back
 392
 393 The following are virtual fields, generated by B<dpkg-query> from
 394 values from other fields (note that these do not use valid names for
 395 fields in control files):
 396
 397 =over
 398
 399 =item B<binary:Package>
 400
 401 It contains the binary package name with a possible architecture qualifier
 402 like “libc6:amd64” (since dpkg 1.16.2).
 403 An architecture qualifier will be present to make the package name unambiguous,
 404 for packages with a B<Multi-Arch> field with the value B<same> or
 405 with a foreign architecture, which is an architecture that is neither
 406 the native one nor B<all>.
 407
 408 =item B<binary:Synopsis>
 409
 410 It contains the package short description (since dpkg 1.19.1).
 411
 412 =item B<binary:Summary>
 413
 414 This is an alias for B<binary:Synopsis> (since dpkg 1.16.2).
 415
 416 =item B<db:Status-Abbrev>
 417
 418 It contains the abbreviated package status (as three characters),
 419 such as “ii ” or “iHR” (since dpkg 1.16.2).
 420 See the B<--list> command description for more details.
 421
 422 =item B<db:Status-Want>
 423
 424 It contains the package wanted status, part of the Status field
 425 (since dpkg 1.17.11).
 426
 427 =item B<db:Status-Status>
 428
 429 It contains the package status word, part of the Status field
 430 (since dpkg 1.17.11).
 431
 432 =item B<db:Status-Eflag>
 433
 434 It contains the package status error flag, part of the Status field
 435 (since dpkg 1.17.11).
 436
 437 =item B<db-fsys:Files>
 438
 439 It contains the list of the package filesystem entries separated by newlines
 440 (since dpkg 1.19.3).
 441
 442 =item B<db-fsys:Last-Modified>
 443
 444 It contains the timestamp in seconds of the last time the package filesystem
 445 entries were modified (since dpkg 1.19.3).
 446
 447 =item B<source:Package>
 448
 449 It contains the source package name for this binary package
 450 (since dpkg 1.16.2).
 451
 452 =item B<source:Version>
 453
 454 It contains the source package version for this binary package
 455 (since dpkg 1.16.2)
 456
 457 =item B<source:Upstream-Version>
 458
 459 It contains the source package upstream version for this binary package
 460 (since dpkg 1.18.16)
 461
 462 =back
 463
 464 The default format string is “B<${binary:Package}\t${Version}\n>”.
 465 Actually, all other fields found in the status file (i.e. user defined
 466 fields) can be requested, too.
 467 They will be printed as-is, though,
 468 no conversion nor error checking is done on them.
 469 To get the name of the
 470 B<dpkg> maintainer and the installed version, you could run:
 471
 472 =over
 473
 474  dpkg-query -f='${binary:Package} ${Version}\t${Maintainer}\n' \
 475   -W dpkg
 476
 477 =back
 478
 479 =back
 480
 481 =head1 EXIT STATUS
 482
 483 =over
 484
 485 =item B<0>
 486
 487 The requested query was successfully performed.
 488
 489 =item B<1>
 490
 491 The requested query failed either fully or partially, due to no file or
 492 package being found (except for B<--control-path>,
 493 B<--control-list> and B<--control-show> were such errors are
 494 fatal).
 495
 496 =item B<2>
 497
 498 Fatal or unrecoverable error due to invalid command-line usage, or
 499 interactions with the system, such as accesses to the database,
 500 memory allocations, etc.
 501
 502 =back
 503
 504 =head1 ENVIRONMENT
 505
 506 =head2 External environment
 507
 508 =over
 509
 510 =item B<SHELL>
 511
 512 Sets the program to execute when spawning a command via a shell
 513 (since dpkg 1.19.2).
 514
 515 =item B<PAGER>
 516
 517 =item B<DPKG_PAGER>
 518
 519 Sets the pager command to use (since dpkg 1.19.1), which will be executed
 520 with «B<$SHELL -c>».
 521 If B<SHELL> is not set, «B<%DPKG_DEFAULT_SHELL%>» will be used instead.
 522 The B<DPKG_PAGER> overrides the B<PAGER> environment variable
 523 (since dpkg 1.19.2).
 524
 525 =item B<DPKG_ROOT>
 526
 527 If set and the B<--root> option has not been specified, it will
 528 be used as the filesystem root directory (since dpkg 1.21.0).
 529
 530 =item B<DPKG_ADMINDIR>
 531
 532 If set and the B<--admindir> option has not been specified, it will
 533 be used as the B<dpkg> data directory.
 534
 535 =item B<DPKG_DEBUG>
 536
 537 Sets the debug mask (since dpkg 1.21.10) from an octal value.
 538 The currently accepted flags are described in the B<dpkg --debug> option,
 539 but not all these flags might have an effect on this program.
 540
 541 =item B<DPKG_COLORS>
 542
 543 Sets the color mode (since dpkg 1.18.5).
 544 The currently accepted values are: B<auto> (default), B<always> and
 545 B<never>.
 546
 547 =item B<DPKG_NLS>
 548
 549 If set, it will be used to decide whether to activate Native Language Support,
 550 also known as internationalization (or i18n) support (since dpkg 1.22.7).
 551 The accepted values are: B<0> and B<1> (default).
 552
 553 =back
 554
 555 =head2 Internal environment
 556
 557 =over
 558
 559 =item B<LESS>
 560
 561 Defined by B<dpkg-query> to “B<-FRSXMQ>”, if not already set, when
 562 spawning a pager (since dpkg 1.19.2).
 563 To change the default behavior, this variable can be preset to some other
 564 value including an empty string, or the B<PAGER> or B<DPKG_PAGER>
 565 variables can be set to disable specific options with «B<-+>», for
 566 example B<DPKG_PAGER="less -+F">.
 567
 568 =back
 569
 570 =head1 SECURITY
 571
 572 Query operations should never require root, and delegating their execution
 573 to unprivileged users via some gain-root command can have security
 574 implications (such as privilege escalation), for example when a pager is
 575 automatically invoked by the tool.
 576
 577 =head1 SEE ALSO
 578
 579 L<dpkg(1)>.
 580