Merge from vendor branch LIBARCHIVE:
[dragonfly.git] / contrib / libarchive-2.0 / libarchive / archive_read.3
1 .\" Copyright (c) 2003-2007 Tim Kientzle
2 .\" All rights reserved.
3 .\"
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
6 .\" are met:
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.
12 .\"
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
23 .\" SUCH DAMAGE.
24 .\"
25 .\" $FreeBSD: src/lib/libarchive/archive_read.3,v 1.31 2007/03/03 07:37:36 kientzle Exp $
26 .\"
27 .Dd August 19, 2006
28 .Dt archive_read 3
29 .Os
30 .Sh NAME
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
60 .Sh SYNOPSIS
61 .In archive.h
62 .Ft struct archive *
63 .Fn archive_read_new "void"
64 .Ft int
65 .Fn archive_read_support_compression_all "struct archive *"
66 .Ft int
67 .Fn archive_read_support_compression_bzip2 "struct archive *"
68 .Ft int
69 .Fn archive_read_support_compression_compress "struct archive *"
70 .Ft int
71 .Fn archive_read_support_compression_gzip "struct archive *"
72 .Ft int
73 .Fn archive_read_support_compression_none "struct archive *"
74 .Ft int
75 .Fn archive_read_support_format_all "struct archive *"
76 .Ft int
77 .Fn archive_read_support_format_cpio "struct archive *"
78 .Ft int
79 .Fn archive_read_support_format_empty "struct archive *"
80 .Ft int
81 .Fn archive_read_support_format_iso9660 "struct archive *"
82 .Ft int
83 .Fn archive_read_support_format_tar "struct archive *"
84 .Ft int
85 .Fn archive_read_support_format_zip "struct archive *"
86 .Ft int
87 .Fn archive_read_open "struct archive *" "void *client_data" "archive_open_callback *" "archive_read_callback *" "archive_close_callback *"
88 .Ft int
89 .Fn archive_read_open2 "struct archive *" "void *client_data" "archive_open_callback *" "archive_read_callback *" "archive_skip_callback *" "archive_close_callback *"
90 .Ft int
91 .Fn archive_read_open_FILE "struct archive *" "FILE *file"
92 .Ft int
93 .Fn archive_read_open_fd "struct archive *" "int fd" "size_t block_size"
94 .Ft int
95 .Fn archive_read_open_filename "struct archive *" "const char *filename" "size_t block_size"
96 .Ft int
97 .Fn archive_read_open_memory "struct archive *" "void *buff" "size_t size"
98 .Ft int
99 .Fn archive_read_next_header "struct archive *" "struct archive_entry **"
100 .Ft ssize_t
101 .Fn archive_read_data "struct archive *" "void *buff" "size_t len"
102 .Ft int
103 .Fn archive_read_data_block "struct archive *" "const void **buff" "size_t *len" "off_t *offset"
104 .Ft int
105 .Fn archive_read_data_skip "struct archive *"
106 .Ft int
107 .Fn archive_read_data_into_buffer "struct archive *" "void *" "ssize_t len"
108 .Ft int
109 .Fn archive_read_data_into_fd "struct archive *" "int fd"
110 .Ft int
111 .Fn archive_read_extract "struct archive *" "struct archive_entry *" "int flags"
112 .Ft void
113 .Fn archive_read_extract_set_progress_callback "struct archive *" "void (*func)(void *)" "void *user_data"
114 .Ft int
115 .Fn archive_read_close "struct archive *"
116 .Ft int
117 .Fn archive_read_finish "struct archive *"
118 .Sh DESCRIPTION
119 These functions provide a complete API for reading streaming archives.
120 The general process is to first create the
121 .Tn struct archive
122 object, set options, initialize the reader, iterate over the archive
123 headers and associated data, then close the archive and release all
124 resources.
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
130 .Tn struct archive
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.
135 Note that
136 .Dq none
137 is always enabled by default.
138 For convenience,
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.
144 For example,
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.
148 For convenience,
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
153 The same as
154 .Fn archive_read_open2 ,
155 except that the skip callback is assumed to be
156 .Dv NULL .
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 ,
165 or
166 .Fn archive_read_open_memory
167 instead.
168 The library invokes the client-provided functions to obtain
169 raw bytes from the archive.
170 .It Fn archive_read_open_FILE
171 Like
172 .Fn archive_read_open ,
173 except that it accepts a
174 .Ft "FILE *"
175 pointer.
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
179 Like
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
184 end-of-archive.
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
190 Like
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
196 Like
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
202 a
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.
212 Unlike
213 .Fn archive_read_data ,
214 the
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
219 will not overlap.
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
239 interfaces.
240 The first call to
241 .Fn archive_read_extract
242 creates a restore object using
243 .Xr archive_write_disk_new 3
244 and
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 ,
250 and
251 .Xr archive_write_finish_entry 3
252 to create the entry on disk and copy data into it.
253 The
254 .Va flags
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
261 regular files.
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
269 Invokes
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
273 .Ft void ,
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.
278 .El
279 .Pp
280 Note that the library determines most of the relevant information about
281 the archive by inspection.
282 In particular, it automatically detects
283 .Xr gzip 1
284 or
285 .Xr bzip2 1
286 compression and transparently performs the appropriate decompression.
287 It also automatically detects the archive format.
288 .Pp
289 A complete description of the
290 .Tn struct archive
291 and
292 .Tn struct archive_entry
293 objects can be found in the overview manual page for
294 .Xr libarchive 3 .
295 .Sh CLIENT CALLBACKS
296 The callback functions must match the following prototypes:
297 .Bl -item -offset indent
298 .It
299 .Ft typedef ssize_t
300 .Fn archive_read_callback "struct archive *" "void *client_data" "const void **buffer"
301 .It
302 .\" #if ARCHIVE_API_VERSION < 2
303 .Ft typedef int
304 .Fn archive_skip_callback "struct archive *" "void *client_data" "size_t request"
305 .\" #else
306 .\" .Ft typedef off_t
307 .\" .Fn archive_skip_callback "struct archive *" "void *client_data" "off_t request"
308 .\" #endif
309 .It
310 .Ft typedef int
311 .Fn archive_open_callback "struct archive *" "void *client_data"
312 .It
313 .Ft typedef int
314 .Fn archive_close_callback "struct archive *" "void *client_data"
315 .El
316 .Pp
317 The open callback is invoked by
318 .Fn archive_open .
319 It should return
320 .Cm ARCHIVE_OK
321 if the underlying file or data source is successfully
322 opened.
323 If the open fails, it should call
324 .Fn archive_set_error
325 to register an error code and message and return
326 .Cm ARCHIVE_FATAL .
327 .Pp
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,
331 set the
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
340 return zero.
341 On error, the read callback should invoke
342 .Fn archive_set_error
343 to register an error code and message and
344 return -1.
345 .Pp
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
351 zero.
352 If the skip callback is not provided (the
353 function pointer is
354 .Dv NULL ),
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.
361 .Pp
362 The close callback is invoked by archive_close when
363 the archive processing is complete.
364 The callback should return
365 .Cm ARCHIVE_OK
366 on success.
367 On failure, the callback should invoke
368 .Fn archive_set_error
369 to register an error code and message and
370 return
371 .Cm ARCHIVE_FATAL.
372 .Sh EXAMPLE
373 The following illustrates basic usage of the library.
374 In this example,
375 the callback functions are simply wrappers around the standard
376 .Xr open 2 ,
377 .Xr read 2 ,
378 and
379 .Xr close 2
380 system calls.
381 .Bd -literal -offset indent
382 void
383 list_archive(const char *name)
384 {
385   struct mydata *mydata;
386   struct archive *a;
387   struct archive_entry *entry;
388
389   mydata = malloc(sizeof(struct mydata));
390   a = archive_read_new();
391   mydata->name = name;
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);
398   }
399   archive_read_finish(a);
400   free(mydata);
401 }
402
403 ssize_t
404 myread(struct archive *a, void *client_data, const void **buff)
405 {
406   struct mydata *mydata = client_data;
407
408   *buff = mydata->buff;
409   return (read(mydata->fd, mydata->buff, 10240));
410 }
411
412 int
413 myopen(struct archive *a, void *client_data)
414 {
415   struct mydata *mydata = client_data;
416
417   mydata->fd = open(mydata->name, O_RDONLY);
418   return (mydata->fd >= 0 ? ARCHIVE_OK : ARCHIVE_FATAL);
419 }
420
421 int
422 myclose(struct archive *a, void *client_data)
423 {
424   struct mydata *mydata = client_data;
425
426   if (mydata->fd > 0)
427     close(mydata->fd);
428   return (ARCHIVE_OK);
429 }
430 .Ed
431 .Sh RETURN VALUES
432 Most functions return zero on success, non-zero on error.
433 The possible return codes include:
434 .Cm ARCHIVE_OK
435 (the operation succeeded),
436 .Cm ARCHIVE_WARN
437 (the operation succeeded but a non-critical error was encountered),
438 .Cm ARCHIVE_EOF
439 (end-of-archive was encountered),
440 .Cm ARCHIVE_RETRY
441 (the operation failed but can be retried),
442 and
443 .Cm ARCHIVE_FATAL
444 (there was a fatal error; the archive should be closed immediately).
445 Detailed error codes and textual descriptions are available from the
446 .Fn archive_errno
447 and
448 .Fn archive_error_string
449 functions.
450 .Pp
451 .Fn archive_read_new
452 returns a pointer to a freshly allocated
453 .Tn struct archive
454 object.
455 It returns
456 .Dv NULL
457 on error.
458 .Pp
459 .Fn archive_read_data
460 returns a count of bytes actually read or zero at the end of the entry.
461 On error, a value of
462 .Cm ARCHIVE_FATAL ,
463 .Cm ARCHIVE_WARN ,
464 or
465 .Cm ARCHIVE_RETRY
466 is returned and an error code and textual description can be retrieved from the
467 .Fn archive_errno
468 and
469 .Fn archive_error_string
470 functions.
471 .Pp
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
481 .Cm ARCHIVE_FATAL
482 to be returned.)
483 .\" .Sh ERRORS
484 .Sh SEE ALSO
485 .Xr tar 1 ,
486 .Xr archive 3 ,
487 .Xr archive_util 3 ,
488 .Xr tar 5
489 .Sh HISTORY
490 The
491 .Nm libarchive
492 library first appeared in
493 .Fx 5.3 .
494 .Sh AUTHORS
495 .An -nosplit
496 The
497 .Nm libarchive
498 library was written by
499 .An Tim Kientzle Aq kientzle@acm.org .
500 .Sh BUGS
501 Many traditional archiver programs treat
502 empty files as valid empty archives.
503 For example, many implementations of
504 .Xr tar 1
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
508 having a special
509 .Dq empty
510 format.