156 lines
6.4 KiB
Text
156 lines
6.4 KiB
Text
|
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
|
||
|
|
http://code.google.com/p/libarchive/issues/list
|
||
|
|
* 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'
|
||
|
|
replacement built on libarchive
|
||
|
|
* cpio: the 'bsdcpio' program is a different interface to
|
||
|
|
essentially the same functionality
|
||
|
|
* 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
|
||
|
|
* 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
|
||
|
|
|
||
|
|
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
|
||
|
|
* 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
|
||
|
|
|
||
|
|
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.
|
||
|
|
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.
|