mirror of
https://github.com/cmclark00/retro-imager.git
synced 2025-05-19 08:25:21 +01:00
67618a2eac
- Update bunlded libarchive version used on Windows/Mac - Enable requested zstd support while we are at it. Closes #211
303 lines
9.7 KiB
Text
303 lines
9.7 KiB
Text
LIBARCHIVE_CHANGES(3) manual page
|
|
== NAME ==
|
|
'''libarchive_changes'''
|
|
- changes in libarchive interface
|
|
== 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.
|
|
=== Multiple Filters===
|
|
Libarchive2 permitted a single (input or output) filter active
|
|
on an archive.
|
|
Libarchive3 extends this into a variable-length stack.
|
|
Where
|
|
'''archive_write_set_compression_XXX'''()
|
|
would replace any existing filter,
|
|
'''archive_write_add_filter_XXX'''()
|
|
extends the write pipeline with another filter.
|
|
=== Character Set Handling===
|
|
Libarchive2 assumed 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 were 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 .'''
|
|
|
|
Libarchive3 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.
|
|
|
|
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.
|
|
=== 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
|
|
'''int64_t'''
|
|
instead of less-portable types such as
|
|
'''off_t ,'''
|
|
'''gid_t ,'''
|
|
'''uid_t ,'''
|
|
and
|
|
'''ino_t .'''
|
|
|
|
There are a few cases where these changes will affect your source code:
|
|
<ul>
|
|
<li>
|
|
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'''
|
|
```text
|
|
65536
|
|
```
|
|
be truncated to uid
|
|
```text
|
|
0,
|
|
```
|
|
which can cause serious security problems.
|
|
</li><li>
|
|
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:
|
|
```text
|
|
#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 ...
|
|
}
|
|
```
|
|
</li></ul>
|
|
|
|
Affected functions:
|
|
|
|
<ul>
|
|
<li>
|
|
'''archive_entry_gid'''(),
|
|
'''archive_entry_set_gid'''()
|
|
</li><li>
|
|
'''archive_entry_uid'''(),
|
|
'''archive_entry_set_uid'''()
|
|
</li><li>
|
|
'''archive_entry_ino'''(),
|
|
'''archive_entry_set_ino'''()
|
|
</li><li>
|
|
'''archive_read_data_block'''(),
|
|
'''archive_write_data_block'''()
|
|
</li><li>
|
|
'''archive_read_disk_gname'''(),
|
|
'''archive_read_disk_uname'''()
|
|
</li><li>
|
|
'''archive_read_disk_set_gname_lookup'''(),
|
|
'''archive_read_disk_set_group_lookup'''(),
|
|
'''archive_read_disk_set_uname_lookup'''(),
|
|
'''archive_read_disk_set_user_lookup'''()
|
|
</li><li>
|
|
'''archive_skip_callback'''()
|
|
</li><li>
|
|
'''archive_read_extract_set_skip_file'''(),
|
|
'''archive_write_disk_set_skip_file'''(),
|
|
'''archive_write_set_skip_file'''()
|
|
</li><li>
|
|
'''archive_write_disk_set_group_lookup'''(),
|
|
'''archive_write_disk_set_user_lookup'''()
|
|
</li></ul>
|
|
|
|
Where these functions or their arguments took or returned
|
|
'''gid_t ,'''
|
|
'''ino_t ,'''
|
|
'''off_t ,'''
|
|
or
|
|
'''uid_t'''
|
|
they now take or return
|
|
'''int64_t'''
|
|
or equivalent.
|
|
=== Deprecated Symbols===
|
|
Symbols deprecated in libarchive3 will be removed in libarchive4.
|
|
These symbols, along with their replacements if any, are listed below:
|
|
<dl>
|
|
<dt>'''archive_position_compressed'''(), '''archive_position_uncompressed'''()</dt><dd>
|
|
'''archive_filter_bytes'''()
|
|
</dd><dt>'''archive_compression'''()</dt><dd>
|
|
'''archive_filter_code'''()
|
|
</dd><dt>'''archive_compression_name'''()</dt><dd>
|
|
'''archive_filter_name'''()
|
|
</dd><dt>'''archive_read_finish'''(), '''archive_write_finish'''()</dt><dd>
|
|
'''archive_read_free'''(),
|
|
'''archive_write_free'''()
|
|
</dd><dt>'''archive_read_open_file'''(), '''archive_write_open_file'''()</dt><dd>
|
|
'''archive_read_open_filename'''(),
|
|
'''archive_write_open_filename'''()
|
|
</dd><dt>'''archive_read_support_compression_all'''()</dt><dd>
|
|
'''archive_read_support_filter_all'''()
|
|
</dd><dt>'''archive_read_support_compression_bzip2'''()</dt><dd>
|
|
'''archive_read_support_filter_bzip2'''()
|
|
</dd><dt>'''archive_read_support_compression_compress'''()</dt><dd>
|
|
'''archive_read_support_filter_compress'''()
|
|
</dd><dt>'''archive_read_support_compression_gzip'''()</dt><dd>
|
|
'''archive_read_support_filter_gzip'''()
|
|
</dd><dt>'''archive_read_support_compression_lzip'''()</dt><dd>
|
|
'''archive_read_support_filter_lzip'''()
|
|
</dd><dt>'''archive_read_support_compression_lzma'''()</dt><dd>
|
|
'''archive_read_support_filter_lzma'''()
|
|
</dd><dt>'''archive_read_support_compression_none'''()</dt><dd>
|
|
'''archive_read_support_filter_none'''()
|
|
</dd><dt>'''archive_read_support_compression_program'''()</dt><dd>
|
|
'''archive_read_support_filter_program'''()
|
|
</dd><dt>'''archive_read_support_compression_program_signature'''()</dt><dd>
|
|
'''archive_read_support_filter_program_signature'''()
|
|
</dd><dt>'''archive_read_support_compression_rpm'''()</dt><dd>
|
|
'''archive_read_support_filter_rpm'''()
|
|
</dd><dt>'''archive_read_support_compression_uu'''()</dt><dd>
|
|
'''archive_read_support_filter_uu'''()
|
|
</dd><dt>'''archive_read_support_compression_xz'''()</dt><dd>
|
|
'''archive_read_support_filter_xz'''()
|
|
</dd><dt>'''archive_write_set_compression_bzip2'''()</dt><dd>
|
|
'''archive_write_add_filter_bzip2'''()
|
|
</dd><dt>'''archive_write_set_compression_compress'''()</dt><dd>
|
|
'''archive_write_add_filter_compress'''()
|
|
</dd><dt>'''archive_write_set_compression_gzip'''()</dt><dd>
|
|
'''archive_write_add_filter_gzip'''()
|
|
</dd><dt>'''archive_write_set_compression_lzip'''()</dt><dd>
|
|
'''archive_write_add_filter_lzip'''()
|
|
</dd><dt>'''archive_write_set_compression_lzma'''()</dt><dd>
|
|
'''archive_write_add_filter_lzma'''()
|
|
</dd><dt>'''archive_write_set_compression_none'''()</dt><dd>
|
|
'''archive_write_add_filter_none'''()
|
|
</dd><dt>'''archive_write_set_compression_program'''()</dt><dd>
|
|
'''archive_write_add_filter_program'''()
|
|
</dd><dt>'''archive_write_set_compression_filter'''()</dt><dd>
|
|
'''archive_write_add_filter_filter'''()
|
|
</dd></dl>
|
|
=== Removed Symbols===
|
|
These symbols, listed below along with their replacements if any,
|
|
were deprecated in libarchive2, and are not part of libarchive3.
|
|
<dl>
|
|
<dt>'''archive_api_feature'''()</dt><dd>
|
|
'''archive_version_number'''()
|
|
</dd><dt>'''archive_api_version'''()</dt><dd>
|
|
'''archive_version_number'''()
|
|
</dd><dt>'''archive_version'''()</dt><dd>
|
|
'''archive_version_string'''()
|
|
</dd><dt>'''archive_version_stamp'''()</dt><dd>
|
|
'''archive_version_number'''()
|
|
</dd><dt>'''archive_read_set_filter_options'''()</dt><dd>
|
|
'''archive_read_set_options'''()
|
|
or
|
|
'''archive_read_set_filter_option'''()
|
|
</dd><dt>'''archive_read_set_format_options'''()</dt><dd>
|
|
'''archive_read_set_options'''()
|
|
or
|
|
'''archive_read_set_format_option'''()
|
|
</dd><dt>'''archive_write_set_filter_options'''()</dt><dd>
|
|
'''archive_write_set_options'''()
|
|
or
|
|
'''archive_write_set_filter_option'''()
|
|
</dd><dt>'''archive_write_set_format_options'''()</dt><dd>
|
|
'''archive_write_set_options'''()
|
|
or
|
|
'''archive_write_set_format_option'''()
|
|
</dd><dt></dt><dd>
|
|
ARCHIVE_API_FEATURE
|
|
ARCHIVE_VERSION_NUMBER
|
|
</dd><dt></dt><dd>
|
|
ARCHIVE_API_VERSION
|
|
ARCHIVE_VERSION_NUMBER
|
|
</dd><dt></dt><dd>
|
|
ARCHIVE_VERSION_STAMP
|
|
ARCHIVE_VERSION_NUMBER
|
|
</dd><dt></dt><dd>
|
|
ARCHIVE_LIBRARY_VERSION
|
|
ARCHIVE_VERSION_STRING
|
|
</dd><dt></dt><dd>
|
|
ARCHIVE_COMPRESSION_NONE
|
|
ARCHIVE_FILTER_NONE
|
|
</dd><dt></dt><dd>
|
|
ARCHIVE_COMPRESSION_GZIP
|
|
ARCHIVE_FILTER_GZIP
|
|
</dd><dt></dt><dd>
|
|
ARCHIVE_COMPRESSION_BZIP2
|
|
ARCHIVE_FILTER_BZIP2
|
|
</dd><dt></dt><dd>
|
|
ARCHIVE_COMPRESSION_COMPRESS
|
|
ARCHIVE_FILTER_COMPRESS
|
|
</dd><dt></dt><dd>
|
|
ARCHIVE_COMPRESSION_PROGRAM
|
|
ARCHIVE_FILTER_PROGRAM
|
|
</dd><dt></dt><dd>
|
|
ARCHIVE_COMPRESSION_LZMA
|
|
ARCHIVE_FILTER_LZMA
|
|
</dd><dt></dt><dd>
|
|
ARCHIVE_COMPRESSION_XZ
|
|
ARCHIVE_FILTER_XZ
|
|
</dd><dt></dt><dd>
|
|
ARCHIVE_COMPRESSION_UU
|
|
ARCHIVE_FILTER_UU
|
|
</dd><dt></dt><dd>
|
|
ARCHIVE_COMPRESSION_RPM
|
|
ARCHIVE_FILTER_RPM
|
|
</dd><dt></dt><dd>
|
|
ARCHIVE_COMPRESSION_LZIP
|
|
ARCHIVE_FILTER_LZIP
|
|
</dd><dt></dt><dd>
|
|
ARCHIVE_BYTES_PER_RECORD
|
|
```text
|
|
512
|
|
```
|
|
</dd><dt></dt><dd>
|
|
ARCHIVE_DEFAULT_BYTES_PER_BLOCK
|
|
```text
|
|
10240
|
|
```
|
|
</dd></dl>
|
|
== SEE ALSO ==
|
|
[[ManPageArchiveRead3]],
|
|
[[ManPageArchiveReadFilter3]],
|
|
[[ManPageArchiveReadFormat3]],
|
|
[[ManPageArchiveReadSetOptions3]],
|
|
[[ManPageArchiveUtil3]],
|
|
[[ManPageArchiveWrite3]],
|
|
[[ManPageArchiveWriteFilter3]],
|
|
[[ManPageArchiveWriteFormat3]],
|
|
[[ManPageArchiveWriteSetOptions3]],
|
|
[[ManPageLibarchive3]]
|