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 4462fa18ca22f47a5ea7d10b3e63cc66c84779bb..c2ae31fd561c8f560cd3e8f88406a215d64719b3 100644 (file)
--- 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 e9f8131947ba567758b74c80ea42d6e2a1187d00..708ed31106d82d9fd60b75bb6f6b6159b6a166bc 100644 (file)
--- 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