doc/wiki/ManPageArchiveUtil3.wiki

   1 ARCHIVE_UTIL(3) manual page
   2 == NAME ==
   3 '''archive_clear_error''',
   4 '''archive_compression''',
   5 '''archive_compression_name''',
   6 '''archive_copy_error''',
   7 '''archive_errno''',
   8 '''archive_error_string''',
   9 '''archive_file_count''',
  10 '''archive_filter_code''',
  11 '''archive_filter_count''',
  12 '''archive_filter_name''',
  13 '''archive_format''',
  14 '''archive_format_name''',
  15 '''archive_position''',
  16 '''archive_set_error'''
  17 - libarchive utility functions
  18 == LIBRARY ==
  19 Streaming Archive Library (libarchive, -larchive)
  20 == SYNOPSIS ==
  21 '''<nowiki>#include <archive.h></nowiki>'''
  22 <br>
  23 ''void''
  24 <br>
  25 '''archive_clear_error'''(''struct archive *'');
  26 <br>
  27 ''int''
  28 <br>
  29 '''archive_compression'''(''struct archive *'');
  30 <br>
  31 ''const char *''
  32 <br>
  33 '''archive_compression_name'''(''struct archive *'');
  34 <br>
  35 ''void''
  36 <br>
  37 '''archive_copy_error'''(''struct archive *'', ''struct archive *'');
  38 <br>
  39 ''int''
  40 <br>
  41 '''archive_errno'''(''struct archive *'');
  42 <br>
  43 ''const char *''
  44 <br>
  45 '''archive_error_string'''(''struct archive *'');
  46 <br>
  47 ''int''
  48 <br>
  49 '''archive_file_count'''(''struct archive *'');
  50 <br>
  51 ''int''
  52 <br>
  53 '''archive_filter_code'''(''struct archive *'', ''int'');
  54 <br>
  55 ''int''
  56 <br>
  57 '''archive_filter_count'''(''struct archive *'', ''int'');
  58 <br>
  59 ''const char *''
  60 <br>
  61 '''archive_filter_name'''(''struct archive *'', ''int'');
  62 <br>
  63 ''int''
  64 <br>
  65 '''archive_format'''(''struct archive *'');
  66 <br>
  67 ''const char *''
  68 <br>
  69 '''archive_format_name'''(''struct archive *'');
  70 <br>
  71 ''int64_t''
  72 <br>
  73 '''archive_position'''(''struct archive *'', ''int'');
  74 <br>
  75 ''void''
  76 <br>
  77 '''archive_set_error'''(''struct archive *'', ''int error_code'', ''const char *fmt'', ''...'');
  78 == DESCRIPTION ==
  79 These functions provide access to various information about the
  80 '''struct archive'''
  81 object used in the
  82 [[ManPageLibarchive3]]
  83 library.
  84 <dl>
  85 <dt>'''archive_clear_error'''()</dt><dd>
  86 Clears any error information left over from a previous call.
  87 Not generally used in client code.
  88 </dd><dt>'''archive_compression'''()</dt><dd>
  89 Synonym for
  90 '''archive_filter_code(a,'''(''0)'').
  91 </dd><dt>'''archive_compression_name'''()</dt><dd>
  92 Synonym for
  93 '''archive_filter_name(a,'''(''0)'').
  94 </dd><dt>'''archive_copy_error'''()</dt><dd>
  95 Copies error information from one archive to another.
  96 </dd><dt>'''archive_errno'''()</dt><dd>
  97 Returns a numeric error code (see
  98 [[errno(2)|http://www.freebsd.org/cgi/man.cgi?query=errno&sektion=2]])
  99 indicating the reason for the most recent error return.
 100 Note that this can not be reliably used to detect whether an
 101 error has occurred.
 102 It should be used only after another libarchive function
 103 has returned an error status.
 104 </dd><dt>'''archive_error_string'''()</dt><dd>
 105 Returns a textual error message suitable for display.
 106 The error message here is usually more specific than that
 107 obtained from passing the result of
 108 '''archive_errno'''()
 109 to
 110 [[strerror(3)|http://www.freebsd.org/cgi/man.cgi?query=strerror&sektion=3]].
 111 </dd><dt>'''archive_file_count'''()</dt><dd>
 112 Returns a count of the number of files processed by this archive object.
 113 The count is incremented by calls to
 114 [[ManPageArchiveWriteHeader3]]
 115 or
 116 [[ManPageArchiveReadNextHeader3]].
 117 </dd><dt>'''archive_filter_code'''()</dt><dd>
 118 Returns a numeric code identifying the indicated filter.
 119 See
 120 '''archive_filter_count'''()
 121 for details of the numbering.
 122 </dd><dt>'''archive_filter_count'''()</dt><dd>
 123 Returns the number of filters in the current pipeline.
 124 For read archive handles, these filters are added automatically
 125 by the automatic format detection.
 126 For write archive handles, these filters are added by calls to the various
 127 '''archive_write_add_filter_XXX'''()
 128 functions.
 129 Filters in the resulting pipeline are numbered so that filter 0
 130 is the filter closest to the format handler.
 131 As a convenience, functions that expect a filter number will
 132 accept -1 as a synonym for the highest-numbered filter.
 133
 134 For example, when reading a uuencoded gzipped tar archive, there
 135 are three filters:
 136 filter 0 is the gunzip filter,
 137 filter 1 is the uudecode filter,
 138 and filter 2 is the pseudo-filter that wraps the archive read functions.
 139 In this case, requesting
 140 '''archive_position(a,'''(''-1)'')
 141 would be a synonym for
 142 '''archive_position(a,'''(''2)'')
 143 which would return the number of bytes currently read from the archive, while
 144 '''archive_position(a,'''(''1)'')
 145 would return the number of bytes after uudecoding, and
 146 '''archive_position(a,'''(''0)'')
 147 would return the number of bytes after decompression.
 148 </dd><dt>'''archive_filter_name'''()</dt><dd>
 149 Returns a textual name identifying the indicated filter.
 150 See
 151 '''archive_filter_count'''()
 152 for details of the numbering.
 153 </dd><dt>'''archive_format'''()</dt><dd>
 154 Returns a numeric code indicating the format of the current
 155 archive entry.
 156 This value is set by a successful call to
 157 '''archive_read_next_header'''().
 158 Note that it is common for this value to change from
 159 entry to entry.
 160 For example, a tar archive might have several entries that
 161 utilize GNU tar extensions and several entries that do not.
 162 These entries will have different format codes.
 163 </dd><dt>'''archive_format_name'''()</dt><dd>
 164 A textual description of the format of the current entry.
 165 </dd><dt>'''archive_position'''()</dt><dd>
 166 Returns the number of bytes read from or written to the indicated filter.
 167 In particular,
 168 '''archive_position(a,'''(''0)'')
 169 returns the number of bytes read or written by the format handler, while
 170 '''archive_position(a,'''(''-1)'')
 171 returns the number of bytes read or written to the archive.
 172 See
 173 '''archive_filter_count'''()
 174 for details of the numbering here.
 175 </dd><dt>'''archive_set_error'''()</dt><dd>
 176 Sets the numeric error code and error description that will be returned
 177 by
 178 '''archive_errno'''()
 179 and
 180 '''archive_error_string'''().
 181 This function should be used within I/O callbacks to set system-specific
 182 error codes and error descriptions.
 183 This function accepts a printf-like format string and arguments.
 184 However, you should be careful to use only the following printf
 185 format specifiers:
 186 "%c",
 187 "%d",
 188 "%jd",
 189 "%jo",
 190 "%ju",
 191 "%jx",
 192 "%ld",
 193 "%lo",
 194 "%lu",
 195 "%lx",
 196 "%o",
 197 "%u",
 198 "%s",
 199 "%x",
 200 "%%".
 201 Field-width specifiers and other printf features are
 202 not uniformly supported and should not be used.
 203 </dd></dl>
 204 == SEE ALSO ==
 205 [[ManPageArchiveRead3]],
 206 [[ManPageArchiveWrite3]],
 207 [[ManPageLibarchive3]],
 208 [[printf(3)|http://www.freebsd.org/cgi/man.cgi?query=printf&sektion=3]]
 209 == HISTORY ==
 210 The
 211 '''libarchive'''
 212 library first appeared in
 213 FreeBSD 5.3.
 214 == AUTHORS ==
 215 The
 216 '''libarchive'''
 217 library was written by
 218 Tim Kientzle  &lt;kientzle@acm.org.&gt;