1 files changed, 891 insertions, 381 deletions
diff --git a/archivers/libarchive/files/doc/html/libarchive_internals.3.html b/archivers/libarchive/files/doc/html/libarchive_internals.3.html
index 31c716a0f74..62f4277aa00 100644
--- a/archivers/libarchive/files/doc/html/libarchive_internals.3.html
+++ b/archivers/libarchive/files/doc/html/libarchive_internals.3.html
@@ -1,381 +1,891 @@
-<!-- Creator     : groff version 1.19.2 -->
-<!-- CreationDate: Thu Feb  4 20:36:36 2010 -->
-<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
-"http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta name="generator" content="groff -Thtml, see www.gnu.org">
-<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
-<meta name="Content-Style" content="text/css">
-<style type="text/css">
-       p     { margin-top: 0; margin-bottom: 0; }
-       pre   { margin-top: 0; margin-bottom: 0; }
-       table { margin-top: 0; margin-bottom: 0; }
-</style>
-<title></title>
-</head>
-<body>
-
-<hr>
-
-
-<p valign="top">LIBARCHIVE(3) FreeBSD Library Functions
-Manual LIBARCHIVE(3)</p>
-
-<p style="margin-top: 1em" valign="top"><b>NAME</b></p>
-
-<p style="margin-left:8%;"><b>libarchive_internals</b>
-&mdash; description of libarchive internal interfaces</p>
-
-
-<p style="margin-top: 1em" valign="top"><b>OVERVIEW</b></p>
-
-<p style="margin-left:8%;">The <b>libarchive</b> 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.</p>
-
-<p style="margin-top: 1em" valign="top"><b>GENERAL
-ARCHITECTURE</b></p>
-
-<p style="margin-left:8%;">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.)</p>
-
-<p style="margin-left:8%; margin-top: 1em">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.</p>
-
-<p style="margin-left:8%; margin-top: 1em">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.</p>
-
-<p style="margin-top: 1em" valign="top"><b>READ
-ARCHITECTURE</b></p>
-
-<p style="margin-left:8%;">From the outside, clients use
-the archive_read(3) API to manipulate an <b>archive</b>
-object to read entries and bodies from an archive stream.
-Internally, the <b>archive</b> object is cast to an
-<b>archive_read</b> 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 <b>archive_entry</b> 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.)</p>
-
-<p style="margin-left:8%; margin-top: 1em"><b>I/O Layer and
-Client Callbacks</b> <br>
-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.</p>
-
-<p style="margin-left:8%; margin-top: 1em">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.</p>
-
-<p style="margin-left:8%; margin-top: 1em">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&rsquo;t want to handle. The skip callback must never be
-invoked with a negative value.</p>
-
-<p style="margin-left:8%; margin-top: 1em">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.</p>
-
-
-<p style="margin-left:8%; margin-top: 1em"><b>Decompresssion
-Layer</b> <br>
-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.</p>
-
-<p style="margin-left:8%; margin-top: 1em">A subsequent
-call to the <b>consume</b>() function advances the read
-pointer. Note that data returned from a <b>read_ahead</b>()
-call is guaranteed to remain in place until the next call to
-<b>read_ahead</b>(). Intervening calls to <b>consume</b>()
-should not cause the data to move.</p>
-
-<p style="margin-left:8%; margin-top: 1em">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.</p>
-
-<p style="margin-left:8%; margin-top: 1em">A decompression
-handler has a specific lifecycle:</p>
-
-<p valign="top">Registration/Configuration</p>
-
-<p style="margin-left:20%;">When the client invokes the
-public support function, the decompression handler invokes
-the internal <b>__archive_read_register_compression</b>()
-function to provide bid and initialization functions. This
-function returns <b>NULL</b> on error or else a pointer to a
-<b>struct decompressor_t</b>. This structure contains a
-<i>void * config</i> slot that can be used for storing any
-customization information.</p>
-
-<p valign="top">Bid</p>
-
-<p style="margin-left:20%; margin-top: 1em">The bid
-function is invoked with a pointer and size of a block of
-data. The decompressor can access its config data through
-the <i>decompressor</i> element of the <b>archive_read</b>
-object. The bid function is otherwise stateless. In
-particular, it must not perform any I/O operations.</p>
-
-<p style="margin-left:20%; margin-top: 1em">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.)</p>
-
-<p valign="top">Initialize</p>
-
-<p style="margin-left:20%;">The winning bidder will have
-its init function called. This function should initialize
-the remaining slots of the <i>struct decompressor_t</i>
-object pointed to by the <i>decompressor</i> element of the
-<i>archive_read</i> object. In particular, it should
-allocate any working data it needs in the <i>data</i> 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.</p>
-
-<p valign="top">Satisfy I/O requests</p>
-
-<p style="margin-left:20%;">The format handler will invoke
-the <i>read_ahead</i>, <i>consume</i>, and <i>skip</i>
-functions as needed.</p>
-
-<p valign="top">Finish</p>
-
-<p style="margin-left:20%; margin-top: 1em">The finish
-method is called only once when the archive is closed. It
-should release anything stored in the <i>data</i> and
-<i>config</i> slots of the <i>decompressor</i> object. It
-should not invoke the client close callback.</p>
-
-<p style="margin-left:8%; margin-top: 1em"><b>Format
-Layer</b> <br>
-The read formats have a similar lifecycle to the
-decompression handlers:</p>
-
-<p valign="top">Registration</p>
-
-<p style="margin-left:20%;">Allocate your private data and
-initialize your pointers.</p>
-
-<p valign="top">Bid</p>
-
-<p style="margin-left:20%; margin-top: 1em">Formats bid by
-invoking the <b>read_ahead</b>() decompression method but
-not calling the <b>consume</b>() 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.)</p>
-
-<p valign="top">Read header</p>
-
-<p style="margin-left:20%;">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.</p>
-
-<p valign="top">Read Data</p>
-
-<p style="margin-left:20%;">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.</p>
-
-<p valign="top">Skip All Data</p>
-
-<p style="margin-left:20%;">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 <b>data_skip</b>() function.</p>
-
-<p valign="top">Cleanup</p>
-
-<p style="margin-left:20%;">On cleanup, the format should
-release all of its allocated memory.</p>
-
-<p style="margin-left:8%; margin-top: 1em"><b>API Layer</b>
-<br>
-XXX to do XXX</p>
-
-<p style="margin-top: 1em" valign="top"><b>WRITE
-ARCHITECTURE</b></p>
-
-<p style="margin-left:8%;">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.</p>
-
-<p style="margin-left:8%; margin-top: 1em"><b>I/O Layer and
-Client Callbacks</b> <br>
-XXX To be written XXX</p>
-
-<p style="margin-left:8%; margin-top: 1em"><b>Compression
-Layer</b> <br>
-XXX To be written XXX</p>
-
-<p style="margin-left:8%; margin-top: 1em"><b>Format
-Layer</b> <br>
-XXX To be written XXX</p>
-
-<p style="margin-left:8%; margin-top: 1em"><b>API Layer</b>
-<br>
-XXX To be written XXX</p>
-
-<p style="margin-top: 1em" valign="top"><b>WRITE_DISK
-ARCHITECTURE</b></p>
-
-<p style="margin-left:8%;">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.</p>
-
-<p style="margin-top: 1em" valign="top"><b>GENERAL
-SERVICES</b></p>
-
-<p style="margin-left:8%;">The <b>archive_read</b>,
-<b>archive_write</b>, and <b>archive_write_disk</b> objects
-all contain an initial <b>archive</b> 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 <b>archive</b> 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.</p>
-
-<p style="margin-top: 1em" valign="top"><b>MISCELLANEOUS
-NOTES</b></p>
-
-<p style="margin-left:8%;">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.</p>
-
-<p style="margin-left:8%; margin-top: 1em">For example,
-libarchive&rsquo;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&rsquo;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.</p>
-
-<p style="margin-left:8%; margin-top: 1em">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.</p>
-
-<p style="margin-top: 1em" valign="top"><b>SEE ALSO</b></p>
-
-<p style="margin-left:8%;">archive(3), archive_entry(3),
-archive_read(3), archive_write(3), archive_write_disk(3)</p>
-
-<p style="margin-top: 1em" valign="top"><b>HISTORY</b></p>
-
-<p style="margin-left:8%;">The <b>libarchive</b> library
-first appeared in FreeBSD&nbsp;5.3.</p>
-
-<p style="margin-top: 1em" valign="top"><b>AUTHORS</b></p>
-
-<p style="margin-left:8%;">The <b>libarchive</b> library
-was written by Tim Kientzle
-&lang;kientzle@acm.org&rang;.</p>
-
-<p style="margin-top: 1em" valign="top"><b>BUGS</b></p>
-
-<p style="margin-left:8%;">FreeBSD&nbsp;8.0 April&nbsp;16,
-2007 FreeBSD&nbsp;8.0</p>
-<hr>
-</body>
-</html>
+%!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(<html>)0 12 Q(<head>)0 24 Q(<title>)36 36 Q
+(April 16, 2007 LIB)74.5 48 Q(ARCHIVE 3)-.35 E(</title>)36 72 Q 0 Cg EP
+%%Page: 2 2
+%%BeginPageSetup
+BP
+%%EndPageSetup
+/F0 10/Times-Roman@0 SF(<style type="te)36 12 Q(xt/css">)-.15 E(<!--)36
+24 Q(body { mar)72 36 Q(gin-left:4%; })-.18 E(H1, H2, H3, H4, H5 {)72 48
+Q(color: maroon; padding: 4pt; mar)108 60 Q(gin-left: -4%;)-.18 E
+(border: solid; border)108 72 Q(-width: thin; width: 100%;)-.2 E 0 Cg EP
+%%Page: 3 3
+%%BeginPageSetup
+BP
+%%EndPageSetup
+/F0 10/Times-Roman@0 SF(background: r)108 12 Q(gb\(204,204,255\))-.18 E
+(})72 24 Q(-->)36 36 Q(</style>)36 48 Q(</head>)0 60 Q
+(<body bgcolor="#FFFFFF" te)0 72 Q(xt="#000000">)-.15 E 0 Cg EP
+%%Page: 4 4
+%%BeginPageSetup
+BP
+%%EndPageSetup
+/F0 10/Times-Roman@0 SF(<h3 id="N)36 12 Q(AME">)-.35 E -.35(NA)36 24 S
+(ME).35 E(</h3>)36 36 Q(<b>libarchi)0 48 Q -.15(ve)-.25 G
+(_internals</b>).15 E 2.5(-d)0 60 S(escription of libarchi)-2.5 E .3
+-.15(ve i)-.25 H(nternal interf).15 E(aces)-.1 E(<h3 id="O)36 72 Q(VER)
+-.5 E(VIEW">)-.8 E 0 Cg EP
+%%Page: 5 5
+%%BeginPageSetup
+BP
+%%EndPageSetup
+/F0 10/Times-Roman@0 SF -.5(OV)36 12 S(ER).5 E(VIEW)-.8 E(</h3>)36 24 Q
+(The)0 36 Q(<b>libarchi)0 48 Q -.15(ve)-.25 G(</b>).15 E(library pro)0
+60 Q(vides a \215e)-.15 E(xible interf)-.15 E
+(ace for reading and writing)-.1 E(streaming archi)0 72 Q .3 -.15
+(ve \214)-.25 H(les such as tar and cpio.).15 E 0 Cg EP
+%%Page: 6 6
+%%BeginPageSetup
+BP
+%%EndPageSetup
+/F0 10/Times-Roman@0 SF(Internally)0 12 Q 2.5(,i)-.65 G 2.5(tf)-2.5 G
+(ollo)-2.5 E(ws a modular layered design that should)-.25 E(mak)0 24 Q
+2.5(ei)-.1 G 2.5(te)-2.5 G(asy to add ne)-2.5 E 2.5(wa)-.25 G(rchi)-2.5
+E .3 -.15(ve a)-.25 H(nd compression formats.).15 E
+(<h3 id="GENERAL ARCHITECTURE">)36 36 Q(GENERAL ARCHITECTURE)36 48 Q
+(</h3>)36 60 Q(Externally)0 72 Q 2.5(,l)-.65 G(ibarchi)-2.5 E .3 -.15
+(ve ex)-.25 H(poses most operations through an).15 E 0 Cg EP
+%%Page: 7 7
+%%BeginPageSetup
+BP
+%%EndPageSetup
+/F0 10/Times-Roman@0 SF(opaque, object-style interf)0 12 Q(ace.)-.1 E
+(The)0 24 Q(<a href="../html1/archi)0 36 Q -.15(ve)-.25 G(_entry).15 E
+(.html">archi)-.65 E -.15(ve)-.25 G(_entry\(1\)</a>).15 E
+(objects store information about a single \214lesystem object.)0 48 Q
+(The rest of the library pro)0 60 Q(vides f)-.15 E(acilities to write)
+-.1 E(<a href="../html1/archi)0 72 Q -.15(ve)-.25 G(_entry).15 E
+(.html">archi)-.65 E -.15(ve)-.25 G(_entry\(1\)</a>).15 E 0 Cg EP
+%%Page: 8 8
+%%BeginPageSetup
+BP
+%%EndPageSetup
+/F0 10/Times-Roman@0 SF(objects to archi)0 12 Q .3 -.15(ve \214)-.25 H
+(les,).15 E(read them from archi)0 24 Q .3 -.15(ve \214)-.25 H(les,).15
+E(and write them to disk.)0 36 Q(\(There are plans to add a f)0 48 Q
+(acility to read)-.1 E(<a href="../html1/archi)0 60 Q -.15(ve)-.25 G
+(_entry).15 E(.html">archi)-.65 E -.15(ve)-.25 G(_entry\(1\)</a>).15 E
+(objects from disk as well.\))0 72 Q 0 Cg EP
+%%Page: 9 9
+%%BeginPageSetup
+BP
+%%EndPageSetup
+/F0 10/Times-Roman@0 SF(<p>)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(<p>)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(<h3 id="READ ARCHITECTURE">)36 12 Q
+(READ ARCHITECTURE)36 24 Q(</h3>)36 36 Q
+(From the outside, clients use the)0 48 Q(<a href="../html3/archi)0 60 Q
+-.15(ve)-.25 G(_read.html">archi).15 E -.15(ve)-.25 G(_read\(3\)</a>).15
+E(API to manipulate an)0 72 Q 0 Cg EP
+%%Page: 12 12
+%%BeginPageSetup
+BP
+%%EndPageSetup
+/F0 10/Times-Roman@0 SF(<b>archi)0 12 Q -.15(ve)-.25 G(</b>).15 E
+(object to read entries and bodies from an archi)0 24 Q .3 -.15(ve s)
+-.25 H(tream.).15 E(Internally)0 36 Q 2.5(,t)-.65 G(he)-2.5 E(<b>archi)0
+48 Q -.15(ve)-.25 G(</b>).15 E(object is cast to an)0 60 Q(<b>archi)0 72
+Q -.15(ve)-.25 G(_read</b>).15 E 0 Cg EP
+%%Page: 13 13
+%%BeginPageSetup
+BP
+%%EndPageSetup
+/F0 10/Times-Roman@0 SF(object, which holds all read-speci\214c data.)0
+12 Q(The API has four layers:)0 24 Q(The lo)0 36 Q
+(west layer is the I/O layer)-.25 E(.)-.55 E(This layer can be o)0 48 Q
+-.15(ve)-.15 G(rridden by clients, b).15 E(ut most clients use)-.2 E
+(the packaged I/O callbacks pro)0 60 Q(vided, for e)-.15 E(xample, by)
+-.15 E(<a href="../html3/archi)0 72 Q -.15(ve)-.25 G(_read_open_memory)
+.15 E(.html">archi)-.65 E -.15(ve)-.25 G(_read_open_memory\(3\)</a>,).15
+E 0 Cg EP
+%%Page: 14 14
+%%BeginPageSetup
+BP
+%%EndPageSetup
+/F0 10/Times-Roman@0 SF(and)0 12 Q(<a href="../html3/archi)0 24 Q -.15
+(ve)-.25 G(_read_open_fd.html">archi).15 E -.15(ve)-.25 G
+(_read_open_fd\(3\)</a>.).15 E
+(The compression layer calls the I/O layer to)0 36 Q
+(read bytes and decompresses them for the format layer)0 48 Q(.)-.55 E
+(The format layer unpacks a stream of uncompressed bytes and)0 60 Q
+(creates)0 72 Q 0 Cg EP
+%%Page: 15 15
+%%BeginPageSetup
+BP
+%%EndPageSetup
+/F0 10/Times-Roman@0 SF(<b>archi)0 12 Q -.15(ve)-.25 G(_entry</b>).15 E
+(objects from the incoming data.)0 24 Q(The API layer tracks o)0 36 Q
+-.15(ve)-.15 G(rall state).15 E(\(for e)0 48 Q(xample, it pre)-.15 E
+-.15(ve)-.25 G(nts clients from reading data before reading a header\))
+.15 E(and in)0 60 Q -.2(vo)-.4 G -.1(ke).2 G 2.5(st).1 G
+(he format and compression layer operations)-2.5 E(through re)0 72 Q
+(gistered function pointers.)-.15 E 0 Cg EP
+%%Page: 16 16
+%%BeginPageSetup
+BP
+%%EndPageSetup
+/F0 10/Times-Roman@0 SF(In particular)0 12 Q 2.5(,t)-.4 G
+(he API layer dri)-2.5 E -.15(ve)-.25 G 2.5(st).15 G
+(he format-detection process:)-2.5 E(When opening the archi)0 24 Q -.15
+(ve)-.25 G 2.5(,i).15 G 2.5(tr)-2.5 G(eads an initial block of data)-2.5
+E(and of)0 36 Q(fers it to each re)-.25 E(gistered compression handler)
+-.15 E(.)-.55 E
+(The one with the highest bid is initialized with the \214rst block.)0
+48 Q(Similarly)0 60 Q 2.5(,t)-.65 G
+(he format handlers are polled to see which handler)-2.5 E
+(is the best for each archi)0 72 Q -.15(ve)-.25 G(.).15 E 0 Cg EP
+%%Page: 17 17
+%%BeginPageSetup
+BP
+%%EndPageSetup
+/F0 10/Times-Roman@0 SF(\(Prior to 2.4.0, the format bidders were in)0
+12 Q -.2(vo)-.4 G -.1(ke).2 G 2.5(df).1 G(or each)-2.5 E(entry)0 24 Q
+2.5(,b)-.65 G(ut this design hindered error reco)-2.7 E -.15(ve)-.15 G
+(ry).15 E(.\))-.65 E(<h4 id="I/O Layer and Client Callbacks">)36 36 Q
+(I/O Layer and Client Callbacks)36 48 Q(</h4>)36 60 Q
+(The read API goes to some lengths to be nice to clients.)0 72 Q 0 Cg EP
+%%Page: 18 18
+%%BeginPageSetup
+BP
+%%EndPageSetup
+/F0 10/Times-Roman@0 SF(As a result, there are fe)0 12 Q 2.5(wr)-.25 G
+(estrictions on the beha)-2.5 E(vior of)-.2 E(the client callbacks.)0 24
+Q(<p>)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(<p>)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
+(<p>)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
+(<a href="../html2/mmap.html">mmap\(2\)</a>)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
+(<h4 id="Decompresssion Layer">)36 24 Q(Decompresssion Layer)36 36 Q
+(</h4>)36 48 Q(The decompression layer not only handles decompression,)0
+60 Q(it also b)0 72 Q(uf)-.2 E
+(fers data so that the format handlers see a)-.25 E 0 Cg EP
+%%Page: 23 23
+%%BeginPageSetup
+BP
+%%EndPageSetup
+/F0 10/Times-Roman@0 SF(much nicer I/O model.)0 12 Q
+(The decompression API is a tw)0 24 Q 2.5(os)-.1 G
+(tage peek/consume model.)-2.5 E 2.5(Ar)0 36 S
+(ead_ahead request speci\214es a minimum read amount;)-2.5 E
+(the decompression layer must pro)0 48 Q(vide a pointer to at least)-.15
+E(that much data.)0 60 Q(If more data is immediately a)0 72 Q -.25(va)
+-.2 G(ilable, it should return more:).25 E 0 Cg EP
+%%Page: 24 24
+%%BeginPageSetup
+BP
+%%EndPageSetup
+/F0 10/Times-Roman@0 SF(the format layer handles b)0 12 Q
+(ulk data reads by asking for a minimum)-.2 E(of one byte and then cop)0
+24 Q(ying as much data as is a)-.1 E -.25(va)-.2 G(ilable.).25 E(<p>)36
+36 Q 2.5(As)0 48 S(ubsequent call to the)-2.5 E
+(<b>consume</b>\(<code></code>\))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
+(<b>read_ahead</b>\(<code></code>\))0 24 Q
+(call is guaranteed to remain in place until)0 36 Q(the ne)0 48 Q
+(xt call to)-.15 E(<b>read_ahead</b>\(<code></code>\).)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(<b>consume</b>\(<code></code>\))0 12 Q
+(should not cause the data to mo)0 24 Q -.15(ve)-.15 G(.).15 E(<p>)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(<p>)36 24 Q 2.5(Ad)0 36 S
+(ecompression handler has a speci\214c lifec)-2.5 E(ycle:)-.15 E
+(<dl compact>)0 48 Q(<dt>Re)0 60 Q(gistration/Con\214guration<dd>)-.15 E
+(When the client in)0 72 Q -.2(vo)-.4 G -.1(ke).2 G 2.5(st).1 G
+(he public support function,)-2.5 E 0 Cg EP
+%%Page: 28 28
+%%BeginPageSetup
+BP
+%%EndPageSetup
+/F0 10/Times-Roman@0 SF(the decompression handler in)0 12 Q -.2(vo)-.4 G
+-.1(ke).2 G 2.5(st).1 G(he internal)-2.5 E(<b>__archi)0 24 Q -.15(ve)
+-.25 G(_read_re).15 E(gister_compression</b>\(<code></code>\))-.15 E
+(function to pro)0 36 Q(vide bid and initialization functions.)-.15 E
+(This function returns)0 48 Q(<b></b><b>NULL</b>)0 60 Q
+(on error or else a pointer to a)0 72 Q 0 Cg EP
+%%Page: 29 29
+%%BeginPageSetup
+BP
+%%EndPageSetup
+/F0 10/Times-Roman@0 SF(<b></b><b>struct</b><b> decompressor_t</b>.)0 12
+Q(This structure contains a)0 24 Q(<i></i><i>v)0 36 Q
+(oid</i><i> *</i><i> con\214g</i>)-.2 E
+(slot that can be used for storing an)0 48 Q 2.5(yc)-.15 G
+(ustomization information.)-2.5 E(<dt>Bid<dd>)0 60 Q
+(The bid function is in)0 72 Q -.2(vo)-.4 G -.1(ke).2 G 2.5(dw).1 G
+(ith a pointer and size of a block of data.)-2.5 E 0 Cg EP
+%%Page: 30 30
+%%BeginPageSetup
+BP
+%%EndPageSetup
+/F0 10/Times-Roman@0 SF(The decompressor can access its con\214g data)0
+12 Q(through the)0 24 Q(<i></i><i>decompressor</i>)0 36 Q
+(element of the)0 48 Q(<b></b><b>archi)0 60 Q -.15(ve)-.25 G(_read</b>)
+.15 E(object.)0 72 Q 0 Cg EP
+%%Page: 31 31
+%%BeginPageSetup
+BP
+%%EndPageSetup
+/F0 10/Times-Roman@0 SF(The bid function is otherwise stateless.)0 12 Q
+(In particular)0 24 Q 2.5(,i)-.4 G 2.5(tm)-2.5 G(ust not perform an)-2.5
+E 2.5(yI)-.15 G(/O operations.)-2.5 E(<p>)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(<dt>Initialize<dd>)0
+36 Q(The winning bidder will ha)0 48 Q .3 -.15(ve i)-.2 H
+(ts init function called.).15 E
+(This function should initialize the remaining slots of the)0 60 Q
+(<i></i><i>struct</i><i> decompressor_t</i>)0 72 Q 0 Cg EP
+%%Page: 34 34
+%%BeginPageSetup
+BP
+%%EndPageSetup
+/F0 10/Times-Roman@0 SF(object pointed to by the)0 12 Q
+(<i></i><i>decompressor</i>)0 24 Q(element of the)0 36 Q
+(<i></i><i>archi)0 48 Q -.15(ve)-.25 G(_read</i>).15 E(object.)0 60 Q
+(In particular)0 72 Q 2.5(,i)-.4 G 2.5(ts)-2.5 G(hould allocate an)-2.5
+E 2.5(yw)-.15 G(orking data it needs)-2.6 E 0 Cg EP
+%%Page: 35 35
+%%BeginPageSetup
+BP
+%%EndPageSetup
+/F0 10/Times-Roman@0 SF(in the)0 12 Q(<i></i><i>data</i>)0 24 Q
+(slot of that structure.)0 36 Q
+(The init function is called with the block of data that)0 48 Q -.1(wa)0
+60 S 2.5(su).1 G(sed for tasting.)-2.5 E
+(At this point, the decompressor is responsible for all I/O)0 72 Q 0 Cg
+EP
+%%Page: 36 36
+%%BeginPageSetup
+BP
+%%EndPageSetup
+/F0 10/Times-Roman@0 SF(requests to the client callbacks.)0 12 Q
+(The decompressor is free to read more data as and when)0 24 Q
+(necessary)0 36 Q(.)-.65 E(<dt>Satisfy I/O requests<dd>)0 48 Q
+(The format handler will in)0 60 Q -.2(vo)-.4 G .2 -.1(ke t).2 H(he).1 E
+(<i></i><i>read_ahead</i>,)0 72 Q 0 Cg EP
+%%Page: 37 37
+%%BeginPageSetup
+BP
+%%EndPageSetup
+/F0 10/Times-Roman@0 SF(<i></i><i>consume</i>,)0 12 Q(and)0 24 Q
+(<i></i><i>skip</i>)0 36 Q(functions as needed.)0 48 Q(<dt>Finish<dd>)0
+60 Q(The \214nish method is called only once when the archi)0 72 Q .3
+-.15(ve i)-.25 H 2.5(sc).15 G(losed.)-2.5 E 0 Cg EP
+%%Page: 38 38
+%%BeginPageSetup
+BP
+%%EndPageSetup
+/F0 10/Times-Roman@0 SF(It should release an)0 12 Q
+(ything stored in the)-.15 E(<i></i><i>data</i>)0 24 Q(and)0 36 Q
+(<i></i><i>con\214g</i>)0 48 Q(slots of the)0 60 Q
+(<i></i><i>decompressor</i>)0 72 Q 0 Cg EP
+%%Page: 39 39
+%%BeginPageSetup
+BP
+%%EndPageSetup
+/F0 10/Times-Roman@0 SF(object.)0 12 Q(It should not in)0 24 Q -.2(vo)
+-.4 G .2 -.1(ke t).2 H(he client close callback.).1 E(</dl>)0 36 Q
+(<h4 id="F)36 48 Q(ormat Layer">)-.15 E -.15(Fo)36 60 S(rmat Layer).15 E
+(</h4>)36 72 Q 0 Cg EP
+%%Page: 40 40
+%%BeginPageSetup
+BP
+%%EndPageSetup
+/F0 10/Times-Roman@0 SF(The read formats ha)0 12 Q .3 -.15(ve a s)-.2 H
+(imilar lifec).15 E(ycle to the decompression handlers:)-.15 E
+(<dl compact>)0 24 Q(<dt>Re)0 36 Q(gistration<dd>)-.15 E
+(Allocate your pri)0 48 Q -.25(va)-.25 G
+(te data and initialize your pointers.).25 E(<dt>Bid<dd>)0 60 Q -.15(Fo)
+0 72 S(rmats bid by in).15 E -.2(vo)-.4 G(king the).2 E 0 Cg EP
+%%Page: 41 41
+%%BeginPageSetup
+BP
+%%EndPageSetup
+/F0 10/Times-Roman@0 SF(<b>read_ahead</b>\(<code></code>\))0 12 Q
+(decompression method b)0 24 Q(ut not calling the)-.2 E
+(<b>consume</b>\(<code></code>\))0 36 Q(method.)0 48 Q(This allo)0 60 Q
+(ws each bidder to look ahead in the input stream.)-.25 E
+(Bidders should not look further ahead than necessary)0 72 Q 2.5(,a)-.65
+G 2.5(sl)-2.5 G(ong)-2.5 E 0 Cg EP
+%%Page: 42 42
+%%BeginPageSetup
+BP
+%%EndPageSetup
+/F0 10/Times-Roman@0 SF
+(look aheads put pressure on the decompression layer to b)0 12 Q(uf)-.2
+E(fer)-.25 E(lots of data.)0 24 Q(Most formats only require a fe)0 36 Q
+2.5(wh)-.25 G(undred bytes of look ahead;)-2.5 E(look aheads of a fe)0
+48 Q 2.5(wk)-.25 G(ilobytes are reasonable.)-2.5 E
+(\(The ISO9660 reader sometimes looks ahead by 48k, which)0 60 Q
+(should be considered an upper limit.\))0 72 Q 0 Cg EP
+%%Page: 43 43
+%%BeginPageSetup
+BP
+%%EndPageSetup
+/F0 10/Times-Roman@0 SF(<dt>Read header<dd>)0 12 Q
+(The header read is usually the most comple)0 24 Q 2.5(xp)-.15 G
+(art of an)-2.5 E 2.5(yf)-.15 G(ormat.)-2.5 E(There are a fe)0 36 Q 2.5
+(ws)-.25 G(trate)-2.5 E(gies w)-.15 E(orth mentioning:)-.1 E -.15(Fo)0
+48 S 2.5(rf).15 G
+(ormats such as tar or cpio, reading and parsing the header is)-2.5 E
+(straightforw)0 60 Q(ard since headers alternate with data.)-.1 E -.15
+(Fo)0 72 S 2.5(rf).15 G(ormats that store all header data at the be)-2.5
+E(ginning of the \214le,)-.15 E 0 Cg EP
+%%Page: 44 44
+%%BeginPageSetup
+BP
+%%EndPageSetup
+/F0 10/Times-Roman@0 SF(the \214rst header read request may ha)0 12 Q .3
+-.15(ve t)-.2 H 2.5(or).15 G(ead all headers into)-2.5 E
+(memory and store that data, sorted by the location of the \214le)0 24 Q
+(data.)0 36 Q(Subsequent header read requests will skip forw)0 48 Q
+(ard to the)-.1 E(be)0 60 Q
+(ginning of the \214le data and return the corresponding header)-.15 E
+(.)-.55 E(<dt>Read Data<dd>)0 72 Q 0 Cg EP
+%%Page: 45 45
+%%BeginPageSetup
+BP
+%%EndPageSetup
+/F0 10/Times-Roman@0 SF(The read data interf)0 12 Q
+(ace supports sparse \214les; this requires that)-.1 E
+(each call return a block of data specifying the \214le of)0 24 Q
+(fset and)-.25 E(size.)0 36 Q
+(This may require you to carefully track the location so that you)0 48 Q
+(can return accurate \214le of)0 60 Q(fsets for each read.)-.25 E
+(Remember that the decompressor will return as much data as it has.)0 72
+Q 0 Cg EP
+%%Page: 46 46
+%%BeginPageSetup
+BP
+%%EndPageSetup
+/F0 10/Times-Roman@0 SF(Generally)0 12 Q 2.5(,y)-.65 G(ou will w)-2.5 E
+(ant to request one byte,)-.1 E -.15(ex)0 24 S(amine the return v).15 E
+(alue to see ho)-.25 E 2.5(wm)-.25 G(uch data is a)-2.5 E -.25(va)-.2 G
+(ilable, and).25 E(possibly trim that to the amount you can use.)0 36 Q
+-1.1(Yo)0 48 S 2.5(us)1.1 G(hould in)-2.5 E -.2(vo)-.4 G .2 -.1(ke c).2
+H(onsume for each block just before you return it.).1 E
+(<dt>Skip All Data<dd>)0 60 Q(The skip data call should skip o)0 72 Q
+-.15(ve)-.15 G 2.5(ra).15 G(ll \214le data and trailing padding.)-2.5 E
+0 Cg EP
+%%Page: 47 47
+%%BeginPageSetup
+BP
+%%EndPageSetup
+/F0 10/Times-Roman@0 SF
+(This is called automatically by the API layer just before each)0 12 Q
+(header read.)0 24 Q
+(It is also called in response to the client calling the public)0 36 Q
+(<b>data_skip</b>\(<code></code>\))0 48 Q(function.)0 60 Q
+(<dt>Cleanup<dd>)0 72 Q 0 Cg EP
+%%Page: 48 48
+%%BeginPageSetup
+BP
+%%EndPageSetup
+/F0 10/Times-Roman@0 SF
+(On cleanup, the format should release all of its allocated memory)0 12
+Q(.)-.65 E(</dl>)0 24 Q(<h4 id="API Layer">)36 36 Q(API Layer)36 48 Q
+(</h4>)36 60 Q(XXX to do XXX)0 72 Q 0 Cg EP
+%%Page: 49 49
+%%BeginPageSetup
+BP
+%%EndPageSetup
+/F0 10/Times-Roman@0 SF(<h3 id="WRITE ARCHITECTURE">)36 12 Q
+(WRITE ARCHITECTURE)36 24 Q(</h3>)36 36 Q
+(The write API has a similar set of four layers:)0 48 Q(an API layer)0
+60 Q 2.5(,af)-.4 G(ormat layer)-2.5 E 2.5(,ac)-.4 G(ompression layer)
+-2.5 E 2.5(,a)-.4 G(nd an I/O layer)-2.5 E(.)-.55 E(The re)0 72 Q
+(gistration here is much simpler because only)-.15 E 0 Cg EP
+%%Page: 50 50
+%%BeginPageSetup
+BP
+%%EndPageSetup
+/F0 10/Times-Roman@0 SF(one format and one compression can be re)0 12 Q
+(gistered at a time.)-.15 E(<h4 id="I/O Layer and Client Callbacks">)36
+24 Q(I/O Layer and Client Callbacks)36 36 Q(</h4>)36 48 Q(XXX T)0 60 Q
+2.5(ob)-.8 G 2.5(ew)-2.5 G(ritten XXX)-2.5 E
+(<h4 id="Compression Layer">)36 72 Q 0 Cg EP
+%%Page: 51 51
+%%BeginPageSetup
+BP
+%%EndPageSetup
+/F0 10/Times-Roman@0 SF(Compression Layer)36 12 Q(</h4>)36 24 Q(XXX T)0
+36 Q 2.5(ob)-.8 G 2.5(ew)-2.5 G(ritten XXX)-2.5 E(<h4 id="F)36 48 Q
+(ormat Layer">)-.15 E -.15(Fo)36 60 S(rmat Layer).15 E(</h4>)36 72 Q 0
+Cg EP
+%%Page: 52 52
+%%BeginPageSetup
+BP
+%%EndPageSetup
+/F0 10/Times-Roman@0 SF(XXX T)0 12 Q 2.5(ob)-.8 G 2.5(ew)-2.5 G
+(ritten XXX)-2.5 E(<h4 id="API Layer">)36 24 Q(API Layer)36 36 Q(</h4>)
+36 48 Q(XXX T)0 60 Q 2.5(ob)-.8 G 2.5(ew)-2.5 G(ritten XXX)-2.5 E
+(<h3 id="WRITE_DISK ARCHITECTURE">)36 72 Q 0 Cg EP
+%%Page: 53 53
+%%BeginPageSetup
+BP
+%%EndPageSetup
+/F0 10/Times-Roman@0 SF(WRITE_DISK ARCHITECTURE)36 12 Q(</h3>)36 24 Q
+(The write_disk API is intended to look just lik)0 36 Q 2.5(et)-.1 G
+(he write API)-2.5 E(to clients.)0 48 Q
+(Since it does not handle multiple formats or compression, it)0 60 Q
+(is not layered internally)0 72 Q(.)-.65 E 0 Cg EP
+%%Page: 54 54
+%%BeginPageSetup
+BP
+%%EndPageSetup
+/F0 10/Times-Roman@0 SF(<h3 id="GENERAL SER)36 12 Q(VICES">)-.8 E
+(GENERAL SER)36 24 Q(VICES)-.8 E(</h3>)36 36 Q(The)0 48 Q(<b>archi)0 60
+Q -.15(ve)-.25 G(_read</b>,).15 E(<b>archi)0 72 Q -.15(ve)-.25 G
+(_write</b>,).15 E 0 Cg EP
+%%Page: 55 55
+%%BeginPageSetup
+BP
+%%EndPageSetup
+/F0 10/Times-Roman@0 SF(and)0 12 Q(<b>archi)0 24 Q -.15(ve)-.25 G
+(_write_disk</b>).15 E(objects all contain an initial)0 36 Q(<b>archi)0
+48 Q -.15(ve)-.25 G(</b>).15 E(object which pro)0 60 Q
+(vides common support for a set of standard services.)-.15 E
+(\(Recall that ANSI/ISO C90 guarantees that you can cast freely between)
+0 72 Q 0 Cg EP
+%%Page: 56 56
+%%BeginPageSetup
+BP
+%%EndPageSetup
+/F0 10/Times-Roman@0 SF 2.5(ap)0 12 S
+(ointer to a structure and a pointer to the \214rst element of that)-2.5
+E(structure.\))0 24 Q(The)0 36 Q(<b>archi)0 48 Q -.15(ve)-.25 G(</b>).15
+E(object has a magic v)0 60 Q(alue that indicates which API this object)
+-.25 E(is associated with,)0 72 Q 0 Cg EP
+%%Page: 57 57
+%%BeginPageSetup
+BP
+%%EndPageSetup
+/F0 10/Times-Roman@0 SF(slots for storing error information,)0 12 Q
+(and function pointers for virtualized API functions.)0 24 Q
+(<h3 id="MISCELLANEOUS NO)36 36 Q(TES">)-.4 E(MISCELLANEOUS NO)36 48 Q
+(TES)-.4 E(</h3>)36 60 Q(Connecting e)0 72 Q(xisting archi)-.15 E
+(ving libraries into libarchi)-.25 E .3 -.15(ve i)-.25 H 2.5(sg).15 G
+(enerally)-2.5 E 0 Cg EP
+%%Page: 58 58
+%%BeginPageSetup
+BP
+%%EndPageSetup
+/F0 10/Times-Roman@0 SF(quite dif)0 12 Q(\214cult.)-.25 E(In particular)
+0 24 Q 2.5(,m)-.4 G(an)-2.5 E 2.5(ye)-.15 G
+(xisting libraries strongly assume that you)-2.65 E
+(are reading from a \214le; the)0 36 Q 2.5(ys)-.15 G(eek forw)-2.5 E
+(ards and backw)-.1 E(ards as necessary)-.1 E(to locate v)0 48 Q
+(arious pieces of information.)-.25 E(In contrast, libarchi)0 60 Q .3
+-.15(ve n)-.25 H -2.15 -.25(ev e).15 H 2.5(rs).25 G(eeks backw)-2.5 E
+(ards in its input, which)-.1 E(sometimes requires v)0 72 Q(ery dif)-.15
+E(ferent approaches.)-.25 E 0 Cg EP
+%%Page: 59 59
+%%BeginPageSetup
+BP
+%%EndPageSetup
+/F0 10/Times-Roman@0 SF(<p>)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(<p>)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(<h3 id="SEE ALSO">)36 48 Q(SEE ALSO)
+36 60 Q(</h3>)36 72 Q 0 Cg EP
+%%Page: 63 63
+%%BeginPageSetup
+BP
+%%EndPageSetup
+/F0 10/Times-Roman@0 SF(<a href="../html3/archi)0 12 Q -.15(ve)-.25 G
+(.html">archi).15 E -.15(ve)-.25 G(\(3\)</a>,).15 E
+(<a href="../html3/archi)0 24 Q -.15(ve)-.25 G(_entry).15 E
+(.html">archi)-.65 E -.15(ve)-.25 G(_entry\(3\)</a>,).15 E
+(<a href="../html3/archi)0 36 Q -.15(ve)-.25 G(_read.html">archi).15 E
+-.15(ve)-.25 G(_read\(3\)</a>,).15 E(<a href="../html3/archi)0 48 Q -.15
+(ve)-.25 G(_write.html">archi).15 E -.15(ve)-.25 G(_write\(3\)</a>,).15
+E(<a href="../html3/archi)0 60 Q -.15(ve)-.25 G(_write_disk.html">archi)
+.15 E -.15(ve)-.25 G(_write_disk\(3\)</a>).15 E(<h3 id="HIST)36 72 Q(OR)
+-.18 E(Y">)-.65 E 0 Cg EP
+%%Page: 64 64
+%%BeginPageSetup
+BP
+%%EndPageSetup
+/F0 10/Times-Roman@0 SF(HIST)36 12 Q(OR)-.18 E(Y)-.65 E(</h3>)36 24 Q
+(The)0 36 Q(<b>libarchi)0 48 Q -.15(ve)-.25 G(</b>).15 E
+(library \214rst appeared in)0 60 Q(FreeBSD5.3.)0 72 Q 0 Cg EP
+%%Page: 65 65
+%%BeginPageSetup
+BP
+%%EndPageSetup
+/F0 10/Times-Roman@0 SF(<h3 id="A)36 12 Q(UTHORS">)-.55 E -.55(AU)36 24
+S(THORS).55 E(</h3>)36 36 Q(<p>)36 48 Q(The)0 60 Q(<b>libarchi)0 72 Q
+-.15(ve)-.25 G(</b>).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 &lt;kientzle@acm.or)-2.5 E(g&gt;.)-.18 E
+(<h3 id="B)36 36 Q(UGS">)-.1 E -.1(BU)36 48 S(GS).1 E(</h3>)36 60 Q
+(</body>)0 72 Q 0 Cg EP
+%%Trailer
+end
+%%EOF