Import libarchive-3.2.1:

- security fixes and other bugfixes
- support for multhreading in xz 5.2+

1 files changed, 165 insertions, 651 deletions

diff --git a/archivers/libarchive/files/doc/wiki/ManPageArchiveRead3.wiki b/archivers/libarchive/files/doc/wiki/ManPageArchiveRead3.wiki
index c6f24017788..69b6c479aa8 100644
--- a/archivers/libarchive/files/doc/wiki/ManPageArchiveRead3.wiki
+++ b/archivers/libarchive/files/doc/wiki/ManPageArchiveRead3.wiki
@@ -1,577 +1,135 @@
-#summary archive_read 3 manual page
-== NAME ==
-*archive_read_new*,
-*archive_read_set_filter_options*,
-*archive_read_set_format_options*,
-*archive_read_set_options*,
-*archive_read_support_compression_all*,
-*archive_read_support_compression_bzip2*,
-*archive_read_support_compression_compress*,
-*archive_read_support_compression_gzip*,
-*archive_read_support_compression_lzma*,
-*archive_read_support_compression_none*,
-*archive_read_support_compression_xz*,
-*archive_read_support_compression_program*,
-*archive_read_support_compression_program_signature*,
-*archive_read_support_format_all*,
-*archive_read_support_format_ar*,
-*archive_read_support_format_cpio*,
-*archive_read_support_format_empty*,
-*archive_read_support_format_iso9660*,
-*archive_read_support_format_mtree,*
-*archive_read_support_format_raw,*
-*archive_read_support_format_tar*,
-*archive_read_support_format_zip*,
-*archive_read_open*,
-*archive_read_open2*,
-*archive_read_open_fd*,
-*archive_read_open_FILE*,
-*archive_read_open_filename*,
-*archive_read_open_memory*,
-*archive_read_next_header*,
-*archive_read_next_header2*,
-*archive_read_data*,
-*archive_read_data_block*,
-*archive_read_data_skip*,
-*archive_read_data_into_buffer*,
-*archive_read_data_into_fd*,
-*archive_read_extract*,
-*archive_read_extract2*,
-*archive_read_extract_set_progress_callback*,
-*archive_read_close*,
-*archive_read_finish*
-- functions for reading streaming archives
-== SYNOPSIS ==
-*#include <archive.h>*
-<br>
-*struct archive `*`*
-<br>
-*archive_read_new*(_void_);
-<br>
-*int*
-<br>
-*archive_read_support_compression_all*(_struct archive `*`_);
-<br>
-*int*
-<br>
-*archive_read_support_compression_bzip2*(_struct archive `*`_);
-<br>
-*int*
-<br>
-*archive_read_support_compression_compress*(_struct archive `*`_);
-<br>
-*int*
-<br>
-*archive_read_support_compression_gzip*(_struct archive `*`_);
-<br>
-*int*
-<br>
-*archive_read_support_compression_lzma*(_struct archive `*`_);
-<br>
-*int*
-<br>
-*archive_read_support_compression_none*(_struct archive `*`_);
-<br>
-*int*
-<br>
-*archive_read_support_compression_xz*(_struct archive `*`_);
-<br>
-*int*
-<br>
-*archive_read_support_compression_program*(_struct archive `*`_, _const char `*`cmd_);
-<br>
-*int*
-<br>
-*archive_read_support_compression_program_signature*(_struct archive `*`_, _const char `*`cmd_, _const void `*`signature_, _size_t signature_length_);
-<br>
-*int*
-<br>
-*archive_read_support_format_all*(_struct archive `*`_);
-<br>
-*int*
-<br>
-*archive_read_support_format_ar*(_struct archive `*`_);
-<br>
-*int*
-<br>
-*archive_read_support_format_cpio*(_struct archive `*`_);
-<br>
-*int*
-<br>
-*archive_read_support_format_empty*(_struct archive `*`_);
-<br>
-*int*
-<br>
-*archive_read_support_format_iso9660*(_struct archive `*`_);
-<br>
-*int*
-<br>
-*archive_read_support_format_mtree*(_struct archive `*`_);
-<br>
-*int*
-<br>
-*archive_read_support_format_raw*(_struct archive `*`_);
-<br>
-*int*
-<br>
-*archive_read_support_format_tar*(_struct archive `*`_);
-<br>
-*int*
-<br>
-*archive_read_support_format_zip*(_struct archive `*`_);
-<br>
-*int*
-<br>
-*archive_read_set_filter_options*(_struct archive `*`_, _const char `*`_);
-<br>
-*int*
-<br>
-*archive_read_set_format_options*(_struct archive `*`_, _const char `*`_);
-<br>
-*int*
-<br>
-*archive_read_set_options*(_struct archive `*`_, _const char `*`_);
-<br>
-*int*
-<br>
-*archive_read_open*(_struct archive `*`_, _void `*`client_data_, _archive_open_callback `*`_, _archive_read_callback `*`_, _archive_close_callback `*`_);
-<br>
-*int*
-<br>
-*archive_read_open2*(_struct archive `*`_, _void `*`client_data_, _archive_open_callback `*`_, _archive_read_callback `*`_, _archive_skip_callback `*`_, _archive_close_callback `*`_);
-<br>
-*int*
-<br>
-*archive_read_open_FILE*(_struct archive `*`_, _FILE `*`file_);
-<br>
-*int*
-<br>
-*archive_read_open_fd*(_struct archive `*`_, _int fd_, _size_t block_size_);
-<br>
-*int*
-<br>
-*archive_read_open_filename*(_struct archive `*`_, _const char `*`filename_, _size_t block_size_);
-<br>
-*int*
-<br>
-*archive_read_open_memory*(_struct archive `*`_, _void `*`buff_, _size_t size_);
-<br>
-*int*
-<br>
-*archive_read_next_header*(_struct archive `*`_, _struct archive_entry `*``*`_);
-<br>
-*int*
-<br>
-*archive_read_next_header2*(_struct archive `*`_, _struct archive_entry `*`_);
-<br>
-*ssize_t*
-<br>
-*archive_read_data*(_struct archive `*`_, _void `*`buff_, _size_t len_);
-<br>
-*int*
-<br>
-*archive_read_data_block*(_struct archive `*`_, _const void `*``*`buff_, _size_t `*`len_, _off_t `*`offset_);
-<br>
-*int*
-<br>
-*archive_read_data_skip*(_struct archive `*`_);
-<br>
-*int*
-<br>
-*archive_read_data_into_buffer*(_struct archive `*`_, _void `*`_, _ssize_t len_);
-<br>
-*int*
-<br>
-*archive_read_data_into_fd*(_struct archive `*`_, _int fd_);
-<br>
-*int*
-<br>
-*archive_read_extract*(_struct archive `*`_, _struct archive_entry `*`_, _int flags_);
-<br>
-*int*
-<br>
-*archive_read_extract2*(_struct archive `*`src_, _struct archive_entry `*`_, _struct archive `*`dest_);
-<br>
-*void*
-<br>
-*archive_read_extract_set_progress_callback*(_struct archive `*`_, _void (`*`func)(void `*`)_, _void `*`user_data_);
-<br>
-*int*
-<br>
-*archive_read_close*(_struct archive `*`_);
-<br>
-*int*
-<br>
-*archive_read_finish*(_struct archive `*`_);
-== DESCRIPTION ==
-These functions provide a complete API for reading streaming archives.
-The general process is to first create the
-*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:
-<dl>
-<dt>*archive_read_new*()</dt><dd>
-Allocates and initializes a
-*struct archive*
-object suitable for reading from an archive.
-</dd><dt>
-*archive_read_support_compression_bzip2*(),
-*archive_read_support_compression_compress*(),
-*archive_read_support_compression_gzip*(),
-*archive_read_support_compression_lzma*(),
-*archive_read_support_compression_none*(),
-*archive_read_support_compression_xz*()
-</dt> <dd>
-Enables auto-detection code and decompression support for the
-specified compression.
-Returns
-*ARCHIVE_OK*
-if the compression is fully supported, or
-*ARCHIVE_WARN*
-if the compression is supported only through an external program.
-Note that decompression using an external program is usually slower than
-decompression through built-in libraries.
-Note that
-"none"
-is always enabled by default.
-</dd><dt>*archive_read_support_compression_all*()</dt><dd>
-Enables all available decompression filters.
-</dd><dt>*archive_read_support_compression_program*()</dt><dd>
-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.
-</dd><dt>*archive_read_support_compression_program_signature*()</dt><dd>
-This feeds data through the specified external program
-but only if the initial bytes of the data match the specified
-signature value.
-</dd><dt>
-*archive_read_support_format_all*(),
-*archive_read_support_format_ar*(),
-*archive_read_support_format_cpio*(),
-*archive_read_support_format_empty*(),
-*archive_read_support_format_iso9660*(),
-*archive_read_support_format_mtree*(),
-*archive_read_support_format_tar*(),
-*archive_read_support_format_zip*()
-</dt> <dd>
-Enables support---including auto-detection code---for the
-specified archive format.
-For example,
-*archive_read_support_format_tar*()
-enables support for a variety of standard tar formats, old-style tar,
-ustar, pax interchange format, and many common variants.
-For convenience,
-*archive_read_support_format_all*()
-enables support for all available formats.
-Only empty archives are supported by default.
-</dd><dt>*archive_read_support_format_raw*()</dt><dd>
-The
-"raw"
-format handler allows libarchive to be used to read arbitrary data.
-It treats any data stream as an archive with a single entry.
-The pathname of this entry is
-"data ;"
-all other entry fields are unset.
-This is not enabled by
-*archive_read_support_format_all*()
-in order to avoid erroneous handling of damaged archives.
-</dd><dt>
-*archive_read_set_filter_options*(),
-*archive_read_set_format_options*(),
-*archive_read_set_options*()
-</dt> <dd>
-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:
-<dl>
-<dt>_option=value_</dt><dd>
-The option/value pair will be provided to every module.
-Modules that do not accept an option with this name will ignore it.
-</dd><dt>_option_</dt><dd>
-The option will be provided to every module with a value of
-"1".
-</dd><dt>_!option_</dt><dd>
-The option will be provided to every module with a NULL value.
-</dd><dt>_module:option=value_, _module:option_, _module:!option_</dt><dd>
-As above, but the corresponding option and value will be provided
-only to modules whose name matches
-_module_.
-</dd></dl>
-The return value will be
-*ARCHIVE_OK*
-if any module accepts the option, or
-*ARCHIVE_WARN*
-if no module accepted the option, or
-*ARCHIVE_FATAL*
-if there was a fatal error while attempting to process the option.
+ARCHIVE_READ(3) manual page 
+== NAME == 
+'''archive_read''' 
+- functions for reading streaming archives 
+== LIBRARY == 
+Streaming Archive Library (libarchive, -larchive) 
+== SYNOPSIS == 
+'''<nowiki>#include <archive.h></nowiki>''' 
+== DESCRIPTION == 
+These functions provide a complete API for reading streaming archives. 
+The general process is to first create the 
+'''struct archive''' 
+object, set options, initialize the reader, iterate over the archive 
+headers and associated data, then close the archive and release all 
+resources. 
+=== Create archive object=== 
+See 
+[[ManPagerchiveeadew3]]. 
 
