archivers/libarchive/files/doc/text/archive_read.3.txt

   1 archive_read(3)         NetBSD Library Functions Manual        archive_read(3)
   2
   3 NAME
   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
  28 SYNOPSIS
  29      #include <archive.h>
  30
  31      struct archive *
  32      archive_read_new(void);
  33
  34      int
  35      archive_read_support_compression_all(struct archive *);
  36
  37      int
  38      archive_read_support_compression_bzip2(struct archive *);
  39
  40      int
  41      archive_read_support_compression_compress(struct archive *);
  42
  43      int
  44      archive_read_support_compression_gzip(struct archive *);
  45
  46      int
  47      archive_read_support_compression_lzma(struct archive *);
  48
  49      int
  50      archive_read_support_compression_none(struct archive *);
  51
  52      int
  53      archive_read_support_compression_xz(struct archive *);
  54
  55      int
  56      archive_read_support_compression_program(struct archive *,
  57          const char *cmd);
  58
  59      int
  60      archive_read_support_compression_program_signature(struct archive *,
  61          const char *cmd, const void *signature, size_t signature_length);
  62
  63      int
  64      archive_read_support_format_all(struct archive *);
  65
  66      int
  67      archive_read_support_format_ar(struct archive *);
  68
  69      int
  70      archive_read_support_format_cpio(struct archive *);
  71
  72      int
  73      archive_read_support_format_empty(struct archive *);
  74
  75      int
  76      archive_read_support_format_iso9660(struct archive *);
  77
  78      int
  79      archive_read_support_format_mtree(struct archive *);
  80
  81      int
  82      archive_read_support_format_raw(struct archive *);
  83
  84      int
  85      archive_read_support_format_tar(struct archive *);
  86
  87      int
  88      archive_read_support_format_zip(struct archive *);
  89
  90      int
  91      archive_read_set_filter_options(struct archive *, const char *);
  92
  93      int
  94      archive_read_set_format_options(struct archive *, const char *);
  95
  96      int
  97      archive_read_set_options(struct archive *, const char *);
  98
  99      int
 100      archive_read_open(struct archive *, void *client_data,
 101          archive_open_callback *, archive_read_callback *,
 102          archive_close_callback *);
 103
 104      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
 109      int
 110      archive_read_open_FILE(struct archive *, FILE *file);
 111
 112      int
 113      archive_read_open_fd(struct archive *, int fd, size_t block_size);
 114
 115      int
 116      archive_read_open_filename(struct archive *, const char *filename,
 117          size_t block_size);
 118
 119      int
 120      archive_read_open_memory(struct archive *, void *buff, size_t size);
 121
 122      int
 123      archive_read_next_header(struct archive *, struct archive_entry **);
 124
 125      int
 126      archive_read_next_header2(struct archive *, struct archive_entry *);
 127
 128      ssize_t
 129      archive_read_data(struct archive *, void *buff, size_t len);
 130
 131      int
 132      archive_read_data_block(struct archive *, const void **buff, size_t *len,
 133          off_t *offset);
 134
 135      int
 136      archive_read_data_skip(struct archive *);
 137
 138      int
 139      archive_read_data_into_buffer(struct archive *, void *, ssize_t len);
 140
 141      int
 142      archive_read_data_into_fd(struct archive *, int fd);
 143
 144      int
 145      archive_read_extract(struct archive *, struct archive_entry *,
 146          int flags);
 147
 148      int
 149      archive_read_extract2(struct archive *src, struct archive_entry *,
 150          struct archive *dest);
 151
 152      void
 153      archive_read_extract_set_progress_callback(struct archive *,
 154          void (*func)(void *), void *user_data);
 155
 156      int
 157      archive_read_close(struct archive *);
 158
 159      int
 160      archive_read_finish(struct archive *);
 161
 162 DESCRIPTION
 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
 240              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
 347      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
 352      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
 355 CLIENT CALLBACKS
 356      The callback functions must match the following prototypes:
 357
 358            typedef ssize_t archive_read_callback(struct archive *,
 359            void *client_data, const void **buffer)
 360
 361            typedef int archive_skip_callback(struct archive *,
 362            void *client_data, size_t request)
 363
 364            typedef int archive_open_callback(struct archive *, void
 365            *client_data)
 366
 367            typedef int archive_close_callback(struct archive *, void
 368            *client_data)
 369
 370      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
 375      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
 385      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
 394      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
 399 EXAMPLE
 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
 404            void
 405            list_archive(const char *name)
 406            {
 407              struct mydata *mydata;
 408              struct archive *a;
 409              struct archive_entry *entry;
 410
 411              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
 425            ssize_t
 426            myread(struct archive *a, void *client_data, const void **buff)
 427            {
 428              struct mydata *mydata = client_data;
 429
 430              *buff = mydata->buff;
 431              return (read(mydata->fd, mydata->buff, 10240));
 432            }
 433
 434            int
 435            myopen(struct archive *a, void *client_data)
 436            {
 437              struct mydata *mydata = client_data;
 438
 439              mydata->fd = open(mydata->name, O_RDONLY);
 440              return (mydata->fd >= 0 ? ARCHIVE_OK : ARCHIVE_FATAL);
 441            }
 442
 443            int
 444            myclose(struct archive *a, void *client_data)
 445            {
 446              struct mydata *mydata = client_data;
 447
 448              if (mydata->fd > 0)
 449                close(mydata->fd);
 450              return (ARCHIVE_OK);
 451            }
 452
 453 RETURN VALUES
 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
 463      archive_read_new() returns a pointer to a freshly allocated struct
 464      archive object.  It returns NULL on error.
 465
 466      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
 472      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
 480 SEE ALSO
 481      tar(1), archive(3), archive_util(3), tar(5)
 482
 483 HISTORY
 484      The libarchive library first appeared in FreeBSD 5.3.
 485
 486 AUTHORS
 487      The libarchive library was written by Tim Kientzle <kientzle@acm.org>.
 488
 489 BUGS
 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.
 495
 496 NetBSD 5.0                      April 13, 2009                      NetBSD 5.0