doc/html/archive_util.3.html

   1 <!-- Creator     : groff version 1.22.3 -->
   2 <!-- CreationDate: Fri Apr 29 22:04:22 2016 -->
   3 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
   4 "http://www.w3.org/TR/html4/loose.dtd">
   5 <html>
   6 <head>
   7 <meta name="generator" content="groff -Thtml, see www.gnu.org">
   8 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   9 <meta name="Content-Style" content="text/css">
  10 <style type="text/css">
  11        p       { margin-top: 0; margin-bottom: 0; vertical-align: top }
  12        pre     { margin-top: 0; margin-bottom: 0; vertical-align: top }
  13        table   { margin-top: 0; margin-bottom: 0; vertical-align: top }
  14        h1      { text-align: center }
  15 </style>
  16 <title></title>
  17 </head>
  18 <body>
  19
  20 <hr>
  21
  22
  23 <p>ARCHIVE_UTIL(3) BSD Library Functions Manual
  24 ARCHIVE_UTIL(3)</p>
  25
  26 <p style="margin-top: 1em"><b>NAME</b></p>
  27
  28 <p style="margin-left:6%;"><b>archive_clear_error</b>,
  29 <b>archive_compression</b>, <b>archive_compression_name</b>,
  30 <b>archive_copy_error</b>, <b>archive_errno</b>,
  31 <b>archive_error_string</b>, <b>archive_file_count</b>,
  32 <b>archive_filter_code</b>, <b>archive_filter_count</b>,
  33 <b>archive_filter_name</b>, <b>archive_format</b>,
  34 <b>archive_format_name</b>, <b>archive_position</b>,
  35 <b>archive_set_error</b> &mdash; libarchive utility
  36 functions</p>
  37
  38 <p style="margin-top: 1em"><b>LIBRARY</b></p>
  39
  40 <p style="margin-left:6%;">Streaming Archive Library
  41 (libarchive, -larchive)</p>
  42
  43 <p style="margin-top: 1em"><b>SYNOPSIS</b></p>
  44
  45 <p style="margin-left:6%;"><b>#include
  46 &lt;archive.h&gt;</b></p>
  47
  48 <p style="margin-left:6%; margin-top: 1em"><i>void</i></p>
  49
  50
  51 <p style="margin-left:12%;"><b>archive_clear_error</b>(<i>struct&nbsp;archive&nbsp;*</i>);</p>
  52
  53 <p style="margin-left:6%; margin-top: 1em"><i>int</i></p>
  54
  55
  56 <p style="margin-left:12%;"><b>archive_compression</b>(<i>struct&nbsp;archive&nbsp;*</i>);</p>
  57
  58 <p style="margin-left:6%; margin-top: 1em"><i>const char
  59 *</i></p>
  60
  61
  62 <p style="margin-left:12%;"><b>archive_compression_name</b>(<i>struct&nbsp;archive&nbsp;*</i>);</p>
  63
  64 <p style="margin-left:6%; margin-top: 1em"><i>void</i></p>
  65
  66
  67 <p style="margin-left:12%;"><b>archive_copy_error</b>(<i>struct&nbsp;archive&nbsp;*</i>,
  68 <i>struct&nbsp;archive&nbsp;*</i>);</p>
  69
  70 <p style="margin-left:6%; margin-top: 1em"><i>int</i></p>
  71
  72
  73 <p style="margin-left:12%;"><b>archive_errno</b>(<i>struct&nbsp;archive&nbsp;*</i>);</p>
  74
  75 <p style="margin-left:6%; margin-top: 1em"><i>const char
  76 *</i></p>
  77
  78
  79 <p style="margin-left:12%;"><b>archive_error_string</b>(<i>struct&nbsp;archive&nbsp;*</i>);</p>
  80
  81 <p style="margin-left:6%; margin-top: 1em"><i>int</i></p>
  82
  83
  84 <p style="margin-left:12%;"><b>archive_file_count</b>(<i>struct&nbsp;archive&nbsp;*</i>);</p>
  85
  86 <p style="margin-left:6%; margin-top: 1em"><i>int</i></p>
  87
  88
  89 <p style="margin-left:12%;"><b>archive_filter_code</b>(<i>struct&nbsp;archive&nbsp;*</i>,
  90 <i>int</i>);</p>
  91
  92 <p style="margin-left:6%; margin-top: 1em"><i>int</i></p>
  93
  94
  95 <p style="margin-left:12%;"><b>archive_filter_count</b>(<i>struct&nbsp;archive&nbsp;*</i>,
  96 <i>int</i>);</p>
  97
  98 <p style="margin-left:6%; margin-top: 1em"><i>const char
  99 *</i></p>
 100
 101
 102 <p style="margin-left:12%;"><b>archive_filter_name</b>(<i>struct&nbsp;archive&nbsp;*</i>,
 103 <i>int</i>);</p>
 104
 105 <p style="margin-left:6%; margin-top: 1em"><i>int</i></p>
 106
 107
 108 <p style="margin-left:12%;"><b>archive_format</b>(<i>struct&nbsp;archive&nbsp;*</i>);</p>
 109
 110 <p style="margin-left:6%; margin-top: 1em"><i>const char
 111 *</i></p>
 112
 113
 114 <p style="margin-left:12%;"><b>archive_format_name</b>(<i>struct&nbsp;archive&nbsp;*</i>);</p>
 115
 116
 117 <p style="margin-left:6%; margin-top: 1em"><i>int64_t</i></p>
 118
 119
 120 <p style="margin-left:12%;"><b>archive_position</b>(<i>struct&nbsp;archive&nbsp;*</i>,
 121 <i>int</i>);</p>
 122
 123 <p style="margin-left:6%; margin-top: 1em"><i>void</i></p>
 124
 125
 126 <p><b>archive_set_error</b>(<i>struct&nbsp;archive&nbsp;*</i>,
 127 <i>int&nbsp;error_code</i>,
 128 <i>const&nbsp;char&nbsp;*fmt</i>, <i>...</i>);</p>
 129
 130 <p style="margin-top: 1em"><b>DESCRIPTION</b></p>
 131
 132 <p style="margin-left:6%;">These functions provide access
 133 to various information about the struct archive object used
 134 in the libarchive(3) library.</p>
 135
 136 <p><b>archive_clear_error</b>()</p>
 137
 138 <p style="margin-left:17%;">Clears any error information
 139 left over from a previous call. Not generally used in client
 140 code.</p>
 141
 142 <p><b>archive_compression</b>()</p>
 143
 144 <p style="margin-left:17%;">Synonym for
 145 <b>archive_filter_code(a,</b>(<i>0)</i>).</p>
 146
 147 <p><b>archive_compression_name</b>()</p>
 148
 149 <p style="margin-left:17%;">Synonym for
 150 <b>archive_filter_name(a,</b>(<i>0)</i>).</p>
 151
 152 <p><b>archive_copy_error</b>()</p>
 153
 154 <p style="margin-left:17%;">Copies error information from
 155 one archive to another.</p>
 156
 157 <p><b>archive_errno</b>()</p>
 158
 159 <p style="margin-left:17%;">Returns a numeric error code
 160 (see errno(2)) indicating the reason for the most recent
 161 error return. Note that this can not be reliably used to
 162 detect whether an error has occurred. It should be used only
 163 after another libarchive function has returned an error
 164 status.</p>
 165
 166 <p><b>archive_error_string</b>()</p>
 167
 168 <p style="margin-left:17%;">Returns a textual error message
 169 suitable for display. The error message here is usually more
 170 specific than that obtained from passing the result of
 171 <b>archive_errno</b>() to strerror(3).</p>
 172
 173 <p><b>archive_file_count</b>()</p>
 174
 175 <p style="margin-left:17%;">Returns a count of the number
 176 of files processed by this archive object. The count is
 177 incremented by calls to archive_write_header(3) or
 178 archive_read_next_header(3).</p>
 179
 180 <p><b>archive_filter_code</b>()</p>
 181
 182 <p style="margin-left:17%;">Returns a numeric code
 183 identifying the indicated filter. See
 184 <b>archive_filter_count</b>() for details of the
 185 numbering.</p>
 186
 187 <p><b>archive_filter_count</b>()</p>
 188
 189 <p style="margin-left:17%;">Returns the number of filters
 190 in the current pipeline. For read archive handles, these
 191 filters are added automatically by the automatic format
 192 detection. For write archive handles, these filters are
 193 added by calls to the various
 194 <b>archive_write_add_filter_XXX</b>() functions. Filters in
 195 the resulting pipeline are numbered so that filter 0 is the
 196 filter closest to the format handler. As a convenience,
 197 functions that expect a filter number will accept -1 as a
 198 synonym for the highest-numbered filter.</p>
 199
 200 <p style="margin-left:17%; margin-top: 1em">For example,
 201 when reading a uuencoded gzipped tar archive, there are
 202 three filters: filter 0 is the gunzip filter, filter 1 is
 203 the uudecode filter, and filter 2 is the pseudo-filter that
 204 wraps the archive read functions. In this case, requesting
 205 <b>archive_position(a,</b>(<i>-1)</i>) would be a synonym
 206 for <b>archive_position(a,</b>(<i>2)</i>) which would return
 207 the number of bytes currently read from the archive, while
 208 <b>archive_position(a,</b>(<i>1)</i>) would return the
 209 number of bytes after uudecoding, and
 210 <b>archive_position(a,</b>(<i>0)</i>) would return the
 211 number of bytes after decompression.</p>
 212
 213 <p><b>archive_filter_name</b>()</p>
 214
 215 <p style="margin-left:17%;">Returns a textual name
 216 identifying the indicated filter. See
 217 <b>archive_filter_count</b>() for details of the
 218 numbering.</p>
 219
 220 <p><b>archive_format</b>()</p>
 221
 222 <p style="margin-left:17%;">Returns a numeric code
 223 indicating the format of the current archive entry. This
 224 value is set by a successful call to
 225 <b>archive_read_next_header</b>(). Note that it is common
 226 for this value to change from entry to entry. For example, a
 227 tar archive might have several entries that utilize GNU tar
 228 extensions and several entries that do not. These entries
 229 will have different format codes.</p>
 230
 231 <p><b>archive_format_name</b>()</p>
 232
 233 <p style="margin-left:17%;">A textual description of the
 234 format of the current entry.</p>
 235
 236 <p><b>archive_position</b>()</p>
 237
 238 <p style="margin-left:17%;">Returns the number of bytes
 239 read from or written to the indicated filter. In particular,
 240 <b>archive_position(a,</b>(<i>0)</i>) returns the number of
 241 bytes read or written by the format handler, while
 242 <b>archive_position(a,</b>(<i>-1)</i>) returns the number of
 243 bytes read or written to the archive. See
 244 <b>archive_filter_count</b>() for details of the numbering
 245 here.</p>
 246
 247 <p><b>archive_set_error</b>()</p>
 248
 249 <p style="margin-left:17%;">Sets the numeric error code and
 250 error description that will be returned by
 251 <b>archive_errno</b>() and <b>archive_error_string</b>().
 252 This function should be used within I/O callbacks to set
 253 system-specific error codes and error descriptions. This
 254 function accepts a printf-like format string and arguments.
 255 However, you should be careful to use only the following
 256 printf format specifiers: &rsquo;&rsquo;%c&rsquo;&rsquo;,
 257 &rsquo;&rsquo;%d&rsquo;&rsquo;,
 258 &rsquo;&rsquo;%jd&rsquo;&rsquo;,
 259 &rsquo;&rsquo;%jo&rsquo;&rsquo;,
 260 &rsquo;&rsquo;%ju&rsquo;&rsquo;,
 261 &rsquo;&rsquo;%jx&rsquo;&rsquo;,
 262 &rsquo;&rsquo;%ld&rsquo;&rsquo;,
 263 &rsquo;&rsquo;%lo&rsquo;&rsquo;,
 264 &rsquo;&rsquo;%lu&rsquo;&rsquo;,
 265 &rsquo;&rsquo;%lx&rsquo;&rsquo;,
 266 &rsquo;&rsquo;%o&rsquo;&rsquo;,
 267 &rsquo;&rsquo;%u&rsquo;&rsquo;,
 268 &rsquo;&rsquo;%s&rsquo;&rsquo;,
 269 &rsquo;&rsquo;%x&rsquo;&rsquo;,
 270 &rsquo;&rsquo;%%&rsquo;&rsquo;. Field-width specifiers and
 271 other printf features are not uniformly supported and should
 272 not be used.</p>
 273
 274 <p style="margin-top: 1em"><b>SEE ALSO</b></p>
 275
 276 <p style="margin-left:6%;">archive_read(3),
 277 archive_write(3), libarchive(3), printf(3)</p>
 278
 279 <p style="margin-top: 1em"><b>HISTORY</b></p>
 280
 281 <p style="margin-left:6%;">The <b>libarchive</b> library
 282 first appeared in FreeBSD&nbsp;5.3.</p>
 283
 284 <p style="margin-top: 1em"><b>AUTHORS</b></p>
 285
 286 <p style="margin-left:6%;">The <b>libarchive</b> library
 287 was written by Tim Kientzle &lt;kientzle@acm.org&gt;.</p>
 288
 289 <p style="margin-left:6%; margin-top: 1em">BSD
 290 February&nbsp;2, 2012 BSD</p>
 291 <hr>
 292 </body>
 293 </html>