chiark - git - mdw - dpkg/blob - man/dpkg-query.man

   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 .TH dpkg\-query 1 "%RELEASE_DATE%" "%VERSION%" "dpkg suite"
  22 .nh
  23 .SH NAME
  24 dpkg\-query \- a tool to query the dpkg database
  25 .
  26 .SH SYNOPSIS
  27 .B dpkg\-query
  28 .RI [ option "...] " command
  29 .
  30 .SH DESCRIPTION
  31 \fBdpkg\-query\fP is a tool to show information about packages listed in
  32 the \fBdpkg\fP database.
  33 .
  34 .SH COMMANDS
  35 .TP
  36 .BR \-l ", " \-\-list " [\fIpackage-name-pattern\fP...]"
  37 List packages matching given pattern. If no \fIpackage-name-pattern\fP
  38 is given, list all packages in \fI%ADMINDIR%/status\fP, excluding
  39 the ones marked as not-installed (i.e. those which have been previously
  40 purged). Normal shell wildcard characters are allowed
  41 in \fIpackage-name-pattern\fP. Please note you will probably have to
  42 quote \fIpackage-name-pattern\fP to prevent the shell from performing
  43 filename expansion. For example this will list all package names starting
  44 with \*(lqlibc6\*(rq:
  45
  46 .nf
  47   \fBdpkg\-query \-l 'libc6*'\fP
  48 .fi
  49
  50 The first three columns of the output show the desired action, the package
  51 status, and errors, in that order.
  52
  53 Desired action:
  54 .nf
  55   u = Unknown
  56   i = Install
  57   h = Hold
  58   r = Remove
  59   p = Purge
  60 .fi
  61
  62 Package status:
  63 .nf
  64   n = Not-installed
  65   c = Config-files
  66   H = Half-installed
  67   U = Unpacked
  68   F = Half-configured
  69   W = Triggers-awaiting
  70   t = Triggers-pending
  71   i = Installed
  72 .fi
  73
  74 Error flags:
  75 .nf
  76   <empty> = (none)
  77   R = Reinst-required
  78 .fi
  79
  80 An uppercase status or error letter indicates the package is likely to
  81 cause severe problems. Please refer to \fBdpkg\fP(1) for information
  82 about the above states and flags.
  83
  84 The output format of this option is not configurable, but varies
  85 automatically to fit the terminal width. It is intended for human
  86 readers, and is not easily machine-readable. See \fB\-W\fP (\fB\-\-show\fP)
  87 and \fB\-\-showformat\fP for a way to configure the output format.
  88 .TP
  89 .BR \-W ", " \-\-show " [\fIpackage-name-pattern\fP...]"
  90 Just like the \fB\-\-list\fP option this will list all packages matching
  91 the given pattern. However the output can be customized using the
  92 \fB\-\-showformat\fP option.
  93 The default output format gives one line per matching package, each line
  94 having the name (extended with the architecture qualifier for
  95 \fBMulti\-Arch\fP \fBsame\fP packages) and installed version of the package,
  96 separated by a tab.
  97 .TP
  98 .BR \-s ", " \-\-status " \fIpackage-name\fP..."
  99 Report status of specified package. This just displays the entry in
 100 the installed package status database. When multiple \fIpackage-name\fP
 101 are listed, the requested status entries are separated by an empty line,
 102 with the same order as specified on the argument list.
 103 .TP
 104 .BR \-L ", " \-\-listfiles " \fIpackage-name\fP..."
 105 List files installed to your system from \fIpackage-name\fP. When multiple
 106 \fIpackage-name\fP are listed, the requested lists of files are separated
 107 by an empty line, with the same order as specified on the argument list.
 108 However, note that files created by package-specific installation-scripts
 109 are not listed.
 110 .TP
 111 .BR \-\-control\-list " \fIpackage-name\fP
 112 List control files installed to your system from \fIpackage-name\fP
 113 (since dpkg 1.16.5).
 114 These can be used as input arguments to \fB\-\-control\-show\fP.
 115 .TP
 116 .BR \-\-control\-show " \fIpackage-name\fP \fIcontrol-file\fP"
 117 Print the \fIcontrol-file\fP installed to your system from \fIpackage-name\fP
 118 to the standard output (since dpkg 1.16.5).
 119 .TP
 120 .BR \-c ", " \-\-control\-path " \fIpackage-name\fP [\fIcontrol-file\fP]"
 121 List paths for control files installed to your system from \fIpackage-name\fP
 122 (since dpkg 1.15.4).
 123 If \fIcontrol-file\fP is specified then only list the path for that control
 124 file if it is present.
 125
 126 \fBWarning\fP: this command is deprecated as it gives direct access to the
 127 internal dpkg database, please switch to use \fB\-\-control\-list\fP and
 128 \fB\-\-control\-show\fP instead for all cases where those commands might
 129 give the same end result. Although, as long as there is still at least
 130 one case where this command is needed (i.e. when having to remove a
 131 damaging postrm maintainer script), and while there is no good solution
 132 for that, this command will not get removed.
 133 .TP
 134 .BR \-S ", " \-\-search " \fIfilename-search-pattern\fP..."
 135 Search for packages that own files corresponding to the given pattern.
 136 Standard shell wildcard characters can be used in the pattern, where
 137 asterisk (\fB*\fP) and question mark (\fB?\fP) will match a slash,
 138 and blackslash (\fB\\\fP) will be used as an escape character.
 139
 140 If the first character in the \fIfilename-search-pattern\fP is none of
 141 ‘\fB*[?/\fP’ then it will be considered a substring match and will be
 142 implicitly surrounded by ‘\fB*\fP’ (as in
 143 \fB*\fP\fIfilename-search-pattern\fP\fB*\fP).
 144 If the subsequent string contains any of ‘\fB*[?\\\fP’, then it will
 145 handled like a glob pattern, otherwise any trailing ‘\fB/\fP’ or
 146 ‘\fB/.\fP’ will be removed and a literal path lookup will be performed.
 147
 148 This command will not list extra files created by maintainer scripts,
 149 nor will it list alternatives.
 150 .TP
 151 .BR \-p ", " \-\-print\-avail " \fIpackage-name\fP..."
 152 Display details about \fIpackage-name\fP, as found in
 153 \fI%ADMINDIR%/available\fP. When multiple \fIpackage-name\fP are
 154 listed, the requested \fIavailable\fP entries are separated by an empty
 155 line, with the same order as specified on the argument list.
 156
 157 Users of APT-based frontends
 158 should use \fBapt\-cache show\fP \fIpackage-name\fP instead
 159 as the \fIavailable\fP file is only kept up-to-date when
 160 using \fBdselect\fP.
 161 .TP
 162 .BR \-? ", " \-\-help
 163 Show the usage message and exit.
 164 .TP
 165 .B \-\-version
 166 Show the version and exit.
 167 .
 168 .SH OPTIONS
 169 .TP
 170 .BI \-\-admindir= dir
 171 Change the location of the \fBdpkg\fR database. The default location is
 172 \fI%ADMINDIR%\fP.
 173 .TP
 174 .B \-\-load\-avail
 175 Also load the available file when using the \fB\-\-show\fP and \fB\-\-list\fP
 176 commands, which now default to only querying the status file
 177 (since dpkg 1.16.2).
 178 .TP
 179 .BR \-f ", " \-\-showformat=\fIformat\fR
 180 This option is used to specify the format of the output \fB\-\-show\fP
 181 will produce. The format is a string that will be output for each package
 182 listed.
 183
 184 In the format string, “\fB\e\fP” introduces escapes:
 185
 186 .nf
 187     \fB\en\fP  newline
 188     \fB\er\fP  carriage return
 189     \fB\et\fP  tab
 190 .fi
 191
 192 “\fB\e\fP” before any other character suppresses any special
 193 meaning of the following character, which is useful for “\fB\e\fP”
 194 and “\fB$\fP”.
 195
 196 Package information can be included by inserting
 197 variable references to package fields using the syntax
 198 “\fB${\fP\fIfield\fR[\fB;\fP\fIwidth\fR]\fB}\fP”. Fields are
 199 printed right-aligned unless the width is negative in which case left
 200 alignment will be used. The following \fIfield\fRs are recognized but
 201 they are not necessarily available in the status file (only internal
 202 fields or fields stored in the binary package end up in it):
 203
 204 .nf
 205     \fBArchitecture\fP
 206     \fBBugs\fP
 207     \fBConffiles\fP (internal)
 208     \fBConfig\-Version\fP (internal)
 209     \fBConflicts\fP
 210     \fBBreaks\fP
 211     \fBDepends\fP
 212     \fBDescription\fP
 213     \fBEnhances\fP
 214     \fBEssential\fP
 215     \fBFilename\fP (internal, front-end related)
 216     \fBHomepage\fP
 217     \fBInstalled\-Size\fP
 218     \fBMD5sum\fP (internal, front-end related)
 219     \fBMSDOS\-Filename\fP (internal, front-end related)
 220     \fBMaintainer\fP
 221     \fBOrigin\fP
 222     \fBPackage\fP
 223     \fBPre\-Depends\fP
 224     \fBPriority\fP
 225     \fBProvides\fP
 226     \fBRecommends\fP
 227     \fBReplaces\fP
 228     \fBRevision\fP (obsolete)
 229     \fBSection\fP
 230     \fBSize\fP (internal, front-end related)
 231     \fBSource\fP
 232     \fBStatus\fP (internal)
 233     \fBSuggests\fP
 234     \fBTag\fP (usually not in .deb but in repository Packages files)
 235     \fBTriggers\-Awaited\fP (internal)
 236     \fBTriggers\-Pending\fP (internal)
 237     \fBVersion\fP
 238 .fi
 239
 240 The following are virtual fields, generated by \fBdpkg\-query\fP from
 241 values from other fields (note that these do not use valid names for
 242 fields in control files):
 243 .RS
 244 .TP
 245 .B binary:Package
 246 It contains the binary package name with a possible architecture qualifier
 247 like “libc6:amd64” (since dpkg 1.16.2).
 248 An architecture qualifier will be present to make the package name unambiguous,
 249 for example if the package has a \fBMulti\-Arch\fP field with a value of
 250 \fBsame\fP or the package is of a foreign architecture.
 251 .TP
 252 .B binary:Summary
 253 It contains the package short description (since dpkg 1.16.2).
 254 .TP
 255 .B db:Status\-Abbrev
 256 It contains the abbreviated package status (as three characters),
 257 such as “ii ” or “iHR” (since dpkg 1.16.2).
 258 See the \fB\-\-list\fP command description for more details.
 259 .TP
 260 .B db:Status\-Want
 261 It contains the package wanted status, part of the Status field
 262 (since dpkg 1.17.11).
 263 .TP
 264 .B db:Status\-Status
 265 It contains the package status word, part of the Status field
 266 (since dpkg 1.17.11).
 267 .TP
 268 .B db:Status\-Eflag
 269 It contains the package status error flag, part of the Status field
 270 (since dpkg 1.17.11).
 271 .TP
 272 .B source:Package
 273 It contains the source package name for this binary package
 274 (since dpkg 1.16.2).
 275 .TP
 276 .B source:Version
 277 It contains the source package version for this binary package
 278 (since dpkg 1.16.2)
 279 .TP
 280 .B source:Upstream-Version
 281 It contains the source package upstream version for this binary package
 282 (since dpkg 1.18.16)
 283 .RE
 284 .IP
 285 The default format string is “\fB${binary:Package}\et${Version}\en\fP”.
 286 Actually, all other fields found in the status file (i.e. user defined
 287 fields) can be requested, too. They will be printed as-is, though, no
 288 conversion nor error checking is done on them. To get the name of the
 289 \fBdpkg\fP maintainer and the installed version, you could run:
 290
 291 .nf
 292   \fBdpkg\-query \-W \-f='${binary:Package} ${Version}\\t${Maintainer}\\n' dpkg\fP
 293 .fi
 294 .
 295 .SH EXIT STATUS
 296 .TP
 297 .B 0
 298 The requested query was successfully performed.
 299 .TP
 300 .B 1
 301 The requested query failed either fully or partially, due to no file or
 302 package being found (except for \fB\-\-control\-path\fP,
 303 \fB\-\-control\-list\fP and \fB\-\-control\-show\fP were such errors are
 304 fatal).
 305 .TP
 306 .B 2
 307 Fatal or unrecoverable error due to invalid command-line usage, or
 308 interactions with the system, such as accesses to the database,
 309 memory allocations, etc.
 310 .
 311 .SH ENVIRONMENT
 312 .TP
 313 .B DPKG_ADMINDIR
 314 If set and the \fB\-\-admindir\fP option has not been specified, it will
 315 be used as the \fBdpkg\fP data directory.
 316 .TP
 317 \fBCOLUMNS\fP
 318 This setting influences the output of the \fB\-\-list\fP option by changing
 319 the width of its output.
 320 .
 321 .SH SEE ALSO
 322 .BR dpkg (1).
 323