-The currently supported options are:
-<dl>
-<dt>Format iso9660</dt><dd>
-<dl>
-<dt>*joliet*</dt><dd>
-Support Joliet extensions.
-Defaults to enabled, use
-*!joliet*
-to disable.
-</dd></dl>
-</dd></dl>
-</dd><dt>*archive_read_open*()</dt><dd>
-The same as
-*archive_read_open2*(),
-except that the skip callback is assumed to be
-NULL.
-</dd><dt>*archive_read_open2*()</dt><dd>
-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
-*archive_read_open_filename*(),
-*archive_read_open_FILE*(),
-*archive_read_open_fd*(),
-or
-*archive_read_open_memory*()
-instead.
-The library invokes the client-provided functions to obtain
-raw bytes from the archive.
-</dd><dt>*archive_read_open_FILE*()</dt><dd>
-Like
-*archive_read_open*(),
-except that it accepts a
-*FILE `*`*
-pointer.
-This function should not be used with tape drives or other devices
-that require strict I/O blocking.
-</dd><dt>*archive_read_open_fd*()</dt><dd>
-Like
-*archive_read_open*(),
-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.
-</dd><dt>*archive_read_open_file*()</dt><dd>
-This is a deprecated synonym for
-*archive_read_open_filename*().
-</dd><dt>*archive_read_open_filename*()</dt><dd>
-Like
-*archive_read_open*(),
-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.
-</dd><dt>*archive_read_open_memory*()</dt><dd>
-Like
-*archive_read_open*(),
-except that it accepts a pointer and size of a block of
-memory containing the archive data.
-</dd><dt>*archive_read_next_header*()</dt><dd>
-Read the header for the next entry and return a pointer to
-a
-*struct archive_entry .*
-This is a convenience wrapper around
-*archive_read_next_header2*()
-that reuses an internal
-*struct archive_entry*
-object for each request.
-</dd><dt>*archive_read_next_header2*()</dt><dd>
-Read the header for the next entry and populate the provided
-*struct archive_entry .*
-</dd><dt>*archive_read_data*()</dt><dd>
-Read data associated with the header just read.
-Internally, this is a convenience function that calls
-*archive_read_data_block*()
-and fills any gaps with nulls so that callers see a single
-continuous stream of data.
-</dd><dt>*archive_read_data_block*()</dt><dd>
-Return the next available block of data for this entry.
-Unlike
-*archive_read_data*(),
-the
-*archive_read_data_block*()
-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.
-</dd><dt>*archive_read_data_skip*()</dt><dd>
-A convenience function that repeatedly calls
-*archive_read_data_block*()
-to skip all of the data for this archive entry.
-</dd><dt>*archive_read_data_into_buffer*()</dt><dd>
-This function is deprecated and will be removed.
-Use
-*archive_read_data*()
-instead.
-</dd><dt>*archive_read_data_into_fd*()</dt><dd>
-A convenience function that repeatedly calls
-*archive_read_data_block*()
-to copy the entire entry to the provided file descriptor.
-</dd><dt>*archive_read_extract*(), *archive_read_extract_set_skip_file*()</dt><dd>
-A convenience function that wraps the corresponding
-*archive_write_disk*(3)
-interfaces.
-The first call to
-*archive_read_extract*()
-creates a restore object using
-*archive_write_disk_new*(3)
-and
-*archive_write_disk_set_standard_lookup*(3),
-then transparently invokes
-*archive_write_disk_set_options*(3),
-*archive_write_header*(3),
-*archive_write_data*(3),
-and
-*archive_write_finish_entry*(3)
-to create the entry on disk and copy data into it.
-The
-_flags_
-argument is passed unmodified to
-*archive_write_disk_set_options*(3).
-</dd><dt>*archive_read_extract2*()</dt><dd>
-This is another version of
-*archive_read_extract*()
-that allows you to provide your own restore object.
-In particular, this allows you to override the standard lookup functions
-using
-*archive_write_disk_set_group_lookup*(3),
-and
-*archive_write_disk_set_user_lookup*(3).
-Note that
-*archive_read_extract2*()
-does not accept a
-_flags_
-argument; you should use
-*archive_write_disk_set_options*()
-to set the restore options yourself.
-</dd><dt>*archive_read_extract_set_progress_callback*()</dt><dd>
-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.
-</dd><dt>*archive_read_close*()</dt><dd>
-Complete the archive and invoke the close callback.
-</dd><dt>*archive_read_finish*()</dt><dd>
-Invokes
-*archive_read_close*()
-if it was not invoked manually, then release all resources.
-Note: In libarchive 1.x, this function was declared to return
-*void ,*
-which made it impossible to detect certain errors when
-*archive_read_close*()
-was invoked implicitly from this function.
-The declaration is corrected beginning with libarchive 2.0.
-</dd></dl>
+To read an archive, you must first obtain an initialized 
+'''struct archive''' 
+object from 
+'''archive_read_new'''(). 
+=== Enable filters and formats=== 
+See 
+[[ManPagerchiveeadilter3]] 
+and 
+[[ManPagerchiveeadormat3]]. 
 
