diff options
Diffstat (limited to 'libarchive/libarchive-2.8.0/doc/html/archive_read.3.html')
| -rw-r--r-- | libarchive/libarchive-2.8.0/doc/html/archive_read.3.html | 820 |
1 files changed, 0 insertions, 820 deletions
diff --git a/libarchive/libarchive-2.8.0/doc/html/archive_read.3.html b/libarchive/libarchive-2.8.0/doc/html/archive_read.3.html deleted file mode 100644 index c37fcac..0000000 --- a/libarchive/libarchive-2.8.0/doc/html/archive_read.3.html +++ /dev/null @@ -1,820 +0,0 @@ -<!-- Creator : groff version 1.19.2 --> -<!-- CreationDate: Thu Feb 4 20:36:31 2010 --> -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" -"http://www.w3.org/TR/html4/loose.dtd"> -<html> -<head> -<meta name="generator" content="groff -Thtml, see www.gnu.org"> -<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> -<meta name="Content-Style" content="text/css"> -<style type="text/css"> - p { margin-top: 0; margin-bottom: 0; } - pre { margin-top: 0; margin-bottom: 0; } - table { margin-top: 0; margin-bottom: 0; } -</style> -<title></title> -</head> -<body> - -<hr> - - -<p valign="top">archive_read(3) FreeBSD Library Functions -Manual archive_read(3)</p> - -<p style="margin-top: 1em" valign="top"><b>NAME</b></p> - -<p style="margin-left:8%;"><b>archive_read_new</b>, -<b>archive_read_set_filter_options</b>, -<b>archive_read_set_format_options</b>, -<b>archive_read_set_options</b>, -<b>archive_read_support_compression_all</b>, -<b>archive_read_support_compression_bzip2</b>, -<b>archive_read_support_compression_compress</b>, -<b>archive_read_support_compression_gzip</b>, -<b>archive_read_support_compression_lzma</b>, -<b>archive_read_support_compression_none</b>, -<b>archive_read_support_compression_xz</b>, -<b>archive_read_support_compression_program</b>, -<b>archive_read_support_compression_program_signature</b>, -<b>archive_read_support_format_all</b>, -<b>archive_read_support_format_ar</b>, -<b>archive_read_support_format_cpio</b>, -<b>archive_read_support_format_empty</b>, -<b>archive_read_support_format_iso9660</b>, -<b>archive_read_support_format_mtree, -archive_read_support_format_raw, -archive_read_support_format_tar</b>, -<b>archive_read_support_format_zip</b>, -<b>archive_read_open</b>, <b>archive_read_open2</b>, -<b>archive_read_open_fd</b>, <b>archive_read_open_FILE</b>, -<b>archive_read_open_filename</b>, -<b>archive_read_open_memory</b>, -<b>archive_read_next_header</b>, -<b>archive_read_next_header2</b>, <b>archive_read_data</b>, -<b>archive_read_data_block</b>, -<b>archive_read_data_skip</b>, -<b>archive_read_data_into_buffer</b>, -<b>archive_read_data_into_fd</b>, -<b>archive_read_extract</b>, <b>archive_read_extract2</b>, -<b>archive_read_extract_set_progress_callback</b>, -<b>archive_read_close</b>, <b>archive_read_finish</b> -— functions for reading streaming archives</p> - - -<p style="margin-top: 1em" valign="top"><b>SYNOPSIS</b></p> - -<p style="margin-left:8%;"><b>#include -<archive.h></b></p> - -<p style="margin-left:8%; margin-top: 1em"><i>struct -archive *</i></p> - - -<p style="margin-left:14%;"><b>archive_read_new</b>(<i>void</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_support_compression_all</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_support_compression_bzip2</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_support_compression_compress</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_support_compression_gzip</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_support_compression_lzma</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_support_compression_none</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_support_compression_xz</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p valign="top"><b>archive_read_support_compression_program</b>(<i>struct archive *</i>, -<i>const char *cmd</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p valign="top"><b>archive_read_support_compression_program_signature</b>(<i>struct archive *</i>, -<i>const char *cmd</i>, -<i>const void *signature</i>, -<i>size_t signature_length</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_support_format_all</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_support_format_ar</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_support_format_cpio</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_support_format_empty</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_support_format_iso9660</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_support_format_mtree</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_support_format_raw</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_support_format_tar</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_support_format_zip</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_set_filter_options</b>(<i>struct archive *</i>, -<i>const char *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_set_format_options</b>(<i>struct archive *</i>, -<i>const char *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_set_options</b>(<i>struct archive *</i>, -<i>const char *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p valign="top"><b>archive_read_open</b>(<i>struct archive *</i>, -<i>void *client_data</i>, -<i>archive_open_callback *</i>, -<i>archive_read_callback *</i>, -<i>archive_close_callback *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p valign="top"><b>archive_read_open2</b>(<i>struct archive *</i>, -<i>void *client_data</i>, -<i>archive_open_callback *</i>, -<i>archive_read_callback *</i>, -<i>archive_skip_callback *</i>, -<i>archive_close_callback *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_open_FILE</b>(<i>struct archive *</i>, -<i>FILE *file</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_open_fd</b>(<i>struct archive *</i>, -<i>int fd</i>, <i>size_t block_size</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p valign="top"><b>archive_read_open_filename</b>(<i>struct archive *</i>, -<i>const char *filename</i>, -<i>size_t block_size</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_open_memory</b>(<i>struct archive *</i>, -<i>void *buff</i>, <i>size_t size</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_next_header</b>(<i>struct archive *</i>, -<i>struct archive_entry **</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_next_header2</b>(<i>struct archive *</i>, -<i>struct archive_entry *</i>);</p> - - -<p style="margin-left:8%; margin-top: 1em"><i>ssize_t</i></p> - - -<p style="margin-left:14%;"><b>archive_read_data</b>(<i>struct archive *</i>, -<i>void *buff</i>, <i>size_t len</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p valign="top"><b>archive_read_data_block</b>(<i>struct archive *</i>, -<i>const void **buff</i>, <i>size_t *len</i>, -<i>off_t *offset</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_data_skip</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_data_into_buffer</b>(<i>struct archive *</i>, -<i>void *</i>, <i>ssize_t len</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_data_into_fd</b>(<i>struct archive *</i>, -<i>int fd</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p valign="top"><b>archive_read_extract</b>(<i>struct archive *</i>, -<i>struct archive_entry *</i>, -<i>int flags</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p valign="top"><b>archive_read_extract2</b>(<i>struct archive *src</i>, -<i>struct archive_entry *</i>, -<i>struct archive *dest</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> - - -<p valign="top"><b>archive_read_extract_set_progress_callback</b>(<i>struct archive *</i>, -<i>void (*func)(void *)</i>, -<i>void *user_data</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_close</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_finish</b>(<i>struct archive *</i>);</p> - - -<p style="margin-top: 1em" valign="top"><b>DESCRIPTION</b></p> - -<p style="margin-left:8%;">These functions provide a -complete API for reading streaming archives. The general -process is to first create the struct archive object, set -options, initialize the reader, iterate over the archive -headers and associated data, then close the archive and -release all resources. The following summary describes the -functions in approximately the order they would be used:</p> - -<p valign="top"><b>archive_read_new</b>()</p> - -<p style="margin-left:20%;">Allocates and initializes a -struct archive object suitable for reading from an -archive.</p> - - -<p valign="top"><b>archive_read_support_compression_bzip2</b>(), -<b>archive_read_support_compression_compress</b>(), -<b>archive_read_support_compression_gzip</b>(), -<b>archive_read_support_compression_lzma</b>(), -<b>archive_read_support_compression_none</b>(), -<b>archive_read_support_compression_xz</b>()</p> - -<p style="margin-left:20%;">Enables auto-detection code and -decompression support for the specified compression. Returns -<b>ARCHIVE_OK</b> if the compression is fully supported, or -<b>ARCHIVE_WARN</b> 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 -‘‘none’’ is always enabled by -default.</p> - - -<p valign="top"><b>archive_read_support_compression_all</b>()</p> - -<p style="margin-left:20%;">Enables all available -decompression filters.</p> - - -<p valign="top"><b>archive_read_support_compression_program</b>()</p> - -<p style="margin-left:20%;">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.</p> - - -<p valign="top"><b>archive_read_support_compression_program_signature</b>()</p> - -<p style="margin-left:20%;">This feeds data through the -specified external program but only if the initial bytes of -the data match the specified signature value.</p> - -<p valign="top"><b>archive_read_support_format_all</b>(), -<b>archive_read_support_format_ar</b>(), -<b>archive_read_support_format_cpio</b>(), -<b>archive_read_support_format_empty</b>(), -<b>archive_read_support_format_iso9660</b>(), -<b>archive_read_support_format_mtree</b>(), -<b>archive_read_support_format_tar</b>(), -<b>archive_read_support_format_zip</b>()</p> - -<p style="margin-left:20%;">Enables support---including -auto-detection code---for the specified archive format. For -example, <b>archive_read_support_format_tar</b>() enables -support for a variety of standard tar formats, old-style -tar, ustar, pax interchange format, and many common -variants. For convenience, -<b>archive_read_support_format_all</b>() enables support for -all available formats. Only empty archives are supported by -default.</p> - - -<p valign="top"><b>archive_read_support_format_raw</b>()</p> - -<p style="margin-left:20%;">The -‘‘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 ‘‘data’’; all other -entry fields are unset. This is not enabled by -<b>archive_read_support_format_all</b>() in order to avoid -erroneous handling of damaged archives.</p> - -<p valign="top"><b>archive_read_set_filter_options</b>(), -<b>archive_read_set_format_options</b>(), -<b>archive_read_set_options</b>()</p> - -<p style="margin-left:20%;">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:</p> - -<p valign="top"><i>option=value</i></p> - -<p style="margin-left:32%;">The option/value pair will be -provided to every module. Modules that do not accept an -option with this name will ignore it.</p> - -<p valign="top"><i>option</i></p> - -<p style="margin-left:32%; margin-top: 1em">The option will -be provided to every module with a value of -‘‘1’’.</p> - -<p valign="top"><i>!option</i></p> - -<p style="margin-left:32%;">The option will be provided to -every module with a NULL value.</p> - -<p valign="top"><i>module:option=value</i>, -<i>module:option</i>, <i>module:!option</i></p> - -<p style="margin-left:32%;">As above, but the corresponding -option and value will be provided only to modules whose name -matches <i>module</i>.</p> - -<p style="margin-left:20%;">The return value will be -<b>ARCHIVE_OK</b> if any module accepts the option, or -<b>ARCHIVE_WARN</b> if no module accepted the option, or -<b>ARCHIVE_FATAL</b> if there was a fatal error while -attempting to process the option.</p> - -<p style="margin-left:20%; margin-top: 1em">The currently -supported options are:</p> - -<p valign="top">Format iso9660 <b><br> -joliet</b></p> - -<p style="margin-left:45%; margin-top: 1em">Support Joliet -extensions. Defaults to enabled, use <b>!joliet</b> to -disable.</p> - -<p valign="top"><b>archive_read_open</b>()</p> - -<p style="margin-left:20%;">The same as -<b>archive_read_open2</b>(), except that the skip callback -is assumed to be NULL.</p> - -<p valign="top"><b>archive_read_open2</b>()</p> - -<p style="margin-left:20%;">Freeze the settings, open the -archive, and prepare for reading entries. This is the most -generic version of this call, which accepts four callback -functions. Most clients will want to use -<b>archive_read_open_filename</b>(), -<b>archive_read_open_FILE</b>(), -<b>archive_read_open_fd</b>(), or -<b>archive_read_open_memory</b>() instead. The library -invokes the client-provided functions to obtain raw bytes -from the archive.</p> - -<p valign="top"><b>archive_read_open_FILE</b>()</p> - -<p style="margin-left:20%;">Like -<b>archive_read_open</b>(), except that it accepts a <i>FILE -*</i> pointer. This function should not be used with tape -drives or other devices that require strict I/O -blocking.</p> - -<p valign="top"><b>archive_read_open_fd</b>()</p> - -<p style="margin-left:20%;">Like -<b>archive_read_open</b>(), except that it accepts a file -descriptor and block size rather than 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.</p> - -<p valign="top"><b>archive_read_open_file</b>()</p> - -<p style="margin-left:20%;">This is a deprecated synonym -for <b>archive_read_open_filename</b>().</p> - -<p valign="top"><b>archive_read_open_filename</b>()</p> - -<p style="margin-left:20%;">Like -<b>archive_read_open</b>(), 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.</p> - -<p valign="top"><b>archive_read_open_memory</b>()</p> - -<p style="margin-left:20%;">Like -<b>archive_read_open</b>(), except that it accepts a pointer -and size of a block of memory containing the archive -data.</p> - -<p valign="top"><b>archive_read_next_header</b>()</p> - -<p style="margin-left:20%;">Read the header for the next -entry and return a pointer to a struct archive_entry. This -is a convenience wrapper around -<b>archive_read_next_header2</b>() that reuses an internal -struct archive_entry object for each request.</p> - -<p valign="top"><b>archive_read_next_header2</b>()</p> - -<p style="margin-left:20%;">Read the header for the next -entry and populate the provided struct archive_entry.</p> - -<p valign="top"><b>archive_read_data</b>()</p> - -<p style="margin-left:20%;">Read data associated with the -header just read. Internally, this is a convenience function -that calls <b>archive_read_data_block</b>() and fills any -gaps with nulls so that callers see a single continuous -stream of data.</p> - -<p valign="top"><b>archive_read_data_block</b>()</p> - -<p style="margin-left:20%;">Return the next available block -of data for this entry. Unlike <b>archive_read_data</b>(), -the <b>archive_read_data_block</b>() function avoids copying -data and allows you to correctly handle sparse files, as -supported by some archive formats. The library guarantees -that offsets will increase and that blocks will not overlap. -Note that the blocks returned from this function can be much -larger than the block size read from disk, due to -compression and internal buffer optimizations.</p> - -<p valign="top"><b>archive_read_data_skip</b>()</p> - -<p style="margin-left:20%;">A convenience function that -repeatedly calls <b>archive_read_data_block</b>() to skip -all of the data for this archive entry.</p> - -<p valign="top"><b>archive_read_data_into_buffer</b>()</p> - -<p style="margin-left:20%;">This function is deprecated and -will be removed. Use <b>archive_read_data</b>() instead.</p> - -<p valign="top"><b>archive_read_data_into_fd</b>()</p> - -<p style="margin-left:20%;">A convenience function that -repeatedly calls <b>archive_read_data_block</b>() to copy -the entire entry to the provided file descriptor.</p> - -<p valign="top"><b>archive_read_extract</b>(), -<b>archive_read_extract_set_skip_file</b>()</p> - -<p style="margin-left:20%;">A convenience function that -wraps the corresponding archive_write_disk(3) interfaces. -The first call to <b>archive_read_extract</b>() creates a -restore object using archive_write_disk_new(3) and -archive_write_disk_set_standard_lookup(3), then -transparently invokes archive_write_disk_set_options(3), -archive_write_header(3), archive_write_data(3), and -archive_write_finish_entry(3) to create the entry on disk -and copy data into it. The <i>flags</i> argument is passed -unmodified to archive_write_disk_set_options(3).</p> - -<p valign="top"><b>archive_read_extract2</b>()</p> - -<p style="margin-left:20%;">This is another version of -<b>archive_read_extract</b>() that allows you to provide -your own restore object. In particular, this allows you to -override the standard lookup functions using -archive_write_disk_set_group_lookup(3), and -archive_write_disk_set_user_lookup(3). Note that -<b>archive_read_extract2</b>() does not accept a -<i>flags</i> argument; you should use -<b>archive_write_disk_set_options</b>() to set the restore -options yourself.</p> - - -<p valign="top"><b>archive_read_extract_set_progress_callback</b>()</p> - -<p style="margin-left:20%;">Sets a pointer to a -user-defined callback that can be used for updating progress -displays during extraction. The progress function will be -invoked during the extraction of large regular files. The -progress function will be invoked with the pointer provided -to this call. Generally, the data pointed to should include -a reference to the archive object and the archive_entry -object so that various statistics can be retrieved for the -progress display.</p> - -<p valign="top"><b>archive_read_close</b>()</p> - -<p style="margin-left:20%;">Complete the archive and invoke -the close callback.</p> - -<p valign="top"><b>archive_read_finish</b>()</p> - -<p style="margin-left:20%;">Invokes -<b>archive_read_close</b>() if it was not invoked manually, -then release all resources. Note: In libarchive 1.x, this -function was declared to return <i>void</i>, which made it -impossible to detect certain errors when -<b>archive_read_close</b>() was invoked implicitly from this -function. The declaration is corrected beginning with -libarchive 2.0.</p> - -<p style="margin-left:8%; margin-top: 1em">Note that the -library determines most of the relevant information about -the archive by inspection. In particular, it automatically -detects gzip(1) or bzip2(1) compression and transparently -performs the appropriate decompression. It also -automatically detects the archive format.</p> - -<p style="margin-left:8%; margin-top: 1em">A complete -description of the struct archive and struct archive_entry -objects can be found in the overview manual page for -libarchive(3).</p> - -<p style="margin-top: 1em" valign="top"><b>CLIENT -CALLBACKS</b></p> - -<p style="margin-left:8%;">The callback functions must -match the following prototypes:</p> - -<p style="margin-left:17%; margin-top: 1em"><i>typedef -ssize_t</i></p> - - -<p valign="top"><b>archive_read_callback</b>(<i>struct archive *</i>, -<i>void *client_data</i>, -<i>const void **buffer</i>)</p> - -<p style="margin-left:17%; margin-top: 1em"><i>typedef -int</i></p> - - -<p valign="top"><b>archive_skip_callback</b>(<i>struct archive *</i>, -<i>void *client_data</i>, -<i>size_t request</i>)</p> - -<p style="margin-left:17%; margin-top: 1em"><i>typedef -int</i> <b>archive_open_callback</b>(<i>struct archive -*</i>, <i>void *client_data</i>)</p> - -<p style="margin-left:17%; margin-top: 1em"><i>typedef -int</i> <b>archive_close_callback</b>(<i>struct archive -*</i>, <i>void *client_data</i>)</p> - -<p style="margin-left:8%; margin-top: 1em">The open -callback is invoked by <b>archive_open</b>(). It should -return <b>ARCHIVE_OK</b> if the underlying file or data -source is successfully opened. If the open fails, it should -call <b>archive_set_error</b>() to register an error code -and message and return <b>ARCHIVE_FATAL</b>.</p> - -<p style="margin-left:8%; margin-top: 1em">The read -callback is invoked whenever the library requires raw bytes -from the archive. The read callback should read data into a -buffer, set the const void **buffer argument to point to the -available data, and return a count of the number of bytes -available. The library will invoke the read callback again -only after it has consumed this data. The library imposes no -constraints on the size of the data blocks returned. On -end-of-file, the read callback should return zero. On error, -the read callback should invoke <b>archive_set_error</b>() -to register an error code and message and return -1.</p> - -<p style="margin-left:8%; margin-top: 1em">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 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.</p> - -<p style="margin-left:8%; margin-top: 1em">The close -callback is invoked by archive_close when the archive -processing is complete. The callback should return -<b>ARCHIVE_OK</b> on success. On failure, the callback -should invoke <b>archive_set_error</b>() to register an -error code and message and return <b>ARCHIVE_FATAL.</b></p> - -<p style="margin-top: 1em" valign="top"><b>EXAMPLE</b></p> - -<p style="margin-left:8%;">The following illustrates basic -usage of the library. In this example, the callback -functions are simply wrappers around the standard open(2), -read(2), and close(2) system calls.</p> - -<p style="margin-left:17%; margin-top: 1em">void <br> -list_archive(const char *name) <br> -{ <br> -struct mydata *mydata; <br> -struct archive *a; <br> -struct archive_entry *entry;</p> - -<p style="margin-left:17%; margin-top: 1em">mydata = -malloc(sizeof(struct mydata)); <br> -a = archive_read_new(); <br> -mydata->name = name; <br> -archive_read_support_compression_all(a); <br> -archive_read_support_format_all(a); <br> -archive_read_open(a, mydata, myopen, myread, myclose); <br> -while (archive_read_next_header(a, &entry) == -ARCHIVE_OK) { <br> -printf("%s\n",archive_entry_pathname(entry)); <br> -archive_read_data_skip(a); <br> -} <br> -archive_read_finish(a); <br> -free(mydata); <br> -}</p> - -<p style="margin-left:17%; margin-top: 1em">ssize_t <br> -myread(struct archive *a, void *client_data, const void -**buff) <br> -{ <br> -struct mydata *mydata = client_data;</p> - -<p style="margin-left:17%; margin-top: 1em">*buff = -mydata->buff; <br> -return (read(mydata->fd, mydata->buff, 10240)); <br> -}</p> - -<p style="margin-left:17%; margin-top: 1em">int <br> -myopen(struct archive *a, void *client_data) <br> -{ <br> -struct mydata *mydata = client_data;</p> - -<p style="margin-left:17%; margin-top: 1em">mydata->fd = -open(mydata->name, O_RDONLY); <br> -return (mydata->fd >= 0 ? ARCHIVE_OK : ARCHIVE_FATAL); -<br> -}</p> - -<p style="margin-left:17%; margin-top: 1em">int <br> -myclose(struct archive *a, void *client_data) <br> -{ <br> -struct mydata *mydata = client_data;</p> - -<p style="margin-left:17%; margin-top: 1em">if -(mydata->fd > 0) <br> -close(mydata->fd); <br> -return (ARCHIVE_OK); <br> -}</p> - -<p style="margin-top: 1em" valign="top"><b>RETURN -VALUES</b></p> - -<p style="margin-left:8%;">Most functions return zero on -success, non-zero on error. The possible return codes -include: <b>ARCHIVE_OK</b> (the operation succeeded), -<b>ARCHIVE_WARN</b> (the operation succeeded but a -non-critical error was encountered), <b>ARCHIVE_EOF</b> -(end-of-archive was encountered), <b>ARCHIVE_RETRY</b> (the -operation failed but can be retried), and -<b>ARCHIVE_FATAL</b> (there was a fatal error; the archive -should be closed immediately). Detailed error codes and -textual descriptions are available from the -<b>archive_errno</b>() and <b>archive_error_string</b>() -functions.</p> - - -<p style="margin-left:8%; margin-top: 1em"><b>archive_read_new</b>() -returns a pointer to a freshly allocated struct archive -object. It returns NULL on error.</p> - - -<p style="margin-left:8%; margin-top: 1em"><b>archive_read_data</b>() -returns a count of bytes actually read or zero at the end of -the entry. On error, a value of <b>ARCHIVE_FATAL</b>, -<b>ARCHIVE_WARN</b>, or <b>ARCHIVE_RETRY</b> is returned and -an error code and textual description can be retrieved from -the <b>archive_errno</b>() and <b>archive_error_string</b>() -functions.</p> - -<p style="margin-left:8%; margin-top: 1em">The library -expects the client callbacks to behave similarly. If there -is an error, you can use <b>archive_set_error</b>() to set -an appropriate error code and description, then return one -of the non-zero values above. (Note that the value -eventually returned to the client may not be the same; many -errors that are not critical at the level of basic I/O can -prevent the archive from being properly read, thus most I/O -errors eventually cause <b>ARCHIVE_FATAL</b> to be -returned.)</p> - -<p style="margin-top: 1em" valign="top"><b>SEE ALSO</b></p> - -<p style="margin-left:8%;">tar(1), archive(3), -archive_util(3), tar(5)</p> - -<p style="margin-top: 1em" valign="top"><b>HISTORY</b></p> - -<p style="margin-left:8%;">The <b>libarchive</b> library -first appeared in FreeBSD 5.3.</p> - -<p style="margin-top: 1em" valign="top"><b>AUTHORS</b></p> - -<p style="margin-left:8%;">The <b>libarchive</b> library -was written by Tim Kientzle -⟨kientzle@acm.org⟩.</p> - -<p style="margin-top: 1em" valign="top"><b>BUGS</b></p> - -<p style="margin-left:8%;">Many traditional archiver -programs treat empty files as valid empty archives. For -example, many implementations of tar(1) allow you to append -entries to an empty file. Of course, it is impossible to -determine the format of an empty file by inspecting the -contents, so this library treats empty files as having a -special ‘‘empty’’ format.</p> - - -<p style="margin-left:8%; margin-top: 1em">FreeBSD 8.0 -April 13, 2009 FreeBSD 8.0</p> -<hr> -</body> -</html> |