Update libarchive to v2.5.5

1 files changed, 379 insertions, 0 deletions

diff --git a/libarchive/libarchive-2.5.5/doc/man/libarchive.3 b/libarchive/libarchive-2.5.5/doc/man/libarchive.3
new file mode 100644
index 0000000..722b765
--- /dev/null
+++ b/libarchive/libarchive-2.5.5/doc/man/libarchive.3
@@ -0,0 +1,379 @@
+.TH LIBARCHIVE 3 "August 19, 2006" ""
+.SH NAME
+\fBlibarchive\fP
+\- functions for reading and writing streaming archives
+.SH LIBRARY
+Lb libarchive
+.SH OVERVIEW
+The
+\fBlibarchive\fP
+library provides a flexible interface for reading and writing
+streaming archive files such as tar and cpio.
+The library is inherently stream-oriented; readers serially iterate through
+the archive, writers serially add things to the archive.
+In particular, note that there is no built-in support for
+random access nor for in-place modification.
+When reading an archive, the library automatically detects the
+format and the compression.
+The library currently has read support for:
+.IP \(bu
+old-style tar archives,
+.IP \(bu
+most variants of the POSIX
+``ustar''
+format,
+.IP \(bu
+the POSIX
+``pax interchange''
+format,
+.IP \(bu
+GNU-format tar archives,
+.IP \(bu
+most common cpio archive formats,
+.IP \(bu
+ISO9660 CD images (with or without RockRidge extensions),
+.IP \(bu
+Zip archives.
+The library automatically detects archives compressed with
+\fBgzip\fP(1),
+\fBbzip2\fP(1),
+or
+\fBcompress\fP(1)
+and decompresses them transparently.
+When writing an archive, you can specify the compression
+to be used and the format to use.
+The library can write
+.IP \(bu
+POSIX-standard
+``ustar''
+archives,
+.IP \(bu
+POSIX
+``pax interchange format''
+archives,
+.IP \(bu
+POSIX octet-oriented cpio archives,
+.IP \(bu
+two different variants of shar archives.
+Pax interchange format is an extension of the tar archive format that
+eliminates essentially all of the limitations of historic tar formats
+in a standard fashion that is supported
+by POSIX-compliant
+\fBpax\fP(1)
+implementations on many systems as well as several newer implementations of
+\fBtar\fP(1).
+Note that the default write format will suppress the pax extended
+attributes for most entries; explicitly requesting pax format will
+enable those attributes for all entries.
+The read and write APIs are accessed through the
+.nh
+\fBarchive_read_XXX\fP
+.hy
+();
+functions and the
+.nh
+\fBarchive_write_XXX\fP
+.hy
+();
+functions, respectively, and either can be used independently
+of the other.
+The rest of this manual page provides an overview of the library
+operation.
+More detailed information can be found in the individual manual
+pages for each API or utility function.
+.SH READING AN ARCHIVE
+To read an archive, you must first obtain an initialized
+Tn struct archive
+object from
+.nh
+\fBarchive_read_new\fP
+.hy
+(.);
+You can then modify this object for the desired operations with the
+various
+.nh
+\fBarchive_read_set_XXX\fP
+.hy
+();
+and
+.nh
+\fBarchive_read_support_XXX\fP
+.hy
+();
+functions.
+In particular, you will need to invoke appropriate
+.nh
+\fBarchive_read_support_XXX\fP
+.hy
+();
+functions to enable the corresponding compression and format
+support.
+Note that these latter functions perform two distinct operations:
+they cause the corresponding support code to be linked into your
+program, and they enable the corresponding auto-detect code.
+Unless you have specific constraints, you will generally want
+to invoke
+.nh
+\fBarchive_read_support_compression_all\fP
+.hy
+();
+and
+.nh
+\fBarchive_read_support_format_all\fP
+.hy
+();
+to enable auto-detect for all formats and compression types
+currently supported by the library.
+Once you have prepared the
+Tn struct archive
+object, you call
+.nh
+\fBarchive_read_open\fP
+.hy
+();
+to actually open the archive and prepare it for reading.
+There are several variants of this function;
+the most basic expects you to provide pointers to several
+functions that can provide blocks of bytes from the archive.
+There are convenience forms that allow you to
+specify a filename, file descriptor,
+\fI"FILE *"\fP
+.RE
+object, or a block of memory from which to read the archive data.
+Note that the core library makes no assumptions about the
+size of the blocks read;
+callback functions are free to read whatever block size is
+most appropriate for the medium.
+Each archive entry consists of a header followed by a certain
+amount of data.
+You can obtain the next header with
+.nh
+\fBarchive_read_next_header\fP
+.hy
+(,);
+which returns a pointer to an
+Tn struct archive_entry
+structure with information about the current archive element.
+If the entry is a regular file, then the header will be followed
+by the file data.
+You can use
+.nh
+\fBarchive_read_data\fP
+.hy
+();
+(which works much like the
+\fBread\fP(2)
+system call)
+to read this data from the archive.
+You may prefer to use the higher-level
+.nh
+\fBarchive_read_data_skip\fP
+.hy
+(,);
+which reads and discards the data for this entry,
+.nh
+\fBarchive_read_data_to_buffer\fP
+.hy
+(,);
+which reads the data into an in-memory buffer,
+.nh
+\fBarchive_read_data_to_file\fP
+.hy
+(,);
+which copies the data to the provided file descriptor, or
+.nh
+\fBarchive_read_extract\fP
+.hy
+(,);
+which recreates the specified entry on disk and copies data
+from the archive.
+In particular, note that
+.nh
+\fBarchive_read_extract\fP
+.hy
+();
+uses the
+Tn struct archive_entry
+structure that you provide it, which may differ from the
+entry just read from the archive.
+In particular, many applications will want to override the
+pathname, file permissions, or ownership.
+Once you have finished reading data from the archive, you
+should call
+.nh
+\fBarchive_read_close\fP
+.hy
+();
+to close the archive, then call
+.nh
+\fBarchive_read_finish\fP
+.hy
+();
+to release all resources, including all memory allocated by the library.
+The
+\fBarchive_read\fP(3)
+manual page provides more detailed calling information for this API.
+.SH WRITING AN ARCHIVE
+You use a similar process to write an archive.
+The
+.nh
+\fBarchive_write_new\fP
+.hy
+();
+function creates an archive object useful for writing,
+the various
+.nh
+\fBarchive_write_set_XXX\fP
+.hy
+();
+functions are used to set parameters for writing the archive, and
+.nh
+\fBarchive_write_open\fP
+.hy
+();
+completes the setup and opens the archive for writing.
+Individual archive entries are written in a three-step
+process:
+You first initialize a
+Tn struct archive_entry
+structure with information about the new entry.
+At a minimum, you should set the pathname of the
+entry and provide a
+\fIstruct\fP stat
+with a valid
+\fIst_mode\fP
+field, which specifies the type of object and
+\fIst_size\fP
+field, which specifies the size of the data portion of the object.
+The
+.nh
+\fBarchive_write_header\fP
+.hy
+();
+function actually writes the header data to the archive.
+You can then use
+.nh
+\fBarchive_write_data\fP
+.hy
+();
+to write the actual data.
+After all entries have been written, use the
+.nh
+\fBarchive_write_finish\fP
+.hy
+();
+function to release all resources.
+The
+\fBarchive_write\fP(3)
+manual page provides more detailed calling information for this API.
+.SH DESCRIPTION
+Detailed descriptions of each function are provided by the
+corresponding manual pages.
+All of the functions utilize an opaque
+Tn struct archive
+datatype that provides access to the archive contents.
+The
+Tn struct archive_entry
+structure contains a complete description of a single archive
+entry.
+It uses an opaque interface that is fully documented in
+\fBarchive_entry\fP(3).
+Users familiar with historic formats should be aware that the newer
+variants have eliminated most restrictions on the length of textual fields.
+Clients should not assume that filenames, link names, user names, or
+group names are limited in length.
+In particular, pax interchange format can easily accommodate pathnames
+in arbitrary character sets that exceed
+\fIPATH_MAX\fP.
+.SH RETURN VALUES
+Most functions return zero on success, non-zero on error.
+The return value indicates the general severity of the error, ranging
+from
+\fBARCHIVE_WARN\fP,
+which indicates a minor problem that should probably be reported
+to the user, to
+\fBARCHIVE_FATAL\fP,
+which indicates a serious problem that will prevent any further
+operations on this archive.
+On error, the
+.nh
+\fBarchive_errno\fP
+.hy
+();
+function can be used to retrieve a numeric error code (see
+\fBerrno\fP(2)).
+The
+.nh
+\fBarchive_error_string\fP
+.hy
+();
+returns a textual error message suitable for display.
+.nh
+\fBarchive_read_new\fP
+.hy
+();
+and
+.nh
+\fBarchive_write_new\fP
+.hy
+();
+return pointers to an allocated and initialized
+Tn struct archive
+object.
+.nh
+\fBarchive_read_data\fP
+.hy
+();
+and
+.nh
+\fBarchive_write_data\fP
+.hy
+();
+return a count of the number of bytes actually read or written.
+A value of zero indicates the end of the data for this entry.
+A negative value indicates an error, in which case the
+.nh
+\fBarchive_errno\fP
+.hy
+();
+and
+.nh
+\fBarchive_error_string\fP
+.hy
+();
+functions can be used to obtain more information.
+.SH ENVIRONMENT
+There are character set conversions within the
+\fBarchive_entry\fP(3)
+functions that are impacted by the currently-selected locale.
+.SH SEE ALSO
+\fBtar\fP(1),
+\fBarchive_entry\fP(3),
+\fBarchive_read\fP(3),
+\fBarchive_util\fP(3),
+\fBarchive_write\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
+Some archive formats support information that is not supported by
+Tn struct archive_entry.
+Such information cannot be fully archived or restored using this library.
+This includes, for example, comments, character sets,
+or the arbitrary key/value pairs that can appear in
+pax interchange format archives.
+Conversely, of course, not all of the information that can be
+stored in an
+Tn struct archive_entry
+is supported by all formats.
+For example, cpio formats do not support nanosecond timestamps;
+old tar formats do not support large device numbers.