doc/text/libarchive_changes.3.txt

   1 LIBARCHIVE_CHANGES(3)    BSD Library Functions Manual    LIBARCHIVE_CHANGES(3)
   2
   3 1mNAME0m
   4      — changes in libarchive interface
   5
   6 1mCHANGES IN LIBARCHIVE 30m
   7      This page describes user-visible changes in libarchive3, and lists public
   8      functions and other symbols changed, deprecated or removed in
   9      libarchive3, along with their replacements if any.
  10
  11    1mMultiple Filters0m
  12      Libarchive2 permitted a single (input or output) filter active on an ar‐
  13      chive.  Libarchive3 extends this into a variable-length stack.  Where
  14      1marchive_write_set_compression_XXX22m() would replace any existing filter,
  15      1marchive_write_add_filter_XXX22m() extends the write pipeline with another
  16      filter.
  17
  18    1mCharacter Set Handling0m
  19      Libarchive2 assumed that the local platform uses Unicode as the native
  20      wchar_t encoding, which is true on Windows, modern Linux, and a few other
  21      systems, but is certainly not universal.  As a result, pax format ar‐
  22      chives were written incorrectly on some systems, since pax format
  23      requires UTF-8 and libarchive 2 incorrectly assumed that wchar_t strings
  24      can be easily converted to UTF-8.
  25
  26      Libarchive3 uses the standard iconv library to convert between character
  27      sets and is introducing the notion of a “default character set for the
  28      archive”.        To support this, archive_entry objects can now be bound to a
  29      particular archive when they are created.  The automatic character set
  30      conversions performed by archive_entry objects when reading and writing
  31      filenames, usernames, and other strings will now use an appropriate
  32      default character set:
  33
  34      If the archive_entry object is bound to an archive, it will use the
  35      default character set for that archive.
  36
  37      The platform default character encoding (as returned by
  38      1mnl_langinfo22m(4mCHARSET24m)) will be used if nothing else is specified.
  39
  40      Libarchive3 also introduces charset options to many of the archive read‐
  41      ers and writers to control the character set that will be used for file‐
  42      names written in those archives.  When possible, this will be set auto‐
  43      matically based on information in the archive itself.  Combining this
  44      with the notion of a default character set for the archive should allow
  45      you to configure libarchive to read archives from other platforms and
  46      have the filenames and other information transparently converted to the
  47      character encoding suitable for your application.
  48
  49    1mPrototype Changes0m
  50      These changes break binary compatibility; libarchive3 has a new shared
  51      library version to reflect these changes.  The library now uses portable
  52      wide types such as int64_t instead of less-portable types such as off_t,
  53      gid_t, uid_t, and ino_t.
  54
  55      There are a few cases where these changes will affect your source code:
  56
  57      1m·    22mIn some cases, libarchive's wider types will introduce the possibil‐
  58           ity of truncation: for example, on a system with a 16-bit uid_t, you
  59           risk having uid 65536 be truncated to uid 0, which can cause serious
  60           security problems.
  61
  62      1m·    22mTypedef function pointer types will be incompatible.  For example,
  63           if you define custom skip callbacks, you may have to use code simi‐
  64           lar to the following if you want to support building against
  65           libarchive2 and libarchive3:
  66
  67           #if ARCHIVE_VERSION_NUMBER < 3000000
  68           typedef off_t myoff_t;
  69           #else
  70           typedef int64_t myoff_t;
  71           #endif
  72
  73           myoff_t
  74           my_skip_function(struct archive *a, void *v, myoff_t o)
  75           {
  76               ... implementation ...
  77           }
  78
  79      Affected functions:
  80
  81      1m·   archive_entry_gid22m(), 1marchive_entry_set_gid22m()
  82      1m·   archive_entry_uid22m(), 1marchive_entry_set_uid22m()
  83      1m·   archive_entry_ino22m(), 1marchive_entry_set_ino22m()
  84      1m·   archive_read_data_block22m(), 1marchive_write_data_block22m()
  85      1m·   archive_read_disk_gname22m(), 1marchive_read_disk_uname22m()
  86      1m·   archive_read_disk_set_gname_lookup22m(),
  87          1marchive_read_disk_set_group_lookup22m(),
  88          1marchive_read_disk_set_uname_lookup22m(),
  89          1marchive_read_disk_set_user_lookup22m()
  90      1m·   archive_skip_callback22m()
  91      1m·   archive_read_extract_set_skip_file22m(),
  92          1marchive_write_disk_set_skip_file22m(), 1marchive_write_set_skip_file22m()
  93      1m·   archive_write_disk_set_group_lookup22m(),
  94          1marchive_write_disk_set_user_lookup22m()
  95
  96      Where these functions or their arguments took or returned gid_t, ino_t,
  97      off_t, or uid_t they now take or return int64_t or equivalent.
  98
  99    1mDeprecated Symbols0m
 100      Symbols deprecated in libarchive3 will be removed in libarchive4.  These
 101      symbols, along with their replacements if any, are listed below:
 102
 103      1marchive_position_compressed22m(), 1marchive_position_uncompressed22m()
 104           1marchive_filter_bytes22m()
 105
 106      1marchive_compression22m()
 107           1marchive_filter_code22m()
 108
 109      1marchive_compression_name22m()
 110           1marchive_filter_name22m()
 111
 112      1marchive_read_finish22m(), 1marchive_write_finish22m()
 113           1marchive_read_free22m(), 1marchive_write_free22m()
 114
 115      1marchive_read_open_file22m(), 1marchive_write_open_file22m()
 116           1marchive_read_open_filename22m(), 1marchive_write_open_filename22m()
 117
 118      1marchive_read_support_compression_all22m()
 119           1marchive_read_support_filter_all22m()
 120
 121      1marchive_read_support_compression_bzip222m()
 122           1marchive_read_support_filter_bzip222m()
 123
 124      1marchive_read_support_compression_compress22m()
 125           1marchive_read_support_filter_compress22m()
 126
 127      1marchive_read_support_compression_gzip22m()
 128           1marchive_read_support_filter_gzip22m()
 129
 130      1marchive_read_support_compression_lzip22m()
 131           1marchive_read_support_filter_lzip22m()
 132
 133      1marchive_read_support_compression_lzma22m()
 134           1marchive_read_support_filter_lzma22m()
 135
 136      1marchive_read_support_compression_none22m()
 137           1marchive_read_support_filter_none22m()
 138
 139      1marchive_read_support_compression_program22m()
 140           1marchive_read_support_filter_program22m()
 141
 142      1marchive_read_support_compression_program_signature22m()
 143           1marchive_read_support_filter_program_signature22m()
 144
 145      1marchive_read_support_compression_rpm22m()
 146           1marchive_read_support_filter_rpm22m()
 147
 148      1marchive_read_support_compression_uu22m()
 149           1marchive_read_support_filter_uu22m()
 150
 151      1marchive_read_support_compression_xz22m()
 152           1marchive_read_support_filter_xz22m()
 153
 154      1marchive_write_set_compression_bzip222m()
 155           1marchive_write_add_filter_bzip222m()
 156
 157      1marchive_write_set_compression_compress22m()
 158           1marchive_write_add_filter_compress22m()
 159
 160      1marchive_write_set_compression_gzip22m()
 161           1marchive_write_add_filter_gzip22m()
 162
 163      1marchive_write_set_compression_lzip22m()
 164           1marchive_write_add_filter_lzip22m()
 165
 166      1marchive_write_set_compression_lzma22m()
 167           1marchive_write_add_filter_lzma22m()
 168
 169      1marchive_write_set_compression_none22m()
 170           1marchive_write_add_filter_none22m()
 171
 172      1marchive_write_set_compression_program22m()
 173           1marchive_write_add_filter_program22m()
 174
 175      1marchive_write_set_compression_filter22m()
 176           1marchive_write_add_filter_filter22m()
 177
 178    1mRemoved Symbols0m
 179      These symbols, listed below along with their replacements if any, were
 180      deprecated in libarchive2, and are not part of libarchive3.
 181
 182      1marchive_api_feature22m()
 183           1marchive_version_number22m()
 184
 185      1marchive_api_version22m()
 186           1marchive_version_number22m()
 187
 188      1marchive_version22m()
 189           1marchive_version_string22m()
 190
 191      1marchive_version_stamp22m()
 192           1marchive_version_number22m()
 193
 194      1marchive_read_set_filter_options22m()
 195           1marchive_read_set_options22m() or 1marchive_read_set_filter_option22m()
 196
 197      1marchive_read_set_format_options22m()
 198           1marchive_read_set_options22m() or 1marchive_read_set_format_option22m()
 199
 200      1marchive_write_set_filter_options22m()
 201           1marchive_write_set_options22m() or 1marchive_write_set_filter_option22m()
 202
 203      1marchive_write_set_format_options22m()
 204           1marchive_write_set_options22m() or 1marchive_write_set_format_option22m()
 205
 206      ARCHIVE_API_FEATURE
 207           ARCHIVE_VERSION_NUMBER
 208
 209      ARCHIVE_API_VERSION
 210           ARCHIVE_VERSION_NUMBER
 211
 212      ARCHIVE_VERSION_STAMP
 213           ARCHIVE_VERSION_NUMBER
 214
 215      ARCHIVE_LIBRARY_VERSION
 216           ARCHIVE_VERSION_STRING
 217
 218      ARCHIVE_COMPRESSION_NONE
 219           ARCHIVE_FILTER_NONE
 220
 221      ARCHIVE_COMPRESSION_GZIP
 222           ARCHIVE_FILTER_GZIP
 223
 224      ARCHIVE_COMPRESSION_BZIP2
 225           ARCHIVE_FILTER_BZIP2
 226
 227      ARCHIVE_COMPRESSION_COMPRESS
 228           ARCHIVE_FILTER_COMPRESS
 229
 230      ARCHIVE_COMPRESSION_PROGRAM
 231           ARCHIVE_FILTER_PROGRAM
 232
 233      ARCHIVE_COMPRESSION_LZMA
 234           ARCHIVE_FILTER_LZMA
 235
 236      ARCHIVE_COMPRESSION_XZ
 237           ARCHIVE_FILTER_XZ
 238
 239      ARCHIVE_COMPRESSION_UU
 240           ARCHIVE_FILTER_UU
 241
 242      ARCHIVE_COMPRESSION_RPM
 243           ARCHIVE_FILTER_RPM
 244
 245      ARCHIVE_COMPRESSION_LZIP
 246           ARCHIVE_FILTER_LZIP
 247
 248      ARCHIVE_BYTES_PER_RECORD
 249           512
 250
 251      ARCHIVE_DEFAULT_BYTES_PER_BLOCK
 252           10240
 253
 254 1mSEE ALSO0m
 255      libarchive(3), archive_read(3), archive_read_filter(3),
 256      archive_read_format(3), archive_read_set_options(3), archive_write(3),
 257      archive_write_filter(3), archive_write_format(3),
 258      archive_write_set_options(3), archive_util(3)
 259
 260 BSD                            December 23, 2011                           BSD