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.Nm libarchive_changes 32.Nd changes in libarchive interface 33.\" 34.Sh CHANGES IN LIBARCHIVE 3 35This page describes user-visible changes in libarchive3, and lists 36public functions and other symbols changed, deprecated or removed 37in libarchive3, along with their replacements if any. 38.Pp 39.\" 40.Ss Multiple Filters 41.\" 42Libarchive2 permitted a single (input or output) filter active 43on an archive. 44Libarchive3 extends this into a variable-length stack. 45Where 46.Fn archive_write_set_compression_XXX 47would replace any existing filter, 48.Fn archive_write_add_filter_XXX 49extends the write pipeline with another filter. 50.\" 51.Ss Character Set Handling 52.\" 53Libarchive2 assumed that the local platform uses 54.Tn Unicode 55as the native 56.Tn wchar_t 57encoding, which is true on 58.Tn Windows , 59modern 60.Tn Linux , 61and a few other systems, but is certainly not universal. 62As a result, pax format archives were written incorrectly on some 63systems, since pax format requires 64.Tn UTF-8 65and libarchive 2 incorrectly 66assumed that 67.Tn wchar_t 68strings can be easily converted to 69.Tn UTF-8 . 70.Pp 71Libarchive3 uses the standard iconv library to convert between character 72sets and is introducing the notion of a 73.Dq default character set for the archive . 74To support this, 75.Tn archive_entry 76objects can now be bound to a particular archive when they are created. 77The automatic character set conversions performed by 78.Tn archive_entry 79objects when reading and writing filenames, usernames, and other strings 80will now use an appropriate default character set: 81.Pp 82If the 83.Tn archive_entry 84object is bound to an archive, it will use the 85default character set for that archive. 86.Pp 87The platform default character encoding (as returned by 88.Fn nl_langinfo CHARSET ) 89will be used if nothing else is specified. 90.Pp 91Libarchive3 also introduces charset options to many of the archive 92readers and writers to control the character set that will be used for 93filenames written in those archives. 94When possible, this will be set automatically based on information in 95the archive itself. 96Combining this with the notion of a default character set for the 97archive should allow you to configure libarchive to read archives from 98other platforms and have the filenames and other information 99transparently converted to the character encoding suitable for your 100application. 101.\" 102.Ss Prototype Changes 103.\" 104These changes break binary compatibility; libarchive3 has a new shared 105library version to reflect these changes. 106The library now uses portable wide types such as 107.Tn int64_t 108instead of less-portable types such as 109.Tn off_t , 110.Tn gid_t , 111.Tn uid_t , 112and 113.Tn ino_t . 114.Pp 115There are a few cases where these changes will affect your source code: 116.Bl -bullet -width ind 117.It 118In some cases, libarchive's wider types will introduce the possibility 119of truncation: for example, on a system with a 16-bit 120.Tn uid_t , you risk having uid 121.Li 65536 122be truncated to uid 123.Li 0 , 124which can cause serious security problems. 125.It 126Typedef function pointer types will be incompatible. 127For example, if you define custom skip callbacks, you may have to use 128code similar to the following if you want to support building against 129libarchive2 and libarchive3: 130.Bd -literal 131#if ARCHIVE_VERSION_NUMBER < 3000000 132typedef off_t myoff_t; 133#else 134typedef int64_t myoff_t; 135#endif 136 137myoff_t 138my_skip_function(struct archive *a, void *v, myoff_t o) 139{ 140 ... implementation ... 141} 142.Ed 143.El 144.Pp 145Affected functions: 146.Pp 147.Bl -bullet -compact 148.It 149.Xo 150.Fn archive_entry_gid , 151.Fn archive_entry_set_gid 152.Xc 153.It 154.Xo 155.Fn archive_entry_uid , 156.Fn archive_entry_set_uid 157.Xc 158.It 159.Xo 160.Fn archive_entry_ino , 161.Fn archive_entry_set_ino 162.Xc 163.It 164.Xo 165.Fn archive_read_data_block , 166.Fn archive_write_data_block 167.Xc 168.It 169.Xo 170.Fn archive_read_disk_gname , 171.Fn archive_read_disk_uname 172.Xc 173.It 174.Xo 175.Fn archive_read_disk_set_gname_lookup , 176.Fn archive_read_disk_set_group_lookup , 177.Fn archive_read_disk_set_uname_lookup , 178.Fn archive_read_disk_set_user_lookup 179.Xc 180.It 181.Fn archive_skip_callback 182.It 183.Xo 184.Fn archive_read_extract_set_skip_file , 185.Fn archive_write_disk_set_skip_file , 186.Fn archive_write_set_skip_file 187.Xc 188.It 189.Xo 190.Fn archive_write_disk_set_group_lookup , 191.Fn archive_write_disk_set_user_lookup 192.Xc 193.El 194.Pp 195Where these functions or their arguments took or returned 196.Tn gid_t , 197.Tn ino_t , 198.Tn off_t , 199or 200.Tn uid_t 201they now take or return 202.Tn int64_t 203or equivalent. 204.\" 205.Ss Deprecated Symbols 206.\" 207Symbols deprecated in libarchive3 will be removed in libarchive4. 208These symbols, along with their replacements if any, are listed below: 209.\" 210.Bl -tag -width ind 211.It Fn archive_position_compressed , Fn archive_position_uncompressed 212.Fn archive_filter_bytes 213.It Fn archive_compression 214.Fn archive_filter_code 215.It Fn archive_compression_name 216.Fn archive_filter_name 217.It Fn archive_read_finish , Fn archive_write_finish 218.Fn archive_read_free , 219.Fn archive_write_free 220.It Fn archive_read_open_file , Fn archive_write_open_file 221.Fn archive_read_open_filename , 222.Fn archive_write_open_filename 223.It Fn archive_read_support_compression_all 224.\" archive_read_support_compression_* -> archive_read_support_filter_* 225.Fn archive_read_support_filter_all 226.It Fn archive_read_support_compression_bzip2 227.Fn archive_read_support_filter_bzip2 228.It Fn archive_read_support_compression_compress 229.Fn archive_read_support_filter_compress 230.It Fn archive_read_support_compression_gzip 231.Fn archive_read_support_filter_gzip 232.It Fn archive_read_support_compression_lzip 233.Fn archive_read_support_filter_lzip 234.It Fn archive_read_support_compression_lzma 235.Fn archive_read_support_filter_lzma 236.It Fn archive_read_support_compression_none 237.Fn archive_read_support_filter_none 238.It Fn archive_read_support_compression_program 239.Fn archive_read_support_filter_program 240.It Fn archive_read_support_compression_program_signature 241.Fn archive_read_support_filter_program_signature 242.It Fn archive_read_support_compression_rpm 243.Fn archive_read_support_filter_rpm 244.It Fn archive_read_support_compression_uu 245.Fn archive_read_support_filter_uu 246.It Fn archive_read_support_compression_xz 247.Fn archive_read_support_filter_xz 248.\" archive_write_set_compression_* -> archive_write_add_filter_* 249.It Fn archive_write_set_compression_bzip2 250.Fn archive_write_add_filter_bzip2 251.It Fn archive_write_set_compression_compress 252.Fn archive_write_add_filter_compress 253.It Fn archive_write_set_compression_gzip 254.Fn archive_write_add_filter_gzip 255.It Fn archive_write_set_compression_lzip 256.Fn archive_write_add_filter_lzip 257.It Fn archive_write_set_compression_lzma 258.Fn archive_write_add_filter_lzma 259.It Fn archive_write_set_compression_none 260.Fn archive_write_add_filter_none 261.It Fn archive_write_set_compression_program 262.Fn archive_write_add_filter_program 263.It Fn archive_write_set_compression_filter 264.Fn archive_write_add_filter_filter 265.El 266.\" 267.Ss Removed Symbols 268.\" 269These symbols, listed below along with their replacements if any, 270were deprecated in libarchive2, and are not part of libarchive3. 271.\" 272.Bl -tag -width ind 273.It Fn archive_api_feature 274.Fn archive_version_number 275.It Fn archive_api_version 276.Fn archive_version_number 277.It Fn archive_version 278.Fn archive_version_string 279.It Fn archive_version_stamp 280.Fn archive_version_number 281.It Fn archive_read_set_filter_options 282.Fn archive_read_set_options 283or 284.Fn archive_read_set_filter_option 285.It Fn archive_read_set_format_options 286.Fn archive_read_set_options 287or 288.Fn archive_read_set_format_option 289.It Fn archive_write_set_filter_options 290.Fn archive_write_set_options 291or 292.Fn archive_write_set_filter_option 293.It Fn archive_write_set_format_options 294.Fn archive_write_set_options 295or 296.Fn archive_write_set_format_option 297.It Dv ARCHIVE_API_FEATURE 298.Dv ARCHIVE_VERSION_NUMBER 299.It Dv ARCHIVE_API_VERSION 300.Dv ARCHIVE_VERSION_NUMBER 301.It Dv ARCHIVE_VERSION_STAMP 302.Dv ARCHIVE_VERSION_NUMBER 303.It Dv ARCHIVE_LIBRARY_VERSION 304.Dv ARCHIVE_VERSION_STRING 305.\" 306.It Dv ARCHIVE_COMPRESSION_NONE 307.Dv ARCHIVE_FILTER_NONE 308.It Dv ARCHIVE_COMPRESSION_GZIP 309.Dv ARCHIVE_FILTER_GZIP 310.It Dv ARCHIVE_COMPRESSION_BZIP2 311.Dv ARCHIVE_FILTER_BZIP2 312.It Dv ARCHIVE_COMPRESSION_COMPRESS 313.Dv ARCHIVE_FILTER_COMPRESS 314.It Dv ARCHIVE_COMPRESSION_PROGRAM 315.Dv ARCHIVE_FILTER_PROGRAM 316.It Dv ARCHIVE_COMPRESSION_LZMA 317.Dv ARCHIVE_FILTER_LZMA 318.It Dv ARCHIVE_COMPRESSION_XZ 319.Dv ARCHIVE_FILTER_XZ 320.It Dv ARCHIVE_COMPRESSION_UU 321.Dv ARCHIVE_FILTER_UU 322.It Dv ARCHIVE_COMPRESSION_RPM 323.Dv ARCHIVE_FILTER_RPM 324.It Dv ARCHIVE_COMPRESSION_LZIP 325.Dv ARCHIVE_FILTER_LZIP 326.\" 327.It Dv ARCHIVE_BYTES_PER_RECORD 328.Li 512 329.It Dv ARCHIVE_DEFAULT_BYTES_PER_BLOCK 330.Li 10240 331.El 332.Sh SEE ALSO 333.Xr libarchive 3 , 334.Xr archive_read 3 , 335.Xr archive_read_filter 3 , 336.Xr archive_read_format 3 , 337.Xr archive_read_set_options 3 , 338.Xr archive_write 3 , 339.Xr archive_write_filter 3 , 340.Xr archive_write_format 3 , 341.Xr archive_write_set_options 3 , 342.Xr archive_util 3 343