-README for libarchive bundle.
-
-Questions? Issues?
- * http://www.libarchive.org is the home for ongoing
- libarchive development, including documentation, and
- links to the libarchive mailing lists.
- * To report an issue, use the issue tracker at
- https://github.com/libarchive/libarchive/issues
- * To submit an enhancement to libarchive, please submit
- a pull request via GitHub.
- https://github.com/libarchive/libarchive/pulls
-
-This distribution bundle includes the following components:
- * libarchive: a library for reading and writing streaming archives
- * tar: the 'bsdtar' program is a full-featured 'tar'
- implementation built on libarchive
- * cpio: the 'bsdcpio' program is a different interface to
- essentially the same functionality
- * cat: the 'bsdcat' program is a simple replacement tool for
- zcat, bzcat, xzcat, and such
- * examples: Some small example programs that you may find useful.
- * examples/minitar: a compact sample demonstrating use of libarchive.
- * contrib: Various items sent to me by third parties;
- please contact the authors with any questions.
-
-The top-level directory contains the following information files:
- * NEWS - highlights of recent changes
- * COPYING - what you can do with this
- * INSTALL - installation instructions
- * README - this file
- * configure - configuration script, see INSTALL for details.
- * CMakeLists.txt - input for "cmake" build tool, see INSTALL
-
-The following files in the top-level directory are used by the
-'configure' script:
- * Makefile.am, aclocal.m4, configure.ac
- - used to build this distribution, only needed by maintainers
- * Makefile.in, config.h.in
- - templates used by configure script
-
-Guide to Documentation installed by this system:
- * bsdtar.1 explains the use of the bsdtar program
- * bsdcpio.1 explains the use of the bsdcpio program
- * bsdcat.1 explains the use of the bsdcat program
- * libarchive.3 gives an overview of the library as a whole
- * archive_read.3, archive_write.3, archive_write_disk.3, and
- archive_read_disk.3 provide detailed calling sequences for the read
- and write APIs
- * archive_entry.3 details the "struct archive_entry" utility class
- * archive_internals.3 provides some insight into libarchive's
- internal structure and operation.
- * libarchive-formats.5 documents the file formats supported by the library
- * cpio.5, mtree.5, and tar.5 provide detailed information about these
- popular archive formats, including hard-to-find details about
- modern cpio and tar variants.
-The manual pages above are provided in the 'doc' directory in
-a number of different formats.
-
-You should also read the copious comments in "archive.h" and the
-source code for the sample programs for more details. Please let us
-know about any errors or omissions you find.
-
-Currently, the library automatically detects and reads the following fomats:
- * GNU tar format (including GNU long filenames, long link names, and sparse files)
- * Solaris 9 extended tar format (including ACLs)
- * Old V7 tar archives
- * POSIX ustar
- * POSIX pax interchange format
- * POSIX octet-oriented cpio
- * SVR4 ASCII cpio
- * POSIX octet-oriented cpio
- * Binary cpio (big-endian or little-endian)
- * ISO9660 CD-ROM images (with optional Rockridge or Joliet extensions)
- * ZIP archives (with uncompressed or "deflate" compressed entries)
- * GNU and BSD 'ar' archives
- * 'mtree' format
- * 7-Zip archives
- * Microsoft CAB format
- * LHA and LZH archives
- * RAR archives
- * XAR archives
-
-The library also detects and handles any of the following before evaluating the archive:
- * uuencoded files
- * files with RPM wrapper
- * gzip compression
- * bzip2 compression
- * compress/LZW compression
- * lzma, lzip, and xz compression
- * lz4 compression
- * lzop compression
-
-The library can create archives in any of the following formats:
- * POSIX ustar
- * POSIX pax interchange format
- * "restricted" pax format, which will create ustar archives except for
- entries that require pax extensions (for long filenames, ACLs, etc).
- * Old GNU tar format
- * Old V7 tar format
- * POSIX octet-oriented cpio
- * SVR4 "newc" cpio
- * shar archives
- * ZIP archives (with uncompressed or "deflate" compressed entries)
- * GNU and BSD 'ar' archives
- * 'mtree' format
- * ISO9660 format
- * 7-Zip archives
- * XAR archives
-
-When creating archives, the result can be filtered with any of the following:
- * uuencode
- * gzip compression
- * bzip2 compression
- * compress/LZW compression
- * lzma, lzip, and xz compression
- * lz4 compression
- * lzop compression
-
-Notes about the library architecture:
-
- * This is a heavily stream-oriented system. There is no direct
- support for in-place modification or random access.
-
- * The library is designed to be extended with new compression and
- archive formats. The only requirement is that the format be
- readable or writable as a stream and that each archive entry be
- independent. There are articles on the libarchive Wiki explaining
- how to extend libarchive.
-
- * On read, compression and format are always detected automatically.
-
- * I've attempted to minimize static link pollution. If you don't
- explicitly invoke a particular feature (such as support for a
- particular compression or format), it won't get pulled in to
- statically-linked programs. In particular, if you don't explicitly
- enable a particular compression or decompression support, you won't
- need to link against the corresponding compression or decompression
- libraries. This also reduces the size of statically-linked
- binaries in environments where that matters.
-
- * On read, the library accepts whatever blocks you hand it.
- Your read callback is free to pass the library a byte at a time
- or mmap the entire archive and give it to the library at once.
- On write, the library always produces correctly-blocked output.
-
- * The object-style approach allows you to have multiple archive streams
- open at once. bsdtar uses this in its "@archive" extension.
-
- * The archive itself is read/written using callback functions.
- You can read an archive directly from an in-memory buffer or
- write it to a socket, if you wish. There are some utility
- functions to provide easy-to-use "open file," etc, capabilities.
-
- * The read/write APIs are designed to allow individual entries
- to be read or written to any data source: You can create
- a block of data in memory and add it to a tar archive without
- first writing a temporary file. You can also read an entry from
- an archive and write the data directly to a socket. If you want
- to read/write entries to disk, there are convenience functions to
- make this especially easy.
-
- * Note: "pax interchange format" is really an extended tar format,
- despite what the name says.