diff options
Diffstat (limited to 'archivers/libarchive/files/doc/html/archive_write.3.html')
| -rw-r--r-- | archivers/libarchive/files/doc/html/archive_write.3.html | 2193 |
1 files changed, 845 insertions, 1348 deletions
diff --git a/archivers/libarchive/files/doc/html/archive_write.3.html b/archivers/libarchive/files/doc/html/archive_write.3.html index b0c9e218067..7c07568618f 100644 --- a/archivers/libarchive/files/doc/html/archive_write.3.html +++ b/archivers/libarchive/files/doc/html/archive_write.3.html @@ -1,1348 +1,845 @@ -%!PS-Adobe-3.0 -%%Creator: groff version 1.19.2 -%%CreationDate: Sun Mar 14 02:49:16 2010 -%%DocumentNeededResources: font Times-Roman -%%DocumentSuppliedResources: procset grops 1.19 2 -%%Pages: 107 -%%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 -(May 11, 2008 archi)74.5 48 Q -.15(ve)-.25 G(_write 3).15 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>archi)0 48 Q -.15(ve)-.25 G(_write_ne).15 E -(w</b>,)-.25 E(<b>archi)0 60 Q -.15(ve)-.25 G -(_write_set_format_cpio</b>,).15 E(<b>archi)0 72 Q -.15(ve)-.25 G -(_write_set_format_pax</b>,).15 E 0 Cg EP -%%Page: 5 5 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(<b>archi)0 12 Q -.15(ve)-.25 G -(_write_set_format_pax_restricted</b>,).15 E(<b>archi)0 24 Q -.15(ve) --.25 G(_write_set_format_shar</b>,).15 E(<b>archi)0 36 Q -.15(ve)-.25 G -(_write_set_format_shar_binary</b>,).15 E(<b>archi)0 48 Q -.15(ve)-.25 G -(_write_set_format_ustar</b>,).15 E(<b>archi)0 60 Q -.15(ve)-.25 G -(_write_get_bytes_per_block</b>,).15 E(<b>archi)0 72 Q -.15(ve)-.25 G -(_write_set_bytes_per_block</b>,).15 E 0 Cg EP -%%Page: 6 6 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(<b>archi)0 12 Q -.15(ve)-.25 G -(_write_set_bytes_in_last_block</b>,).15 E(<b>archi)0 24 Q -.15(ve)-.25 -G(_write_set_compression_bzip2</b>,).15 E(<b>archi)0 36 Q -.15(ve)-.25 G -(_write_set_compression_compress</b>,).15 E(<b>archi)0 48 Q -.15(ve)-.25 -G(_write_set_compression_gzip</b>,).15 E(<b>archi)0 60 Q -.15(ve)-.25 G -(_write_set_compression_none</b>,).15 E(<b>archi)0 72 Q -.15(ve)-.25 G -(_write_set_compression_program</b>,).15 E 0 Cg EP -%%Page: 7 7 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(<b>archi)0 12 Q -.15(ve)-.25 G -(_write_set_compressor_options</b>,).15 E(<b>archi)0 24 Q -.15(ve)-.25 G -(_write_set_format_options</b>,).15 E(<b>archi)0 36 Q -.15(ve)-.25 G -(_write_set_options</b>,).15 E(<b>archi)0 48 Q -.15(ve)-.25 G -(_write_open</b>,).15 E(<b>archi)0 60 Q -.15(ve)-.25 G -(_write_open_fd</b>,).15 E(<b>archi)0 72 Q -.15(ve)-.25 G -(_write_open_FILE</b>,).15 E 0 Cg EP -%%Page: 8 8 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(<b>archi)0 12 Q -.15(ve)-.25 G -(_write_open_\214lename</b>,).15 E(<b>archi)0 24 Q -.15(ve)-.25 G -(_write_open_memory</b>,).15 E(<b>archi)0 36 Q -.15(ve)-.25 G -(_write_header</b>,).15 E(<b>archi)0 48 Q -.15(ve)-.25 G -(_write_data</b>,).15 E(<b>archi)0 60 Q -.15(ve)-.25 G -(_write_\214nish_entry</b>,).15 E(<b>archi)0 72 Q -.15(ve)-.25 G -(_write_close</b>,).15 E 0 Cg EP -%%Page: 9 9 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(<b>archi)0 12 Q -.15(ve)-.25 G -(_write_\214nish</b>).15 E 2.5(-f)0 24 S(unctions for creating archi) --2.5 E -.15(ve)-.25 G(s).15 E(<h3 id="SYNOPSIS">)36 36 Q(SYNOPSIS)36 48 -Q(</h3>)36 60 Q(<br><br><code></code><code>struct</code><code> archi)0 -72 Q -.15(ve)-.25 G(</code><code> *</code>).15 E 0 Cg EP -%%Page: 10 10 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(<b>archi)0 12 Q -.15(ve)-.25 G(_write_ne).15 E -(w</b>\(<code></code><code>v)-.25 E(oid</code>\))-.2 E -(<br><br><code></code><code>int</code>)0 24 Q(<b>archi)0 36 Q -.15(ve) --.25 G(_write_get_bytes_per_block</b>\(<code></code><code>struct archi) -.15 E .3 -.15(ve *)-.25 H(</code>\)).15 E -(<br><br><code></code><code>int</code>)0 48 Q(<b>archi)0 60 Q -.15(ve) --.25 G(_write_set_bytes_per_block</b>\(<code></code><code>struct archi) -.15 E .3 -.15(ve *)-.25 H(</code><code>, int bytes_per_block</code>\)) -.15 E(<br><br><code></code><code>int</code>)0 72 Q 0 Cg EP -%%Page: 11 11 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(<b>archi)0 12 Q -.15(ve)-.25 G -(_write_set_bytes_in_last_block</b>\(<code></code><code>struct archi).15 -E .3 -.15(ve *)-.25 H(</code><code>, int</code>\)).15 E -(<br><br><code></code><code>int</code>)0 24 Q(<b>archi)0 36 Q -.15(ve) --.25 G -(_write_set_compression_bzip2</b>\(<code></code><code>struct archi).15 E -.3 -.15(ve *)-.25 H(</code>\)).15 E -(<br><br><code></code><code>int</code>)0 48 Q(<b>archi)0 60 Q -.15(ve) --.25 G -(_write_set_compression_compress</b>\(<code></code><code>struct archi) -.15 E .3 -.15(ve *)-.25 H(</code>\)).15 E -(<br><br><code></code><code>int</code>)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 -(_write_set_compression_gzip</b>\(<code></code><code>struct archi).15 E -.3 -.15(ve *)-.25 H(</code>\)).15 E -(<br><br><code></code><code>int</code>)0 24 Q(<b>archi)0 36 Q -.15(ve) --.25 G(_write_set_compression_none</b>\(<code></code><code>struct archi) -.15 E .3 -.15(ve *)-.25 H(</code>\)).15 E -(<br><br><code></code><code>int</code>)0 48 Q(<b>archi)0 60 Q -.15(ve) --.25 G -(_write_set_compression_program</b>\(<code></code><code>struct archi).15 -E .3 -.15(ve *)-.25 H(</code><code>, const char * cmd</code>\)).15 E -(<br><br><code></code><code>int</code>)0 72 Q 0 Cg EP -%%Page: 13 13 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(<b>archi)0 12 Q -.15(ve)-.25 G -(_write_set_format_cpio</b>\(<code></code><code>struct archi).15 E .3 --.15(ve *)-.25 H(</code>\)).15 E(<br><br><code></code><code>int</code>)0 -24 Q(<b>archi)0 36 Q -.15(ve)-.25 G -(_write_set_format_pax</b>\(<code></code><code>struct archi).15 E .3 --.15(ve *)-.25 H(</code>\)).15 E(<br><br><code></code><code>int</code>)0 -48 Q(<b>archi)0 60 Q -.15(ve)-.25 G -(_write_set_format_pax_restricted</b>\(<code></code><code>struct archi) -.15 E .3 -.15(ve *)-.25 H(</code>\)).15 E -(<br><br><code></code><code>int</code>)0 72 Q 0 Cg EP -%%Page: 14 14 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(<b>archi)0 12 Q -.15(ve)-.25 G -(_write_set_format_shar</b>\(<code></code><code>struct archi).15 E .3 --.15(ve *)-.25 H(</code>\)).15 E(<br><br><code></code><code>int</code>)0 -24 Q(<b>archi)0 36 Q -.15(ve)-.25 G -(_write_set_format_shar_binary</b>\(<code></code><code>struct archi).15 -E .3 -.15(ve *)-.25 H(</code>\)).15 E -(<br><br><code></code><code>int</code>)0 48 Q(<b>archi)0 60 Q -.15(ve) --.25 G(_write_set_format_ustar</b>\(<code></code><code>struct archi).15 -E .3 -.15(ve *)-.25 H(</code>\)).15 E -(<br><br><code></code><code>int</code>)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 -(_write_set_format_options</b>\(<code></code><code>struct archi).15 E .3 --.15(ve *)-.25 H(</code><code>, const char *</code>\)).15 E -(<br><br><code></code><code>int</code>)0 24 Q(<b>archi)0 36 Q -.15(ve) --.25 G -(_write_set_compressor_options</b>\(<code></code><code>struct archi).15 -E .3 -.15(ve *)-.25 H(</code><code>, const char *</code>\)).15 E -(<br><br><code></code><code>int</code>)0 48 Q(<b>archi)0 60 Q -.15(ve) --.25 G(_write_set_options</b>\(<code></code><code>struct archi).15 E .3 --.15(ve *)-.25 H(</code><code>, const char *</code>\)).15 E -(<br><br><code></code><code>int</code>)0 72 Q 0 Cg EP -%%Page: 16 16 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(<b>archi)0 12 Q -.15(ve)-.25 G -(_write_open</b>\(<code></code>).15 E(<code></code><code>struct archi)0 -24 Q .3 -.15(ve *)-.25 H(</code>).15 E(<code></code><code>v)0 36 Q -(oid *client_data</code>)-.2 E(<code></code><code>archi)0 48 Q -.15(ve) --.25 G(_open_callback *</code>).15 E(<code></code><code>archi)0 60 Q --.15(ve)-.25 G(_write_callback *</code>).15 E(<code></code><code>archi)0 -72 Q -.15(ve)-.25 G(_close_callback *</code>).15 E 0 Cg EP -%%Page: 17 17 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(\))0 12 Q(<br><br><code></code><code>int</code>) -0 24 Q(<b>archi)0 36 Q -.15(ve)-.25 G -(_write_open_fd</b>\(<code></code><code>struct archi).15 E .3 -.15(ve *) --.25 H(</code><code>, int fd</code>\)).15 E -(<br><br><code></code><code>int</code>)0 48 Q(<b>archi)0 60 Q -.15(ve) --.25 G(_write_open_FILE</b>\(<code></code><code>struct archi).15 E .3 --.15(ve *)-.25 H(</code><code>, FILE *\214le</code>\)).15 E -(<br><br><code></code><code>int</code>)0 72 Q 0 Cg EP -%%Page: 18 18 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(<b>archi)0 12 Q -.15(ve)-.25 G -(_write_open_\214lename</b>\(<code></code><code>struct archi).15 E .3 --.15(ve *)-.25 H(</code><code>, const char *\214lename</code>\)).15 E -(<br><br><code></code><code>int</code>)0 24 Q(<b>archi)0 36 Q -.15(ve) --.25 G(_write_open_memory</b>\(<code></code>).15 E -(<code></code><code>struct archi)0 48 Q .3 -.15(ve *)-.25 H(</code>).15 -E(<code></code><code>v)0 60 Q(oid *b)-.2 E(uf)-.2 E(fer</code>)-.25 E -(<code></code><code>size_t b)0 72 Q(uf)-.2 E(ferSize</code>)-.25 E 0 Cg -EP -%%Page: 19 19 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(<code></code><code>size_t *outUsed</code>)0 12 Q -(\))0 24 Q(<br><br><code></code><code>int</code>)0 36 Q(<b>archi)0 48 Q --.15(ve)-.25 G(_write_header</b>\(<code></code><code>struct archi).15 E -.3 -.15(ve *)-.25 H(</code><code>, struct archi).15 E -.15(ve)-.25 G -(_entry *</code>\)).15 E(<br><br><code></code><code>ssize_t</code>)0 60 -Q(<b>archi)0 72 Q -.15(ve)-.25 G -(_write_data</b>\(<code></code><code>struct archi).15 E .3 -.15(ve *) --.25 H(</code><code>, const v).15 E(oid *</code><code>, size_t</code>\)) --.2 E 0 Cg EP -%%Page: 20 20 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(<br><br><code></code><code>int</code>)0 12 Q -(<b>archi)0 24 Q -.15(ve)-.25 G -(_write_\214nish_entry</b>\(<code></code><code>struct archi).15 E .3 --.15(ve *)-.25 H(</code>\)).15 E(<br><br><code></code><code>int</code>)0 -36 Q(<b>archi)0 48 Q -.15(ve)-.25 G -(_write_close</b>\(<code></code><code>struct archi).15 E .3 -.15(ve *) --.25 H(</code>\)).15 E(<br><br><code></code><code>int</code>)0 60 Q -(<b>archi)0 72 Q -.15(ve)-.25 G -(_write_\214nish</b>\(<code></code><code>struct archi).15 E .3 -.15 -(ve *)-.25 H(</code>\)).15 E 0 Cg EP -%%Page: 21 21 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(<h3 id="DESCRIPTION">)36 12 Q(DESCRIPTION)36 24 -Q(</h3>)36 36 Q(These functions pro)0 48 Q -(vide a complete API for creating streaming)-.15 E(archi)0 60 Q .3 -.15 -(ve \214)-.25 H(les.).15 E(The general process is to \214rst create the) -0 72 Q 0 Cg EP -%%Page: 22 22 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(<font size="-1"></font><font size="-1">struct</\ -font><font size="-1"> archi)0 12 Q -.15(ve)-.25 G(</font>).15 E -(object, set an)0 24 Q 2.5(yd)-.15 G -(esired options, initialize the archi)-2.5 E -.15(ve)-.25 G 2.5(,a).15 G -(ppend entries, then)-2.5 E(close the archi)0 36 Q .3 -.15(ve a)-.25 H -(nd release all resources.).15 E(The follo)0 48 Q -(wing summary describes the functions in approximately)-.25 E -(the order the)0 60 Q 2.5(ya)-.15 G(re ordinarily used:)-2.5 E -(<dl compact>)0 72 Q 0 Cg EP -%%Page: 23 23 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(<p><dt><b>archi)0 12 Q -.15(ve)-.25 G(_write_ne) -.15 E(w</b>\(<code></code>\)<dd>)-.25 E(Allocates and initializes a)0 24 -Q(<font size="-1"></font><font size="-1">struct</font><font size="-1"> \ -archi)0 36 Q -.15(ve)-.25 G(</font>).15 E -(object suitable for writing a tar archi)0 48 Q -.15(ve)-.25 G(.).15 E -(<p><dt><b>archi)0 60 Q -.15(ve)-.25 G -(_write_set_bytes_per_block</b>\(<code></code>\)<dd>).15 E -(Sets the block size used for writing the archi)0 72 Q .3 -.15(ve d)-.25 -H(ata.).15 E 0 Cg EP -%%Page: 24 24 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(Ev)0 12 Q -(ery call to the write callback function, e)-.15 E -(xcept possibly the last one, will)-.15 E(use this v)0 24 Q -(alue for the length.)-.25 E(The third parameter is a boolean that spec\ -i\214es whether or not the \214nal block)0 36 Q -(written will be padded to the full block size.)0 48 Q -(If it is zero, the last block will not be padded.)0 60 Q(If it is non-\ -zero, padding will be added both before and after compression.)0 72 Q 0 -Cg EP -%%Page: 25 25 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(The def)0 12 Q -(ault is to use a block size of 10240 bytes and to pad the last block.) --.1 E(Note that a block size of zero will suppress internal blocking)0 -24 Q(and cause writes to be sent directly to the write callback as the)0 -36 Q 2.5(yo)-.15 G(ccur)-2.5 E(.)-.55 E(<p><dt><b>archi)0 48 Q -.15(ve) --.25 G(_write_get_bytes_per_block</b>\(<code></code>\)<dd>).15 E(Retrie) -0 60 Q .3 -.15(ve t)-.25 H(he block size to be used for writing.).15 E -2.5(Av)0 72 S(alue of -1 here indicates that the library should use def) --2.75 E(ault v)-.1 E(alues.)-.25 E 0 Cg EP -%%Page: 26 26 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF 2.5(Av)0 12 S -(alue of zero indicates that internal blocking is suppressed.)-2.75 E -(<p><dt><b>archi)0 24 Q -.15(ve)-.25 G -(_write_set_bytes_in_last_block</b>\(<code></code>\)<dd>).15 E -(Sets the block size used for writing the last block.)0 36 Q(If this v)0 -48 Q(alue is zero, the last block will be padded to the same size)-.25 E -(as the other blocks.)0 60 Q(Otherwise, the \214nal block will be padde\ -d to a multiple of this size.)0 72 Q 0 Cg EP -%%Page: 27 27 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(In particular)0 12 Q 2.5(,s)-.4 G -(etting it to 1 will cause the \214nal block to not be padded.)-2.5 E --.15(Fo)0 24 S 2.5(rc).15 G(ompressed output, an)-2.5 E 2.5(yp)-.15 G -(adding generated by this option)-2.5 E -(is applied only after the compression.)0 36 Q -(The uncompressed data is al)0 48 Q -.1(wa)-.1 G(ys unpadded.).1 E -(The def)0 60 Q -(ault is to pad the last block to the full block size \(note that)-.1 E -(<b>archi)0 72 Q -.15(ve)-.25 G -(_write_open_\214lename</b>\(<code></code>\)).15 E 0 Cg EP -%%Page: 28 28 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(will set this based on the \214le type\).)0 12 Q -(Unlik)0 24 Q 2.5(et)-.1 G(he other)-2.5 E -.74(``)0 36 S(set').74 E(') --.74 E(functions, this function can be called after the archi)0 48 Q .3 --.15(ve i)-.25 H 2.5(so).15 G(pened.)-2.5 E(<p><dt><b>archi)0 60 Q -.15 -(ve)-.25 G(_write_get_bytes_in_last_block</b>\(<code></code>\)<dd>).15 E -(Retrie)0 72 Q .3 -.15(ve t)-.25 H(he currently-set v).15 E -(alue for last block size.)-.25 E 0 Cg EP -%%Page: 29 29 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF 2.5(Av)0 12 S -(alue of -1 here indicates that the library should use def)-2.75 E -(ault v)-.1 E(alues.)-.25 E(<p><dt>Xo<dd>)0 24 Q(<b>archi)0 36 Q -.15 -(ve)-.25 G(_write_set_format_cpio</b>\(<code></code>\),).15 E(<b>archi)0 -48 Q -.15(ve)-.25 G(_write_set_format_pax</b>\(<code></code>\),).15 E -(<b>archi)0 60 Q -.15(ve)-.25 G -(_write_set_format_pax_restricted</b>\(<code></code>\),).15 E(<b>archi)0 -72 Q -.15(ve)-.25 G(_write_set_format_shar</b>\(<code></code>\),).15 E 0 -Cg EP -%%Page: 30 30 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(<b>archi)0 12 Q -.15(ve)-.25 G -(_write_set_format_shar_binary</b>\(<code></code>\),).15 E(<b>archi)0 24 -Q -.15(ve)-.25 G(_write_set_format_ustar</b>\(<code></code>\)).15 E -(Sets the format that will be used for the archi)0 36 Q -.15(ve)-.25 G -(.).15 E(The library can write)0 48 Q -(POSIX octet-oriented cpio format archi)0 60 Q -.15(ve)-.25 G(s,).15 E -(POSIX-standard)0 72 Q 0 Cg EP -%%Page: 31 31 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF -.74(``)0 12 S(pax interchange').74 E(')-.74 E -(format archi)0 24 Q -.15(ve)-.25 G(s,).15 E(traditional)0 36 Q -.74(``) -0 48 S(shar').74 E(')-.74 E(archi)0 60 Q -.15(ve)-.25 G(s,).15 E -(enhanced)0 72 Q 0 Cg EP -%%Page: 32 32 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF -.74(``)0 12 S(binary').74 E(')-.74 E -(shar archi)0 24 Q -.15(ve)-.25 G 2.5(st).15 G(hat store a v)-2.5 E -(ariety of \214le attrib)-.25 E(utes and handle binary \214les,)-.2 E -(and)0 36 Q(POSIX-standard)0 48 Q -.74(``)0 60 S(ustar').74 E(')-.74 E -(archi)0 72 Q -.15(ve)-.25 G(s.).15 E 0 Cg EP -%%Page: 33 33 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(The pax interchange format is a backw)0 12 Q -(ards-compatible tar format that)-.1 E(adds k)0 24 Q -.15(ey)-.1 G(/v) -.15 E(alue attrib)-.25 E(utes to each entry and supports arbitrary)-.2 E -(\214lenames, linknames, uids, sizes, etc.)0 36 Q -.74(``)0 48 S -(Restricted pax interchange format').74 E(')-.74 E(is the library def)0 -60 Q(ault; this is the same as pax format, b)-.1 E(ut suppresses)-.2 E -(the pax e)0 72 Q(xtended header for most normal \214les.)-.15 E 0 Cg EP -%%Page: 34 34 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF -(In most cases, this will result in ordinary ustar archi)0 12 Q -.15(ve) --.25 G(s.).15 E(<p><dt>Xo<dd>)0 24 Q(<b>archi)0 36 Q -.15(ve)-.25 G -(_write_set_compression_bzip2</b>\(<code></code>\),).15 E(<b>archi)0 48 -Q -.15(ve)-.25 G(_write_set_compression_compress</b>\(<code></code>\),) -.15 E(<b>archi)0 60 Q -.15(ve)-.25 G -(_write_set_compression_gzip</b>\(<code></code>\),).15 E(<b>archi)0 72 Q --.15(ve)-.25 G(_write_set_compression_none</b>\(<code></code>\)).15 E 0 -Cg EP -%%Page: 35 35 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(The resulting archi)0 12 Q .3 -.15(ve w)-.25 H -(ill be compressed as speci\214ed.).15 E -(Note that the compressed output is al)0 24 Q -.1(wa)-.1 G -(ys properly block).1 E(ed.)-.1 E(<p><dt><b>archi)0 36 Q -.15(ve)-.25 G -(_write_set_compression_program</b>\(<code></code>\)<dd>).15 E -(The archi)0 48 Q .3 -.15(ve w)-.25 H -(ill be fed into the speci\214ed compression program.).15 E -(The output of that program is block)0 60 Q -(ed and written to the client)-.1 E(write callbacks.)0 72 Q 0 Cg EP -%%Page: 36 36 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(<p><dt>Xo<dd>)0 12 Q(<b>archi)0 24 Q -.15(ve) --.25 G(_write_set_compressor_options</b>\(<code></code>\),).15 E -(<b>archi)0 36 Q -.15(ve)-.25 G -(_write_set_format_options</b>\(<code></code>\),).15 E(<b>archi)0 48 Q --.15(ve)-.25 G(_write_set_options</b>\(<code></code>\)).15 E -(Speci\214es options that will be passed to the currently-enabled)0 60 Q -(compressor and/or format writer)0 72 Q(.)-.55 E 0 Cg EP -%%Page: 37 37 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(The ar)0 12 Q -(gument is a comma-separated list of indi)-.18 E(vidual options.)-.25 E -(Indi)0 24 Q(vidual options ha)-.25 E .3 -.15(ve o)-.2 H -(ne of the follo).15 E(wing forms:)-.25 E(<dl compact>)0 36 Q -(<dt><i></i><i>option=v)0 48 Q(alue</i><dd>)-.25 E(The option/v)0 60 Q -(alue pair will be pro)-.25 E(vided to e)-.15 E -.15(ve)-.25 G -(ry module.).15 E -(Modules that do not accept an option with this name will ignore it.)0 -72 Q 0 Cg EP -%%Page: 38 38 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(<dt><i></i><i>option</i><dd>)0 12 Q -(The option will be pro)0 24 Q(vided to e)-.15 E -.15(ve)-.25 G -(ry module with a v).15 E(alue of)-.25 E -.74(``)0 36 S(1').74 E('.)-.74 -E(<dt><i></i><i>!option</i><dd>)0 48 Q(The option will be pro)0 60 Q -(vided to e)-.15 E -.15(ve)-.25 G(ry module with a NULL v).15 E(alue.) --.25 E(<dt><i></i><i>module:option=v)0 72 Q(alue</i><i></i>,<i> module:\ -option</i><i></i>,<i> module:!option</i><dd>)-.25 E 0 Cg EP -%%Page: 39 39 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(As abo)0 12 Q -.15(ve)-.15 G 2.5(,b).15 G -(ut the corresponding option and v)-2.7 E(alue will be pro)-.25 E(vided) --.15 E(only to modules whose name matches)0 24 Q(<i></i><i>module</i>.)0 -36 Q(</dl>)0 48 Q(The return v)0 60 Q(alue will be)-.25 E -(<b></b><b>ARCHIVE_OK</b>)0 72 Q 0 Cg EP -%%Page: 40 40 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(if an)0 12 Q 2.5(ym)-.15 G -(odule accepts the option, or)-2.5 E(<b></b><b>ARCHIVE_W)0 24 Q(ARN</b>) --1.2 E(if no module accepted the option, or)0 36 Q(<b></b><b>ARCHIVE_F)0 -48 Q -1.21 -1.11(AT A)-.74 H(L</b>)1.11 E(if there w)0 60 Q(as a f)-.1 E -(atal error while attempting to process the option.)-.1 E(<p>)36 72 Q 0 -Cg EP -%%Page: 41 41 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(The currently supported options are:)0 12 Q -(<dl compact>)0 24 Q(<dt>Compressor gzip<dd>)0 36 Q(<dl compact>)0 48 Q -(<dt><b></b><b>compression-le)0 60 Q -.15(ve)-.25 G(l</b><dd>).15 E -(The v)0 72 Q(alue is interpreted as a decimal inte)-.25 E -(ger specifying the)-.15 E 0 Cg EP -%%Page: 42 42 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(gzip compression le)0 12 Q -.15(ve)-.25 G(l.).15 -E(</dl>)0 24 Q(<dt>Compressor xz<dd>)0 36 Q(<dl compact>)0 48 Q -(<dt><b></b><b>compression-le)0 60 Q -.15(ve)-.25 G(l</b><dd>).15 E -(The v)0 72 Q(alue is interpreted as a decimal inte)-.25 E -(ger specifying the)-.15 E 0 Cg EP -%%Page: 43 43 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(compression le)0 12 Q -.15(ve)-.25 G(l.).15 E -(</dl>)0 24 Q(<dt>F)0 36 Q(ormat mtree<dd>)-.15 E(<dl compact>)0 48 Q -(<dt><b></b><b>cksum</b><b></b>,<b> de)0 60 Q(vice</b><b></b>,<b> \215a\ -gs</b><b></b>,<b> gid</b><b></b>,<b> gname</b><b></b>,<b> indent</b><b>\ -</b>,<b> link</b><b></b>,<b> md5</b><b></b>,<b> mode</b><b></b>,<b> nli\ -nk</b><b></b>,<b> rmd160</b><b></b>,<b> sha1</b><b></b>,<b> sha256</b><\ -b></b>,<b> sha384</b>)-.25 E(<b></b>,<b> sha512</b><b></b>,<b> size</b>\ -<b></b>,<b> time</b><b></b>,<b> uid</b><b></b>,<b> uname</b><dd>)A -(Enable a particular k)0 72 Q -.15(ey)-.1 G -.1(wo).15 G -(rd in the mtree output.).1 E 0 Cg EP -%%Page: 44 44 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(Pre\214x with an e)0 12 Q -(xclamation mark to disable the corresponding k)-.15 E -.15(ey)-.1 G -.1 -(wo).15 G(rd.).1 E(The def)0 24 Q(ault is equi)-.1 E -.25(va)-.25 G -(lent to).25 E -.74(``)0 36 S(de).74 E(vice, \215ags, gid, gname, link,\ - mode, nlink, size, time, type, uid, uname')-.25 E('.)-.74 E -(<dt><b></b><b>all</b><dd>)0 48 Q(Enables all of the abo)0 60 Q .3 -.15 -(ve k)-.15 H -.15(ey).05 G -.1(wo).15 G(rds.).1 E -(<dt><b></b><b>use-set</b><dd>)0 72 Q 0 Cg EP -%%Page: 45 45 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(Enables generation of)0 12 Q(<b></b><b>/set</b>) -0 24 Q(lines that specify def)0 36 Q(ault v)-.1 E(alues for the follo) --.25 E(wing \214les and/or directories.)-.25 E -(<dt><b></b><b>indent</b><dd>)0 48 Q(XXX needs e)0 60 Q(xplanation XXX) --.15 E(</dl>)0 72 Q 0 Cg EP -%%Page: 46 46 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(</dl>)0 12 Q(<p><dt><b>archi)0 24 Q -.15(ve)-.25 -G(_write_open</b>\(<code></code>\)<dd>).15 E -(Freeze the settings, open the archi)0 36 Q -.15(ve)-.25 G 2.5(,a).15 G -(nd prepare for writing entries.)-2.5 E -(This is the most generic form of this function, which accepts)0 48 Q -(pointers to three callback functions which will be in)0 60 Q -.2(vo)-.4 -G -.1(ke).2 G 2.5(db).1 G(y)-2.5 E -(the compression layer to write the constructed archi)0 72 Q -.15(ve) --.25 G(.).15 E 0 Cg EP -%%Page: 47 47 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(<p><dt><b>archi)0 12 Q -.15(ve)-.25 G -(_write_open_fd</b>\(<code></code>\)<dd>).15 E 2.5(Ac)0 24 S(on)-2.5 E --.15(ve)-.4 G(nience form of).15 E(<b>archi)0 36 Q -.15(ve)-.25 G -(_write_open</b>\(<code></code>\)).15 E -(that accepts a \214le descriptor)0 48 Q(.)-.55 E(The)0 60 Q(<b>archi)0 -72 Q -.15(ve)-.25 G(_write_open_fd</b>\(<code></code>\)).15 E 0 Cg EP -%%Page: 48 48 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(function is safe for use with tape dri)0 12 Q --.15(ve)-.25 G 2.5(so).15 G 2.5(ro)-2.5 G(ther)-2.5 E(block-oriented de) -0 24 Q(vices.)-.25 E(<p><dt><b>archi)0 36 Q -.15(ve)-.25 G -(_write_open_FILE</b>\(<code></code>\)<dd>).15 E 2.5(Ac)0 48 S(on)-2.5 E --.15(ve)-.4 G(nience form of).15 E(<b>archi)0 60 Q -.15(ve)-.25 G -(_write_open</b>\(<code></code>\)).15 E(that accepts a)0 72 Q 0 Cg EP -%%Page: 49 49 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(<br><br><code></code><code>FILE *</code>)0 12 Q -(pointer)0 24 Q(.)-.55 E(Note that)0 36 Q(<b>archi)0 48 Q -.15(ve)-.25 G -(_write_open_FILE</b>\(<code></code>\)).15 E -(is not safe for writing to tape dri)0 60 Q -.15(ve)-.25 G 2.5(so).15 G -2.5(ro)-2.5 G(ther de)-2.5 E(vices)-.25 E -(that require correct blocking.)0 72 Q 0 Cg EP -%%Page: 50 50 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(<p><dt><b>archi)0 12 Q -.15(ve)-.25 G -(_write_open_\214le</b>\(<code></code>\)<dd>).15 E 2.5(Ad)0 24 S -(eprecated synon)-2.5 E(ym for)-.15 E(<b>archi)0 36 Q -.15(ve)-.25 G -(_write_open_\214lename</b>\(<code></code>\).).15 E(<p><dt><b>archi)0 48 -Q -.15(ve)-.25 G(_write_open_\214lename</b>\(<code></code>\)<dd>).15 E -2.5(Ac)0 60 S(on)-2.5 E -.15(ve)-.4 G(nience form of).15 E(<b>archi)0 72 -Q -.15(ve)-.25 G(_write_open</b>\(<code></code>\)).15 E 0 Cg EP -%%Page: 51 51 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(that accepts a \214lename.)0 12 Q 2.5(AN)0 24 S -(ULL ar)-2.5 E -(gument indicates that the output should be written to standard output;) --.18 E(an ar)0 36 Q(gument of)-.18 E -.74(``)0 48 S(-').74 E(')-.74 E -(will open a \214le with that name.)0 60 Q(If you ha)0 72 Q .3 -.15 -(ve n)-.2 H(ot in).15 E -.2(vo)-.4 G -.1(ke).2 G(d).1 E 0 Cg EP -%%Page: 52 52 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(<b>archi)0 12 Q -.15(ve)-.25 G -(_write_set_bytes_in_last_block</b>\(<code></code>\),).15 E(then)0 24 Q -(<b>archi)0 36 Q -.15(ve)-.25 G -(_write_open_\214lename</b>\(<code></code>\)).15 E -(will adjust the last-block padding depending on the \214le:)0 48 Q -(it will enable padding when writing to standard output or)0 60 Q -(to a character or block de)0 72 Q -(vice node, it will disable padding otherwise.)-.25 E 0 Cg EP -%%Page: 53 53 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF -1.1(Yo)0 12 S 2.5(uc)1.1 G(an o)-2.5 E -.15(ve) --.15 G(rride this by manually in).15 E -.2(vo)-.4 G(king).2 E(<b>archi)0 -24 Q -.15(ve)-.25 G(_write_set_bytes_in_last_block</b>\(<code></code>\)) -.15 E(before calling)0 36 Q(<b>archi)0 48 Q -.15(ve)-.25 G -(_write_open</b>\(<code></code>\).).15 E(The)0 60 Q(<b>archi)0 72 Q -.15 -(ve)-.25 G(_write_open_\214lename</b>\(<code></code>\)).15 E 0 Cg EP -%%Page: 54 54 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(function is safe for use with tape dri)0 12 Q --.15(ve)-.25 G 2.5(so).15 G 2.5(ro)-2.5 G(ther)-2.5 E(block-oriented de) -0 24 Q(vices.)-.25 E(<p><dt><b>archi)0 36 Q -.15(ve)-.25 G -(_write_open_memory</b>\(<code></code>\)<dd>).15 E 2.5(Ac)0 48 S(on)-2.5 -E -.15(ve)-.4 G(nience form of).15 E(<b>archi)0 60 Q -.15(ve)-.25 G -(_write_open</b>\(<code></code>\)).15 E -(that accepts a pointer to a block of memory that will recei)0 72 Q -.15 -(ve)-.25 G 0 Cg EP -%%Page: 55 55 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(the archi)0 12 Q -.15(ve)-.25 G(.).15 E -(The \214nal)0 24 Q(<br><br><code></code><code>size_t *</code>)0 36 Q -(ar)0 48 Q(gument points to a v)-.18 E(ariable that will be updated)-.25 -E(after each write to re\215ect ho)0 60 Q 2.5(wm)-.25 G(uch of the b) --2.5 E(uf)-.2 E(fer)-.25 E(is currently in use.)0 72 Q 0 Cg EP -%%Page: 56 56 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF -1.1(Yo)0 12 S 2.5(us)1.1 G -(hould be careful to ensure that this v)-2.5 E(ariable)-.25 E -(remains allocated until after the archi)0 24 Q .3 -.15(ve i)-.25 H(s) -.15 E(closed.)0 36 Q(<p><dt><b>archi)0 48 Q -.15(ve)-.25 G -(_write_header</b>\(<code></code>\)<dd>).15 E -(Build and write a header using the data in the pro)0 60 Q(vided)-.15 E -(<font size="-1"></font><font size="-1">struct</font><font size="-1"> a\ -rchi)0 72 Q -.15(ve)-.25 G(_entry</font>).15 E 0 Cg EP -%%Page: 57 57 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(structure.)0 12 Q(See)0 24 Q -(<a href="../html3/archi)0 36 Q -.15(ve)-.25 G(_entry).15 E -(.html">archi)-.65 E -.15(ve)-.25 G(_entry\(3\)</a>).15 E -(for information on creating and populating)0 48 Q(<font size="-1"></fo\ -nt><font size="-1">struct</font><font size="-1"> archi)0 60 Q -.15(ve) --.25 G(_entry</font>).15 E(objects.)0 72 Q 0 Cg EP -%%Page: 58 58 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(<p><dt><b>archi)0 12 Q -.15(ve)-.25 G -(_write_data</b>\(<code></code>\)<dd>).15 E -(Write data corresponding to the header just written.)0 24 Q -(Returns number of bytes written or -1 on error)0 36 Q(.)-.55 E -(<p><dt><b>archi)0 48 Q -.15(ve)-.25 G -(_write_\214nish_entry</b>\(<code></code>\)<dd>).15 E -(Close out the entry just written.)0 60 Q(In particular)0 72 Q 2.5(,t) --.4 G(his writes out the \214nal padding required by some formats.)-2.5 -E 0 Cg EP -%%Page: 59 59 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(Ordinarily)0 12 Q 2.5(,c)-.65 G(lients ne)-2.5 E --.15(ve)-.25 G 2.5(rn).15 G(eed to call this, as it)-2.5 E -(is called automatically by)0 24 Q(<b>archi)0 36 Q -.15(ve)-.25 G -(_write_ne).15 E(xt_header</b>\(<code></code>\))-.15 E(and)0 48 Q -(<b>archi)0 60 Q -.15(ve)-.25 G(_write_close</b>\(<code></code>\)).15 E -(as needed.)0 72 Q 0 Cg EP -%%Page: 60 60 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(<p><dt><b>archi)0 12 Q -.15(ve)-.25 G -(_write_close</b>\(<code></code>\)<dd>).15 E(Complete the archi)0 24 Q -.3 -.15(ve a)-.25 H(nd in).15 E -.2(vo)-.4 G .2 -.1(ke t).2 H -(he close callback.).1 E(<p><dt><b>archi)0 36 Q -.15(ve)-.25 G -(_write_\214nish</b>\(<code></code>\)<dd>).15 E(In)0 48 Q -.2(vo)-.4 G --.1(ke).2 G(s).1 E(<b>archi)0 60 Q -.15(ve)-.25 G -(_write_close</b>\(<code></code>\)).15 E(if it w)0 72 Q(as not in)-.1 E --.2(vo)-.4 G -.1(ke).2 G 2.5(dm).1 G(anually)-2.5 E 2.5(,t)-.65 G -(hen releases all resources.)-2.5 E 0 Cg EP -%%Page: 61 61 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(Note that this function w)0 12 Q -(as declared to return)-.1 E(<br><br><code></code><code>v)0 24 Q -(oid</code>)-.2 E(in libarchi)0 36 Q .3 -.15(ve 1)-.25 H -(.x, which made it impossible to detect errors when).15 E(<b>archi)0 48 -Q -.15(ve)-.25 G(_write_close</b>\(<code></code>\)).15 E -.1(wa)0 60 S -2.5(si).1 G -1.9 -.4(nv o)-2.5 H -.1(ke).4 G 2.5(di).1 G -(mplicitly from this function.)-2.5 E(This is corrected be)0 72 Q -(ginning with libarchi)-.15 E .3 -.15(ve 2)-.25 H(.0.).15 E 0 Cg EP -%%Page: 62 62 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(</dl>)0 12 Q(More information about the)0 24 Q -(<i></i><i>struct</i><i> archi)0 36 Q -.15(ve)-.25 G(</i>).15 E -(object and the o)0 48 Q -.15(ve)-.15 G -(rall design of the library can be found in the).15 E -(<a href="../html3/libarchi)0 60 Q -.15(ve)-.25 G(.html">libarchi).15 E --.15(ve)-.25 G(\(3\)</a>).15 E -.15(ove)0 72 S(rvie).15 E -.65(w.)-.25 G -0 Cg EP -%%Page: 63 63 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(<h3 id="IMPLEMENT)36 12 Q -1.11(AT)-.93 G(ION">) -1.11 E(IMPLEMENT)36 24 Q -1.11(AT)-.93 G(ION)1.11 E(</h3>)36 36 Q -(Compression support is b)0 48 Q(uilt-in to libarchi)-.2 E -.15(ve)-.25 -G 2.5(,w).15 G(hich uses zlib and bzlib)-2.5 E -(to handle gzip and bzip2 compression, respecti)0 60 Q -.15(ve)-.25 G -(ly).15 E(.)-.65 E(<h3 id="CLIENT CALLB)36 72 Q -.4(AC)-.35 G(KS">).4 E -0 Cg EP -%%Page: 64 64 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(CLIENT CALLB)36 12 Q -.4(AC)-.35 G(KS).4 E -(</h3>)36 24 Q 1.6 -.8(To u)0 36 T(se this library).8 E 2.5(,y)-.65 G -(ou will need to de\214ne and re)-2.5 E(gister)-.15 E -(callback functions that will be in)0 48 Q -.2(vo)-.4 G -.1(ke).2 G 2.5 -(dt).1 G 2.5(ow)-2.5 G(rite data to the)-2.5 E(resulting archi)0 60 Q --.15(ve)-.25 G(.).15 E(These functions are re)0 72 Q -(gistered by calling)-.15 E 0 Cg EP -%%Page: 65 65 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(<b>archi)0 12 Q -.15(ve)-.25 G -(_write_open</b>\(<code></code>\):).15 E(<dl>)0 24 Q(<p><dd>)0 36 Q -(<br><br><code></code><code>typedef</code><code> int</code>)0 48 Q -(<b>archi)0 60 Q -.15(ve)-.25 G -(_open_callback</b>\(<code></code><code>struct archi).15 E .3 -.15(ve *) --.25 H(</code><code>, v).15 E(oid *client_data</code>\))-.2 E(</dl>)0 72 -Q 0 Cg EP -%%Page: 66 66 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(<p>)36 12 Q(The open callback is in)0 24 Q -.2 -(vo)-.4 G -.1(ke).2 G 2.5(db).1 G(y)-2.5 E(<b>archi)0 36 Q -.15(ve)-.25 -G(_write_open</b>\(<code></code>\).).15 E(It should return)0 48 Q -(<b></b><b>ARCHIVE_OK</b>)0 60 Q -(if the underlying \214le or data source is successfully)0 72 Q 0 Cg EP -%%Page: 67 67 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(opened.)0 12 Q(If the open f)0 24 Q -(ails, it should call)-.1 E(<b>archi)0 36 Q -.15(ve)-.25 G -(_set_error</b>\(<code></code>\)).15 E(to re)0 48 Q -(gister an error code and message and return)-.15 E(<b></b><b>ARCHIVE_F) -0 60 Q -1.21 -1.11(AT A)-.74 H(L</b>.)1.11 E(<dl>)0 72 Q 0 Cg EP -%%Page: 68 68 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(<p><dd>)0 12 Q -(<br><br><code></code><code>typedef</code><code> ssize_t</code>)0 24 Q -(<b>archi)0 36 Q -.15(ve)-.25 G(_write_callback</b>\(<code></code>).15 E -(<code></code><code>struct archi)0 48 Q .3 -.15(ve *)-.25 H(</code>).15 -E(<code></code><code>v)0 60 Q(oid *client_data</code>)-.2 E -(<code></code><code>const v)0 72 Q(oid *b)-.2 E(uf)-.2 E(fer</code>)-.25 -E 0 Cg EP -%%Page: 69 69 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(<code></code><code>size_t length</code>)0 12 Q -(\))0 24 Q(</dl>)0 36 Q(<p>)36 48 Q(The write callback is in)0 60 Q -.2 -(vo)-.4 G -.1(ke).2 G 2.5(dw).1 G(hene)-2.5 E -.15(ve)-.25 G 2.5(rt).15 -G(he library)-2.5 E(needs to write ra)0 72 Q 2.5(wb)-.15 G -(ytes to the archi)-2.5 E -.15(ve)-.25 G(.).15 E 0 Cg EP -%%Page: 70 70 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF -.15(Fo)0 12 S 2.5(rc).15 G -(orrect blocking, each call to the write callback function)-2.5 E -(should translate into a single)0 24 Q -(<a href="../html2/write.html">write\(2\)</a>)0 36 Q(system call.)0 48 Q -(This is especially critical when writing archi)0 60 Q -.15(ve)-.25 G -2.5(st).15 G 2.5(ot)-2.5 G(ape dri)-2.5 E -.15(ve)-.25 G(s.).15 E -(On success, the write callback should return the)0 72 Q 0 Cg EP -%%Page: 71 71 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(number of bytes actually written.)0 12 Q -(On error)0 24 Q 2.5(,t)-.4 G(he callback should in)-2.5 E -.2(vo)-.4 G --.1(ke).2 G(<b>archi)0 36 Q -.15(ve)-.25 G -(_set_error</b>\(<code></code>\)).15 E(to re)0 48 Q -(gister an error code and message and return -1.)-.15 E(<dl>)0 60 Q -(<p><dd>)0 72 Q 0 Cg EP -%%Page: 72 72 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF -(<br><br><code></code><code>typedef</code><code> int</code>)0 12 Q -(<b>archi)0 24 Q -.15(ve)-.25 G -(_close_callback</b>\(<code></code><code>struct archi).15 E .3 -.15 -(ve *)-.25 H(</code><code>, v).15 E(oid *client_data</code>\))-.2 E -(</dl>)0 36 Q(<p>)36 48 Q(The close callback is in)0 60 Q -.2(vo)-.4 G --.1(ke).2 G 2.5(db).1 G 2.5(ya)-2.5 G(rchi)-2.5 E -.15(ve)-.25 G -(_close when).15 E(the archi)0 72 Q .3 -.15(ve p)-.25 H -(rocessing is complete.).15 E 0 Cg EP -%%Page: 73 73 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(The callback should return)0 12 Q -(<b></b><b>ARCHIVE_OK</b>)0 24 Q(on success.)0 36 Q(On f)0 48 Q -(ailure, the callback should in)-.1 E -.2(vo)-.4 G -.1(ke).2 G(<b>archi) -0 60 Q -.15(ve)-.25 G(_set_error</b>\(<code></code>\)).15 E(to re)0 72 Q -(gister an error code and message and)-.15 E 0 Cg EP -%%Page: 74 74 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(return)0 12 Q(<b></b><b>ARCHIVE_F)0 24 Q -1.21 --1.11(AT A)-.74 H(L.</b>)1.11 E(<h3 id="EXAMPLE">)36 36 Q(EXAMPLE)36 48 -Q(</h3>)36 60 Q(The follo)0 72 Q(wing sk)-.25 E -(etch illustrates basic usage of the library)-.1 E(.)-.65 E 0 Cg EP -%%Page: 75 75 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(In this e)0 12 Q(xample,)-.15 E -(the callback functions are simply wrappers around the standard)0 24 Q -(<a href="../html2/open.html">open\(2\)</a>,)0 36 Q -(<a href="../html2/write.html">write\(2\)</a>,)0 48 Q(and)0 60 Q -(<a href="../html2/close.html">close\(2\)</a>)0 72 Q 0 Cg EP -%%Page: 76 76 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(system calls.)0 12 Q(<dl compact><dt><dd>)0 24 Q -(<code>)0 36 Q(<pre>)0 48 Q(#ifdef __linux__)0 60 Q 4.06 -(#de\214ne _FILE_OFFSET_BITS)0 72 R(64)2.5 E 0 Cg EP -%%Page: 77 77 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(#endif)0 12 Q(#include <sys/stat.h>)0 24 Q -(#include <archi)0 36 Q -.15(ve)-.25 G(.h>).15 E(#include <archi)0 48 Q --.15(ve)-.25 G(_entry).15 E(.h>)-.65 E(#include <fcntl.h>)0 60 Q -(#include <stdlib)0 72 Q(.h>)-.4 E 0 Cg EP -%%Page: 78 78 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(#include <unistd.h>)0 12 Q(<p>)36 24 Q -(struct mydata {)0 36 Q(const char *name;)36 48 Q(int fd;)36 60 Q(};)0 -72 Q 0 Cg EP -%%Page: 79 79 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(<p>)36 12 Q(int)0 24 Q(myopen\(struct archi)0 36 -Q .3 -.15(ve *)-.25 H(a, v).15 E(oid *client_data\))-.2 E({)0 48 Q -(struct mydata *mydata = client_data;)5 60 Q(<p>)36 72 Q 0 Cg EP -%%Page: 80 80 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(mydata->fd = open\(mydata->name, O_WR)5 12 Q -(ONL)-.4 E 2.5(Y|O)-1 G(_CREA)-2.5 E 1.48 -.74(T, 0)-1.11 H(644\);).74 E -(if \(mydata->fd >= 0\))5 24 Q(return \(ARCHIVE_OK\);)10 36 Q(else)5 48 -Q(return \(ARCHIVE_F)10 60 Q -1.21 -1.11(AT A)-.74 H(L\);)1.11 E(})0 72 -Q 0 Cg EP -%%Page: 81 81 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(<p>)36 12 Q(ssize_t)0 24 Q -(mywrite\(struct archi)0 36 Q .3 -.15(ve *)-.25 H(a, v).15 E -(oid *client_data, const v)-.2 E(oid *b)-.2 E(uf)-.2 E(f, size_t n\)) --.25 E({)0 48 Q(struct mydata *mydata = client_data;)5 60 Q(<p>)36 72 Q -0 Cg EP -%%Page: 82 82 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(return \(write\(mydata->fd, b)5 12 Q(uf)-.2 E -(f, n\)\);)-.25 E(})0 24 Q(<p>)36 36 Q(int)0 48 Q(myclose\(struct archi) -0 60 Q .3 -.15(ve *)-.25 H(a, v).15 E(oid *client_data\))-.2 E({)0 72 Q -0 Cg EP -%%Page: 83 83 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(struct mydata *mydata = client_data;)5 12 Q(<p>) -36 24 Q(if \(mydata->fd > 0\))5 36 Q(close\(mydata->fd\);)10 48 Q -(return \(0\);)5 60 Q(})0 72 Q 0 Cg EP -%%Page: 84 84 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(<p>)36 12 Q -.2(vo)0 24 S(id).2 E(write_archi)0 -36 Q -.15(ve)-.25 G(\(const char *outname, const char **\214lename\)).15 -E({)0 48 Q(struct mydata *mydata = malloc\(sizeof\(struct mydata\)\);)5 -60 Q(struct archi)5 72 Q .3 -.15(ve *)-.25 H(a;).15 E 0 Cg EP -%%Page: 85 85 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(struct archi)5 12 Q -.15(ve)-.25 G -(_entry *entry;).15 E(struct stat st;)5 24 Q(char b)5 36 Q(uf)-.2 E -(f[8192];)-.25 E(int len;)5 48 Q(int fd;)5 60 Q(<p>)36 72 Q 0 Cg EP -%%Page: 86 86 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF 2.5(a=a)5 12 S(rchi)-2.5 E -.15(ve)-.25 G -(_write_ne).15 E(w\(\);)-.25 E(mydata->name = outname;)5 24 Q(archi)5 36 -Q -.15(ve)-.25 G(_write_set_compression_gzip\(a\);).15 E(archi)5 48 Q --.15(ve)-.25 G(_write_set_format_ustar\(a\);).15 E(archi)5 60 Q -.15(ve) --.25 G(_write_open\(a, mydata, myopen, mywrite, myclose\);).15 E -(while \(*\214lename\) {)5 72 Q 0 Cg EP -%%Page: 87 87 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(stat\(*\214lename, &st\);)10 12 Q(entry = archi) -10 24 Q -.15(ve)-.25 G(_entry_ne).15 E(w\(\);)-.25 E(archi)10 36 Q -.15 -(ve)-.25 G(_entry_cop).15 E(y_stat\(entry)-.1 E 2.5(,&)-.65 G(st\);)-2.5 -E(archi)10 48 Q -.15(ve)-.25 G(_entry_set_pathname\(entry).15 E 2.5(,*) --.65 G(\214lename\);)-2.5 E(archi)10 60 Q -.15(ve)-.25 G -(_write_header\(a, entry\);).15 E(fd = open\(*\214lename, O_RDONL)10 72 -Q(Y\);)-1 E 0 Cg EP -%%Page: 88 88 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(len = read\(fd, b)10 12 Q(uf)-.2 E(f, sizeof\(b) --.25 E(uf)-.2 E(f\)\);)-.25 E(while \( len > 0 \) {)10 24 Q(archi)36 36 -Q -.15(ve)-.25 G(_write_data\(a, b).15 E(uf)-.2 E(f, len\);)-.25 E -(len = read\(fd, b)36 48 Q(uf)-.2 E(f, sizeof\(b)-.25 E(uf)-.2 E(f\)\);) --.25 E(})10 60 Q(archi)10 72 Q -.15(ve)-.25 G(_entry_free\(entry\);).15 -E 0 Cg EP -%%Page: 89 89 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(\214lename++;)10 12 Q(})5 24 Q(archi)5 36 Q -.15 -(ve)-.25 G(_write_\214nish\(a\);).15 E(})0 48 Q(<p>)36 60 Q -(int main\(int ar)0 72 Q(gc, const char **ar)-.18 E(gv\))-.18 E 0 Cg EP -%%Page: 90 90 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF({)0 12 Q(const char *outname;)36 24 Q(ar)36 36 Q -(gv++;)-.18 E(outname = ar)36 48 Q(gv++;)-.18 E(write_archi)36 60 Q -.15 -(ve)-.25 G(\(outname, ar).15 E(gv\);)-.18 E(return 0;)36 72 Q 0 Cg EP -%%Page: 91 91 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(})0 12 Q(</pre>)0 24 Q(</code>)0 36 Q(</dl>)0 48 -Q(<h3 id="RETURN V)36 60 Q(ALUES">)-1.35 E(RETURN V)36 72 Q(ALUES)-1.35 -E 0 Cg EP -%%Page: 92 92 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(</h3>)36 12 Q(Most functions return)0 24 Q -(<b></b><b>ARCHIVE_OK</b>)0 36 Q(\(zero\) on success, or one of se)0 48 -Q -.15(ve)-.25 G(ral non-zero).15 E(error codes for errors.)0 60 Q -(Speci\214c error codes include:)0 72 Q 0 Cg EP -%%Page: 93 93 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(<b></b><b>ARCHIVE_RETR)0 12 Q(Y</b>)-.65 E -(for operations that might succeed if retried,)0 24 Q -(<b></b><b>ARCHIVE_W)0 36 Q(ARN</b>)-1.2 E -(for unusual conditions that do not pre)0 48 Q -.15(ve)-.25 G -(nt further operations, and).15 E(<b></b><b>ARCHIVE_F)0 60 Q -1.21 -1.11 -(AT A)-.74 H(L</b>)1.11 E(for serious errors that mak)0 72 Q 2.5(er)-.1 -G(emaining operations impossible.)-2.5 E 0 Cg EP -%%Page: 94 94 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(The)0 12 Q(<b>archi)0 24 Q -.15(ve)-.25 G -(_errno</b>\(<code></code>\)).15 E(and)0 36 Q(<b>archi)0 48 Q -.15(ve) --.25 G(_error_string</b>\(<code></code>\)).15 E -(functions can be used to retrie)0 60 Q .3 -.15(ve a)-.25 H 2.5(na).15 G -(ppropriate error code and a)-2.5 E(te)0 72 Q(xtual error message.)-.15 -E 0 Cg EP -%%Page: 95 95 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(<p>)36 12 Q(<b>archi)0 24 Q -.15(ve)-.25 G -(_write_ne).15 E(w</b>\(<code></code>\))-.25 E -(returns a pointer to a ne)0 36 Q(wly-allocated)-.25 E(<font size="-1">\ -</font><font size="-1">struct</font><font size="-1"> archi)0 48 Q -.15 -(ve)-.25 G(</font>).15 E(object.)0 60 Q(<p>)36 72 Q 0 Cg EP -%%Page: 96 96 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(<b>archi)0 12 Q -.15(ve)-.25 G -(_write_data</b>\(<code></code>\)).15 E -(returns a count of the number of bytes actually written.)0 24 Q -(On error)0 36 Q 2.5(,-)-.4 G 2.5(1i)-2.5 G 2.5(sr)-2.5 G -(eturned and the)-2.5 E(<b>archi)0 48 Q -.15(ve)-.25 G -(_errno</b>\(<code></code>\)).15 E(and)0 60 Q(<b>archi)0 72 Q -.15(ve) --.25 G(_error_string</b>\(<code></code>\)).15 E 0 Cg EP -%%Page: 97 97 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(functions will return appropriate v)0 12 Q -(alues.)-.25 E(Note that if the client-pro)0 24 Q -(vided write callback function)-.15 E(returns a non-zero v)0 36 Q -(alue, that error will be propag)-.25 E(ated back to the caller)-.05 E -(through whate)0 48 Q -.15(ve)-.25 G 2.5(rA).15 G -(PI function resulted in that call, which)-2.5 E(may include)0 60 Q -(<b>archi)0 72 Q -.15(ve)-.25 G(_write_header</b>\(<code></code>\),).15 -E 0 Cg EP -%%Page: 98 98 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(<b>archi)0 12 Q -.15(ve)-.25 G -(_write_data</b>\(<code></code>\),).15 E(<b>archi)0 24 Q -.15(ve)-.25 G -(_write_close</b>\(<code></code>\),).15 E(or)0 36 Q(<b>archi)0 48 Q -.15 -(ve)-.25 G(_write_\214nish</b>\(<code></code>\).).15 E -(The client callback can call)0 60 Q(<b>archi)0 72 Q -.15(ve)-.25 G -(_set_error</b>\(<code></code>\)).15 E 0 Cg EP -%%Page: 99 99 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(to pro)0 12 Q(vide v)-.15 E -(alues that can then be retrie)-.25 E -.15(ve)-.25 G 2.5(db).15 G(y)-2.5 -E(<b>archi)0 24 Q -.15(ve)-.25 G(_errno</b>\(<code></code>\)).15 E(and)0 -36 Q(<b>archi)0 48 Q -.15(ve)-.25 G(_error_string</b>\(<code></code>\).) -.15 E(<h3 id="SEE ALSO">)36 60 Q(SEE ALSO)36 72 Q 0 Cg EP -%%Page: 100 100 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(</h3>)36 12 Q(<a href="../html1/tar)0 24 Q -(.html">tar\(1\)</a>,)-.55 E(<a href="../html3/libarchi)0 36 Q -.15(ve) --.25 G(.html">libarchi).15 E -.15(ve)-.25 G(\(3\)</a>,).15 E -(<a href="../html5/tar)0 48 Q(.html">tar\(5\)</a>)-.55 E(<h3 id="HIST)36 -60 Q(OR)-.18 E(Y">)-.65 E(HIST)36 72 Q(OR)-.18 E(Y)-.65 E 0 Cg EP -%%Page: 101 101 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(</h3>)36 12 Q(The)0 24 Q(<b>libarchi)0 36 Q -.15 -(ve)-.25 G(</b>).15 E(library \214rst appeared in)0 48 Q(FreeBSD5.3.)0 -60 Q(<h3 id="A)36 72 Q(UTHORS">)-.55 E 0 Cg EP -%%Page: 102 102 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF -.55(AU)36 12 S(THORS).55 E(</h3>)36 24 Q(<p>)36 -36 Q(The)0 48 Q(<b>libarchi)0 60 Q -.15(ve)-.25 G(</b>).15 E(library w)0 -72 Q(as written by)-.1 E 0 Cg EP -%%Page: 103 103 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF -.35(Ti)0 12 S 2.5(mK).35 G -(ientzle <kientzle@acm.or)-2.5 E(g>.)-.18 E(<h3 id="B)36 24 Q -(UGS">)-.1 E -.1(BU)36 36 S(GS).1 E(</h3>)36 48 Q(There are man)0 60 Q -2.5(yp)-.15 G(eculiar b)-2.5 E -(ugs in historic tar implementations that may cause)-.2 E -(certain programs to reject archi)0 72 Q -.15(ve)-.25 G 2.5(sw).15 G -(ritten by this library)-2.5 E(.)-.65 E 0 Cg EP -%%Page: 104 104 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF -.15(Fo)0 12 S 2.5(re).15 G(xample, se)-2.65 E --.15(ve)-.25 G(ral historic implementations calculated header checksums) -.15 E(incorrectly and will thus reject v)0 24 Q(alid archi)-.25 E -.15 -(ve)-.25 G(s; GNU tar does not fully support).15 E(pax interchange form\ -at; some old tar implementations required speci\214c)0 36 Q -(\214eld terminations.)0 48 Q(<p>)36 60 Q(The def)0 72 Q -(ault pax interchange format eliminates most of the historic)-.1 E 0 Cg -EP -%%Page: 105 105 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(tar limitations and pro)0 12 Q -(vides a generic k)-.15 E -.15(ey)-.1 G(/v).15 E(alue attrib)-.25 E -(ute f)-.2 E(acility)-.1 E(for v)0 24 Q(endor)-.15 E(-de\214ned e)-.2 E -(xtensions.)-.15 E(One o)0 36 Q -.15(ve)-.15 G(rsight in POSIX is the f) -.15 E(ailure to pro)-.1 E(vide a standard attrib)-.15 E(ute)-.2 E -(for lar)0 48 Q(ge de)-.18 E(vice numbers.)-.25 E(This library uses)0 60 -Q -.74(``)0 72 S(SCHIL).74 E -1.29(Y.)-1 G(de)1.29 E(vminor')-.25 E(') --.74 E 0 Cg EP -%%Page: 106 106 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(and)0 12 Q -.74(``)0 24 S(SCHIL).74 E -1.29(Y.) --1 G(de)1.29 E(vmajor')-.25 E(')-.74 E(for de)0 36 Q -(vice numbers that e)-.25 E(xceed the range supported by the backw)-.15 -E(ards-compatible)-.1 E(ustar header)0 48 Q(.)-.55 E(These k)0 60 Q -.15 -(ey)-.1 G 2.5(sa).15 G(re compatible with Joer)-2.5 E 2.5(gS)-.18 G -(chilling')-2.5 E(s)-.55 E(<b>star</b>)0 72 Q 0 Cg EP -%%Page: 107 107 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(archi)0 12 Q -.15(ve)-.25 G -.55(r.).15 G -(Other implementations may not recognize these k)0 24 Q -.15(ey)-.1 G -2.5(sa).15 G(nd will thus be unable)-2.5 E(to correctly restore de)0 36 -Q(vice nodes with lar)-.25 E(ge de)-.18 E(vice numbers from archi)-.25 E --.15(ve)-.25 G(s).15 E(created by this library)0 48 Q(.)-.65 E(</body>)0 -60 Q(</html>)0 72 Q 0 Cg EP -%%Trailer -end -%%EOF +<!-- Creator : groff version 1.19.2 --> +<!-- CreationDate: Sun Mar 14 19:50:23 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">archive_write(3) FreeBSD Library Functions +Manual archive_write(3)</p> + +<p style="margin-top: 1em" valign="top"><b>NAME</b></p> + +<p style="margin-left:8%;"><b>archive_write_new</b>, +<b>archive_write_set_format_cpio</b>, +<b>archive_write_set_format_pax</b>, +<b>archive_write_set_format_pax_restricted</b>, +<b>archive_write_set_format_shar</b>, +<b>archive_write_set_format_shar_binary</b>, +<b>archive_write_set_format_ustar</b>, +<b>archive_write_get_bytes_per_block</b>, +<b>archive_write_set_bytes_per_block</b>, +<b>archive_write_set_bytes_in_last_block</b>, +<b>archive_write_set_compression_bzip2</b>, +<b>archive_write_set_compression_compress</b>, +<b>archive_write_set_compression_gzip</b>, +<b>archive_write_set_compression_none</b>, +<b>archive_write_set_compression_program</b>, +<b>archive_write_set_compressor_options</b>, +<b>archive_write_set_format_options</b>, +<b>archive_write_set_options</b>, <b>archive_write_open</b>, +<b>archive_write_open_fd</b>, +<b>archive_write_open_FILE</b>, +<b>archive_write_open_filename</b>, +<b>archive_write_open_memory</b>, +<b>archive_write_header</b>, <b>archive_write_data</b>, +<b>archive_write_finish_entry</b>, +<b>archive_write_close</b>, <b>archive_write_finish</b> +— functions for creating archives</p> + + +<p style="margin-top: 1em" valign="top"><b>SYNOPSIS</b></p> + +<p style="margin-left:8%;"><b>#include +<archive.h></b></p> + +<p style="margin-left:8%; margin-top: 1em"><i>struct +archive *</i></p> + + +<p style="margin-left:14%;"><b>archive_write_new</b>(<i>void</i>);</p> + +<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> + + +<p style="margin-left:14%;"><b>archive_write_get_bytes_per_block</b>(<i>struct archive *</i>);</p> + +<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> + + +<p style="margin-left:14%;"><b>archive_write_set_bytes_per_block</b>(<i>struct archive *</i>, +<i>int bytes_per_block</i>);</p> + +<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> + + +<p style="margin-left:14%;"><b>archive_write_set_bytes_in_last_block</b>(<i>struct archive *</i>, +<i>int</i>);</p> + +<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> + + +<p style="margin-left:14%;"><b>archive_write_set_compression_bzip2</b>(<i>struct archive *</i>);</p> + +<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> + + +<p style="margin-left:14%;"><b>archive_write_set_compression_compress</b>(<i>struct archive *</i>);</p> + +<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> + + +<p style="margin-left:14%;"><b>archive_write_set_compression_gzip</b>(<i>struct archive *</i>);</p> + +<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> + + +<p style="margin-left:14%;"><b>archive_write_set_compression_none</b>(<i>struct archive *</i>);</p> + +<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> + + +<p style="margin-left:14%;"><b>archive_write_set_compression_program</b>(<i>struct archive *</i>, +<i>const char * cmd</i>);</p> + +<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> + + +<p style="margin-left:14%;"><b>archive_write_set_format_cpio</b>(<i>struct archive *</i>);</p> + +<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> + + +<p style="margin-left:14%;"><b>archive_write_set_format_pax</b>(<i>struct archive *</i>);</p> + +<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> + + +<p style="margin-left:14%;"><b>archive_write_set_format_pax_restricted</b>(<i>struct archive *</i>);</p> + +<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> + + +<p style="margin-left:14%;"><b>archive_write_set_format_shar</b>(<i>struct archive *</i>);</p> + +<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> + + +<p style="margin-left:14%;"><b>archive_write_set_format_shar_binary</b>(<i>struct archive *</i>);</p> + +<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> + + +<p style="margin-left:14%;"><b>archive_write_set_format_ustar</b>(<i>struct archive *</i>);</p> + +<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> + + +<p style="margin-left:14%;"><b>archive_write_set_format_options</b>(<i>struct archive *</i>, +<i>const char *</i>);</p> + +<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> + + +<p style="margin-left:14%;"><b>archive_write_set_compressor_options</b>(<i>struct archive *</i>, +<i>const char *</i>);</p> + +<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> + + +<p style="margin-left:14%;"><b>archive_write_set_options</b>(<i>struct archive *</i>, +<i>const char *</i>);</p> + +<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> + + +<p valign="top"><b>archive_write_open</b>(<i>struct archive *</i>, +<i>void *client_data</i>, +<i>archive_open_callback *</i>, +<i>archive_write_callback *</i>, +<i>archive_close_callback *</i>);</p> + +<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> + + +<p style="margin-left:14%;"><b>archive_write_open_fd</b>(<i>struct archive *</i>, +<i>int fd</i>);</p> + +<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> + + +<p style="margin-left:14%;"><b>archive_write_open_FILE</b>(<i>struct archive *</i>, +<i>FILE *file</i>);</p> + +<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> + + +<p style="margin-left:14%;"><b>archive_write_open_filename</b>(<i>struct archive *</i>, +<i>const char *filename</i>);</p> + +<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> + + +<p valign="top"><b>archive_write_open_memory</b>(<i>struct archive *</i>, +<i>void *buffer</i>, <i>size_t bufferSize</i>, +<i>size_t *outUsed</i>);</p> + +<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> + + +<p style="margin-left:14%;"><b>archive_write_header</b>(<i>struct archive *</i>, +<i>struct archive_entry *</i>);</p> + + +<p style="margin-left:8%; margin-top: 1em"><i>ssize_t</i></p> + + +<p style="margin-left:14%;"><b>archive_write_data</b>(<i>struct archive *</i>, +<i>const void *</i>, <i>size_t</i>);</p> + +<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> + + +<p style="margin-left:14%;"><b>archive_write_finish_entry</b>(<i>struct archive *</i>);</p> + +<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> + + +<p style="margin-left:14%;"><b>archive_write_close</b>(<i>struct archive *</i>);</p> + +<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> + + +<p style="margin-left:14%;"><b>archive_write_finish</b>(<i>struct archive *</i>);</p> + + +<p style="margin-top: 1em" valign="top"><b>DESCRIPTION</b></p> + +<p style="margin-left:8%;">These functions provide a +complete API for creating streaming archive files. The +general process is to first create the struct archive +object, set any desired options, initialize the archive, +append entries, then close the archive and release all +resources. The following summary describes the functions in +approximately the order they are ordinarily used:</p> + + +<p style="margin-top: 1em" valign="top"><b>archive_write_new</b>()</p> + +<p style="margin-left:20%;">Allocates and initializes a +struct archive object suitable for writing a tar +archive.</p> + + +<p style="margin-top: 1em" valign="top"><b>archive_write_set_bytes_per_block</b>()</p> + +<p style="margin-left:20%;">Sets the block size used for +writing the archive data. Every call to the write callback +function, except possibly the last one, will use this value +for the length. The third parameter is a boolean that +specifies whether or not the final block written will be +padded to the full block size. If it is zero, the last block +will not be padded. If it is non-zero, padding will be added +both before and after compression. The default is to use a +block size of 10240 bytes and to pad the last block. Note +that a block size of zero will suppress internal blocking +and cause writes to be sent directly to the write callback +as they occur.</p> + + +<p style="margin-top: 1em" valign="top"><b>archive_write_get_bytes_per_block</b>()</p> + +<p style="margin-left:20%;">Retrieve the block size to be +used for writing. A value of -1 here indicates that the +library should use default values. A value of zero indicates +that internal blocking is suppressed.</p> + + +<p style="margin-top: 1em" valign="top"><b>archive_write_set_bytes_in_last_block</b>()</p> + +<p style="margin-left:20%;">Sets the block size used for +writing the last block. If this value is zero, the last +block will be padded to the same size as the other blocks. +Otherwise, the final block will be padded to a multiple of +this size. In particular, setting it to 1 will cause the +final block to not be padded. For compressed output, any +padding generated by this option is applied only after the +compression. The uncompressed data is always unpadded. The +default is to pad the last block to the full block size +(note that <b>archive_write_open_filename</b>() will set +this based on the file type). Unlike the other +‘‘set’’ functions, this function can +be called after the archive is opened.</p> + + +<p style="margin-top: 1em" valign="top"><b>archive_write_get_bytes_in_last_block</b>()</p> + +<p style="margin-left:20%;">Retrieve the currently-set +value for last block size. A value of -1 here indicates that +the library should use default values.</p> + + +<p style="margin-top: 1em" valign="top"><b>archive_write_set_format_cpio</b>(), +<b>archive_write_set_format_pax</b>(), +<b>archive_write_set_format_pax_restricted</b>(), +<b>archive_write_set_format_shar</b>(), +<b>archive_write_set_format_shar_binary</b>(), +<b>archive_write_set_format_ustar</b>()</p> + +<p style="margin-left:20%;">Sets the format that will be +used for the archive. The library can write POSIX +octet-oriented cpio format archives, POSIX-standard +‘‘pax interchange’’ format archives, +traditional ‘‘shar’’ archives, +enhanced ‘‘binary’’ shar archives +that store a variety of file attributes and handle binary +files, and POSIX-standard ‘‘ustar’’ +archives. The pax interchange format is a +backwards-compatible tar format that adds key/value +attributes to each entry and supports arbitrary filenames, +linknames, uids, sizes, etc. ‘‘Restricted pax +interchange format’’ is the library default; +this is the same as pax format, but suppresses the pax +extended header for most normal files. In most cases, this +will result in ordinary ustar archives.</p> + + +<p style="margin-top: 1em" valign="top"><b>archive_write_set_compression_bzip2</b>(), +<b>archive_write_set_compression_compress</b>(), +<b>archive_write_set_compression_gzip</b>(), +<b>archive_write_set_compression_none</b>()</p> + +<p style="margin-left:20%;">The resulting archive will be +compressed as specified. Note that the compressed output is +always properly blocked.</p> + + +<p style="margin-top: 1em" valign="top"><b>archive_write_set_compression_program</b>()</p> + +<p style="margin-left:20%;">The archive will be fed into +the specified compression program. The output of that +program is blocked and written to the client write +callbacks.</p> + + +<p style="margin-top: 1em" valign="top"><b>archive_write_set_compressor_options</b>(), +<b>archive_write_set_format_options</b>(), +<b>archive_write_set_options</b>()</p> + +<p style="margin-left:20%;">Specifies options that will be +passed to the currently-enabled compressor and/or format +writer. The argument is a comma-separated list of individual +options. Individual options have one of the following +forms:</p> + +<p valign="top"><i>option=value</i></p> + +<p style="margin-left:32%;">The option/value pair will be +provided to every module. Modules that do not accept an +option with this name will ignore it.</p> + +<p valign="top"><i>option</i></p> + +<p style="margin-left:32%; margin-top: 1em">The option will +be provided to every module with a value of +‘‘1’’.</p> + +<p valign="top"><i>!option</i></p> + +<p style="margin-left:32%;">The option will be provided to +every module with a NULL value.</p> + +<p valign="top"><i>module:option=value</i>, +<i>module:option</i>, <i>module:!option</i></p> + +<p style="margin-left:32%;">As above, but the corresponding +option and value will be provided only to modules whose name +matches <i>module</i>.</p> + +<p style="margin-left:20%;">The return value will be +<b>ARCHIVE_OK</b> if any module accepts the option, or +<b>ARCHIVE_WARN</b> if no module accepted the option, or +<b>ARCHIVE_FATAL</b> if there was a fatal error while +attempting to process the option.</p> + +<p style="margin-left:20%; margin-top: 1em">The currently +supported options are:</p> + +<p valign="top">Compressor gzip <b><br> +compression-level</b></p> + +<p style="margin-left:45%;">The value is interpreted as a +decimal integer specifying the gzip compression level.</p> + +<p valign="top">Compressor xz <b><br> +compression-level</b></p> + +<p style="margin-left:45%;">The value is interpreted as a +decimal integer specifying the compression level.</p> + +<p valign="top">Format mtree <b><br> +cksum</b>, <b>device</b>, <b>flags</b>, <b>gid</b>, +<b>gname</b>, <b>indent</b>, <b>link</b>, <b>md5</b>, +<b>mode</b>, <b>nlink</b>, <b>rmd160</b>, <b>sha1</b>, +<b>sha256</b>, <b>sha384</b>, <b>sha512</b>, <b>size</b>, +<b>time</b>, <b>uid</b>, <b>uname</b></p> + +<p style="margin-left:45%;">Enable a particular keyword in +the mtree output. Prefix with an exclamation mark to disable +the corresponding keyword. The default is equivalent to +‘‘device, flags, gid, gname, link, mode, nlink, +size, time, type, uid, uname’’.</p> + +<p valign="top"><b>all</b></p> + +<p style="margin-left:45%; margin-top: 1em">Enables all of +the above keywords.</p> + +<p valign="top"><b>use-set</b></p> + +<p style="margin-left:45%;">Enables generation of +<b>/set</b> lines that specify default values for the +following files and/or directories.</p> + +<p valign="top"><b>indent</b></p> + +<p style="margin-left:45%; margin-top: 1em">XXX needs +explanation XXX</p> + + +<p style="margin-top: 1em" valign="top"><b>archive_write_open</b>()</p> + +<p style="margin-left:20%;">Freeze the settings, open the +archive, and prepare for writing entries. This is the most +generic form of this function, which accepts pointers to +three callback functions which will be invoked by the +compression layer to write the constructed archive.</p> + + +<p style="margin-top: 1em" valign="top"><b>archive_write_open_fd</b>()</p> + +<p style="margin-left:20%;">A convenience form of +<b>archive_write_open</b>() that accepts a file descriptor. +The <b>archive_write_open_fd</b>() function is safe for use +with tape drives or other block-oriented devices.</p> + + +<p style="margin-top: 1em" valign="top"><b>archive_write_open_FILE</b>()</p> + +<p style="margin-left:20%;">A convenience form of +<b>archive_write_open</b>() that accepts a <i>FILE *</i> +pointer. Note that <b>archive_write_open_FILE</b>() is not +safe for writing to tape drives or other devices that +require correct blocking.</p> + + +<p style="margin-top: 1em" valign="top"><b>archive_write_open_file</b>()</p> + +<p style="margin-left:20%;">A deprecated synonym for +<b>archive_write_open_filename</b>().</p> + + +<p style="margin-top: 1em" valign="top"><b>archive_write_open_filename</b>()</p> + +<p style="margin-left:20%;">A convenience form of +<b>archive_write_open</b>() that accepts a filename. A NULL +argument indicates that the output should be written to +standard output; an argument of +‘‘-’’ will open a file with that +name. If you have not invoked +<b>archive_write_set_bytes_in_last_block</b>(), then +<b>archive_write_open_filename</b>() will adjust the +last-block padding depending on the file: it will enable +padding when writing to standard output or to a character or +block device node, it will disable padding otherwise. You +can override this by manually invoking +<b>archive_write_set_bytes_in_last_block</b>() before +calling <b>archive_write_open</b>(). The +<b>archive_write_open_filename</b>() function is safe for +use with tape drives or other block-oriented devices.</p> + + +<p style="margin-top: 1em" valign="top"><b>archive_write_open_memory</b>()</p> + +<p style="margin-left:20%;">A convenience form of +<b>archive_write_open</b>() that accepts a pointer to a +block of memory that will receive the archive. The final +<i>size_t *</i> argument points to a variable that will be +updated after each write to reflect how much of the buffer +is currently in use. You should be careful to ensure that +this variable remains allocated until after the archive is +closed.</p> + + +<p style="margin-top: 1em" valign="top"><b>archive_write_header</b>()</p> + +<p style="margin-left:20%;">Build and write a header using +the data in the provided struct archive_entry structure. See +archive_entry(3) for information on creating and populating +struct archive_entry objects.</p> + + +<p style="margin-top: 1em" valign="top"><b>archive_write_data</b>()</p> + +<p style="margin-left:20%;">Write data corresponding to the +header just written. Returns number of bytes written or -1 +on error.</p> + + +<p style="margin-top: 1em" valign="top"><b>archive_write_finish_entry</b>()</p> + +<p style="margin-left:20%;">Close out the entry just +written. In particular, this writes out the final padding +required by some formats. Ordinarily, clients never need to +call this, as it is called automatically by +<b>archive_write_next_header</b>() and +<b>archive_write_close</b>() as needed.</p> + + +<p style="margin-top: 1em" valign="top"><b>archive_write_close</b>()</p> + +<p style="margin-left:20%;">Complete the archive and invoke +the close callback.</p> + + +<p style="margin-top: 1em" valign="top"><b>archive_write_finish</b>()</p> + +<p style="margin-left:20%;">Invokes +<b>archive_write_close</b>() if it was not invoked manually, +then releases all resources. Note that this function was +declared to return <i>void</i> in libarchive 1.x, which made +it impossible to detect errors when +<b>archive_write_close</b>() was invoked implicitly from +this function. This is corrected beginning with libarchive +2.0.</p> + +<p style="margin-left:8%;">More information about the +<i>struct archive</i> object and the overall design of the +library can be found in the libarchive(3) overview.</p> + + +<p style="margin-top: 1em" valign="top"><b>IMPLEMENTATION</b></p> + +<p style="margin-left:8%;">Compression support is built-in +to libarchive, which uses zlib and bzlib to handle gzip and +bzip2 compression, respectively.</p> + +<p style="margin-top: 1em" valign="top"><b>CLIENT +CALLBACKS</b></p> + +<p style="margin-left:8%;">To use this library, you will +need to define and register callback functions that will be +invoked to write data to the resulting archive. These +functions are registered by calling +<b>archive_write_open</b>():</p> + +<p style="margin-left:17%; margin-top: 1em"><i>typedef +int</i> <b>archive_open_callback</b>(<i>struct archive +*</i>, <i>void *client_data</i>)</p> + +<p style="margin-left:8%; margin-top: 1em">The open +callback is invoked by <b>archive_write_open</b>(). It +should return <b>ARCHIVE_OK</b> if the underlying file or +data source is successfully opened. If the open fails, it +should call <b>archive_set_error</b>() to register an error +code and message and return <b>ARCHIVE_FATAL</b>.</p> + +<p style="margin-left:17%; margin-top: 1em"><i>typedef +ssize_t</i></p> + + +<p valign="top"><b>archive_write_callback</b>(<i>struct archive *</i>, +<i>void *client_data</i>, +<i>const void *buffer</i>, +<i>size_t length</i>)</p> + +<p style="margin-left:8%; margin-top: 1em">The write +callback is invoked whenever the library needs to write raw +bytes to the archive. For correct blocking, each call to the +write callback function should translate into a single +write(2) system call. This is especially critical when +writing archives to tape drives. On success, the write +callback should return the number of bytes actually written. +On error, the callback should invoke +<b>archive_set_error</b>() to register an error code and +message and return -1.</p> + +<p style="margin-left:17%; margin-top: 1em"><i>typedef +int</i> <b>archive_close_callback</b>(<i>struct archive +*</i>, <i>void *client_data</i>)</p> + +<p style="margin-left:8%; margin-top: 1em">The close +callback is invoked by archive_close when the archive +processing is complete. The callback should return +<b>ARCHIVE_OK</b> on success. On failure, the callback +should invoke <b>archive_set_error</b>() to register an +error code and message and return <b>ARCHIVE_FATAL.</b></p> + +<p style="margin-top: 1em" valign="top"><b>EXAMPLE</b></p> + +<p style="margin-left:8%;">The following sketch illustrates +basic usage of the library. In this example, the callback +functions are simply wrappers around the standard open(2), +write(2), and close(2) system calls.</p> + +<p style="margin-left:17%; margin-top: 1em">#ifdef +__linux__</p> + +<table width="100%" border=0 rules="none" frame="void" + cellspacing="0" cellpadding="0"> +<tr valign="top" align="left"> +<td width="17%"></td> +<td width="12%"> + + +<p valign="top">#define</p></td> +<td width="13%"> + + +<p valign="top">_FILE_OFFSET_BITS 64</p></td> +<td width="58%"> +</td> +</table> + +<p style="margin-left:17%;">#endif <br> +#include <sys/stat.h> <br> +#include <archive.h> <br> +#include <archive_entry.h> <br> +#include <fcntl.h> <br> +#include <stdlib.h> <br> +#include <unistd.h></p> + +<p style="margin-left:17%; margin-top: 1em">struct mydata +{</p> + +<table width="100%" border=0 rules="none" frame="void" + cellspacing="0" cellpadding="0"> +<tr valign="top" align="left"> +<td width="29%"></td> +<td width="71%"> + + +<p valign="top">const char *name;</p></td> +<tr valign="top" align="left"> +<td width="29%"></td> +<td width="71%"> + + +<p valign="top">int fd;</p></td> +</table> + +<p style="margin-left:17%;">};</p> + +<p style="margin-left:17%; margin-top: 1em">int <br> +myopen(struct archive *a, void *client_data) <br> +{ <br> +struct mydata *mydata = client_data;</p> + +<p style="margin-left:17%; margin-top: 1em">mydata->fd = +open(mydata->name, O_WRONLY | O_CREAT, 0644); <br> +if (mydata->fd >= 0) <br> +return (ARCHIVE_OK); <br> +else <br> +return (ARCHIVE_FATAL); <br> +}</p> + +<p style="margin-left:17%; margin-top: 1em">ssize_t <br> +mywrite(struct archive *a, void *client_data, const void +*buff, size_t n) <br> +{ <br> +struct mydata *mydata = client_data;</p> + +<p style="margin-left:17%; margin-top: 1em">return +(write(mydata->fd, buff, n)); <br> +}</p> + +<p style="margin-left:17%; margin-top: 1em">int <br> +myclose(struct archive *a, void *client_data) <br> +{ <br> +struct mydata *mydata = client_data;</p> + +<p style="margin-left:17%; margin-top: 1em">if +(mydata->fd > 0) <br> +close(mydata->fd); <br> +return (0); <br> +}</p> + +<p style="margin-left:17%; margin-top: 1em">void <br> +write_archive(const char *outname, const char **filename) +<br> +{ <br> +struct mydata *mydata = malloc(sizeof(struct mydata)); <br> +struct archive *a; <br> +struct archive_entry *entry; <br> +struct stat st; <br> +char buff[8192]; <br> +int len; <br> +int fd;</p> + +<p style="margin-left:17%; margin-top: 1em">a = +archive_write_new(); <br> +mydata->name = outname; <br> +archive_write_set_compression_gzip(a); <br> +archive_write_set_format_ustar(a); <br> +archive_write_open(a, mydata, myopen, mywrite, myclose); +<br> +while (*filename) { <br> +stat(*filename, &st); <br> +entry = archive_entry_new(); <br> +archive_entry_copy_stat(entry, &st); <br> +archive_entry_set_pathname(entry, *filename); <br> +archive_write_header(a, entry); <br> +fd = open(*filename, O_RDONLY); <br> +len = read(fd, buff, sizeof(buff)); <br> +while ( len > 0 ) {</p> + +<table width="100%" border=0 rules="none" frame="void" + cellspacing="0" cellpadding="0"> +<tr valign="top" align="left"> +<td width="29%"></td> +<td width="71%"> + + +<p valign="top">archive_write_data(a, buff, len);</p></td> +<tr valign="top" align="left"> +<td width="29%"></td> +<td width="71%"> + + +<p valign="top">len = read(fd, buff, sizeof(buff));</p></td> +</table> + +<p style="margin-left:17%;">} <br> +archive_entry_free(entry); <br> +filename++; <br> +} <br> +archive_write_finish(a); <br> +}</p> + +<p style="margin-left:17%; margin-top: 1em">int main(int +argc, const char **argv) <br> +{</p> + +<table width="100%" border=0 rules="none" frame="void" + cellspacing="0" cellpadding="0"> +<tr valign="top" align="left"> +<td width="29%"></td> +<td width="71%"> + + +<p valign="top">const char *outname;</p></td> +<tr valign="top" align="left"> +<td width="29%"></td> +<td width="71%"> + + +<p valign="top">argv++;</p></td> +<tr valign="top" align="left"> +<td width="29%"></td> +<td width="71%"> + + +<p valign="top">outname = argv++;</p></td> +<tr valign="top" align="left"> +<td width="29%"></td> +<td width="71%"> + + +<p valign="top">write_archive(outname, argv);</p></td> +<tr valign="top" align="left"> +<td width="29%"></td> +<td width="71%"> + + +<p valign="top">return 0;</p></td> +</table> + +<p style="margin-left:17%;">}</p> + +<p style="margin-top: 1em" valign="top"><b>RETURN +VALUES</b></p> + +<p style="margin-left:8%;">Most functions return +<b>ARCHIVE_OK</b> (zero) on success, or one of several +non-zero error codes for errors. Specific error codes +include: <b>ARCHIVE_RETRY</b> for operations that might +succeed if retried, <b>ARCHIVE_WARN</b> for unusual +conditions that do not prevent further operations, and +<b>ARCHIVE_FATAL</b> for serious errors that make remaining +operations impossible. The <b>archive_errno</b>() and +<b>archive_error_string</b>() functions can be used to +retrieve an appropriate error code and a textual error +message.</p> + + +<p style="margin-left:8%; margin-top: 1em"><b>archive_write_new</b>() +returns a pointer to a newly-allocated struct archive +object.</p> + + +<p style="margin-left:8%; margin-top: 1em"><b>archive_write_data</b>() +returns a count of the number of bytes actually written. On +error, -1 is returned and the <b>archive_errno</b>() and +<b>archive_error_string</b>() functions will return +appropriate values. Note that if the client-provided write +callback function returns a non-zero value, that error will +be propagated back to the caller through whatever API +function resulted in that call, which may include +<b>archive_write_header</b>(), <b>archive_write_data</b>(), +<b>archive_write_close</b>(), or +<b>archive_write_finish</b>(). The client callback can call +<b>archive_set_error</b>() to provide values that can then +be retrieved by <b>archive_errno</b>() and +<b>archive_error_string</b>().</p> + +<p style="margin-top: 1em" valign="top"><b>SEE ALSO</b></p> + +<p style="margin-left:8%;">tar(1), libarchive(3), +tar(5)</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 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 +⟨kientzle@acm.org⟩.</p> + +<p style="margin-top: 1em" valign="top"><b>BUGS</b></p> + +<p style="margin-left:8%;">There are many peculiar bugs in +historic tar implementations that may cause certain programs +to reject archives written by this library. For example, +several historic implementations calculated header checksums +incorrectly and will thus reject valid archives; GNU tar +does not fully support pax interchange format; some old tar +implementations required specific field terminations.</p> + +<p style="margin-left:8%; margin-top: 1em">The default pax +interchange format eliminates most of the historic tar +limitations and provides a generic key/value attribute +facility for vendor-defined extensions. One oversight in +POSIX is the failure to provide a standard attribute for +large device numbers. This library uses +‘‘SCHILY.devminor’’ and +‘‘SCHILY.devmajor’’ for device +numbers that exceed the range supported by the +backwards-compatible ustar header. These keys are compatible +with Joerg Schilling’s <b>star</b> archiver. Other +implementations may not recognize these keys and will thus +be unable to correctly restore device nodes with large +device numbers from archives created by this library.</p> + + +<p style="margin-left:8%; margin-top: 1em">FreeBSD 9.0 +May 11, 2008 FreeBSD 9.0</p> +<hr> +</body> +</html> |