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