contrib/libarchive/libarchive/archive_util.3

   1 .\" Copyright (c) 2003-2007 Tim Kientzle
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD: head/lib/libarchive/archive_util.3 201098 2009-12-28 02:58:14Z kientzle $
  26 .\"
  27 .Dd January 8, 2005
  28 .Dt ARCHIVE_UTIL 3
  29 .Os
  30 .Sh NAME
  31 .Nm archive_clear_error ,
  32 .Nm archive_compression ,
  33 .Nm archive_compression_name ,
  34 .Nm archive_copy_error ,
  35 .Nm archive_errno ,
  36 .Nm archive_error_string ,
  37 .Nm archive_file_count ,
  38 .Nm archive_filter_code ,
  39 .Nm archive_filter_count ,
  40 .Nm archive_filter_name ,
  41 .Nm archive_format ,
  42 .Nm archive_format_name ,
  43 .Nm archive_position ,
  44 .Nm archive_set_error
  45 .Nd libarchive utility functions
  46 .Sh SYNOPSIS
  47 .In archive.h
  48 .Ft void
  49 .Fn archive_clear_error "struct archive *"
  50 .Ft int
  51 .Fn archive_compression "struct archive *"
  52 .Ft const char *
  53 .Fn archive_compression_name "struct archive *"
  54 .Ft void
  55 .Fn archive_copy_error "struct archive *" "struct archive *"
  56 .Ft int
  57 .Fn archive_errno "struct archive *"
  58 .Ft const char *
  59 .Fn archive_error_string "struct archive *"
  60 .Ft int
  61 .Fn archive_file_count "struct archive *"
  62 .Ft int
  63 .Fn archive_filter_code "struct archive *" "int"
  64 .Ft int
  65 .Fn archive_filter_count "struct archive *" "int"
  66 .Ft const char *
  67 .Fn archive_filter_name "struct archive *" "int"
  68 .Ft int
  69 .Fn archive_format "struct archive *"
  70 .Ft const char *
  71 .Fn archive_format_name "struct archive *"
  72 .Ft int64_t
  73 .Fn archive_position "struct archive *" "int"
  74 .Ft void
  75 .Fo archive_set_error
  76 .Fa "struct archive *"
  77 .Fa "int error_code"
  78 .Fa "const char *fmt"
  79 .Fa "..."
  80 .Fc
  81 .Sh DESCRIPTION
  82 These functions provide access to various information about the
  83 .Tn struct archive
  84 object used in the
  85 .Xr libarchive 3
  86 library.
  87 .Bl -tag -compact -width indent
  88 .It Fn archive_clear_error
  89 Clears any error information left over from a previous call.
  90 Not generally used in client code.
  91 .It Fn archive_compression
  92 Synonym for
  93 .Fn archive_filter_code(a, 0) .
  94 .It Fn archive_compression_name
  95 Synonym for
  96 .Fn archive_filter_name(a, 0) .
  97 .It Fn archive_copy_error
  98 Copies error information from one archive to another.
  99 .It Fn archive_errno
 100 Returns a numeric error code (see
 101 .Xr errno 2 )
 102 indicating the reason for the most recent error return.
 103 Note that this can not be reliably used to detect whether an
 104 error has occurred.
 105 It should be used only after another libarchive function
 106 has returned an error status.
 107 .It Fn archive_error_string
 108 Returns a textual error message suitable for display.
 109 The error message here is usually more specific than that
 110 obtained from passing the result of
 111 .Fn archive_errno
 112 to
 113 .Xr strerror 3 .
 114 .It Fn archive_file_count
 115 Returns a count of the number of files processed by this archive object.
 116 The count is incremented by calls to
 117 .Xr archive_write_header 3
 118 or
 119 .Xr archive_read_next_header 3 .
 120 .It Fn archive_filter_code
 121 Returns a numeric code identifying the indicated filter.
 122 See
 123 .Fn archive_filter_count
 124 for details of the numbering.
 125 .It Fn archive_filter_count
 126 Returns the number of filters in the current pipeline.
 127 For read archive handles, these filters are added automatically
 128 by the automatic format detection.
 129 For write archive handles, these filters are added by calls to the various
 130 .Fn archive_write_add_filter_XXX
 131 functions.
 132 Filters in the resulting pipeline are numbered so that filter 0
 133 is the filter closest to the format handler.
 134 As a convenience, functions that expect a filter number will
 135 accept -1 as a synonym for the highest-numbered filter.
 136 .Pp
 137 For example, when reading a uuencoded gzipped tar archive, there
 138 are three filters:
 139 filter 0 is the gunzip filter,
 140 filter 1 is the uudecode filter,
 141 and filter 2 is the pseudo-filter that wraps the archive read functions.
 142 In this case, requesting
 143 .Fn archive_position(a, -1)
 144 would be a synonym for
 145 .Fn archive_position(a, 2)
 146 which would return the number of bytes currently read from the archive, while
 147 .Fn archive_position(a, 1)
 148 would return the number of bytes after uudecoding, and
 149 .Fn archive_position(a, 0)
 150 would return the number of bytes after decompression.
 151 .It Fn archive_filter_name
 152 Returns a textual name identifying the indicated filter.
 153 See
 154 .Fn archive_filter_count
 155 for details of the numbering.
 156 .It Fn archive_format
 157 Returns a numeric code indicating the format of the current
 158 archive entry.
 159 This value is set by a successful call to
 160 .Fn archive_read_next_header .
 161 Note that it is common for this value to change from
 162 entry to entry.
 163 For example, a tar archive might have several entries that
 164 utilize GNU tar extensions and several entries that do not.
 165 These entries will have different format codes.
 166 .It Fn archive_format_name
 167 A textual description of the format of the current entry.
 168 .It Fn archive_position
 169 Returns the number of bytes read from or written to the indicated filter.
 170 In particular,
 171 .Fn archive_position(a, 0)
 172 returns the number of bytes read or written by the format handler, while
 173 .Fn archive_position(a, -1)
 174 returns the number of bytes read or written to the archive.
 175 See
 176 .Fn archive_filter_count
 177 for details of the numbering here.
 178 .It Fn archive_set_error
 179 Sets the numeric error code and error description that will be returned
 180 by
 181 .Fn archive_errno
 182 and
 183 .Fn archive_error_string .
 184 This function should be used within I/O callbacks to set system-specific
 185 error codes and error descriptions.
 186 This function accepts a printf-like format string and arguments.
 187 However, you should be careful to use only the following printf
 188 format specifiers:
 189 .Dq %c ,
 190 .Dq %d ,
 191 .Dq %jd ,
 192 .Dq %jo ,
 193 .Dq %ju ,
 194 .Dq %jx ,
 195 .Dq %ld ,
 196 .Dq %lo ,
 197 .Dq %lu ,
 198 .Dq %lx ,
 199 .Dq %o ,
 200 .Dq %u ,
 201 .Dq %s ,
 202 .Dq %x ,
 203 .Dq %% .
 204 Field-width specifiers and other printf features are
 205 not uniformly supported and should not be used.
 206 .El
 207 .Sh SEE ALSO
 208 .Xr archive_read 3 ,
 209 .Xr archive_write 3 ,
 210 .Xr libarchive 3 ,
 211 .Xr printf 3
 212 .Sh HISTORY
 213 The
 214 .Nm libarchive
 215 library first appeared in
 216 .Fx 5.3 .
 217 .Sh AUTHORS
 218 .An -nosplit
 219 The
 220 .Nm libarchive
 221 library was written by
 222 .An Tim Kientzle Aq kientzle@acm.org .