Rebase libarchive to 2.7.1

1 files changed, 676 insertions, 0 deletions

diff --git a/libarchive/libarchive-2.7.1/doc/man/archive_read.3 b/libarchive/libarchive-2.7.1/doc/man/archive_read.3
new file mode 100644
index 0000000..b0e36b5
--- /dev/null
+++ b/libarchive/libarchive-2.7.1/doc/man/archive_read.3
@@ -0,0 +1,676 @@
+.TH archive_read 3 "August 19, 2006" ""
+.SH NAME
+.ad l
+\fB\%archive_read_new\fP,
+\fB\%archive_read_set_filter_options\fP,
+\fB\%archive_read_set_format_options\fP,
+\fB\%archive_read_set_options\fP,
+\fB\%archive_read_support_compression_all\fP,
+\fB\%archive_read_support_compression_bzip2\fP,
+\fB\%archive_read_support_compression_compress\fP,
+\fB\%archive_read_support_compression_gzip\fP,
+\fB\%archive_read_support_compression_none\fP,
+\fB\%archive_read_support_compression_program\fP,
+\fB\%archive_read_support_format_all\fP,
+\fB\%archive_read_support_format_cpio\fP,
+\fB\%archive_read_support_format_empty\fP,
+\fB\%archive_read_support_format_iso9660\fP,
+\fB\%archive_read_support_format_tar\fP,
+\fB\%archive_read_support_format_zip\fP,
+\fB\%archive_read_open\fP,
+\fB\%archive_read_open2\fP,
+\fB\%archive_read_open_fd\fP,
+\fB\%archive_read_open_FILE\fP,
+\fB\%archive_read_open_filename\fP,
+\fB\%archive_read_open_memory\fP,
+\fB\%archive_read_next_header\fP,
+\fB\%archive_read_next_header2\fP,
+\fB\%archive_read_data\fP,
+\fB\%archive_read_data_block\fP,
+\fB\%archive_read_data_skip\fP,
+\fB\%archive_read_data_into_buffer\fP,
+\fB\%archive_read_data_into_fd\fP,
+\fB\%archive_read_extract\fP,
+\fB\%archive_read_extract2\fP,
+\fB\%archive_read_extract_set_progress_callback\fP,
+\fB\%archive_read_close\fP,
+\fB\%archive_read_finish\fP
+\- functions for reading streaming archives
+.SH SYNOPSIS
+.ad l
+\fB#include <archive.h>\fP
+.br
+\fIstruct archive *\fP
+.br
+\fB\%archive_read_new\fP(\fI\%void\fP);
+.br
+\fIint\fP
+.br
+\fB\%archive_read_support_compression_all\fP(\fI\%struct\ archive\ *\fP);
+.br
+\fIint\fP
+.br
+\fB\%archive_read_support_compression_bzip2\fP(\fI\%struct\ archive\ *\fP);
+.br
+\fIint\fP
+.br
+\fB\%archive_read_support_compression_compress\fP(\fI\%struct\ archive\ *\fP);
+.br
+\fIint\fP
+.br
+\fB\%archive_read_support_compression_gzip\fP(\fI\%struct\ archive\ *\fP);
+.br
+\fIint\fP
+.br
+\fB\%archive_read_support_compression_none\fP(\fI\%struct\ archive\ *\fP);
+.br
+\fIint\fP
+.br
+\fB\%archive_read_support_compression_program\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ char\ *cmd\fP);
+.br
+\fIint\fP
+.br
+\fB\%archive_read_support_format_all\fP(\fI\%struct\ archive\ *\fP);
+.br
+\fIint\fP
+.br
+\fB\%archive_read_support_format_cpio\fP(\fI\%struct\ archive\ *\fP);
+.br
+\fIint\fP
+.br
+\fB\%archive_read_support_format_empty\fP(\fI\%struct\ archive\ *\fP);
+.br
+\fIint\fP
+.br
+\fB\%archive_read_support_format_iso9660\fP(\fI\%struct\ archive\ *\fP);
+.br
+\fIint\fP
+.br
+\fB\%archive_read_support_format_tar\fP(\fI\%struct\ archive\ *\fP);
+.br
+\fIint\fP
+.br
+\fB\%archive_read_support_format_zip\fP(\fI\%struct\ archive\ *\fP);
+.br
+\fIint\fP
+.br
+\fB\%archive_read_set_filter_options\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ char\ *\fP);
+.br
+\fIint\fP
+.br
+\fB\%archive_read_set_format_options\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ char\ *\fP);
+.br
+\fIint\fP
+.br
+\fB\%archive_read_set_options\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ char\ *\fP);
+.br
+\fIint\fP
+.br
+\fB\%archive_read_open\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *client_data\fP, \fI\%archive_open_callback\ *\fP, \fI\%archive_read_callback\ *\fP, \fI\%archive_close_callback\ *\fP);
+.br
+\fIint\fP
+.br
+\fB\%archive_read_open2\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *client_data\fP, \fI\%archive_open_callback\ *\fP, \fI\%archive_read_callback\ *\fP, \fI\%archive_skip_callback\ *\fP, \fI\%archive_close_callback\ *\fP);
+.br
+\fIint\fP
+.br
+\fB\%archive_read_open_FILE\fP(\fI\%struct\ archive\ *\fP, \fI\%FILE\ *file\fP);
+.br
+\fIint\fP
+.br
+\fB\%archive_read_open_fd\fP(\fI\%struct\ archive\ *\fP, \fI\%int\ fd\fP, \fI\%size_t\ block_size\fP);
+.br
+\fIint\fP
+.br
+\fB\%archive_read_open_filename\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ char\ *filename\fP, \fI\%size_t\ block_size\fP);
+.br
+\fIint\fP
+.br
+\fB\%archive_read_open_memory\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *buff\fP, \fI\%size_t\ size\fP);
+.br
+\fIint\fP
+.br
+\fB\%archive_read_next_header\fP(\fI\%struct\ archive\ *\fP, \fI\%struct\ archive_entry\ **\fP);
+.br
+\fIint\fP
+.br
+\fB\%archive_read_next_header2\fP(\fI\%struct\ archive\ *\fP, \fI\%struct\ archive_entry\ *\fP);
+.br
+\fIssize_t\fP
+.br
+\fB\%archive_read_data\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *buff\fP, \fI\%size_t\ len\fP);
+.br
+\fIint\fP
+.br
+\fB\%archive_read_data_block\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ void\ **buff\fP, \fI\%size_t\ *len\fP, \fI\%off_t\ *offset\fP);
+.br
+\fIint\fP
+.br
+\fB\%archive_read_data_skip\fP(\fI\%struct\ archive\ *\fP);
+.br
+\fIint\fP
+.br
+\fB\%archive_read_data_into_buffer\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *\fP, \fI\%ssize_t\ len\fP);
+.br
+\fIint\fP
+.br
+\fB\%archive_read_data_into_fd\fP(\fI\%struct\ archive\ *\fP, \fI\%int\ fd\fP);
+.br
+\fIint\fP
+.br
+\fB\%archive_read_extract\fP(\fI\%struct\ archive\ *\fP, \fI\%struct\ archive_entry\ *\fP, \fI\%int\ flags\fP);
+.br
+\fIint\fP
+.br
+\fB\%archive_read_extract2\fP(\fI\%struct\ archive\ *src\fP, \fI\%struct\ archive_entry\ *\fP, \fI\%struct\ archive\ *dest\fP);
+.br
+\fIvoid\fP
+.br
+\fB\%archive_read_extract_set_progress_callback\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ (*func)(void\ *)\fP, \fI\%void\ *user_data\fP);
+.br
+\fIint\fP
+.br
+\fB\%archive_read_close\fP(\fI\%struct\ archive\ *\fP);
+.br
+\fIint\fP
+.br
+\fB\%archive_read_finish\fP(\fI\%struct\ archive\ *\fP);
+.SH DESCRIPTION
+.ad l
+These functions provide a complete API for reading streaming archives.
+The general process is to first create the
+Tn struct archive
+object, set options, initialize the reader, iterate over the archive
+headers and associated data, then close the archive and release all
+resources.
+The following summary describes the functions in approximately the
+order they would be used:
+.RS 5
+.TP
+\fB\%archive_read_new\fP()
+Allocates and initializes a
+Tn struct archive
+object suitable for reading from an archive.
+.TP
+\fB\%archive_read_support_compression_all\fP(),
+\fB\%archive_read_support_compression_bzip2\fP(),
+\fB\%archive_read_support_compression_compress\fP(),
+\fB\%archive_read_support_compression_gzip\fP(),
+\fB\%archive_read_support_compression_none\fP()
+Enables auto-detection code and decompression support for the
+specified compression.
+Note that
+``none''
+is always enabled by default.
+For convenience,
+\fB\%archive_read_support_compression_all\fP()
+enables all available decompression code.
+.TP
+\fB\%archive_read_support_compression_program\fP()
+Data is fed through the specified external program before being dearchived.
+Note that this disables automatic detection of the compression format,
+so it makes no sense to specify this in conjunction with any other
+decompression option.
+.TP
+\fB\%archive_read_support_format_all\fP(),
+\fB\%archive_read_support_format_cpio\fP(),
+\fB\%archive_read_support_format_empty\fP(),
+\fB\%archive_read_support_format_iso9660\fP(),
+\fB\%archive_read_support_format_tar\fP(),
+\fB\%archive_read_support_format_zip\fP()
+Enables support---including auto-detection code---for the
+specified archive format.
+For example,
+\fB\%archive_read_support_format_tar\fP()
+enables support for a variety of standard tar formats, old-style tar,
+ustar, pax interchange format, and many common variants.
+For convenience,
+\fB\%archive_read_support_format_all\fP()
+enables support for all available formats.
+Only empty archives are supported by default.
+.TP
+\fB\%archive_read_set_filter_options\fP(),
+\fB\%archive_read_set_format_options\fP(),
+\fB\%archive_read_set_options\fP()
+Specifies options that will be passed to currently-registered
+filters (including decompression filters) and/or format readers.
+The argument is a comma-separated list of individual options.
+Individual options have one of the following forms:
+.RS 5
+.TP
+\fIoption=value\fP
+The option/value pair will be provided to every module.
+Modules that do not accept an option with this name will ignore it.
+.TP
+\fIoption\fP
+The option will be provided to every module with a value of
+``1''.
+.TP
+\fI!option\fP
+The option will be provided to every module with a NULL value.
+.TP
+\fImodule:option=value\fP, \fImodule:option\fP, \fImodule:!option\fP
+As above, but the corresponding option and value will be provided
+only to modules whose name matches
+\fImodule\fP.
+.RE
+The return value will be
+\fBARCHIVE_OK\fP
+if any module accepts the option, or
+\fBARCHIVE_WARN\fP
+if no module accepted the option, or
+\fBARCHIVE_FATAL\fP
+if there was a fatal error while attempting to process the option.
+.PP
+The currently supported options are:
+.RS 5
+.TP
+Format iso9660
+.RS 5
+.TP
+\fBjoliet\fP
+Support Joliet extensions.
+Defaults to enabled, use
+\fB!joliet\fP
+to disable.
+.RE
+.RE
+.TP
+\fB\%archive_read_open\fP()
+The same as
+\fB\%archive_read_open2\fP(),
+except that the skip callback is assumed to be
+.BR NULL.
+.TP
+\fB\%archive_read_open2\fP()
+Freeze the settings, open the archive, and prepare for reading entries.
+This is the most generic version of this call, which accepts
+four callback functions.
+Most clients will want to use
+\fB\%archive_read_open_filename\fP(),
+\fB\%archive_read_open_FILE\fP(),
+\fB\%archive_read_open_fd\fP(),
+or
+\fB\%archive_read_open_memory\fP()
+instead.
+The library invokes the client-provided functions to obtain
+raw bytes from the archive.
+.TP
+\fB\%archive_read_open_FILE\fP()
+Like
+\fB\%archive_read_open\fP(),
+except that it accepts a
+\fIFILE *\fP
+pointer.
+This function should not be used with tape drives or other devices
+that require strict I/O blocking.
+.TP
+\fB\%archive_read_open_fd\fP()
+Like
+\fB\%archive_read_open\fP(),
+except that it accepts a file descriptor and block size rather than
+a set of function pointers.
+Note that the file descriptor will not be automatically closed at
+end-of-archive.
+This function is safe for use with tape drives or other blocked devices.
+.TP
+\fB\%archive_read_open_file\fP()
+This is a deprecated synonym for
+\fB\%archive_read_open_filename\fP().
+.TP
+\fB\%archive_read_open_filename\fP()
+Like
+\fB\%archive_read_open\fP(),
+except that it accepts a simple filename and a block size.
+A NULL filename represents standard input.
+This function is safe for use with tape drives or other blocked devices.
+.TP
+\fB\%archive_read_open_memory\fP()
+Like
+\fB\%archive_read_open\fP(),
+except that it accepts a pointer and size of a block of
+memory containing the archive data.
+.TP
+\fB\%archive_read_next_header\fP()
+Read the header for the next entry and return a pointer to
+a
+Tn struct archive_entry.
+This is a convenience wrapper around
+\fB\%archive_read_next_header2\fP()
+that uses an internal
+Tn struct archive_entry
+object.
+.TP
+\fB\%archive_read_next_header2\fP()
+Read the header for the next entry and populate the provided
+Tn struct archive_entry.
+.TP
+\fB\%archive_read_data\fP()
+Read data associated with the header just read.
+Internally, this is a convenience function that calls
+\fB\%archive_read_data_block\fP()
+and fills any gaps with nulls so that callers see a single
+continuous stream of data.
+.TP
+\fB\%archive_read_data_block\fP()
+Return the next available block of data for this entry.
+Unlike
+\fB\%archive_read_data\fP(),
+the
+\fB\%archive_read_data_block\fP()
+function avoids copying data and allows you to correctly handle
+sparse files, as supported by some archive formats.
+The library guarantees that offsets will increase and that blocks
+will not overlap.
+Note that the blocks returned from this function can be much larger
+than the block size read from disk, due to compression
+and internal buffer optimizations.
+.TP
+\fB\%archive_read_data_skip\fP()
+A convenience function that repeatedly calls
+\fB\%archive_read_data_block\fP()
+to skip all of the data for this archive entry.
+.TP
+\fB\%archive_read_data_into_buffer\fP()
+This function is deprecated and will be removed.
+Use
+\fB\%archive_read_data\fP()
+instead.
+.TP
+\fB\%archive_read_data_into_fd\fP()
+A convenience function that repeatedly calls
+\fB\%archive_read_data_block\fP()
+to copy the entire entry to the provided file descriptor.
+.TP
+\fB\%archive_read_extract\fP(), \fB\%archive_read_extract_set_skip_file\fP()
+A convenience function that wraps the corresponding
+\fBarchive_write_disk\fP(3)
+interfaces.
+The first call to
+\fB\%archive_read_extract\fP()
+creates a restore object using
+\fBarchive_write_disk_new\fP(3)
+and
+\fBarchive_write_disk_set_standard_lookup\fP(3),
+then transparently invokes
+\fBarchive_write_disk_set_options\fP(3),
+\fBarchive_write_header\fP(3),
+\fBarchive_write_data\fP(3),
+and
+\fBarchive_write_finish_entry\fP(3)
+to create the entry on disk and copy data into it.
+The
+\fIflags\fP
+argument is passed unmodified to
+\fBarchive_write_disk_set_options\fP(3).
+.TP
+\fB\%archive_read_extract2\fP()
+This is another version of
+\fB\%archive_read_extract\fP()
+that allows you to provide your own restore object.
+In particular, this allows you to override the standard lookup functions
+using
+\fBarchive_write_disk_set_group_lookup\fP(3),
+and
+\fBarchive_write_disk_set_user_lookup\fP(3).
+Note that
+\fB\%archive_read_extract2\fP()
+does not accept a
+\fIflags\fP
+argument; you should use
+\fB\%archive_write_disk_set_options\fP()
+to set the restore options yourself.
+.TP
+\fB\%archive_read_extract_set_progress_callback\fP()
+Sets a pointer to a user-defined callback that can be used
+for updating progress displays during extraction.
+The progress function will be invoked during the extraction of large
+regular files.
+The progress function will be invoked with the pointer provided to this call.
+Generally, the data pointed to should include a reference to the archive
+object and the archive_entry object so that various statistics
+can be retrieved for the progress display.
+.TP
+\fB\%archive_read_close\fP()
+Complete the archive and invoke the close callback.
+.TP
+\fB\%archive_read_finish\fP()
+Invokes
+\fB\%archive_read_close\fP()
+if it was not invoked manually, then release all resources.
+Note: In libarchive 1.x, this function was declared to return
+\fIvoid ,\fP
+which made it impossible to detect certain errors when
+\fB\%archive_read_close\fP()
+was invoked implicitly from this function.
+The declaration is corrected beginning with libarchive 2.0.
+.RE
+.PP
+Note that the library determines most of the relevant information about
+the archive by inspection.
+In particular, it automatically detects
+\fBgzip\fP(1)
+or
+\fBbzip2\fP(1)
+compression and transparently performs the appropriate decompression.
+It also automatically detects the archive format.
+.PP
+A complete description of the
+Tn struct archive
+and
+Tn struct archive_entry
+objects can be found in the overview manual page for
+\fBlibarchive\fP(3).
+.SH CLIENT CALLBACKS
+.ad l
+The callback functions must match the following prototypes:
+.RS 5
+.IP
+\fItypedef ssize_t\fP
+\fB\%archive_read_callback\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *client_data\fP, \fI\%const\ void\ **buffer\fP)
+.IP
+\fItypedef int\fP
+\fB\%archive_skip_callback\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *client_data\fP, \fI\%size_t\ request\fP)
+.IP
+\fItypedef int\fP
+\fB\%archive_open_callback\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *client_data\fP)
+.IP
+\fItypedef int\fP
+\fB\%archive_close_callback\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *client_data\fP)
+.RE
+.PP
+The open callback is invoked by
+\fB\%archive_open\fP().
+It should return
+\fBARCHIVE_OK\fP
+if the underlying file or data source is successfully
+opened.
+If the open fails, it should call
+\fB\%archive_set_error\fP()
+to register an error code and message and return
+\fBARCHIVE_FATAL\fP.
+.PP
+The read callback is invoked whenever the library
+requires raw bytes from the archive.
+The read callback should read data into a buffer,
+set the
+.RS 4
+const void **buffer
+.RE
+argument to point to the available data, and
+return a count of the number of bytes available.
+The library will invoke the read callback again
+only after it has consumed this data.
+The library imposes no constraints on the size
+of the data blocks returned.
+On end-of-file, the read callback should
+return zero.
+On error, the read callback should invoke
+\fB\%archive_set_error\fP()
+to register an error code and message and
+return -1.
+.PP
+The skip callback is invoked when the
+library wants to ignore a block of data.
+The return value is the number of bytes actually
+skipped, which may differ from the request.
+If the callback cannot skip data, it should return
+zero.
+If the skip callback is not provided (the
+function pointer is
+.BR NULL ),
+the library will invoke the read function
+instead and simply discard the result.
+A skip callback can provide significant
+performance gains when reading uncompressed
+archives from slow disk drives or other media
+that can skip quickly.
+.PP
+The close callback is invoked by archive_close when
+the archive processing is complete.
+The callback should return
+\fBARCHIVE_OK\fP
+on success.
+On failure, the callback should invoke
+\fB\%archive_set_error\fP()
+to register an error code and message and
+return
+\fBARCHIVE_FATAL.\fP
+.SH EXAMPLE
+.ad l
+The following illustrates basic usage of the library.
+In this example,
+the callback functions are simply wrappers around the standard
+\fBopen\fP(2),
+\fBread\fP(2),
+and
+\fBclose\fP(2)
+system calls.
+.RS 4
+.nf
+void
+list_archive(const char *name)
+{
+  struct mydata *mydata;
+  struct archive *a;
+  struct archive_entry *entry;
+  mydata = malloc(sizeof(struct mydata));
+  a = archive_read_new();
+  mydata->name = name;
+  archive_read_support_compression_all(a);
+  archive_read_support_format_all(a);
+  archive_read_open(a, mydata, myopen, myread, myclose);
+  while (archive_read_next_header(a, &entry) == ARCHIVE_OK) {
+    printf("%s\\n",archive_entry_pathname(entry));
+    archive_read_data_skip(a);
+  }
+  archive_read_finish(a);
+  free(mydata);
+}
+ssize_t
+myread(struct archive *a, void *client_data, const void **buff)
+{
+  struct mydata *mydata = client_data;
+  *buff = mydata->buff;
+  return (read(mydata->fd, mydata->buff, 10240));
+}
+int
+myopen(struct archive *a, void *client_data)
+{
+  struct mydata *mydata = client_data;
+  mydata->fd = open(mydata->name, O_RDONLY);
+  return (mydata->fd >= 0 ? ARCHIVE_OK : ARCHIVE_FATAL);
+}
+int
+myclose(struct archive *a, void *client_data)
+{
+  struct mydata *mydata = client_data;
+  if (mydata->fd > 0)
+    close(mydata->fd);
+  return (ARCHIVE_OK);
+}
+.RE
+.SH RETURN VALUES
+.ad l
+Most functions return zero on success, non-zero on error.
+The possible return codes include:
+\fBARCHIVE_OK\fP
+(the operation succeeded),
+\fBARCHIVE_WARN\fP
+(the operation succeeded but a non-critical error was encountered),
+\fBARCHIVE_EOF\fP
+(end-of-archive was encountered),
+\fBARCHIVE_RETRY\fP
+(the operation failed but can be retried),
+and
+\fBARCHIVE_FATAL\fP
+(there was a fatal error; the archive should be closed immediately).
+Detailed error codes and textual descriptions are available from the
+\fB\%archive_errno\fP()
+and
+\fB\%archive_error_string\fP()
+functions.
+.PP
+\fB\%archive_read_new\fP()
+returns a pointer to a freshly allocated
+Tn struct archive
+object.
+It returns
+.BR NULL
+on error.
+.PP
+\fB\%archive_read_data\fP()
+returns a count of bytes actually read or zero at the end of the entry.
+On error, a value of
+\fBARCHIVE_FATAL\fP,
+\fBARCHIVE_WARN\fP,
+or
+\fBARCHIVE_RETRY\fP
+is returned and an error code and textual description can be retrieved from the
+\fB\%archive_errno\fP()
+and
+\fB\%archive_error_string\fP()
+functions.
+.PP
+The library expects the client callbacks to behave similarly.
+If there is an error, you can use
+\fB\%archive_set_error\fP()
+to set an appropriate error code and description,
+then return one of the non-zero values above.
+(Note that the value eventually returned to the client may
+not be the same; many errors that are not critical at the level
+of basic I/O can prevent the archive from being properly read,
+thus most I/O errors eventually cause
+\fBARCHIVE_FATAL\fP
+to be returned.)
+.SH SEE ALSO
+.ad l
+\fBtar\fP(1),
+\fBarchive\fP(3),
+\fBarchive_util\fP(3),
+\fBtar\fP(5)
+.SH HISTORY
+.ad l
+The
+\fB\%libarchive\fP
+library first appeared in
+FreeBSD 5.3.
+.SH AUTHORS
+.ad l
+-nosplit
+The
+\fB\%libarchive\fP
+library was written by
+Tim Kientzle \%<kientzle@acm.org.>
+.SH BUGS
+.ad l
+Many traditional archiver programs treat
+empty files as valid empty archives.
+For example, many implementations of
+\fBtar\fP(1)
+allow you to append entries to an empty file.
+Of course, it is impossible to determine the format of an empty file
+by inspecting the contents, so this library treats empty files as
+having a special
+``empty''
+format.