1 .\" Copyright (c) 2003-2007 Tim Kientzle
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
25 .\" $FreeBSD: src/lib/libarchive/archive_read.3,v 1.33 2007/04/07 05:53:11 kientzle Exp $
31 .Nm archive_read_new ,
32 .Nm archive_read_support_compression_all ,
33 .Nm archive_read_support_compression_bzip2 ,
34 .Nm archive_read_support_compression_compress ,
35 .Nm archive_read_support_compression_gzip ,
36 .Nm archive_read_support_compression_none ,
37 .Nm archive_read_support_format_all ,
38 .Nm archive_read_support_format_cpio ,
39 .Nm archive_read_support_format_empty ,
40 .Nm archive_read_support_format_iso9660 ,
41 .Nm archive_read_support_format_tar ,
42 .Nm archive_read_support_format_zip ,
43 .Nm archive_read_open ,
44 .Nm archive_read_open2 ,
45 .Nm archive_read_open_fd ,
46 .Nm archive_read_open_FILE ,
47 .Nm archive_read_open_filename ,
48 .Nm archive_read_open_memory ,
49 .Nm archive_read_next_header ,
50 .Nm archive_read_data ,
51 .Nm archive_read_data_block ,
52 .Nm archive_read_data_skip ,
53 .\" #if ARCHIVE_API_VERSION < 3
54 .Nm archive_read_data_into_buffer ,
56 .Nm archive_read_data_into_fd ,
57 .Nm archive_read_extract ,
58 .Nm archive_read_extract_set_progress_callback ,
59 .Nm archive_read_close ,
60 .Nm archive_read_finish
61 .Nd functions for reading streaming archives
65 .Fn archive_read_new "void"
67 .Fn archive_read_support_compression_all "struct archive *"
69 .Fn archive_read_support_compression_bzip2 "struct archive *"
71 .Fn archive_read_support_compression_compress "struct archive *"
73 .Fn archive_read_support_compression_gzip "struct archive *"
75 .Fn archive_read_support_compression_none "struct archive *"
77 .Fn archive_read_support_format_all "struct archive *"
79 .Fn archive_read_support_format_cpio "struct archive *"
81 .Fn archive_read_support_format_empty "struct archive *"
83 .Fn archive_read_support_format_iso9660 "struct archive *"
85 .Fn archive_read_support_format_tar "struct archive *"
87 .Fn archive_read_support_format_zip "struct archive *"
89 .Fn archive_read_open "struct archive *" "void *client_data" "archive_open_callback *" "archive_read_callback *" "archive_close_callback *"
91 .Fn archive_read_open2 "struct archive *" "void *client_data" "archive_open_callback *" "archive_read_callback *" "archive_skip_callback *" "archive_close_callback *"
93 .Fn archive_read_open_FILE "struct archive *" "FILE *file"
95 .Fn archive_read_open_fd "struct archive *" "int fd" "size_t block_size"
97 .Fn archive_read_open_filename "struct archive *" "const char *filename" "size_t block_size"
99 .Fn archive_read_open_memory "struct archive *" "void *buff" "size_t size"
101 .Fn archive_read_next_header "struct archive *" "struct archive_entry **"
103 .Fn archive_read_data "struct archive *" "void *buff" "size_t len"
105 .Fn archive_read_data_block "struct archive *" "const void **buff" "size_t *len" "off_t *offset"
107 .Fn archive_read_data_skip "struct archive *"
108 .\" #if ARCHIVE_API_VERSION < 3
110 .Fn archive_read_data_into_buffer "struct archive *" "void *" "ssize_t len"
113 .Fn archive_read_data_into_fd "struct archive *" "int fd"
115 .Fn archive_read_extract "struct archive *" "struct archive_entry *" "int flags"
117 .Fn archive_read_extract_set_progress_callback "struct archive *" "void (*func)(void *)" "void *user_data"
119 .Fn archive_read_close "struct archive *"
121 .Fn archive_read_finish "struct archive *"
123 These functions provide a complete API for reading streaming archives.
124 The general process is to first create the
126 object, set options, initialize the reader, iterate over the archive
127 headers and associated data, then close the archive and release all
129 The following summary describes the functions in approximately the
130 order they would be used:
131 .Bl -tag -compact -width indent
132 .It Fn archive_read_new
133 Allocates and initializes a
135 object suitable for reading from an archive.
136 .It Fn archive_read_support_compression_all , Fn archive_read_support_compression_bzip2 , Fn archive_read_support_compression_compress , Fn archive_read_support_compression_gzip , Fn archive_read_support_compression_none
137 Enables auto-detection code and decompression support for the
138 specified compression.
141 is always enabled by default.
143 .Fn archive_read_support_compression_all
144 enables all available decompression code.
145 .It Fn archive_read_support_format_all , Fn archive_read_support_format_cpio , Fn archive_read_support_format_empty , Fn archive_read_support_format_iso9660 , Fn archive_read_support_format_tar, Fn archive_read_support_format_zip
146 Enables support---including auto-detection code---for the
147 specified archive format.
149 .Fn archive_read_support_format_tar
150 enables support for a variety of standard tar formats, old-style tar,
151 ustar, pax interchange format, and many common variants.
153 .Fn archive_read_support_format_all
154 enables support for all available formats.
155 Only empty archives are supported by default.
156 .It Fn archive_read_open
158 .Fn archive_read_open2 ,
159 except that the skip callback is assumed to be
161 .It Fn archive_read_open2
162 Freeze the settings, open the archive, and prepare for reading entries.
163 This is the most generic version of this call, which accepts
164 four callback functions.
165 Most clients will want to use
166 .Fn archive_read_open_filename ,
167 .Fn archive_read_open_FILE ,
168 .Fn archive_read_open_fd ,
170 .Fn archive_read_open_memory
172 The library invokes the client-provided functions to obtain
173 raw bytes from the archive.
174 .It Fn archive_read_open_FILE
176 .Fn archive_read_open ,
177 except that it accepts a
180 This function should not be used with tape drives or other devices
181 that require strict I/O blocking.
182 .It Fn archive_read_open_fd
184 .Fn archive_read_open ,
185 except that it accepts a file descriptor and block size rather than
186 a set of function pointers.
187 Note that the file descriptor will not be automatically closed at
189 This function is safe for use with tape drives or other blocked devices.
190 .It Fn archive_read_open_file
191 This is a deprecated synonym for
192 .Fn archive_read_open_filename .
193 .It Fn archive_read_open_filename
195 .Fn archive_read_open ,
196 except that it accepts a simple filename and a block size.
197 A NULL filename represents standard input.
198 This function is safe for use with tape drives or other blocked devices.
199 .It Fn archive_read_open_memory
201 .Fn archive_read_open ,
202 except that it accepts a pointer and size of a block of
203 memory containing the archive data.
204 .It Fn archive_read_next_header
205 Read the header for the next entry and return a pointer to
207 .Tn struct archive_entry .
208 .It Fn archive_read_data
209 Read data associated with the header just read.
210 Internally, this is a convenience function that calls
211 .Fn archive_read_data_block
212 and fills any gaps with nulls so that callers see a single
213 continuous stream of data.
214 .It Fn archive_read_data_block
215 Return the next available block of data for this entry.
217 .Fn archive_read_data ,
219 .Fn archive_read_data_block
220 function avoids copying data and allows you to correctly handle
221 sparse files, as supported by some archive formats.
222 The library guarantees that offsets will increase and that blocks
224 Note that the blocks returned from this function can be much larger
225 than the block size read from disk, due to compression
226 and internal buffer optimizations.
227 .It Fn archive_read_data_skip
228 A convenience function that repeatedly calls
229 .Fn archive_read_data_block
230 to skip all of the data for this archive entry.
231 .\" #if ARCHIVE_API_VERSION < 3
232 .It Fn archive_read_data_into_buffer
233 This function is deprecated and will be removed.
235 .Fn archive_read_data
238 .It Fn archive_read_data_into_fd
239 A convenience function that repeatedly calls
240 .Fn archive_read_data_block
241 to copy the entire entry to the provided file descriptor.
242 .It Fn archive_read_extract , Fn archive_read_extract_set_skip_file
243 A convenience function that wraps the corresponding
244 .Xr archive_write_disk 3
247 .Fn archive_read_extract
248 creates a restore object using
249 .Xr archive_write_disk_new 3
251 .Xr archive_write_disk_set_standard_lookup 3 ,
252 then transparently invokes
253 .Xr archive_write_disk_set_options 3 ,
254 .Xr archive_write_header 3 ,
255 .Xr archive_write_data 3 ,
257 .Xr archive_write_finish_entry 3
258 to create the entry on disk and copy data into it.
261 argument is passed unmodified to
262 .Xr archiv_write_disk_set_options 3 .
263 .It Fn archive_read_extract_set_progress_callback
264 Sets a pointer to a user-defined callback that can be used
265 for updating progress displays during extraction.
266 The progress function will be invoked during the extraction of large
268 The progress function will be invoked with the pointer provided to this call.
269 Generally, the data pointed to should include a reference to the archive
270 object and the archive_entry object so that various statistics
271 can be retrieved for the progress display.
272 .It Fn archive_read_close
273 Complete the archive and invoke the close callback.
274 .It Fn archive_read_finish
276 .Fn archive_read_close
277 if it was not invoked manually, then release all resources.
278 Note: In libarchive 1.x, this function was declared to return
280 which made it impossible to detect certain errors when
281 .Fn archive_read_close
282 was invoked implicitly from this function.
283 The declaration is corrected beginning with libarchive 2.0.
286 Note that the library determines most of the relevant information about
287 the archive by inspection.
288 In particular, it automatically detects
292 compression and transparently performs the appropriate decompression.
293 It also automatically detects the archive format.
295 A complete description of the
298 .Tn struct archive_entry
299 objects can be found in the overview manual page for
302 The callback functions must match the following prototypes:
303 .Bl -item -offset indent
306 .Fn archive_read_callback "struct archive *" "void *client_data" "const void **buffer"
308 .\" #if ARCHIVE_API_VERSION < 2
310 .Fn archive_skip_callback "struct archive *" "void *client_data" "size_t request"
312 .\" .Ft typedef off_t
313 .\" .Fn archive_skip_callback "struct archive *" "void *client_data" "off_t request"
317 .Fn archive_open_callback "struct archive *" "void *client_data"
320 .Fn archive_close_callback "struct archive *" "void *client_data"
323 The open callback is invoked by
327 if the underlying file or data source is successfully
329 If the open fails, it should call
330 .Fn archive_set_error
331 to register an error code and message and return
334 The read callback is invoked whenever the library
335 requires raw bytes from the archive.
336 The read callback should read data into a buffer,
338 .Li const void **buffer
339 argument to point to the available data, and
340 return a count of the number of bytes available.
341 The library will invoke the read callback again
342 only after it has consumed this data.
343 The library imposes no constraints on the size
344 of the data blocks returned.
345 On end-of-file, the read callback should
347 On error, the read callback should invoke
348 .Fn archive_set_error
349 to register an error code and message and
352 The skip callback is invoked when the
353 library wants to ignore a block of data.
354 The return value is the number of bytes actually
355 skipped, which may differ from the request.
356 If the callback cannot skip data, it should return
358 If the skip callback is not provided (the
361 the library will invoke the read function
362 instead and simply discard the result.
363 A skip callback can provide significant
364 performance gains when reading uncompressed
365 archives from slow disk drives or other media
366 that can skip quickly.
368 The close callback is invoked by archive_close when
369 the archive processing is complete.
370 The callback should return
373 On failure, the callback should invoke
374 .Fn archive_set_error
375 to register an error code and message and
379 The following illustrates basic usage of the library.
381 the callback functions are simply wrappers around the standard
387 .Bd -literal -offset indent
389 list_archive(const char *name)
391 struct mydata *mydata;
393 struct archive_entry *entry;
395 mydata = malloc(sizeof(struct mydata));
396 a = archive_read_new();
398 archive_read_support_compression_all(a);
399 archive_read_support_format_all(a);
400 archive_read_open(a, mydata, myopen, myread, myclose);
401 while (archive_read_next_header(a, &entry) == ARCHIVE_OK) {
402 printf("%s\\n",archive_entry_pathname(entry));
403 archive_read_data_skip(a);
405 archive_read_finish(a);
410 myread(struct archive *a, void *client_data, const void **buff)
412 struct mydata *mydata = client_data;
414 *buff = mydata->buff;
415 return (read(mydata->fd, mydata->buff, 10240));
419 myopen(struct archive *a, void *client_data)
421 struct mydata *mydata = client_data;
423 mydata->fd = open(mydata->name, O_RDONLY);
424 return (mydata->fd >= 0 ? ARCHIVE_OK : ARCHIVE_FATAL);
428 myclose(struct archive *a, void *client_data)
430 struct mydata *mydata = client_data;
438 Most functions return zero on success, non-zero on error.
439 The possible return codes include:
441 (the operation succeeded),
443 (the operation succeeded but a non-critical error was encountered),
445 (end-of-archive was encountered),
447 (the operation failed but can be retried),
450 (there was a fatal error; the archive should be closed immediately).
451 Detailed error codes and textual descriptions are available from the
454 .Fn archive_error_string
458 returns a pointer to a freshly allocated
465 .Fn archive_read_data
466 returns a count of bytes actually read or zero at the end of the entry.
472 is returned and an error code and textual description can be retrieved from the
475 .Fn archive_error_string
478 The library expects the client callbacks to behave similarly.
479 If there is an error, you can use
480 .Fn archive_set_error
481 to set an appropriate error code and description,
482 then return one of the non-zero values above.
483 (Note that the value eventually returned to the client may
484 not be the same; many errors that are not critical at the level
485 of basic I/O can prevent the archive from being properly read,
486 thus most I/O errors eventually cause
498 library first appeared in
504 library was written by
505 .An Tim Kientzle Aq kientzle@acm.org .
507 Many traditional archiver programs treat
508 empty files as valid empty archives.
509 For example, many implementations of
511 allow you to append entries to an empty file.
512 Of course, it is impossible to determine the format of an empty file
513 by inspecting the contents, so this library treats empty files as