Adding upstream version 1.22.4.upstream/1.22.4

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 456 insertions, 0 deletions

diff --git a/man/dpkg-deb.pod b/man/dpkg-deb.pod
new file mode 100644
index 0000000..103d6c0
--- /dev/null
+++ b/man/dpkg-deb.pod
@@ -0,0 +1,456 @@
+# dpkg manual page - dpkg-deb(1)
+#
+# Copyright © 1995-1996 Ian Jackson <ijackson@chiark.greenend.org.uk>
+# Copyright © 1999 Wichert Akkerman <wakkerma@debian.org>
+# Copyright © 2006 Frank Lichtenheld <djpig@debian.org>
+# Copyright © 2007-2015 Guillem Jover <guillem@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-deb - Debian package archive (.deb) manipulation tool
+
+=head1 SYNOPSIS
+
+B<dpkg-deb>
+[I<option>...] I<command>
+
+=head1 DESCRIPTION
+
+B<dpkg-deb>
+packs, unpacks and provides information about Debian archives.
+
+Use
+B<dpkg>
+to install and remove packages from your system.
+
+You can also invoke
+B<dpkg-deb>
+by calling
+B<dpkg>
+with whatever options you want to pass to
+B<dpkg-deb>.
+B<dpkg>
+will spot that you wanted
+B<dpkg-deb>
+and run it for you.
+
+For most commands taking an input archive argument, the archive can be
+read from standard input if the archive name is given as a single minus
+character («B<->»); otherwise lack of support will be documented in
+their respective command description.
+
+=head1 COMMANDS
+
+=over
+
+=item B<-b>, B<--build> I<binary-directory> [I<archive>|I<directory>]
+
+Creates a debian archive from the filesystem tree stored in
+I<binary-directory>.
+I<binary-directory>
+must have a
+B<DEBIAN>
+subdirectory, which contains the control information files such
+as the control file itself.
+This directory will
+I<not>
+appear in the binary package's filesystem archive, but instead
+the files in it will be put in the binary package's control
+information area.
+
+Unless you specify
+B<--nocheck>, B<dpkg-deb>
+will read
+B<DEBIAN/control>
+and parse it.
+It will check the file for syntax errors and other problems,
+and display the name of the binary package being built.
+B<dpkg-deb>
+will also check the permissions of the maintainer scripts and other
+files found in the
+B<DEBIAN>
+control information directory.
+
+If no
+I<archive>
+is specified then
+B<dpkg-deb>
+will write the package into the file
+I<binary-directory>B<.deb>.
+
+If the archive to be created already exists it will be overwritten.
+
+If the second argument is a directory then
+B<dpkg-deb>
+will write to the file
+I<directory>B</>I<package>B<_>I<version>B<_>I<arch>B<.deb.>
+When a target directory is specified, rather than a file, the
+B<--nocheck>
+option may not be used (since
+B<dpkg-deb>
+needs to read and parse the package control file to determine which
+filename to use).
+
+=item B<-I>, B<--info> I<archive> [I<control-file-name>...]
+
+Provides information about a binary package archive.
+
+If no
+I<control-file-name>s
+are specified then it will print a summary of the contents of the
+package as well as its control file.
+
+If any
+I<control-file-name>s
+are specified then
+B<dpkg-deb>
+will print them in the order they were specified; if any of the
+components weren't present it will print an error message to stderr
+about each one and exit with status 2.
+
+=item B<-W>, B<--show> I<archive>
+
+Provides information about a binary package archive in the format
+specified by the
+B<--showformat>
+argument.
+The default format displays the package's name and version
+on one line, separated by a tabulator.
+
+=item B<-f>, B<--field> I<archive> [I<control-field-name>...]
+
+Extracts control file information from a binary package archive.
+
+If no
+I<control-field-name>s
+are specified then it will print the whole control file.
+
+If any are specified then
+B<dpkg-deb>
+will print their contents, in the order in which they appear in the
+control file.
+If more than one
+I<control-field-name>
+is specified then
+B<dpkg-deb>
+will precede each with its field name (and a colon and space).
+
+No errors are reported for fields requested but not found.
+
+=item B<-c>, B<--contents> I<archive>
+
+Lists the contents of the filesystem tree archive portion of the
+package archive.
+It is currently produced in the format generated by
+B<tar>'s
+verbose listing.
+
+=item B<-x>, B<--extract> I<archive> I<directory>
+
+Extracts the filesystem tree from a package archive into the specified
+directory.
+
+Note that extracting a package to the root directory will
+I<not>
+result in a correct installation!
+Use
+B<dpkg>
+to install packages.
+
+I<directory>
+(but not its parents) will be created if necessary, and its permissions
+modified to match the contents of the package.
+
+=item B<-X>, B<--vextract> I<archive> I<directory>
+
+Is like
+B<--extract> (B<-x>)
+with
+B<--verbose> (B<-v>)
+which prints a listing of the files extracted as it goes.
+
+=item B<-R>, B<--raw-extract> I<archive> I<directory>
+
+Extracts the filesystem tree from a package archive into a specified
+directory, and the control information files into a
+B<DEBIAN>
+subdirectory of the specified directory (since dpkg 1.16.1).
+
+The target directory (but not its parents) will be created if necessary.
+
+The input archive is not (currently) processed sequentially, so reading
+it from standard input («B<->») is B<not> supported.
+
+=item B<--ctrl-tarfile> I<archive>
+
+Extracts the control data from a binary package and sends it to standard
+output in
+B<tar>
+format (since dpkg 1.17.14).
+Together with
+L<tar(1)>
+this can be used to extract a particular control file from a package archive.
+The input archive will always be processed sequentially.
+
+=item B<--fsys-tarfile> I<archive>
+
+Extracts the filesystem tree data from a binary package and sends it
+to standard output in
+B<tar>
+format.
+Together with
+L<tar(1)>
+this can be used to extract a particular file from a package archive.
+The input archive will always be processed sequentially.
+
+=item B<-e>, B<--control> I<archive> [I<directory>]
+
+Extracts the control information files from a package archive into the
+specified directory.
+
+If no directory is specified then a subdirectory
+B<DEBIAN>
+in the current directory is used.
+
+The target directory (but not its parents) will be created if
+necessary.
+
+=item B<-?>, B<--help>
+
+Show the usage message and exit.
+
+=item B<--version>
+
+Show the version and exit.
+
+=back
+
+=head1 OPTIONS
+
+=over
+
+=item B<--showformat=>I<format>
+
+This option is used to specify the format of the output B<--show>
+will produce.
+The format is a string that will be output for each package
+listed.
+
+The string may reference any status field using the
+“${I<field-name>}” form, a list of the valid fields can be easily
+produced using
+B<-I>
+on the same package.
+A complete explanation of the formatting options
+(including escape sequences and field tabbing) can be found in the
+explanation of the B<--showformat> option in
+L<dpkg-query(1)>.
+
+The default for this field is “${Package}\t${Version}\n”.
+
+=item B<-z>I<compress-level>
+
+Specify which compression level to use on the compressor backend, when
+building a package (default is 9 for gzip, 6 for xz, 3 for zstd).
+The accepted values are compressor specific.
+For gzip, from 0-9 with 0 being mapped to compressor none.
+For xz from 0-9.
+For zstd from 0-22, with levels from 20 to 22 enabling its ultra mode.
+Before dpkg 1.16.2 level 0 was equivalent to compressor none for all
+compressors.
+
+=item B<-S>I<compress-strategy>
+
+Specify which compression strategy to use on the compressor backend, when
+building a package (since dpkg 1.16.2).
+Allowed values are B<none> (since
+dpkg 1.16.4), B<filtered>, B<huffman>, B<rle> and B<fixed> for
+gzip (since dpkg 1.17.0) and B<extreme> for xz.
+
+=item B<-Z>I<compress-type>
+
+Specify which compression type to use when building a package.
+Allowed values are B<gzip>, B<xz> (since dpkg 1.15.6),
+B<zstd> (since dpkg 1.21.18)
+and B<none> (default is B<%DEB_DEFAULT_COMPRESSOR%>).
+
+=item B<--[no-]uniform-compression>
+
+Specify that the same compression parameters should be used for all archive
+members (i.e. B<control.tar> and B<data.tar>; since dpkg 1.17.6).
+Otherwise only the
+B<data.tar> member will use those parameters.
+The only supported
+compression types allowed to be uniformly used are B<none>, B<gzip>,
+B<xz> and B<zstd>.
+The B<--no-uniform-compression> option disables uniform compression
+(since dpkg 1.19.0).
+Uniform compression is the default (since dpkg 1.19.0).
+
+=item B<--threads-max=>I<threads>
+
+Sets the maximum number of threads allowed for compressors that support
+multi-threaded operations (since dpkg 1.21.9).
+
+=item B<--root-owner-group>
+
+Set the owner and group for each entry in the filesystem tree data to
+root with id 0 (since dpkg 1.19.0).
+
+B<Note>: This option can be useful for rootless builds (see
+I<rootless-builds.txt>), but should B<not> be used when the
+entries have an owner or group that is not root.
+Support for these will be added later in the form of a meta manifest.
+
+=item B<--deb-format=>I<format>
+
+Set the archive format version used when building (since dpkg 1.17.0).
+Allowed values are B<2.0> for the new format, and B<0.939000>
+for the old one (default is B<2.0>).
+
+The old archive format is less easily parsed by non-Debian tools and is
+now obsolete; its only use is when building packages to be parsed by
+versions of dpkg older than 0.93.76 (September 1995), which was released
+as i386 a.out only.
+
+=item B<--nocheck>
+
+Inhibits
+B<dpkg-deb --build>'s
+usual checks on the proposed contents of an archive.
+You can build
+any archive you want, no matter how broken, this way.
+
+=item B<-v>, B<--verbose>
+
+Enables verbose output (since dpkg 1.16.1).
+This currently only affects B<--extract> making it behave like
+B<--vextract>.
+
+=item B<-D>, B<--debug>
+
+Enables debugging output.
+This is not very interesting.
+
+=back
+
+=head1 EXIT STATUS
+
+=over
+
+=item B<0>
+
+The requested action was successfully performed.
+
+=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
+
+=over
+
+=item B<DPKG_DEB_THREADS_MAX>
+
+Sets the maximum number of threads allowed for compressors that support
+multi-threaded operations (since dpkg 1.21.9).
+
+The B<--threads-max> option overrides this value.
+
+=item B<DPKG_DEB_COMPRESSOR_TYPE>
+
+Sets the compressor type to use (since dpkg 1.21.10).
+
+The B<-Z> option overrides this value.
+
+=item B<DPKG_DEB_COMPRESSOR_LEVEL>
+
+Sets the compressor level to use (since dpkg 1.21.10).
+
+The B<-z> option overrides this value.
+
+=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>.
+
+=item B<TMPDIR>
+
+If set, B<dpkg-deb> will use it as the directory in which to create
+temporary files and directories.
+
+=item B<SOURCE_DATE_EPOCH>
+
+If set, it will be used as the timestamp (as seconds since the epoch) in
+the L<deb(5)>'s L<ar(5)> container and used to clamp the mtime in
+the L<tar(5)> file entries.
+
+=back
+
+=head1 NOTES
+
+Do not attempt to use just
+B<dpkg-deb>
+to install software!
+You must use
+B<dpkg>
+proper to ensure that all the files are correctly placed and the
+package's scripts run and its status and contents recorded.
+
+=head1 SECURITY
+
+Examining untrusted package archives or extracting them into staging
+directories should be considered a security boundary, and any breakage
+of that boundary stemming from these operations should be considered a
+security vulnerability.
+But handling untrusted package archives should not be done lightly,
+as the surface area includes any compression library supported,
+in addition to the archive formats and control files themselves.
+Performing these operations over untrusted data as root is strongly
+discouraged.
+
+Building package archives should only be performed over trusted data.
+
+=head1 BUGS
+
+B<dpkg-deb -I>
+I<package1>B<.deb>
+I<package2>B<.deb>
+does the wrong thing.
+
+There is no authentication on
+B<.deb>
+files; in fact, there isn't even a straightforward checksum.
+(Higher level tools like APT support authenticating B<.deb> packages
+retrieved from a given repository, and most packages nowadays provide an
+md5sum control file generated by debian/rules.
+Though this is not directly
+supported by the lower level tools.)
+
+=head1 SEE ALSO
+
+F<%PKGDOCDIR%/spec/rootless-builds.txt>,
+L<deb(5)>,
+L<deb-control(5)>,
+L<dpkg(1)>,
+L<dselect(1)>.