summaryrefslogtreecommitdiffstats
path: root/man/dpkg-query.pod
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--man/dpkg-query.pod497
1 files changed, 497 insertions, 0 deletions
diff --git a/man/dpkg-query.pod b/man/dpkg-query.pod
new file mode 100644
index 0000000..d361ac9
--- /dev/null
+++ b/man/dpkg-query.pod
@@ -0,0 +1,497 @@
+# dpkg manual page - dpkg-query(1)
+#
+# Copyright © 2001 Wichert Akkerman <wakkerma@debian.org>
+# Copyright © 2006-2007 Frank Lichtenheld <djpig@debian.org>
+# Copyright © 2006-2015 Guillem Jover <guillem@debian.org>
+# Copyright © 2008-2011 Raphaël Hertzog <hertzog@debian.org>
+#
+# This is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+=encoding utf8
+
+=head1 NAME
+
+dpkg-query - a tool to query the dpkg database
+
+=head1 SYNOPSIS
+
+B<dpkg-query>
+[I<option>...] I<command>
+
+=head1 DESCRIPTION
+
+B<dpkg-query> is a tool to show information about packages listed in
+the B<dpkg> database.
+
+=head1 COMMANDS
+
+=over
+
+=item B<-l>, B<--list> [I<package-name-pattern>...]
+
+List all known packages matching one or more patterns, regardless of their
+status, which includes any real or virtual package referenced in any
+dependency relationship field (such as B<Breaks>, B<Enhances>, etc.).
+If no I<package-name-pattern> is given, list all packages in
+I<%ADMINDIR%/status>, excluding the ones marked as not-installed (i.e.
+those which have been previously purged).
+Normal shell wildcard characters are allowed in I<package-name-pattern>.
+Please note you will probably have to quote I<package-name-pattern> to
+prevent the shell from performing filename expansion.
+For example this will list all package names starting with “libc6”:
+
+=over
+
+ dpkg-query -l 'libc6*'
+
+=back
+
+The first three columns of the output show the desired action, the package
+status, and errors, in that order.
+
+Desired action:
+
+=over
+
+=item u = Unknown
+
+=item i = Install
+
+=item h = Hold
+
+=item r = Remove
+
+=item p = Purge
+
+=back
+
+Package status:
+
+=over
+
+=item n = Not-installed
+
+=item c = Config-files
+
+=item H = Half-installed
+
+=item U = Unpacked
+
+=item F = Half-configured
+
+=item W = Triggers-awaiting
+
+=item t = Triggers-pending
+
+=item i = Installed
+
+=back
+
+Error flags:
+
+=over
+
+=item E<lt>emptyE<gt> = (none)
+
+=item R = Reinst-required
+
+=back
+
+An uppercase status or error letter indicates the package is likely to
+cause severe problems. Please refer to B<dpkg>(1) for information
+about the above states and flags.
+
+The output format of this option is not configurable, but varies
+automatically to fit the terminal width. It is intended for human
+readers, and is not easily machine-readable. See B<-W> (B<--show>)
+and B<--showformat> for a way to configure the output format.
+
+=item B<-W>, B<--show> [I<package-name-pattern>...]
+
+Just like the B<--list> option this will list all packages matching
+the given pattern. However the output can be customized using the
+B<--showformat> option.
+The default output format gives one line per matching package, each line
+having the name (extended with the architecture qualifier for
+B<Multi-Arch> B<same> packages) and installed version of the package,
+separated by a tab.
+
+=item B<-s>, B<--status> [I<package-name>...]
+
+Report status of specified package. This just displays the entry in
+the installed package status database.
+If no I<package-name> is specified it will display all package entries
+in the status database (since dpkg 1.19.1).
+When multiple I<package-name> entries are listed, the requested status
+entries are separated by an empty line, with the same order as specified
+on the argument list.
+
+=item B<-L>, B<--listfiles> I<package-name>...
+
+List files installed to your system from I<package-name>. When multiple
+I<package-name> are listed, the requested lists of files are separated
+by an empty line, with the same order as specified on the argument list.
+However, note that files created by package-specific installation-scripts
+are not listed.
+
+=item B<--control-list> I<package-name>
+
+List control files installed to your system from I<package-name>
+(since dpkg 1.16.5).
+These can be used as input arguments to B<--control-show>.
+
+=item B<--control-show> I<package-name> I<control-file>
+
+Print the I<control-file> installed to your system from I<package-name>
+to the standard output (since dpkg 1.16.5).
+
+=item B<-c>, B<--control-path> I<package-name> [I<control-file>]
+
+List paths for control files installed to your system from I<package-name>
+(since dpkg 1.15.4).
+If I<control-file> is specified then only list the path for that control
+file if it is present.
+
+B<Warning>: this command is deprecated as it gives direct access to the
+internal dpkg database, please switch to use B<--control-list> and
+B<--control-show> instead for all cases where those commands might
+give the same end result. Although, as long as there is still at least
+one case where this command is needed (i.e. when having to remove a
+damaging postrm maintainer script), and while there is no good solution
+for that, this command will not get removed.
+
+=item B<-S>, B<--search> I<filename-search-pattern>...
+
+Search for packages that own files corresponding to the given pattern.
+Standard shell wildcard characters can be used in the pattern, where
+asterisk (B<*>) and question mark (B<?>) will match a slash,
+and backslash (B<\>) will be used as an escape character.
+
+If the first character in the I<filename-search-pattern> is none of
+‘B<*[?/>’ then it will be considered a substring match and will be
+implicitly surrounded by ‘B<*>’ (as in
+B<*>I<filename-search-pattern>B<*>).
+If the subsequent string contains any of ‘B<*[?\>’, then it will
+handled like a glob pattern, otherwise any trailing ‘B</>’ or
+‘B</.>’ will be removed and a literal path lookup will be performed.
+
+This command will not list extra files created by maintainer scripts,
+nor will it list alternatives.
+
+=item B<-p>, B<--print-avail> [I<package-name>...]
+
+Display details about packages, as found in I<%ADMINDIR%/available>.
+If no I<package-name> is specified, it will display all package entries
+in the I<available> database (since dpkg 1.19.1).
+When multiple I<package-name> are listed, the requested I<available>
+entries are separated by an empty line, with the same order as specified
+on the argument list.
+
+Users of APT-based frontends
+should use B<apt show> I<package-name> instead
+as the I<available> file is only kept up-to-date when
+using B<dselect>.
+
+=item B<-?>, B<--help>
+
+Show the usage message and exit.
+
+=item B<--version>
+
+Show the version and exit.
+
+=back
+
+=head1 OPTIONS
+
+=over
+
+=item B<--admindir=>I<dir>
+
+Change the location of the B<dpkg> database. The default location is
+I<%ADMINDIR%>.
+
+=item B<--load-avail>
+
+Also load the available file when using the B<--show> and B<--list>
+commands, which now default to only querying the status file
+(since dpkg 1.16.2).
+
+=item B<--no-pager>
+
+Disables the use of any pager when showing information (since dpkg 1.19.2).
+
+=item B<-f>, B<--showformat=>I<format>
+
+This option is used to specify the format of the output B<--show>
+will produce (short option since dpkg 1.13.1).
+The format is a string that will be output for each package listed.
+
+In the format string, “B<\>” introduces escapes:
+
+=over
+
+=item B<\n> newline
+
+=item B<\r> carriage return
+
+=item B<\t> tab
+
+=back
+
+“B<\>” before any other character suppresses any special
+meaning of the following character, which is useful for “B<\>”
+and “B<$>”.
+
+Package information can be included by inserting
+variable references to package fields using the syntax
+“B<${>I<field>[B<;>I<width>]B<}>”. Fields are
+printed right-aligned unless the width is negative in which case left
+alignment will be used. The following I<field>s are recognized but
+they are not necessarily available in the status file (only internal
+fields or fields stored in the binary package end up in it):
+
+=over
+
+=item B<Architecture>
+
+=item B<Bugs>
+
+=item B<Conffiles> (internal)
+
+=item B<Config-Version> (internal)
+
+=item B<Conflicts>
+
+=item B<Breaks>
+
+=item B<Depends>
+
+=item B<Description>
+
+=item B<Enhances>
+
+=item B<Protected>
+
+=item B<Essential>
+
+=item B<Filename> (internal, front-end related)
+
+=item B<Homepage>
+
+=item B<Installed-Size>
+
+=item B<MD5sum> (internal, front-end related)
+
+=item B<MSDOS-Filename> (internal, front-end related)
+
+=item B<Maintainer>
+
+=item B<Origin>
+
+=item B<Package>
+
+=item B<Pre-Depends>
+
+=item B<Priority>
+
+=item B<Provides>
+
+=item B<Recommends>
+
+=item B<Replaces>
+
+=item B<Revision> (obsolete)
+
+=item B<Section>
+
+=item B<Size> (internal, front-end related)
+
+=item B<Source>
+
+=item B<Status> (internal)
+
+=item B<Suggests>
+
+=item B<Tag> (usually not in .deb but in repository Packages files)
+
+=item B<Triggers-Awaited> (internal)
+
+=item B<Triggers-Pending> (internal)
+
+=item B<Version>
+
+=back
+
+The following are virtual fields, generated by B<dpkg-query> from
+values from other fields (note that these do not use valid names for
+fields in control files):
+
+=over
+
+=item B<binary:Package>
+
+It contains the binary package name with a possible architecture qualifier
+like “libc6:amd64” (since dpkg 1.16.2).
+An architecture qualifier will be present to make the package name unambiguous,
+for example if the package has a B<Multi-Arch> field with a value of
+B<same> or the package is of a foreign architecture.
+
+=item B<binary:Synopsis>
+
+It contains the package short description (since dpkg 1.19.1).
+
+=item B<binary:Summary>
+
+This is an alias for B<binary:Synopsis> (since dpkg 1.16.2).
+
+=item B<db:Status-Abbrev>
+
+It contains the abbreviated package status (as three characters),
+such as “ii ” or “iHR” (since dpkg 1.16.2).
+See the B<--list> command description for more details.
+
+=item B<db:Status-Want>
+
+It contains the package wanted status, part of the Status field
+(since dpkg 1.17.11).
+
+=item B<db:Status-Status>
+
+It contains the package status word, part of the Status field
+(since dpkg 1.17.11).
+
+=item B<db:Status-Eflag>
+
+It contains the package status error flag, part of the Status field
+(since dpkg 1.17.11).
+
+=item B<db-fsys:Files>
+
+It contains the list of the package filesystem entries separated by newlines
+(since dpkg 1.19.3).
+
+=item B<db-fsys:Last-Modified>
+
+It contains the timestamp in seconds of the last time the package filesystem
+entries were modified (since dpkg 1.19.3).
+
+=item B<source:Package>
+
+It contains the source package name for this binary package
+(since dpkg 1.16.2).
+
+=item B<source:Version>
+
+It contains the source package version for this binary package
+(since dpkg 1.16.2)
+
+=item B<source:Upstream-Version>
+
+It contains the source package upstream version for this binary package
+(since dpkg 1.18.16)
+
+=back
+
+The default format string is “B<${binary:Package}\t${Version}\n>”.
+Actually, all other fields found in the status file (i.e. user defined
+fields) can be requested, too. They will be printed as-is, though, no
+conversion nor error checking is done on them. To get the name of the
+B<dpkg> maintainer and the installed version, you could run:
+
+=over
+
+ dpkg-query -f='${binary:Package} ${Version}\t${Maintainer}\n' \
+ -W dpkg
+
+=back
+
+=back
+
+=head1 EXIT STATUS
+
+=over
+
+=item B<0>
+
+The requested query was successfully performed.
+
+=item B<1>
+
+The requested query failed either fully or partially, due to no file or
+package being found (except for B<--control-path>,
+B<--control-list> and B<--control-show> were such errors are
+fatal).
+
+=item B<2>
+
+Fatal or unrecoverable error due to invalid command-line usage, or
+interactions with the system, such as accesses to the database,
+memory allocations, etc.
+
+=back
+
+=head1 ENVIRONMENT
+
+=head2 External environment
+
+=over
+
+=item B<SHELL>
+
+Sets the program to execute when spawning a command via a shell
+(since dpkg 1.19.2).
+
+=item B<PAGER>
+
+=item B<DPKG_PAGER>
+
+Sets the pager command to use (since dpkg 1.19.1), which will be executed
+with «B<$SHELL -c>».
+If B<SHELL> is not set, «B<sh>» will be used instead.
+The B<DPKG_PAGER> overrides the B<PAGER> environment variable
+(since dpkg 1.19.2).
+
+=item B<DPKG_ADMINDIR>
+
+If set and the B<--admindir> option has not been specified, it will
+be used as the B<dpkg> data directory.
+
+=item B<DPKG_COLORS>
+
+Sets the color mode (since dpkg 1.18.5).
+The currently accepted values are: B<auto> (default), B<always> and
+B<never>.
+
+=back
+
+=head2 Internal environment
+
+=over
+
+=item B<LESS>
+
+Defined by B<dpkg-query> to “B<-FRSXMQ>”, if not already set, when
+spawning a pager (since dpkg 1.19.2).
+To change the default behavior, this variable can be preset to some other
+value including an empty string, or the B<PAGER> or B<DPKG_PAGER>
+variables can be set to disable specific options with «B<-+>», for
+example B<DPKG_PAGER="less -+F">.
+
+=back
+
+=head1 SEE ALSO
+
+B<dpkg>(1).
+