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