1 .TH archive_read 3 "August 19, 2006" ""
3 \fBarchive_read_new\fP,
4 \fBarchive_read_support_compression_all\fP,
5 \fBarchive_read_support_compression_bzip2\fP,
6 \fBarchive_read_support_compression_compress\fP,
7 \fBarchive_read_support_compression_gzip\fP,
8 \fBarchive_read_support_compression_none\fP,
9 \fBarchive_read_support_compression_program\fP,
10 \fBarchive_read_support_format_all\fP,
11 \fBarchive_read_support_format_cpio\fP,
12 \fBarchive_read_support_format_empty\fP,
13 \fBarchive_read_support_format_iso9660\fP,
14 \fBarchive_read_support_format_tar\fP,
15 \fBarchive_read_support_format_zip\fP,
16 \fBarchive_read_open\fP,
17 \fBarchive_read_open2\fP,
18 \fBarchive_read_open_fd\fP,
19 \fBarchive_read_open_FILE\fP,
20 \fBarchive_read_open_filename\fP,
21 \fBarchive_read_open_memory\fP,
22 \fBarchive_read_next_header\fP,
23 \fBarchive_read_data\fP,
24 \fBarchive_read_data_block\fP,
25 \fBarchive_read_data_skip\fP,
26 \fBarchive_read_data_into_buffer\fP,
27 \fBarchive_read_data_into_fd\fP,
28 \fBarchive_read_extract\fP,
29 \fBarchive_read_extract2\fP,
30 \fBarchive_read_extract_set_progress_callback\fP,
31 \fBarchive_read_close\fP,
32 \fBarchive_read_finish\fP
33 \- functions for reading streaming archives
35 \fB#include <archive.h>\fP
37 \fIstruct archive *\fP
40 \fBarchive_read_new\fP
46 \fBarchive_read_support_compression_all\fP
52 \fBarchive_read_support_compression_bzip2\fP
58 \fBarchive_read_support_compression_compress\fP
64 \fBarchive_read_support_compression_gzip\fP
70 \fBarchive_read_support_compression_none\fP
75 Fo archive_read_support_compression_program
82 \fBarchive_read_support_format_all\fP
88 \fBarchive_read_support_format_cpio\fP
94 \fBarchive_read_support_format_empty\fP
100 \fBarchive_read_support_format_iso9660\fP
102 ("struct archive *");
106 \fBarchive_read_support_format_tar\fP
108 ("struct archive *");
112 \fBarchive_read_support_format_zip\fP
114 ("struct archive *");
118 Fa "struct archive *"
119 Fa "void *client_data"
120 Fa "archive_open_callback *"
121 Fa "archive_read_callback *"
122 Fa "archive_close_callback *"
126 Fo archive_read_open2
127 Fa "struct archive *"
128 Fa "void *client_data"
129 Fa "archive_open_callback *"
130 Fa "archive_read_callback *"
131 Fa "archive_skip_callback *"
132 Fa "archive_close_callback *"
137 \fBarchive_read_open_FILE\fP
139 ("struct archive *" "FILE *file");
143 \fBarchive_read_open_fd\fP
145 ("struct archive *" "int fd" "size_t block_size");
148 Fo archive_read_open_filename
149 Fa "struct archive *"
150 Fa "const char *filename"
151 Fa "size_t block_size"
156 \fBarchive_read_open_memory\fP
158 ("struct archive *" "void *buff" "size_t size");
162 \fBarchive_read_next_header\fP
164 ("struct archive *" "struct archive_entry **");
168 \fBarchive_read_data\fP
170 ("struct archive *" "void *buff" "size_t len");
173 Fo archive_read_data_block
174 Fa "struct archive *"
175 Fa "const void **buff"
182 \fBarchive_read_data_skip\fP
184 ("struct archive *");
188 \fBarchive_read_data_into_buffer\fP
190 ("struct archive *" "void *" "ssize_t len");
194 \fBarchive_read_data_into_fd\fP
196 ("struct archive *" "int fd");
199 Fo archive_read_extract
200 Fa "struct archive *"
201 Fa "struct archive_entry *"
206 Fo archive_read_extract2
207 Fa "struct archive *src"
208 Fa "struct archive_entry *"
209 Fa "struct archive *dest"
213 Fo archive_read_extract_set_progress_callback
214 Fa "struct archive *"
215 Fa "void (*func)(void *)"
221 \fBarchive_read_close\fP
223 ("struct archive *");
227 \fBarchive_read_finish\fP
229 ("struct archive *");
231 These functions provide a complete API for reading streaming archives.
232 The general process is to first create the
234 object, set options, initialize the reader, iterate over the archive
235 headers and associated data, then close the archive and release all
237 The following summary describes the functions in approximately the
238 order they would be used:
241 \fBarchive_read_new\fP
244 Allocates and initializes a
246 object suitable for reading from an archive.
250 \fBarchive_read_support_compression_all\fP
254 \fBarchive_read_support_compression_bzip2\fP
258 \fBarchive_read_support_compression_compress\fP
262 \fBarchive_read_support_compression_gzip\fP
266 \fBarchive_read_support_compression_none\fP
270 Enables auto-detection code and decompression support for the
271 specified compression.
274 is always enabled by default.
277 \fBarchive_read_support_compression_all\fP
280 enables all available decompression code.
283 \fBarchive_read_support_compression_program\fP
286 Data is fed through the specified external program before being dearchived.
287 Note that this disables automatic detection of the compression format,
288 so it makes no sense to specify this in conjunction with any other
289 decompression option.
293 \fBarchive_read_support_format_all\fP
297 \fBarchive_read_support_format_cpio\fP
301 \fBarchive_read_support_format_empty\fP
305 \fBarchive_read_support_format_iso9660\fP
309 \fBarchive_read_support_format_tar\fP
313 \fBarchive_read_support_format_zip\fP
317 Enables support---including auto-detection code---for the
318 specified archive format.
321 \fBarchive_read_support_format_tar\fP
324 enables support for a variety of standard tar formats, old-style tar,
325 ustar, pax interchange format, and many common variants.
328 \fBarchive_read_support_format_all\fP
331 enables support for all available formats.
332 Only empty archives are supported by default.
335 \fBarchive_read_open\fP
340 \fBarchive_read_open2\fP
343 except that the skip callback is assumed to be
347 \fBarchive_read_open2\fP
350 Freeze the settings, open the archive, and prepare for reading entries.
351 This is the most generic version of this call, which accepts
352 four callback functions.
353 Most clients will want to use
355 \fBarchive_read_open_filename\fP
359 \fBarchive_read_open_FILE\fP
363 \fBarchive_read_open_fd\fP
368 \fBarchive_read_open_memory\fP
372 The library invokes the client-provided functions to obtain
373 raw bytes from the archive.
376 \fBarchive_read_open_FILE\fP
381 \fBarchive_read_open\fP
384 except that it accepts a
388 This function should not be used with tape drives or other devices
389 that require strict I/O blocking.
392 \fBarchive_read_open_fd\fP
397 \fBarchive_read_open\fP
400 except that it accepts a file descriptor and block size rather than
401 a set of function pointers.
402 Note that the file descriptor will not be automatically closed at
404 This function is safe for use with tape drives or other blocked devices.
407 \fBarchive_read_open_file\fP
410 This is a deprecated synonym for
412 \fBarchive_read_open_filename\fP
417 \fBarchive_read_open_filename\fP
422 \fBarchive_read_open\fP
425 except that it accepts a simple filename and a block size.
426 A NULL filename represents standard input.
427 This function is safe for use with tape drives or other blocked devices.
430 \fBarchive_read_open_memory\fP
435 \fBarchive_read_open\fP
438 except that it accepts a pointer and size of a block of
439 memory containing the archive data.
442 \fBarchive_read_next_header\fP
445 Read the header for the next entry and return a pointer to
447 Tn struct archive_entry.
450 \fBarchive_read_data\fP
453 Read data associated with the header just read.
454 Internally, this is a convenience function that calls
456 \fBarchive_read_data_block\fP
459 and fills any gaps with nulls so that callers see a single
460 continuous stream of data.
463 \fBarchive_read_data_block\fP
466 Return the next available block of data for this entry.
469 \fBarchive_read_data\fP
474 \fBarchive_read_data_block\fP
477 function avoids copying data and allows you to correctly handle
478 sparse files, as supported by some archive formats.
479 The library guarantees that offsets will increase and that blocks
481 Note that the blocks returned from this function can be much larger
482 than the block size read from disk, due to compression
483 and internal buffer optimizations.
486 \fBarchive_read_data_skip\fP
489 A convenience function that repeatedly calls
491 \fBarchive_read_data_block\fP
494 to skip all of the data for this archive entry.
497 \fBarchive_read_data_into_buffer\fP
500 This function is deprecated and will be removed.
503 \fBarchive_read_data\fP
509 \fBarchive_read_data_into_fd\fP
512 A convenience function that repeatedly calls
514 \fBarchive_read_data_block\fP
517 to copy the entire entry to the provided file descriptor.
520 \fBarchive_read_extract\fP
523 \fBarchive_read_extract_set_skip_file\fP
526 A convenience function that wraps the corresponding
527 \fBarchive_write_disk\fP(3)
531 \fBarchive_read_extract\fP
534 creates a restore object using
535 \fBarchive_write_disk_new\fP(3)
537 \fBarchive_write_disk_set_standard_lookup\fP(3),
538 then transparently invokes
539 \fBarchive_write_disk_set_options\fP(3),
540 \fBarchive_write_header\fP(3),
541 \fBarchive_write_data\fP(3),
543 \fBarchive_write_finish_entry\fP(3)
544 to create the entry on disk and copy data into it.
547 argument is passed unmodified to
548 \fBarchive_write_disk_set_options\fP(3).
551 \fBarchive_read_extract2\fP
554 This is another version of
556 \fBarchive_read_extract\fP
559 that allows you to provide your own restore object.
560 In particular, this allows you to override the standard lookup functions
562 \fBarchive_write_disk_set_group_lookup\fP(3),
564 \fBarchive_write_disk_set_user_lookup\fP(3).
567 \fBarchive_read_extract2\fP
572 argument; you should use
574 \fBarchive_write_disk_set_options\fP
577 to set the restore options yourself.
580 \fBarchive_read_extract_set_progress_callback\fP
583 Sets a pointer to a user-defined callback that can be used
584 for updating progress displays during extraction.
585 The progress function will be invoked during the extraction of large
587 The progress function will be invoked with the pointer provided to this call.
588 Generally, the data pointed to should include a reference to the archive
589 object and the archive_entry object so that various statistics
590 can be retrieved for the progress display.
593 \fBarchive_read_close\fP
596 Complete the archive and invoke the close callback.
599 \fBarchive_read_finish\fP
604 \fBarchive_read_close\fP
607 if it was not invoked manually, then release all resources.
608 Note: In libarchive 1.x, this function was declared to return
611 which made it impossible to detect certain errors when
613 \fBarchive_read_close\fP
616 was invoked implicitly from this function.
617 The declaration is corrected beginning with libarchive 2.0.
618 Note that the library determines most of the relevant information about
619 the archive by inspection.
620 In particular, it automatically detects
624 compression and transparently performs the appropriate decompression.
625 It also automatically detects the archive format.
626 A complete description of the
629 Tn struct archive_entry
630 objects can be found in the overview manual page for
633 The callback functions must match the following prototypes:
635 \fItypedef ssize_t\fP
637 Fo archive_read_callback
638 Fa "struct archive *"
639 Fa "void *client_data"
640 Fa "const void **buffer"
645 Fo archive_skip_callback
646 Fa "struct archive *"
647 Fa "void *client_data"
654 \fBarchive_open_callback\fP
656 ("struct archive *" "void *client_data");
661 \fBarchive_close_callback\fP
663 ("struct archive *" "void *client_data");
664 The open callback is invoked by
671 if the underlying file or data source is successfully
673 If the open fails, it should call
675 \fBarchive_set_error\fP
678 to register an error code and message and return
680 The read callback is invoked whenever the library
681 requires raw bytes from the archive.
682 The read callback should read data into a buffer,
687 argument to point to the available data, and
688 return a count of the number of bytes available.
689 The library will invoke the read callback again
690 only after it has consumed this data.
691 The library imposes no constraints on the size
692 of the data blocks returned.
693 On end-of-file, the read callback should
695 On error, the read callback should invoke
697 \fBarchive_set_error\fP
700 to register an error code and message and
702 The skip callback is invoked when the
703 library wants to ignore a block of data.
704 The return value is the number of bytes actually
705 skipped, which may differ from the request.
706 If the callback cannot skip data, it should return
708 If the skip callback is not provided (the
711 the library will invoke the read function
712 instead and simply discard the result.
713 A skip callback can provide significant
714 performance gains when reading uncompressed
715 archives from slow disk drives or other media
716 that can skip quickly.
717 The close callback is invoked by archive_close when
718 the archive processing is complete.
719 The callback should return
722 On failure, the callback should invoke
724 \fBarchive_set_error\fP
727 to register an error code and message and
731 The following illustrates basic usage of the library.
733 the callback functions are simply wrappers around the standard
741 list_archive(const char *name)
743 struct mydata *mydata;
745 struct archive_entry *entry;
746 mydata = malloc(sizeof(struct mydata));
747 a = archive_read_new();
749 archive_read_support_compression_all(a);
750 archive_read_support_format_all(a);
751 archive_read_open(a, mydata, myopen, myread, myclose);
752 while (archive_read_next_header(a, &entry) == ARCHIVE_OK) {
753 printf("%s\\n",archive_entry_pathname(entry));
754 archive_read_data_skip(a);
756 archive_read_finish(a);
760 myread(struct archive *a, void *client_data, const void **buff)
762 struct mydata *mydata = client_data;
763 *buff = mydata->buff;
764 return (read(mydata->fd, mydata->buff, 10240));
767 myopen(struct archive *a, void *client_data)
769 struct mydata *mydata = client_data;
770 mydata->fd = open(mydata->name, O_RDONLY);
771 return (mydata->fd >= 0 ? ARCHIVE_OK : ARCHIVE_FATAL);
774 myclose(struct archive *a, void *client_data)
776 struct mydata *mydata = client_data;
783 Most functions return zero on success, non-zero on error.
784 The possible return codes include:
786 (the operation succeeded),
788 (the operation succeeded but a non-critical error was encountered),
790 (end-of-archive was encountered),
792 (the operation failed but can be retried),
795 (there was a fatal error; the archive should be closed immediately).
796 Detailed error codes and textual descriptions are available from the
803 \fBarchive_error_string\fP
808 \fBarchive_read_new\fP
811 returns a pointer to a freshly allocated
818 \fBarchive_read_data\fP
821 returns a count of bytes actually read or zero at the end of the entry.
827 is returned and an error code and textual description can be retrieved from the
834 \fBarchive_error_string\fP
838 The library expects the client callbacks to behave similarly.
839 If there is an error, you can use
841 \fBarchive_set_error\fP
844 to set an appropriate error code and description,
845 then return one of the non-zero values above.
846 (Note that the value eventually returned to the client may
847 not be the same; many errors that are not critical at the level
848 of basic I/O can prevent the archive from being properly read,
849 thus most I/O errors eventually cause
855 \fBarchive_util\fP(3),
860 library first appeared in
866 library was written by
867 Tim Kientzle <kientzle@acm.org.>
869 Many traditional archiver programs treat
870 empty files as valid empty archives.
871 For example, many implementations of
873 allow you to append entries to an empty file.
874 Of course, it is impossible to determine the format of an empty file
875 by inspecting the contents, so this library treats empty files as