From 4d24dc3687f4fef1560ae7b27c93c138b5ff28d2 Mon Sep 17 00:00:00 2001 From: Tim Kientzle Date: Mon, 27 Apr 2009 20:13:13 +0000 Subject: [PATCH] Merge r991 from libarchive.googlecode.com: Various updates to archive_read.3 manpage, including documentation for the new "raw" handler. --- lib/libarchive/archive_read.3 | 63 ++++++++++++++++++++++++++++++----- 1 file changed, 55 insertions(+), 8 deletions(-) diff --git a/lib/libarchive/archive_read.3 b/lib/libarchive/archive_read.3 index 9777736c3647..9f37695f99f8 100644 --- a/lib/libarchive/archive_read.3 +++ b/lib/libarchive/archive_read.3 @@ -24,7 +24,7 @@ .\" .\" $FreeBSD$ .\" -.Dd August 19, 2006 +.Dd April 13, 2009 .Dt archive_read 3 .Os .Sh NAME @@ -36,12 +36,18 @@ .Nm archive_read_support_compression_bzip2 , .Nm archive_read_support_compression_compress , .Nm archive_read_support_compression_gzip , +.Nm archive_read_support_compression_lzma , .Nm archive_read_support_compression_none , +.Nm archive_read_support_compression_xz , .Nm archive_read_support_compression_program , +.Nm archive_read_support_compression_program_signature , .Nm archive_read_support_format_all , +.Nm archive_read_support_format_ar , .Nm archive_read_support_format_cpio , .Nm archive_read_support_format_empty , .Nm archive_read_support_format_iso9660 , +.Nm archive_read_support_format_mtree, +.Nm archive_read_support_format_raw, .Nm archive_read_support_format_tar , .Nm archive_read_support_format_zip , .Nm archive_read_open , @@ -78,21 +84,38 @@ .Ft int .Fn archive_read_support_compression_gzip "struct archive *" .Ft int +.Fn archive_read_support_compression_lzma "struct archive *" +.Ft int .Fn archive_read_support_compression_none "struct archive *" .Ft int +.Fn archive_read_support_compression_xz "struct archive *" +.Ft int .Fo archive_read_support_compression_program .Fa "struct archive *" .Fa "const char *cmd" .Fc .Ft int +.Fo archive_read_support_compression_program_signature +.Fa "struct archive *" +.Fa "const char *cmd" +.Fa "const void *signature" +.Fa "size_t signature_length" +.Fc +.Ft int .Fn archive_read_support_format_all "struct archive *" .Ft int +.Fn archive_read_support_format_ar "struct archive *" +.Ft int .Fn archive_read_support_format_cpio "struct archive *" .Ft int .Fn archive_read_support_format_empty "struct archive *" .Ft int .Fn archive_read_support_format_iso9660 "struct archive *" .Ft int +.Fn archive_read_support_format_mtree "struct archive *" +.Ft int +.Fn archive_read_support_format_raw "struct archive *" +.Ft int .Fn archive_read_support_format_tar "struct archive *" .Ft int .Fn archive_read_support_format_zip "struct archive *" @@ -189,30 +212,43 @@ Allocates and initializes a .Tn struct archive object suitable for reading from an archive. .It Xo -.Fn archive_read_support_compression_all , .Fn archive_read_support_compression_bzip2 , .Fn archive_read_support_compression_compress , .Fn archive_read_support_compression_gzip , -.Fn archive_read_support_compression_none +.Fn archive_read_support_compression_lzma , +.Fn archive_read_support_compression_none , +.Fn archive_read_support_compression_xz .Xc Enables auto-detection code and decompression support for the specified compression. +Returns +.Cm ARCHIVE_OK +if the compression is fully supported, or +.Cm ARCHIVE_WARN +if the compression is supported only through an external program. +Note that decompression using an external program is usually slower than +decompression through built-in libraries. Note that .Dq none is always enabled by default. -For convenience, -.Fn archive_read_support_compression_all -enables all available decompression code. +.It Fn archive_read_support_compression_all +Enables all available decompression filters. .It Fn archive_read_support_compression_program Data is fed through the specified external program before being dearchived. Note that this disables automatic detection of the compression format, so it makes no sense to specify this in conjunction with any other decompression option. +.It Fn archive_read_support_compression_program_signature +This feeds data through the specified external program +but only if the initial bytes of the data match the specified +signature value. .It Xo .Fn archive_read_support_format_all , +.Fn archive_read_support_format_ar , .Fn archive_read_support_format_cpio , .Fn archive_read_support_format_empty , .Fn archive_read_support_format_iso9660 , +.Fn archive_read_support_format_mtree , .Fn archive_read_support_format_tar , .Fn archive_read_support_format_zip .Xc @@ -226,6 +262,17 @@ For convenience, .Fn archive_read_support_format_all enables support for all available formats. Only empty archives are supported by default. +.It Fn archive_read_support_format_raw +The +.Dq raw +format handler allows libarchive to be used to read arbitrary data. +It treats any data stream as an archive with a single entry. +The pathname of this entry is +.Dq data ; +all other entry fields are unset. +This is not enabled by +.Fn archive_read_support_format_all +in order to avoid erroneous handling of damaged archives. .It Xo .Fn archive_read_set_filter_options , .Fn archive_read_set_format_options , @@ -322,9 +369,9 @@ a .Tn struct archive_entry . This is a convenience wrapper around .Fn archive_read_next_header2 -that uses an internal +that reuses an internal .Tn struct archive_entry -object. +object for each request. .It Fn archive_read_next_header2 Read the header for the next entry and populate the provided .Tn struct archive_entry .