README revision 238856
1228753SmmREADME for libarchive bundle. 2228753Smm 3228753SmmQuestions? Issues? 4238856Smm * http://libarchive.github.com/ is the home for ongoing 5238856Smm libarchive development, including documentation, and 6238856Smm links to the libarchive mailing lists. 7238856Smm * To report an issue, use the issue tracker at 8238856Smm http://code.google.com/p/libarchive/issues/list 9238856Smm * To submit an enhancement to libarchive, please submit 10238856Smm a pull request via GitHub. 11238856Smm https://github.com/libarchive/libarchive/pulls 12228753Smm 13228753SmmThis distribution bundle includes the following components: 14228753Smm * libarchive: a library for reading and writing streaming archives 15228753Smm * tar: the 'bsdtar' program is a full-featured 'tar' 16228753Smm replacement built on libarchive 17228753Smm * cpio: the 'bsdcpio' program is a different interface to 18228753Smm essentially the same functionality 19228753Smm * examples: Some small example programs that you may find useful. 20228753Smm * examples/minitar: a compact sample demonstrating use of libarchive. 21228753Smm * contrib: Various items sent to me by third parties; 22228753Smm please contact the authors with any questions. 23228753Smm 24228753SmmThe top-level directory contains the following information files: 25228753Smm * NEWS - highlights of recent changes 26228753Smm * COPYING - what you can do with this 27228753Smm * INSTALL - installation instructions 28228753Smm * README - this file 29228753Smm * configure - configuration script, see INSTALL for details. 30228753Smm * CMakeLists.txt - input for "cmake" build tool, see INSTALL 31228753Smm 32228753SmmThe following files in the top-level directory are used by the 33228753Smm'configure' script: 34228753Smm * Makefile.am, aclocal.m4, configure.ac 35228753Smm - used to build this distribution, only needed by maintainers 36228753Smm * Makefile.in, config.h.in 37228753Smm - templates used by configure script 38228753Smm 39228753SmmGuide to Documentation installed by this system: 40228753Smm * bsdtar.1 explains the use of the bsdtar program 41228753Smm * bsdcpio.1 explains the use of the bsdcpio program 42228753Smm * libarchive.3 gives an overview of the library as a whole 43228753Smm * archive_read.3, archive_write.3, archive_write_disk.3, and 44228753Smm archive_read_disk.3 provide detailed calling sequences for the read 45228753Smm and write APIs 46228753Smm * archive_entry.3 details the "struct archive_entry" utility class 47228753Smm * archive_internals.3 provides some insight into libarchive's 48228753Smm internal structure and operation. 49228753Smm * libarchive-formats.5 documents the file formats supported by the library 50228753Smm * cpio.5, mtree.5, and tar.5 provide detailed information about these 51228753Smm popular archive formats, including hard-to-find details about 52228753Smm modern cpio and tar variants. 53228753SmmThe manual pages above are provided in the 'doc' directory in 54228753Smma number of different formats. 55228753Smm 56228753SmmYou should also read the copious comments in "archive.h" and the 57232153Smmsource code for the sample programs for more details. Please let us 58228753Smmknow about any errors or omissions you find. 59228753Smm 60232153SmmCurrently, the library automatically detects and reads the following fomats: 61232153Smm * GNU tar format (including GNU long filenames, long link names, and sparse files) 62228753Smm * Solaris 9 extended tar format (including ACLs) 63228753Smm * Old V7 tar archives 64228753Smm * POSIX ustar 65228753Smm * POSIX pax interchange format 66228753Smm * POSIX octet-oriented cpio 67228753Smm * SVR4 ASCII cpio 68228753Smm * POSIX octet-oriented cpio 69228753Smm * Binary cpio (big-endian or little-endian) 70228753Smm * ISO9660 CD-ROM images (with optional Rockridge or Joliet extensions) 71228753Smm * ZIP archives (with uncompressed or "deflate" compressed entries) 72228753Smm * GNU and BSD 'ar' archives 73228753Smm * 'mtree' format 74238856Smm * 7-Zip archives 75232153Smm * Microsoft CAB format 76232153Smm * LHA and LZH archives 77232153Smm * RAR archives 78232153Smm * XAR archives 79228753Smm 80232153SmmThe library also detects and handles any of the following before evaluating the archive: 81232153Smm * uuencoded files 82232153Smm * files with RPM wrapper 83228753Smm * gzip compression 84228753Smm * bzip2 compression 85228753Smm * compress/LZW compression 86232153Smm * lzma, lzip, and xz compression 87232153Smm 88232153SmmThe library can create archives in any of the following formats: 89228753Smm * POSIX ustar 90228753Smm * POSIX pax interchange format 91228753Smm * "restricted" pax format, which will create ustar archives except for 92228753Smm entries that require pax extensions (for long filenames, ACLs, etc). 93232153Smm * Old GNU tar format 94228753Smm * POSIX octet-oriented cpio 95228753Smm * SVR4 "newc" cpio 96228753Smm * shar archives 97228753Smm * ZIP archives (with uncompressed or "deflate" compressed entries) 98228753Smm * GNU and BSD 'ar' archives 99228753Smm * 'mtree' format 100232153Smm * ISO9660 format 101238856Smm * 7-Zip archives 102232153Smm * XAR archives 103228753Smm 104232153SmmWhen creating archives, the result can be filtered with any of the following: 105232153Smm * uuencode 106232153Smm * gzip compression 107232153Smm * bzip2 compression 108232153Smm * compress/LZW compression 109232153Smm * lzma, lzip, and xz compression 110232153Smm 111228753SmmNotes about the library architecture: 112228753Smm 113228753Smm * This is a heavily stream-oriented system. There is no direct 114228753Smm support for in-place modification or random access. 115228753Smm 116228753Smm * The library is designed to be extended with new compression and 117228753Smm archive formats. The only requirement is that the format be 118228753Smm readable or writable as a stream and that each archive entry be 119228753Smm independent. There are articles on the libarchive Wiki explaining 120228753Smm how to extend libarchive. 121228753Smm 122228753Smm * On read, compression and format are always detected automatically. 123228753Smm 124228753Smm * I've attempted to minimize static link pollution. If you don't 125228753Smm explicitly invoke a particular feature (such as support for a 126228753Smm particular compression or format), it won't get pulled in. 127228753Smm In particular, if you don't explicitly enable a particular 128228753Smm compression or decompression support, you won't need to link 129228753Smm against the corresponding compression or decompression libraries. 130228753Smm This also reduces the size of statically-linked binaries in 131228753Smm environments where that matters. 132228753Smm 133228753Smm * On read, the library accepts whatever blocks you hand it. 134228753Smm Your read callback is free to pass the library a byte at a time 135228753Smm or mmap the entire archive and give it to the library at once. 136228753Smm On write, the library always produces correctly-blocked output. 137228753Smm 138228753Smm * The object-style approach allows you to have multiple archive streams 139228753Smm open at once. bsdtar uses this in its "@archive" extension. 140228753Smm 141228753Smm * The archive itself is read/written using callback functions. 142228753Smm You can read an archive directly from an in-memory buffer or 143228753Smm write it to a socket, if you wish. There are some utility 144228753Smm functions to provide easy-to-use "open file," etc, capabilities. 145228753Smm 146228753Smm * The read/write APIs are designed to allow individual entries 147228753Smm to be read or written to any data source: You can create 148228753Smm a block of data in memory and add it to a tar archive without 149228753Smm first writing a temporary file. You can also read an entry from 150228753Smm an archive and write the data directly to a socket. If you want 151228753Smm to read/write entries to disk, there are convenience functions to 152228753Smm make this especially easy. 153228753Smm 154228753Smm * Note: "pax interchange format" is really an extended tar format, 155228753Smm despite what the name says. 156