Merge from vendor branch LIBARCHIVE:
[dragonfly.git] / contrib / libarchive-1.3.1 / libarchive / archive_read.3
1 .\" Copyright (c) 2003-2006 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.24 2006/09/05 05:59:45 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_set_bytes_per_block ,
33 .Nm archive_read_support_compression_all ,
34 .Nm archive_read_support_compression_bzip2 ,
35 .Nm archive_read_support_compression_compress ,
36 .Nm archive_read_support_compression_gzip ,
37 .Nm archive_read_support_compression_none ,
38 .Nm archive_read_support_format_all ,
39 .Nm archive_read_support_format_cpio ,
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_set_bytes_per_block "struct archive *" "int"
66 .Ft int
67 .Fn archive_read_support_compression_all "struct archive *"
68 .Ft int
69 .Fn archive_read_support_compression_bzip2 "struct archive *"
70 .Ft int
71 .Fn archive_read_support_compression_compress "struct archive *"
72 .Ft int
73 .Fn archive_read_support_compression_gzip "struct archive *"
74 .Ft int
75 .Fn archive_read_support_compression_none "struct archive *"
76 .Ft int
77 .Fn archive_read_support_format_all "struct archive *"
78 .Ft int
79 .Fn archive_read_support_format_cpio "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_set_bytes_per_block
133 Sets the block size used for reading the archive data.
134 This controls the size that will be used when invoking the read
135 callback function.
136 The default is 20 records or 10240 bytes for tar formats.
137 .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
138 Enables auto-detection code and decompression support for the
139 specified compression.
140 Note that
141 .Dq none
142 is always enabled by default.
143 For convenience,
144 .Fn archive_read_support_compression_all
145 enables all available decompression code.
146 .It Fn archive_read_support_format_all , Fn archive_read_support_format_cpio , Fn archive_read_support_format_iso9660 , Fn archive_read_support_format_tar, Fn archive_read_support_format_zip
147 Enables support---including auto-detection code---for the
148 specified archive format.
149 For example,
150 .Fn archive_read_support_format_tar
151 enables support for a variety of standard tar formats, old-style tar,
152 ustar, pax interchange format, and many common variants.
153 For convenience,
154 .Fn archive_read_support_format_all
155 enables support for all available formats.
156 Note that there is no default.
157 .It Fn archive_read_open
158 The same as
159 .Fn archive_read_open2 ,
160 except that the skip callback is assumed to be
161 .Dv NULL .
162 .It Fn archive_read_open2
163 Freeze the settings, open the archive, and prepare for reading entries.
164 This is the most generic version of this call, which accepts
165 four callback functions.
166 Most clients will want to use
167 .Fn archive_read_open_filename ,
168 .Fn archive_read_open_FILE ,
169 .Fn archive_read_open_fd ,
170 or
171 .Fn archive_read_open_memory
172 instead.
173 The library invokes the client-provided functions to obtain
174 raw bytes from the archive.
175 .It Fn archive_read_open_FILE
176 Like
177 .Fn archive_read_open ,
178 except that it accepts a
179 .Ft "FILE *"
180 pointer.
181 This function should not be used with tape drives or other devices
182 that require strict I/O blocking.
183 .It Fn archive_read_open_fd
184 Like
185 .Fn archive_read_open ,
186 except that it accepts a file descriptor and block size rather than
187 a set of function pointers.
188 Note that the file descriptor will not be automatically closed at
189 end-of-archive.
190 This function is safe for use with tape drives or other blocked devices.
191 .It Fn archive_read_open_file
192 A deprecated synonym for
193 .Fn archive_read_open_filename .
194 .It Fn archive_read_open_filename
195 Like
196 .Fn archive_read_open ,
197 except that it accepts a simple filename and a block size.
198 A NULL filename represents standard input.
199 This function is safe for use with tape drives or other blocked devices.
200 .It Fn archive_read_open_memory
201 Like
202 .Fn archive_read_open ,
203 except that it accepts a pointer and size of a block of
204 memory containing the archive data.
205 .It Fn archive_read_next_header
206 Read the header for the next entry and return a pointer to
207 a
208 .Tn struct archive_entry .
209 .It Fn archive_read_data
210 Read data associated with the header just read.
211 Internally, this is a convenience function that calls
212 .Fn archive_read_data_block
213 and fills any gaps with nulls so that callers see a single
214 continuous stream of data.
215 .It Fn archive_read_data_block
216 Return the next available block of data for this entry.
217 Unlike
218 .Fn archive_read_data ,
219 the
220 .Fn archive_read_data_block
221 function avoids copying data and allows you to correctly handle
222 sparse files, as supported by some archive formats.
223 The library guarantees that offsets will increase and that blocks
224 will not overlap.
225 Note that the blocks returned from this function can be much larger
226 than the block size read from disk, due to compression
227 and internal buffer optimizations.
228 .It Fn archive_read_data_skip
229 A convenience function that repeatedly calls
230 .Fn archive_read_data_block
231 to skip all of the data for this archive entry.
232 .It Fn archive_read_data_into_buffer
233 A convenience function that repeatedly calls
234 .Fn archive_read_data_block
235 to copy the entire entry into the client-supplied buffer.
236 Note that the client is responsible for sizing the buffer appropriately.
237 .It Fn archive_read_data_into_fd
238 A convenience function that repeatedly calls
239 .Fn archive_read_data_block
240 to copy the entire entry to the provided file descriptor.
241 .It Fn archive_read_extract_set_skip_file
242 This function records the device and inode numbers
243 of a file that should not be restored.
244 This is a convenience that prevents
245 .Fn archive_read_extract
246 from restoring a file over the archive itself.
247 .It Fn archive_read_extract
248 A convenience function that recreates the specified object on
249 disk and reads the entry data into that object.
250 The filename, permissions, and other critical information
251 are taken from the provided
252 .Va archive_entry
253 object.
254 The
255 .Va flags
256 argument modifies how the object is recreated.
257 It consists of a bitwise OR of one or more of the following values:
258 .Bl -tag -compact -width "indent"
259 .It Cm ARCHIVE_EXTRACT_OWNER
260 The user and group IDs should be set on the restored file.
261 By default, the user and group IDs are not restored.
262 .It Cm ARCHIVE_EXTRACT_PERM
263 The permissions (mode bits) should be restored for all objects.
264 By default, permissions are only restored for regular files.
265 .It Cm ARCHIVE_EXTRACT_TIME
266 The timestamps (mtime, ctime, and atime) should be restored.
267 By default, they are ignored.
268 Note that restoring of atime is not currently supported.
269 .It Cm ARCHIVE_EXTRACT_NO_OVERWRITE
270 Existing files on disk will not be overwritten.
271 By default, existing regular files are truncated and overwritten;
272 existing directories will have their permissions updated;
273 other pre-existing objects are unlinked and recreated from scratch.
274 .It Cm ARCHIVE_EXTRACT_UNLINK
275 Existing files on disk will be unlinked and recreated from scratch.
276 By default, existing files are truncated and rewritten, but
277 the file is not recreated.
278 In particular, the default behavior does not break existing hard links.
279 .It Cm ARCHIVE_EXTRACT_ACL
280 Attempt to restore ACLs.
281 By default, extended ACLs are ignored.
282 .It Cm ARCHIVE_EXTRACT_FFLAGS
283 Attempt to restore extended file flags.
284 By default, file flags are ignored.
285 .El
286 Note that not all attributes are set immediately;
287 some attributes are cached in memory and written to disk only
288 when the archive is closed.
289 (For example, read-only directories are initially created
290 writable so that files within those directories can be
291 restored.
292 The final permissions are set when the archive is closed.)
293 .It Fn archive_read_extract_set_progress_callback
294 Sets a pointer to a user-defined callback that can be used
295 for updating progress displays during extraction.
296 The progress function will be invoked during the extraction of large
297 regular files.
298 The progress function will be invoked with the pointer provided to this call.
299 Generally, the data pointed to should include a reference to the archive
300 object and the archive_entry object so that various statistics
301 can be retrieved for the progress display.
302 .It Fn archive_read_close
303 Complete the archive and invoke the close callback.
304 .It Fn archive_read_finish
305 Invokes
306 .Fn archive_read_close
307 if it was not invoked manually, then release all resources.
308 Note: In libarchive 1.x, this function was declared to return
309 .Ft void ,
310 which made it impossible to detect certain errors when
311 .Fn archive_read_close
312 was invoked implicitly from this function.
313 The declaration is corrected beginning with libarchive 2.0.
314 .El
315 .Pp
316 Note that the library determines most of the relevant information about
317 the archive by inspection.
318 In particular, it automatically detects
319 .Xr gzip 1
320 or
321 .Xr bzip2 1
322 compression and transparently performs the appropriate decompression.
323 It also automatically detects the archive format.
324 .Pp
325 A complete description of the
326 .Tn struct archive
327 and
328 .Tn struct archive_entry
329 objects can be found in the overview manual page for
330 .Xr libarchive 3 .
331 .Sh CLIENT CALLBACKS
332 The callback functions must match the following prototypes:
333 .Bl -item -offset indent
334 .It
335 .Ft typedef ssize_t
336 .Fn archive_read_callback "struct archive *" "void *client_data" "const void **buffer"
337 .It
338 .Ft typedef int
339 .Fn archive_skip_callback "struct archive *" "void *client_data" "size_t request"
340 .It
341 .Ft typedef int
342 .Fn archive_open_callback "struct archive *" "void *client_data"
343 .It
344 .Ft typedef int
345 .Fn archive_close_callback "struct archive *" "void *client_data"
346 .El
347 .Pp
348 The open callback is invoked by
349 .Fn archive_open .
350 It should return
351 .Cm ARCHIVE_OK
352 if the underlying file or data source is successfully
353 opened.
354 If the open fails, it should call
355 .Fn archive_set_error
356 to register an error code and message and return
357 .Cm ARCHIVE_FATAL .
358 .Pp
359 The read callback is invoked whenever the library
360 requires raw bytes from the archive.
361 The read callback should read data into a buffer,
362 set the
363 .Li const void **buffer
364 argument to point to the available data, and
365 return a count of the number of bytes available.
366 The library will invoke the read callback again
367 only after it has consumed this data.
368 The library imposes no constraints on the size
369 of the data blocks returned.
370 On end-of-file, the read callback should
371 return zero.
372 On error, the read callback should invoke
373 .Fn archive_set_error
374 to register an error code and message and
375 return -1.
376 .Pp
377 The skip callback is invoked when the
378 library wants to ignore a block of data.
379 The return value is the number of bytes actually
380 skipped, which may differ from the request.
381 If the callback cannot skip data, it should return
382 zero.
383 If the skip callback is not provided (the
384 function pointer is
385 .Dv NULL ),
386 the library will invoke the read function
387 instead and simply discard the result.
388 A skip callback can provide significant
389 performance gains when reading uncompressed
390 archives from slow disk drives or other media
391 that can skip quickly.
392 .Pp
393 The close callback is invoked by archive_close when
394 the archive processing is complete.
395 The callback should return
396 .Cm ARCHIVE_OK
397 on success.
398 On failure, the callback should invoke
399 .Fn archive_set_error
400 to register an error code and message and
401 return
402 .Cm ARCHIVE_FATAL.
403 .Sh EXAMPLE
404 The following illustrates basic usage of the library.
405 In this example,
406 the callback functions are simply wrappers around the standard
407 .Xr open 2 ,
408 .Xr read 2 ,
409 and
410 .Xr close 2
411 system calls.
412 .Bd -literal -offset indent
413 void
414 list_archive(const char *name)
415 {
416   struct mydata *mydata;
417   struct archive *a;
418   struct archive_entry *entry;
419
420   mydata = malloc(sizeof(struct mydata));
421   a = archive_read_new();
422   mydata->name = name;
423   archive_read_support_compression_all(a);
424   archive_read_support_format_all(a);
425   archive_read_open(a, mydata, myopen, myread, myclose);
426   while (archive_read_next_header(a, &entry) == ARCHIVE_OK) {
427     printf("%s\\n",archive_entry_pathname(entry));
428     archive_read_data_skip(a);
429   }
430   archive_read_finish(a);
431   free(mydata);
432 }
433
434 ssize_t
435 myread(struct archive *a, void *client_data, const void **buff)
436 {
437   struct mydata *mydata = client_data;
438
439   *buff = mydata->buff;
440   return (read(mydata->fd, mydata->buff, 10240));
441 }
442
443 int
444 myopen(struct archive *a, void *client_data)
445 {
446   struct mydata *mydata = client_data;
447
448   mydata->fd = open(mydata->name, O_RDONLY);
449   return (mydata->fd >= 0 ? ARCHIVE_OK : ARCHIVE_FATAL);
450 }
451
452 int
453 myclose(struct archive *a, void *client_data)
454 {
455   struct mydata *mydata = client_data;
456
457   if (mydata->fd > 0)
458     close(mydata->fd);
459   return (ARCHIVE_OK);
460 }
461 .Ed
462 .Sh RETURN VALUES
463 Most functions return zero on success, non-zero on error.
464 The possible return codes include:
465 .Cm ARCHIVE_OK
466 (the operation succeeded),
467 .Cm ARCHIVE_WARN
468 (the operation succeeded but a non-critical error was encountered),
469 .Cm ARCHIVE_EOF
470 (end-of-archive was encountered),
471 .Cm ARCHIVE_RETRY
472 (the operation failed but can be retried),
473 and
474 .Cm ARCHIVE_FATAL
475 (there was a fatal error; the archive should be closed immediately).
476 Detailed error codes and textual descriptions are available from the
477 .Fn archive_errno
478 and
479 .Fn archive_error_string
480 functions.
481 .Pp
482 .Fn archive_read_new
483 returns a pointer to a freshly allocated
484 .Tn struct archive
485 object.
486 It returns
487 .Dv NULL
488 on error.
489 .Pp
490 .Fn archive_read_data
491 returns a count of bytes actually read or zero at the end of the entry.
492 On error, a value of
493 .Cm ARCHIVE_FATAL ,
494 .Cm ARCHIVE_WARN ,
495 or
496 .Cm ARCHIVE_RETRY
497 is returned and an error code and textual description can be retrieved from the
498 .Fn archive_errno
499 and
500 .Fn archive_error_string
501 functions.
502 .Pp
503 The library expects the client callbacks to behave similarly.
504 If there is an error, you can use
505 .Fn archive_set_error
506 to set an appropriate error code and description,
507 then return one of the non-zero values above.
508 (Note that the value eventually returned to the client may
509 not be the same; many errors that are not critical at the level
510 of basic I/O can prevent the archive from being properly read,
511 thus most I/O errors eventually cause
512 .Cm ARCHIVE_FATAL
513 to be returned.)
514 .\" .Sh ERRORS
515 .Sh SEE ALSO
516 .Xr tar 1 ,
517 .Xr archive 3 ,
518 .Xr archive_util 3 ,
519 .Xr tar 5
520 .Sh HISTORY
521 The
522 .Nm libarchive
523 library first appeared in
524 .Fx 5.3 .
525 .Sh AUTHORS
526 .An -nosplit
527 The
528 .Nm libarchive
529 library was written by
530 .An Tim Kientzle Aq kientzle@acm.org .
531 .Sh BUGS
532 Directories are actually extracted in two distinct phases.
533 Directories are created during
534 .Fn archive_read_extract ,
535 but final permissions are not set until
536 .Fn archive_read_close .
537 This separation is necessary to correctly handle borderline
538 cases such as a non-writable directory containing
539 files, but can cause unexpected results.
540 In particular, directory permissions are not fully
541 restored until the archive is closed.
542 If you use
543 .Xr chdir 2
544 to change the current directory between calls to
545 .Fn archive_read_extract
546 or before calling
547 .Fn archive_read_close ,
548 you may confuse the permission-setting logic with
549 the result that directory permissions are restored
550 incorrectly.