Transitioning to libarchive 3.0.

Libarchive 3.0 was released in late December 2011. It represents nearly two years of development since libarchive 2.8 was released in early 2010. It also represents only the second API/ABI breakage since libarchive was first released in 2006.

For most users, the transition from libarchive 2.x should be nearly invisible, with at most a few minor changes to ensure that your code can compile against either libarchive 2.x or libarchive 3.0.

Most of the changes involve either removing functionality that has long been deprecated (and for which alternatives have existed for some time) and the adjustment of a number of function argument and return types to provide better portability.

The libarchive 3.0 release will also be deprecating some older functionality. This functionality will not be completely removed until libarchive 4.0, which should provide a transition window of at least two full years.

In all of these cases, the new function has been available for some time. If you are still using any of the old functions listed here, you should have already switched to the newer version.

These changes will break binary compatibility; the libarchive 3.0 distribution will have a new shared library version to reflect these changes. Most of these changes involve the use of portable wide types such as `int64_t` instead of less-portable types such as `off_t`, `gid_t`, `uid_t`, `dev_t`, and `ino_t`.

There are a few cases where these changes will affect your source code:

• In some cases, libarchive's wider types will introduce the possibility of truncation: For example, on a system with a 16-bit uid_t, you risk having uid 65536 be truncated to uid 0, which can cause serious security problems.
• 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 libarchive 2.x and libarchive 3.x.

#if ARCHIVE_VERSION_NUMBER < 3000000
off_t my_skip_function(struct archive *a, void *v, off_t o)
#else
int64_t my_skip_function(struct archive *a, void *v, int64_t o)
#endif
{
    /* ... implementation ... */
}

The old function name will continue to be supported until libarchive 4.0 is released, at which point the old name will be removed. So you can use the old function name for compatibility with libarchive 2.x. After 2012, you should plan to switch to the new names for compatibility with libarchive 4.0. This should provide libarchive users with a transition window of at least two full years.

The new functions will sometimes have slightly different functionality. In particular, the `write_add_filter` functions extend the write pipeline with a new filter, whereas the old `write_set_compression` functions replaced any existing filter.

Libarchive 2 has some deep bugs around handling character sets. In particular, it assumes that the local platform uses Unicode as the native wchar_t encoding, which is true on Windows, modern Linux, and a few other systems, but is certainly not universal. As a result, pax format archives are written incorrectly on some systems, since pax format requires UTF-8 and libarchive 2 incorrectly assumed that wchar_t strings can be easily converted to UTF-8.

Libarchive 3 now uses the standard iconv library to convert between character sets and is introducing the notion of a "default character set for the archive." To support this, `archive_entry` objects can now be bound to a particular archive when they are created. The automatic character set conversions performed by `archive_entry` objects when reading and writing filenames, usernames, and other strings will now use an appropriate default character set:

• If the `archive_entry` object is bound to an archive, it will use the default character set for that archive.
• The platform default character encoding (as returned by `nl_langinfo(CHARSET)`) will be used if nothing else is specified.