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