Some minor corrections:

  * Expose functions for setting the "skip file" dev/ino information
  * Expose functions for setting/querying the block size on reads
  * Correctly propagate errors out of archive_read_close/archive_write_close
  * Update manpage with information about new functions

1 files changed, 39 insertions, 12 deletions

diff --git a/lib/libarchive/archive_read.3 b/lib/libarchive/archive_read.3
index 1575c7b..ec9ae3d 100644
--- a/lib/libarchive/archive_read.3
+++ b/lib/libarchive/archive_read.3
@@ -1,4 +1,4 @@
-.\" Copyright (c) 2003-2005 Tim Kientzle
+.\" Copyright (c) 2003-2006 Tim Kientzle
 .\" All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd January 8, 2005
+.Dd August 19, 2006
 .Dt archive_read 3
 .Os
 .Sh NAME
@@ -41,6 +41,7 @@
 .Nm archive_read_support_format_tar ,
 .Nm archive_read_support_format_zip ,
 .Nm archive_read_open ,
+.Nm archive_read_open2 ,
 .Nm archive_read_open_fd ,
 .Nm archive_read_open_file ,
 .Nm archive_read_next_header ,
@@ -83,6 +84,8 @@
 .Ft int
 .Fn archive_read_open "struct archive *" "void *client_data" "archive_open_callback *" "archive_read_callback *" "archive_close_callback *"
 .Ft int
+.Fn archive_read_open2 "struct archive *" "void *client_data" "archive_open_callback *" "archive_read_callback *" "archive_skip_callback *" "archive_close_callback *"
+.Ft int
 .Fn archive_read_open_fd "struct archive *" "int fd" "size_t block_size"
 .Ft int
 .Fn archive_read_open_file "struct archive *" "const char *filename" "size_t block_size"
@@ -146,9 +149,14 @@ For convenience,
 enables support for all available formats.
 Note that there is no default.
 .It Fn archive_read_open
+The same as
+.Fn archive_read_open2 ,
+except that the skip callback is assumed to be
+.Dv NULL .
+.It Fn archive_read_open2
 Freeze the settings, open the archive, and prepare for reading entries.
 This is the most generic version of this call, which accepts
-three callback functions.
+four callback functions.
 Most clients will want to use
 .Fn archive_read_open_file
 or
@@ -156,26 +164,20 @@ or
 instead.
 The library invokes the client-provided functions to obtain
 raw bytes from the archive.
-Note: The API permits a decompression method to fork and invoke the
-callbacks from another process.
-Although none of the current decompression methods use this technique,
-future decompression methods may utilize this technique.
-If the decompressor forks, it will ensure that the open and close
-callbacks are invoked within the same process as the read callback.
-In particular, clients should not attempt to use shared variables to
-communicate between the open/read/close callbacks and the mainline code.
 .It Fn archive_read_open_fd
 Like
 .Fn archive_read_open ,
 except that it accepts a file descriptor and block size rather than
-a trio of function pointers.
+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.
 .It Fn archive_read_open_file
 Like
 .Fn 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.
 .It Fn archive_read_next_header
 Read the header for the next entry and return a pointer to
 a
@@ -212,6 +214,12 @@ Note that the client is responsible for sizing the buffer appropriately.
 A convenience function that repeatedly calls
 .Fn archive_read_data_block
 to copy the entire entry to the provided file descriptor.
+.It Fn archive_read_extract_set_skip_file
+This function records the device and inode numbers
+of a file that should not be restored.
+This is a convenience that prevents
+.Fn archive_read_extract
+from restoring a file over the archive itself.
 .It Fn archive_read_extract
 A convenience function that recreates the specified object on
 disk and reads the entry data into that object.
@@ -298,6 +306,9 @@ The callback functions must match the following prototypes:
 .Fn archive_read_callback "struct archive *" "void *client_data" "const void **buffer"
 .It
 .Ft typedef int
+.Fn archive_skip_callback "struct archive *" "void *client_data" "size_t request"
+.It
+.Ft typedef int
 .Fn archive_open_callback "struct archive *" "void *client_data"
 .It
 .Ft typedef int
@@ -333,6 +344,22 @@ On error, the read callback should invoke
 to register an error code and message and
 return -1.
 .Pp
+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
+.Dv 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.
+.Pp
 The close callback is invoked by archive_close when
 the archive processing is complete.
 The callback should return