contrib/libarchive-2/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.37 2008/05/26 17:00:22 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_compression_program ,
  38 .Nm archive_read_support_format_all ,
  39 .Nm archive_read_support_format_cpio ,
  40 .Nm archive_read_support_format_empty ,
  41 .Nm archive_read_support_format_iso9660 ,
  42 .Nm archive_read_support_format_tar ,
  43 .Nm archive_read_support_format_zip ,
  44 .Nm archive_read_open ,
  45 .Nm archive_read_open2 ,
  46 .Nm archive_read_open_fd ,
  47 .Nm archive_read_open_FILE ,
  48 .Nm archive_read_open_filename ,
  49 .Nm archive_read_open_memory ,
  50 .Nm archive_read_next_header ,
  51 .Nm archive_read_data ,
  52 .Nm archive_read_data_block ,
  53 .Nm archive_read_data_skip ,
  54 .\" #if ARCHIVE_API_VERSION < 3
  55 .Nm archive_read_data_into_buffer ,
  56 .\" #endif
  57 .Nm archive_read_data_into_fd ,
  58 .Nm archive_read_extract ,
  59 .Nm archive_read_extract2 ,
  60 .Nm archive_read_extract_set_progress_callback ,
  61 .Nm archive_read_close ,
  62 .Nm archive_read_finish
  63 .Nd functions for reading streaming archives
  64 .Sh SYNOPSIS
  65 .In archive.h
  66 .Ft struct archive *
  67 .Fn archive_read_new "void"
  68 .Ft int
  69 .Fn archive_read_support_compression_all "struct archive *"
  70 .Ft int
  71 .Fn archive_read_support_compression_bzip2 "struct archive *"
  72 .Ft int
  73 .Fn archive_read_support_compression_compress "struct archive *"
  74 .Ft int
  75 .Fn archive_read_support_compression_gzip "struct archive *"
  76 .Ft int
  77 .Fn archive_read_support_compression_none "struct archive *"
  78 .Ft int
  79 .Fo archive_read_support_compression_program
  80 .Fa "struct archive *"
  81 .Fa "const char *cmd"
  82 .Fc
  83 .Ft int
  84 .Fn archive_read_support_format_all "struct archive *"
  85 .Ft int
  86 .Fn archive_read_support_format_cpio "struct archive *"
  87 .Ft int
  88 .Fn archive_read_support_format_empty "struct archive *"
  89 .Ft int
  90 .Fn archive_read_support_format_iso9660 "struct archive *"
  91 .Ft int
  92 .Fn archive_read_support_format_tar "struct archive *"
  93 .Ft int
  94 .Fn archive_read_support_format_zip "struct archive *"
  95 .Ft int
  96 .Fo archive_read_open
  97 .Fa "struct archive *"
  98 .Fa "void *client_data"
  99 .Fa "archive_open_callback *"
 100 .Fa "archive_read_callback *"
 101 .Fa "archive_close_callback *"
 102 .Fc
 103 .Ft int
 104 .Fo archive_read_open2
 105 .Fa "struct archive *"
 106 .Fa "void *client_data"
 107 .Fa "archive_open_callback *"
 108 .Fa "archive_read_callback *"
 109 .Fa "archive_skip_callback *"
 110 .Fa "archive_close_callback *"
 111 .Fc
 112 .Ft int
 113 .Fn archive_read_open_FILE "struct archive *" "FILE *file"
 114 .Ft int
 115 .Fn archive_read_open_fd "struct archive *" "int fd" "size_t block_size"
 116 .Ft int
 117 .Fo archive_read_open_filename
 118 .Fa "struct archive *"
 119 .Fa "const char *filename"
 120 .Fa "size_t block_size"
 121 .Fc
 122 .Ft int
 123 .Fn archive_read_open_memory "struct archive *" "void *buff" "size_t size"
 124 .Ft int
 125 .Fn archive_read_next_header "struct archive *" "struct archive_entry **"
 126 .Ft ssize_t
 127 .Fn archive_read_data "struct archive *" "void *buff" "size_t len"
 128 .Ft int
 129 .Fo archive_read_data_block
 130 .Fa "struct archive *"
 131 .Fa "const void **buff"
 132 .Fa "size_t *len"
 133 .Fa "off_t *offset"
 134 .Fc
 135 .Ft int
 136 .Fn archive_read_data_skip "struct archive *"
 137 .\" #if ARCHIVE_API_VERSION < 3
 138 .Ft int
 139 .Fn archive_read_data_into_buffer "struct archive *" "void *" "ssize_t len"
 140 .\" #endif
 141 .Ft int
 142 .Fn archive_read_data_into_fd "struct archive *" "int fd"
 143 .Ft int
 144 .Fo archive_read_extract
 145 .Fa "struct archive *"
 146 .Fa "struct archive_entry *"
 147 .Fa "int flags"
 148 .Fc
 149 .Ft int
 150 .Fo archive_read_extract2
 151 .Fa "struct archive *src"
 152 .Fa "struct archive_entry *"
 153 .Fa "struct archive *dest"
 154 .Fc
 155 .Ft void
 156 .Fo archive_read_extract_set_progress_callback
 157 .Fa "struct archive *"
 158 .Fa "void (*func)(void *)"
 159 .Fa "void *user_data"
 160 .Fc
 161 .Ft int
 162 .Fn archive_read_close "struct archive *"
 163 .Ft int
 164 .Fn archive_read_finish "struct archive *"
 165 .Sh DESCRIPTION
 166 These functions provide a complete API for reading streaming archives.
 167 The general process is to first create the
 168 .Tn struct archive
 169 object, set options, initialize the reader, iterate over the archive
 170 headers and associated data, then close the archive and release all
 171 resources.
 172 The following summary describes the functions in approximately the
 173 order they would be used:
 174 .Bl -tag -compact -width indent
 175 .It Fn archive_read_new
 176 Allocates and initializes a
 177 .Tn struct archive
 178 object suitable for reading from an archive.
 179 .It Xo
 180 .Fn archive_read_support_compression_all ,
 181 .Fn archive_read_support_compression_bzip2 ,
 182 .Fn archive_read_support_compression_compress ,
 183 .Fn archive_read_support_compression_gzip ,
 184 .Fn archive_read_support_compression_none
 185 .Xc
 186 Enables auto-detection code and decompression support for the
 187 specified compression.
 188 Note that
 189 .Dq none
 190 is always enabled by default.
 191 For convenience,
 192 .Fn archive_read_support_compression_all
 193 enables all available decompression code.
 194 .It Fn archive_read_support_compression_program
 195 Data is fed through the specified external program before being dearchived.
 196 Note that this disables automatic detection of the compression format,
 197 so it makes no sense to specify this in conjunction with any other
 198 decompression option.
 199 .It Xo
 200 .Fn archive_read_support_format_all ,
 201 .Fn archive_read_support_format_cpio ,
 202 .Fn archive_read_support_format_empty ,
 203 .Fn archive_read_support_format_iso9660 ,
 204 .Fn archive_read_support_format_tar ,
 205 .Fn archive_read_support_format_zip
 206 .Xc
 207 Enables support---including auto-detection code---for the
 208 specified archive format.
 209 For example,
 210 .Fn archive_read_support_format_tar
 211 enables support for a variety of standard tar formats, old-style tar,
 212 ustar, pax interchange format, and many common variants.
 213 For convenience,
 214 .Fn archive_read_support_format_all
 215 enables support for all available formats.
 216 Only empty archives are supported by default.
 217 .It Fn archive_read_open
 218 The same as
 219 .Fn archive_read_open2 ,
 220 except that the skip callback is assumed to be
 221 .Dv NULL .
 222 .It Fn archive_read_open2
 223 Freeze the settings, open the archive, and prepare for reading entries.
 224 This is the most generic version of this call, which accepts
 225 four callback functions.
 226 Most clients will want to use
 227 .Fn archive_read_open_filename ,
 228 .Fn archive_read_open_FILE ,
 229 .Fn archive_read_open_fd ,
 230 or
 231 .Fn archive_read_open_memory
 232 instead.
 233 The library invokes the client-provided functions to obtain
 234 raw bytes from the archive.
 235 .It Fn archive_read_open_FILE
 236 Like
 237 .Fn archive_read_open ,
 238 except that it accepts a
 239 .Ft "FILE *"
 240 pointer.
 241 This function should not be used with tape drives or other devices
 242 that require strict I/O blocking.
 243 .It Fn archive_read_open_fd
 244 Like
 245 .Fn archive_read_open ,
 246 except that it accepts a file descriptor and block size rather than
 247 a set of function pointers.
 248 Note that the file descriptor will not be automatically closed at
 249 end-of-archive.
 250 This function is safe for use with tape drives or other blocked devices.
 251 .It Fn archive_read_open_file
 252 This is a deprecated synonym for
 253 .Fn archive_read_open_filename .
 254 .It Fn archive_read_open_filename
 255 Like
 256 .Fn archive_read_open ,
 257 except that it accepts a simple filename and a block size.
 258 A NULL filename represents standard input.
 259 This function is safe for use with tape drives or other blocked devices.
 260 .It Fn archive_read_open_memory
 261 Like
 262 .Fn archive_read_open ,
 263 except that it accepts a pointer and size of a block of
 264 memory containing the archive data.
 265 .It Fn archive_read_next_header
 266 Read the header for the next entry and return a pointer to
 267 a
 268 .Tn struct archive_entry .
 269 .It Fn archive_read_data
 270 Read data associated with the header just read.
 271 Internally, this is a convenience function that calls
 272 .Fn archive_read_data_block
 273 and fills any gaps with nulls so that callers see a single
 274 continuous stream of data.
 275 .It Fn archive_read_data_block
 276 Return the next available block of data for this entry.
 277 Unlike
 278 .Fn archive_read_data ,
 279 the
 280 .Fn archive_read_data_block
 281 function avoids copying data and allows you to correctly handle
 282 sparse files, as supported by some archive formats.
 283 The library guarantees that offsets will increase and that blocks
 284 will not overlap.
 285 Note that the blocks returned from this function can be much larger
 286 than the block size read from disk, due to compression
 287 and internal buffer optimizations.
 288 .It Fn archive_read_data_skip
 289 A convenience function that repeatedly calls
 290 .Fn archive_read_data_block
 291 to skip all of the data for this archive entry.
 292 .\" #if ARCHIVE_API_VERSION < 3
 293 .It Fn archive_read_data_into_buffer
 294 This function is deprecated and will be removed.
 295 Use
 296 .Fn archive_read_data
 297 instead.
 298 .\" #endif
 299 .It Fn archive_read_data_into_fd
 300 A convenience function that repeatedly calls
 301 .Fn archive_read_data_block
 302 to copy the entire entry to the provided file descriptor.
 303 .It Fn archive_read_extract , Fn archive_read_extract_set_skip_file
 304 A convenience function that wraps the corresponding
 305 .Xr archive_write_disk 3
 306 interfaces.
 307 The first call to
 308 .Fn archive_read_extract
 309 creates a restore object using
 310 .Xr archive_write_disk_new 3
 311 and
 312 .Xr archive_write_disk_set_standard_lookup 3 ,
 313 then transparently invokes
 314 .Xr archive_write_disk_set_options 3 ,
 315 .Xr archive_write_header 3 ,
 316 .Xr archive_write_data 3 ,
 317 and
 318 .Xr archive_write_finish_entry 3
 319 to create the entry on disk and copy data into it.
 320 The
 321 .Va flags
 322 argument is passed unmodified to
 323 .Xr archive_write_disk_set_options 3 .
 324 .It Fn archive_read_extract2
 325 This is another version of
 326 .Fn archive_read_extract
 327 that allows you to provide your own restore object.
 328 In particular, this allows you to override the standard lookup functions
 329 using
 330 .Xr archive_write_disk_set_group_lookup 3 ,
 331 and
 332 .Xr archive_write_disk_set_user_lookup 3 .
 333 Note that
 334 .Fn archive_read_extract2
 335 does not accept a
 336 .Va flags
 337 argument; you should use
 338 .Fn archive_write_disk_set_options
 339 to set the restore options yourself.
 340 .It Fn archive_read_extract_set_progress_callback
 341 Sets a pointer to a user-defined callback that can be used
 342 for updating progress displays during extraction.
 343 The progress function will be invoked during the extraction of large
 344 regular files.
 345 The progress function will be invoked with the pointer provided to this call.
 346 Generally, the data pointed to should include a reference to the archive
 347 object and the archive_entry object so that various statistics
 348 can be retrieved for the progress display.
 349 .It Fn archive_read_close
 350 Complete the archive and invoke the close callback.
 351 .It Fn archive_read_finish
 352 Invokes
 353 .Fn archive_read_close
 354 if it was not invoked manually, then release all resources.
 355 Note: In libarchive 1.x, this function was declared to return
 356 .Ft void ,
 357 which made it impossible to detect certain errors when
 358 .Fn archive_read_close
 359 was invoked implicitly from this function.
 360 The declaration is corrected beginning with libarchive 2.0.
 361 .El
 362 .Pp
 363 Note that the library determines most of the relevant information about
 364 the archive by inspection.
 365 In particular, it automatically detects
 366 .Xr gzip 1
 367 or
 368 .Xr bzip2 1
 369 compression and transparently performs the appropriate decompression.
 370 It also automatically detects the archive format.
 371 .Pp
 372 A complete description of the
 373 .Tn struct archive
 374 and
 375 .Tn struct archive_entry
 376 objects can be found in the overview manual page for
 377 .Xr libarchive 3 .
 378 .Sh CLIENT CALLBACKS
 379 The callback functions must match the following prototypes:
 380 .Bl -item -offset indent
 381 .It
 382 .Ft typedef ssize_t
 383 .Fo archive_read_callback
 384 .Fa "struct archive *"
 385 .Fa "void *client_data"
 386 .Fa "const void **buffer"
 387 .Fc
 388 .It
 389 .\" #if ARCHIVE_API_VERSION < 2
 390 .Ft typedef int
 391 .Fo archive_skip_callback
 392 .Fa "struct archive *"
 393 .Fa "void *client_data"
 394 .Fa "size_t request"
 395 .Fc
 396 .\" #else
 397 .\" .Ft typedef off_t
 398 .\" .Fo archive_skip_callback
 399 .\" .Fa "struct archive *"
 400 .\" .Fa "void *client_data"
 401 .\" .Fa "off_t request"
 402 .\" .Fc
 403 .\" #endif
 404 .It
 405 .Ft typedef int
 406 .Fn archive_open_callback "struct archive *" "void *client_data"
 407 .It
 408 .Ft typedef int
 409 .Fn archive_close_callback "struct archive *" "void *client_data"
 410 .El
 411 .Pp
 412 The open callback is invoked by
 413 .Fn archive_open .
 414 It should return
 415 .Cm ARCHIVE_OK
 416 if the underlying file or data source is successfully
 417 opened.
 418 If the open fails, it should call
 419 .Fn archive_set_error
 420 to register an error code and message and return
 421 .Cm ARCHIVE_FATAL .
 422 .Pp
 423 The read callback is invoked whenever the library
 424 requires raw bytes from the archive.
 425 The read callback should read data into a buffer,
 426 set the
 427 .Li const void **buffer
 428 argument to point to the available data, and
 429 return a count of the number of bytes available.
 430 The library will invoke the read callback again
 431 only after it has consumed this data.
 432 The library imposes no constraints on the size
 433 of the data blocks returned.
 434 On end-of-file, the read callback should
 435 return zero.
 436 On error, the read callback should invoke
 437 .Fn archive_set_error
 438 to register an error code and message and
 439 return -1.
 440 .Pp
 441 The skip callback is invoked when the
 442 library wants to ignore a block of data.
 443 The return value is the number of bytes actually
 444 skipped, which may differ from the request.
 445 If the callback cannot skip data, it should return
 446 zero.
 447 If the skip callback is not provided (the
 448 function pointer is
 449 .Dv NULL ),
 450 the library will invoke the read function
 451 instead and simply discard the result.
 452 A skip callback can provide significant
 453 performance gains when reading uncompressed
 454 archives from slow disk drives or other media
 455 that can skip quickly.
 456 .Pp
 457 The close callback is invoked by archive_close when
 458 the archive processing is complete.
 459 The callback should return
 460 .Cm ARCHIVE_OK
 461 on success.
 462 On failure, the callback should invoke
 463 .Fn archive_set_error
 464 to register an error code and message and
 465 return
 466 .Cm ARCHIVE_FATAL.
 467 .Sh EXAMPLE
 468 The following illustrates basic usage of the library.
 469 In this example,
 470 the callback functions are simply wrappers around the standard
 471 .Xr open 2 ,
 472 .Xr read 2 ,
 473 and
 474 .Xr close 2
 475 system calls.
 476 .Bd -literal -offset indent
 477 void
 478 list_archive(const char *name)
 479 {
 480   struct mydata *mydata;
 481   struct archive *a;
 482   struct archive_entry *entry;
 483
 484   mydata = malloc(sizeof(struct mydata));
 485   a = archive_read_new();
 486   mydata->name = name;
 487   archive_read_support_compression_all(a);
 488   archive_read_support_format_all(a);
 489   archive_read_open(a, mydata, myopen, myread, myclose);
 490   while (archive_read_next_header(a, &entry) == ARCHIVE_OK) {
 491     printf("%s\\n",archive_entry_pathname(entry));
 492     archive_read_data_skip(a);
 493   }
 494   archive_read_finish(a);
 495   free(mydata);
 496 }
 497
 498 ssize_t
 499 myread(struct archive *a, void *client_data, const void **buff)
 500 {
 501   struct mydata *mydata = client_data;
 502
 503   *buff = mydata->buff;
 504   return (read(mydata->fd, mydata->buff, 10240));
 505 }
 506
 507 int
 508 myopen(struct archive *a, void *client_data)
 509 {
 510   struct mydata *mydata = client_data;
 511
 512   mydata->fd = open(mydata->name, O_RDONLY);
 513   return (mydata->fd >= 0 ? ARCHIVE_OK : ARCHIVE_FATAL);
 514 }
 515
 516 int
 517 myclose(struct archive *a, void *client_data)
 518 {
 519   struct mydata *mydata = client_data;
 520
 521   if (mydata->fd > 0)
 522     close(mydata->fd);
 523   return (ARCHIVE_OK);
 524 }
 525 .Ed
 526 .Sh RETURN VALUES
 527 Most functions return zero on success, non-zero on error.
 528 The possible return codes include:
 529 .Cm ARCHIVE_OK
 530 (the operation succeeded),
 531 .Cm ARCHIVE_WARN
 532 (the operation succeeded but a non-critical error was encountered),
 533 .Cm ARCHIVE_EOF
 534 (end-of-archive was encountered),
 535 .Cm ARCHIVE_RETRY
 536 (the operation failed but can be retried),
 537 and
 538 .Cm ARCHIVE_FATAL
 539 (there was a fatal error; the archive should be closed immediately).
 540 Detailed error codes and textual descriptions are available from the
 541 .Fn archive_errno
 542 and
 543 .Fn archive_error_string
 544 functions.
 545 .Pp
 546 .Fn archive_read_new
 547 returns a pointer to a freshly allocated
 548 .Tn struct archive
 549 object.
 550 It returns
 551 .Dv NULL
 552 on error.
 553 .Pp
 554 .Fn archive_read_data
 555 returns a count of bytes actually read or zero at the end of the entry.
 556 On error, a value of
 557 .Cm ARCHIVE_FATAL ,
 558 .Cm ARCHIVE_WARN ,
 559 or
 560 .Cm ARCHIVE_RETRY
 561 is returned and an error code and textual description can be retrieved from the
 562 .Fn archive_errno
 563 and
 564 .Fn archive_error_string
 565 functions.
 566 .Pp
 567 The library expects the client callbacks to behave similarly.
 568 If there is an error, you can use
 569 .Fn archive_set_error
 570 to set an appropriate error code and description,
 571 then return one of the non-zero values above.
 572 (Note that the value eventually returned to the client may
 573 not be the same; many errors that are not critical at the level
 574 of basic I/O can prevent the archive from being properly read,
 575 thus most I/O errors eventually cause
 576 .Cm ARCHIVE_FATAL
 577 to be returned.)
 578 .\" .Sh ERRORS
 579 .Sh SEE ALSO
 580 .Xr tar 1 ,
 581 .Xr archive 3 ,
 582 .Xr archive_util 3 ,
 583 .Xr tar 5
 584 .Sh HISTORY
 585 The
 586 .Nm libarchive
 587 library first appeared in
 588 .Fx 5.3 .
 589 .Sh AUTHORS
 590 .An -nosplit
 591 The
 592 .Nm libarchive
 593 library was written by
 594 .An Tim Kientzle Aq kientzle@acm.org .
 595 .Sh BUGS
 596 Many traditional archiver programs treat
 597 empty files as valid empty archives.
 598 For example, many implementations of
 599 .Xr tar 1
 600 allow you to append entries to an empty file.
 601 Of course, it is impossible to determine the format of an empty file
 602 by inspecting the contents, so this library treats empty files as
 603 having a special
 604 .Dq empty
 605 format.