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: head/lib/libarchive/archive_read.3 191595 2009-04-27 20:13:13Z kientzle $
31
.Nm archive_read_new ,
32
.Nm archive_read_set_filter_options ,
33
.Nm archive_read_set_format_options ,
34
.Nm archive_read_set_options ,
35
.Nm archive_read_support_compression_all ,
36
.Nm archive_read_support_compression_bzip2 ,
37
.Nm archive_read_support_compression_compress ,
38
.Nm archive_read_support_compression_gzip ,
39
.Nm archive_read_support_compression_lzma ,
40
.Nm archive_read_support_compression_none ,
41
.Nm archive_read_support_compression_xz ,
42
.Nm archive_read_support_compression_program ,
43
.Nm archive_read_support_compression_program_signature ,
44
.Nm archive_read_support_format_all ,
45
.Nm archive_read_support_format_ar ,
46
.Nm archive_read_support_format_cpio ,
47
.Nm archive_read_support_format_empty ,
48
.Nm archive_read_support_format_iso9660 ,
49
.Nm archive_read_support_format_mtree,
50
.Nm archive_read_support_format_raw,
51
.Nm archive_read_support_format_tar ,
52
.Nm archive_read_support_format_zip ,
53
.Nm archive_read_open ,
54
.Nm archive_read_open2 ,
55
.Nm archive_read_open_fd ,
56
.Nm archive_read_open_FILE ,
57
.Nm archive_read_open_filename ,
58
.Nm archive_read_open_memory ,
59
.Nm archive_read_next_header ,
60
.Nm archive_read_next_header2 ,
61
.Nm archive_read_data ,
62
.Nm archive_read_data_block ,
63
.Nm archive_read_data_skip ,
64
.\" #if ARCHIVE_API_VERSION < 3
65
.Nm archive_read_data_into_buffer ,
67
.Nm archive_read_data_into_fd ,
68
.Nm archive_read_extract ,
69
.Nm archive_read_extract2 ,
70
.Nm archive_read_extract_set_progress_callback ,
71
.Nm archive_read_close ,
72
.Nm archive_read_finish
73
.Nd functions for reading streaming archives
77
.Fn archive_read_new "void"
79
.Fn archive_read_support_compression_all "struct archive *"
81
.Fn archive_read_support_compression_bzip2 "struct archive *"
83
.Fn archive_read_support_compression_compress "struct archive *"
85
.Fn archive_read_support_compression_gzip "struct archive *"
87
.Fn archive_read_support_compression_lzma "struct archive *"
89
.Fn archive_read_support_compression_none "struct archive *"
91
.Fn archive_read_support_compression_xz "struct archive *"
93
.Fo archive_read_support_compression_program
94
.Fa "struct archive *"
98
.Fo archive_read_support_compression_program_signature
99
.Fa "struct archive *"
100
.Fa "const char *cmd"
101
.Fa "const void *signature"
102
.Fa "size_t signature_length"
105
.Fn archive_read_support_format_all "struct archive *"
107
.Fn archive_read_support_format_ar "struct archive *"
109
.Fn archive_read_support_format_cpio "struct archive *"
111
.Fn archive_read_support_format_empty "struct archive *"
113
.Fn archive_read_support_format_iso9660 "struct archive *"
115
.Fn archive_read_support_format_mtree "struct archive *"
117
.Fn archive_read_support_format_raw "struct archive *"
119
.Fn archive_read_support_format_tar "struct archive *"
121
.Fn archive_read_support_format_zip "struct archive *"
123
.Fn archive_read_set_filter_options "struct archive *" "const char *"
125
.Fn archive_read_set_format_options "struct archive *" "const char *"
127
.Fn archive_read_set_options "struct archive *" "const char *"
129
.Fo archive_read_open
130
.Fa "struct archive *"
131
.Fa "void *client_data"
132
.Fa "archive_open_callback *"
133
.Fa "archive_read_callback *"
134
.Fa "archive_close_callback *"
137
.Fo archive_read_open2
138
.Fa "struct archive *"
139
.Fa "void *client_data"
140
.Fa "archive_open_callback *"
141
.Fa "archive_read_callback *"
142
.Fa "archive_skip_callback *"
143
.Fa "archive_close_callback *"
146
.Fn archive_read_open_FILE "struct archive *" "FILE *file"
148
.Fn archive_read_open_fd "struct archive *" "int fd" "size_t block_size"
150
.Fo archive_read_open_filename
151
.Fa "struct archive *"
152
.Fa "const char *filename"
153
.Fa "size_t block_size"
156
.Fn archive_read_open_memory "struct archive *" "void *buff" "size_t size"
158
.Fn archive_read_next_header "struct archive *" "struct archive_entry **"
160
.Fn archive_read_next_header2 "struct archive *" "struct archive_entry *"
162
.Fn archive_read_data "struct archive *" "void *buff" "size_t len"
164
.Fo archive_read_data_block
165
.Fa "struct archive *"
166
.Fa "const void **buff"
171
.Fn archive_read_data_skip "struct archive *"
172
.\" #if ARCHIVE_API_VERSION < 3
174
.Fn archive_read_data_into_buffer "struct archive *" "void *" "ssize_t len"
177
.Fn archive_read_data_into_fd "struct archive *" "int fd"
179
.Fo archive_read_extract
180
.Fa "struct archive *"
181
.Fa "struct archive_entry *"
185
.Fo archive_read_extract2
186
.Fa "struct archive *src"
187
.Fa "struct archive_entry *"
188
.Fa "struct archive *dest"
191
.Fo archive_read_extract_set_progress_callback
192
.Fa "struct archive *"
193
.Fa "void (*func)(void *)"
194
.Fa "void *user_data"
197
.Fn archive_read_close "struct archive *"
199
.Fn archive_read_finish "struct archive *"
201
These functions provide a complete API for reading streaming archives.
202
The general process is to first create the
204
object, set options, initialize the reader, iterate over the archive
205
headers and associated data, then close the archive and release all
207
The following summary describes the functions in approximately the
208
order they would be used:
209
.Bl -tag -compact -width indent
210
.It Fn archive_read_new
211
Allocates and initializes a
213
object suitable for reading from an archive.
215
.Fn archive_read_support_compression_bzip2 ,
216
.Fn archive_read_support_compression_compress ,
217
.Fn archive_read_support_compression_gzip ,
218
.Fn archive_read_support_compression_lzma ,
219
.Fn archive_read_support_compression_none ,
220
.Fn archive_read_support_compression_xz
222
Enables auto-detection code and decompression support for the
223
specified compression.
226
if the compression is fully supported, or
228
if the compression is supported only through an external program.
229
Note that decompression using an external program is usually slower than
230
decompression through built-in libraries.
233
is always enabled by default.
234
.It Fn archive_read_support_compression_all
235
Enables all available decompression filters.
236
.It Fn archive_read_support_compression_program
237
Data is fed through the specified external program before being dearchived.
238
Note that this disables automatic detection of the compression format,
239
so it makes no sense to specify this in conjunction with any other
240
decompression option.
241
.It Fn archive_read_support_compression_program_signature
242
This feeds data through the specified external program
243
but only if the initial bytes of the data match the specified
246
.Fn archive_read_support_format_all ,
247
.Fn archive_read_support_format_ar ,
248
.Fn archive_read_support_format_cpio ,
249
.Fn archive_read_support_format_empty ,
250
.Fn archive_read_support_format_iso9660 ,
251
.Fn archive_read_support_format_mtree ,
252
.Fn archive_read_support_format_tar ,
253
.Fn archive_read_support_format_zip
255
Enables support---including auto-detection code---for the
256
specified archive format.
258
.Fn archive_read_support_format_tar
259
enables support for a variety of standard tar formats, old-style tar,
260
ustar, pax interchange format, and many common variants.
262
.Fn archive_read_support_format_all
263
enables support for all available formats.
264
Only empty archives are supported by default.
265
.It Fn archive_read_support_format_raw
268
format handler allows libarchive to be used to read arbitrary data.
269
It treats any data stream as an archive with a single entry.
270
The pathname of this entry is
272
all other entry fields are unset.
273
This is not enabled by
274
.Fn archive_read_support_format_all
275
in order to avoid erroneous handling of damaged archives.
277
.Fn archive_read_set_filter_options ,
278
.Fn archive_read_set_format_options ,
279
.Fn archive_read_set_options
281
Specifies options that will be passed to currently-registered
282
filters (including decompression filters) and/or format readers.
283
The argument is a comma-separated list of individual options.
284
Individual options have one of the following forms:
285
.Bl -tag -compact -width indent
287
The option/value pair will be provided to every module.
288
Modules that do not accept an option with this name will ignore it.
290
The option will be provided to every module with a value of
293
The option will be provided to every module with a NULL value.
294
.It Ar module:option=value , Ar module:option , Ar module:!option
295
As above, but the corresponding option and value will be provided
296
only to modules whose name matches
299
The return value will be
301
if any module accepts the option, or
303
if no module accepted the option, or
305
if there was a fatal error while attempting to process the option.
307
The currently supported options are:
308
.Bl -tag -compact -width indent
310
.Bl -tag -compact -width indent
312
Support Joliet extensions.
313
Defaults to enabled, use
318
.It Fn archive_read_open
320
.Fn archive_read_open2 ,
321
except that the skip callback is assumed to be
323
.It Fn archive_read_open2
324
Freeze the settings, open the archive, and prepare for reading entries.
325
This is the most generic version of this call, which accepts
326
four callback functions.
327
Most clients will want to use
328
.Fn archive_read_open_filename ,
329
.Fn archive_read_open_FILE ,
330
.Fn archive_read_open_fd ,
332
.Fn archive_read_open_memory
334
The library invokes the client-provided functions to obtain
335
raw bytes from the archive.
336
.It Fn archive_read_open_FILE
338
.Fn archive_read_open ,
339
except that it accepts a
342
This function should not be used with tape drives or other devices
343
that require strict I/O blocking.
344
.It Fn archive_read_open_fd
346
.Fn archive_read_open ,
347
except that it accepts a file descriptor and block size rather than
348
a set of function pointers.
349
Note that the file descriptor will not be automatically closed at
351
This function is safe for use with tape drives or other blocked devices.
352
.It Fn archive_read_open_file
353
This is a deprecated synonym for
354
.Fn archive_read_open_filename .
355
.It Fn archive_read_open_filename
357
.Fn archive_read_open ,
358
except that it accepts a simple filename and a block size.
359
A NULL filename represents standard input.
360
This function is safe for use with tape drives or other blocked devices.
361
.It Fn archive_read_open_memory
363
.Fn archive_read_open ,
364
except that it accepts a pointer and size of a block of
365
memory containing the archive data.
366
.It Fn archive_read_next_header
367
Read the header for the next entry and return a pointer to
369
.Tn struct archive_entry .
370
This is a convenience wrapper around
371
.Fn archive_read_next_header2
372
that reuses an internal
373
.Tn struct archive_entry
374
object for each request.
375
.It Fn archive_read_next_header2
376
Read the header for the next entry and populate the provided
377
.Tn struct archive_entry .
378
.It Fn archive_read_data
379
Read data associated with the header just read.
380
Internally, this is a convenience function that calls
381
.Fn archive_read_data_block
382
and fills any gaps with nulls so that callers see a single
383
continuous stream of data.
384
.It Fn archive_read_data_block
385
Return the next available block of data for this entry.
387
.Fn archive_read_data ,
389
.Fn archive_read_data_block
390
function avoids copying data and allows you to correctly handle
391
sparse files, as supported by some archive formats.
392
The library guarantees that offsets will increase and that blocks
394
Note that the blocks returned from this function can be much larger
395
than the block size read from disk, due to compression
396
and internal buffer optimizations.
397
.It Fn archive_read_data_skip
398
A convenience function that repeatedly calls
399
.Fn archive_read_data_block
400
to skip all of the data for this archive entry.
401
.\" #if ARCHIVE_API_VERSION < 3
402
.It Fn archive_read_data_into_buffer
403
This function is deprecated and will be removed.
405
.Fn archive_read_data
408
.It Fn archive_read_data_into_fd
409
A convenience function that repeatedly calls
410
.Fn archive_read_data_block
411
to copy the entire entry to the provided file descriptor.
412
.It Fn archive_read_extract , Fn archive_read_extract_set_skip_file
413
A convenience function that wraps the corresponding
414
.Xr archive_write_disk 3
417
.Fn archive_read_extract
418
creates a restore object using
419
.Xr archive_write_disk_new 3
421
.Xr archive_write_disk_set_standard_lookup 3 ,
422
then transparently invokes
423
.Xr archive_write_disk_set_options 3 ,
424
.Xr archive_write_header 3 ,
425
.Xr archive_write_data 3 ,
427
.Xr archive_write_finish_entry 3
428
to create the entry on disk and copy data into it.
431
argument is passed unmodified to
432
.Xr archive_write_disk_set_options 3 .
433
.It Fn archive_read_extract2
434
This is another version of
435
.Fn archive_read_extract
436
that allows you to provide your own restore object.
437
In particular, this allows you to override the standard lookup functions
439
.Xr archive_write_disk_set_group_lookup 3 ,
441
.Xr archive_write_disk_set_user_lookup 3 .
443
.Fn archive_read_extract2
446
argument; you should use
447
.Fn archive_write_disk_set_options
448
to set the restore options yourself.
449
.It Fn archive_read_extract_set_progress_callback
450
Sets a pointer to a user-defined callback that can be used
451
for updating progress displays during extraction.
452
The progress function will be invoked during the extraction of large
454
The progress function will be invoked with the pointer provided to this call.
455
Generally, the data pointed to should include a reference to the archive
456
object and the archive_entry object so that various statistics
457
can be retrieved for the progress display.
458
.It Fn archive_read_close
459
Complete the archive and invoke the close callback.
460
.It Fn archive_read_finish
462
.Fn archive_read_close
463
if it was not invoked manually, then release all resources.
464
Note: In libarchive 1.x, this function was declared to return
466
which made it impossible to detect certain errors when
467
.Fn archive_read_close
468
was invoked implicitly from this function.
469
The declaration is corrected beginning with libarchive 2.0.
472
Note that the library determines most of the relevant information about
473
the archive by inspection.
474
In particular, it automatically detects
478
compression and transparently performs the appropriate decompression.
479
It also automatically detects the archive format.
481
A complete description of the
484
.Tn struct archive_entry
485
objects can be found in the overview manual page for
488
The callback functions must match the following prototypes:
489
.Bl -item -offset indent
492
.Fo archive_read_callback
493
.Fa "struct archive *"
494
.Fa "void *client_data"
495
.Fa "const void **buffer"
498
.\" #if ARCHIVE_API_VERSION < 2
500
.Fo archive_skip_callback
501
.Fa "struct archive *"
502
.Fa "void *client_data"
506
.\" .Ft typedef off_t
507
.\" .Fo archive_skip_callback
508
.\" .Fa "struct archive *"
509
.\" .Fa "void *client_data"
510
.\" .Fa "off_t request"
515
.Fn archive_open_callback "struct archive *" "void *client_data"
518
.Fn archive_close_callback "struct archive *" "void *client_data"
521
The open callback is invoked by
525
if the underlying file or data source is successfully
527
If the open fails, it should call
528
.Fn archive_set_error
529
to register an error code and message and return
532
The read callback is invoked whenever the library
533
requires raw bytes from the archive.
534
The read callback should read data into a buffer,
536
.Li const void **buffer
537
argument to point to the available data, and
538
return a count of the number of bytes available.
539
The library will invoke the read callback again
540
only after it has consumed this data.
541
The library imposes no constraints on the size
542
of the data blocks returned.
543
On end-of-file, the read callback should
545
On error, the read callback should invoke
546
.Fn archive_set_error
547
to register an error code and message and
550
The skip callback is invoked when the
551
library wants to ignore a block of data.
552
The return value is the number of bytes actually
553
skipped, which may differ from the request.
554
If the callback cannot skip data, it should return
556
If the skip callback is not provided (the
559
the library will invoke the read function
560
instead and simply discard the result.
561
A skip callback can provide significant
562
performance gains when reading uncompressed
563
archives from slow disk drives or other media
564
that can skip quickly.
566
The close callback is invoked by archive_close when
567
the archive processing is complete.
568
The callback should return
571
On failure, the callback should invoke
572
.Fn archive_set_error
573
to register an error code and message and
577
The following illustrates basic usage of the library.
579
the callback functions are simply wrappers around the standard
585
.Bd -literal -offset indent
587
list_archive(const char *name)
589
struct mydata *mydata;
591
struct archive_entry *entry;
593
mydata = malloc(sizeof(struct mydata));
594
a = archive_read_new();
596
archive_read_support_compression_all(a);
597
archive_read_support_format_all(a);
598
archive_read_open(a, mydata, myopen, myread, myclose);
599
while (archive_read_next_header(a, &entry) == ARCHIVE_OK) {
600
printf("%s\en",archive_entry_pathname(entry));
601
archive_read_data_skip(a);
603
archive_read_finish(a);
608
myread(struct archive *a, void *client_data, const void **buff)
610
struct mydata *mydata = client_data;
612
*buff = mydata->buff;
613
return (read(mydata->fd, mydata->buff, 10240));
617
myopen(struct archive *a, void *client_data)
619
struct mydata *mydata = client_data;
621
mydata->fd = open(mydata->name, O_RDONLY);
622
return (mydata->fd >= 0 ? ARCHIVE_OK : ARCHIVE_FATAL);
626
myclose(struct archive *a, void *client_data)
628
struct mydata *mydata = client_data;
636
Most functions return zero on success, non-zero on error.
637
The possible return codes include:
639
(the operation succeeded),
641
(the operation succeeded but a non-critical error was encountered),
643
(end-of-archive was encountered),
645
(the operation failed but can be retried),
648
(there was a fatal error; the archive should be closed immediately).
649
Detailed error codes and textual descriptions are available from the
652
.Fn archive_error_string
656
returns a pointer to a freshly allocated
663
.Fn archive_read_data
664
returns a count of bytes actually read or zero at the end of the entry.
670
is returned and an error code and textual description can be retrieved from the
673
.Fn archive_error_string
676
The library expects the client callbacks to behave similarly.
677
If there is an error, you can use
678
.Fn archive_set_error
679
to set an appropriate error code and description,
680
then return one of the non-zero values above.
681
(Note that the value eventually returned to the client may
682
not be the same; many errors that are not critical at the level
683
of basic I/O can prevent the archive from being properly read,
684
thus most I/O errors eventually cause
696
library first appeared in
702
library was written by
703
.An Tim Kientzle Aq kientzle@acm.org .
705
Many traditional archiver programs treat
706
empty files as valid empty archives.
707
For example, many implementations of
709
allow you to append entries to an empty file.
710
Of course, it is impossible to determine the format of an empty file
711
by inspecting the contents, so this library treats empty files as
added
removed
src/libarchive/libarchive/archive_read.3
