Document the new read options interface and the new read_header2() call.

1 files changed, 62 insertions, 0 deletions

diff --git a/lib/libarchive/archive_read.3 b/lib/libarchive/archive_read.3
index 591819c..9777736 100644
--- a/lib/libarchive/archive_read.3
+++ b/lib/libarchive/archive_read.3
@@ -29,6 +29,9 @@
 .Os
 .Sh NAME
 .Nm archive_read_new ,
+.Nm archive_read_set_filter_options ,
+.Nm archive_read_set_format_options ,
+.Nm archive_read_set_options ,
 .Nm archive_read_support_compression_all ,
 .Nm archive_read_support_compression_bzip2 ,
 .Nm archive_read_support_compression_compress ,
@@ -48,6 +51,7 @@
 .Nm archive_read_open_filename ,
 .Nm archive_read_open_memory ,
 .Nm archive_read_next_header ,
+.Nm archive_read_next_header2 ,
 .Nm archive_read_data ,
 .Nm archive_read_data_block ,
 .Nm archive_read_data_skip ,
@@ -93,6 +97,12 @@
 .Ft int
 .Fn archive_read_support_format_zip "struct archive *"
 .Ft int
+.Fn archive_read_set_filter_options "struct archive *" "const char *"
+.Ft int
+.Fn archive_read_set_format_options "struct archive *" "const char *"
+.Ft int
+.Fn archive_read_set_options "struct archive *" "const char *"
+.Ft int
 .Fo archive_read_open
 .Fa "struct archive *"
 .Fa "void *client_data"
@@ -123,6 +133,8 @@
 .Fn archive_read_open_memory "struct archive *" "void *buff" "size_t size"
 .Ft int
 .Fn archive_read_next_header "struct archive *" "struct archive_entry **"
+.Ft int
+.Fn archive_read_next_header2 "struct archive *" "struct archive_entry *"
 .Ft ssize_t
 .Fn archive_read_data "struct archive *" "void *buff" "size_t len"
 .Ft int
@@ -214,6 +226,48 @@ For convenience,
 .Fn archive_read_support_format_all
 enables support for all available formats.
 Only empty archives are supported by default.
+.It Xo
+.Fn archive_read_set_filter_options ,
+.Fn archive_read_set_format_options ,
+.Fn archive_read_set_options
+.Xc
+Specifies options that will be passed to currently-registered
+filters (including decompression filters) and/or format readers.
+The argument is a comma-separated list of individual options.
+Individual options have one of the following forms:
+.Bl -tag -compact -width indent
+.It Ar option=value
+The option/value pair will be provided to every module.
+Modules that do not accept an option with this name will ignore it.
+.It Ar option
+The option will be provided to every module with a value of
+.Dq 1 .
+.It Ar !option
+The option will be provided to every module with a NULL value.
+.It Ar module:option=value , Ar module:option , Ar module:!option
+As above, but the corresponding option and value will be provided
+only to modules whose name matches
+.Ar module .
+.El
+The return value will be
+.Cm ARCHIVE_OK
+if any module accepts the option, or
+.Cm ARCHIVE_WARN
+if no module accepted the option, or
+.Cm ARCHIVE_FATAL
+if there was a fatal error while attempting to process the option.
+.Pp
+The currently supported options are:
+.Bl -tag -compact -width indent
+.It Format iso9660
+.Bl -tag -compact -width indent
+.It Cm joliet
+Support Joliet extensions.
+Defaults to enabled, use
+.Cm !joliet
+to disable.
+.El
+.El
 .It Fn archive_read_open
 The same as
 .Fn archive_read_open2 ,
@@ -266,6 +320,14 @@ memory containing the archive data.
 Read the header for the next entry and return a pointer to
 a
 .Tn struct archive_entry .
+This is a convenience wrapper around
+.Fn archive_read_next_header2
+that uses an internal
+.Tn struct archive_entry
+object.
+.It Fn archive_read_next_header2
+Read the header for the next entry and populate the provided
+.Tn struct archive_entry .
 .It Fn archive_read_data
 Read data associated with the header just read.
 Internally, this is a convenience function that calls