diff options
Diffstat (limited to '')
| -rw-r--r-- | man/dpkg-query.pod | 574 |
1 files changed, 574 insertions, 0 deletions
diff --git a/man/dpkg-query.pod b/man/dpkg-query.pod new file mode 100644 index 0000000..599fed4 --- /dev/null +++ b/man/dpkg-query.pod @@ -0,0 +1,574 @@ +# 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 L<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 patterns. +However the output can be customized using the +B<--showformat> option. + +The default output format gives one line per matching package, +each line consisting of the package name and its installed version, +separated by a tab. +The package name will be architecture qualified for packages with a +B<Multi-Arch> field with the value B<same> or with a foreign architecture, +which is an architecture that is neither the native one nor B<all>. + +=item B<-s>, B<--status> [I<package-name>...] + +Report status of specified packages. +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>s are listed, the requested lists of files are separated +by an empty line, with the same order as specified on the argument list. + +Each file diversion is printed on its own line after its diverted file, +prefixed with one of the following localized strings: + +Z<> + locally diverted to: I<diverted-to> + package diverts others to: I<diverted-to> + diverted by I<pkg> to: I<diverted-to> + +B<Hint>: When machine parsing the output, it is customary to set the locale to +B<C.UTF-8> to get reproducible results. +On some systems this might also +require adapting the B<LANGUAGE> environment variable appropriately if it +is already set (see L<locale(7)>). + +This command will not list extra files created by maintainer scripts, +nor will it list alternatives. + +=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 patterns. +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. + +The output format consists of one line per matching pattern, with a list +of packages owning the pathname separated by a comma (U+002C ‘B<,>’) and +a space (U+0020 ‘B< >’), followed by a colon (U+003A ‘B<:>’) and a space, +followed by the pathname. +As in: + + pkgname1, pkgname2: pathname1 + pkgname3: pathname2 + +File diversions are printed with the following localized strings: + +Z<> + diversion by I<pkgname> from: I<diverted-from> + diversion by I<pkgname> to: I<diverted-to> + +or for local diversions: + +Z<> + local diversion from: I<diverted-from> + local diversion to: I<diverted-to> + +B<Hint>: When machine parsing the output, it is customary to set the locale to +B<C.UTF-8> to get reproducible results. + +=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<--root=>I<directory> + +Set the root directory to I<directory>, which sets the administrative +directory to «I<directory>%ADMINDIR%» (since dpkg 1.21.0). + +=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 packages with a B<Multi-Arch> field with the value B<same> or +with a foreign architecture, which is an architecture that is neither +the native one nor B<all>. + +=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<%DPKG_DEFAULT_SHELL%>» will be used instead. +The B<DPKG_PAGER> overrides the B<PAGER> environment variable +(since dpkg 1.19.2). + +=item B<DPKG_ROOT> + +If set and the B<--root> option has not been specified, it will +be used as the filesystem root directory (since dpkg 1.21.0). + +=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_DEBUG> + +Sets the debug mask (since dpkg 1.21.10) from an octal value. +The currently accepted flags are described in the B<dpkg --debug> option, +but not all these flags might have an effect on this program. + +=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 SECURITY + +Query operations should never require root, and delegating their execution +to unprivileged users via some gain-root command can have security +implications (such as privilege escalation), for example when a pager is +automatically invoked by the tool. + +=head1 SEE ALSO + +L<dpkg(1)>. + |