From: Roman Neuhauser <neuhauser@sigpipe.cz>
Date: Mon, 28 Mar 2011 09:18:09 +0000 (-0400)
Subject: archive_write.3: narrative moved from libarchive.3, edited
X-Git-Tag: v3.0.0a~577
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=be061dc61c5c212f031cba62ea56f0ea4fe11a2e;p=thirdparty%2Flibarchive.git

archive_write.3: narrative moved from libarchive.3, edited

SVN-Revision: 3101
---

diff --git a/libarchive/archive_write.3 b/libarchive/archive_write.3
index f3d35f9cb..f5eb0529a 100644
--- a/libarchive/archive_write.3
+++ b/libarchive/archive_write.3
@@ -43,36 +43,79 @@ close the archive and release all resources.
 .Ss Create archive object
 See
 .Xr archive_write_new 3 .
+.Pp
+To write an archive, you must first obtain an initialized
+.Tn struct archive
+object from
+.Fn archive_write_new .
 .\"
-.Ss Enable filters and formats
+.Ss Enable filters and formats, configure block size and padding
 See
-.Xr archive_write_filter 3
+.Xr archive_write_filter 3 ,
+.Xr archive_write_format 3
+and
+.Xr archive_write_blocksize 3 .
+.Pp
+You can then modify this object for the desired operations with the
+various
+.Fn archive_write_set_XXX
+functions.
+In particular, you will need to invoke appropriate
+.Fn archive_write_add_XXX
 and
-.Xr archive_write_format 3 .
+.Fn archive_write_set_XXX
+functions to enable the corresponding compression and format
+support.
 .\"
-.Ss Configure block size and padding
+.Ss Set options
 See
-.Xr archive_write_blocksize 3 .
+.Xr archive_read_set_options 3 .
 .\"
 .Ss Open archive
 See
 .Xr archive_write_open 3 .
+.Pp
+Once you have prepared the
+.Tn struct archive
+object, you call
+.Fn archive_write_open
+to actually open the archive and prepare it for writing.
+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 write the archive data.
 .\"
 .Ss Produce archive
 See
 .Xr archive_write_header 3
 and
 .Xr archive_write_data 3 .
+.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.
 .\"
 .Ss Release resources
 See
 .Xr archive_write_free 3 .
 .Pp
-More information about the
-.Va struct archive
-object and the overall design of the library can be found in the
-.Xr libarchive 3
-overview.
+After all entries have been written, use the
+.Fn archive_write_free
+function to release all resources.
+.\"
 .Sh EXAMPLE
 The following sketch illustrates basic usage of the library.
 In this example,
diff --git a/libarchive/libarchive.3 b/libarchive/libarchive.3
index 692ee3174..02bee81d0 100644
--- a/libarchive/libarchive.3
+++ b/libarchive/libarchive.3
@@ -120,48 +120,9 @@ See
 .Xr libarchive_read 3 .
 .\"
 .Sh WRITING AN ARCHIVE
-You use a similar process to write an archive.
-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.
-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.
-(Note:
-.Fn archive_write_finish
-is deprecated in Libarchive 3.0; please use
-.Fn archive_write_free
-instead.)
-.Pp
-The
-.Xr archive_write 3
-manual page provides more detailed calling information for this API.
+See
+.Xr libarchive_write 3 .
+.\"
 .Sh WRITING ENTRIES TO DISK
 The
 .Xr archive_write_disk 3