1 files changed, 50 insertions, 125 deletions
diff --git a/Utilities/cmlibarchive/libarchive/libarchive.3 b/Utilities/cmlibarchive/libarchive/libarchive.3
index 8c19d00..d655404 100644
--- a/Utilities/cmlibarchive/libarchive/libarchive.3
+++ b/Utilities/cmlibarchive/libarchive/libarchive.3
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD: src/lib/libarchive/libarchive.3,v 1.11 2007/01/09 08:05:56 kientzle Exp $
 .\"
-.Dd August 19, 2006
+.Dd February 6, 2010
 .Dt LIBARCHIVE 3
 .Os
 .Sh NAME
@@ -36,10 +36,13 @@
 The
 .Nm
 library provides a flexible interface for reading and writing
-streaming archive files such as tar and cpio.
+archives in various formats such as tar and cpio.
+.Nm
+also supports reading and writing archives compressed using
+various compression filters such as gzip and bzip2.
 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
+In particular, note that there is currently no built-in support for
 random access nor for in-place modification.
 .Pp
 When reading an archive, the library automatically detects the
@@ -61,13 +64,14 @@ GNU-format tar archives,
 .It
 most common cpio archive formats,
 .It
-ISO9660 CD images (with or without RockRidge extensions),
+ISO9660 CD images (including RockRidge and Joliet extensions),
 .It
 Zip archives.
 .El
 The library automatically detects archives compressed with
 .Xr gzip 1 ,
 .Xr bzip2 1 ,
+.Xr xz 1 ,
 or
 .Xr compress 1
 and decompresses them transparently.
@@ -87,6 +91,8 @@ archives,
 .It
 POSIX octet-oriented cpio archives,
 .It
+Zip archive,
+.It
 two different variants of shar archives.
 .El
 Pax interchange format is an extension of the tar archive format that
@@ -111,131 +117,37 @@ 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
-.Fn archive_read_new .
-You can then modify this object for the desired operations with the
-various
-.Fn archive_read_set_XXX
-and
-.Fn archive_read_support_XXX
-functions.
-In particular, you will need to invoke appropriate
-.Fn archive_read_support_XXX
-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
-.Fn archive_read_support_compression_all
-and
-.Fn archive_read_support_format_all
-to enable auto-detect for all formats and compression types
-currently supported by the library.
-.Pp
-Once you have prepared the
-.Tn struct archive
-object, you call
-.Fn archive_read_open
-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,
-.Ft "FILE *"
-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.
-.Pp
-Each archive entry consists of a header followed by a certain
-amount of data.
-You can obtain the next header with
-.Fn archive_read_next_header ,
-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
-.Fn archive_read_data
-(which works much like the
-.Xr read 2
-system call)
-to read this data from the archive.
-You may prefer to use the higher-level
-.Fn archive_read_data_skip ,
-which reads and discards the data for this entry,
-.Fn archive_read_data_to_buffer ,
-which reads the data into an in-memory buffer,
-.Fn archive_read_data_to_file ,
-which copies the data to the provided file descriptor, or
-.Fn archive_read_extract ,
-which recreates the specified entry on disk and copies data
-from the archive.
-In particular, note that
-.Fn archive_read_extract
-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.
-.Pp
-Once you have finished reading data from the archive, you
-should call
-.Fn archive_read_close
-to close the archive, then call
-.Fn archive_read_finish
-to release all resources, including all memory allocated by the library.
-.Pp
-The
-.Xr archive_read 3
-manual page provides more detailed calling information for this API.
+See
+.Xr libarchive_read 3 .
+.\"
 .Sh WRITING AN ARCHIVE
-You use a similar process to write an archive.
+See
+.Xr libarchive_write 3 .
+.\"
+.Sh WRITING ENTRIES TO DISK
 The
-.Fn archive_write_new
-function creates an archive object useful for writing,
-the various
-.Fn archive_write_set_XXX
-functions are used to set parameters for writing the archive, and
-.Fn archive_write_open
-completes the setup and opens the archive for writing.
-.Pp
-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
-.Va struct stat
-with a valid
-.Va st_mode
-field, which specifies the type of object and
-.Va st_size
-field, which specifies the size of the data portion of the object.
+.Xr archive_write_disk 3
+API allows you to write
+.Xr archive_entry 3
+objects to disk using the same API used by
+.Xr archive_write 3 .
 The
-.Fn archive_write_header
-function actually writes the header data to the archive.
-You can then use
-.Fn archive_write_data
-to write the actual data.
-.Pp
-After all entries have been written, use the
-.Fn archive_write_finish
-function to release all resources.
-.Pp
+.Xr archive_write_disk 3
+API is used internally by
+.Fn archive_read_extract ;
+using it directly can provide greater control over how entries
+get written to disk.
+This API also makes it possible to share code between
+archive-to-archive copy and archive-to-disk extraction
+operations.
+.Sh READING ENTRIES FROM DISK
 The
-.Xr archive_write 3
-manual page provides more detailed calling information for this API.
+.Xr archive_read_disk 3
+provides some support for populating
+.Xr archive_entry 3
+objects from information in the filesystem.
 .Sh DESCRIPTION
 Detailed descriptions of each function are provided by the
 corresponding manual pages.
@@ -259,7 +171,9 @@ In particular, pax interchange format can easily accommodate pathnames
 in arbitrary character sets that exceed
 .Va PATH_MAX .
 .Sh RETURN VALUES
-Most functions return zero on success, non-zero on error.
+Most functions return
+.Cm ARCHIVE_OK
+(zero) on success, non-zero on error.
 The return value indicates the general severity of the error, ranging
 from
 .Cm ARCHIVE_WARN ,
@@ -329,3 +243,14 @@ stored in an
 is supported by all formats.
 For example, cpio formats do not support nanosecond timestamps;
 old tar formats do not support large device numbers.
+.Pp
+The
+.Xr archive_read_disk 3
+API should support iterating over filesystems;
+that would make it possible to share code among
+disk-to-archive, archive-to-archive, archive-to-disk,
+and disk-to-disk operations.
+Currently, it only supports reading the
+information for a single file.
+(Which is still quite useful, as it hides a lot
+of system-specific details.)