doc/text/archive_util.3.txt

   1 ARCHIVE_UTIL(3)          BSD Library Functions Manual          ARCHIVE_UTIL(3)
   2
   3 NAME
   4      archive_clear_error, archive_compression, archive_compression_name,
   5      archive_copy_error, archive_errno, archive_error_string,
   6      archive_file_count, archive_filter_code, archive_filter_count,
   7      archive_filter_name, archive_format, archive_format_name,
   8      archive_position, archive_set_error -- libarchive utility functions
   9
  10 LIBRARY
  11      Streaming Archive Library (libarchive, -larchive)
  12
  13 SYNOPSIS
  14      #include <archive.h>
  15
  16      void
  17      archive_clear_error(struct archive *);
  18
  19      int
  20      archive_compression(struct archive *);
  21
  22      const char *
  23      archive_compression_name(struct archive *);
  24
  25      void
  26      archive_copy_error(struct archive *, struct archive *);
  27
  28      int
  29      archive_errno(struct archive *);
  30
  31      const char *
  32      archive_error_string(struct archive *);
  33
  34      int
  35      archive_file_count(struct archive *);
  36
  37      int
  38      archive_filter_code(struct archive *, int);
  39
  40      int
  41      archive_filter_count(struct archive *, int);
  42
  43      const char *
  44      archive_filter_name(struct archive *, int);
  45
  46      int
  47      archive_format(struct archive *);
  48
  49      const char *
  50      archive_format_name(struct archive *);
  51
  52      int64_t
  53      archive_position(struct archive *, int);
  54
  55      void
  56      archive_set_error(struct archive *, int error_code, const char *fmt,
  57          ...);
  58
  59 DESCRIPTION
  60      These functions provide access to various information about the struct
  61      archive object used in the libarchive(3) library.
  62      archive_clear_error()
  63              Clears any error information left over from a previous call.  Not
  64              generally used in client code.
  65      archive_compression()
  66              Synonym for archive_filter_code(a, 0).
  67      archive_compression_name()
  68              Synonym for archive_filter_name(a, 0).
  69      archive_copy_error()
  70              Copies error information from one archive to another.
  71      archive_errno()
  72              Returns a numeric error code (see errno(2)) indicating the reason
  73              for the most recent error return.  Note that this can not be
  74              reliably used to detect whether an error has occurred.  It should
  75              be used only after another libarchive function has returned an
  76              error status.
  77      archive_error_string()
  78              Returns a textual error message suitable for display.  The error
  79              message here is usually more specific than that obtained from
  80              passing the result of archive_errno() to strerror(3).
  81      archive_file_count()
  82              Returns a count of the number of files processed by this archive
  83              object.  The count is incremented by calls to
  84              archive_write_header(3) or archive_read_next_header(3).
  85      archive_filter_code()
  86              Returns a numeric code identifying the indicated filter.  See
  87              archive_filter_count() for details of the numbering.
  88      archive_filter_count()
  89              Returns the number of filters in the current pipeline.  For read
  90              archive handles, these filters are added automatically by the
  91              automatic format detection.  For write archive handles, these
  92              filters are added by calls to the various
  93              archive_write_add_filter_XXX() functions.  Filters in the result-
  94              ing pipeline are numbered so that filter 0 is the filter closest
  95              to the format handler.  As a convenience, functions that expect a
  96              filter number will accept -1 as a synonym for the highest-num-
  97              bered filter.
  98
  99              For example, when reading a uuencoded gzipped tar archive, there
 100              are three filters: filter 0 is the gunzip filter, filter 1 is the
 101              uudecode filter, and filter 2 is the pseudo-filter that wraps the
 102              archive read functions.  In this case, requesting
 103              archive_position(a, -1) would be a synonym for
 104              archive_position(a, 2) which would return the number of bytes
 105              currently read from the archive, while archive_position(a, 1)
 106              would return the number of bytes after uudecoding, and
 107              archive_position(a, 0) would return the number of bytes after
 108              decompression.
 109      archive_filter_name()
 110              Returns a textual name identifying the indicated filter.  See
 111              archive_filter_count() for details of the numbering.
 112      archive_format()
 113              Returns a numeric code indicating the format of the current ar-
 114              chive entry.  This value is set by a successful call to
 115              archive_read_next_header().  Note that it is common for this
 116              value to change from entry to entry.  For example, a tar archive
 117              might have several entries that utilize GNU tar extensions and
 118              several entries that do not.  These entries will have different
 119              format codes.
 120      archive_format_name()
 121              A textual description of the format of the current entry.
 122      archive_position()
 123              Returns the number of bytes read from or written to the indicated
 124              filter.  In particular, archive_position(a, 0) returns the number
 125              of bytes read or written by the format handler, while
 126              archive_position(a, -1) returns the number of bytes read or writ-
 127              ten to the archive.  See archive_filter_count() for details of
 128              the numbering here.
 129      archive_set_error()
 130              Sets the numeric error code and error description that will be
 131              returned by archive_errno() and archive_error_string().  This
 132              function should be used within I/O callbacks to set system-spe-
 133              cific error codes and error descriptions.  This function accepts
 134              a printf-like format string and arguments.  However, you should
 135              be careful to use only the following printf format specifiers:
 136              ``%c'', ``%d'', ``%jd'', ``%jo'', ``%ju'', ``%jx'', ``%ld'',
 137              ``%lo'', ``%lu'', ``%lx'', ``%o'', ``%u'', ``%s'', ``%x'',
 138              ``%%''.  Field-width specifiers and other printf features are not
 139              uniformly supported and should not be used.
 140
 141 SEE ALSO
 142      archive_read(3), archive_write(3), libarchive(3), printf(3)
 143
 144 HISTORY
 145      The libarchive library first appeared in FreeBSD 5.3.
 146
 147 AUTHORS
 148      The libarchive library was written by Tim Kientzle <kientzle@acm.org>.
 149
 150 BSD                            February 2, 2012                            BSD