contrib/libarchive/README.md

4 can read and write streaming archives in a variety of formats.  It
6 command-line tools that use the libarchive library.
10 * http://www.libarchive.org is the home for ongoing
12   and links to the libarchive mailing lists.
14   https://github.com/libarchive/libarchive/issues
16   submit a pull request via GitHub: https://github.com/libarchive/libarchive/pulls
26 * **examples**: Some small example programs that you may find useful.
27 * **examples/minitar**: a compact sample demonstrating use of libarchive.
28 * **contrib**:  Various items sent to me by third parties; please contact the authors with any questions.
36 * **CMakeLists.txt** - input for "cmake" build tool, see INSTALL
37 * **configure** - configuration script, see INSTALL for details.  If your copy of the source lacks a `configure` script, you can try to construct it by running the script in `build/autogen.sh` (or use `cmake`).
40 * `Makefile.am`, `aclocal.m4`, `configure.ac` - used to build this distribution, only needed by maintainers
41 * `Makefile.in`, `config.h.in` - templates used by configure script
46 in the online [libarchive Wiki](https://github.com/libarchive/libarchive/wiki),
49  * bsdtar.1 explains the use of the bsdtar program
50  * bsdcpio.1 explains the use of the bsdcpio program
51  * bsdcat.1 explains the use of the bsdcat program
52  * libarchive.3 gives an overview of the library as a whole
53  * archive_read.3, archive_write.3, archive_write_disk.3, and
54    archive_read_disk.3 provide detailed calling sequences for the read
56  * archive_entry.3 details the "struct archive_entry" utility class
57  * archive_internals.3 provides some insight into libarchive's
58    internal structure and operation.
59  * libarchive-formats.5 documents the file formats supported by the library
60  * cpio.5, mtree.5, and tar.5 provide detailed information about these
62    modern cpio and tar variants.
65 a number of different formats.
67 You should also read the copious comments in `archive.h` and the
68 source code for the sample programs for more details.  Please let us
69 know about any errors or omissions you find.
85   * ZIPX archives (with support for bzip2, ppmd8, lzma and xz compressed entries)
98   * bzip2 compression
109     entries that require pax extensions (for long filenames, ACLs, etc).
127   * bzip2 compression
139 * This is a heavily stream-oriented system.  That means that
141   pass from beginning to end.  For example, this allows
144   written to a network or tape drive.  This also makes
147   archived contents of a users account).
150   of an archive are not directly supported.  For some formats,
151   this is not an issue: For example, tar.gz archives are not
152   designed for random access.  In some other cases, libarchive
155   random access.  Of course, some applications do require true
157   to libarchive.
160   archive formats.  The only requirement is that the format be
162   independent.  There are articles on the libarchive Wiki explaining
163   how to extend libarchive.
165 * On read, compression and format are always detected automatically.
169   any of libarchive's archiving formats.
173   formats.
175 * I've attempted to minimize static link pollution.  If you don't
178   statically-linked programs.  In particular, if you don't explicitly
181   libraries.  This also reduces the size of statically-linked
182   binaries in environments where that matters.
185   it does not define any global variables of its own.  However, some
187   functions.  On those platforms, libarchive will use the non-thread-safe
188   functions.  Patches to improve this are of great interest to us.
191   tree do use `chdir()` to optimize the directory traversals.  This
193   multiple threads.  Of course, those modules are completely
194   optional and you can use the rest of libarchive without them.
196 * The library is _not_ thread aware, however.  It does no locking
197   or thread management of any kind.  If you create a libarchive
199   need to provide your own locking.
201 * On read, the library accepts whatever blocks you hand it.
203   or mmap the entire archive and give it to the library at once.
204   On write, the library always produces correctly-blocked output.
207   open at once.  bsdtar uses this in its "@archive" extension.
209 * The archive itself is read/written using callback functions.
211   write it to a socket, if you wish.  There are some utility
212   functions to provide easy-to-use "open file," etc, capabilities.
217   first writing a temporary file.  You can also read an entry from
218   an archive and write the data directly to a socket.  If you want
220   make this especially easy.
224   appropriate.  It has many advantages over other tar formats
226   current tar implementations.