contrib/libarchive/README

   1 README for libarchive bundle.
   2
   3 Questions?  Issues?
   4    * http://www.libarchive.org is the home for ongoing
   5      libarchive development, including documentation, and
   6      links to the libarchive mailing lists.
   7    * To report an issue, use the issue tracker at
   8      https://github.com/libarchive/libarchive/issues
   9    * To submit an enhancement to libarchive, please submit
  10      a pull request via GitHub.
  11      https://github.com/libarchive/libarchive/pulls
  12
  13 This distribution bundle includes the following components:
  14    * libarchive: a library for reading and writing streaming archives
  15    * tar: the 'bsdtar' program is a full-featured 'tar'
  16           implementation built on libarchive
  17    * cpio: the 'bsdcpio' program is a different interface to
  18           essentially the same functionality
  19    * cat: the 'bsdcat' program is a simple replacement tool for
  20           zcat, bzcat, xzcat, and such
  21    * examples: Some small example programs that you may find useful.
  22    * examples/minitar: a compact sample demonstrating use of libarchive.
  23    * contrib:  Various items sent to me by third parties;
  24           please contact the authors with any questions.
  25
  26 The top-level directory contains the following information files:
  27    * NEWS - highlights of recent changes
  28    * COPYING - what you can do with this
  29    * INSTALL - installation instructions
  30    * README - this file
  31    * configure - configuration script, see INSTALL for details.
  32    * CMakeLists.txt - input for "cmake" build tool, see INSTALL
  33
  34 The following files in the top-level directory are used by the
  35 'configure' script:
  36    * Makefile.am, aclocal.m4, configure.ac
  37        - used to build this distribution, only needed by maintainers
  38    * Makefile.in, config.h.in
  39         - templates used by configure script
  40
  41 Guide to Documentation installed by this system:
  42  * bsdtar.1 explains the use of the bsdtar program
  43  * bsdcpio.1 explains the use of the bsdcpio program
  44  * bsdcat.1 explains the use of the bsdcat program
  45  * libarchive.3 gives an overview of the library as a whole
  46  * archive_read.3, archive_write.3, archive_write_disk.3, and
  47    archive_read_disk.3 provide detailed calling sequences for the read
  48    and write APIs
  49  * archive_entry.3 details the "struct archive_entry" utility class
  50  * archive_internals.3 provides some insight into libarchive's
  51    internal structure and operation.
  52  * libarchive-formats.5 documents the file formats supported by the library
  53  * cpio.5, mtree.5, and tar.5 provide detailed information about these
  54    popular archive formats, including hard-to-find details about
  55    modern cpio and tar variants.
  56 The manual pages above are provided in the 'doc' directory in
  57 a number of different formats.
  58
  59 You should also read the copious comments in "archive.h" and the
  60 source code for the sample programs for more details.  Please let us
  61 know about any errors or omissions you find.
  62
  63 Currently, the library automatically detects and reads the following fomats:
  64   * GNU tar format (including GNU long filenames, long link names, and sparse files)
  65   * Solaris 9 extended tar format (including ACLs)
  66   * Old V7 tar archives
  67   * POSIX ustar
  68   * POSIX pax interchange format
  69   * POSIX octet-oriented cpio
  70   * SVR4 ASCII cpio
  71   * POSIX octet-oriented cpio
  72   * Binary cpio (big-endian or little-endian)
  73   * ISO9660 CD-ROM images (with optional Rockridge or Joliet extensions)
  74   * ZIP archives (with uncompressed or "deflate" compressed entries)
  75   * GNU and BSD 'ar' archives
  76   * 'mtree' format
  77   * 7-Zip archives
  78   * Microsoft CAB format
  79   * LHA and LZH archives
  80   * RAR archives
  81   * XAR archives
  82
  83 The library also detects and handles any of the following before evaluating the archive:
  84   * uuencoded files
  85   * files with RPM wrapper
  86   * gzip compression
  87   * bzip2 compression
  88   * compress/LZW compression
  89   * lzma, lzip, and xz compression
  90   * lz4 compression
  91   * lzop compression
  92
  93 The library can create archives in any of the following formats:
  94   * POSIX ustar
  95   * POSIX pax interchange format
  96   * "restricted" pax format, which will create ustar archives except for
  97     entries that require pax extensions (for long filenames, ACLs, etc).
  98   * Old GNU tar format
  99   * Old V7 tar format
 100   * POSIX octet-oriented cpio
 101   * SVR4 "newc" cpio
 102   * shar archives
 103   * ZIP archives (with uncompressed or "deflate" compressed entries)
 104   * GNU and BSD 'ar' archives
 105   * 'mtree' format
 106   * ISO9660 format
 107   * 7-Zip archives
 108   * XAR archives
 109
 110 When creating archives, the result can be filtered with any of the following:
 111   * uuencode
 112   * gzip compression
 113   * bzip2 compression
 114   * compress/LZW compression
 115   * lzma, lzip, and xz compression
 116   * lz4 compression
 117   * lzop compression
 118
 119 Notes about the library architecture:
 120
 121  * This is a heavily stream-oriented system.  There is no direct
 122    support for in-place modification or random access.
 123
 124  * The library is designed to be extended with new compression and
 125    archive formats.  The only requirement is that the format be
 126    readable or writable as a stream and that each archive entry be
 127    independent.  There are articles on the libarchive Wiki explaining
 128    how to extend libarchive.
 129
 130  * On read, compression and format are always detected automatically.
 131
 132  * I've attempted to minimize static link pollution.  If you don't
 133    explicitly invoke a particular feature (such as support for a
 134    particular compression or format), it won't get pulled in to
 135    statically-linked programs.  In particular, if you don't explicitly
 136    enable a particular compression or decompression support, you won't
 137    need to link against the corresponding compression or decompression
 138    libraries.  This also reduces the size of statically-linked
 139    binaries in environments where that matters.
 140
 141  * On read, the library accepts whatever blocks you hand it.
 142    Your read callback is free to pass the library a byte at a time
 143    or mmap the entire archive and give it to the library at once.
 144    On write, the library always produces correctly-blocked output.
 145
 146  * The object-style approach allows you to have multiple archive streams
 147    open at once.  bsdtar uses this in its "@archive" extension.
 148
 149  * The archive itself is read/written using callback functions.
 150    You can read an archive directly from an in-memory buffer or
 151    write it to a socket, if you wish.  There are some utility
 152    functions to provide easy-to-use "open file," etc, capabilities.
 153
 154  * The read/write APIs are designed to allow individual entries
 155    to be read or written to any data source:  You can create
 156    a block of data in memory and add it to a tar archive without
 157    first writing a temporary file.  You can also read an entry from
 158    an archive and write the data directly to a socket.  If you want
 159    to read/write entries to disk, there are convenience functions to
 160    make this especially easy.
 161
 162  * Note: "pax interchange format" is really an extended tar format,
 163    despite what the name says.