Adding upstream version 1.22.4.upstream/1.22.4

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

1 files changed, 344 insertions, 0 deletions

diff --git a/man/dpkg-split.pod b/man/dpkg-split.pod
new file mode 100644
index 0000000..8f5b553
--- /dev/null
+++ b/man/dpkg-split.pod
@@ -0,0 +1,344 @@
+# dpkg manual page - dpkg-split(1)
+#
+# Copyright © 1995-1996 Ian Jackson <ijackson@chiark.greenend.org.uk>
+# Copyright © 2011 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-split - Debian package archive split/join tool
+
+=head1 SYNOPSIS
+
+B<dpkg-split>
+[I<option>...] I<command>
+
+=head1 DESCRIPTION
+
+B<dpkg-split>
+splits Debian binary package files into smaller parts and reassembles
+them again, to support the storage of large package files on small
+media such as floppy disks.
+
+It can be operated manually using the
+B<--split>, B<--join> and B<--info>
+options.
+
+It also has an automatic mode, invoked using the
+B<--auto>
+option, where it maintains a queue of parts seen but not yet
+reassembled and reassembles a package file when it has seen all of its
+parts.
+The
+B<--listq> and B<--discard>
+options allow the management of the queue.
+
+All splitting, joining and queueing operations produce informative
+messages on standard output; these may safely be ignored.
+
+=head1 COMMANDS
+
+=over
+
+=item B<-s>, B<--split> I<complete-archive> [I<prefix>]
+
+Splits a single Debian binary package into several parts.
+
+The parts are named
+I<prefix>B<.>I<N>B<of>I<M>B<.deb>
+where
+I<N>
+is the part number, starting at 1, and
+I<M>
+is the total number of parts (both in decimal).
+
+If no
+I<prefix>
+is supplied then the
+I<complete-archive>
+filename is taken, including directory, with any trailing
+B<.deb>
+removed.
+
+=item B<-j>, B<--join> I<part>...
+
+Joins the parts of a package file together, reassembling the original
+file as it was before it was split.
+
+The part files given as arguments must be all the parts of exactly the
+same original binary file.
+Each part must occur exactly once in the
+argument list, though the parts to not need to be listed in order.
+
+The parts must of course all have been generated with the same part
+size specified at split time, which means that they must usually have
+been generated by the same invocation of
+B<dpkg-split --split>.
+
+The parts' filenames are not significant for the reassembly process.
+
+By default the output file is called
+I<package>B<_>I<version>B<_>I<arch>B<.deb>.
+
+=item B<-I>, B<--info> I<part>...
+
+Prints information, in a human-readable format, about the part file(s)
+specified.
+Arguments which are not binary package parts produce a
+message saying so instead (but still on standard output).
+
+=item B<-a>, B<--auto -o> I<complete-output> I<part>
+
+Automatically queue parts and reassemble a package if possible.
+
+The
+I<part>
+specified is examined, and compared with other parts of the same
+package (if any) in the queue of packages file parts.
+
+If all parts of the package file of which
+I<part>
+is a part are available then the package is reassembled and written to
+I<complete-output>
+(which should not usually already exist, though this is not an
+error).
+
+If not then the
+I<part>
+is copied into the queue and
+I<complete-output>
+is not created.
+
+If
+I<part>
+is not a split binary package part then
+B<dpkg-split>
+will exit with status B<1>; if some other trouble occurs then it will
+exit with status B<2>.
+
+The
+B<--output> or B<-o>
+option must be supplied when using
+B<--auto>.
+(If this were not mandatory the calling program would not know what
+output file to expect.)
+
+=item B<-l>, B<--listq>
+
+Lists the contents of the queue of packages to be reassembled.
+
+For each package file of which parts are in the queue the output gives
+the name of the package, the parts in the queue, and the total number
+of bytes stored in the queue.
+
+=item B<-d>, B<--discard> [I<package>...]
+
+This discards parts from the queue of those waiting for the remaining
+parts of their packages.
+
+If no
+I<package>
+is specified then the queue is cleared completely; if any are
+specified then only parts of the relevant package(s) are deleted.
+
+=item B<-?>, B<--help>
+
+Show the usage message and exit.
+
+=item B<--version>
+
+Show the version and exit.
+
+=back
+
+=head1 OPTIONS
+
+=over
+
+=item B<--depotdir> I<directory>
+
+Specifies an alternative directory for the queue of parts awaiting
+automatic reassembly.
+The default is
+B<%ADMINDIR%/parts>.
+
+=item B<--admindir> I<directory>
+
+Set the administrative directory to I<directory> (since dpkg 1.21.10).
+This is where the I<statoverride> file is stored.
+Defaults to «I<%ADMINDIR%>» if B<DPKG_ADMINDIR> has not been set.
+
+=item B<--root> I<directory>
+
+Set the root directory to B<directory> (since dpkg 1.21.10),
+which sets the installation directory to «I<directory>» and
+the administrative directory to «I<directory>B<%ADMINDIR%>»
+if B<DPKG_ROOT> has not been set.
+
+=item B<-S>, B<--partsize> I<kibibytes>
+
+Specifies the maximum part size when splitting, in kibibytes (1024
+bytes).
+The default is 450 KiB.
+
+=item B<-o>, B<--output> I<complete-output>
+
+Specifies the output file name for a reassembly.
+
+This overrides the default for a manual reassembly
+(B<--join>)
+and is mandatory for an automatic queue-or-reassemble
+(B<--auto>).
+
+=item B<-Q>, B<--npquiet>
+
+When doing automatic queue-or-reassembly
+B<dpkg-split>
+usually prints a message if it is given a
+I<part>
+that is not a binary package part.
+This option suppresses this
+message, to allow programs such as
+B<dpkg>
+to cope with both split and unsplit packages without producing
+spurious messages.
+
+=item B<--msdos>
+
+Forces the output filenames generated by
+B<--split>
+to be MSDOS-compatible.
+
+This mangles the prefix - either the default derived from the input
+filename or the one supplied as an argument: alphanumerics are
+lowercased, plus signs are replaced by
+B<x>'s
+and all other characters are discarded.
+
+The result is then truncated as much as is necessary, and filenames of
+the form
+I<prefixN>B<of>I<M>B<.deb>
+are generated.
+
+=back
+
+=head1 EXIT STATUS
+
+=over
+
+=item B<0>
+
+The requested split, merge, or other command succeeded.
+B<--info>
+commands count as successful even if the files are not binary package
+parts.
+
+=item B<1>
+
+Only occurs with
+B<--auto>
+and indicates that the
+I<part>
+file was not a binary package part.
+
+=item B<2>
+
+Fatal or unrecoverable error due to invalid command-line usage,
+a file that looked like a package part file but was corrupted, or
+interactions with the system, such as accesses to the database,
+memory allocations, etc.
+
+=back
+
+=head1 ENVIRONMENT
+
+=over
+
+=item B<DPKG_ROOT>
+
+If set and B<--root> option has not been specified,
+it will be used as the filesystem root directory (since dpkg 1.21.10).
+
+=item B<DPKG_ADMINDIR>
+
+If set and the B<--admindir> or B<--root> options have not been specified,
+it will be used as the B<dpkg> data directory (since dpkg 1.21.10).
+
+=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>.
+
+=item B<SOURCE_DATE_EPOCH>
+
+If set, it will be used as the timestamp (as seconds since the epoch) in
+the L<deb-split(5)>'s L<ar(5)> container.
+
+=back
+
+=head1 FILES
+
+=over
+
+=item I<%ADMINDIR%/parts>
+
+The default queue directory for part files awaiting automatic
+reassembly.
+
+The filenames used in this directory are in a format internal to
+B<dpkg-split>
+and are unlikely to be useful to other programs, and in any case the
+filename format should not be relied upon.
+
+=back
+
+=head1 SECURITY
+
+Examining or joining untrusted split package archives should be considered
+a security boundary, and any breakage of that boundary stemming from these
+operations should be considered a security vulnerability.
+Performing these operations over untrusted data as root is strongly
+discouraged.
+
+Auto-accumulating and discarding split package parts are considered
+privileged operations that might allow root escalation.
+These operations must never be delegated to an untrusted user or be done
+on untrusted packages, as that might allow root access to the system.
+
+Splitting package archives should only be performed over trusted data.
+
+=head1 BUGS
+
+Full details of the packages in the queue are impossible to get
+without digging into the queue directory yourself.
+
+There is no easy way to test whether a file that may be a binary
+package part is one.
+
+=head1 SEE ALSO
+
+L<deb(5)>,
+L<deb-control(5)>,
+L<dpkg-deb(1)>,
+L<dpkg(1)>.