LIBARCHIVE_INTERNALS(3) Library Functions Manual LIBARCHIVE_INTERNALS(3)
NAME
libarchive_internals — description of libarchive internal interfaces
OVERVIEW
The libarchive library provides a flexible interface for reading and writing streaming archive files such as tar and cpio. Internally, it follows a modular layered design that should make it easy to add new archive and compression formats.
GENERAL ARCHITECTURE
Externally, libarchive exposes most operations through an opaque, object-style interface. The archive_entry(3) objects store information about a single filesystem object. The rest of the library provides facilities to write archive_entry(3) objects to archive files, read them from archive files, and write them to disk. (There are plans to add a facility to read archive_entry(3) objects from disk as well.)
The read and write APIs each have four layers: a public API layer, a format layer that understands the archive file format, a compression layer, and an I/O layer. The I/O layer is completely exposed to clients who can replace it entirely with their own functions.
In order to provide as much consistency as possible for clients, some public functions are virtualized. Eventually, it should be possible for clients to open an archive or disk writer, and then use a single set of code to select and write entries, regardless of the target.
READ ARCHITECTURE
From the outside, clients use the archive_read(3) API to manipulate an archive object to read entries and bodies from an archive stream. Internally, the archive object is cast to an archive_read object, which holds all read-specific data. The API has four layers: The lowest layer is the I/O layer. This layer can be overridden by clients, but most clients use the packaged I/O callbacks provided, for example, by archive_read_open_memory(3), and archive_read_open_fd(3). The compression layer calls the I/O layer to read bytes and decompresses them for the format layer. The format layer unpacks a stream of uncompressed bytes and creates archive_entry objects from the incoming data. The API layer tracks overall state (for example, it prevents clients from reading data before reading a header) and invokes the format and compression layer operations through registered function pointers. In particular, the API layer drives the format-detection process: When opening the archive, it reads an initial block of data and offers it to each registered compression handler. The one with the highest bid is initialized with the first block. Similarly, the format handlers are polled to see which handler is the best for each archive. (Prior to 2.4.0, the format bidders were invoked for each entry, but this design hindered error recovery.)
I/O Layer and Client Callbacks
The read API goes to some lengths to be nice to clients. As a result, there are few restrictions on the behavior of the client callbacks.
The client read callback is expected to provide a block of data on each call. A zero-length return does indicate end of file, but otherwise blocks may be as small as one byte or as large as the entire file. In particular, blocks may be of different sizes.
The client skip callback returns the number of bytes actually skipped, which may be much smaller than the skip requested. The only requirement is that the skip not be larger. In particular, clients are allowed to return zero for any skip that they don’t want to handle. The skip callback must never be invoked with a negative value.
Keep in mind that not all clients are reading from disk: clients reading from networks may provide different-sized blocks on every request and cannot skip at all; advanced clients may use mmap(2) to read the entire file into memory at once and return the entire file to libarchive as a single block; other clients may begin asynchronous I/O operations for the next block on each request.
Decompression Layer
The decompression layer not only handles decompression, it also buffers data so that the format handlers see a much nicer I/O model. The decompression API is a two stage peek/consume model. A read_ahead request specifies a minimum read amount; the decompression layer must provide a pointer to at least that much data. If more data is immediately available, it should return more: the format layer handles bulk data reads by asking for a minimum of one byte and then copying as much data as is available.
A subsequent call to the consume() function advances the read pointer. Note that data returned from a read_ahead() call is guaranteed to remain in place until the next call to read_ahead(). Intervening calls to consume() should not cause the data to move.
Skip requests must always be handled exactly. Decompression handlers that cannot seek forward should not register a skip handler; the API layer fills in a generic skip handler that reads and discards data.
A decompression handler has a specific lifecycle:
Registration/Configuration
When the client invokes the public support function, the decompression handler invokes the internal __archive_read_register_compression() function to provide bid and initialization functions. This function returns NULL on error or else a pointer to a struct decompressor_t. This structure contains a void * config slot that can be used for storing any customization information.
Bid
The bid function is invoked with a pointer and size of a block of data. The decompressor can access its config data through the decompressor element of the archive_read object. The bid function is otherwise stateless. In particular, it must not perform any I/O operations.
The value returned by the bid function indicates its suitability for handling this data stream. A bid of zero will ensure that this decompressor is never invoked. Return zero if magic number checks fail. Otherwise, your initial implementation should return the number of bits actually checked. For example, if you verify two full bytes and three bits of another byte, bid 19. Note that the initial block may be very short; be careful to only inspect the data you are given. (The current decompressors require two bytes for correct bidding.)
Initialize
The winning bidder will have its init function called. This function should initialize the remaining slots of the struct decompressor_t object pointed to by the decompressor element of the archive_read object. In particular, it should allocate any working data it needs in the data slot of that structure. The init function is called with the block of data that was used for tasting. At this point, the decompressor is responsible for all I/O requests to the client callbacks. The decompressor is free to read more data as and when necessary.
Satisfy I/O requests
The format handler will invoke the read_ahead, consume, and skip functions as needed.
Finish
The finish method is called only once when the archive is closed. It should release anything stored in the data and config slots of the decompressor object. It should not invoke the client close callback.
Format Layer
The read formats have a similar lifecycle to the decompression handlers:
Registration
Allocate your private data and initialize your pointers.
Bid
Formats bid by invoking the read_ahead() decompression method but not calling the consume() method. This allows each bidder to look ahead in the input stream. Bidders should not look further ahead than necessary, as long look aheads put pressure on the decompression layer to buffer lots of data. Most formats only require a few hundred bytes of look ahead; look aheads of a few kilobytes are reasonable. (The ISO9660 reader sometimes looks ahead by 48k, which should be considered an upper limit.)
Read header
The header read is usually the most complex part of any format. There are a few strategies worth mentioning: For formats such as tar or cpio, reading and parsing the header is straightforward since headers alternate with data. For formats that store all header data at the beginning of the file, the first header read request may have to read all headers into memory and store that data, sorted by the location of the file data. Subsequent header read requests will skip forward to the beginning of the file data and return the corresponding header.
Read Data
The read data interface supports sparse files; this requires that each call return a block of data specifying the file offset and size. This may require you to carefully track the location so that you can return accurate file offsets for each read. Remember that the decompressor will return as much data as it has. Generally, you will want to request one byte, examine the return value to see how much data is available, and possibly trim that to the amount you can use. You should invoke consume for each block just before you return it.
Skip All Data
The skip data call should skip over all file data and trailing padding. This is called automatically by the API layer just before each header read. It is also called in response to the client calling the public data_skip() function.
Cleanup
On cleanup, the format should release all of its allocated memory.
API Layer
XXX to do XXX
WRITE ARCHITECTURE
The write API has a similar set of four layers: an API layer, a format layer, a compression layer, and an I/O layer. The registration here is much simpler because only one format and one compression can be registered at a time.
I/O Layer and Client Callbacks
XXX To be written XXX
Compression Layer
XXX To be written XXX
Format Layer
XXX To be written XXX
API Layer
XXX To be written XXX
WRITE_DISK ARCHITECTURE
The write_disk API is intended to look just like the write API to clients. Since it does not handle multiple formats or compression, it is not layered internally.
GENERAL SERVICES
The archive_read, archive_write, and archive_write_disk objects all contain an initial archive object which provides common support for a set of standard services. (Recall that ANSI/ISO C90 guarantees that you can cast freely between a pointer to a structure and a pointer to the first element of that structure.) The archive object has a magic value that indicates which API this object is associated with, slots for storing error information, and function pointers for virtualized API functions.
MISCELLANEOUS NOTES
Connecting existing archiving libraries into libarchive is generally quite difficult. In particular, many existing libraries strongly assume that you are reading from a file; they seek forwards and backwards as necessary to locate various pieces of information. In contrast, libarchive never seeks backwards in its input, which sometimes requires very different approaches.
For example, libarchive’s ISO9660 support operates very differently from most ISO9660 readers. The libarchive support utilizes a work-queue design that keeps a list of known entries sorted by their location in the input. Whenever libarchive’s ISO9660 implementation is asked for the next header, checks this list to find the next item on the disk. Directories are parsed when they are encountered and new items are added to the list. This design relies heavily on the ISO9660 image being optimized so that directories always occur earlier on the disk than the files they describe.
Depending on the specific format, such approaches may not be possible. The ZIP format specification, for example, allows archivers to store key information only at the end of the file. In theory, it is possible to create ZIP archives that cannot be read without seeking. Fortunately, such archives are very rare, and libarchive can read most ZIP archives, though it cannot always extract as much information as a dedicated ZIP program.
SEE ALSO
archive_entry(3), archive_read(3), archive_write(3), archive_write_disk(3), libarchive(3)
HISTORY
The libarchive library first appeared in FreeBSD 5.3.
AUTHORS
The libarchive library was written by Tim Kientzle <kientzle@@acm.org>. Debian January 26, 2011 LIBARCHIVE_INTERNALS(3)
LIBARCHIVE_INTERNALS(3) BSD Library Functions Manual LIBARCHIVE_INTERNALS(3)
d28 2 a29 2libarchive_internals — description of libarchive internal interfaces
d33 1 a33 1The libarchive library d41 1 a41 1
Externally, libarchive exposes d43 6 a48 6 The archive_entry(3) objects store information about a single filesystem object. The rest of the library provides facilities to write archive_entry(3) objects to archive files, read them from archive files, and write them to disk. (There are plans to add a facility to read archive_entry(3) objects from disk as well.)
d50 1 a50 1The read and d57 1 a57 1
In order to d66 16 a81 15
From the outside, clients use the archive_read(3) API to manipulate an archive object to read entries and bodies from an archive stream. Internally, the archive object is cast to an archive_read object, which holds all read-specific data. The API has four layers: The lowest layer is the I/O layer. This layer can be overridden by clients, but most clients use the packaged I/O callbacks provided, for example, by archive_read_open_memory(3), and archive_read_open_fd(3). The compression layer calls the I/O layer to read bytes and decompresses them for the format layer. The format layer unpacks a stream of uncompressed bytes and creates archive_entry objects from the incoming data. The API layer tracks overall state (for example, it prevents clients from reading data before d93 2 a94 5
I/O Layer and
Client Callbacks
The read API goes to some lengths to be nice to clients. As
a result, there are few restrictions on the behavior of the
client callbacks.
The client read d107 1 a107 1
The client skip d115 1 a115 1
Keep in mind d119 2 a120 2 mmap(2) to read the entire file into memory at once and return the entire file to libarchive as a single block; d125 13 a137 11
Decompression
Layer
The decompression layer not only handles decompression, it
also buffers data so that the format handlers see a much
nicer I/O model. The decompression API is a two stage
peek/consume model. A read_ahead request specifies a minimum
read amount; the decompression layer must provide a pointer
to at least that much data. If more data is immediately
available, it should return more: the format layer handles
bulk data reads by asking for a minimum of one byte and then
copying as much data as is available.
A subsequent d146 1 a146 1
Skip requests d152 1 a152 1
A decompression d157 1 a157 1
When the client invokes the d168 1 a168 1
The bid d175 1 a175 1
The value d189 1 a189 1
The winning bidder will have d203 1 a203 1
The format handler will invoke d209 1 a209 1
The finish d215 5 a219 4
Format
Layer
The read formats have a similar lifecycle to the
decompression handlers:
Allocate your private data and d228 1 a228 1
Formats bid by d241 1 a241 1
The header read is usually the d254 1 a254 1
The read data interface d267 1 a267 1
The skip data call should skip d275 1 a275 1
On cleanup, the format should d278 4 a281 3
API Layer
XXX to do XXX
The write API has a similar set d291 19 a309 15
I/O Layer and
Client Callbacks
XXX To be written XXX
Compression
Layer
XXX To be written XXX
Format
Layer
XXX To be written XXX
API Layer
XXX To be written XXX
The write_disk API is intended d321 1 a321 1
The archive_read, d334 1 a334 1
Connecting existing archiving d342 1 a342 1
For example, d354 1 a354 1
Depending on the d366 3 a368 3
archive_entry(3), archive_read(3), archive_write(3), archive_write_disk(3), libarchive(3)
d372 1 a372 1The libarchive library d377 3 a379 5
The libarchive library was written by Tim Kientzle <kientzle@@acm.org>.
BSD January 26, 2011 BSD
@ 1.11 log @libarchive: updated to 3.7.4 Libarchive 3.7.4 is a bugfix and security release Security fixes: rar: Fix OOB in rar e8 filter (CVE-2024-26256) zip: Fix out of boundary access Important bugfixes: 7zip: Limit amount of properties bsdtar: Fix error handling around strtol() usages passphrase: Improve newline handling on Windows passphrase: Never allow empty passwords rar: Fix "File CRC Error" when extracting specific rar4 archives xar: Avoid infinite link loop zip: Update AppleDouble support for directories zstd: Implement core detection @ text @d2 1 a2 1 @ 1.10 log @libarchive: updated to 3.7.3 Libarchive 3.7.3 is a feature, security and bugfix release. New features: PCRE2 support add trailing letter b to bsdtar(1) substitute pattern add support for long options "--group" and "--owner" to tar(1) Security fixes: Fix possible vulnerability in tar error reporting introduced in f27c173 Important bugfixes: ISO9660: preserve the natural order of links rar5: fix decoding unicode filenames on Windows rar5: fix infinite loop if during rar5 decompression the last block produced no data xz filter: fix incorrect eof at the end of an lzip member zip: fix end-of-data marker processing when decompressing zip archives multiple bsdunzip(1) fixes filetime truncation fix on Windows @ text @d2 1 a2 1 d123 1 a123 1Decompresssion @ 1.9 log @libarchive: updated to 3.7.2 Libarchive 3.7.2 is a security, bugfix and feature release. Security fixes: Multiple vulnerabilities have been fixed in the PAX writer (1b4e0d0) Important bugfixes: bsdunzip(1) now correctly handles arguments following an -x after the zipfile New features: bsdunzip(1) now supports the "--version" flag 7-zip reader now translates Windows permissions into UNIX permissions uudecode filter in raw mode now supports file name and file mode zstd filter now supports the "long" write option Libarchive 3.7.1 is a security, feature and bugfix release. Security fixes: SEGV and stack buffer overflow in verbose mode of cpio Feature updates: bsdunzip updated to match latest upstream code Important bugfixes: miscellaneous functional bugfixes build fixes on multiple platforms Libarchive 3.7.0 is a feature and bugfix release. New features: bsdunzip: new tool ported from FreeBSD drop-in replacement for Info-ZIP unzip, not yet ported for Windows 7zip reader: support for Zstandard compression 7zip reader: support for ARM64 filter zstd filter: support for multi-frame zstd archives Other notable bugfixes and improvements: pax: fix year 2038 problem on platforms with 64-bit time_t Windows: Universal Windows Platform (UWP) fixes and improvements Windows: bcrypt usage fixes and improvements Windows: time function usage fixes and improvements @ text @d2 1 a2 1 @ 1.8 log @libarchive: Update to 3.4.3 Libarchive 3.4.3 is a feature and bugfix release. New features: support for pzstd compressed files (#1357) support for RHT.security.selinux tar extended attribute (#1348) Important bugfixes: various zstd fixes and improvements (#1342 #1352 #1359) child process handling fixes (#1372) Libarchive 3.4.2 is a feature and security release. New features: support for atomic file extraction (bsdtar -x --safe-writes) (#1289) support for mbed TLS (PolarSSL) (#1301) Important bugfixes: security fixes in RAR5 reader (#1280 #1326) compression buffer fix in XAR writer (#1317) fix uname and gname longer than 32 characters in PAX writer (#1319) fix segfault when archiving hard links in ISO9660 and XAR writers (#1325) fix support for extracting 7z archive entries with Delta filter (#987) Libarchive 3.4.1 is a feature and security release. New features: Unicode filename support for reading lha/lzh archives New pax write option "xattrhdr" Important bugfixes: security fixes in wide string processing (#1276 #1298) security fixes in RAR5 reader (#1212 #1217 #1296) security fixes and optimizations to write filter logic (#351) security fix related to use of readlink(2) (1dae5a5) sparse file handling fixes (#1218 #1260) Thanks to all contributors and bug reporters. Special thanks to Christos Zoulas (@@zoulasc) from NetBSD for the atomic file extraction feature. @ text @d1 2 a2 2 @ 1.7 log @Update for libarchive-3.4.0: - improvements for Android APK and JAR archives - better support for non-recursive list and extract - tar --exclude-vcs support - fixes for file attributes and flags handling - zipx support - rar 5.0 reader @ text @d1 2 a2 2 d357 2 a358 2 archive_read(3), archive_write(3), archive_write_disk(3) libarchive(3),
@ 1.6 log @libarchive: updated to 3.3.3 libarchive 3.3.3: Avoid super-linear slowdown on malformed mtree files Many fixes for building with Visual Studio NO_OVERWRITE doesn't change existing directory attributes New support for Zstandard read and write filters @ text @d1 2 a2 2 @ 1.5 log @Merge for libarchive-3.3.2. @ text @d2 1 a2 1 @ 1.4 log @Merge libarchive-3.3.1. @ text @d2 1 a2 1 @ 1.3 log @Update for libarchive 3.2.1. @ text @d2 1 a2 1 @ 1.2 log @Changes 3.1.2: This is a maintenance update to fix issues with the new RAR seeking feature. This new release also contains fixes for build failures when building libarchive using Visual Studio 2012 and MinGW. @ text @d1 2 a2 2 d356 3 a358 2archive(3), archive_entry(3), archive_read(3), archive_write(3), archive_write_disk(3)
d368 1 a368 2 was written by Tim Kientzle ⟨ kientzle@@acm.org⟩ . @ 1.1 log @Initial revision @ text @d1 2 a2 2 d11 4 a14 3 p { margin-top: 0; margin-bottom: 0; } pre { margin-top: 0; margin-bottom: 0; } table { margin-top: 0; margin-bottom: 0; } d23 2 a24 2LIBARCHIVE(3) FreeBSD Library Functions Manual LIBARCHIVE(3)
d26 1 a26 1NAME
d28 1 a28 1libarchive_internals d31 1 d33 1 a33 3
OVERVIEW
The libarchive library d39 1 a39 2
GENERAL ARCHITECTURE
d41 1 a41 1Externally, libarchive exposes d43 1 a43 1 The archive_entry(1) objects store information about a d45 1 a45 1 facilities to write archive_entry(1) objects to archive d47 1 a47 1 (There are plans to add a facility to read archive_entry(1) d50 1 a50 1
The read and d57 1 a57 1
In order to d64 1 a64 2
READ ARCHITECTURE
d66 1 a66 1From the outside, clients use d92 1 a92 1
I/O Layer and d98 1 a98 1
The client read d105 1 a105 1
The client skip d113 1 a113 1
Keep in mind d123 1 a123 1
Decompresssion d135 1 a135 1
A subsequent d142 1 a142 1
Skip requests d148 1 a148 1
A decompression d151 1 a151 1
Registration/Configuration
d153 1 a153 1When the client invokes the d162 1 a162 1
Bid
d164 1 a164 1The bid d171 1 a171 1
The value d183 1 a183 1
Initialize
d185 1 a185 1The winning bidder will have d197 1 a197 1
Satisfy I/O requests
d199 1 a199 1The format handler will invoke d203 1 a203 1
Finish
d205 1 a205 1The finish d211 1 a211 1
Format d216 1 a216 1
Registration
d218 1 a218 1Allocate your private data and d221 1 a221 1
Bid
d223 1 a223 1Formats bid by d234 1 a234 1
Read header
d236 1 a236 1The header read is usually the d247 1 a247 1
Read Data
d249 1 a249 1The read data interface d260 1 a260 1
Skip All Data
d262 1 a262 1The skip data call should skip d268 1 a268 1
Cleanup
d270 1 a270 1On cleanup, the format should d273 1 a273 1
API Layer d277 1 a277 2
WRITE ARCHITECTURE
d279 1 a279 1The write API has a similar set d285 1 a285 1
I/O Layer and d289 1 a289 1
Compression d293 1 a293 1
Format d297 1 a297 1
API Layer d301 1 a301 1
WRITE_DISK d304 1 a304 1
The write_disk API is intended d309 1 a309 2
GENERAL SERVICES
d311 1 a311 1The archive_read, d322 1 a322 2
MISCELLANEOUS NOTES
d324 1 a324 1Connecting existing archiving d332 1 a332 1
For example, d344 1 a344 1
Depending on the d354 1 a354 1
SEE ALSO
d356 1 a356 1archive(3), archive_entry(3), d359 1 a359 1
HISTORY
d361 1 a361 1The libarchive library d364 1 a364 5
AUTHORS
The libarchive library was written by Tim Kientzle ⟨kientzle@@acm.org⟩.
d366 3 a368 1BUGS
d370 2 a371 2FreeBSD 8.0 April 16, 2007 FreeBSD 8.0
@ 1.1.1.1 log @Import libarchive 2.8.0: - Infrastructure: - Allow command line tools as fallback for missing compression libraries. If compiled without gzip for example, gunzip will be used automatically. - Improved support for a number of platforms like high-resolution timestamps and Extended Attributes on various Unix systems - New convience interface for creating archives based on disk content, complement of the archive_write_disk interface. - Frontends: - bsdcpio ready for public consumption - hand-written date parser replaces the yacc code - Filter system: - Simplified read filter chains - Option support for filters - LZMA, XZ, uudecode handled - Format support: - Write support for mtree files based on file system or archive content - Basic read support for Joliet - Write support for zip files - Write support for shar archives, both text-only and binary-safe @ text @@ 1.1.1.2 log @libarchive-2.8.2: - Fix NULL deference for short self-extracting zip archives - Don't dereference symlinks on Linux when reading ACLs - Better detection of SHA2 support for old OpenSSL versions - Fix parsing of input files for bsdtar -T - Do not leak setup_xattr into the global namespace - Fix build when an older libarchive is already installed - Use O_BINARY opening files in bsdtar - Include missing archive_crc32.h - Correctly include iconv.h required by libxml2 @ text @d1 381 a381 891 %!PS-Adobe-3.0 %%Creator: groff version 1.19.2 %%CreationDate: Sun Mar 14 02:49:17 2010 %%DocumentNeededResources: font Times-Roman %%DocumentSuppliedResources: procset grops 1.19 2 %%Pages: 66 %%PageOrder: Ascend %%DocumentMedia: Default 612 792 0 () () %%Orientation: Portrait %%EndComments %%BeginDefaults %%PageMedia: Default %%EndDefaults %%BeginProlog %%BeginResource: procset grops 1.19 2 %!PS-Adobe-3.0 Resource-ProcSet /setpacking where{ pop currentpacking true setpacking }if /grops 120 dict dup begin /SC 32 def /A/show load def /B{0 SC 3 -1 roll widthshow}bind def /C{0 exch ashow}bind def /D{0 exch 0 SC 5 2 roll awidthshow}bind def /E{0 rmoveto show}bind def /F{0 rmoveto 0 SC 3 -1 roll widthshow}bind def /G{0 rmoveto 0 exch ashow}bind def /H{0 rmoveto 0 exch 0 SC 5 2 roll awidthshow}bind def /I{0 exch rmoveto show}bind def /J{0 exch rmoveto 0 SC 3 -1 roll widthshow}bind def /K{0 exch rmoveto 0 exch ashow}bind def /L{0 exch rmoveto 0 exch 0 SC 5 2 roll awidthshow}bind def /M{rmoveto show}bind def /N{rmoveto 0 SC 3 -1 roll widthshow}bind def /O{rmoveto 0 exch ashow}bind def /P{rmoveto 0 exch 0 SC 5 2 roll awidthshow}bind def /Q{moveto show}bind def /R{moveto 0 SC 3 -1 roll widthshow}bind def /S{moveto 0 exch ashow}bind def /T{moveto 0 exch 0 SC 5 2 roll awidthshow}bind def /SF{ findfont exch [exch dup 0 exch 0 exch neg 0 0]makefont dup setfont [exch/setfont cvx]cvx bind def }bind def /MF{ findfont [5 2 roll 0 3 1 roll neg 0 0]makefont dup setfont [exch/setfont cvx]cvx bind def }bind def /level0 0 def /RES 0 def /PL 0 def /LS 0 def /MANUAL{ statusdict begin/manualfeed true store end }bind def /PLG{ gsave newpath clippath pathbbox grestore exch pop add exch pop }bind def /BP{ /level0 save def 1 setlinecap 1 setlinejoin 72 RES div dup scale LS{ 90 rotate }{ 0 PL translate }ifelse 1 -1 scale }bind def /EP{ level0 restore showpage }def /DA{ newpath arcn stroke }bind def /SN{ transform .25 sub exch .25 sub exch round .25 add exch round .25 add exch itransform }bind def /DL{ SN moveto SN lineto stroke }bind def /DC{ newpath 0 360 arc closepath }bind def /TM matrix def /DE{ TM currentmatrix pop translate scale newpath 0 0 .5 0 360 arc closepath TM setmatrix }bind def /RC/rcurveto load def /RL/rlineto load def /ST/stroke load def /MT/moveto load def /CL/closepath load def /Fr{ setrgbcolor fill }bind def /setcmykcolor where{ pop /Fk{ setcmykcolor fill }bind def }if /Fg{ setgray fill }bind def /FL/fill load def /LW/setlinewidth load def /Cr/setrgbcolor load def /setcmykcolor where{ pop /Ck/setcmykcolor load def }if /Cg/setgray load def /RE{ findfont dup maxlength 1 index/FontName known not{1 add}if dict begin { 1 index/FID ne{def}{pop pop}ifelse }forall /Encoding exch def dup/FontName exch def currentdict end definefont pop }bind def /DEFS 0 def /EBEGIN{ moveto DEFS begin }bind def /EEND/end load def /CNT 0 def /level1 0 def /PBEGIN{ /level1 save def translate div 3 1 roll div exch scale neg exch neg exch translate 0 setgray 0 setlinecap 1 setlinewidth 0 setlinejoin 10 setmiterlimit []0 setdash /setstrokeadjust where{ pop false setstrokeadjust }if /setoverprint where{ pop false setoverprint }if newpath /CNT countdictstack def userdict begin /showpage{}def /setpagedevice{}def }bind def /PEND{ countdictstack CNT sub{end}repeat level1 restore }bind def end def /setpacking where{ pop setpacking }if %%EndResource %%EndProlog %%BeginSetup %%BeginFeature: *PageSize Default << /PageSize [ 612 792 ] /ImagingBBox null >> setpagedevice %%EndFeature %%IncludeResource: font Times-Roman grops begin/DEFS 1 dict def DEFS begin/u{.001 mul}bind def end/RES 72 def/PL 792 def/LS false def/ENC0[/asciicircum/asciitilde/Scaron/Zcaron /scaron/zcaron/Ydieresis/trademark/quotesingle/Euro/.notdef/.notdef /.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef /.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef /.notdef/.notdef/space/exclam/quotedbl/numbersign/dollar/percent /ampersand/quoteright/parenleft/parenright/asterisk/plus/comma/hyphen /period/slash/zero/one/two/three/four/five/six/seven/eight/nine/colon /semicolon/less/equal/greater/question/at/A/B/C/D/E/F/G/H/I/J/K/L/M/N/O /P/Q/R/S/T/U/V/W/X/Y/Z/bracketleft/backslash/bracketright/circumflex /underscore/quoteleft/a/b/c/d/e/f/g/h/i/j/k/l/m/n/o/p/q/r/s/t/u/v/w/x/y /z/braceleft/bar/braceright/tilde/.notdef/quotesinglbase/guillemotleft /guillemotright/bullet/florin/fraction/perthousand/dagger/daggerdbl /endash/emdash/ff/fi/fl/ffi/ffl/dotlessi/dotlessj/grave/hungarumlaut /dotaccent/breve/caron/ring/ogonek/quotedblleft/quotedblright/oe/lslash /quotedblbase/OE/Lslash/.notdef/exclamdown/cent/sterling/currency/yen /brokenbar/section/dieresis/copyright/ordfeminine/guilsinglleft /logicalnot/minus/registered/macron/degree/plusminus/twosuperior /threesuperior/acute/mu/paragraph/periodcentered/cedilla/onesuperior /ordmasculine/guilsinglright/onequarter/onehalf/threequarters /questiondown/Agrave/Aacute/Acircumflex/Atilde/Adieresis/Aring/AE /Ccedilla/Egrave/Eacute/Ecircumflex/Edieresis/Igrave/Iacute/Icircumflex /Idieresis/Eth/Ntilde/Ograve/Oacute/Ocircumflex/Otilde/Odieresis /multiply/Oslash/Ugrave/Uacute/Ucircumflex/Udieresis/Yacute/Thorn /germandbls/agrave/aacute/acircumflex/atilde/adieresis/aring/ae/ccedilla /egrave/eacute/ecircumflex/edieresis/igrave/iacute/icircumflex/idieresis /eth/ntilde/ograve/oacute/ocircumflex/otilde/odieresis/divide/oslash /ugrave/uacute/ucircumflex/udieresis/yacute/thorn/ydieresis]def /Times-Roman@@0 ENC0/Times-Roman RE %%EndSetup %%Page: 1 1 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF()0 12 Q()0 24 Q()36 12 Q(The read and write APIs each ha)0 24 Q .3 -.15(ve f)-.2 H(our layers: a public API).15 E(layer)0 36 Q 2.5 (,af)-.4 G(ormat layer that understands the archi)-2.5 E .3 -.15 (ve \214)-.25 H(le format,).15 E 2.5(ac)0 48 S(ompression layer)-2.5 E 2.5(,a)-.4 G(nd an I/O layer)-2.5 E(.)-.55 E (The I/O layer is completely e)0 60 Q(xposed to clients who can replace) -.15 E(it entirely with their o)0 72 Q(wn functions.)-.25 E 0 Cg EP %%Page: 10 10 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF(
)36 12 Q(In order to pro)0 24 Q (vide as much consistenc)-.15 E 2.5(ya)-.15 G 2.5(sp)-2.5 G (ossible for clients,)-2.5 E(some public functions are virtualized.)0 36 Q(Ev)0 48 Q(entually)-.15 E 2.5(,i)-.65 G 2.5(ts)-2.5 G (hould be possible for clients to open)-2.5 E(an archi)0 60 Q .3 -.15 (ve o)-.25 H 2.5(rd).15 G(isk writer)-2.5 E 2.5(,a)-.4 G (nd then use a single set of)-2.5 E (code to select and write entries, re)0 72 Q -.05(ga)-.15 G (rdless of the tar).05 E(get.)-.18 E 0 Cg EP %%Page: 11 11 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF(
)36 36 Q(The client read callback is e)0 48 Q(xpected to pro)-.15 E (vide a block)-.15 E(of data on each call.)0 60 Q 2.5(Az)0 72 S (ero-length return does indicate end of \214le, b)-2.5 E(ut otherwise) -.2 E 0 Cg EP %%Page: 19 19 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF(blocks may be as small as one byte or as lar)0 12 Q(ge as the entire \214le.)-.18 E(In particular)0 24 Q 2.5(,b)-.4 G (locks may be of dif)-2.5 E(ferent sizes.)-.25 E(
)36 36 Q (The client skip callback returns the number of bytes actually)0 48 Q (skipped, which may be much smaller than the skip requested.)0 60 Q (The only requirement is that the skip not be lar)0 72 Q(ger)-.18 E(.) -.55 E 0 Cg EP %%Page: 20 20 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF(In particular)0 12 Q 2.5(,c)-.4 G (lients are allo)-2.5 E(wed to return zero for an)-.25 E(y)-.15 E (skip that the)0 24 Q 2.5(yd)-.15 G(on')-2.5 E 2.5(tw)-.18 G (ant to handle.)-2.6 E(The skip callback must ne)0 36 Q -.15(ve)-.25 G 2.5(rb).15 G 2.5(ei)-2.5 G -1.9 -.4(nv o)-2.5 H -.1(ke).4 G 2.5(dw).1 G (ith a ne)-2.5 E -.05(ga)-.15 G(ti).05 E .3 -.15(ve v)-.25 H(alue.)-.1 E (
)36 48 Q -.25(Ke)0 60 S (ep in mind that not all clients are reading from disk:).25 E (clients reading from netw)0 72 Q(orks may pro)-.1 E(vide dif)-.15 E (ferent-sized)-.25 E 0 Cg EP %%Page: 21 21 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF(blocks on e)0 12 Q -.15(ve)-.25 G (ry request and cannot skip at all;).15 E(adv)0 24 Q (anced clients may use)-.25 E (mmap\(2\))0 36 Q (to read the entire \214le into memory at once and return the)0 48 Q (entire \214le to libarchi)0 60 Q .3 -.15(ve a)-.25 H 2.5(sas).15 G (ingle block;)-2.5 E(other clients may be)0 72 Q (gin asynchronous I/O operations for the)-.15 E 0 Cg EP %%Page: 22 22 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF(ne)0 12 Q(xt block on each request.)-.15 E (
)36
36 Q 2.5(As)0 48 S(ubsequent call to the)-2.5 E
(consume\(\))0 60 Q(function adv)0 72 Q
(ances the read pointer)-.25 E(.)-.55 E 0 Cg EP
%%Page: 25 25
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(Note that data returned from a)0 12 Q
(read_ahead\(\))0 24 Q
(call is guaranteed to remain in place until)0 36 Q(the ne)0 48 Q
(xt call to)-.15 E(read_ahead\(\).)0 60 Q(Interv)0
72 Q(ening calls to)-.15 E 0 Cg EP
%%Page: 26 26
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(consume\(\))0 12 Q
(should not cause the data to mo)0 24 Q -.15(ve)-.15 G(.).15 E(
)36 36 Q(Skip requests must al)0 48 Q -.1(wa)-.1 G(ys be handled e).1 E(xactly) -.15 E(.)-.65 E(Decompression handlers that cannot seek forw)0 60 Q (ard should)-.1 E(not re)0 72 Q(gister a skip handler;)-.15 E 0 Cg EP %%Page: 27 27 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF(the API layer \214lls in a generic skip handler\ that reads and discards data.)0 12 Q(
)36 24 Q 2.5(Ad)0 36 S (ecompression handler has a speci\214c lifec)-2.5 E(ycle:)-.15 E (
)36 36 Q(The v)0 48 Q (alue returned by the bid function indicates its suitability)-.25 E (for handling this data stream.)0 60 Q 2.5(Ab)0 72 S (id of zero will ensure that this decompressor is ne)-2.5 E -.15(ve)-.25 G 2.5(ri).15 G -1.9 -.4(nv o)-2.5 H -.1(ke).4 G(d.).1 E 0 Cg EP %%Page: 32 32 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF(Return zero if magic number checks f)0 12 Q (ail.)-.1 E(Otherwise, your initial implementation should return the nu\ mber of bits)0 24 Q(actually check)0 36 Q(ed.)-.1 E -.15(Fo)0 48 S 2.5 (re).15 G(xample, if you v)-2.65 E(erify tw)-.15 E 2.5(of)-.1 G (ull bytes and three bits of another)-2.5 E(byte, bid 19.)0 60 Q (Note that the initial block may be v)0 72 Q(ery short;)-.15 E 0 Cg EP %%Page: 33 33 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF(be careful to only inspect the data you are gi)0 12 Q -.15(ve)-.25 G(n.).15 E(\(The current decompressors require tw)0 24 Q 2.5(ob)-.1 G(ytes for correct bidding.\))-2.5 E(
)36 12 Q -.15(Fo)0 24 S 2.5(re).15 G (xample, libarchi)-2.65 E -.15(ve)-.25 G 1.1 -.55('s I).15 H (SO9660 support operates v).55 E(ery dif)-.15 E(ferently)-.25 E (from most ISO9660 readers.)0 36 Q(The libarchi)0 48 Q .3 -.15(ve s)-.25 H(upport utilizes a w).15 E(ork-queue design that)-.1 E -.1(ke)0 60 S (eps a list of kno).1 E (wn entries sorted by their location in the input.)-.25 E(Whene)0 72 Q -.15(ve)-.25 G 2.5(rl).15 G(ibarchi)-2.5 E -.15(ve)-.25 G 1.1 -.55('s I) .15 H(SO9660 implementation is ask).55 E(ed for the ne)-.1 E(xt)-.15 E 0 Cg EP %%Page: 60 60 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF(header)0 12 Q 2.5(,c)-.4 G (hecks this list to \214nd the ne)-2.5 E(xt item on the disk.)-.15 E (Directories are parsed when the)0 24 Q 2.5(ya)-.15 G (re encountered and ne)-2.5 E(w)-.25 E(items are added to the list.)0 36 Q(This design relies hea)0 48 Q (vily on the ISO9660 image being optimized so that)-.2 E(directories al) 0 60 Q -.1(wa)-.1 G(ys occur earlier on the disk than the \214les the).1 E(y)-.15 E(describe.)0 72 Q 0 Cg EP %%Page: 61 61 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF(
)36 12 Q(Depending on the speci\214c format,\ such approaches may not be possible.)0 24 Q (The ZIP format speci\214cation, for e)0 36 Q(xample, allo)-.15 E (ws archi)-.25 E -.15(ve)-.25 G(rs to store).15 E -.1(ke)0 48 S 2.5(yi) -.05 G(nformation only at the end of the \214le.)-2.5 E(In theory)0 60 Q 2.5(,i)-.65 G 2.5(ti)-2.5 G 2.5(sp)-2.5 G(ossible to create ZIP archi) -2.5 E -.15(ve)-.25 G 2.5(st).15 G(hat cannot)-2.5 E (be read without seeking.)0 72 Q 0 Cg EP %%Page: 62 62 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF -.15(Fo)0 12 S(rtunately).15 E 2.5(,s)-.65 G (uch archi)-2.5 E -.15(ve)-.25 G 2.5(sa).15 G(re v)-2.5 E (ery rare, and libarchi)-.15 E .3 -.15(ve c)-.25 H(an read).15 E (most ZIP archi)0 24 Q -.15(ve)-.25 G(s, though it cannot al).15 E -.1 (wa)-.1 G(ys e).1 E(xtract as much information)-.15 E (as a dedicated ZIP program.)0 36 Q(
)36 48 Q(The)0 60 Q(libarchi)0 72 Q -.15(ve)-.25 G().15 E 0 Cg EP %%Page: 66 66 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF(library w)0 12 Q(as written by)-.1 E -.35(Ti)0 24 S 2.5(mK).35 G(ientzle <kientzle@@acm.or)-2.5 E(g>.)-.18 E (
LIBARCHIVE(3) FreeBSD Library Functions Manual LIBARCHIVE(3)
NAME
libarchive_internals — description of libarchive internal interfaces
OVERVIEW
The libarchive library provides a flexible interface for reading and writing streaming archive files such as tar and cpio. Internally, it follows a modular layered design that should make it easy to add new archive and compression formats.
GENERAL ARCHITECTURE
Externally, libarchive exposes most operations through an opaque, object-style interface. The archive_entry(1) objects store information about a single filesystem object. The rest of the library provides facilities to write archive_entry(1) objects to archive files, read them from archive files, and write them to disk. (There are plans to add a facility to read archive_entry(1) objects from disk as well.)
The read and write APIs each have four layers: a public API layer, a format layer that understands the archive file format, a compression layer, and an I/O layer. The I/O layer is completely exposed to clients who can replace it entirely with their own functions.
In order to provide as much consistency as possible for clients, some public functions are virtualized. Eventually, it should be possible for clients to open an archive or disk writer, and then use a single set of code to select and write entries, regardless of the target.
READ ARCHITECTURE
From the outside, clients use the archive_read(3) API to manipulate an archive object to read entries and bodies from an archive stream. Internally, the archive object is cast to an archive_read object, which holds all read-specific data. The API has four layers: The lowest layer is the I/O layer. This layer can be overridden by clients, but most clients use the packaged I/O callbacks provided, for example, by archive_read_open_memory(3), and archive_read_open_fd(3). The compression layer calls the I/O layer to read bytes and decompresses them for the format layer. The format layer unpacks a stream of uncompressed bytes and creates archive_entry objects from the incoming data. The API layer tracks overall state (for example, it prevents clients from reading data before reading a header) and invokes the format and compression layer operations through registered function pointers. In particular, the API layer drives the format-detection process: When opening the archive, it reads an initial block of data and offers it to each registered compression handler. The one with the highest bid is initialized with the first block. Similarly, the format handlers are polled to see which handler is the best for each archive. (Prior to 2.4.0, the format bidders were invoked for each entry, but this design hindered error recovery.)
I/O Layer and
Client Callbacks
The read API goes to some lengths to be nice to clients. As
a result, there are few restrictions on the behavior of the
client callbacks.
The client read callback is expected to provide a block of data on each call. A zero-length return does indicate end of file, but otherwise blocks may be as small as one byte or as large as the entire file. In particular, blocks may be of different sizes.
The client skip callback returns the number of bytes actually skipped, which may be much smaller than the skip requested. The only requirement is that the skip not be larger. In particular, clients are allowed to return zero for any skip that they don’t want to handle. The skip callback must never be invoked with a negative value.
Keep in mind that not all clients are reading from disk: clients reading from networks may provide different-sized blocks on every request and cannot skip at all; advanced clients may use mmap(2) to read the entire file into memory at once and return the entire file to libarchive as a single block; other clients may begin asynchronous I/O operations for the next block on each request.
Decompresssion
Layer
The decompression layer not only handles decompression, it
also buffers data so that the format handlers see a much
nicer I/O model. The decompression API is a two stage
peek/consume model. A read_ahead request specifies a minimum
read amount; the decompression layer must provide a pointer
to at least that much data. If more data is immediately
available, it should return more: the format layer handles
bulk data reads by asking for a minimum of one byte and then
copying as much data as is available.
A subsequent call to the consume() function advances the read pointer. Note that data returned from a read_ahead() call is guaranteed to remain in place until the next call to read_ahead(). Intervening calls to consume() should not cause the data to move.
Skip requests must always be handled exactly. Decompression handlers that cannot seek forward should not register a skip handler; the API layer fills in a generic skip handler that reads and discards data.
A decompression handler has a specific lifecycle:
Registration/Configuration
When the client invokes the public support function, the decompression handler invokes the internal __archive_read_register_compression() function to provide bid and initialization functions. This function returns NULL on error or else a pointer to a struct decompressor_t. This structure contains a void * config slot that can be used for storing any customization information.
Bid
The bid function is invoked with a pointer and size of a block of data. The decompressor can access its config data through the decompressor element of the archive_read object. The bid function is otherwise stateless. In particular, it must not perform any I/O operations.
The value returned by the bid function indicates its suitability for handling this data stream. A bid of zero will ensure that this decompressor is never invoked. Return zero if magic number checks fail. Otherwise, your initial implementation should return the number of bits actually checked. For example, if you verify two full bytes and three bits of another byte, bid 19. Note that the initial block may be very short; be careful to only inspect the data you are given. (The current decompressors require two bytes for correct bidding.)
Initialize
The winning bidder will have its init function called. This function should initialize the remaining slots of the struct decompressor_t object pointed to by the decompressor element of the archive_read object. In particular, it should allocate any working data it needs in the data slot of that structure. The init function is called with the block of data that was used for tasting. At this point, the decompressor is responsible for all I/O requests to the client callbacks. The decompressor is free to read more data as and when necessary.
Satisfy I/O requests
The format handler will invoke the read_ahead, consume, and skip functions as needed.
Finish
The finish method is called only once when the archive is closed. It should release anything stored in the data and config slots of the decompressor object. It should not invoke the client close callback.
Format
Layer
The read formats have a similar lifecycle to the
decompression handlers:
Registration
Allocate your private data and initialize your pointers.
Bid
Formats bid by invoking the read_ahead() decompression method but not calling the consume() method. This allows each bidder to look ahead in the input stream. Bidders should not look further ahead than necessary, as long look aheads put pressure on the decompression layer to buffer lots of data. Most formats only require a few hundred bytes of look ahead; look aheads of a few kilobytes are reasonable. (The ISO9660 reader sometimes looks ahead by 48k, which should be considered an upper limit.)
Read header
The header read is usually the most complex part of any format. There are a few strategies worth mentioning: For formats such as tar or cpio, reading and parsing the header is straightforward since headers alternate with data. For formats that store all header data at the beginning of the file, the first header read request may have to read all headers into memory and store that data, sorted by the location of the file data. Subsequent header read requests will skip forward to the beginning of the file data and return the corresponding header.
Read Data
The read data interface supports sparse files; this requires that each call return a block of data specifying the file offset and size. This may require you to carefully track the location so that you can return accurate file offsets for each read. Remember that the decompressor will return as much data as it has. Generally, you will want to request one byte, examine the return value to see how much data is available, and possibly trim that to the amount you can use. You should invoke consume for each block just before you return it.
Skip All Data
The skip data call should skip over all file data and trailing padding. This is called automatically by the API layer just before each header read. It is also called in response to the client calling the public data_skip() function.
Cleanup
On cleanup, the format should release all of its allocated memory.
API Layer
XXX to do XXX
WRITE ARCHITECTURE
The write API has a similar set of four layers: an API layer, a format layer, a compression layer, and an I/O layer. The registration here is much simpler because only one format and one compression can be registered at a time.
I/O Layer and
Client Callbacks
XXX To be written XXX
Compression
Layer
XXX To be written XXX
Format
Layer
XXX To be written XXX
API Layer
XXX To be written XXX
WRITE_DISK ARCHITECTURE
The write_disk API is intended to look just like the write API to clients. Since it does not handle multiple formats or compression, it is not layered internally.
GENERAL SERVICES
The archive_read, archive_write, and archive_write_disk objects all contain an initial archive object which provides common support for a set of standard services. (Recall that ANSI/ISO C90 guarantees that you can cast freely between a pointer to a structure and a pointer to the first element of that structure.) The archive object has a magic value that indicates which API this object is associated with, slots for storing error information, and function pointers for virtualized API functions.
MISCELLANEOUS NOTES
Connecting existing archiving libraries into libarchive is generally quite difficult. In particular, many existing libraries strongly assume that you are reading from a file; they seek forwards and backwards as necessary to locate various pieces of information. In contrast, libarchive never seeks backwards in its input, which sometimes requires very different approaches.
For example, libarchive’s ISO9660 support operates very differently from most ISO9660 readers. The libarchive support utilizes a work-queue design that keeps a list of known entries sorted by their location in the input. Whenever libarchive’s ISO9660 implementation is asked for the next header, checks this list to find the next item on the disk. Directories are parsed when they are encountered and new items are added to the list. This design relies heavily on the ISO9660 image being optimized so that directories always occur earlier on the disk than the files they describe.
Depending on the specific format, such approaches may not be possible. The ZIP format specification, for example, allows archivers to store key information only at the end of the file. In theory, it is possible to create ZIP archives that cannot be read without seeking. Fortunately, such archives are very rare, and libarchive can read most ZIP archives, though it cannot always extract as much information as a dedicated ZIP program.
SEE ALSO
archive(3), archive_entry(3), archive_read(3), archive_write(3), archive_write_disk(3)
HISTORY
The libarchive library first appeared in FreeBSD 5.3.
AUTHORS
The libarchive library was written by Tim Kientzle ⟨kientzle@@acm.org⟩.
BUGS
FreeBSD 9.0 April 16, 2007 FreeBSD 9.0
)36 12 Q(The read and write APIs each ha)0 24 Q .3 -.15(ve f)-.2 H(our layers: a public API).15 E(layer)0 36 Q 2.5 (,af)-.4 G(ormat layer that understands the archi)-2.5 E .3 -.15 (ve \214)-.25 H(le format,).15 E 2.5(ac)0 48 S(ompression layer)-2.5 E 2.5(,a)-.4 G(nd an I/O layer)-2.5 E(.)-.55 E (The I/O layer is completely e)0 60 Q(xposed to clients who can replace) -.15 E(it entirely with their o)0 72 Q(wn functions.)-.25 E 0 Cg EP %%Page: 10 10 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF(
)36 12 Q(In order to pro)0 24 Q (vide as much consistenc)-.15 E 2.5(ya)-.15 G 2.5(sp)-2.5 G (ossible for clients,)-2.5 E(some public functions are virtualized.)0 36 Q(Ev)0 48 Q(entually)-.15 E 2.5(,i)-.65 G 2.5(ts)-2.5 G (hould be possible for clients to open)-2.5 E(an archi)0 60 Q .3 -.15 (ve o)-.25 H 2.5(rd).15 G(isk writer)-2.5 E 2.5(,a)-.4 G (nd then use a single set of)-2.5 E (code to select and write entries, re)0 72 Q -.05(ga)-.15 G (rdless of the tar).05 E(get.)-.18 E 0 Cg EP %%Page: 11 11 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF(
)36 36 Q(The client read callback is e)0 48 Q(xpected to pro)-.15 E (vide a block)-.15 E(of data on each call.)0 60 Q 2.5(Az)0 72 S (ero-length return does indicate end of \214le, b)-2.5 E(ut otherwise) -.2 E 0 Cg EP %%Page: 19 19 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF(blocks may be as small as one byte or as lar)0 12 Q(ge as the entire \214le.)-.18 E(In particular)0 24 Q 2.5(,b)-.4 G (locks may be of dif)-2.5 E(ferent sizes.)-.25 E(
)36 36 Q (The client skip callback returns the number of bytes actually)0 48 Q (skipped, which may be much smaller than the skip requested.)0 60 Q (The only requirement is that the skip not be lar)0 72 Q(ger)-.18 E(.) -.55 E 0 Cg EP %%Page: 20 20 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF(In particular)0 12 Q 2.5(,c)-.4 G (lients are allo)-2.5 E(wed to return zero for an)-.25 E(y)-.15 E (skip that the)0 24 Q 2.5(yd)-.15 G(on')-2.5 E 2.5(tw)-.18 G (ant to handle.)-2.6 E(The skip callback must ne)0 36 Q -.15(ve)-.25 G 2.5(rb).15 G 2.5(ei)-2.5 G -1.9 -.4(nv o)-2.5 H -.1(ke).4 G 2.5(dw).1 G (ith a ne)-2.5 E -.05(ga)-.15 G(ti).05 E .3 -.15(ve v)-.25 H(alue.)-.1 E (
)36 48 Q -.25(Ke)0 60 S (ep in mind that not all clients are reading from disk:).25 E (clients reading from netw)0 72 Q(orks may pro)-.1 E(vide dif)-.15 E (ferent-sized)-.25 E 0 Cg EP %%Page: 21 21 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF(blocks on e)0 12 Q -.15(ve)-.25 G (ry request and cannot skip at all;).15 E(adv)0 24 Q (anced clients may use)-.25 E (mmap\(2\))0 36 Q (to read the entire \214le into memory at once and return the)0 48 Q (entire \214le to libarchi)0 60 Q .3 -.15(ve a)-.25 H 2.5(sas).15 G (ingle block;)-2.5 E(other clients may be)0 72 Q (gin asynchronous I/O operations for the)-.15 E 0 Cg EP %%Page: 22 22 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF(ne)0 12 Q(xt block on each request.)-.15 E (
)36
36 Q 2.5(As)0 48 S(ubsequent call to the)-2.5 E
(consume\(\))0 60 Q(function adv)0 72 Q
(ances the read pointer)-.25 E(.)-.55 E 0 Cg EP
%%Page: 25 25
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(Note that data returned from a)0 12 Q
(read_ahead\(\))0 24 Q
(call is guaranteed to remain in place until)0 36 Q(the ne)0 48 Q
(xt call to)-.15 E(read_ahead\(\).)0 60 Q(Interv)0
72 Q(ening calls to)-.15 E 0 Cg EP
%%Page: 26 26
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(consume\(\))0 12 Q
(should not cause the data to mo)0 24 Q -.15(ve)-.15 G(.).15 E(
)36 36 Q(Skip requests must al)0 48 Q -.1(wa)-.1 G(ys be handled e).1 E(xactly) -.15 E(.)-.65 E(Decompression handlers that cannot seek forw)0 60 Q (ard should)-.1 E(not re)0 72 Q(gister a skip handler;)-.15 E 0 Cg EP %%Page: 27 27 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF(the API layer \214lls in a generic skip handler\ that reads and discards data.)0 12 Q(
)36 24 Q 2.5(Ad)0 36 S (ecompression handler has a speci\214c lifec)-2.5 E(ycle:)-.15 E (
)36 36 Q(The v)0 48 Q (alue returned by the bid function indicates its suitability)-.25 E (for handling this data stream.)0 60 Q 2.5(Ab)0 72 S (id of zero will ensure that this decompressor is ne)-2.5 E -.15(ve)-.25 G 2.5(ri).15 G -1.9 -.4(nv o)-2.5 H -.1(ke).4 G(d.).1 E 0 Cg EP %%Page: 32 32 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF(Return zero if magic number checks f)0 12 Q (ail.)-.1 E(Otherwise, your initial implementation should return the nu\ mber of bits)0 24 Q(actually check)0 36 Q(ed.)-.1 E -.15(Fo)0 48 S 2.5 (re).15 G(xample, if you v)-2.65 E(erify tw)-.15 E 2.5(of)-.1 G (ull bytes and three bits of another)-2.5 E(byte, bid 19.)0 60 Q (Note that the initial block may be v)0 72 Q(ery short;)-.15 E 0 Cg EP %%Page: 33 33 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF(be careful to only inspect the data you are gi)0 12 Q -.15(ve)-.25 G(n.).15 E(\(The current decompressors require tw)0 24 Q 2.5(ob)-.1 G(ytes for correct bidding.\))-2.5 E(
)36 12 Q -.15(Fo)0 24 S 2.5(re).15 G (xample, libarchi)-2.65 E -.15(ve)-.25 G 1.1 -.55('s I).15 H (SO9660 support operates v).55 E(ery dif)-.15 E(ferently)-.25 E (from most ISO9660 readers.)0 36 Q(The libarchi)0 48 Q .3 -.15(ve s)-.25 H(upport utilizes a w).15 E(ork-queue design that)-.1 E -.1(ke)0 60 S (eps a list of kno).1 E (wn entries sorted by their location in the input.)-.25 E(Whene)0 72 Q -.15(ve)-.25 G 2.5(rl).15 G(ibarchi)-2.5 E -.15(ve)-.25 G 1.1 -.55('s I) .15 H(SO9660 implementation is ask).55 E(ed for the ne)-.1 E(xt)-.15 E 0 Cg EP %%Page: 60 60 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF(header)0 12 Q 2.5(,c)-.4 G (hecks this list to \214nd the ne)-2.5 E(xt item on the disk.)-.15 E (Directories are parsed when the)0 24 Q 2.5(ya)-.15 G (re encountered and ne)-2.5 E(w)-.25 E(items are added to the list.)0 36 Q(This design relies hea)0 48 Q (vily on the ISO9660 image being optimized so that)-.2 E(directories al) 0 60 Q -.1(wa)-.1 G(ys occur earlier on the disk than the \214les the).1 E(y)-.15 E(describe.)0 72 Q 0 Cg EP %%Page: 61 61 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF(
)36 12 Q(Depending on the speci\214c format,\ such approaches may not be possible.)0 24 Q (The ZIP format speci\214cation, for e)0 36 Q(xample, allo)-.15 E (ws archi)-.25 E -.15(ve)-.25 G(rs to store).15 E -.1(ke)0 48 S 2.5(yi) -.05 G(nformation only at the end of the \214le.)-2.5 E(In theory)0 60 Q 2.5(,i)-.65 G 2.5(ti)-2.5 G 2.5(sp)-2.5 G(ossible to create ZIP archi) -2.5 E -.15(ve)-.25 G 2.5(st).15 G(hat cannot)-2.5 E (be read without seeking.)0 72 Q 0 Cg EP %%Page: 62 62 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF -.15(Fo)0 12 S(rtunately).15 E 2.5(,s)-.65 G (uch archi)-2.5 E -.15(ve)-.25 G 2.5(sa).15 G(re v)-2.5 E (ery rare, and libarchi)-.15 E .3 -.15(ve c)-.25 H(an read).15 E (most ZIP archi)0 24 Q -.15(ve)-.25 G(s, though it cannot al).15 E -.1 (wa)-.1 G(ys e).1 E(xtract as much information)-.15 E (as a dedicated ZIP program.)0 36 Q(
)36 48 Q(The)0 60 Q(libarchi)0 72 Q -.15(ve)-.25 G().15 E 0 Cg EP %%Page: 66 66 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF(library w)0 12 Q(as written by)-.1 E -.35(Ti)0 24 S 2.5(mK).35 G(ientzle <kientzle@@acm.or)-2.5 E(g>.)-.18 E ()0 36 Q()0 48 Q 0 Cg EP %%Trailer end %%EOF @ 1.1.1.5 log @Import libarchive-3.2.1: - security fixes and other bugfixes - support for multhreading in xz 5.2+ @ text @d1 890 a890 374
LIBARCHIVE_INTERNALS(3) BSD Library Functions Manual LIBARCHIVE_INTERNALS(3)
NAME
libarchive_internals — description of libarchive internal interfaces
OVERVIEW
The libarchive library provides a flexible interface for reading and writing streaming archive files such as tar and cpio. Internally, it follows a modular layered design that should make it easy to add new archive and compression formats.
GENERAL ARCHITECTURE
Externally, libarchive exposes most operations through an opaque, object-style interface. The archive_entry(3) objects store information about a single filesystem object. The rest of the library provides facilities to write archive_entry(3) objects to archive files, read them from archive files, and write them to disk. (There are plans to add a facility to read archive_entry(3) objects from disk as well.)
The read and write APIs each have four layers: a public API layer, a format layer that understands the archive file format, a compression layer, and an I/O layer. The I/O layer is completely exposed to clients who can replace it entirely with their own functions.
In order to provide as much consistency as possible for clients, some public functions are virtualized. Eventually, it should be possible for clients to open an archive or disk writer, and then use a single set of code to select and write entries, regardless of the target.
READ ARCHITECTURE
From the outside, clients use the archive_read(3) API to manipulate an archive object to read entries and bodies from an archive stream. Internally, the archive object is cast to an archive_read object, which holds all read-specific data. The API has four layers: The lowest layer is the I/O layer. This layer can be overridden by clients, but most clients use the packaged I/O callbacks provided, for example, by archive_read_open_memory(3), and archive_read_open_fd(3). The compression layer calls the I/O layer to read bytes and decompresses them for the format layer. The format layer unpacks a stream of uncompressed bytes and creates archive_entry objects from the incoming data. The API layer tracks overall state (for example, it prevents clients from reading data before reading a header) and invokes the format and compression layer operations through registered function pointers. In particular, the API layer drives the format-detection process: When opening the archive, it reads an initial block of data and offers it to each registered compression handler. The one with the highest bid is initialized with the first block. Similarly, the format handlers are polled to see which handler is the best for each archive. (Prior to 2.4.0, the format bidders were invoked for each entry, but this design hindered error recovery.)
I/O Layer and
Client Callbacks
The read API goes to some lengths to be nice to clients. As
a result, there are few restrictions on the behavior of the
client callbacks.
The client read callback is expected to provide a block of data on each call. A zero-length return does indicate end of file, but otherwise blocks may be as small as one byte or as large as the entire file. In particular, blocks may be of different sizes.
The client skip callback returns the number of bytes actually skipped, which may be much smaller than the skip requested. The only requirement is that the skip not be larger. In particular, clients are allowed to return zero for any skip that they don’t want to handle. The skip callback must never be invoked with a negative value.
Keep in mind that not all clients are reading from disk: clients reading from networks may provide different-sized blocks on every request and cannot skip at all; advanced clients may use mmap(2) to read the entire file into memory at once and return the entire file to libarchive as a single block; other clients may begin asynchronous I/O operations for the next block on each request.
Decompresssion
Layer
The decompression layer not only handles decompression, it
also buffers data so that the format handlers see a much
nicer I/O model. The decompression API is a two stage
peek/consume model. A read_ahead request specifies a minimum
read amount; the decompression layer must provide a pointer
to at least that much data. If more data is immediately
available, it should return more: the format layer handles
bulk data reads by asking for a minimum of one byte and then
copying as much data as is available.
A subsequent call to the consume() function advances the read pointer. Note that data returned from a read_ahead() call is guaranteed to remain in place until the next call to read_ahead(). Intervening calls to consume() should not cause the data to move.
Skip requests must always be handled exactly. Decompression handlers that cannot seek forward should not register a skip handler; the API layer fills in a generic skip handler that reads and discards data.
A decompression handler has a specific lifecycle:
Registration/Configuration
When the client invokes the public support function, the decompression handler invokes the internal __archive_read_register_compression() function to provide bid and initialization functions. This function returns NULL on error or else a pointer to a struct decompressor_t. This structure contains a void * config slot that can be used for storing any customization information.
Bid
The bid function is invoked with a pointer and size of a block of data. The decompressor can access its config data through the decompressor element of the archive_read object. The bid function is otherwise stateless. In particular, it must not perform any I/O operations.
The value returned by the bid function indicates its suitability for handling this data stream. A bid of zero will ensure that this decompressor is never invoked. Return zero if magic number checks fail. Otherwise, your initial implementation should return the number of bits actually checked. For example, if you verify two full bytes and three bits of another byte, bid 19. Note that the initial block may be very short; be careful to only inspect the data you are given. (The current decompressors require two bytes for correct bidding.)
Initialize
The winning bidder will have its init function called. This function should initialize the remaining slots of the struct decompressor_t object pointed to by the decompressor element of the archive_read object. In particular, it should allocate any working data it needs in the data slot of that structure. The init function is called with the block of data that was used for tasting. At this point, the decompressor is responsible for all I/O requests to the client callbacks. The decompressor is free to read more data as and when necessary.
Satisfy I/O requests
The format handler will invoke the read_ahead, consume, and skip functions as needed.
Finish
The finish method is called only once when the archive is closed. It should release anything stored in the data and config slots of the decompressor object. It should not invoke the client close callback.
Format
Layer
The read formats have a similar lifecycle to the
decompression handlers:
Registration
Allocate your private data and initialize your pointers.
Bid
Formats bid by invoking the read_ahead() decompression method but not calling the consume() method. This allows each bidder to look ahead in the input stream. Bidders should not look further ahead than necessary, as long look aheads put pressure on the decompression layer to buffer lots of data. Most formats only require a few hundred bytes of look ahead; look aheads of a few kilobytes are reasonable. (The ISO9660 reader sometimes looks ahead by 48k, which should be considered an upper limit.)
Read header
The header read is usually the most complex part of any format. There are a few strategies worth mentioning: For formats such as tar or cpio, reading and parsing the header is straightforward since headers alternate with data. For formats that store all header data at the beginning of the file, the first header read request may have to read all headers into memory and store that data, sorted by the location of the file data. Subsequent header read requests will skip forward to the beginning of the file data and return the corresponding header.
Read Data
The read data interface supports sparse files; this requires that each call return a block of data specifying the file offset and size. This may require you to carefully track the location so that you can return accurate file offsets for each read. Remember that the decompressor will return as much data as it has. Generally, you will want to request one byte, examine the return value to see how much data is available, and possibly trim that to the amount you can use. You should invoke consume for each block just before you return it.
Skip All Data
The skip data call should skip over all file data and trailing padding. This is called automatically by the API layer just before each header read. It is also called in response to the client calling the public data_skip() function.
Cleanup
On cleanup, the format should release all of its allocated memory.
API Layer
XXX to do XXX
WRITE ARCHITECTURE
The write API has a similar set of four layers: an API layer, a format layer, a compression layer, and an I/O layer. The registration here is much simpler because only one format and one compression can be registered at a time.
I/O Layer and
Client Callbacks
XXX To be written XXX
Compression
Layer
XXX To be written XXX
Format
Layer
XXX To be written XXX
API Layer
XXX To be written XXX
WRITE_DISK ARCHITECTURE
The write_disk API is intended to look just like the write API to clients. Since it does not handle multiple formats or compression, it is not layered internally.
GENERAL SERVICES
The archive_read, archive_write, and archive_write_disk objects all contain an initial archive object which provides common support for a set of standard services. (Recall that ANSI/ISO C90 guarantees that you can cast freely between a pointer to a structure and a pointer to the first element of that structure.) The archive object has a magic value that indicates which API this object is associated with, slots for storing error information, and function pointers for virtualized API functions.
MISCELLANEOUS NOTES
Connecting existing archiving libraries into libarchive is generally quite difficult. In particular, many existing libraries strongly assume that you are reading from a file; they seek forwards and backwards as necessary to locate various pieces of information. In contrast, libarchive never seeks backwards in its input, which sometimes requires very different approaches.
For example, libarchive’s ISO9660 support operates very differently from most ISO9660 readers. The libarchive support utilizes a work-queue design that keeps a list of known entries sorted by their location in the input. Whenever libarchive’s ISO9660 implementation is asked for the next header, checks this list to find the next item on the disk. Directories are parsed when they are encountered and new items are added to the list. This design relies heavily on the ISO9660 image being optimized so that directories always occur earlier on the disk than the files they describe.
Depending on the specific format, such approaches may not be possible. The ZIP format specification, for example, allows archivers to store key information only at the end of the file. In theory, it is possible to create ZIP archives that cannot be read without seeking. Fortunately, such archives are very rare, and libarchive can read most ZIP archives, though it cannot always extract as much information as a dedicated ZIP program.
SEE ALSO
archive_entry(3), archive_read(3), archive_write(3), archive_write_disk(3) libarchive(3),
HISTORY
The libarchive library first appeared in FreeBSD 5.3.
AUTHORS
The libarchive library was written by Tim Kientzle <kientzle@@acm.org>.
BSD January 26, 2011 BSD
Decompression @ 1.1.1.13 log @libarchive: imported version 3.7.5 Libarchive 3.7.5 Security fixes: fix multiple vulnerabilities identified by SAST cpio: ignore out-of-range gid/uid/size/ino and harden AFIO parsing lzop: prevent integer overflow rar4: protect copy_from_lzss_window_to_unp() rar4: fix CVE-2024-26256 rar4: fix OOB in delta and audio filter rar4: fix out of boundary access with large files rar4: add boundary checks to rgb filter rar4: fix OOB access with unicode filenames rar5: clear 'data ready' cache on window buffer reallocs rpm: calculate huge header sizes correctly unzip: unify EOF handling util: fix out of boundary access in mktemp functions uu: stop processing if lines are too long Important bugfixes: 7zip: fix issue when skipping first file in 7zip archive that is a multiple of 65536 bytes ar: fix archive entries having no type lha: do not allow negative file sizes lha: fix integer truncation on 32-bit systems shar: check strdup return value rar5: don't try to read rediculously long names xar: fix another infinite loop and expat error handling many Windows fixes, cleanups and improvements @ text @d2 1 a2 1 @ 1.1.1.14 log @libarchove: import version 3.7.7 @ text @d1 2 a2 2 d23 2 a24 2
LIBARCHIVE_INTERNALS(3) Library Functions Manual LIBARCHIVE_INTERNALS(3)
d28 2 a29 2libarchive_internals — description of libarchive internal interfaces
d33 1 a33 1The libarchive library d41 1 a41 1
Externally, libarchive exposes d43 6 a48 6 The archive_entry(3) objects store information about a single filesystem object. The rest of the library provides facilities to write archive_entry(3) objects to archive files, read them from archive files, and write them to disk. (There are plans to add a facility to read archive_entry(3) objects from disk as well.)
d50 1 a50 1The read and d57 1 a57 1
In order to d66 15 a80 16
From the outside, clients use the archive_read(3) API to manipulate an archive object to read entries and bodies from an archive stream. Internally, the archive object is cast to an archive_read object, which holds all read-specific data. The API has four layers: The lowest layer is the I/O layer. This layer can be overridden by clients, but most clients use the packaged I/O callbacks provided, for example, by archive_read_open_memory(3), and archive_read_open_fd(3). The compression layer calls the I/O layer to read bytes and decompresses them for the format layer. The format layer unpacks a stream of uncompressed bytes and creates archive_entry objects from the incoming data. The API layer tracks overall state (for example, it prevents clients from reading data before d92 5 a96 2
I/O Layer and Client Callbacks
d98 1 a98 5The read API goes to some lengths to be nice to clients. As a result, there are few restrictions on the behavior of the client callbacks.
The client read d105 1 a105 1
The client skip d113 1 a113 1
Keep in mind d117 2 a118 2 mmap(2) to read the entire file into memory at once and return the entire file to libarchive as a single block; d123 11 a133 13
Decompression Layer
The decompression layer not only handles decompression, it also buffers data so that the format handlers see a much nicer I/O model. The decompression API is a two stage peek/consume model. A read_ahead request specifies a minimum read amount; the decompression layer must provide a pointer to at least that much data. If more data is immediately available, it should return more: the format layer handles bulk data reads by asking for a minimum of one byte and then copying as much data as is available.
d135 1 a135 1A subsequent d142 1 a142 1
Skip requests d148 1 a148 1
A decompression d153 1 a153 1
When the client invokes the d164 1 a164 1
The bid d171 1 a171 1
The value d185 1 a185 1
The winning bidder will have d199 1 a199 1
The format handler will invoke d205 1 a205 1
The finish d211 4 a214 5
Format Layer
The read formats have a similar lifecycle to the decompression handlers:
d218 1 a218 1Allocate your private data and d223 1 a223 1
Formats bid by d236 1 a236 1
The header read is usually the d249 1 a249 1
The read data interface d262 1 a262 1
The skip data call should skip d270 1 a270 1
On cleanup, the format should d273 3 a275 4
API Layer
XXX to do XXX
d279 1 a279 1The write API has a similar set d285 15 a299 19
I/O Layer and Client Callbacks
XXX To be written XXX
Compression Layer
XXX To be written XXX
Format Layer
XXX To be written XXX
API Layer
XXX To be written XXX
d304 1 a304 1The write_disk API is intended d311 1 a311 1
The archive_read, d324 1 a324 1
Connecting existing archiving d332 1 a332 1
For example, d344 1 a344 1
Depending on the d356 3 a358 3
archive_entry(3), archive_read(3), archive_write(3), archive_write_disk(3), libarchive(3)
d362 1 a362 1The libarchive library d367 5 a371 3
The libarchive library was written by Tim Kientzle <kientzle@@acm.org>. Debian January 26, 2011 LIBARCHIVE_INTERNALS(3)
@ 1.1.1.15 log @libarchive: imported version 3.7.9 @ text @d2 1 a2 1 @ 1.1.1.16 log @libarchive: import version 3.8.0 Libarchive 3.8.0 is a feature and bugfix release. New features: bsdtar: support --mtime and --clamp-mtime lib: mbedtls 3.x compatibility 7-zip reader: improve self-extracting archive detection xar: xmllite support for the XAR reader and writer zip writer: added XZ, LZMA, ZSTD and BZIP2 support zip writer: added LZMA + RISCV BCJ filter Notable security fixes: rar: do not skip past EOF while reading rar: fix double free with over 4 billion nodes rar: fix heap-buffer-overflow warc: prevent signed integer overflow tar: fix overflow in build_ustar_entry Notable bugfixes: bsdtar: don't hardlink negative inode files together gz: allow setting the original filename for gzip compressed files lib: improve lseek handling lib: support @@-prefixed Unix epoch timestamps as date strings rar: support large headers on 32 bit systems tar reader: Improve LFS support on 32 bit systems @ text @d2 1 a2 1 @ 1.1.1.17 log @libarchive: import version 3.8.1 @ text @d2 1 a2 1 @ 1.1.1.18 log @libarchive: imported version 3.8.2 @ text @d2 1 a2 1 @ 1.1.1.19 log @libarchive: import version 3.8.3 @ text @d2 1 a2 1 @ 1.1.1.20 log @libarchive: import 3.8.4 @ text @d2 1 a2 1 @ 1.1.1.21 log @libarchive: import version 3.8.5 @ text @d2 1 a2 1 @ 1.1.1.22 log @libarchive: imported version 3.8.6 @ text @d2 1 a2 1 @ 1.1.1.23 log @libarchive: imported version 3.8.7 @ text @d2 1 a2 1 @ 1.1.1.24 log @libarchive: import 3.8.8 @ text @d2 1 a2 1 @