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%>.
 174
 175 =item B<-S>, B<--partsize> I<kibibytes>
 176
 177 Specifies the maximum part size when splitting, in kibibytes (1024
 178 bytes). The default is 450 KiB.
 179
 180 =item B<-o>, B<--output> I<complete-output>
 181
 182 Specifies the output file name for a reassembly.
 183
 184 This overrides the default for a manual reassembly
 185 (B<--join>)
 186 and is mandatory for an automatic queue-or-reassemble
 187 (B<--auto>).
 188
 189 =item B<-Q>, B<--npquiet>
 190
 191 When doing automatic queue-or-reassembly
 192 B<dpkg-split>
 193 usually prints a message if it is given a
 194 I<part>
 195 that is not a binary package part. This option suppresses this
 196 message, to allow programs such as
 197 B<dpkg>
 198 to cope with both split and unsplit packages without producing
 199 spurious messages.
 200
 201 =item B<--msdos>
 202
 203 Forces the output filenames generated by
 204 B<--split>
 205 to be MSDOS-compatible.
 206
 207 This mangles the prefix - either the default derived from the input
 208 filename or the one supplied as an argument: alphanumerics are
 209 lowercased, plus signs are replaced by
 210 B<x>'s
 211 and all other characters are discarded.
 212
 213 The result is then truncated as much as is necessary, and filenames of
 214 the form
 215 I<prefixN>B<of>I<M>B<.deb>
 216 are generated.
 217
 218 =back
 219
 220 =head1 EXIT STATUS
 221
 222 =over
 223
 224 =item B<0>
 225
 226 The requested split, merge, or other command succeeded.
 227 B<--info>
 228 commands count as successful even if the files are not binary package
 229 parts.
 230
 231 =item B<1>
 232
 233 Only occurs with
 234 B<--auto>
 235 and indicates that the
 236 I<part>
 237 file was not a binary package part.
 238
 239 =item B<2>
 240
 241 Fatal or unrecoverable error due to invalid command-line usage,
 242 a file that looked like a package part file but was corrupted, or
 243 interactions with the system, such as accesses to the database,
 244 memory allocations, etc.
 245
 246 =back
 247
 248 =head1 ENVIRONMENT
 249
 250 =over
 251
 252 =item B<DPKG_COLORS>
 253
 254 Sets the color mode (since dpkg 1.18.5).
 255 The currently accepted values are: B<auto> (default), B<always> and
 256 B<never>.
 257
 258 =item B<SOURCE_DATE_EPOCH>
 259
 260 If set, it will be used as the timestamp (as seconds since the epoch) in
 261 the B<deb-split>(5)'s B<ar>(5) container.
 262
 263 =back
 264
 265 =head1 FILES
 266
 267 =over
 268
 269 =item I<%ADMINDIR%/parts>
 270
 271 The default queue directory for part files awaiting automatic
 272 reassembly.
 273
 274 The filenames used in this directory are in a format internal to
 275 B<dpkg-split>
 276 and are unlikely to be useful to other programs, and in any case the
 277 filename format should not be relied upon.
 278
 279 =back
 280
 281 =head1 BUGS
 282
 283 Full details of the packages in the queue are impossible to get
 284 without digging into the queue directory yourself.
 285
 286 There is no easy way to test whether a file that may be a binary
 287 package part is one.
 288
 289 =head1 SEE ALSO
 290
 291 B<deb>(5),
 292 B<deb-control>(5),
 293 B<dpkg-deb>(1),
 294 B<dpkg>(1).