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$
  26 .\"
  27 .Dd February 2, 2012
  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 LIBRARY
  47 Streaming Archive Library (libarchive, -larchive)
  48 .Sh SYNOPSIS
  49 .In archive.h
  50 .Ft void
  51 .Fn archive_clear_error "struct archive *"
  52 .Ft int
  53 .Fn archive_compression "struct archive *"
  54 .Ft const char *
  55 .Fn archive_compression_name "struct archive *"
  56 .Ft void
  57 .Fn archive_copy_error "struct archive *" "struct archive *"
  58 .Ft int
  59 .Fn archive_errno "struct archive *"
  60 .Ft const char *
  61 .Fn archive_error_string "struct archive *"
  62 .Ft int
  63 .Fn archive_file_count "struct archive *"
  64 .Ft int
  65 .Fn archive_filter_code "struct archive *" "int"
  66 .Ft int
  67 .Fn archive_filter_count "struct archive *" "int"
  68 .Ft const char *
  69 .Fn archive_filter_name "struct archive *" "int"
  70 .Ft int
  71 .Fn archive_format "struct archive *"
  72 .Ft const char *
  73 .Fn archive_format_name "struct archive *"
  74 .Ft int64_t
  75 .Fn archive_position "struct archive *" "int"
  76 .Ft void
  77 .Fo archive_set_error
  78 .Fa "struct archive *"
  79 .Fa "int error_code"
  80 .Fa "const char *fmt"
  81 .Fa "..."
  82 .Fc
  83 .Sh DESCRIPTION
  84 These functions provide access to various information about the
  85 .Tn struct archive
  86 object used in the
  87 .Xr libarchive 3
  88 library.
  89 .Bl -tag -compact -width indent
  90 .It Fn archive_clear_error
  91 Clears any error information left over from a previous call.
  92 Not generally used in client code.
  93 .It Fn archive_compression
  94 Synonym for
  95 .Fn archive_filter_code a 0 .
  96 .It Fn archive_compression_name
  97 Synonym for
  98 .Fn archive_filter_name a 0 .
  99 .It Fn archive_copy_error
 100 Copies error information from one archive to another.
 101 .It Fn archive_errno
 102 Returns a numeric error code (see
 103 .Xr errno 2 )
 104 indicating the reason for the most recent error return.
 105 Note that this can not be reliably used to detect whether an
 106 error has occurred.
 107 It should be used only after another libarchive function
 108 has returned an error status.
 109 .It Fn archive_error_string
 110 Returns a textual error message suitable for display.
 111 The error message here is usually more specific than that
 112 obtained from passing the result of
 113 .Fn archive_errno
 114 to
 115 .Xr strerror 3 .
 116 .It Fn archive_file_count
 117 Returns a count of the number of files processed by this archive object.
 118 The count is incremented by calls to
 119 .Xr archive_write_header 3
 120 or
 121 .Xr archive_read_next_header 3 .
 122 .It Fn archive_filter_code
 123 Returns a numeric code identifying the indicated filter.
 124 See
 125 .Fn archive_filter_count
 126 for details of the numbering.
 127 .It Fn archive_filter_count
 128 Returns the number of filters in the current pipeline.
 129 For read archive handles, these filters are added automatically
 130 by the automatic format detection.
 131 For write archive handles, these filters are added by calls to the various
 132 .Fn archive_write_add_filter_XXX
 133 functions.
 134 Filters in the resulting pipeline are numbered so that filter 0
 135 is the filter closest to the format handler.
 136 As a convenience, functions that expect a filter number will
 137 accept -1 as a synonym for the highest-numbered filter.
 138 .Pp
 139 For example, when reading a uuencoded gzipped tar archive, there
 140 are three filters:
 141 filter 0 is the gunzip filter,
 142 filter 1 is the uudecode filter,
 143 and filter 2 is the pseudo-filter that wraps the archive read functions.
 144 In this case, requesting
 145 .Fn archive_position a -1
 146 would be a synonym for
 147 .Fn archive_position a 2
 148 which would return the number of bytes currently read from the archive, while
 149 .Fn archive_position a 1
 150 would return the number of bytes after uudecoding, and
 151 .Fn archive_position a 0
 152 would return the number of bytes after decompression.
 153 .It Fn archive_filter_name
 154 Returns a textual name identifying the indicated filter.
 155 See
 156 .Fn archive_filter_count
 157 for details of the numbering.
 158 .It Fn archive_format
 159 Returns a numeric code indicating the format of the current
 160 archive entry.
 161 This value is set by a successful call to
 162 .Fn archive_read_next_header .
 163 Note that it is common for this value to change from
 164 entry to entry.
 165 For example, a tar archive might have several entries that
 166 utilize GNU tar extensions and several entries that do not.
 167 These entries will have different format codes.
 168 .It Fn archive_format_name
 169 A textual description of the format of the current entry.
 170 .It Fn archive_position
 171 Returns the number of bytes read from or written to the indicated filter.
 172 In particular,
 173 .Fn archive_position a 0
 174 returns the number of bytes read or written by the format handler, while
 175 .Fn archive_position a -1
 176 returns the number of bytes read or written to the archive.
 177 See
 178 .Fn archive_filter_count
 179 for details of the numbering here.
 180 .It Fn archive_set_error
 181 Sets the numeric error code and error description that will be returned
 182 by
 183 .Fn archive_errno
 184 and
 185 .Fn archive_error_string .
 186 This function should be used within I/O callbacks to set system-specific
 187 error codes and error descriptions.
 188 This function accepts a printf-like format string and arguments.
 189 However, you should be careful to use only the following printf
 190 format specifiers:
 191 .Dq %c ,
 192 .Dq %d ,
 193 .Dq %jd ,
 194 .Dq %jo ,
 195 .Dq %ju ,
 196 .Dq %jx ,
 197 .Dq %ld ,
 198 .Dq %lo ,
 199 .Dq %lu ,
 200 .Dq %lx ,
 201 .Dq %o ,
 202 .Dq %u ,
 203 .Dq %s ,
 204 .Dq %x ,
 205 .Dq %% .
 206 Field-width specifiers and other printf features are
 207 not uniformly supported and should not be used.
 208 .El
 209 .Sh SEE ALSO
 210 .Xr archive_read 3 ,
 211 .Xr archive_write 3 ,
 212 .Xr libarchive 3 ,
 213 .Xr printf 3
 214 .Sh HISTORY
 215 The
 216 .Nm libarchive
 217 library first appeared in
 218 .Fx 5.3 .
 219 .Sh AUTHORS
 220 .An -nosplit
 221 The
 222 .Nm libarchive
 223 library was written by
 224 .An Tim Kientzle Aq kientzle@acm.org .