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