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
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
47 Streaming Archive Library (libarchive, -larchive)
51 .Fn archive_clear_error "struct archive *"
53 .Fn archive_compression "struct archive *"
55 .Fn archive_compression_name "struct archive *"
57 .Fn archive_copy_error "struct archive *" "struct archive *"
59 .Fn archive_errno "struct archive *"
61 .Fn archive_error_string "struct archive *"
63 .Fn archive_file_count "struct archive *"
65 .Fn archive_filter_code "struct archive *" "int"
67 .Fn archive_filter_count "struct archive *" "int"
69 .Fn archive_filter_name "struct archive *" "int"
71 .Fn archive_format "struct archive *"
73 .Fn archive_format_name "struct archive *"
75 .Fn archive_position "struct archive *" "int"
78 .Fa "struct archive *"
84 These functions provide access to various information about the
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
95 .Fn archive_filter_code(a, 0) .
96 .It Fn archive_compression_name
98 .Fn archive_filter_name(a, 0) .
99 .It Fn archive_copy_error
100 Copies error information from one archive to another.
102 Returns a numeric error code (see
104 indicating the reason for the most recent error return.
105 Note that this can not be reliably used to detect whether an
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
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
121 .Xr archive_read_next_header 3 .
122 .It Fn archive_filter_code
123 Returns a numeric code identifying the indicated filter.
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
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.
139 For example, when reading a uuencoded gzipped tar archive, there
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.
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
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
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.
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.
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
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
206 Field-width specifiers and other printf features are
207 not uniformly supported and should not be used.
211 .Xr archive_write 3 ,
217 library first appeared in
223 library was written by
224 .An Tim Kientzle Aq kientzle@acm.org .