1 .\" Copyright (c) 2003-2007 Tim Kientzle
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
25 .\" $FreeBSD: head/lib/libarchive/archive_util.3 201098 2009-12-28 02:58:14Z kientzle $
31 .Nm archive_clear_error ,
32 .Nm archive_compression ,
33 .Nm archive_compression_name ,
34 .Nm archive_copy_error ,
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 ,
42 .Nm archive_format_name ,
43 .Nm archive_position ,
45 .Nd libarchive utility functions
49 .Fn archive_clear_error "struct archive *"
51 .Fn archive_compression "struct archive *"
53 .Fn archive_compression_name "struct archive *"
55 .Fn archive_copy_error "struct archive *" "struct archive *"
57 .Fn archive_errno "struct archive *"
59 .Fn archive_error_string "struct archive *"
61 .Fn archive_file_count "struct archive *"
63 .Fn archive_filter_code "struct archive *" "int"
65 .Fn archive_filter_count "struct archive *" "int"
67 .Fn archive_filter_name "struct archive *" "int"
69 .Fn archive_format "struct archive *"
71 .Fn archive_format_name "struct archive *"
73 .Fn archive_position "struct archive *" "int"
76 .Fa "struct archive *"
82 These functions provide access to various information about the
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
93 .Fn archive_filter_code(a, 0) .
94 .It Fn archive_compression_name
96 .Fn archive_filter_name(a, 0) .
97 .It Fn archive_copy_error
98 Copies error information from one archive to another.
100 Returns a numeric error code (see
102 indicating the reason for the most recent error return.
103 Note that this can not be reliably used to detect whether an
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
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
119 .Xr archive_read_next_header 3 .
120 .It Fn archive_filter_code
121 Returns a numeric code identifying the indicated filter.
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
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.
137 For example, when reading a uuencoded gzipped tar archive, there
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.
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
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
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.
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.
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
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
204 Field-width specifiers and other printf features are
205 not uniformly supported and should not be used.
209 .Xr archive_write 3 ,
215 library first appeared in
221 library was written by
222 .An Tim Kientzle Aq kientzle@acm.org .