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