-Note that the library determines most of the relevant information about
-the archive by inspection.
-In particular, it automatically detects
-*gzip*(1)
-or
-*bzip2*(1)
-compression and transparently performs the appropriate decompression.
-It also automatically detects the archive format.
+You can then modify this object for the desired operations with the 
+various 
+'''archive_read_set_XXX'''() 
+and 
+'''archive_read_support_XXX'''() 
+functions. 
+In particular, you will need to invoke appropriate 
+'''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 
+'''archive_read_support_filter_all'''() 
+and 
+'''archive_read_support_format_all'''() 
+to enable auto-detect for all formats and compression types 
+currently supported by the library. 
+=== Set options=== 
+See 
+[[ManPagerchiveeadetptions3]]. 
+=== Open archive=== 
+See 
+[[ManPagerchiveeadpen3]]. 
 
-A complete description of the
-*struct archive*
-and
-*struct archive_entry*
-objects can be found in the overview manual page for
-*libarchive*(3).
-== CLIENT CALLBACKS ==
-The callback functions must match the following prototypes:
-<ul>
-<li>
-*typedef ssize_t*
-*archive_read_callback*(_struct archive `*`_, _void `*`client_data_, _const void `*``*`buffer_)
-</li><li>
-*typedef int*
-*archive_skip_callback*(_struct archive `*`_, _void `*`client_data_, _size_t request_)
-</li><li>
-*typedef int*
-*archive_open_callback*(_struct archive `*`_, _void `*`client_data_)
-</li><li>
-*typedef int*
-*archive_close_callback*(_struct archive `*`_, _void `*`client_data_)
-</li></ul>
+Once you have prepared the 
+'''struct archive''' 
+object, you call 
+'''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, 
+''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. 
+=== Consume archive=== 
+See 
+[[ManPagerchiveeadeader3]], 
+[[ManPagerchiveeadata3]] 
+and 
+[[ManPagerchiveeadxtract3]]. 
 
