diff options
Diffstat (limited to 'libarchive/libarchive-2.4.17/doc/man/archive_read.3')
| -rw-r--r-- | libarchive/libarchive-2.4.17/doc/man/archive_read.3 | 814 |
1 files changed, 0 insertions, 814 deletions
diff --git a/libarchive/libarchive-2.4.17/doc/man/archive_read.3 b/libarchive/libarchive-2.4.17/doc/man/archive_read.3 deleted file mode 100644 index 524c5a8..0000000 --- a/libarchive/libarchive-2.4.17/doc/man/archive_read.3 +++ /dev/null @@ -1,814 +0,0 @@ -.TH archive_read 3 "August 19, 2006" "" -.SH NAME -\fBarchive_read_new\fP, -\fBarchive_read_support_compression_all\fP, -\fBarchive_read_support_compression_bzip2\fP, -\fBarchive_read_support_compression_compress\fP, -\fBarchive_read_support_compression_gzip\fP, -\fBarchive_read_support_compression_none\fP, -\fBarchive_read_support_compression_program\fP, -\fBarchive_read_support_format_all\fP, -\fBarchive_read_support_format_cpio\fP, -\fBarchive_read_support_format_empty\fP, -\fBarchive_read_support_format_iso9660\fP, -\fBarchive_read_support_format_tar\fP, -\fBarchive_read_support_format_zip\fP, -\fBarchive_read_open\fP, -\fBarchive_read_open2\fP, -\fBarchive_read_open_fd\fP, -\fBarchive_read_open_FILE\fP, -\fBarchive_read_open_filename\fP, -\fBarchive_read_open_memory\fP, -\fBarchive_read_next_header\fP, -\fBarchive_read_data\fP, -\fBarchive_read_data_block\fP, -\fBarchive_read_data_skip\fP, -\fBarchive_read_data_into_buffer\fP, -\fBarchive_read_data_into_fd\fP, -\fBarchive_read_extract\fP, -\fBarchive_read_extract_set_progress_callback\fP, -\fBarchive_read_close\fP, -\fBarchive_read_finish\fP -\- functions for reading streaming archives -.SH SYNOPSIS -\fB#include <archive.h>\fP -.br -\fIstruct archive *\fP -.RE -.nh -\fBarchive_read_new\fP -.hy -("void"); -\fIint\fP -.RE -.nh -\fBarchive_read_support_compression_all\fP -.hy -("struct archive *"); -\fIint\fP -.RE -.nh -\fBarchive_read_support_compression_bzip2\fP -.hy -("struct archive *"); -\fIint\fP -.RE -.nh -\fBarchive_read_support_compression_compress\fP -.hy -("struct archive *"); -\fIint\fP -.RE -.nh -\fBarchive_read_support_compression_gzip\fP -.hy -("struct archive *"); -\fIint\fP -.RE -.nh -\fBarchive_read_support_compression_none\fP -.hy -("struct archive *"); -\fIint\fP -.RE -.nh -\fBarchive_read_support_compression_program\fP -.hy -("struct archive *" "const char *cmd"); -\fIint\fP -.RE -.nh -\fBarchive_read_support_format_all\fP -.hy -("struct archive *"); -\fIint\fP -.RE -.nh -\fBarchive_read_support_format_cpio\fP -.hy -("struct archive *"); -\fIint\fP -.RE -.nh -\fBarchive_read_support_format_empty\fP -.hy -("struct archive *"); -\fIint\fP -.RE -.nh -\fBarchive_read_support_format_iso9660\fP -.hy -("struct archive *"); -\fIint\fP -.RE -.nh -\fBarchive_read_support_format_tar\fP -.hy -("struct archive *"); -\fIint\fP -.RE -.nh -\fBarchive_read_support_format_zip\fP -.hy -("struct archive *"); -\fIint\fP -.RE -.nh -\fBarchive_read_open\fP -.hy -("struct archive *" "void *client_data" "archive_open_callback *" "archive_read_callback *" "archive_close_callback *"); -\fIint\fP -.RE -.nh -\fBarchive_read_open2\fP -.hy -("struct archive *" "void *client_data" "archive_open_callback *" "archive_read_callback *" "archive_skip_callback *" "archive_close_callback *"); -\fIint\fP -.RE -.nh -\fBarchive_read_open_FILE\fP -.hy -("struct archive *" "FILE *file"); -\fIint\fP -.RE -.nh -\fBarchive_read_open_fd\fP -.hy -("struct archive *" "int fd" "size_t block_size"); -\fIint\fP -.RE -.nh -\fBarchive_read_open_filename\fP -.hy -("struct archive *" "const char *filename" "size_t block_size"); -\fIint\fP -.RE -.nh -\fBarchive_read_open_memory\fP -.hy -("struct archive *" "void *buff" "size_t size"); -\fIint\fP -.RE -.nh -\fBarchive_read_next_header\fP -.hy -("struct archive *" "struct archive_entry **"); -\fIssize_t\fP -.RE -.nh -\fBarchive_read_data\fP -.hy -("struct archive *" "void *buff" "size_t len"); -\fIint\fP -.RE -.nh -\fBarchive_read_data_block\fP -.hy -("struct archive *" "const void **buff" "size_t *len" "off_t *offset"); -\fIint\fP -.RE -.nh -\fBarchive_read_data_skip\fP -.hy -("struct archive *"); -\fIint\fP -.RE -.nh -\fBarchive_read_data_into_buffer\fP -.hy -("struct archive *" "void *" "ssize_t len"); -\fIint\fP -.RE -.nh -\fBarchive_read_data_into_fd\fP -.hy -("struct archive *" "int fd"); -\fIint\fP -.RE -.nh -\fBarchive_read_extract\fP -.hy -("struct archive *" "struct archive_entry *" "int flags"); -\fIvoid\fP -.RE -.nh -\fBarchive_read_extract_set_progress_callback\fP -.hy -("struct archive *" "void (*func)(void *)" "void *user_data"); -\fIint\fP -.RE -.nh -\fBarchive_read_close\fP -.hy -("struct archive *"); -\fIint\fP -.RE -.nh -\fBarchive_read_finish\fP -.hy -("struct archive *"); -.SH DESCRIPTION -These functions provide a complete API for reading streaming archives. -The general process is to first create the -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: -.TP -.nh -\fBarchive_read_new\fP -.hy -(); -Allocates and initializes a -Tn struct archive -object suitable for reading from an archive. -.TP -.nh -\fBarchive_read_support_compression_all\fP -.hy -(, .nh); -\fBarchive_read_support_compression_bzip2\fP -.hy -(, .nh); -\fBarchive_read_support_compression_compress\fP -.hy -(, .nh); -\fBarchive_read_support_compression_gzip\fP -.hy -(, .nh); -\fBarchive_read_support_compression_none\fP -.hy -(); -Enables auto-detection code and decompression support for the -specified compression. -Note that -``none'' -is always enabled by default. -For convenience, -.nh -\fBarchive_read_support_compression_all\fP -.hy -(); -enables all available decompression code. -.TP -.nh -\fBarchive_read_support_compression_program\fP -.hy -(); -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 -.nh -\fBarchive_read_support_format_all\fP -.hy -(, .nh); -\fBarchive_read_support_format_cpio\fP -.hy -(, .nh); -\fBarchive_read_support_format_empty\fP -.hy -(, .nh); -\fBarchive_read_support_format_iso9660\fP -.hy -(, .nh); -\fBarchive_read_support_format_tar,\fP -.hy -(.nh); -\fBarchive_read_support_format_zip\fP -.hy -(); -Enables support---including auto-detection code---for the -specified archive format. -For example, -.nh -\fBarchive_read_support_format_tar\fP -.hy -(); -enables support for a variety of standard tar formats, old-style tar, -ustar, pax interchange format, and many common variants. -For convenience, -.nh -\fBarchive_read_support_format_all\fP -.hy -(); -enables support for all available formats. -Only empty archives are supported by default. -.TP -.nh -\fBarchive_read_open\fP -.hy -(); -The same as -.nh -\fBarchive_read_open2\fP -.hy -(,); -except that the skip callback is assumed to be -.BR NULL. -.TP -.nh -\fBarchive_read_open2\fP -.hy -(); -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 -.nh -\fBarchive_read_open_filename\fP -.hy -(,); -.nh -\fBarchive_read_open_FILE\fP -.hy -(,); -.nh -\fBarchive_read_open_fd\fP -.hy -(,); -or -.nh -\fBarchive_read_open_memory\fP -.hy -(); -instead. -The library invokes the client-provided functions to obtain -raw bytes from the archive. -.TP -.nh -\fBarchive_read_open_FILE\fP -.hy -(); -Like -.nh -\fBarchive_read_open\fP -.hy -(,); -except that it accepts a -\fI"FILE *"\fP -.RE -pointer. -This function should not be used with tape drives or other devices -that require strict I/O blocking. -.TP -.nh -\fBarchive_read_open_fd\fP -.hy -(); -Like -.nh -\fBarchive_read_open\fP -.hy -(,); -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 -.nh -\fBarchive_read_open_file\fP -.hy -(); -This is a deprecated synonym for -.nh -\fBarchive_read_open_filename\fP -.hy -(.); -.TP -.nh -\fBarchive_read_open_filename\fP -.hy -(); -Like -.nh -\fBarchive_read_open\fP -.hy -(,); -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 -.nh -\fBarchive_read_open_memory\fP -.hy -(); -Like -.nh -\fBarchive_read_open\fP -.hy -(,); -except that it accepts a pointer and size of a block of -memory containing the archive data. -.TP -.nh -\fBarchive_read_next_header\fP -.hy -(); -Read the header for the next entry and return a pointer to -a -Tn struct archive_entry. -.TP -.nh -\fBarchive_read_data\fP -.hy -(); -Read data associated with the header just read. -Internally, this is a convenience function that calls -.nh -\fBarchive_read_data_block\fP -.hy -(); -and fills any gaps with nulls so that callers see a single -continuous stream of data. -.TP -.nh -\fBarchive_read_data_block\fP -.hy -(); -Return the next available block of data for this entry. -Unlike -.nh -\fBarchive_read_data\fP -.hy -(,); -the -.nh -\fBarchive_read_data_block\fP -.hy -(); -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 -.nh -\fBarchive_read_data_skip\fP -.hy -(); -A convenience function that repeatedly calls -.nh -\fBarchive_read_data_block\fP -.hy -(); -to skip all of the data for this archive entry. -.TP -.nh -\fBarchive_read_data_into_buffer\fP -.hy -(); -This function is deprecated and will be removed. -Use -.nh -\fBarchive_read_data\fP -.hy -(); -instead. -.TP -.nh -\fBarchive_read_data_into_fd\fP -.hy -(); -A convenience function that repeatedly calls -.nh -\fBarchive_read_data_block\fP -.hy -(); -to copy the entire entry to the provided file descriptor. -.TP -.nh -\fBarchive_read_extract\fP -.hy -(, .nh); -\fBarchive_read_extract_set_skip_file\fP -.hy -(); -A convenience function that wraps the corresponding -\fBarchive_write_disk\fP(3) -interfaces. -The first call to -.nh -\fBarchive_read_extract\fP -.hy -(); -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 -.nh -\fBarchive_read_extract_set_progress_callback\fP -.hy -(); -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 -.nh -\fBarchive_read_close\fP -.hy -(); -Complete the archive and invoke the close callback. -.TP -.nh -\fBarchive_read_finish\fP -.hy -(); -Invokes -.nh -\fBarchive_read_close\fP -.hy -(); -if it was not invoked manually, then release all resources. -Note: In libarchive 1.x, this function was declared to return -\fIvoid,\fP -.RE -which made it impossible to detect certain errors when -.nh -\fBarchive_read_close\fP -.hy -(); -was invoked implicitly from this function. -The declaration is corrected beginning with libarchive 2.0. -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. -A complete description of the -Tn struct archive -and -Tn struct archive_entry -objects can be found in the overview manual page for -\fBlibarchive\fP(3). -.SH CLIENT CALLBACKS -The callback functions must match the following prototypes: -.IP -\fItypedef ssize_t\fP -.RE -.nh -\fBarchive_read_callback\fP -.hy -("struct archive *" "void *client_data" "const void **buffer"); -.IP -\fItypedef int\fP -.RE -.nh -\fBarchive_skip_callback\fP -.hy -("struct archive *" "void *client_data" "size_t request"); -.IP -\fItypedef int\fP -.RE -.nh -\fBarchive_open_callback\fP -.hy -("struct archive *" "void *client_data"); -.IP -\fItypedef int\fP -.RE -.nh -\fBarchive_close_callback\fP -.hy -("struct archive *" "void *client_data"); -The open callback is invoked by -.nh -\fBarchive_open\fP -.hy -(.); -It should return -\fBARCHIVE_OK\fP -if the underlying file or data source is successfully -opened. -If the open fails, it should call -.nh -\fBarchive_set_error\fP -.hy -(); -to register an error code and message and return -\fBARCHIVE_FATAL\fP. -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 -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 -.nh -\fBarchive_set_error\fP -.hy -(); -to register an error code and message and -return -1. -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. -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 -.nh -\fBarchive_set_error\fP -.hy -(); -to register an error code and message and -return -\fBARCHIVE_FATAL.\fP -.SH EXAMPLE -The following illustrates basic usage of the library. -In this example, -the callback functions are simply wrappers around the standard -\fBopen\fP(2), -\fBread\fP(2), -and -\fBclose\fP(2) -system calls. -.RS -void -list_archive(const char *name) -{ - struct mydata *mydata; - struct archive *a; - struct archive_entry *entry; - mydata = malloc(sizeof(struct mydata)); - a = archive_read_new(); - mydata->name = name; - archive_read_support_compression_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\\n",archive_entry_pathname(entry)); - archive_read_data_skip(a); - } - archive_read_finish(a); - free(mydata); -} -ssize_t -myread(struct archive *a, void *client_data, const void **buff) -{ - struct mydata *mydata = client_data; - *buff = mydata->buff; - return (read(mydata->fd, mydata->buff, 10240)); -} -int -myopen(struct archive *a, void *client_data) -{ - struct mydata *mydata = client_data; - mydata->fd = open(mydata->name, O_RDONLY); - return (mydata->fd >= 0 ? ARCHIVE_OK : ARCHIVE_FATAL); -} -int -myclose(struct archive *a, void *client_data) -{ - struct mydata *mydata = client_data; - if (mydata->fd > 0) - close(mydata->fd); - return (ARCHIVE_OK); -} -.RE -.SH RETURN VALUES -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 -.nh -\fBarchive_errno\fP -.hy -(); -and -.nh -\fBarchive_error_string\fP -.hy -(); -functions. -.nh -\fBarchive_read_new\fP -.hy -(); -returns a pointer to a freshly allocated -Tn struct archive -object. -It returns -.BR NULL -on error. -.nh -\fBarchive_read_data\fP -.hy -(); -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 -.nh -\fBarchive_errno\fP -.hy -(); -and -.nh -\fBarchive_error_string\fP -.hy -(); -functions. -The library expects the client callbacks to behave similarly. -If there is an error, you can use -.nh -\fBarchive_set_error\fP -.hy -(); -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 -\fBtar\fP(1), -\fBarchive\fP(3), -\fBarchive_util\fP(3), -\fBtar\fP(5) -.SH HISTORY -The -\fBlibarchive\fP -library first appeared in -FreeBSD 5.3. -.SH AUTHORS --nosplit -The -\fBlibarchive\fP -library was written by -Tim Kientzle <kientzle@acm.org.> -.SH BUGS -Many traditional archiver programs treat -empty files as valid empty archives. -For example, many implementations of -\fBtar\fP(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. |