diff options
Diffstat (limited to 'libarchive/libarchive_changes.3')
| -rw-r--r-- | libarchive/libarchive_changes.3 | 341 |
1 files changed, 341 insertions, 0 deletions
diff --git a/libarchive/libarchive_changes.3 b/libarchive/libarchive_changes.3 new file mode 100644 index 000000000000..6ee6af245a8a --- /dev/null +++ b/libarchive/libarchive_changes.3 @@ -0,0 +1,341 @@ +.\" Copyright (c) 2011 Tim Kientzle +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd March 27, 2011 +.Dt LIBARCHIVE_CHANGES 3 +.Os +.Sh NAME +.Nm changes in libarchive interface +.\" +.Sh CHANGES IN LIBARCHIVE 3 +This page describes user-visible changes in libarchive3, and lists +public functions and other symbols changed, deprecated or removed +in libarchive3, along with their replacements if any. +.Pp +.\" +.Ss Multiple Filters +.\" +Libarchive2 permitted a single (input or output) filter active +on an archive. +Libarchive3 extends this into a variable-length stack. +Where +.Fn archive_write_set_compression_XXX +would replace any existing filter, +.Fn archive_write_add_filter_XXX +extends the write pipeline with another filter. +.\" +.Ss Character Set Handling +.\" +Libarchive2 assumed that the local platform uses +.Tn Unicode +as the native +.Tn wchar_t +encoding, which is true on +.Tn Windows , +modern +.Tn Linux , +and a few other systems, but is certainly not universal. +As a result, pax format archives were written incorrectly on some +systems, since pax format requires +.Tn UTF-8 +and libarchive 2 incorrectly +assumed that +.Tn wchar_t +strings can be easily converted to +.Tn UTF-8 . +.Pp +Libarchive3 uses the standard iconv library to convert between character +sets and is introducing the notion of a +.Dq default character set for the archive . +To support this, +.Tn archive_entry +objects can now be bound to a particular archive when they are created. +The automatic character set conversions performed by +.Tn archive_entry +objects when reading and writing filenames, usernames, and other strings +will now use an appropriate default character set: +.Pp +If the +.Tn archive_entry +object is bound to an archive, it will use the +default character set for that archive. +.Pp +The platform default character encoding (as returned by +.Fn nl_langinfo CHARSET ) +will be used if nothing else is specified. +.Pp +Libarchive3 also introduces charset options to many of the archive +readers and writers to control the character set that will be used for +filenames written in those archives. +When possible, this will be set automatically based on information in +the archive itself. +Combining this with the notion of a default character set for the +archive should allow you to configure libarchive to read archives from +other platforms and have the filenames and other information +transparently converted to the character encoding suitable for your +application. +.\" +.Ss Prototype Changes +.\" +These changes break binary compatibility; libarchive3 has a new shared +library version to reflect these changes. +The library now uses portable wide types such as +.Tn int64_t +instead of less-portable types such as +.Tn off_t , +.Tn gid_t , +.Tn uid_t , +and +.Tn ino_t . +.Pp +There are a few cases where these changes will affect your source code: +.Bl -bullet -width ind +.It +In some cases, libarchive's wider types will introduce the possibility +of truncation: for example, on a system with a 16-bit +.Tn uid_t , you risk having uid +.Li 65536 +be truncated to uid +.Li 0 , +which can cause serious security problems. +.It +Typedef function pointer types will be incompatible. +For example, if you define custom skip callbacks, you may have to use +code similar to the following if you want to support building against +libarchive2 and libarchive3: +.Bd -literal +#if ARCHIVE_VERSION_NUMBER < 3000000 +typedef off_t myoff_t; +#else +typedef int64_t myoff_t; +#endif + +myoff_t +my_skip_function(struct archive *a, void *v, myoff_t o) +{ + ... implementation ... +} +.Ed +.El +.Pp +Affected functions: +.Pp +.Bl -bullet -compact +.It +.Xo +.Fn archive_entry_gid , +.Fn archive_entry_set_gid +.Xc +.It +.Xo +.Fn archive_entry_uid , +.Fn archive_entry_set_uid +.Xc +.It +.Xo +.Fn archive_entry_ino , +.Fn archive_entry_set_ino +.Xc +.It +.Xo +.Fn archive_read_data_block , +.Fn archive_write_data_block +.Xc +.It +.Xo +.Fn archive_read_disk_gname , +.Fn archive_read_disk_uname +.Xc +.It +.Xo +.Fn archive_read_disk_set_gname_lookup , +.Fn archive_read_disk_set_group_lookup , +.Fn archive_read_disk_set_uname_lookup , +.Fn archive_read_disk_set_user_lookup +.Xc +.It +.Fn archive_skip_callback +.It +.Xo +.Fn archive_read_extract_set_skip_file , +.Fn archive_write_disk_set_skip_file , +.Fn archive_write_set_skip_file +.Xc +.It +.Xo +.Fn archive_write_disk_set_group_lookup , +.Fn archive_write_disk_set_user_lookup +.Xc +.El +.Pp +Where these functions or their arguments took or returned +.Tn gid_t , +.Tn ino_t , +.Tn off_t , +or +.Tn uid_t +they now take or return +.Tn int64_t +or equivalent. +.\" +.Ss Deprecated Symbols +.\" +Symbols deprecated in libarchive3 will be removed in libarchive4. +These symbols, along with their replacements if any, are listed below: +.\" +.Bl -tag -width ind +.It Fn archive_position_compressed , Fn archive_position_uncompressed +.Fn archive_filter_bytes +.It Fn archive_compression +.Fn archive_filter_code +.It Fn archive_compression_name +.Fn archive_filter_name +.It Fn archive_read_finish , Fn archive_write_finish +.Fn archive_read_free , +.Fn archive_write_free +.It Fn archive_read_open_file , Fn archive_write_open_file +.Fn archive_read_open_filename , +.Fn archive_write_open_filename +.It Fn archive_read_support_compression_all +.\" archive_read_support_compression_* -> archive_read_support_filter_* +.Fn archive_read_support_filter_all +.It Fn archive_read_support_compression_bzip2 +.Fn archive_read_support_filter_bzip2 +.It Fn archive_read_support_compression_compress +.Fn archive_read_support_filter_compress +.It Fn archive_read_support_compression_gzip +.Fn archive_read_support_filter_gzip +.It Fn archive_read_support_compression_lzip +.Fn archive_read_support_filter_lzip +.It Fn archive_read_support_compression_lzma +.Fn archive_read_support_filter_lzma +.It Fn archive_read_support_compression_none +.Fn archive_read_support_filter_none +.It Fn archive_read_support_compression_program +.Fn archive_read_support_filter_program +.It Fn archive_read_support_compression_program_signature +.Fn archive_read_support_filter_program_signature +.It Fn archive_read_support_compression_rpm +.Fn archive_read_support_filter_rpm +.It Fn archive_read_support_compression_uu +.Fn archive_read_support_filter_uu +.It Fn archive_read_support_compression_xz +.Fn archive_read_support_filter_xz +.\" archive_write_set_compression_* -> archive_write_add_filter_* +.It Fn archive_write_set_compression_bzip2 +.Fn archive_write_add_filter_bzip2 +.It Fn archive_write_set_compression_compress +.Fn archive_write_add_filter_compress +.It Fn archive_write_set_compression_gzip +.Fn archive_write_add_filter_gzip +.It Fn archive_write_set_compression_lzip +.Fn archive_write_add_filter_lzip +.It Fn archive_write_set_compression_lzma +.Fn archive_write_add_filter_lzma +.It Fn archive_write_set_compression_none +.Fn archive_write_add_filter_none +.It Fn archive_write_set_compression_program +.Fn archive_write_add_filter_program +.It Fn archive_write_set_compression_filter +.Fn archive_write_add_filter_filter +.El +.\" +.Ss Removed Symbols +.\" +These symbols, listed below along with their replacements if any, +were deprecated in libarchive2, and are not part of libarchive3. +.\" +.Bl -tag -width ind +.It Fn archive_api_feature +.Fn archive_version_number +.It Fn archive_api_version +.Fn archive_version_number +.It Fn archive_version +.Fn archive_version_string +.It Fn archive_version_stamp +.Fn archive_version_number +.It Fn archive_read_set_filter_options +.Fn archive_read_set_options +or +.Fn archive_read_set_filter_option +.It Fn archive_read_set_format_options +.Fn archive_read_set_options +or +.Fn archive_read_set_format_option +.It Fn archive_write_set_filter_options +.Fn archive_write_set_options +or +.Fn archive_write_set_filter_option +.It Fn archive_write_set_format_options +.Fn archive_write_set_options +or +.Fn archive_write_set_format_option +.It Dv ARCHIVE_API_FEATURE +.Dv ARCHIVE_VERSION_NUMBER +.It Dv ARCHIVE_API_VERSION +.Dv ARCHIVE_VERSION_NUMBER +.It Dv ARCHIVE_VERSION_STAMP +.Dv ARCHIVE_VERSION_NUMBER +.It Dv ARCHIVE_LIBRARY_VERSION +.Dv ARCHIVE_VERSION_STRING +.\" +.It Dv ARCHIVE_COMPRESSION_NONE +.Dv ARCHIVE_FILTER_NONE +.It Dv ARCHIVE_COMPRESSION_GZIP +.Dv ARCHIVE_FILTER_GZIP +.It Dv ARCHIVE_COMPRESSION_BZIP2 +.Dv ARCHIVE_FILTER_BZIP2 +.It Dv ARCHIVE_COMPRESSION_COMPRESS +.Dv ARCHIVE_FILTER_COMPRESS +.It Dv ARCHIVE_COMPRESSION_PROGRAM +.Dv ARCHIVE_FILTER_PROGRAM +.It Dv ARCHIVE_COMPRESSION_LZMA +.Dv ARCHIVE_FILTER_LZMA +.It Dv ARCHIVE_COMPRESSION_XZ +.Dv ARCHIVE_FILTER_XZ +.It Dv ARCHIVE_COMPRESSION_UU +.Dv ARCHIVE_FILTER_UU +.It Dv ARCHIVE_COMPRESSION_RPM +.Dv ARCHIVE_FILTER_RPM +.It Dv ARCHIVE_COMPRESSION_LZIP +.Dv ARCHIVE_FILTER_LZIP +.\" +.It Dv ARCHIVE_BYTES_PER_RECORD +.Li 512 +.It Dv ARCHIVE_DEFAULT_BYTES_PER_BLOCK +.Li 10240 +.El +.Sh SEE ALSO +.Xr libarchive 3 , +.Xr archive_read 3 , +.Xr archive_read_filter 3 , +.Xr archive_read_format 3 , +.Xr archive_read_set_options 3 , +.Xr archive_write 3 , +.Xr archive_write_filter 3 , +.Xr archive_write_format 3 , +.Xr archive_write_set_options 3 , +.Xr archive_util 3 |