-The open callback is invoked by
-*archive_open*().
-It should return
-*ARCHIVE_OK*
-if the underlying file or data source is successfully
-opened.
-If the open fails, it should call
-*archive_set_error*()
-to register an error code and message and return
-*ARCHIVE_FATAL*.
+Each archive entry consists of a header followed by a certain 
+amount of data. 
+You can obtain the next header with 
+'''archive_read_next_header'''(), 
+which returns a pointer to an 
+'''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 
+'''archive_read_data'''() 
+(which works much like the 
+[[read(2)|http://www.freebsd.org/cgi/man.cgi?query=read&sektion=2]] 
+system call) 
+to read this data from the archive, or 
+'''archive_read_data_block'''() 
+which provides a slightly more efficient interface. 
+You may prefer to use the higher-level 
+'''archive_read_data_skip'''(), 
+which reads and discards the data for this entry, 
+'''archive_read_data_into_fd'''(), 
+which copies the data to the provided file descriptor, or 
+'''archive_read_extract'''(), 
+which recreates the specified entry on disk and copies data 
+from the archive. 
+In particular, note that 
+'''archive_read_extract'''() 
+uses the 
+'''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. 
+=== Release resources=== 
+See 
+[[ManPagerchiveeadree3]]. 
 
-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
-{{{
-const void **buffer
-}}}
-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
-*archive_set_error*()
-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
-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
-*ARCHIVE_OK*
-on success.
-On failure, the callback should invoke
-*archive_set_error*()
-to register an error code and message and
-return
-*ARCHIVE_FATAL.*
-== EXAMPLE ==
-The following illustrates basic usage of the library.
-In this example,
-the callback functions are simply wrappers around the standard
-*open*(2),
-*read*(2),
-and
-*close*(2)
-system calls.
-{{{
+Once you have finished reading data from the archive, you 
+should call 
+'''archive_read_close'''() 
+to close the archive, then call 
+'''archive_read_free'''() 
+to release all resources, including all memory allocated by the library. 
+== EXAMPLE == 
+The following illustrates basic usage of the library. 
+In this example, 
+the callback functions are simply wrappers around the standard 
+[[open(2)|http://www.freebsd.org/cgi/man.cgi?query=open&sektion=2]], 
+[[read(2)|http://www.freebsd.org/cgi/man.cgi?query=read&sektion=2]], 
+and 
+[[close(2)|http://www.freebsd.org/cgi/man.cgi?query=close&sektion=2]] 
+system calls. 
+```text
 void
 list_archive(const char *name)
 {
@@ -581,17 +139,17 @@ list_archive(const char *name)
   mydata = malloc(sizeof(struct mydata));
   a = archive_read_new();
   mydata->name = name;
-  archive_read_support_compression_all(a);
+  archive_read_support_filter_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\en",archive_entry_pathname(entry));
     archive_read_data_skip(a);
   }
-  archive_read_finish(a);
+  archive_read_free(a);
   free(mydata);
 }
-ssize_t
+la_ssize_t
 myread(struct archive *a, void *client_data, const void **buff)
 {
   struct mydata *mydata = client_data;
@@ -613,82 +171,38 @@ myclose(struct archive *a, void *client_data)
     close(mydata->fd);
   return (ARCHIVE_OK);
 }
-}}}
-== RETURN VALUES ==
-Most functions return zero on success, non-zero on error.
-The possible return codes include:
-*ARCHIVE_OK*
-(the operation succeeded),
-*ARCHIVE_WARN*
-(the operation succeeded but a non-critical error was encountered),
-*ARCHIVE_EOF*
-(end-of-archive was encountered),
-*ARCHIVE_RETRY*
-(the operation failed but can be retried),
-and
-*ARCHIVE_FATAL*
-(there was a fatal error; the archive should be closed immediately).
-Detailed error codes and textual descriptions are available from the
-*archive_errno*()
-and
-*archive_error_string*()
-functions.
-
-*archive_read_new*()
-returns a pointer to a freshly allocated
-*struct archive*
-object.
-It returns
-NULL
-on error.
-
-*archive_read_data*()
-returns a count of bytes actually read or zero at the end of the entry.
-On error, a value of
-*ARCHIVE_FATAL*,
-*ARCHIVE_WARN*,
-or
-*ARCHIVE_RETRY*
-is returned and an error code and textual description can be retrieved from the
-*archive_errno*()
-and
-*archive_error_string*()
-functions.
-
-The library expects the client callbacks to behave similarly.
-If there is an error, you can use
-*archive_set_error*()
-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
-*ARCHIVE_FATAL*
-to be returned.)
-== SEE ALSO ==
-*tar*(1),
-*archive*(3),
-*archive_util*(3),
-*tar*(5)
-== HISTORY ==
-The
-*libarchive*
-library first appeared in
-FreeBSD 5.3.
-== AUTHORS ==
-The
-*libarchive*
-library was written by
-Tim Kientzle  <kientzle@acm.org.>
-== BUGS ==
-Many traditional archiver programs treat
-empty files as valid empty archives.
-For example, many implementations of
-*tar*(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.
+```
+== SEE ALSO == 
+[[ManPageBsdtar1]], 
+[[ManPageibarchive3]], 
+[[ManPagerchiveeadew3]], 
+[[ManPagerchiveeadata3]], 
+[[ManPagerchiveeadxtract3]], 
+[[ManPagerchiveeadilter3]], 
+[[ManPagerchiveeadormat3]], 
+[[ManPagerchiveeadeader3]], 
+[[ManPagerchiveeadpen3]], 
+[[ManPagerchiveeadetptions3]], 
+[[ManPagerchivetil3]], 
+[[ManPageTar5]] 
+== HISTORY == 
+The 
+'''libarchive''' 
+library first appeared in 
+FreeBSD 5.3. 
+== AUTHORS == 
+The 
+'''libarchive''' 
+library was written by 
+Tim Kientzle  &lt;kientzle@acm.org.&gt; 
+== BUGS == 
+Many traditional archiver programs treat 
+empty files as valid empty archives. 
+For example, many implementations of 
+[[ManPageBsdtar1]] 
+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.