Update libarchive to v2.5.5

1 files changed, 878 insertions, 0 deletions

diff --git a/libarchive/libarchive-2.5.5/doc/man/archive_read.3 b/libarchive/libarchive-2.5.5/doc/man/archive_read.3
new file mode 100644
index 0000000..91908e8
--- /dev/null
+++ b/libarchive/libarchive-2.5.5/doc/man/archive_read.3
@@ -0,0 +1,878 @@
+.TH archive_read 3 "August 19, 2006" ""
+.SH NAME
+\fBarchive_read_new\fP,
+\fBarchive_read_support_compression_all\fP,
+\fBarchive_read_support_compression_bzip2\fP,
+\fBarchive_read_support_compression_compress\fP,
+\fBarchive_read_support_compression_gzip\fP,
+\fBarchive_read_support_compression_none\fP,
+\fBarchive_read_support_compression_program\fP,
+\fBarchive_read_support_format_all\fP,
+\fBarchive_read_support_format_cpio\fP,
+\fBarchive_read_support_format_empty\fP,
+\fBarchive_read_support_format_iso9660\fP,
+\fBarchive_read_support_format_tar\fP,
+\fBarchive_read_support_format_zip\fP,
+\fBarchive_read_open\fP,
+\fBarchive_read_open2\fP,
+\fBarchive_read_open_fd\fP,
+\fBarchive_read_open_FILE\fP,
+\fBarchive_read_open_filename\fP,
+\fBarchive_read_open_memory\fP,
+\fBarchive_read_next_header\fP,
+\fBarchive_read_data\fP,
+\fBarchive_read_data_block\fP,
+\fBarchive_read_data_skip\fP,
+\fBarchive_read_data_into_buffer\fP,
+\fBarchive_read_data_into_fd\fP,
+\fBarchive_read_extract\fP,
+\fBarchive_read_extract2\fP,
+\fBarchive_read_extract_set_progress_callback\fP,
+\fBarchive_read_close\fP,
+\fBarchive_read_finish\fP
+\- functions for reading streaming archives
+.SH SYNOPSIS
+\fB#include <archive.h>\fP
+.br
+\fIstruct archive *\fP
+.RE
+.nh
+\fBarchive_read_new\fP
+.hy
+("void");
+\fIint\fP
+.RE
+.nh
+\fBarchive_read_support_compression_all\fP
+.hy
+("struct archive *");
+\fIint\fP
+.RE
+.nh
+\fBarchive_read_support_compression_bzip2\fP
+.hy
+("struct archive *");
+\fIint\fP
+.RE
+.nh
+\fBarchive_read_support_compression_compress\fP
+.hy
+("struct archive *");
+\fIint\fP
+.RE
+.nh
+\fBarchive_read_support_compression_gzip\fP
+.hy
+("struct archive *");
+\fIint\fP
+.RE
+.nh
+\fBarchive_read_support_compression_none\fP
+.hy
+("struct archive *");
+\fIint\fP
+.RE
+Fo archive_read_support_compression_program
+Fa "struct archive *"
+Fa "const char *cmd"
+Fc
+\fIint\fP
+.RE
+.nh
+\fBarchive_read_support_format_all\fP
+.hy
+("struct archive *");
+\fIint\fP
+.RE
+.nh
+\fBarchive_read_support_format_cpio\fP
+.hy
+("struct archive *");
+\fIint\fP
+.RE
+.nh
+\fBarchive_read_support_format_empty\fP
+.hy
+("struct archive *");
+\fIint\fP
+.RE
+.nh
+\fBarchive_read_support_format_iso9660\fP
+.hy
+("struct archive *");
+\fIint\fP
+.RE
+.nh
+\fBarchive_read_support_format_tar\fP
+.hy
+("struct archive *");
+\fIint\fP
+.RE
+.nh
+\fBarchive_read_support_format_zip\fP
+.hy
+("struct archive *");
+\fIint\fP
+.RE
+Fo archive_read_open
+Fa "struct archive *"
+Fa "void *client_data"
+Fa "archive_open_callback *"
+Fa "archive_read_callback *"
+Fa "archive_close_callback *"
+Fc
+\fIint\fP
+.RE
+Fo archive_read_open2
+Fa "struct archive *"
+Fa "void *client_data"
+Fa "archive_open_callback *"
+Fa "archive_read_callback *"
+Fa "archive_skip_callback *"
+Fa "archive_close_callback *"
+Fc
+\fIint\fP
+.RE
+.nh
+\fBarchive_read_open_FILE\fP
+.hy
+("struct archive *" "FILE *file");
+\fIint\fP
+.RE
+.nh
+\fBarchive_read_open_fd\fP
+.hy
+("struct archive *" "int fd" "size_t block_size");
+\fIint\fP
+.RE
+Fo archive_read_open_filename
+Fa "struct archive *"
+Fa "const char *filename"
+Fa "size_t block_size"
+Fc
+\fIint\fP
+.RE
+.nh
+\fBarchive_read_open_memory\fP
+.hy
+("struct archive *" "void *buff" "size_t size");
+\fIint\fP
+.RE
+.nh
+\fBarchive_read_next_header\fP
+.hy
+("struct archive *" "struct archive_entry **");
+\fIssize_t\fP
+.RE
+.nh
+\fBarchive_read_data\fP
+.hy
+("struct archive *" "void *buff" "size_t len");
+\fIint\fP
+.RE
+Fo archive_read_data_block
+Fa "struct archive *"
+Fa "const void **buff"
+Fa "size_t *len"
+Fa "off_t *offset"
+Fc
+\fIint\fP
+.RE
+.nh
+\fBarchive_read_data_skip\fP
+.hy
+("struct archive *");
+\fIint\fP
+.RE
+.nh
+\fBarchive_read_data_into_buffer\fP
+.hy
+("struct archive *" "void *" "ssize_t len");
+\fIint\fP
+.RE
+.nh
+\fBarchive_read_data_into_fd\fP
+.hy
+("struct archive *" "int fd");
+\fIint\fP
+.RE
+Fo archive_read_extract
+Fa "struct archive *"
+Fa "struct archive_entry *"
+Fa "int flags"
+Fc
+\fIint\fP
+.RE
+Fo archive_read_extract2
+Fa "struct archive *src"
+Fa "struct archive_entry *"
+Fa "struct archive *dest"
+Fc
+\fIvoid\fP
+.RE
+Fo archive_read_extract_set_progress_callback
+Fa "struct archive *"
+Fa "void (*func)(void *)"
+Fa "void *user_data"
+Fc
+\fIint\fP
+.RE
+.nh
+\fBarchive_read_close\fP
+.hy
+("struct archive *");
+\fIint\fP
+.RE
+.nh
+\fBarchive_read_finish\fP
+.hy
+("struct archive *");
+.SH DESCRIPTION
+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:
+.TP
+.nh
+\fBarchive_read_new\fP
+.hy
+();
+Allocates and initializes a
+Tn struct archive
+object suitable for reading from an archive.
+.TP
+Xo
+.nh
+\fBarchive_read_support_compression_all\fP
+.hy
+(,);
+.nh
+\fBarchive_read_support_compression_bzip2\fP
+.hy
+(,);
+.nh
+\fBarchive_read_support_compression_compress\fP
+.hy
+(,);
+.nh
+\fBarchive_read_support_compression_gzip\fP
+.hy
+(,);
+.nh
+\fBarchive_read_support_compression_none\fP
+.hy
+();
+Xc
+Enables auto-detection code and decompression support for the
+specified compression.
+Note that
+``none''
+is always enabled by default.
+For convenience,
+.nh
+\fBarchive_read_support_compression_all\fP
+.hy
+();
+enables all available decompression code.
+.TP
+.nh
+\fBarchive_read_support_compression_program\fP
+.hy
+();
+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
+Xo
+.nh
+\fBarchive_read_support_format_all\fP
+.hy
+(,);
+.nh
+\fBarchive_read_support_format_cpio\fP
+.hy
+(,);
+.nh
+\fBarchive_read_support_format_empty\fP
+.hy
+(,);
+.nh
+\fBarchive_read_support_format_iso9660\fP
+.hy
+(,);
+.nh
+\fBarchive_read_support_format_tar\fP
+.hy
+(,);
+.nh
+\fBarchive_read_support_format_zip\fP
+.hy
+();
+Xc
+Enables support---including auto-detection code---for the
+specified archive format.
+For example,
+.nh
+\fBarchive_read_support_format_tar\fP
+.hy
+();
+enables support for a variety of standard tar formats, old-style tar,
+ustar, pax interchange format, and many common variants.
+For convenience,
+.nh
+\fBarchive_read_support_format_all\fP
+.hy
+();
+enables support for all available formats.
+Only empty archives are supported by default.
+.TP
+.nh
+\fBarchive_read_open\fP
+.hy
+();
+The same as
+.nh
+\fBarchive_read_open2\fP
+.hy
+(,);
+except that the skip callback is assumed to be
+.BR NULL.
+.TP
+.nh
+\fBarchive_read_open2\fP
+.hy
+();
+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
+.nh
+\fBarchive_read_open_filename\fP
+.hy
+(,);
+.nh
+\fBarchive_read_open_FILE\fP
+.hy
+(,);
+.nh
+\fBarchive_read_open_fd\fP
+.hy
+(,);
+or
+.nh
+\fBarchive_read_open_memory\fP
+.hy
+();
+instead.
+The library invokes the client-provided functions to obtain
+raw bytes from the archive.
+.TP
+.nh
+\fBarchive_read_open_FILE\fP
+.hy
+();
+Like
+.nh
+\fBarchive_read_open\fP
+.hy
+(,);
+except that it accepts a
+\fI"FILE *"\fP
+.RE
+pointer.
+This function should not be used with tape drives or other devices
+that require strict I/O blocking.
+.TP
+.nh
+\fBarchive_read_open_fd\fP
+.hy
+();
+Like
+.nh
+\fBarchive_read_open\fP
+.hy
+(,);
+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
+.nh
+\fBarchive_read_open_file\fP
+.hy
+();
+This is a deprecated synonym for
+.nh
+\fBarchive_read_open_filename\fP
+.hy
+(.);
+.TP
+.nh
+\fBarchive_read_open_filename\fP
+.hy
+();
+Like
+.nh
+\fBarchive_read_open\fP
+.hy
+(,);
+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
+.nh
+\fBarchive_read_open_memory\fP
+.hy
+();
+Like
+.nh
+\fBarchive_read_open\fP
+.hy
+(,);
+except that it accepts a pointer and size of a block of
+memory containing the archive data.
+.TP
+.nh
+\fBarchive_read_next_header\fP
+.hy
+();
+Read the header for the next entry and return a pointer to
+a
+Tn struct archive_entry.
+.TP
+.nh
+\fBarchive_read_data\fP
+.hy
+();
+Read data associated with the header just read.
+Internally, this is a convenience function that calls
+.nh
+\fBarchive_read_data_block\fP
+.hy
+();
+and fills any gaps with nulls so that callers see a single
+continuous stream of data.
+.TP
+.nh
+\fBarchive_read_data_block\fP
+.hy
+();
+Return the next available block of data for this entry.
+Unlike
+.nh
+\fBarchive_read_data\fP
+.hy
+(,);
+the
+.nh
+\fBarchive_read_data_block\fP
+.hy
+();
+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
+.nh
+\fBarchive_read_data_skip\fP
+.hy
+();
+A convenience function that repeatedly calls
+.nh
+\fBarchive_read_data_block\fP
+.hy
+();
+to skip all of the data for this archive entry.
+.TP
+.nh
+\fBarchive_read_data_into_buffer\fP
+.hy
+();
+This function is deprecated and will be removed.
+Use
+.nh
+\fBarchive_read_data\fP
+.hy
+();
+instead.
+.TP
+.nh
+\fBarchive_read_data_into_fd\fP
+.hy
+();
+A convenience function that repeatedly calls
+.nh
+\fBarchive_read_data_block\fP
+.hy
+();
+to copy the entire entry to the provided file descriptor.
+.TP
+.nh
+\fBarchive_read_extract\fP
+.hy
+(, .nh);
+\fBarchive_read_extract_set_skip_file\fP
+.hy
+();
+A convenience function that wraps the corresponding
+\fBarchive_write_disk\fP(3)
+interfaces.
+The first call to
+.nh
+\fBarchive_read_extract\fP
+.hy
+();
+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
+.nh
+\fBarchive_read_extract2\fP
+.hy
+();
+This is another version of
+.nh
+\fBarchive_read_extract\fP
+.hy
+();
+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
+.nh
+\fBarchive_read_extract2\fP
+.hy
+();
+does not accept a
+\fIflags\fP
+argument; you should use
+.nh
+\fBarchive_write_disk_set_options\fP
+.hy
+();
+to set the restore options yourself.
+.TP
+.nh
+\fBarchive_read_extract_set_progress_callback\fP
+.hy
+();
+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
+.nh
+\fBarchive_read_close\fP
+.hy
+();
+Complete the archive and invoke the close callback.
+.TP
+.nh
+\fBarchive_read_finish\fP
+.hy
+();
+Invokes
+.nh
+\fBarchive_read_close\fP
+.hy
+();
+if it was not invoked manually, then release all resources.
+Note: In libarchive 1.x, this function was declared to return
+\fIvoid,\fP
+.RE
+which made it impossible to detect certain errors when
+.nh
+\fBarchive_read_close\fP
+.hy
+();
+was invoked implicitly from this function.
+The declaration is corrected beginning with libarchive 2.0.
+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.
+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
+The callback functions must match the following prototypes:
+.IP
+\fItypedef ssize_t\fP
+.RE
+Fo archive_read_callback
+Fa "struct archive *"
+Fa "void *client_data"
+Fa "const void **buffer"
+Fc
+.IP
+\fItypedef int\fP
+.RE
+Fo archive_skip_callback
+Fa "struct archive *"
+Fa "void *client_data"
+Fa "size_t request"
+Fc
+.IP
+\fItypedef int\fP
+.RE
+.nh
+\fBarchive_open_callback\fP
+.hy
+("struct archive *" "void *client_data");
+.IP
+\fItypedef int\fP
+.RE
+.nh
+\fBarchive_close_callback\fP
+.hy
+("struct archive *" "void *client_data");
+The open callback is invoked by
+.nh
+\fBarchive_open\fP
+.hy
+(.);
+It should return
+\fBARCHIVE_OK\fP
+if the underlying file or data source is successfully
+opened.
+If the open fails, it should call
+.nh
+\fBarchive_set_error\fP
+.hy
+();
+to register an error code and message and return
+\fBARCHIVE_FATAL\fP.
+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
+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
+.nh
+\fBarchive_set_error\fP
+.hy
+();
+to register an error code and message and
+return -1.
+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.
+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
+.nh
+\fBarchive_set_error\fP
+.hy
+();
+to register an error code and message and
+return
+\fBARCHIVE_FATAL.\fP
+.SH EXAMPLE
+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
+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
+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
+.nh
+\fBarchive_errno\fP
+.hy
+();
+and
+.nh
+\fBarchive_error_string\fP
+.hy
+();
+functions.
+.nh
+\fBarchive_read_new\fP
+.hy
+();
+returns a pointer to a freshly allocated
+Tn struct archive
+object.
+It returns
+.BR NULL
+on error.
+.nh
+\fBarchive_read_data\fP
+.hy
+();
+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
+.nh
+\fBarchive_errno\fP
+.hy
+();
+and
+.nh
+\fBarchive_error_string\fP
+.hy
+();
+functions.
+The library expects the client callbacks to behave similarly.
+If there is an error, you can use
+.nh
+\fBarchive_set_error\fP
+.hy
+();
+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
+\fBtar\fP(1),
+\fBarchive\fP(3),
+\fBarchive_util\fP(3),
+\fBtar\fP(5)
+.SH HISTORY
+The
+\fBlibarchive\fP
+library first appeared in
+FreeBSD 5.3.
+.SH AUTHORS
+-nosplit
+The
+\fBlibarchive\fP
+library was written by
+Tim Kientzle <kientzle@acm.org.>
+.SH BUGS
+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.