diff options
Diffstat (limited to 'archivers/libarchive/files/doc/man/archive_read.3')
| -rw-r--r-- | archivers/libarchive/files/doc/man/archive_read.3 | 740 |
1 files changed, 113 insertions, 627 deletions
diff --git a/archivers/libarchive/files/doc/man/archive_read.3 b/archivers/libarchive/files/doc/man/archive_read.3 index 6af8b39f5e8..84fb89f086f 100644 --- a/archivers/libarchive/files/doc/man/archive_read.3 +++ b/archivers/libarchive/files/doc/man/archive_read.3 @@ -1,210 +1,14 @@ -.TH archive_read 3 "April 13, 2009" "" +.TH ARCHIVE_READ 3 "February 2, 2012" "" .SH NAME .ad l -\fB\%archive_read_new\fP, -\fB\%archive_read_set_filter_options\fP, -\fB\%archive_read_set_format_options\fP, -\fB\%archive_read_set_options\fP, -\fB\%archive_read_support_compression_all\fP, -\fB\%archive_read_support_compression_bzip2\fP, -\fB\%archive_read_support_compression_compress\fP, -\fB\%archive_read_support_compression_gzip\fP, -\fB\%archive_read_support_compression_lzma\fP, -\fB\%archive_read_support_compression_none\fP, -\fB\%archive_read_support_compression_xz\fP, -\fB\%archive_read_support_compression_program\fP, -\fB\%archive_read_support_compression_program_signature\fP, -\fB\%archive_read_support_format_all\fP, -\fB\%archive_read_support_format_ar\fP, -\fB\%archive_read_support_format_cpio\fP, -\fB\%archive_read_support_format_empty\fP, -\fB\%archive_read_support_format_iso9660\fP, -\fB\%archive_read_support_format_mtree,\fP -\fB\%archive_read_support_format_raw,\fP -\fB\%archive_read_support_format_tar\fP, -\fB\%archive_read_support_format_zip\fP, -\fB\%archive_read_open\fP, -\fB\%archive_read_open2\fP, -\fB\%archive_read_open_fd\fP, -\fB\%archive_read_open_FILE\fP, -\fB\%archive_read_open_filename\fP, -\fB\%archive_read_open_memory\fP, -\fB\%archive_read_next_header\fP, -\fB\%archive_read_next_header2\fP, -\fB\%archive_read_data\fP, -\fB\%archive_read_data_block\fP, -\fB\%archive_read_data_skip\fP, -\fB\%archive_read_data_into_buffer\fP, -\fB\%archive_read_data_into_fd\fP, -\fB\%archive_read_extract\fP, -\fB\%archive_read_extract2\fP, -\fB\%archive_read_extract_set_progress_callback\fP, -\fB\%archive_read_close\fP, -\fB\%archive_read_finish\fP +\fB\%archive_read\fP \- functions for reading streaming archives +.SH LIBRARY +.ad l +Streaming Archive Library (libarchive, -larchive) .SH SYNOPSIS .ad l \fB#include <archive.h>\fP -.br -\fIstruct archive *\fP -.br -\fB\%archive_read_new\fP(\fI\%void\fP); -.br -\fIint\fP -.br -\fB\%archive_read_support_compression_all\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_read_support_compression_bzip2\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_read_support_compression_compress\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_read_support_compression_gzip\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_read_support_compression_lzma\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_read_support_compression_none\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_read_support_compression_xz\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_read_support_compression_program\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ char\ *cmd\fP); -.br -\fIint\fP -.br -\fB\%archive_read_support_compression_program_signature\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ char\ *cmd\fP, \fI\%const\ void\ *signature\fP, \fI\%size_t\ signature_length\fP); -.br -\fIint\fP -.br -\fB\%archive_read_support_format_all\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_read_support_format_ar\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_read_support_format_cpio\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_read_support_format_empty\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_read_support_format_iso9660\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_read_support_format_mtree\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_read_support_format_raw\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_read_support_format_tar\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_read_support_format_zip\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_read_set_filter_options\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ char\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_read_set_format_options\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ char\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_read_set_options\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ char\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_read_open\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *client_data\fP, \fI\%archive_open_callback\ *\fP, \fI\%archive_read_callback\ *\fP, \fI\%archive_close_callback\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_read_open2\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *client_data\fP, \fI\%archive_open_callback\ *\fP, \fI\%archive_read_callback\ *\fP, \fI\%archive_skip_callback\ *\fP, \fI\%archive_close_callback\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_read_open_FILE\fP(\fI\%struct\ archive\ *\fP, \fI\%FILE\ *file\fP); -.br -\fIint\fP -.br -\fB\%archive_read_open_fd\fP(\fI\%struct\ archive\ *\fP, \fI\%int\ fd\fP, \fI\%size_t\ block_size\fP); -.br -\fIint\fP -.br -\fB\%archive_read_open_filename\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ char\ *filename\fP, \fI\%size_t\ block_size\fP); -.br -\fIint\fP -.br -\fB\%archive_read_open_memory\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *buff\fP, \fI\%size_t\ size\fP); -.br -\fIint\fP -.br -\fB\%archive_read_next_header\fP(\fI\%struct\ archive\ *\fP, \fI\%struct\ archive_entry\ **\fP); -.br -\fIint\fP -.br -\fB\%archive_read_next_header2\fP(\fI\%struct\ archive\ *\fP, \fI\%struct\ archive_entry\ *\fP); -.br -\fIssize_t\fP -.br -\fB\%archive_read_data\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *buff\fP, \fI\%size_t\ len\fP); -.br -\fIint\fP -.br -\fB\%archive_read_data_block\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ void\ **buff\fP, \fI\%size_t\ *len\fP, \fI\%off_t\ *offset\fP); -.br -\fIint\fP -.br -\fB\%archive_read_data_skip\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_read_data_into_buffer\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *\fP, \fI\%ssize_t\ len\fP); -.br -\fIint\fP -.br -\fB\%archive_read_data_into_fd\fP(\fI\%struct\ archive\ *\fP, \fI\%int\ fd\fP); -.br -\fIint\fP -.br -\fB\%archive_read_extract\fP(\fI\%struct\ archive\ *\fP, \fI\%struct\ archive_entry\ *\fP, \fI\%int\ flags\fP); -.br -\fIint\fP -.br -\fB\%archive_read_extract2\fP(\fI\%struct\ archive\ *src\fP, \fI\%struct\ archive_entry\ *\fP, \fI\%struct\ archive\ *dest\fP); -.br -\fIvoid\fP -.br -\fB\%archive_read_extract_set_progress_callback\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ (*func)(void\ *)\fP, \fI\%void\ *user_data\fP); -.br -\fIint\fP -.br -\fB\%archive_read_close\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_read_finish\fP(\fI\%struct\ archive\ *\fP); .SH DESCRIPTION .ad l These functions provide a complete API for reading streaming archives. @@ -213,386 +17,113 @@ Tn 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: -.RS 5 -.TP -\fB\%archive_read_new\fP() -Allocates and initializes a +.SS Create archive object +See +\fBarchive_read_new\fP(3). +.PP +To read an archive, you must first obtain an initialized Tn struct archive -object suitable for reading from an archive. -.TP -\fB\%archive_read_support_compression_bzip2\fP(), -\fB\%archive_read_support_compression_compress\fP(), -\fB\%archive_read_support_compression_gzip\fP(), -\fB\%archive_read_support_compression_lzma\fP(), -\fB\%archive_read_support_compression_none\fP(), -\fB\%archive_read_support_compression_xz\fP() -Enables auto-detection code and decompression support for the -specified compression. -Returns -\fBARCHIVE_OK\fP -if the compression is fully supported, or -\fBARCHIVE_WARN\fP -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. -.TP -\fB\%archive_read_support_compression_all\fP() -Enables all available decompression filters. -.TP -\fB\%archive_read_support_compression_program\fP() -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. -.TP -\fB\%archive_read_support_compression_program_signature\fP() -This feeds data through the specified external program -but only if the initial bytes of the data match the specified -signature value. -.TP -\fB\%archive_read_support_format_all\fP(), -\fB\%archive_read_support_format_ar\fP(), -\fB\%archive_read_support_format_cpio\fP(), -\fB\%archive_read_support_format_empty\fP(), -\fB\%archive_read_support_format_iso9660\fP(), -\fB\%archive_read_support_format_mtree\fP(), -\fB\%archive_read_support_format_tar\fP(), -\fB\%archive_read_support_format_zip\fP() -Enables support---including auto-detection code---for the -specified archive format. -For example, -\fB\%archive_read_support_format_tar\fP() -enables support for a variety of standard tar formats, old-style tar, -ustar, pax interchange format, and many common variants. -For convenience, -\fB\%archive_read_support_format_all\fP() -enables support for all available formats. -Only empty archives are supported by default. -.TP -\fB\%archive_read_support_format_raw\fP() -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 +object from +\fB\%archive_read_new\fP(). +.SS Enable filters and formats +See +\fBarchive_read_filter\fP(3) +and +\fBarchive_read_format\fP(3). +.PP +You can then modify this object for the desired operations with the +various +\fB\%archive_read_set_XXX\fP() +and +\fB\%archive_read_support_XXX\fP() +functions. +In particular, you will need to invoke appropriate +\fB\%archive_read_support_XXX\fP() +functions to enable the corresponding compression and format +support. +Note that these latter functions perform two distinct operations: +they cause the corresponding support code to be linked into your +program, and they enable the corresponding auto-detect code. +Unless you have specific constraints, you will generally want +to invoke +\fB\%archive_read_support_filter_all\fP() +and \fB\%archive_read_support_format_all\fP() -in order to avoid erroneous handling of damaged archives. -.TP -\fB\%archive_read_set_filter_options\fP(), -\fB\%archive_read_set_format_options\fP(), -\fB\%archive_read_set_options\fP() -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: -.RS 5 -.TP -\fIoption=value\fP -The option/value pair will be provided to every module. -Modules that do not accept an option with this name will ignore it. -.TP -\fIoption\fP -The option will be provided to every module with a value of -``1''. -.TP -\fI!option\fP -The option will be provided to every module with a NULL value. -.TP -\fImodule:option=value\fP, \fImodule:option\fP, \fImodule:!option\fP -As above, but the corresponding option and value will be provided -only to modules whose name matches -\fImodule\fP. -.RE -The return value will be -\fBARCHIVE_OK\fP -if any module accepts the option, or -\fBARCHIVE_WARN\fP -if no module accepted the option, or -\fBARCHIVE_FATAL\fP -if there was a fatal error while attempting to process the option. +to enable auto-detect for all formats and compression types +currently supported by the library. +.SS Set options +See +\fBarchive_read_set_options\fP(3). +.SS Open archive +See +\fBarchive_read_open\fP(3). .PP -The currently supported options are: -.RS 5 -.TP -Format iso9660 -.RS 5 -.TP -\fBjoliet\fP -Support Joliet extensions. -Defaults to enabled, use -\fB!joliet\fP -to disable. -.RE -.RE -.TP +Once you have prepared the +Tn struct archive +object, you call \fB\%archive_read_open\fP() -The same as -\fB\%archive_read_open2\fP(), -except that the skip callback is assumed to be -.BR NULL. -.TP -\fB\%archive_read_open2\fP() -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 -\fB\%archive_read_open_filename\fP(), -\fB\%archive_read_open_FILE\fP(), -\fB\%archive_read_open_fd\fP(), -or -\fB\%archive_read_open_memory\fP() -instead. -The library invokes the client-provided functions to obtain -raw bytes from the archive. -.TP -\fB\%archive_read_open_FILE\fP() -Like -\fB\%archive_read_open\fP(), -except that it accepts a +to actually open the archive and prepare it for reading. +There are several variants of this function; +the most basic expects you to provide pointers to several +functions that can provide blocks of bytes from the archive. +There are convenience forms that allow you to +specify a filename, file descriptor, \fIFILE *\fP -pointer. -This function should not be used with tape drives or other devices -that require strict I/O blocking. -.TP -\fB\%archive_read_open_fd\fP() -Like -\fB\%archive_read_open\fP(), -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. -.TP -\fB\%archive_read_open_file\fP() -This is a deprecated synonym for -\fB\%archive_read_open_filename\fP(). -.TP -\fB\%archive_read_open_filename\fP() -Like -\fB\%archive_read_open\fP(), -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. -.TP -\fB\%archive_read_open_memory\fP() -Like -\fB\%archive_read_open\fP(), -except that it accepts a pointer and size of a block of -memory containing the archive data. -.TP -\fB\%archive_read_next_header\fP() -Read the header for the next entry and return a pointer to -a -Tn struct archive_entry. -This is a convenience wrapper around -\fB\%archive_read_next_header2\fP() -that reuses an internal +object, or a block of memory from which to read the archive data. +Note that the core library makes no assumptions about the +size of the blocks read; +callback functions are free to read whatever block size is +most appropriate for the medium. +.SS Consume archive +See +\fBarchive_read_header\fP(3), +\fBarchive_read_data\fP(3) +and +\fBarchive_read_extract\fP(3). +.PP +Each archive entry consists of a header followed by a certain +amount of data. +You can obtain the next header with +\fB\%archive_read_next_header\fP(), +which returns a pointer to an Tn struct archive_entry -object for each request. -.TP -\fB\%archive_read_next_header2\fP() -Read the header for the next entry and populate the provided -Tn struct archive_entry. -.TP -\fB\%archive_read_data\fP() -Read data associated with the header just read. -Internally, this is a convenience function that calls -\fB\%archive_read_data_block\fP() -and fills any gaps with nulls so that callers see a single -continuous stream of data. -.TP -\fB\%archive_read_data_block\fP() -Return the next available block of data for this entry. -Unlike -\fB\%archive_read_data\fP(), -the -\fB\%archive_read_data_block\fP() -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. -.TP -\fB\%archive_read_data_skip\fP() -A convenience function that repeatedly calls -\fB\%archive_read_data_block\fP() -to skip all of the data for this archive entry. -.TP -\fB\%archive_read_data_into_buffer\fP() -This function is deprecated and will be removed. -Use +structure with information about the current archive element. +If the entry is a regular file, then the header will be followed +by the file data. +You can use \fB\%archive_read_data\fP() -instead. -.TP -\fB\%archive_read_data_into_fd\fP() -A convenience function that repeatedly calls +(which works much like the +\fBread\fP(2) +system call) +to read this data from the archive, or \fB\%archive_read_data_block\fP() -to copy the entire entry to the provided file descriptor. -.TP -\fB\%archive_read_extract\fP(), \fB\%archive_read_extract_set_skip_file\fP() -A convenience function that wraps the corresponding -\fBarchive_write_disk\fP(3) -interfaces. -The first call to +which provides a slightly more efficient interface. +You may prefer to use the higher-level +\fB\%archive_read_data_skip\fP(), +which reads and discards the data for this entry, +\fB\%archive_read_data_into_fd\fP(), +which copies the data to the provided file descriptor, or +\fB\%archive_read_extract\fP(), +which recreates the specified entry on disk and copies data +from the archive. +In particular, note that \fB\%archive_read_extract\fP() -creates a restore object using -\fBarchive_write_disk_new\fP(3) -and -\fBarchive_write_disk_set_standard_lookup\fP(3), -then transparently invokes -\fBarchive_write_disk_set_options\fP(3), -\fBarchive_write_header\fP(3), -\fBarchive_write_data\fP(3), -and -\fBarchive_write_finish_entry\fP(3) -to create the entry on disk and copy data into it. -The -\fIflags\fP -argument is passed unmodified to -\fBarchive_write_disk_set_options\fP(3). -.TP -\fB\%archive_read_extract2\fP() -This is another version of -\fB\%archive_read_extract\fP() -that allows you to provide your own restore object. -In particular, this allows you to override the standard lookup functions -using -\fBarchive_write_disk_set_group_lookup\fP(3), -and -\fBarchive_write_disk_set_user_lookup\fP(3). -Note that -\fB\%archive_read_extract2\fP() -does not accept a -\fIflags\fP -argument; you should use -\fB\%archive_write_disk_set_options\fP() -to set the restore options yourself. -.TP -\fB\%archive_read_extract_set_progress_callback\fP() -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. -.TP -\fB\%archive_read_close\fP() -Complete the archive and invoke the close callback. -.TP -\fB\%archive_read_finish\fP() -Invokes -\fB\%archive_read_close\fP() -if it was not invoked manually, then release all resources. -Note: In libarchive 1.x, this function was declared to return -\fIvoid ,\fP -which made it impossible to detect certain errors when -\fB\%archive_read_close\fP() -was invoked implicitly from this function. -The declaration is corrected beginning with libarchive 2.0. -.RE -.PP -Note that the library determines most of the relevant information about -the archive by inspection. -In particular, it automatically detects -\fBgzip\fP(1) -or -\fBbzip2\fP(1) -compression and transparently performs the appropriate decompression. -It also automatically detects the archive format. -.PP -A complete description of the -Tn struct archive -and +uses the Tn struct archive_entry -objects can be found in the overview manual page for -\fBlibarchive\fP(3). -.SH CLIENT CALLBACKS -.ad l -The callback functions must match the following prototypes: -.RS 5 -.IP -\fItypedef ssize_t\fP -\fB\%archive_read_callback\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *client_data\fP, \fI\%const\ void\ **buffer\fP) -.IP -\fItypedef int\fP -\fB\%archive_skip_callback\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *client_data\fP, \fI\%size_t\ request\fP) -.IP -\fItypedef int\fP -\fB\%archive_open_callback\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *client_data\fP) -.IP -\fItypedef int\fP -\fB\%archive_close_callback\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *client_data\fP) -.RE -.PP -The open callback is invoked by -\fB\%archive_open\fP(). -It should return -\fBARCHIVE_OK\fP -if the underlying file or data source is successfully -opened. -If the open fails, it should call -\fB\%archive_set_error\fP() -to register an error code and message and return -\fBARCHIVE_FATAL\fP. -.PP -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 -.RS 4 -const void **buffer -.RE -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 -\fB\%archive_set_error\fP() -to register an error code and message and -return -1. +structure that you provide it, which may differ from the +entry just read from the archive. +In particular, many applications will want to override the +pathname, file permissions, or ownership. +.SS Release resources +See +\fBarchive_read_free\fP(3). .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 -.BR 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 -\fBARCHIVE_OK\fP -on success. -On failure, the callback should invoke -\fB\%archive_set_error\fP() -to register an error code and message and -return -\fBARCHIVE_FATAL.\fP +Once you have finished reading data from the archive, you +should call +\fB\%archive_read_close\fP() +to close the archive, then call +\fB\%archive_read_free\fP() +to release all resources, including all memory allocated by the library. .SH EXAMPLE .ad l The following illustrates basic usage of the library. @@ -614,17 +145,17 @@ list_archive(const char *name) mydata = malloc(sizeof(struct mydata)); a = archive_read_new(); mydata->name = name; - archive_read_support_compression_all(a); + archive_read_support_filter_all(a); archive_read_support_format_all(a); archive_read_open(a, mydata, myopen, myread, myclose); while (archive_read_next_header(a, &entry) == ARCHIVE_OK) { printf("%s\en",archive_entry_pathname(entry)); archive_read_data_skip(a); } - archive_read_finish(a); + archive_read_free(a); free(mydata); } -ssize_t +la_ssize_t myread(struct archive *a, void *client_data, const void **buff) { struct mydata *mydata = client_data; @@ -647,63 +178,18 @@ myclose(struct archive *a, void *client_data) return (ARCHIVE_OK); } .RE -.SH RETURN VALUES -.ad l -Most functions return zero on success, non-zero on error. -The possible return codes include: -\fBARCHIVE_OK\fP -(the operation succeeded), -\fBARCHIVE_WARN\fP -(the operation succeeded but a non-critical error was encountered), -\fBARCHIVE_EOF\fP -(end-of-archive was encountered), -\fBARCHIVE_RETRY\fP -(the operation failed but can be retried), -and -\fBARCHIVE_FATAL\fP -(there was a fatal error; the archive should be closed immediately). -Detailed error codes and textual descriptions are available from the -\fB\%archive_errno\fP() -and -\fB\%archive_error_string\fP() -functions. -.PP -\fB\%archive_read_new\fP() -returns a pointer to a freshly allocated -Tn struct archive -object. -It returns -.BR NULL -on error. -.PP -\fB\%archive_read_data\fP() -returns a count of bytes actually read or zero at the end of the entry. -On error, a value of -\fBARCHIVE_FATAL\fP, -\fBARCHIVE_WARN\fP, -or -\fBARCHIVE_RETRY\fP -is returned and an error code and textual description can be retrieved from the -\fB\%archive_errno\fP() -and -\fB\%archive_error_string\fP() -functions. -.PP -The library expects the client callbacks to behave similarly. -If there is an error, you can use -\fB\%archive_set_error\fP() -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 -\fBARCHIVE_FATAL\fP -to be returned.) .SH SEE ALSO .ad l \fBtar\fP(1), -\fBarchive\fP(3), +\fBlibarchive\fP(3), +\fBarchive_read_new\fP(3), +\fBarchive_read_data\fP(3), +\fBarchive_read_extract\fP(3), +\fBarchive_read_filter\fP(3), +\fBarchive_read_format\fP(3), +\fBarchive_read_header\fP(3), +\fBarchive_read_open\fP(3), +\fBarchive_read_set_options\fP(3), \fBarchive_util\fP(3), \fBtar\fP(5) .SH HISTORY |