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