Write-blocking cleanup, largely thanks to Colin Percival (cperciva@).

   * If write block size is zero, don't block at all.
     This supports the unusual requirement of applications
     that need "no-delay" writes.
   * Expose _write_finish_entry() to give such applications more
     control over write boundaries.  (Normal applications do not
     need this, as entries are completed automatically.)
   * Correct the type of write callbacks; this is a minor API
     change that does not affect the ABI.
   * Correct the error handling in _write_next_header() around
     completing the previous entry.
   * Correct the documentation for block-size markers:  Remove
     docs for the long-defunct _read_set_block_size(); document
     all of the write block size manipulators.

MFC after: 14 days

1 files changed, 24 insertions, 0 deletions

diff --git a/lib/libarchive/archive_write.3 b/lib/libarchive/archive_write.3
index cb2b6a0..756d67d 100644
--- a/lib/libarchive/archive_write.3
+++ b/lib/libarchive/archive_write.3
@@ -35,6 +35,7 @@
 .Nm archive_write_set_format_shar ,
 .Nm archive_write_set_format_shar_binary ,
 .Nm archive_write_set_format_ustar ,
+.Nm archive_write_get_bytes_per_block ,
 .Nm archive_write_set_bytes_per_block ,
 .Nm archive_write_set_bytes_in_last_block ,
 .Nm archive_write_set_compressor_gzip ,
@@ -46,6 +47,7 @@
 .Nm archive_write_open_memory ,
 .Nm archive_write_header ,
 .Nm archive_write_data ,
+.Nm archive_write_finish_entry ,
 .Nm archive_write_close ,
 .Nm archive_write_finish
 .Nd functions for creating archives
@@ -54,6 +56,8 @@
 .Ft struct archive *
 .Fn archive_write_new "void"
 .Ft int
+.Fn archive_write_get_bytes_per_block "struct archive *"
+.Ft int
 .Fn archive_write_set_bytes_per_block "struct archive *" "int bytes_per_block"
 .Ft int
 .Fn archive_write_set_bytes_in_last_block "struct archive *" "int"
@@ -88,6 +92,8 @@
 .Ft int
 .Fn archive_write_data "struct archive *" "const void *" "size_t"
 .Ft int
+.Fn archive_write_finish_entry "struct archive *"
+.Ft int
 .Fn archive_write_close "struct archive *"
 .Ft void
 .Fn archive_write_finish "struct archive *"
@@ -114,6 +120,12 @@ written will be padded to the full block size.
 If it is zero, the last block will not be padded.
 If it is non-zero, padding will be added both before and after compression.
 The default is to use a block size of 10240 bytes and to pad the last block.
+Note that a block size of zero will suppress internal blocking
+and cause writes to be sent directly to the write callback as they occur.
+.It Fn archive_write_get_bytes_per_block
+Retrieve the block size to be used for writing.
+A value of -1 here indicates that the library should use default values.
+A value of zero indicates that internal blocking is suppressed.
 .It Fn archive_write_set_bytes_in_last_block
 Sets the block size used for writing the last block.
 If this value is zero, the last block will be padded to the same size
@@ -129,6 +141,9 @@ will set this based on the file type).
 Unlike the other
 .Dq set
 functions, this function can be called after the archive is opened.
+.It Fn archive_write_get_bytes_in_last_block
+Retrieve the currently-set value for last block size.
+A value of -1 here indicates that the library should use default values.
 .It Fn archive_write_set_format_cpio , Fn archive_write_set_format_pax , Fn archive_write_set_format_pax_restricted , Fn archive_write_set_format_shar , Fn archive_write_set_format_shar_binary , Fn archive_write_set_format_ustar
 Sets the format that will be used for the archive.
 The library can write
@@ -230,6 +245,15 @@ 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_finish_entry
+Close out the entry just written.
+In particular, this writes out the final padding required by some formats.
+Ordinarily, clients never need to call this, as it
+is called automatically by
+.Fn archive_write_next_header
+and
+.Fn archive_write_close
+as needed.
 .It Fn archive_write_close
 Complete the archive and invoke the close callback.
 .It Fn archive_write_finish