From ea314d2f45c40a006c0104157013ab4b857f665f Mon Sep 17 00:00:00 2001
From: Daniel Baumann <daniel.baumann@progress-linux.org>
Date: Mon, 15 Apr 2024 20:35:28 +0200
Subject: Adding upstream version 1.22.4.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
---
 man/dpkg-query.pod | 574 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 574 insertions(+)
 create mode 100644 man/dpkg-query.pod

(limited to 'man/dpkg-query.pod')

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)>.
+
-- 
cgit v1.2.3