1 .\" Copyright (c) 2011 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
28 .Dt LIBARCHIVE_CHANGES 3
31 .Nm changes in libarchive interface
33 .Sh CHANGES IN LIBARCHIVE 3
34 This page describes user-visible changes in libarchive3, and lists
35 public functions and other symbols changed, deprecated or removed
36 in libarchive3, along with their replacements if any.
41 Libarchive2 permitted a single (input or output) filter active
43 Libarchive3 extends this into a variable-length stack.
45 .Fn archive_write_set_compression_XXX
46 would replace any existing filter,
47 .Fn archive_write_add_filter_XXX
48 extends the write pipeline with another filter.
50 .Ss Character Set Handling
52 Libarchive2 assumed that the local platform uses
56 encoding, which is true on
60 and a few other systems, but is certainly not universal.
61 As a result, pax format archives were written incorrectly on some
62 systems, since pax format requires
64 and libarchive 2 incorrectly
67 strings can be easily converted to
70 Libarchive3 uses the standard iconv library to convert between character
71 sets and is introducing the notion of a
72 .Dq default character set for the archive .
75 objects can now be bound to a particular archive when they are created.
76 The automatic character set conversions performed by
78 objects when reading and writing filenames, usernames, and other strings
79 will now use an appropriate default character set:
83 object is bound to an archive, it will use the
84 default character set for that archive.
86 The platform default character encoding (as returned by
87 .Fn nl_langinfo CHARSET )
88 will be used if nothing else is specified.
90 Libarchive3 also introduces charset options to many of the archive
91 readers and writers to control the character set that will be used for
92 filenames written in those archives.
93 When possible, this will be set automatically based on information in
95 Combining this with the notion of a default character set for the
96 archive should allow you to configure libarchive to read archives from
97 other platforms and have the filenames and other information
98 transparently converted to the character encoding suitable for your
101 .Ss Prototype Changes
103 These changes break binary compatibility; libarchive3 has a new shared
104 library version to reflect these changes.
105 The library now uses portable wide types such as
107 instead of less-portable types such as
114 There are a few cases where these changes will affect your source code:
115 .Bl -bullet -width ind
117 In some cases, libarchive's wider types will introduce the possibility
118 of truncation: for example, on a system with a 16-bit
119 .Tn uid_t , you risk having uid
123 which can cause serious security problems.
125 Typedef function pointer types will be incompatible.
126 For example, if you define custom skip callbacks, you may have to use
127 code similar to the following if you want to support building against
128 libarchive2 and libarchive3:
130 #if ARCHIVE_VERSION_NUMBER < 3000000
131 typedef off_t myoff_t;
133 typedef int64_t myoff_t;
137 my_skip_function(struct archive *a, void *v, myoff_t o)
139 ... implementation ...
149 .Fn archive_entry_gid ,
150 .Fn archive_entry_set_gid
154 .Fn archive_entry_uid ,
155 .Fn archive_entry_set_uid
159 .Fn archive_entry_ino ,
160 .Fn archive_entry_set_ino
164 .Fn archive_read_data_block ,
165 .Fn archive_write_data_block
169 .Fn archive_read_disk_gname ,
170 .Fn archive_read_disk_uname
174 .Fn archive_read_disk_set_gname_lookup ,
175 .Fn archive_read_disk_set_group_lookup ,
176 .Fn archive_read_disk_set_uname_lookup ,
177 .Fn archive_read_disk_set_user_lookup
180 .Fn archive_skip_callback
183 .Fn archive_read_extract_set_skip_file ,
184 .Fn archive_write_disk_set_skip_file ,
185 .Fn archive_write_set_skip_file
189 .Fn archive_write_disk_set_group_lookup ,
190 .Fn archive_write_disk_set_user_lookup
194 Where these functions or their arguments took or returned
200 they now take or return
204 .Ss Deprecated Symbols
206 Symbols deprecated in libarchive3 will be removed in libarchive4.
207 These symbols, along with their replacements if any, are listed below:
210 .It Fn archive_position_compressed , Fn archive_position_uncompressed
211 .Fn archive_filter_bytes
212 .It Fn archive_compression
213 .Fn archive_filter_code
214 .It Fn archive_compression_name
215 .Fn archive_filter_name
216 .It Fn archive_read_finish , Fn archive_write_finish
217 .Fn archive_read_free ,
218 .Fn archive_write_free
219 .It Fn archive_read_open_file , Fn archive_write_open_file
220 .Fn archive_read_open_filename ,
221 .Fn archive_write_open_filename
222 .It Fn archive_read_support_compression_all
223 .\" archive_read_support_compression_* -> archive_read_support_filter_*
224 .Fn archive_read_support_filter_all
225 .It Fn archive_read_support_compression_bzip2
226 .Fn archive_read_support_filter_bzip2
227 .It Fn archive_read_support_compression_compress
228 .Fn archive_read_support_filter_compress
229 .It Fn archive_read_support_compression_gzip
230 .Fn archive_read_support_filter_gzip
231 .It Fn archive_read_support_compression_lzip
232 .Fn archive_read_support_filter_lzip
233 .It Fn archive_read_support_compression_lzma
234 .Fn archive_read_support_filter_lzma
235 .It Fn archive_read_support_compression_none
236 .Fn archive_read_support_filter_none
237 .It Fn archive_read_support_compression_program
238 .Fn archive_read_support_filter_program
239 .It Fn archive_read_support_compression_program_signature
240 .Fn archive_read_support_filter_program_signature
241 .It Fn archive_read_support_compression_rpm
242 .Fn archive_read_support_filter_rpm
243 .It Fn archive_read_support_compression_uu
244 .Fn archive_read_support_filter_uu
245 .It Fn archive_read_support_compression_xz
246 .Fn archive_read_support_filter_xz
247 .\" archive_write_set_compression_* -> archive_write_add_filter_*
248 .It Fn archive_write_set_compression_bzip2
249 .Fn archive_write_add_filter_bzip2
250 .It Fn archive_write_set_compression_compress
251 .Fn archive_write_add_filter_compress
252 .It Fn archive_write_set_compression_gzip
253 .Fn archive_write_add_filter_gzip
254 .It Fn archive_write_set_compression_lzip
255 .Fn archive_write_add_filter_lzip
256 .It Fn archive_write_set_compression_lzma
257 .Fn archive_write_add_filter_lzma
258 .It Fn archive_write_set_compression_none
259 .Fn archive_write_add_filter_none
260 .It Fn archive_write_set_compression_program
261 .Fn archive_write_add_filter_program
262 .It Fn archive_write_set_compression_filter
263 .Fn archive_write_add_filter_filter
268 These symbols, listed below along with their replacements if any,
269 were deprecated in libarchive2, and are not part of libarchive3.
272 .It Fn archive_api_feature
273 .Fn archive_version_number
274 .It Fn archive_api_version
275 .Fn archive_version_number
276 .It Fn archive_version
277 .Fn archive_version_string
278 .It Fn archive_version_stamp
279 .Fn archive_version_number
280 .It Fn archive_read_set_filter_options
281 .Fn archive_read_set_options
283 .Fn archive_read_set_filter_option
284 .It Fn archive_read_set_format_options
285 .Fn archive_read_set_options
287 .Fn archive_read_set_format_option
288 .It Fn archive_write_set_filter_options
289 .Fn archive_write_set_options
291 .Fn archive_write_set_filter_option
292 .It Fn archive_write_set_format_options
293 .Fn archive_write_set_options
295 .Fn archive_write_set_format_option
296 .It Dv ARCHIVE_API_FEATURE
297 .Dv ARCHIVE_VERSION_NUMBER
298 .It Dv ARCHIVE_API_VERSION
299 .Dv ARCHIVE_VERSION_NUMBER
300 .It Dv ARCHIVE_VERSION_STAMP
301 .Dv ARCHIVE_VERSION_NUMBER
302 .It Dv ARCHIVE_LIBRARY_VERSION
303 .Dv ARCHIVE_VERSION_STRING
305 .It Dv ARCHIVE_COMPRESSION_NONE
306 .Dv ARCHIVE_FILTER_NONE
307 .It Dv ARCHIVE_COMPRESSION_GZIP
308 .Dv ARCHIVE_FILTER_GZIP
309 .It Dv ARCHIVE_COMPRESSION_BZIP2
310 .Dv ARCHIVE_FILTER_BZIP2
311 .It Dv ARCHIVE_COMPRESSION_COMPRESS
312 .Dv ARCHIVE_FILTER_COMPRESS
313 .It Dv ARCHIVE_COMPRESSION_PROGRAM
314 .Dv ARCHIVE_FILTER_PROGRAM
315 .It Dv ARCHIVE_COMPRESSION_LZMA
316 .Dv ARCHIVE_FILTER_LZMA
317 .It Dv ARCHIVE_COMPRESSION_XZ
318 .Dv ARCHIVE_FILTER_XZ
319 .It Dv ARCHIVE_COMPRESSION_UU
320 .Dv ARCHIVE_FILTER_UU
321 .It Dv ARCHIVE_COMPRESSION_RPM
322 .Dv ARCHIVE_FILTER_RPM
323 .It Dv ARCHIVE_COMPRESSION_LZIP
324 .Dv ARCHIVE_FILTER_LZIP
326 .It Dv ARCHIVE_BYTES_PER_RECORD
328 .It Dv ARCHIVE_DEFAULT_BYTES_PER_BLOCK
334 .Xr archive_read_filter 3 ,
335 .Xr archive_read_format 3 ,
336 .Xr archive_read_set_options 3 ,
337 .Xr archive_write 3 ,
338 .Xr archive_write_filter 3 ,
339 .Xr archive_write_format 3 ,
340 .Xr archive_write_set_options 3 ,