1archive_read(3) BSD Library Functions Manual archive_read(3)
2
4 archive_read_new, archive_read_set_filter_options,
5 archive_read_set_format_options, archive_read_set_options,
6 archive_read_support_compression_all,
7 archive_read_support_compression_bzip2,
8 archive_read_support_compression_compress,
9 archive_read_support_compression_gzip,
10 archive_read_support_compression_lzma,
11 archive_read_support_compression_none,
12 archive_read_support_compression_xz,
13 archive_read_support_compression_program,
14 archive_read_support_compression_program_signature,
15 archive_read_support_format_all, archive_read_support_format_ar,
16 archive_read_support_format_cpio, archive_read_support_format_empty,
17 archive_read_support_format_iso9660, archive_read_support_format_mtree,
18 archive_read_support_format_raw, archive_read_support_format_tar,
19 archive_read_support_format_zip, archive_read_open, archive_read_open2,
20 archive_read_open_fd, archive_read_open_FILE, archive_read_open_filename,
21 archive_read_open_memory, archive_read_next_header,
22 archive_read_next_header2, archive_read_data, archive_read_data_block,
23 archive_read_data_skip, archive_read_data_into_buffer,
24 archive_read_data_into_fd, archive_read_extract, archive_read_extract2,
25 archive_read_extract_set_progress_callback, archive_read_close,
26 archive_read_finish — functions for reading streaming archives
27
29 #include <archive.h>
30 struct archive *
32 archive_read_new(void);
33 int
35 archive_read_support_compression_all(struct archive *);
36 int
38 archive_read_support_compression_bzip2(struct archive *);
39 int
41 archive_read_support_compression_compress(struct archive *);
42 int
44 archive_read_support_compression_gzip(struct archive *);
45 int
47 archive_read_support_compression_lzma(struct archive *);
48 int
50 archive_read_support_compression_none(struct archive *);
51 int
53 archive_read_support_compression_xz(struct archive *);
54 int
56 archive_read_support_compression_program(struct archive *,
57 const char *cmd);
58 int
60 archive_read_support_compression_program_signature(struct archive *,
61 const char *cmd, const void *signature, size_t signature_length);
62 int
64 archive_read_support_format_all(struct archive *);
65 int
67 archive_read_support_format_ar(struct archive *);
68 int
70 archive_read_support_format_cpio(struct archive *);
71 int
73 archive_read_support_format_empty(struct archive *);
74 int
76 archive_read_support_format_iso9660(struct archive *);
77 int
79 archive_read_support_format_mtree(struct archive *);
80 int
82 archive_read_support_format_raw(struct archive *);
83 int
85 archive_read_support_format_tar(struct archive *);
86 int
88 archive_read_support_format_zip(struct archive *);
89 int
91 archive_read_set_filter_options(struct archive *, const char *);
92 int
94 archive_read_set_format_options(struct archive *, const char *);
95 int
97 archive_read_set_options(struct archive *, const char *);
98 int
100 archive_read_open(struct archive *, void *client_data,
101 archive_open_callback *, archive_read_callback *,
102 archive_close_callback *);
103 int
105 archive_read_open2(struct archive *, void *client_data,
106 archive_open_callback *, archive_read_callback *,
107 archive_skip_callback *, archive_close_callback *);
108 int
110 archive_read_open_FILE(struct archive *, FILE *file);
111 int
113 archive_read_open_fd(struct archive *, int fd, size_t block_size);
114 int
116 archive_read_open_filename(struct archive *, const char *filename,
117 size_t block_size);
118 int
120 archive_read_open_memory(struct archive *, void *buff, size_t size);
121 int
123 archive_read_next_header(struct archive *, struct archive_entry **);
124 int
126 archive_read_next_header2(struct archive *, struct archive_entry *);
127 ssize_t
129 archive_read_data(struct archive *, void *buff, size_t len);
130 int
132 archive_read_data_block(struct archive *, const void **buff, size_t *len,
133 off_t *offset);
134 int
136 archive_read_data_skip(struct archive *);
137 int
139 archive_read_data_into_buffer(struct archive *, void *, ssize_t len);
140 int
142 archive_read_data_into_fd(struct archive *, int fd);
143 int
145 archive_read_extract(struct archive *, struct archive_entry *,
146 int flags);
147 int
149 archive_read_extract2(struct archive *src, struct archive_entry *,
150 struct archive *dest);
151 void
153 archive_read_extract_set_progress_callback(struct archive *,
154 void (*func)(void *), void *user_data);
155 int
157 archive_read_close(struct archive *);
158 int
160 archive_read_finish(struct archive *);
161
163 These functions provide a complete API for reading streaming archives.
164 The general process is to first create the struct archive object, set
165 options, initialize the reader, iterate over the archive headers and
166 associated data, then close the archive and release all resources. The
167 following summary describes the functions in approximately the order they
168 would be used:
169 archive_read_new()
170 Allocates and initializes a struct archive object suitable for
171 reading from an archive.
172 archive_read_support_compression_bzip2(),
173 archive_read_support_compression_compress(),
174 archive_read_support_compression_gzip(),
175 archive_read_support_compression_lzma(),
176 archive_read_support_compression_none(),
177 archive_read_support_compression_xz()
178 Enables auto-detection code and decompression support for the
179 specified compression. Returns ARCHIVE_OK if the compression is
180 fully supported, or ARCHIVE_WARN if the compression is supported
181 only through an external program. Note that decompression using
182 an external program is usually slower than decompression through
183 built-in libraries. Note that “none” is always enabled by
184 default.
185 archive_read_support_compression_all()
186 Enables all available decompression filters.
187 archive_read_support_compression_program()
188 Data is fed through the specified external program before being
189 dearchived. Note that this disables automatic detection of the
190 compression format, so it makes no sense to specify this in con‐
191 junction with any other decompression option.
192 archive_read_support_compression_program_signature()
193 This feeds data through the specified external program but only
194 if the initial bytes of the data match the specified signature
195 value.
196 archive_read_support_format_all(), archive_read_support_format_ar(),
197 archive_read_support_format_cpio(),
198 archive_read_support_format_empty(),
199 archive_read_support_format_iso9660(),
200 archive_read_support_format_mtree(),
201 archive_read_support_format_tar(),
202 archive_read_support_format_zip()
203 Enables support---including auto-detection code---for the speci‐
204 fied archive format. For example,
205 archive_read_support_format_tar() enables support for a variety
206 of standard tar formats, old-style tar, ustar, pax interchange
207 format, and many common variants. For convenience,
208 archive_read_support_format_all() enables support for all avail‐
209 able formats. Only empty archives are supported by default.
210 archive_read_support_format_raw()
211 The “raw” format handler allows libarchive to be used to read
212 arbitrary data. It treats any data stream as an archive with a
213 single entry. The pathname of this entry is “data”; all other
214 entry fields are unset. This is not enabled by
215 archive_read_support_format_all() in order to avoid erroneous
216 handling of damaged archives.
217 archive_read_set_filter_options(), archive_read_set_format_options(),
218 archive_read_set_options()
219 Specifies options that will be passed to currently-registered
220 filters (including decompression filters) and/or format readers.
221 The argument is a comma-separated list of individual options.
222 Individual options have one of the following forms:
223 option=value
224 The option/value pair will be provided to every module.
225 Modules that do not accept an option with this name will
226 ignore it.
227 option The option will be provided to every module with a value
228 of “1”.
229 !option
230 The option will be provided to every module with a NULL
231 value.
232 module:option=value, module:option, module:!option
233 As above, but the corresponding option and value will be
234 provided only to modules whose name matches module.
235 The return value will be ARCHIVE_OK if any module accepts the
236 option, or ARCHIVE_WARN if no module accepted the option, or
237 ARCHIVE_FATAL if there was a fatal error while attempting to
238 process the option.
239 The currently supported options are:
241 Format iso9660
242 joliet Support Joliet extensions. Defaults to enabled,
243 use !joliet to disable.
244 archive_read_open()
245 The same as archive_read_open2(), except that the skip callback
246 is assumed to be NULL.
247 archive_read_open2()
248 Freeze the settings, open the archive, and prepare for reading
249 entries. This is the most generic version of this call, which
250 accepts four callback functions. Most clients will want to use
251 archive_read_open_filename(), archive_read_open_FILE(),
252 archive_read_open_fd(), or archive_read_open_memory() instead.
253 The library invokes the client-provided functions to obtain raw
254 bytes from the archive.
255 archive_read_open_FILE()
256 Like archive_read_open(), except that it accepts a FILE *
257 pointer. This function should not be used with tape drives or
258 other devices that require strict I/O blocking.
259 archive_read_open_fd()
260 Like archive_read_open(), except that it accepts a file descrip‐
261 tor and block size rather than a set of function pointers. Note
262 that the file descriptor will not be automatically closed at end-
263 of-archive. This function is safe for use with tape drives or
264 other blocked devices.
265 archive_read_open_file()
266 This is a deprecated synonym for archive_read_open_filename().
267 archive_read_open_filename()
268 Like archive_read_open(), except that it accepts a simple file‐
269 name and a block size. A NULL filename represents standard
270 input. This function is safe for use with tape drives or other
271 blocked devices.
272 archive_read_open_memory()
273 Like archive_read_open(), except that it accepts a pointer and
274 size of a block of memory containing the archive data.
275 archive_read_next_header()
276 Read the header for the next entry and return a pointer to a
277 struct archive_entry. This is a convenience wrapper around
278 archive_read_next_header2() that reuses an internal struct
279 archive_entry object for each request.
280 archive_read_next_header2()
281 Read the header for the next entry and populate the provided
282 struct archive_entry.
283 archive_read_data()
284 Read data associated with the header just read. Internally, this
285 is a convenience function that calls archive_read_data_block()
286 and fills any gaps with nulls so that callers see a single con‐
287 tinuous stream of data.
288 archive_read_data_block()
289 Return the next available block of data for this entry. Unlike
290 archive_read_data(), the archive_read_data_block() function
291 avoids copying data and allows you to correctly handle sparse
292 files, as supported by some archive formats. The library guaran‐
293 tees that offsets will increase and that blocks will not overlap.
294 Note that the blocks returned from this function can be much
295 larger than the block size read from disk, due to compression and
296 internal buffer optimizations.
297 archive_read_data_skip()
298 A convenience function that repeatedly calls
299 archive_read_data_block() to skip all of the data for this ar‐
300 chive entry.
301 archive_read_data_into_buffer()
302 This function is deprecated and will be removed. Use
303 archive_read_data() instead.
304 archive_read_data_into_fd()
305 A convenience function that repeatedly calls
306 archive_read_data_block() to copy the entire entry to the pro‐
307 vided file descriptor.
308 archive_read_extract(), archive_read_extract_set_skip_file()
309 A convenience function that wraps the corresponding
310 archive_write_disk(3) interfaces. The first call to
311 archive_read_extract() creates a restore object using
312 archive_write_disk_new(3) and
313 archive_write_disk_set_standard_lookup(3), then transparently
314 invokes archive_write_disk_set_options(3),
315 archive_write_header(3), archive_write_data(3), and
316 archive_write_finish_entry(3) to create the entry on disk and
317 copy data into it. The flags argument is passed unmodified to
318 archive_write_disk_set_options(3).
319 archive_read_extract2()
320 This is another version of archive_read_extract() that allows you
321 to provide your own restore object. In particular, this allows
322 you to override the standard lookup functions using
323 archive_write_disk_set_group_lookup(3), and
324 archive_write_disk_set_user_lookup(3). Note that
325 archive_read_extract2() does not accept a flags argument; you
326 should use archive_write_disk_set_options() to set the restore
327 options yourself.
328 archive_read_extract_set_progress_callback()
329 Sets a pointer to a user-defined callback that can be used for
330 updating progress displays during extraction. The progress func‐
331 tion will be invoked during the extraction of large regular
332 files. The progress function will be invoked with the pointer
333 provided to this call. Generally, the data pointed to should
334 include a reference to the archive object and the archive_entry
335 object so that various statistics can be retrieved for the
336 progress display.
337 archive_read_close()
338 Complete the archive and invoke the close callback.
339 archive_read_finish()
340 Invokes archive_read_close() if it was not invoked manually, then
341 release all resources. Note: In libarchive 1.x, this function
342 was declared to return void, which made it impossible to detect
343 certain errors when archive_read_close() was invoked implicitly
344 from this function. The declaration is corrected beginning with
345 libarchive 2.0.
346 Note that the library determines most of the relevant information about
348 the archive by inspection. In particular, it automatically detects
349 gzip(1) or bzip2(1) compression and transparently performs the appropri‐
350 ate decompression. It also automatically detects the archive format.
351 A complete description of the struct archive and struct archive_entry
353 objects can be found in the overview manual page for libarchive(3).
354
356 The callback functions must match the following prototypes:
357 typedef ssize_t archive_read_callback(struct archive *,
359 void *client_data, const void **buffer)
360 typedef int archive_skip_callback(struct archive *,
362 void *client_data, size_t request)
363 typedef int archive_open_callback(struct archive *, void
365 *client_data)
366 typedef int archive_close_callback(struct archive *, void
368 *client_data)
369 The open callback is invoked by archive_open(). It should return
371 ARCHIVE_OK if the underlying file or data source is successfully opened.
372 If the open fails, it should call archive_set_error() to register an
373 error code and message and return ARCHIVE_FATAL.
374 The read callback is invoked whenever the library requires raw bytes from
376 the archive. The read callback should read data into a buffer, set the
377 const void **buffer argument to point to the available data, and return a
378 count of the number of bytes available. The library will invoke the read
379 callback again only after it has consumed this data. The library imposes
380 no constraints on the size of the data blocks returned. On end-of-file,
381 the read callback should return zero. On error, the read callback should
382 invoke archive_set_error() to register an error code and message and
383 return -1.
384 The skip callback is invoked when the library wants to ignore a block of
386 data. The return value is the number of bytes actually skipped, which
387 may differ from the request. If the callback cannot skip data, it should
388 return zero. If the skip callback is not provided (the function pointer
389 is NULL ), the library will invoke the read function instead and simply
390 discard the result. A skip callback can provide significant performance
391 gains when reading uncompressed archives from slow disk drives or other
392 media that can skip quickly.
393 The close callback is invoked by archive_close when the archive process‐
395 ing is complete. The callback should return ARCHIVE_OK on success. On
396 failure, the callback should invoke archive_set_error() to register an
397 error code and message and return ARCHIVE_FATAL.
398
400 The following illustrates basic usage of the library. In this example,
401 the callback functions are simply wrappers around the standard open(2),
402 read(2), and close(2) system calls.
403 void
405 list_archive(const char *name)
406 {
407 struct mydata *mydata;
408 struct archive *a;
409 struct archive_entry *entry;
410 mydata = malloc(sizeof(struct mydata));
412 a = archive_read_new();
413 mydata->name = name;
414 archive_read_support_compression_all(a);
415 archive_read_support_format_all(a);
416 archive_read_open(a, mydata, myopen, myread, myclose);
417 while (archive_read_next_header(a, &entry) == ARCHIVE_OK) {
418 printf("%s\n",archive_entry_pathname(entry));
419 archive_read_data_skip(a);
420 }
421 archive_read_finish(a);
422 free(mydata);
423 }
424 ssize_t
426 myread(struct archive *a, void *client_data, const void **buff)
427 {
428 struct mydata *mydata = client_data;
429 *buff = mydata->buff;
431 return (read(mydata->fd, mydata->buff, 10240));
432 }
433 int
435 myopen(struct archive *a, void *client_data)
436 {
437 struct mydata *mydata = client_data;
438 mydata->fd = open(mydata->name, O_RDONLY);
440 return (mydata->fd >= 0 ? ARCHIVE_OK : ARCHIVE_FATAL);
441 }
442 int
444 myclose(struct archive *a, void *client_data)
445 {
446 struct mydata *mydata = client_data;
447 if (mydata->fd > 0)
449 close(mydata->fd);
450 return (ARCHIVE_OK);
451 }
452
454 Most functions return zero on success, non-zero on error. The possible
455 return codes include: ARCHIVE_OK (the operation succeeded), ARCHIVE_WARN
456 (the operation succeeded but a non-critical error was encountered),
457 ARCHIVE_EOF (end-of-archive was encountered), ARCHIVE_RETRY (the opera‐
458 tion failed but can be retried), and ARCHIVE_FATAL (there was a fatal
459 error; the archive should be closed immediately). Detailed error codes
460 and textual descriptions are available from the archive_errno() and
461 archive_error_string() functions.
462 archive_read_new() returns a pointer to a freshly allocated struct
464 archive object. It returns NULL on error.
465 archive_read_data() returns a count of bytes actually read or zero at the
467 end of the entry. On error, a value of ARCHIVE_FATAL, ARCHIVE_WARN, or
468 ARCHIVE_RETRY is returned and an error code and textual description can
469 be retrieved from the archive_errno() and archive_error_string() func‐
470 tions.
471 The library expects the client callbacks to behave similarly. If there
473 is an error, you can use archive_set_error() to set an appropriate error
474 code and description, then return one of the non-zero values above.
475 (Note that the value eventually returned to the client may not be the
476 same; many errors that are not critical at the level of basic I/O can
477 prevent the archive from being properly read, thus most I/O errors even‐
478 tually cause ARCHIVE_FATAL to be returned.)
479
481 tar(1), archive(3), archive_util(3), tar(5)
482
484 The libarchive library first appeared in FreeBSD 5.3.
485
487 The libarchive library was written by Tim Kientzle <kientzle@acm.org>.
488
490 Many traditional archiver programs treat empty files as valid empty ar‐
491 chives. For example, many implementations of tar(1) allow you to append
492 entries to an empty file. Of course, it is impossible to determine the
493 format of an empty file by inspecting the contents, so this library
494 treats empty files as having a special “empty” format.
495BSD April 13, 2009 BSD