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.37 2008/05/26 17:00:22 kientzle Exp $
31 .Nm archive_read_new ,
32 .Nm archive_read_set_filter_options ,
33 .Nm archive_read_set_format_options ,
34 .Nm archive_read_set_options ,
35 .Nm archive_read_support_compression_all ,
36 .Nm archive_read_support_compression_bzip2 ,
37 .Nm archive_read_support_compression_compress ,
38 .Nm archive_read_support_compression_gzip ,
39 .Nm archive_read_support_compression_none ,
40 .Nm archive_read_support_compression_program ,
41 .Nm archive_read_support_format_all ,
42 .Nm archive_read_support_format_cpio ,
43 .Nm archive_read_support_format_empty ,
44 .Nm archive_read_support_format_iso9660 ,
45 .Nm archive_read_support_format_tar ,
46 .Nm archive_read_support_format_zip ,
47 .Nm archive_read_open ,
48 .Nm archive_read_open2 ,
49 .Nm archive_read_open_fd ,
50 .Nm archive_read_open_FILE ,
51 .Nm archive_read_open_filename ,
52 .Nm archive_read_open_memory ,
53 .Nm archive_read_next_header ,
54 .Nm archive_read_next_header2 ,
55 .Nm archive_read_data ,
56 .Nm archive_read_data_block ,
57 .Nm archive_read_data_skip ,
58 .\" #if ARCHIVE_API_VERSION < 3
59 .Nm archive_read_data_into_buffer ,
61 .Nm archive_read_data_into_fd ,
62 .Nm archive_read_extract ,
63 .Nm archive_read_extract2 ,
64 .Nm archive_read_extract_set_progress_callback ,
65 .Nm archive_read_close ,
66 .Nm archive_read_finish
67 .Nd functions for reading streaming archives
71 .Fn archive_read_new "void"
73 .Fn archive_read_support_compression_all "struct archive *"
75 .Fn archive_read_support_compression_bzip2 "struct archive *"
77 .Fn archive_read_support_compression_compress "struct archive *"
79 .Fn archive_read_support_compression_gzip "struct archive *"
81 .Fn archive_read_support_compression_none "struct archive *"
83 .Fo archive_read_support_compression_program
84 .Fa "struct archive *"
88 .Fn archive_read_support_format_all "struct archive *"
90 .Fn archive_read_support_format_cpio "struct archive *"
92 .Fn archive_read_support_format_empty "struct archive *"
94 .Fn archive_read_support_format_iso9660 "struct archive *"
96 .Fn archive_read_support_format_tar "struct archive *"
98 .Fn archive_read_support_format_zip "struct archive *"
100 .Fn archive_read_set_filter_options "struct archive *" "const char *"
102 .Fn archive_read_set_format_options "struct archive *" "const char *"
104 .Fn archive_read_set_options "struct archive *" "const char *"
106 .Fo archive_read_open
107 .Fa "struct archive *"
108 .Fa "void *client_data"
109 .Fa "archive_open_callback *"
110 .Fa "archive_read_callback *"
111 .Fa "archive_close_callback *"
114 .Fo archive_read_open2
115 .Fa "struct archive *"
116 .Fa "void *client_data"
117 .Fa "archive_open_callback *"
118 .Fa "archive_read_callback *"
119 .Fa "archive_skip_callback *"
120 .Fa "archive_close_callback *"
123 .Fn archive_read_open_FILE "struct archive *" "FILE *file"
125 .Fn archive_read_open_fd "struct archive *" "int fd" "size_t block_size"
127 .Fo archive_read_open_filename
128 .Fa "struct archive *"
129 .Fa "const char *filename"
130 .Fa "size_t block_size"
133 .Fn archive_read_open_memory "struct archive *" "void *buff" "size_t size"
135 .Fn archive_read_next_header "struct archive *" "struct archive_entry **"
137 .Fn archive_read_next_header2 "struct archive *" "struct archive_entry *"
139 .Fn archive_read_data "struct archive *" "void *buff" "size_t len"
141 .Fo archive_read_data_block
142 .Fa "struct archive *"
143 .Fa "const void **buff"
148 .Fn archive_read_data_skip "struct archive *"
149 .\" #if ARCHIVE_API_VERSION < 3
151 .Fn archive_read_data_into_buffer "struct archive *" "void *" "ssize_t len"
154 .Fn archive_read_data_into_fd "struct archive *" "int fd"
156 .Fo archive_read_extract
157 .Fa "struct archive *"
158 .Fa "struct archive_entry *"
162 .Fo archive_read_extract2
163 .Fa "struct archive *src"
164 .Fa "struct archive_entry *"
165 .Fa "struct archive *dest"
168 .Fo archive_read_extract_set_progress_callback
169 .Fa "struct archive *"
170 .Fa "void (*func)(void *)"
171 .Fa "void *user_data"
174 .Fn archive_read_close "struct archive *"
176 .Fn archive_read_finish "struct archive *"
178 These functions provide a complete API for reading streaming archives.
179 The general process is to first create the
181 object, set options, initialize the reader, iterate over the archive
182 headers and associated data, then close the archive and release all
184 The following summary describes the functions in approximately the
185 order they would be used:
186 .Bl -tag -compact -width indent
187 .It Fn archive_read_new
188 Allocates and initializes a
190 object suitable for reading from an archive.
192 .Fn archive_read_support_compression_all ,
193 .Fn archive_read_support_compression_bzip2 ,
194 .Fn archive_read_support_compression_compress ,
195 .Fn archive_read_support_compression_gzip ,
196 .Fn archive_read_support_compression_none
198 Enables auto-detection code and decompression support for the
199 specified compression.
202 is always enabled by default.
204 .Fn archive_read_support_compression_all
205 enables all available decompression code.
206 .It Fn archive_read_support_compression_program
207 Data is fed through the specified external program before being dearchived.
208 Note that this disables automatic detection of the compression format,
209 so it makes no sense to specify this in conjunction with any other
210 decompression option.
212 .Fn archive_read_support_format_all ,
213 .Fn archive_read_support_format_cpio ,
214 .Fn archive_read_support_format_empty ,
215 .Fn archive_read_support_format_iso9660 ,
216 .Fn archive_read_support_format_tar ,
217 .Fn archive_read_support_format_zip
219 Enables support---including auto-detection code---for the
220 specified archive format.
222 .Fn archive_read_support_format_tar
223 enables support for a variety of standard tar formats, old-style tar,
224 ustar, pax interchange format, and many common variants.
226 .Fn archive_read_support_format_all
227 enables support for all available formats.
228 Only empty archives are supported by default.
230 .Fn archive_read_set_filter_options ,
231 .Fn archive_read_set_format_options ,
232 .Fn archive_read_set_options
234 Specifies options that will be passed to currently-registered
235 filters (including decompression filters) and/or format readers.
236 The argument is a comma-separated list of individual options.
237 Individual options have one of the following forms:
238 .Bl -tag -compact -width indent
240 The option/value pair will be provided to every module.
241 Modules that do not accept an option with this name will ignore it.
243 The option will be provided to every module with a value of
246 The option will be provided to every module with a NULL value.
247 .It Ar module:option=value , Ar module:option , Ar module:!option
248 As above, but the corresponding option and value will be provided
249 only to modules whose name matches
252 The return value will be
254 if any module accepts the option, or
256 if no module accepted the option, or
258 if there was a fatal error while attempting to process the option.
260 The currently supported options are:
261 .Bl -tag -compact -width indent
263 .Bl -tag -compact -width indent
265 Support Joliet extensions.
266 Defaults to enabled, use
271 .It Fn archive_read_open
273 .Fn archive_read_open2 ,
274 except that the skip callback is assumed to be
276 .It Fn archive_read_open2
277 Freeze the settings, open the archive, and prepare for reading entries.
278 This is the most generic version of this call, which accepts
279 four callback functions.
280 Most clients will want to use
281 .Fn archive_read_open_filename ,
282 .Fn archive_read_open_FILE ,
283 .Fn archive_read_open_fd ,
285 .Fn archive_read_open_memory
287 The library invokes the client-provided functions to obtain
288 raw bytes from the archive.
289 .It Fn archive_read_open_FILE
291 .Fn archive_read_open ,
292 except that it accepts a
295 This function should not be used with tape drives or other devices
296 that require strict I/O blocking.
297 .It Fn archive_read_open_fd
299 .Fn archive_read_open ,
300 except that it accepts a file descriptor and block size rather than
301 a set of function pointers.
302 Note that the file descriptor will not be automatically closed at
304 This function is safe for use with tape drives or other blocked devices.
305 .It Fn archive_read_open_file
306 This is a deprecated synonym for
307 .Fn archive_read_open_filename .
308 .It Fn archive_read_open_filename
310 .Fn archive_read_open ,
311 except that it accepts a simple filename and a block size.
312 A NULL filename represents standard input.
313 This function is safe for use with tape drives or other blocked devices.
314 .It Fn archive_read_open_memory
316 .Fn archive_read_open ,
317 except that it accepts a pointer and size of a block of
318 memory containing the archive data.
319 .It Fn archive_read_next_header
320 Read the header for the next entry and return a pointer to
322 .Tn struct archive_entry .
323 This is a convenience wrapper around
324 .Fn archive_read_next_header2
325 that uses an internal
326 .Tn struct archive_entry
328 .It Fn archive_read_next_header2
329 Read the header for the next entry and populate the provided
330 .Tn struct archive_entry .
331 .It Fn archive_read_data
332 Read data associated with the header just read.
333 Internally, this is a convenience function that calls
334 .Fn archive_read_data_block
335 and fills any gaps with nulls so that callers see a single
336 continuous stream of data.
337 .It Fn archive_read_data_block
338 Return the next available block of data for this entry.
340 .Fn archive_read_data ,
342 .Fn archive_read_data_block
343 function avoids copying data and allows you to correctly handle
344 sparse files, as supported by some archive formats.
345 The library guarantees that offsets will increase and that blocks
347 Note that the blocks returned from this function can be much larger
348 than the block size read from disk, due to compression
349 and internal buffer optimizations.
350 .It Fn archive_read_data_skip
351 A convenience function that repeatedly calls
352 .Fn archive_read_data_block
353 to skip all of the data for this archive entry.
354 .\" #if ARCHIVE_API_VERSION < 3
355 .It Fn archive_read_data_into_buffer
356 This function is deprecated and will be removed.
358 .Fn archive_read_data
361 .It Fn archive_read_data_into_fd
362 A convenience function that repeatedly calls
363 .Fn archive_read_data_block
364 to copy the entire entry to the provided file descriptor.
365 .It Fn archive_read_extract , Fn archive_read_extract_set_skip_file
366 A convenience function that wraps the corresponding
367 .Xr archive_write_disk 3
370 .Fn archive_read_extract
371 creates a restore object using
372 .Xr archive_write_disk_new 3
374 .Xr archive_write_disk_set_standard_lookup 3 ,
375 then transparently invokes
376 .Xr archive_write_disk_set_options 3 ,
377 .Xr archive_write_header 3 ,
378 .Xr archive_write_data 3 ,
380 .Xr archive_write_finish_entry 3
381 to create the entry on disk and copy data into it.
384 argument is passed unmodified to
385 .Xr archive_write_disk_set_options 3 .
386 .It Fn archive_read_extract2
387 This is another version of
388 .Fn archive_read_extract
389 that allows you to provide your own restore object.
390 In particular, this allows you to override the standard lookup functions
392 .Xr archive_write_disk_set_group_lookup 3 ,
394 .Xr archive_write_disk_set_user_lookup 3 .
396 .Fn archive_read_extract2
399 argument; you should use
400 .Fn archive_write_disk_set_options
401 to set the restore options yourself.
402 .It Fn archive_read_extract_set_progress_callback
403 Sets a pointer to a user-defined callback that can be used
404 for updating progress displays during extraction.
405 The progress function will be invoked during the extraction of large
407 The progress function will be invoked with the pointer provided to this call.
408 Generally, the data pointed to should include a reference to the archive
409 object and the archive_entry object so that various statistics
410 can be retrieved for the progress display.
411 .It Fn archive_read_close
412 Complete the archive and invoke the close callback.
413 .It Fn archive_read_finish
415 .Fn archive_read_close
416 if it was not invoked manually, then release all resources.
417 Note: In libarchive 1.x, this function was declared to return
419 which made it impossible to detect certain errors when
420 .Fn archive_read_close
421 was invoked implicitly from this function.
422 The declaration is corrected beginning with libarchive 2.0.
425 Note that the library determines most of the relevant information about
426 the archive by inspection.
427 In particular, it automatically detects
431 compression and transparently performs the appropriate decompression.
432 It also automatically detects the archive format.
434 A complete description of the
437 .Tn struct archive_entry
438 objects can be found in the overview manual page for
441 The callback functions must match the following prototypes:
442 .Bl -item -offset indent
445 .Fo archive_read_callback
446 .Fa "struct archive *"
447 .Fa "void *client_data"
448 .Fa "const void **buffer"
451 .\" #if ARCHIVE_API_VERSION < 2
453 .Fo archive_skip_callback
454 .Fa "struct archive *"
455 .Fa "void *client_data"
459 .\" .Ft typedef off_t
460 .\" .Fo archive_skip_callback
461 .\" .Fa "struct archive *"
462 .\" .Fa "void *client_data"
463 .\" .Fa "off_t request"
468 .Fn archive_open_callback "struct archive *" "void *client_data"
471 .Fn archive_close_callback "struct archive *" "void *client_data"
474 The open callback is invoked by
478 if the underlying file or data source is successfully
480 If the open fails, it should call
481 .Fn archive_set_error
482 to register an error code and message and return
485 The read callback is invoked whenever the library
486 requires raw bytes from the archive.
487 The read callback should read data into a buffer,
489 .Li const void **buffer
490 argument to point to the available data, and
491 return a count of the number of bytes available.
492 The library will invoke the read callback again
493 only after it has consumed this data.
494 The library imposes no constraints on the size
495 of the data blocks returned.
496 On end-of-file, the read callback should
498 On error, the read callback should invoke
499 .Fn archive_set_error
500 to register an error code and message and
503 The skip callback is invoked when the
504 library wants to ignore a block of data.
505 The return value is the number of bytes actually
506 skipped, which may differ from the request.
507 If the callback cannot skip data, it should return
509 If the skip callback is not provided (the
512 the library will invoke the read function
513 instead and simply discard the result.
514 A skip callback can provide significant
515 performance gains when reading uncompressed
516 archives from slow disk drives or other media
517 that can skip quickly.
519 The close callback is invoked by archive_close when
520 the archive processing is complete.
521 The callback should return
524 On failure, the callback should invoke
525 .Fn archive_set_error
526 to register an error code and message and
530 The following illustrates basic usage of the library.
532 the callback functions are simply wrappers around the standard
538 .Bd -literal -offset indent
540 list_archive(const char *name)
542 struct mydata *mydata;
544 struct archive_entry *entry;
546 mydata = malloc(sizeof(struct mydata));
547 a = archive_read_new();
549 archive_read_support_compression_all(a);
550 archive_read_support_format_all(a);
551 archive_read_open(a, mydata, myopen, myread, myclose);
552 while (archive_read_next_header(a, &entry) == ARCHIVE_OK) {
553 printf("%s\\n",archive_entry_pathname(entry));
554 archive_read_data_skip(a);
556 archive_read_finish(a);
561 myread(struct archive *a, void *client_data, const void **buff)
563 struct mydata *mydata = client_data;
565 *buff = mydata->buff;
566 return (read(mydata->fd, mydata->buff, 10240));
570 myopen(struct archive *a, void *client_data)
572 struct mydata *mydata = client_data;
574 mydata->fd = open(mydata->name, O_RDONLY);
575 return (mydata->fd >= 0 ? ARCHIVE_OK : ARCHIVE_FATAL);
579 myclose(struct archive *a, void *client_data)
581 struct mydata *mydata = client_data;
589 Most functions return zero on success, non-zero on error.
590 The possible return codes include:
592 (the operation succeeded),
594 (the operation succeeded but a non-critical error was encountered),
596 (end-of-archive was encountered),
598 (the operation failed but can be retried),
601 (there was a fatal error; the archive should be closed immediately).
602 Detailed error codes and textual descriptions are available from the
605 .Fn archive_error_string
609 returns a pointer to a freshly allocated
616 .Fn archive_read_data
617 returns a count of bytes actually read or zero at the end of the entry.
623 is returned and an error code and textual description can be retrieved from the
626 .Fn archive_error_string
629 The library expects the client callbacks to behave similarly.
630 If there is an error, you can use
631 .Fn archive_set_error
632 to set an appropriate error code and description,
633 then return one of the non-zero values above.
634 (Note that the value eventually returned to the client may
635 not be the same; many errors that are not critical at the level
636 of basic I/O can prevent the archive from being properly read,
637 thus most I/O errors eventually cause
649 library first appeared in
655 library was written by
656 .An Tim Kientzle Aq kientzle@acm.org .
658 Many traditional archiver programs treat
659 empty files as valid empty archives.
660 For example, many implementations of
662 allow you to append entries to an empty file.
663 Of course, it is impossible to determine the format of an empty file
664 by inspecting the contents, so this library treats empty files as