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.31 2007/03/03 07:37:36 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 .Nm archive_read_data_into_buffer ,
54 .Nm archive_read_data_into_fd ,
55 .Nm archive_read_extract ,
56 .Nm archive_read_extract_set_progress_callback ,
57 .Nm archive_read_close ,
58 .Nm archive_read_finish
59 .Nd functions for reading streaming archives
63 .Fn archive_read_new "void"
65 .Fn archive_read_support_compression_all "struct archive *"
67 .Fn archive_read_support_compression_bzip2 "struct archive *"
69 .Fn archive_read_support_compression_compress "struct archive *"
71 .Fn archive_read_support_compression_gzip "struct archive *"
73 .Fn archive_read_support_compression_none "struct archive *"
75 .Fn archive_read_support_format_all "struct archive *"
77 .Fn archive_read_support_format_cpio "struct archive *"
79 .Fn archive_read_support_format_empty "struct archive *"
81 .Fn archive_read_support_format_iso9660 "struct archive *"
83 .Fn archive_read_support_format_tar "struct archive *"
85 .Fn archive_read_support_format_zip "struct archive *"
87 .Fn archive_read_open "struct archive *" "void *client_data" "archive_open_callback *" "archive_read_callback *" "archive_close_callback *"
89 .Fn archive_read_open2 "struct archive *" "void *client_data" "archive_open_callback *" "archive_read_callback *" "archive_skip_callback *" "archive_close_callback *"
91 .Fn archive_read_open_FILE "struct archive *" "FILE *file"
93 .Fn archive_read_open_fd "struct archive *" "int fd" "size_t block_size"
95 .Fn archive_read_open_filename "struct archive *" "const char *filename" "size_t block_size"
97 .Fn archive_read_open_memory "struct archive *" "void *buff" "size_t size"
99 .Fn archive_read_next_header "struct archive *" "struct archive_entry **"
101 .Fn archive_read_data "struct archive *" "void *buff" "size_t len"
103 .Fn archive_read_data_block "struct archive *" "const void **buff" "size_t *len" "off_t *offset"
105 .Fn archive_read_data_skip "struct archive *"
107 .Fn archive_read_data_into_buffer "struct archive *" "void *" "ssize_t len"
109 .Fn archive_read_data_into_fd "struct archive *" "int fd"
111 .Fn archive_read_extract "struct archive *" "struct archive_entry *" "int flags"
113 .Fn archive_read_extract_set_progress_callback "struct archive *" "void (*func)(void *)" "void *user_data"
115 .Fn archive_read_close "struct archive *"
117 .Fn archive_read_finish "struct archive *"
119 These functions provide a complete API for reading streaming archives.
120 The general process is to first create the
122 object, set options, initialize the reader, iterate over the archive
123 headers and associated data, then close the archive and release all
125 The following summary describes the functions in approximately the
126 order they would be used:
127 .Bl -tag -compact -width indent
128 .It Fn archive_read_new
129 Allocates and initializes a
131 object suitable for reading from an archive.
132 .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
133 Enables auto-detection code and decompression support for the
134 specified compression.
137 is always enabled by default.
139 .Fn archive_read_support_compression_all
140 enables all available decompression code.
141 .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
142 Enables support---including auto-detection code---for the
143 specified archive format.
145 .Fn archive_read_support_format_tar
146 enables support for a variety of standard tar formats, old-style tar,
147 ustar, pax interchange format, and many common variants.
149 .Fn archive_read_support_format_all
150 enables support for all available formats.
151 Only empty archives are supported by default.
152 .It Fn archive_read_open
154 .Fn archive_read_open2 ,
155 except that the skip callback is assumed to be
157 .It Fn archive_read_open2
158 Freeze the settings, open the archive, and prepare for reading entries.
159 This is the most generic version of this call, which accepts
160 four callback functions.
161 Most clients will want to use
162 .Fn archive_read_open_filename ,
163 .Fn archive_read_open_FILE ,
164 .Fn archive_read_open_fd ,
166 .Fn archive_read_open_memory
168 The library invokes the client-provided functions to obtain
169 raw bytes from the archive.
170 .It Fn archive_read_open_FILE
172 .Fn archive_read_open ,
173 except that it accepts a
176 This function should not be used with tape drives or other devices
177 that require strict I/O blocking.
178 .It Fn archive_read_open_fd
180 .Fn archive_read_open ,
181 except that it accepts a file descriptor and block size rather than
182 a set of function pointers.
183 Note that the file descriptor will not be automatically closed at
185 This function is safe for use with tape drives or other blocked devices.
186 .It Fn archive_read_open_file
187 This is a deprecated synonym for
188 .Fn archive_read_open_filename .
189 .It Fn archive_read_open_filename
191 .Fn archive_read_open ,
192 except that it accepts a simple filename and a block size.
193 A NULL filename represents standard input.
194 This function is safe for use with tape drives or other blocked devices.
195 .It Fn archive_read_open_memory
197 .Fn archive_read_open ,
198 except that it accepts a pointer and size of a block of
199 memory containing the archive data.
200 .It Fn archive_read_next_header
201 Read the header for the next entry and return a pointer to
203 .Tn struct archive_entry .
204 .It Fn archive_read_data
205 Read data associated with the header just read.
206 Internally, this is a convenience function that calls
207 .Fn archive_read_data_block
208 and fills any gaps with nulls so that callers see a single
209 continuous stream of data.
210 .It Fn archive_read_data_block
211 Return the next available block of data for this entry.
213 .Fn archive_read_data ,
215 .Fn archive_read_data_block
216 function avoids copying data and allows you to correctly handle
217 sparse files, as supported by some archive formats.
218 The library guarantees that offsets will increase and that blocks
220 Note that the blocks returned from this function can be much larger
221 than the block size read from disk, due to compression
222 and internal buffer optimizations.
223 .It Fn archive_read_data_skip
224 A convenience function that repeatedly calls
225 .Fn archive_read_data_block
226 to skip all of the data for this archive entry.
227 .It Fn archive_read_data_into_buffer
228 A convenience function that repeatedly calls
229 .Fn archive_read_data_block
230 to copy the entire entry into the client-supplied buffer.
231 Note that the client is responsible for sizing the buffer appropriately.
232 .It Fn archive_read_data_into_fd
233 A convenience function that repeatedly calls
234 .Fn archive_read_data_block
235 to copy the entire entry to the provided file descriptor.
236 .It Fn archive_read_extract , Fn archive_read_extract_set_skip_file
237 A convenience function that wraps the corresponding
238 .Xr archive_write_disk 3
241 .Fn archive_read_extract
242 creates a restore object using
243 .Xr archive_write_disk_new 3
245 .Xr archive_write_disk_set_standard_lookup 3 ,
246 then transparently invokes
247 .Xr archive_write_disk_set_options 3 ,
248 .Xr archive_write_header 3 ,
249 .Xr archive_write_data 3 ,
251 .Xr archive_write_finish_entry 3
252 to create the entry on disk and copy data into it.
255 argument is passed unmodified to
256 .Xr archiv_write_disk_set_options 3 .
257 .It Fn archive_read_extract_set_progress_callback
258 Sets a pointer to a user-defined callback that can be used
259 for updating progress displays during extraction.
260 The progress function will be invoked during the extraction of large
262 The progress function will be invoked with the pointer provided to this call.
263 Generally, the data pointed to should include a reference to the archive
264 object and the archive_entry object so that various statistics
265 can be retrieved for the progress display.
266 .It Fn archive_read_close
267 Complete the archive and invoke the close callback.
268 .It Fn archive_read_finish
270 .Fn archive_read_close
271 if it was not invoked manually, then release all resources.
272 Note: In libarchive 1.x, this function was declared to return
274 which made it impossible to detect certain errors when
275 .Fn archive_read_close
276 was invoked implicitly from this function.
277 The declaration is corrected beginning with libarchive 2.0.
280 Note that the library determines most of the relevant information about
281 the archive by inspection.
282 In particular, it automatically detects
286 compression and transparently performs the appropriate decompression.
287 It also automatically detects the archive format.
289 A complete description of the
292 .Tn struct archive_entry
293 objects can be found in the overview manual page for
296 The callback functions must match the following prototypes:
297 .Bl -item -offset indent
300 .Fn archive_read_callback "struct archive *" "void *client_data" "const void **buffer"
302 .\" #if ARCHIVE_API_VERSION < 2
304 .Fn archive_skip_callback "struct archive *" "void *client_data" "size_t request"
306 .\" .Ft typedef off_t
307 .\" .Fn archive_skip_callback "struct archive *" "void *client_data" "off_t request"
311 .Fn archive_open_callback "struct archive *" "void *client_data"
314 .Fn archive_close_callback "struct archive *" "void *client_data"
317 The open callback is invoked by
321 if the underlying file or data source is successfully
323 If the open fails, it should call
324 .Fn archive_set_error
325 to register an error code and message and return
328 The read callback is invoked whenever the library
329 requires raw bytes from the archive.
330 The read callback should read data into a buffer,
332 .Li const void **buffer
333 argument to point to the available data, and
334 return a count of the number of bytes available.
335 The library will invoke the read callback again
336 only after it has consumed this data.
337 The library imposes no constraints on the size
338 of the data blocks returned.
339 On end-of-file, the read callback should
341 On error, the read callback should invoke
342 .Fn archive_set_error
343 to register an error code and message and
346 The skip callback is invoked when the
347 library wants to ignore a block of data.
348 The return value is the number of bytes actually
349 skipped, which may differ from the request.
350 If the callback cannot skip data, it should return
352 If the skip callback is not provided (the
355 the library will invoke the read function
356 instead and simply discard the result.
357 A skip callback can provide significant
358 performance gains when reading uncompressed
359 archives from slow disk drives or other media
360 that can skip quickly.
362 The close callback is invoked by archive_close when
363 the archive processing is complete.
364 The callback should return
367 On failure, the callback should invoke
368 .Fn archive_set_error
369 to register an error code and message and
373 The following illustrates basic usage of the library.
375 the callback functions are simply wrappers around the standard
381 .Bd -literal -offset indent
383 list_archive(const char *name)
385 struct mydata *mydata;
387 struct archive_entry *entry;
389 mydata = malloc(sizeof(struct mydata));
390 a = archive_read_new();
392 archive_read_support_compression_all(a);
393 archive_read_support_format_all(a);
394 archive_read_open(a, mydata, myopen, myread, myclose);
395 while (archive_read_next_header(a, &entry) == ARCHIVE_OK) {
396 printf("%s\\n",archive_entry_pathname(entry));
397 archive_read_data_skip(a);
399 archive_read_finish(a);
404 myread(struct archive *a, void *client_data, const void **buff)
406 struct mydata *mydata = client_data;
408 *buff = mydata->buff;
409 return (read(mydata->fd, mydata->buff, 10240));
413 myopen(struct archive *a, void *client_data)
415 struct mydata *mydata = client_data;
417 mydata->fd = open(mydata->name, O_RDONLY);
418 return (mydata->fd >= 0 ? ARCHIVE_OK : ARCHIVE_FATAL);
422 myclose(struct archive *a, void *client_data)
424 struct mydata *mydata = client_data;
432 Most functions return zero on success, non-zero on error.
433 The possible return codes include:
435 (the operation succeeded),
437 (the operation succeeded but a non-critical error was encountered),
439 (end-of-archive was encountered),
441 (the operation failed but can be retried),
444 (there was a fatal error; the archive should be closed immediately).
445 Detailed error codes and textual descriptions are available from the
448 .Fn archive_error_string
452 returns a pointer to a freshly allocated
459 .Fn archive_read_data
460 returns a count of bytes actually read or zero at the end of the entry.
466 is returned and an error code and textual description can be retrieved from the
469 .Fn archive_error_string
472 The library expects the client callbacks to behave similarly.
473 If there is an error, you can use
474 .Fn archive_set_error
475 to set an appropriate error code and description,
476 then return one of the non-zero values above.
477 (Note that the value eventually returned to the client may
478 not be the same; many errors that are not critical at the level
479 of basic I/O can prevent the archive from being properly read,
480 thus most I/O errors eventually cause
492 library first appeared in
498 library was written by
499 .An Tim Kientzle Aq kientzle@acm.org .
501 Many traditional archiver programs treat
502 empty files as valid empty archives.
503 For example, many implementations of
505 allow you to append entries to an empty file.
506 Of course, it is impossible to determine the format of an empty file
507 by inspecting the contents, so this library treats empty files as