From: Tim Kientzle <kientzle@gmail.com>
Date: Sat, 12 Feb 2011 23:47:54 +0000 (-0500)
Subject: Issue 135:  document archive_write_data_block and make clear that
X-Git-Tag: v3.0.0a~691
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=020ac1639c5ebf6539a4cbc288bb45530158d27e;p=thirdparty%2Flibarchive.git

Issue 135:  document archive_write_data_block and make clear that
it is not supported for archive_write handles, only for archive_write_disk
handles.

SVN-Revision: 2977
---

diff --git a/libarchive/archive.h b/libarchive/archive.h
index 4462fa18c..c2ae31fd5 100644
--- a/libarchive/archive.h
+++ b/libarchive/archive.h
@@ -628,6 +628,7 @@ __LA_DECL __LA_SSIZE_T	 archive_write_data_block(struct archive *,
 				    const void *, size_t, off_t);
 #else
 /* Libarchive 3.0 uses explicit int64_t to ensure consistent 64-bit support. */
+/* This interface is currently only available for archive_write_disk handles. */
 __LA_DECL __LA_SSIZE_T	 archive_write_data_block(struct archive *,
 				    const void *, size_t, __LA_INT64_T);
 #endif
diff --git a/libarchive/archive_write_disk.3 b/libarchive/archive_write_disk.3
index e9f813194..708ed3110 100644
--- a/libarchive/archive_write_disk.3
+++ b/libarchive/archive_write_disk.3
@@ -36,6 +36,7 @@
 .Nm archive_write_disk_set_user_lookup ,
 .Nm archive_write_header ,
 .Nm archive_write_data ,
+.Nm archive_write_data_block ,
 .Nm archive_write_finish_entry ,
 .Nm archive_write_close ,
 .Nm archive_write_finish
@@ -69,6 +70,8 @@
 .Fn archive_write_header "struct archive *" "struct archive_entry *"
 .Ft ssize_t
 .Fn archive_write_data "struct archive *" "const void *" "size_t"
+.Ft ssize_t
+.Fn archive_write_data_block "struct archive *" "const void *" "size_t size" "int64_t offset"
 .Ft int
 .Fn archive_write_finish_entry "struct archive *"
 .Ft int
@@ -224,6 +227,20 @@ objects.
 .It Fn archive_write_data
 Write data corresponding to the header just written.
 Returns number of bytes written or -1 on error.
+.It Fn archive_write_data_block
+Write data corresponding to the header just written.
+This is like
+.Fn archive_write_data
+except that it performs a seek on the file being
+written to the specified offset before writing the data.
+This is useful when restoring sparse files from archive
+formats that support sparse files.
+Returns number of bytes written or -1 on error.
+(Note: This is currently not supported for
+.Tn archive_write
+handles, only for
+.Tn archive_write_disk
+handles.)
 .It Fn archive_write_finish_entry
 Close out the entry just written.
 Ordinarily, clients never need to call this, as it