%!PS-Adobe-3.0 %%Creator: groff version 1.19.2 %%CreationDate: Wed Jun 30 11:55:53 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 36 Q (April 16, 2007 LIB)74.5 48 Q(ARCHIVE 3)-.35 E()36 72 Q 0 Cg EP %%Page: 2 2 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@0 SF()36 48 Q()0 60 Q ()-.15 E 0 Cg EP %%Page: 4 4 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@0 SF(

)-.35 E -.35(NA)36 24 S (ME).35 E(

)36 36 Q(libarchi)0 48 Q -.15(ve)-.25 G (_internals).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(

)-.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(

)36 24 Q (The)0 36 Q(libarchi)0 48 Q -.15(ve)-.25 G().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 (

)36 36 Q(GENERAL ARCHITECTURE)36 48 Q (

)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(archi)-.65 E -.15(ve)-.25 G(_entry\(1\)).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(archi)-.65 E -.15(ve)-.25 G(_entry\(1\)).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(archi)-.65 E -.15(ve)-.25 G(_entry\(1\)).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(

)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 12 Q (READ ARCHITECTURE)36 24 Q(

)36 36 Q (From the outside, clients use the)0 48 Q(archi).15 E -.15(ve)-.25 G(_read\(3\)).15 E(API to manipulate an)0 72 Q 0 Cg EP %%Page: 12 12 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@0 SF(archi)0 12 Q -.15(ve)-.25 G().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(archi)0 48 Q -.15(ve)-.25 G().15 E(object is cast to an)0 60 Q(archi)0 72 Q -.15(ve)-.25 G(_read).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(archi)-.65 E -.15(ve)-.25 G(_read_open_memory\(3\),).15 E 0 Cg EP %%Page: 14 14 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@0 SF(and)0 12 Q(archi).15 E -.15(ve)-.25 G (_read_open_fd\(3\).).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(archi)0 12 Q -.15(ve)-.25 G(_entry).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(

)36 36 Q (I/O Layer and Client Callbacks)36 48 Q(

)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(

)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 24 Q(Decompresssion Layer)36 36 Q (

)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(

)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 (

)0 48 Q(
Re)0 60 Q(gistration/Con\214guration
)-.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(__archi)0 24 Q -.15(ve) -.25 G(_read_re).15 E(gister_compression\(\))-.15 E (function to pro)0 36 Q(vide bid and initialization functions.)-.15 E (This function returns)0 48 Q(NULL)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(struct decompressor_t.)0 12 Q(This structure contains a)0 24 Q(v)0 36 Q (oid * con\214g)-.2 E (slot that can be used for storing an)0 48 Q 2.5(yc)-.15 G (ustomization information.)-2.5 E(
Bid
)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(decompressor)0 36 Q (element of the)0 48 Q(archi)0 60 Q -.15(ve)-.25 G(_read) .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(

)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(

Initialize
)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 (struct decompressor_t)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 (decompressor)0 24 Q(element of the)0 36 Q (archi)0 48 Q -.15(ve)-.25 G(_read).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(data)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(
Satisfy I/O requests
)0 48 Q (The format handler will in)0 60 Q -.2(vo)-.4 G .2 -.1(ke t).2 H(he).1 E (read_ahead,)0 72 Q 0 Cg EP %%Page: 37 37 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@0 SF(consume,)0 12 Q(and)0 24 Q (skip)0 36 Q(functions as needed.)0 48 Q(
Finish
)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(data)0 24 Q(and)0 36 Q (con\214g)0 48 Q(slots of the)0 60 Q (decompressor)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(
)0 36 Q (

)-.15 E -.15(Fo)36 60 S(rmat Layer).15 E (

)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 (
)0 24 Q(
Re)0 36 Q(gistration
)-.15 E (Allocate your pri)0 48 Q -.25(va)-.25 G (te data and initialize your pointers.).25 E(
Bid
)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(read_ahead\(\))0 12 Q (decompression method b)0 24 Q(ut not calling the)-.2 E (consume\(\))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(
Read header
)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(
Read Data
)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 (
Skip All Data
)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 (data_skip\(\))0 48 Q(function.)0 60 Q (
Cleanup
)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(
)0 24 Q(

)36 36 Q(API Layer)36 48 Q (

)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(

)36 12 Q (WRITE ARCHITECTURE)36 24 Q(

)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(

)36 24 Q(I/O Layer and Client Callbacks)36 36 Q(

)36 48 Q(XXX T)0 60 Q 2.5(ob)-.8 G 2.5(ew)-2.5 G(ritten XXX)-2.5 E (

)36 72 Q 0 Cg EP %%Page: 51 51 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@0 SF(Compression Layer)36 12 Q(

)36 24 Q(XXX T)0 36 Q 2.5(ob)-.8 G 2.5(ew)-2.5 G(ritten XXX)-2.5 E(

)-.15 E -.15(Fo)36 60 S(rmat Layer).15 E(

)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(

)36 24 Q(API Layer)36 36 Q(

) 36 48 Q(XXX T)0 60 Q 2.5(ob)-.8 G 2.5(ew)-2.5 G(ritten XXX)-2.5 E (

)36 72 Q 0 Cg EP %%Page: 53 53 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@0 SF(WRITE_DISK ARCHITECTURE)36 12 Q(

)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(

)-.8 E (GENERAL SER)36 24 Q(VICES)-.8 E(

)36 36 Q(The)0 48 Q(archi)0 60 Q -.15(ve)-.25 G(_read,).15 E(archi)0 72 Q -.15(ve)-.25 G (_write,).15 E 0 Cg EP %%Page: 55 55 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@0 SF(and)0 12 Q(archi)0 24 Q -.15(ve)-.25 G (_write_disk).15 E(objects all contain an initial)0 36 Q(archi)0 48 Q -.15(ve)-.25 G().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(archi)0 48 Q -.15(ve)-.25 G().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 (

)-.4 E(MISCELLANEOUS NO)36 48 Q (TES)-.4 E(

)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(

)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(SEE ALSO) 36 60 Q(

)36 72 Q 0 Cg EP %%Page: 63 63 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@0 SF(archi).15 E -.15(ve)-.25 G(\(3\),).15 E (archi)-.65 E -.15(ve)-.25 G(_entry\(3\),).15 E (archi).15 E -.15(ve)-.25 G(_read\(3\),).15 E(archi).15 E -.15(ve)-.25 G(_write\(3\),).15 E(archi) .15 E -.15(ve)-.25 G(_write_disk\(3\)).15 E(

)-.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(

)36 24 Q (The)0 36 Q(libarchi)0 48 Q -.15(ve)-.25 G().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(

)-.55 E -.55(AU)36 24 S(THORS).55 E(

)36 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