contrib/libarchive/libarchive/libarchive-formats.5

   1 .\" Copyright (c) 2003-2009 Tim Kientzle
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd March 18, 2012
  28 .Dt LIBARCHIVE-FORMATS 5
  29 .Os
  30 .Sh NAME
  31 .Nm libarchive-formats
  32 .Nd archive formats supported by the libarchive library
  33 .Sh DESCRIPTION
  34 The
  35 .Xr libarchive 3
  36 library reads and writes a variety of streaming archive formats.
  37 Generally speaking, all of these archive formats consist of a series of
  38 .Dq entries .
  39 Each entry stores a single file system object, such as a file, directory,
  40 or symbolic link.
  41 .Pp
  42 The following provides a brief description of each format supported
  43 by libarchive, with some information about recognized extensions or
  44 limitations of the current library support.
  45 Note that just because a format is supported by libarchive does not
  46 imply that a program that uses libarchive will support that format.
  47 Applications that use libarchive specify which formats they wish
  48 to support, though many programs do use libarchive convenience
  49 functions to enable all supported formats.
  50 .Ss Tar Formats
  51 The
  52 .Xr libarchive 3
  53 library can read most tar archives.
  54 It can write POSIX-standard
  55 .Dq ustar
  56 and
  57 .Dq pax interchange
  58 formats and a subset of the legacy GNU tar format.
  59 .Pp
  60 All tar formats store each entry in one or more 512-byte records.
  61 The first record is used for file metadata, including filename,
  62 timestamp, and mode information, and the file data is stored in
  63 subsequent records.
  64 Later variants have extended this by either appropriating undefined
  65 areas of the header record, extending the header to multiple records,
  66 or by storing special entries that modify the interpretation of
  67 subsequent entries.
  68 .Pp
  69 .Bl -tag -width indent
  70 .It Cm gnutar
  71 The
  72 .Xr libarchive 3
  73 library can read most GNU-format tar archives.
  74 It currently supports the most popular GNU extensions, including
  75 modern long filename and linkname support, as well as atime and ctime data.
  76 The libarchive library does not support multi-volume
  77 archives, nor the old GNU long filename format.
  78 It can read GNU sparse file entries, including the new POSIX-based
  79 formats.
  80 .Pp
  81 The
  82 .Xr libarchive 3
  83 library can write GNU tar format, including long filename
  84 and linkname support, as well as atime and ctime data.
  85 .It Cm pax
  86 The
  87 .Xr libarchive 3
  88 library can read and write POSIX-compliant pax interchange format
  89 archives.
  90 Pax interchange format archives are an extension of the older ustar
  91 format that adds a separate entry with additional attributes stored
  92 as key/value pairs immediately before each regular entry.
  93 The presence of these additional entries is the only difference between
  94 pax interchange format and the older ustar format.
  95 The extended attributes are of unlimited length and are stored
  96 as UTF-8 Unicode strings.
  97 Keywords defined in the standard are in all lowercase; vendors are allowed
  98 to define custom keys by preceding them with the vendor name in all uppercase.
  99 When writing pax archives, libarchive uses many of the SCHILY keys
 100 defined by Joerg Schilling's
 101 .Dq star
 102 archiver and a few LIBARCHIVE keys.
 103 The libarchive library can read most of the SCHILY keys
 104 and most of the GNU keys introduced by GNU tar.
 105 It silently ignores any keywords that it does not understand.
 106 .Pp
 107 The pax interchange format converts filenames to Unicode
 108 and stores them using the UTF-8 encoding.
 109 Prior to libarchive 3.0, libarchive erroneously assumed
 110 that the system wide-character routines natively supported
 111 Unicode.
 112 This caused it to mis-handle non-ASCII filenames on systems
 113 that did not satisfy this assumption.
 114 .It Cm restricted pax
 115 The libarchive library can also write pax archives in which it
 116 attempts to suppress the extended attributes entry whenever
 117 possible.
 118 The result will be identical to a ustar archive unless the
 119 extended attributes entry is required to store a long file
 120 name, long linkname, extended ACL, file flags, or if any of the standard
 121 ustar data (user name, group name, UID, GID, etc) cannot be fully
 122 represented in the ustar header.
 123 In all cases, the result can be dearchived by any program that
 124 can read POSIX-compliant pax interchange format archives.
 125 Programs that correctly read ustar format (see below) will also be
 126 able to read this format; any extended attributes will be extracted as
 127 separate files stored in
 128 .Pa PaxHeader
 129 directories.
 130 .It Cm ustar
 131 The libarchive library can both read and write this format.
 132 This format has the following limitations:
 133 .Bl -bullet -compact
 134 .It
 135 Device major and minor numbers are limited to 21 bits.
 136 Nodes with larger numbers will not be added to the archive.
 137 .It
 138 Path names in the archive are limited to 255 bytes.
 139 (Shorter if there is no / character in exactly the right place.)
 140 .It
 141 Symbolic links and hard links are stored in the archive with
 142 the name of the referenced file.
 143 This name is limited to 100 bytes.
 144 .It
 145 Extended attributes, file flags, and other extended
 146 security information cannot be stored.
 147 .It
 148 Archive entries are limited to 8 gigabytes in size.
 149 .El
 150 Note that the pax interchange format has none of these restrictions.
 151 The ustar format is old and widely supported.
 152 It is recommended when compatibility is the primary concern.
 153 .El
 154 .Pp
 155 The libarchive library also reads a variety of commonly-used extensions to
 156 the basic tar format.
 157 These extensions are recognized automatically whenever they appear.
 158 .Bl -tag -width indent
 159 .It Numeric extensions.
 160 The POSIX standards require fixed-length numeric fields to be written with
 161 some character position reserved for terminators.
 162 Libarchive allows these fields to be written without terminator characters.
 163 This extends the allowable range; in particular, ustar archives with this
 164 extension can support entries up to 64 gigabytes in size.
 165 Libarchive also recognizes base-256 values in most numeric fields.
 166 This essentially removes all limitations on file size, modification time,
 167 and device numbers.
 168 .It Solaris extensions
 169 Libarchive recognizes ACL and extended attribute records written
 170 by Solaris tar.
 171 Currently, libarchive only has support for old-style ACLs; the
 172 newer NFSv4 ACLs are recognized but discarded.
 173 .El
 174 .Pp
 175 The first tar program appeared in Seventh Edition Unix in 1979.
 176 The first official standard for the tar file format was the
 177 .Dq ustar
 178 (Unix Standard Tar) format defined by POSIX in 1988.
 179 POSIX.1-2001 extended the ustar format to create the
 180 .Dq pax interchange
 181 format.
 182 .Ss Cpio Formats
 183 The libarchive library can read a number of common cpio variants and can write
 184 .Dq odc
 185 and
 186 .Dq newc
 187 format archives.
 188 A cpio archive stores each entry as a fixed-size header followed
 189 by a variable-length filename and variable-length data.
 190 Unlike the tar format, the cpio format does only minimal padding
 191 of the header or file data.
 192 There are several cpio variants, which differ primarily in
 193 how they store the initial header: some store the values as
 194 octal or hexadecimal numbers in ASCII, others as binary values of
 195 varying byte order and length.
 196 .Bl -tag -width indent
 197 .It Cm binary
 198 The libarchive library transparently reads both big-endian and little-endian
 199 variants of the original binary cpio format.
 200 This format used 32-bit binary values for file size and mtime,
 201 and 16-bit binary values for the other fields.
 202 .It Cm odc
 203 The libarchive library can both read and write this
 204 POSIX-standard format, which is officially known as the
 205 .Dq cpio interchange format
 206 or the
 207 .Dq octet-oriented cpio archive format
 208 and sometimes unofficially referred to as the
 209 .Dq old character format .
 210 This format stores the header contents as octal values in ASCII.
 211 It is standard, portable, and immune from byte-order confusion.
 212 File sizes and mtime are limited to 33 bits (8GB file size),
 213 other fields are limited to 18 bits.
 214 .It Cm SVR4
 215 The libarchive library can read both CRC and non-CRC variants of
 216 this format.
 217 The SVR4 format uses eight-digit hexadecimal values for
 218 all header fields.
 219 This limits file size to 4GB, and also limits the mtime and
 220 other fields to 32 bits.
 221 The SVR4 format can optionally include a CRC of the file
 222 contents, although libarchive does not currently verify this CRC.
 223 .El
 224 .Pp
 225 Cpio first appeared in PWB/UNIX 1.0, which was released within
 226 AT&T in 1977.
 227 PWB/UNIX 1.0 formed the basis of System III Unix, released outside
 228 of AT&T in 1981.
 229 This makes cpio older than tar, although cpio was not included
 230 in Version 7 AT&T Unix.
 231 As a result, the tar command became much better known in universities
 232 and research groups that used Version 7.
 233 The combination of the
 234 .Nm find
 235 and
 236 .Nm cpio
 237 utilities provided very precise control over file selection.
 238 Unfortunately, the format has many limitations that make it unsuitable
 239 for widespread use.
 240 Only the POSIX format permits files over 4GB, and its 18-bit
 241 limit for most other fields makes it unsuitable for modern systems.
 242 In addition, cpio formats only store numeric UID/GID values (not
 243 usernames and group names), which can make it very difficult to correctly
 244 transfer archives across systems with dissimilar user numbering.
 245 .Ss Shar Formats
 246 A
 247 .Dq shell archive
 248 is a shell script that, when executed on a POSIX-compliant
 249 system, will recreate a collection of file system objects.
 250 The libarchive library can write two different kinds of shar archives:
 251 .Bl -tag -width indent
 252 .It Cm shar
 253 The traditional shar format uses a limited set of POSIX
 254 commands, including
 255 .Xr echo 1 ,
 256 .Xr mkdir 1 ,
 257 and
 258 .Xr sed 1 .
 259 It is suitable for portably archiving small collections of plain text files.
 260 However, it is not generally well-suited for large archives
 261 (many implementations of
 262 .Xr sh 1
 263 have limits on the size of a script) nor should it be used with non-text files.
 264 .It Cm shardump
 265 This format is similar to shar but encodes files using
 266 .Xr uuencode 1
 267 so that the result will be a plain text file regardless of the file contents.
 268 It also includes additional shell commands that attempt to reproduce as
 269 many file attributes as possible, including owner, mode, and flags.
 270 The additional commands used to restore file attributes make
 271 shardump archives less portable than plain shar archives.
 272 .El
 273 .Ss ISO9660 format
 274 Libarchive can read and extract from files containing ISO9660-compliant
 275 CDROM images.
 276 In many cases, this can remove the need to burn a physical CDROM
 277 just in order to read the files contained in an ISO9660 image.
 278 It also avoids security and complexity issues that come with
 279 virtual mounts and loopback devices.
 280 Libarchive supports the most common Rockridge extensions and has partial
 281 support for Joliet extensions.
 282 If both extensions are present, the Joliet extensions will be
 283 used and the Rockridge extensions will be ignored.
 284 In particular, this can create problems with hardlinks and symlinks,
 285 which are supported by Rockridge but not by Joliet.
 286 .Pp
 287 Libarchive reads ISO9660 images using a streaming strategy.
 288 This allows it to read compressed images directly
 289 (decompressing on the fly) and allows it to read images
 290 directly from network sockets, pipes, and other non-seekable
 291 data sources.
 292 This strategy works well for optimized ISO9660 images created
 293 by many popular programs.
 294 Such programs collect all directory information at the beginning
 295 of the ISO9660 image so it can be read from a physical disk
 296 with a minimum of seeking.
 297 However, not all ISO9660 images can be read in this fashion.
 298 .Pp
 299 Libarchive can also write ISO9660 images.
 300 Such images are fully optimized with the directory information
 301 preceding all file data.
 302 This is done by storing all file data to a temporary file
 303 while collecting directory information in memory.
 304 When the image is finished, libarchive writes out the
 305 directory structure followed by the file data.
 306 The location used for the temporary file can be changed
 307 by the usual environment variables.
 308 .Ss Zip format
 309 Libarchive can read and write zip format archives that have
 310 uncompressed entries and entries compressed with the
 311 .Dq deflate
 312 algorithm.
 313 Other zip compression algorithms are not supported.
 314 It can extract jar archives, archives that use Zip64 extensions and
 315 self-extracting zip archives.
 316 Libarchive can use either of two different strategies for
 317 reading Zip archives:
 318 a streaming strategy which is fast and can handle extremely
 319 large archives, and a seeking strategy which can correctly
 320 process self-extracting Zip archives and archives with
 321 deleted members or other in-place modifications.
 322 .Pp
 323 The streaming reader processes Zip archives as they are read.
 324 It can read archives of arbitrary size from tape or
 325 network sockets, and can decode Zip archives that have
 326 been separately compressed or encoded.
 327 However, self-extracting Zip archives and archives with
 328 certain types of modifications cannot be correctly
 329 handled.
 330 Such archives require that the reader first process the
 331 Central Directory, which is ordinarily located
 332 at the end of a Zip archive and is thus inaccessible
 333 to the streaming reader.
 334 If the program using libarchive has enabled seek support, then
 335 libarchive will use this to processes the central directory first.
 336 .Pp
 337 In particular, the seeking reader must be used to
 338 correctly handle self-extracting archives.
 339 Such archives consist of a program followed by a regular
 340 Zip archive.
 341 The streaming reader cannot parse the initial program
 342 portion, but the seeking reader starts by reading the
 343 Central Directory from the end of the archive.
 344 Similarly, Zip archives that have been modified in-place
 345 can have deleted entries or other garbage data that
 346 can only be accurately detected by first reading the
 347 Central Directory.
 348 .Ss Archive (library) file format
 349 The Unix archive format (commonly created by the
 350 .Xr ar 1
 351 archiver) is a general-purpose format which is
 352 used almost exclusively for object files to be
 353 read by the link editor
 354 .Xr ld 1 .
 355 The ar format has never been standardised.
 356 There are two common variants:
 357 the GNU format derived from SVR4,
 358 and the BSD format, which first appeared in 4.4BSD.
 359 The two differ primarily in their handling of filenames
 360 longer than 15 characters:
 361 the GNU/SVR4 variant writes a filename table at the beginning of the archive;
 362 the BSD format stores each long filename in an extension
 363 area adjacent to the entry.
 364 Libarchive can read both extensions,
 365 including archives that may include both types of long filenames.
 366 Programs using libarchive can write GNU/SVR4 format
 367 if they provide a filename table to be written into
 368 the archive before any of the entries.
 369 Any entries whose names are not in the filename table
 370 will be written using BSD-style long filenames.
 371 This can cause problems for programs such as
 372 GNU ld that do not support the BSD-style long filenames.
 373 .Ss mtree
 374 Libarchive can read and write files in
 375 .Xr mtree 5
 376 format.
 377 This format is not a true archive format, but rather a textual description
 378 of a file hierarchy in which each line specifies the name of a file and
 379 provides specific metadata about that file.
 380 Libarchive can read all of the keywords supported by both
 381 the NetBSD and FreeBSD versions of
 382 .Xr mtree 1 ,
 383 although many of the keywords cannot currently be stored in an
 384 .Tn archive_entry
 385 object.
 386 When writing, libarchive supports use of the
 387 .Xr archive_write_set_options 3
 388 interface to specify which keywords should be included in the
 389 output.
 390 If libarchive was compiled with access to suitable
 391 cryptographic libraries (such as the OpenSSL libraries),
 392 it can compute hash entries such as
 393 .Cm sha512
 394 or
 395 .Cm md5
 396 from file data being written to the mtree writer.
 397 .Pp
 398 When reading an mtree file, libarchive will locate the corresponding
 399 files on disk using the
 400 .Cm contents
 401 keyword if present or the regular filename.
 402 If it can locate and open the file on disk, it will use that
 403 to fill in any metadata that is missing from the mtree file
 404 and will read the file contents and return those to the program
 405 using libarchive.
 406 If it cannot locate and open the file on disk, libarchive
 407 will return an error for any attempt to read the entry
 408 body.
 409 .Ss LHA
 410 XXX Information about libarchive's LHA support XXX
 411 .Ss CAB
 412 XXX Information about libarchive's CAB support XXX
 413 .Ss XAR
 414 XXX Information about libarchive's XAR support XXX
 415 .Ss RAR
 416 Libarchive has limited support for reading RAR format archives.
 417 Currently, libarchive can read RARv3 format archives
 418 which have been either created uncompressed, or compressed using
 419 any of the compression methods supported by the RARv3 format.
 420 Libarchive can also read self-extracting RAR archives.
 421 .Sh SEE ALSO
 422 .Xr ar 1 ,
 423 .Xr cpio 1 ,
 424 .Xr mkisofs 1 ,
 425 .Xr shar 1 ,
 426 .Xr tar 1 ,
 427 .Xr zip 1 ,
 428 .Xr zlib 3 ,
 429 .Xr cpio 5 ,
 430 .Xr mtree 5 ,
 431 .Xr tar 5