1.\" Copyright (c) 2011 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 December 23, 2011 28.Dt LIBARCHIVE_CHANGES 3 29.Os 30.Sh NAME 31.Nd changes in libarchive interface 32.\" 33.Sh CHANGES IN LIBARCHIVE 3 34This page describes user-visible changes in libarchive3, and lists 35public functions and other symbols changed, deprecated or removed 36in libarchive3, along with their replacements if any. 37.Pp 38.\" 39.Ss Multiple Filters 40.\" 41Libarchive2 permitted a single (input or output) filter active 42on an archive. 43Libarchive3 extends this into a variable-length stack. 44Where 45.Fn archive_write_set_compression_XXX 46would replace any existing filter, 47.Fn archive_write_add_filter_XXX 48extends the write pipeline with another filter. 49.\" 50.Ss Character Set Handling 51.\" 52Libarchive2 assumed that the local platform uses 53.Tn Unicode 54as the native 55.Tn wchar_t 56encoding, which is true on 57.Tn Windows , 58modern 59.Tn Linux , 60and a few other systems, but is certainly not universal. 61As a result, pax format archives were written incorrectly on some 62systems, since pax format requires 63.Tn UTF-8 64and libarchive 2 incorrectly 65assumed that 66.Tn wchar_t 67strings can be easily converted to 68.Tn UTF-8 . 69.Pp 70Libarchive3 uses the standard iconv library to convert between character 71sets and is introducing the notion of a 72.Dq default character set for the archive . 73To support this, 74.Tn archive_entry 75objects can now be bound to a particular archive when they are created. 76The automatic character set conversions performed by 77.Tn archive_entry 78objects when reading and writing filenames, usernames, and other strings 79will now use an appropriate default character set: 80.Pp 81If the 82.Tn archive_entry 83object is bound to an archive, it will use the 84default character set for that archive. 85.Pp 86The platform default character encoding (as returned by 87.Fn nl_langinfo CHARSET ) 88will be used if nothing else is specified. 89.Pp 90Libarchive3 also introduces charset options to many of the archive 91readers and writers to control the character set that will be used for 92filenames written in those archives. 93When possible, this will be set automatically based on information in 94the archive itself. 95Combining this with the notion of a default character set for the 96archive should allow you to configure libarchive to read archives from 97other platforms and have the filenames and other information 98transparently converted to the character encoding suitable for your 99application. 100.\" 101.Ss Prototype Changes 102.\" 103These changes break binary compatibility; libarchive3 has a new shared 104library version to reflect these changes. 105The library now uses portable wide types such as 106.Tn int64_t 107instead of less-portable types such as 108.Tn off_t , 109.Tn gid_t , 110.Tn uid_t , 111and 112.Tn ino_t . 113.Pp 114There are a few cases where these changes will affect your source code: 115.Bl -bullet -width ind 116.It 117In some cases, libarchive's wider types will introduce the possibility 118of truncation: for example, on a system with a 16-bit 119.Tn uid_t , you risk having uid 120.Li 65536 121be truncated to uid 122.Li 0 , 123which can cause serious security problems. 124.It 125Typedef function pointer types will be incompatible. 126For example, if you define custom skip callbacks, you may have to use 127code similar to the following if you want to support building against 128libarchive2 and libarchive3: 129.Bd -literal 130#if ARCHIVE_VERSION_NUMBER < 3000000 131typedef off_t myoff_t; 132#else 133typedef int64_t myoff_t; 134#endif 135 136myoff_t 137my_skip_function(struct archive *a, void *v, myoff_t o) 138{ 139 ... implementation ... 140} 141.Ed 142.El 143.Pp 144Affected functions: 145.Pp 146.Bl -bullet -compact 147.It 148.Xo 149.Fn archive_entry_gid , 150.Fn archive_entry_set_gid 151.Xc 152.It 153.Xo 154.Fn archive_entry_uid , 155.Fn archive_entry_set_uid 156.Xc 157.It 158.Xo 159.Fn archive_entry_ino , 160.Fn archive_entry_set_ino 161.Xc 162.It 163.Xo 164.Fn archive_read_data_block , 165.Fn archive_write_data_block 166.Xc 167.It 168.Xo 169.Fn archive_read_disk_gname , 170.Fn archive_read_disk_uname 171.Xc 172.It 173.Xo 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 178.Xc 179.It 180.Fn archive_skip_callback 181.It 182.Xo 183.Fn archive_read_extract_set_skip_file , 184.Fn archive_write_disk_set_skip_file , 185.Fn archive_write_set_skip_file 186.Xc 187.It 188.Xo 189.Fn archive_write_disk_set_group_lookup , 190.Fn archive_write_disk_set_user_lookup 191.Xc 192.El 193.Pp 194Where these functions or their arguments took or returned 195.Tn gid_t , 196.Tn ino_t , 197.Tn off_t , 198or 199.Tn uid_t 200they now take or return 201.Tn int64_t 202or equivalent. 203.\" 204.Ss Deprecated Symbols 205.\" 206Symbols deprecated in libarchive3 will be removed in libarchive4. 207These symbols, along with their replacements if any, are listed below: 208.\" 209.Bl -tag -width ind 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 264.El 265.\" 266.Ss Removed Symbols 267.\" 268These symbols, listed below along with their replacements if any, 269were deprecated in libarchive2, and are not part of libarchive3. 270.\" 271.Bl -tag -width ind 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 282or 283.Fn archive_read_set_filter_option 284.It Fn archive_read_set_format_options 285.Fn archive_read_set_options 286or 287.Fn archive_read_set_format_option 288.It Fn archive_write_set_filter_options 289.Fn archive_write_set_options 290or 291.Fn archive_write_set_filter_option 292.It Fn archive_write_set_format_options 293.Fn archive_write_set_options 294or 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 304.\" 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 325.\" 326.It Dv ARCHIVE_BYTES_PER_RECORD 327.Li 512 328.It Dv ARCHIVE_DEFAULT_BYTES_PER_BLOCK 329.Li 10240 330.El 331.Sh SEE ALSO 332.Xr libarchive 3 , 333.Xr archive_read 3 , 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 , 341.Xr archive_util 3 342