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_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_compression_program ,
38 .Nm archive_read_support_format_all ,
39 .Nm archive_read_support_format_cpio ,
40 .Nm archive_read_support_format_empty ,
41 .Nm archive_read_support_format_iso9660 ,
42 .Nm archive_read_support_format_tar ,
43 .Nm archive_read_support_format_zip ,
44 .Nm archive_read_open ,
45 .Nm archive_read_open2 ,
46 .Nm archive_read_open_fd ,
47 .Nm archive_read_open_FILE ,
48 .Nm archive_read_open_filename ,
49 .Nm archive_read_open_memory ,
50 .Nm archive_read_next_header ,
51 .Nm archive_read_data ,
52 .Nm archive_read_data_block ,
53 .Nm archive_read_data_skip ,
54 .\" #if ARCHIVE_API_VERSION < 3
55 .Nm archive_read_data_into_buffer ,
57 .Nm archive_read_data_into_fd ,
58 .Nm archive_read_extract ,
59 .Nm archive_read_extract2 ,
60 .Nm archive_read_extract_set_progress_callback ,
61 .Nm archive_read_close ,
62 .Nm archive_read_finish
63 .Nd functions for reading streaming archives
67 .Fn archive_read_new "void"
69 .Fn archive_read_support_compression_all "struct archive *"
71 .Fn archive_read_support_compression_bzip2 "struct archive *"
73 .Fn archive_read_support_compression_compress "struct archive *"
75 .Fn archive_read_support_compression_gzip "struct archive *"
77 .Fn archive_read_support_compression_none "struct archive *"
79 .Fo archive_read_support_compression_program
80 .Fa "struct archive *"
84 .Fn archive_read_support_format_all "struct archive *"
86 .Fn archive_read_support_format_cpio "struct archive *"
88 .Fn archive_read_support_format_empty "struct archive *"
90 .Fn archive_read_support_format_iso9660 "struct archive *"
92 .Fn archive_read_support_format_tar "struct archive *"
94 .Fn archive_read_support_format_zip "struct archive *"
97 .Fa "struct archive *"
98 .Fa "void *client_data"
99 .Fa "archive_open_callback *"
100 .Fa "archive_read_callback *"
101 .Fa "archive_close_callback *"
104 .Fo archive_read_open2
105 .Fa "struct archive *"
106 .Fa "void *client_data"
107 .Fa "archive_open_callback *"
108 .Fa "archive_read_callback *"
109 .Fa "archive_skip_callback *"
110 .Fa "archive_close_callback *"
113 .Fn archive_read_open_FILE "struct archive *" "FILE *file"
115 .Fn archive_read_open_fd "struct archive *" "int fd" "size_t block_size"
117 .Fo archive_read_open_filename
118 .Fa "struct archive *"
119 .Fa "const char *filename"
120 .Fa "size_t block_size"
123 .Fn archive_read_open_memory "struct archive *" "void *buff" "size_t size"
125 .Fn archive_read_next_header "struct archive *" "struct archive_entry **"
127 .Fn archive_read_data "struct archive *" "void *buff" "size_t len"
129 .Fo archive_read_data_block
130 .Fa "struct archive *"
131 .Fa "const void **buff"
136 .Fn archive_read_data_skip "struct archive *"
137 .\" #if ARCHIVE_API_VERSION < 3
139 .Fn archive_read_data_into_buffer "struct archive *" "void *" "ssize_t len"
142 .Fn archive_read_data_into_fd "struct archive *" "int fd"
144 .Fo archive_read_extract
145 .Fa "struct archive *"
146 .Fa "struct archive_entry *"
150 .Fo archive_read_extract2
151 .Fa "struct archive *src"
152 .Fa "struct archive_entry *"
153 .Fa "struct archive *dest"
156 .Fo archive_read_extract_set_progress_callback
157 .Fa "struct archive *"
158 .Fa "void (*func)(void *)"
159 .Fa "void *user_data"
162 .Fn archive_read_close "struct archive *"
164 .Fn archive_read_finish "struct archive *"
166 These functions provide a complete API for reading streaming archives.
167 The general process is to first create the
169 object, set options, initialize the reader, iterate over the archive
170 headers and associated data, then close the archive and release all
172 The following summary describes the functions in approximately the
173 order they would be used:
174 .Bl -tag -compact -width indent
175 .It Fn archive_read_new
176 Allocates and initializes a
178 object suitable for reading from an archive.
180 .Fn archive_read_support_compression_all ,
181 .Fn archive_read_support_compression_bzip2 ,
182 .Fn archive_read_support_compression_compress ,
183 .Fn archive_read_support_compression_gzip ,
184 .Fn archive_read_support_compression_none
186 Enables auto-detection code and decompression support for the
187 specified compression.
190 is always enabled by default.
192 .Fn archive_read_support_compression_all
193 enables all available decompression code.
194 .It Fn archive_read_support_compression_program
195 Data is fed through the specified external program before being dearchived.
196 Note that this disables automatic detection of the compression format,
197 so it makes no sense to specify this in conjunction with any other
198 decompression option.
200 .Fn archive_read_support_format_all ,
201 .Fn archive_read_support_format_cpio ,
202 .Fn archive_read_support_format_empty ,
203 .Fn archive_read_support_format_iso9660 ,
204 .Fn archive_read_support_format_tar ,
205 .Fn archive_read_support_format_zip
207 Enables support---including auto-detection code---for the
208 specified archive format.
210 .Fn archive_read_support_format_tar
211 enables support for a variety of standard tar formats, old-style tar,
212 ustar, pax interchange format, and many common variants.
214 .Fn archive_read_support_format_all
215 enables support for all available formats.
216 Only empty archives are supported by default.
217 .It Fn archive_read_open
219 .Fn archive_read_open2 ,
220 except that the skip callback is assumed to be
222 .It Fn archive_read_open2
223 Freeze the settings, open the archive, and prepare for reading entries.
224 This is the most generic version of this call, which accepts
225 four callback functions.
226 Most clients will want to use
227 .Fn archive_read_open_filename ,
228 .Fn archive_read_open_FILE ,
229 .Fn archive_read_open_fd ,
231 .Fn archive_read_open_memory
233 The library invokes the client-provided functions to obtain
234 raw bytes from the archive.
235 .It Fn archive_read_open_FILE
237 .Fn archive_read_open ,
238 except that it accepts a
241 This function should not be used with tape drives or other devices
242 that require strict I/O blocking.
243 .It Fn archive_read_open_fd
245 .Fn archive_read_open ,
246 except that it accepts a file descriptor and block size rather than
247 a set of function pointers.
248 Note that the file descriptor will not be automatically closed at
250 This function is safe for use with tape drives or other blocked devices.
251 .It Fn archive_read_open_file
252 This is a deprecated synonym for
253 .Fn archive_read_open_filename .
254 .It Fn archive_read_open_filename
256 .Fn archive_read_open ,
257 except that it accepts a simple filename and a block size.
258 A NULL filename represents standard input.
259 This function is safe for use with tape drives or other blocked devices.
260 .It Fn archive_read_open_memory
262 .Fn archive_read_open ,
263 except that it accepts a pointer and size of a block of
264 memory containing the archive data.
265 .It Fn archive_read_next_header
266 Read the header for the next entry and return a pointer to
268 .Tn struct archive_entry .
269 .It Fn archive_read_data
270 Read data associated with the header just read.
271 Internally, this is a convenience function that calls
272 .Fn archive_read_data_block
273 and fills any gaps with nulls so that callers see a single
274 continuous stream of data.
275 .It Fn archive_read_data_block
276 Return the next available block of data for this entry.
278 .Fn archive_read_data ,
280 .Fn archive_read_data_block
281 function avoids copying data and allows you to correctly handle
282 sparse files, as supported by some archive formats.
283 The library guarantees that offsets will increase and that blocks
285 Note that the blocks returned from this function can be much larger
286 than the block size read from disk, due to compression
287 and internal buffer optimizations.
288 .It Fn archive_read_data_skip
289 A convenience function that repeatedly calls
290 .Fn archive_read_data_block
291 to skip all of the data for this archive entry.
292 .\" #if ARCHIVE_API_VERSION < 3
293 .It Fn archive_read_data_into_buffer
294 This function is deprecated and will be removed.
296 .Fn archive_read_data
299 .It Fn archive_read_data_into_fd
300 A convenience function that repeatedly calls
301 .Fn archive_read_data_block
302 to copy the entire entry to the provided file descriptor.
303 .It Fn archive_read_extract , Fn archive_read_extract_set_skip_file
304 A convenience function that wraps the corresponding
305 .Xr archive_write_disk 3
308 .Fn archive_read_extract
309 creates a restore object using
310 .Xr archive_write_disk_new 3
312 .Xr archive_write_disk_set_standard_lookup 3 ,
313 then transparently invokes
314 .Xr archive_write_disk_set_options 3 ,
315 .Xr archive_write_header 3 ,
316 .Xr archive_write_data 3 ,
318 .Xr archive_write_finish_entry 3
319 to create the entry on disk and copy data into it.
322 argument is passed unmodified to
323 .Xr archive_write_disk_set_options 3 .
324 .It Fn archive_read_extract2
325 This is another version of
326 .Fn archive_read_extract
327 that allows you to provide your own restore object.
328 In particular, this allows you to override the standard lookup functions
330 .Xr archive_write_disk_set_group_lookup 3 ,
332 .Xr archive_write_disk_set_user_lookup 3 .
334 .Fn archive_read_extract2
337 argument; you should use
338 .Fn archive_write_disk_set_options
339 to set the restore options yourself.
340 .It Fn archive_read_extract_set_progress_callback
341 Sets a pointer to a user-defined callback that can be used
342 for updating progress displays during extraction.
343 The progress function will be invoked during the extraction of large
345 The progress function will be invoked with the pointer provided to this call.
346 Generally, the data pointed to should include a reference to the archive
347 object and the archive_entry object so that various statistics
348 can be retrieved for the progress display.
349 .It Fn archive_read_close
350 Complete the archive and invoke the close callback.
351 .It Fn archive_read_finish
353 .Fn archive_read_close
354 if it was not invoked manually, then release all resources.
355 Note: In libarchive 1.x, this function was declared to return
357 which made it impossible to detect certain errors when
358 .Fn archive_read_close
359 was invoked implicitly from this function.
360 The declaration is corrected beginning with libarchive 2.0.
363 Note that the library determines most of the relevant information about
364 the archive by inspection.
365 In particular, it automatically detects
369 compression and transparently performs the appropriate decompression.
370 It also automatically detects the archive format.
372 A complete description of the
375 .Tn struct archive_entry
376 objects can be found in the overview manual page for
379 The callback functions must match the following prototypes:
380 .Bl -item -offset indent
383 .Fo archive_read_callback
384 .Fa "struct archive *"
385 .Fa "void *client_data"
386 .Fa "const void **buffer"
389 .\" #if ARCHIVE_API_VERSION < 2
391 .Fo archive_skip_callback
392 .Fa "struct archive *"
393 .Fa "void *client_data"
397 .\" .Ft typedef off_t
398 .\" .Fo archive_skip_callback
399 .\" .Fa "struct archive *"
400 .\" .Fa "void *client_data"
401 .\" .Fa "off_t request"
406 .Fn archive_open_callback "struct archive *" "void *client_data"
409 .Fn archive_close_callback "struct archive *" "void *client_data"
412 The open callback is invoked by
416 if the underlying file or data source is successfully
418 If the open fails, it should call
419 .Fn archive_set_error
420 to register an error code and message and return
423 The read callback is invoked whenever the library
424 requires raw bytes from the archive.
425 The read callback should read data into a buffer,
427 .Li const void **buffer
428 argument to point to the available data, and
429 return a count of the number of bytes available.
430 The library will invoke the read callback again
431 only after it has consumed this data.
432 The library imposes no constraints on the size
433 of the data blocks returned.
434 On end-of-file, the read callback should
436 On error, the read callback should invoke
437 .Fn archive_set_error
438 to register an error code and message and
441 The skip callback is invoked when the
442 library wants to ignore a block of data.
443 The return value is the number of bytes actually
444 skipped, which may differ from the request.
445 If the callback cannot skip data, it should return
447 If the skip callback is not provided (the
450 the library will invoke the read function
451 instead and simply discard the result.
452 A skip callback can provide significant
453 performance gains when reading uncompressed
454 archives from slow disk drives or other media
455 that can skip quickly.
457 The close callback is invoked by archive_close when
458 the archive processing is complete.
459 The callback should return
462 On failure, the callback should invoke
463 .Fn archive_set_error
464 to register an error code and message and
468 The following illustrates basic usage of the library.
470 the callback functions are simply wrappers around the standard
476 .Bd -literal -offset indent
478 list_archive(const char *name)
480 struct mydata *mydata;
482 struct archive_entry *entry;
484 mydata = malloc(sizeof(struct mydata));
485 a = archive_read_new();
487 archive_read_support_compression_all(a);
488 archive_read_support_format_all(a);
489 archive_read_open(a, mydata, myopen, myread, myclose);
490 while (archive_read_next_header(a, &entry) == ARCHIVE_OK) {
491 printf("%s\\n",archive_entry_pathname(entry));
492 archive_read_data_skip(a);
494 archive_read_finish(a);
499 myread(struct archive *a, void *client_data, const void **buff)
501 struct mydata *mydata = client_data;
503 *buff = mydata->buff;
504 return (read(mydata->fd, mydata->buff, 10240));
508 myopen(struct archive *a, void *client_data)
510 struct mydata *mydata = client_data;
512 mydata->fd = open(mydata->name, O_RDONLY);
513 return (mydata->fd >= 0 ? ARCHIVE_OK : ARCHIVE_FATAL);
517 myclose(struct archive *a, void *client_data)
519 struct mydata *mydata = client_data;
527 Most functions return zero on success, non-zero on error.
528 The possible return codes include:
530 (the operation succeeded),
532 (the operation succeeded but a non-critical error was encountered),
534 (end-of-archive was encountered),
536 (the operation failed but can be retried),
539 (there was a fatal error; the archive should be closed immediately).
540 Detailed error codes and textual descriptions are available from the
543 .Fn archive_error_string
547 returns a pointer to a freshly allocated
554 .Fn archive_read_data
555 returns a count of bytes actually read or zero at the end of the entry.
561 is returned and an error code and textual description can be retrieved from the
564 .Fn archive_error_string
567 The library expects the client callbacks to behave similarly.
568 If there is an error, you can use
569 .Fn archive_set_error
570 to set an appropriate error code and description,
571 then return one of the non-zero values above.
572 (Note that the value eventually returned to the client may
573 not be the same; many errors that are not critical at the level
574 of basic I/O can prevent the archive from being properly read,
575 thus most I/O errors eventually cause
587 library first appeared in
593 library was written by
594 .An Tim Kientzle Aq kientzle@acm.org .
596 Many traditional archiver programs treat
597 empty files as valid empty archives.
598 For example, many implementations of
600 allow you to append entries to an empty file.
601 Of course, it is impossible to determine the format of an empty file
602 by inspecting the contents, so this library treats empty files as