man/dpkg-split.pod

   1 # dpkg manual page - dpkg-split(1)
   2 #
   3 # Copyright © 1995-1996 Ian Jackson <ijackson@chiark.greenend.org.uk>
   4 # Copyright © 2011 Guillem Jover <guillem@debian.org>
   5 #
   6 # This is free software; you can redistribute it and/or modify
   7 # it under the terms of the GNU General Public License as published by
   8 # the Free Software Foundation; either version 2 of the License, or
   9 # (at your option) any later version.
  10 #
  11 # This is distributed in the hope that it will be useful,
  12 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14 # GNU General Public License for more details.
  15 #
  16 # You should have received a copy of the GNU General Public License
  17 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
  18
  19 =encoding utf8
  20
  21 =head1 NAME
  22
  23 dpkg-split - Debian package archive split/join tool
  24
  25 =head1 SYNOPSIS
  26
  27 B<dpkg-split>
  28 [I<option>...] I<command>
  29
  30 =head1 DESCRIPTION
  31
  32 B<dpkg-split>
  33 splits Debian binary package files into smaller parts and reassembles
  34 them again, to support the storage of large package files on small
  35 media such as floppy disks.
  36
  37 It can be operated manually using the
  38 B<--split>, B<--join> and B<--info>
  39 options.
  40
  41 It also has an automatic mode, invoked using the
  42 B<--auto>
  43 option, where it maintains a queue of parts seen but not yet
  44 reassembled and reassembles a package file when it has seen all of its
  45 parts. The
  46 B<--listq> and B<--discard>
  47 options allow the management of the queue.
  48
  49 All splitting, joining and queueing operations produce informative
  50 messages on standard output; these may safely be ignored.
  51
  52 =head1 COMMANDS
  53
  54 =over
  55
  56 =item B<-s>, B<--split> I<complete-archive> [I<prefix>]
  57
  58 Splits a single Debian binary package into several parts.
  59
  60 The parts are named
  61 I<prefix>B<.>I<N>B<of>I<M>B<.deb>
  62 where
  63 I<N>
  64 is the part number, starting at 1, and
  65 I<M>
  66 is the total number of parts (both in decimal).
  67
  68 If no
  69 I<prefix>
  70 is supplied then the
  71 I<complete-archive>
  72 filename is taken, including directory, with any trailing
  73 B<.deb>
  74 removed.
  75
  76 =item B<-j>, B<--join> I<part>...
  77
  78 Joins the parts of a package file together, reassembling the original
  79 file as it was before it was split.
  80
  81 The part files given as arguments must be all the parts of exactly the
  82 same original binary file. Each part must occur exactly once in the
  83 argument list, though the parts to not need to be listed in order.
  84
  85 The parts must of course all have been generated with the same part
  86 size specified at split time, which means that they must usually have
  87 been generated by the same invocation of
  88 B<dpkg-split --split>.
  89
  90 The parts' filenames are not significant for the reassembly process.
  91
  92 By default the output file is called
  93 I<package>B<_>I<version>B<_>I<arch>B<.deb>.
  94
  95 =item B<-I>, B<--info> I<part>...
  96
  97 Prints information, in a human-readable format, about the part file(s)
  98 specified. Arguments which are not binary package parts produce a
  99 message saying so instead (but still on standard output).
 100
 101 =item B<-a>, B<--auto -o> I<complete-output> I<part>
 102
 103 Automatically queue parts and reassemble a package if possible.
 104
 105 The
 106 I<part>
 107 specified is examined, and compared with other parts of the same
 108 package (if any) in the queue of packages file parts.
 109
 110 If all parts of the package file of which
 111 I<part>
 112 is a part are available then the package is reassembled and written to
 113 I<complete-output>
 114 (which should not usually already exist, though this is not an
 115 error).
 116
 117 If not then the
 118 I<part>
 119 is copied into the queue and
 120 I<complete-output>
 121 is not created.
 122
 123 If
 124 I<part>
 125 is not a split binary package part then
 126 B<dpkg-split>
 127 will exit with status B<1>; if some other trouble occurs then it will
 128 exit with status B<2>.
 129
 130 The
 131 B<--output> or B<-o>
 132 option must be supplied when using
 133 B<--auto>.
 134 (If this were not mandatory the calling program would not know what
 135 output file to expect.)
 136
 137 =item B<-l>, B<--listq>
 138
 139 Lists the contents of the queue of packages to be reassembled.
 140
 141 For each package file of which parts are in the queue the output gives
 142 the name of the package, the parts in the queue, and the total number
 143 of bytes stored in the queue.
 144
 145 =item B<-d>, B<--discard> [I<package>...]
 146
 147 This discards parts from the queue of those waiting for the remaining
 148 parts of their packages.
 149
 150 If no
 151 I<package>
 152 is specified then the queue is cleared completely; if any are
 153 specified then only parts of the relevant package(s) are deleted.
 154
 155 =item B<-?>, B<--help>
 156
 157 Show the usage message and exit.
 158
 159 =item B<--version>
 160
 161 Show the version and exit.
 162
 163 =back
 164
 165 =head1 OPTIONS
 166
 167 =over
 168
 169 =item B<--depotdir> I<directory>
 170
 171 Specifies an alternative directory for the queue of parts awaiting
 172 automatic reassembly. The default is
 173 B<%ADMINDIR%/parts>.
 174
 175 =item B<--admindir> I<directory>
 176
 177 Set the administrative directory to I<directory> (since dpkg 1.21.10).
 178 This is where the I<statoverride> file is stored.
 179 Defaults to «I<%ADMINDIR%>» if B<DPKG_ADMINDIR> has not been set.
 180
 181 =item B<--root> I<directory>
 182
 183 Set the root directory to B<directory> (since dpkg 1.21.10),
 184 which sets the installation directory to «I<directory>» and
 185 the administrative directory to «I<directory>B<%ADMINDIR%>»
 186 if B<DPKG_ROOT> has not been set.
 187
 188 =item B<-S>, B<--partsize> I<kibibytes>
 189
 190 Specifies the maximum part size when splitting, in kibibytes (1024
 191 bytes). The default is 450 KiB.
 192
 193 =item B<-o>, B<--output> I<complete-output>
 194
 195 Specifies the output file name for a reassembly.
 196
 197 This overrides the default for a manual reassembly
 198 (B<--join>)
 199 and is mandatory for an automatic queue-or-reassemble
 200 (B<--auto>).
 201
 202 =item B<-Q>, B<--npquiet>
 203
 204 When doing automatic queue-or-reassembly
 205 B<dpkg-split>
 206 usually prints a message if it is given a
 207 I<part>
 208 that is not a binary package part. This option suppresses this
 209 message, to allow programs such as
 210 B<dpkg>
 211 to cope with both split and unsplit packages without producing
 212 spurious messages.
 213
 214 =item B<--msdos>
 215
 216 Forces the output filenames generated by
 217 B<--split>
 218 to be MSDOS-compatible.
 219
 220 This mangles the prefix - either the default derived from the input
 221 filename or the one supplied as an argument: alphanumerics are
 222 lowercased, plus signs are replaced by
 223 B<x>'s
 224 and all other characters are discarded.
 225
 226 The result is then truncated as much as is necessary, and filenames of
 227 the form
 228 I<prefixN>B<of>I<M>B<.deb>
 229 are generated.
 230
 231 =back
 232
 233 =head1 EXIT STATUS
 234
 235 =over
 236
 237 =item B<0>
 238
 239 The requested split, merge, or other command succeeded.
 240 B<--info>
 241 commands count as successful even if the files are not binary package
 242 parts.
 243
 244 =item B<1>
 245
 246 Only occurs with
 247 B<--auto>
 248 and indicates that the
 249 I<part>
 250 file was not a binary package part.
 251
 252 =item B<2>
 253
 254 Fatal or unrecoverable error due to invalid command-line usage,
 255 a file that looked like a package part file but was corrupted, or
 256 interactions with the system, such as accesses to the database,
 257 memory allocations, etc.
 258
 259 =back
 260
 261 =head1 ENVIRONMENT
 262
 263 =over
 264
 265 =item B<DPKG_ROOT>
 266
 267 If set and B<--root> option has not been specified,
 268 it will be used as the filesystem root directory (since dpkg 1.21.10).
 269
 270 =item B<DPKG_ADMINDIR>
 271
 272 If set and the B<--admindir> or B<--root> options have not been specified,
 273 it will be used as the B<dpkg> data directory (since dpkg 1.21.10).
 274
 275 =item B<DPKG_DEBUG>
 276
 277 Sets the debug mask (since dpkg 1.21.10) from an octal value.
 278 The currently accepted flags are described in the B<dpkg --debug> option,
 279 but not all these flags might have an effect on this program.
 280
 281 =item B<DPKG_COLORS>
 282
 283 Sets the color mode (since dpkg 1.18.5).
 284 The currently accepted values are: B<auto> (default), B<always> and
 285 B<never>.
 286
 287 =item B<SOURCE_DATE_EPOCH>
 288
 289 If set, it will be used as the timestamp (as seconds since the epoch) in
 290 the B<deb-split>(5)'s B<ar>(5) container.
 291
 292 =back
 293
 294 =head1 FILES
 295
 296 =over
 297
 298 =item I<%ADMINDIR%/parts>
 299
 300 The default queue directory for part files awaiting automatic
 301 reassembly.
 302
 303 The filenames used in this directory are in a format internal to
 304 B<dpkg-split>
 305 and are unlikely to be useful to other programs, and in any case the
 306 filename format should not be relied upon.
 307
 308 =back
 309
 310 =head1 SECURITY
 311
 312 Examining or joining untrusted split package archives should be considered
 313 a security boundary, and any breakage of that boundary stemming from these
 314 operations should be considered a security vulnerability.
 315 Performing these operations over untrusted data as root is strongly
 316 discouraged.
 317
 318 Auto-accumulating and discarding split package parts are considered
 319 privileged operations that might allow root escalation.
 320 These operations must never be delegated to an untrusted user or be done
 321 on untrusted packages, as that might allow root access to the system.
 322
 323 Splitting package archives should only be performed over trusted data.
 324
 325 =head1 BUGS
 326
 327 Full details of the packages in the queue are impossible to get
 328 without digging into the queue directory yourself.
 329
 330 There is no easy way to test whether a file that may be a binary
 331 package part is one.
 332
 333 =head1 SEE ALSO
 334
 335 B<deb>(5),
 336 B<deb-control>(5),
 337 B<dpkg-deb>(1),
 338 B<dpkg>(1).