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

This commit is contained in:
Tim Kientzle 2009-04-17 01:02:12 +00:00
parent a5e75fbb6c
commit 7ea8a85dbc

View File

@ -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