From cb3baab306e5951dc3a176fd9061f596a05b4729 Mon Sep 17 00:00:00 2001 From: Tomas Bzatek Date: Sun, 15 Nov 2009 18:32:03 +0100 Subject: Rebase libarchive to 2.7.1 --- libarchive/libarchive-2.7.1/doc/man/libarchive.3 | 315 +++++++++++++++++++++++ 1 file changed, 315 insertions(+) create mode 100644 libarchive/libarchive-2.7.1/doc/man/libarchive.3 (limited to 'libarchive/libarchive-2.7.1/doc/man/libarchive.3') diff --git a/libarchive/libarchive-2.7.1/doc/man/libarchive.3 b/libarchive/libarchive-2.7.1/doc/man/libarchive.3 new file mode 100644 index 0000000..1af1861 --- /dev/null +++ b/libarchive/libarchive-2.7.1/doc/man/libarchive.3 @@ -0,0 +1,315 @@ +.TH LIBARCHIVE 3 "August 19, 2006" "" +.SH NAME +.ad l +\fB\%libarchive\fP +\- functions for reading and writing streaming archives +.SH LIBRARY +.ad l +Lb libarchive +.SH OVERVIEW +.ad l +The +\fB\%libarchive\fP +library provides a flexible interface for reading and writing +streaming archive files such as tar and cpio. +The library is inherently stream-oriented; readers serially iterate through +the archive, writers serially add things to the archive. +In particular, note that there is no built-in support for +random access nor for in-place modification. +.PP +When reading an archive, the library automatically detects the +format and the compression. +The library currently has read support for: +.RS 5 +.IP \(bu +old-style tar archives, +.IP \(bu +most variants of the POSIX +``ustar'' +format, +.IP \(bu +the POSIX +``pax interchange'' +format, +.IP \(bu +GNU-format tar archives, +.IP \(bu +most common cpio archive formats, +.IP \(bu +ISO9660 CD images (with or without RockRidge extensions), +.IP \(bu +Zip archives. +.RE +The library automatically detects archives compressed with +\fBgzip\fP(1), +\fBbzip2\fP(1), +or +\fBcompress\fP(1) +and decompresses them transparently. +.PP +When writing an archive, you can specify the compression +to be used and the format to use. +The library can write +.RS 5 +.IP \(bu +POSIX-standard +``ustar'' +archives, +.IP \(bu +POSIX +``pax interchange format'' +archives, +.IP \(bu +POSIX octet-oriented cpio archives, +.IP \(bu +two different variants of shar archives. +.RE +Pax interchange format is an extension of the tar archive format that +eliminates essentially all of the limitations of historic tar formats +in a standard fashion that is supported +by POSIX-compliant +\fBpax\fP(1) +implementations on many systems as well as several newer implementations of +\fBtar\fP(1). +Note that the default write format will suppress the pax extended +attributes for most entries; explicitly requesting pax format will +enable those attributes for all entries. +.PP +The read and write APIs are accessed through the +\fB\%archive_read_XXX\fP() +functions and the +\fB\%archive_write_XXX\fP() +functions, respectively, and either can be used independently +of the other. +.PP +The rest of this manual page provides an overview of the library +operation. +More detailed information can be found in the individual manual +pages for each API or utility function. +.SH READING AN ARCHIVE +.ad l +To read an archive, you must first obtain an initialized +Tn struct archive +object from +\fB\%archive_read_new\fP(). +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_compression_all\fP() +and +\fB\%archive_read_support_format_all\fP() +to enable auto-detect for all formats and compression types +currently supported by the library. +.PP +Once you have prepared the +Tn struct archive +object, you call +\fB\%archive_read_open\fP() +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 +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. +.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 +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() +(which works much like the +\fBread\fP(2) +system call) +to read this data from the archive. +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_to_buffer\fP(), +which reads the data into an in-memory buffer, +\fB\%archive_read_data_to_file\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() +uses the +Tn struct archive_entry +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. +.PP +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_finish\fP() +to release all resources, including all memory allocated by the library. +.PP +The +\fBarchive_read\fP(3) +manual page provides more detailed calling information for this API. +.SH WRITING AN ARCHIVE +.ad l +You use a similar process to write an archive. +The +\fB\%archive_write_new\fP() +function creates an archive object useful for writing, +the various +\fB\%archive_write_set_XXX\fP() +functions are used to set parameters for writing the archive, and +\fB\%archive_write_open\fP() +completes the setup and opens the archive for writing. +.PP +Individual archive entries are written in a three-step +process: +You first initialize a +Tn struct archive_entry +structure with information about the new entry. +At a minimum, you should set the pathname of the +entry and provide a +\fIstruct\fP stat +with a valid +\fIst_mode\fP +field, which specifies the type of object and +\fIst_size\fP +field, which specifies the size of the data portion of the object. +The +\fB\%archive_write_header\fP() +function actually writes the header data to the archive. +You can then use +\fB\%archive_write_data\fP() +to write the actual data. +.PP +After all entries have been written, use the +\fB\%archive_write_finish\fP() +function to release all resources. +.PP +The +\fBarchive_write\fP(3) +manual page provides more detailed calling information for this API. +.SH DESCRIPTION +.ad l +Detailed descriptions of each function are provided by the +corresponding manual pages. +.PP +All of the functions utilize an opaque +Tn struct archive +datatype that provides access to the archive contents. +.PP +The +Tn struct archive_entry +structure contains a complete description of a single archive +entry. +It uses an opaque interface that is fully documented in +\fBarchive_entry\fP(3). +.PP +Users familiar with historic formats should be aware that the newer +variants have eliminated most restrictions on the length of textual fields. +Clients should not assume that filenames, link names, user names, or +group names are limited in length. +In particular, pax interchange format can easily accommodate pathnames +in arbitrary character sets that exceed +\fIPATH_MAX\fP. +.SH RETURN VALUES +.ad l +Most functions return zero on success, non-zero on error. +The return value indicates the general severity of the error, ranging +from +\fBARCHIVE_WARN\fP, +which indicates a minor problem that should probably be reported +to the user, to +\fBARCHIVE_FATAL\fP, +which indicates a serious problem that will prevent any further +operations on this archive. +On error, the +\fB\%archive_errno\fP() +function can be used to retrieve a numeric error code (see +\fBerrno\fP(2)). +The +\fB\%archive_error_string\fP() +returns a textual error message suitable for display. +.PP +\fB\%archive_read_new\fP() +and +\fB\%archive_write_new\fP() +return pointers to an allocated and initialized +Tn struct archive +object. +.PP +\fB\%archive_read_data\fP() +and +\fB\%archive_write_data\fP() +return a count of the number of bytes actually read or written. +A value of zero indicates the end of the data for this entry. +A negative value indicates an error, in which case the +\fB\%archive_errno\fP() +and +\fB\%archive_error_string\fP() +functions can be used to obtain more information. +.SH ENVIRONMENT +.ad l +There are character set conversions within the +\fBarchive_entry\fP(3) +functions that are impacted by the currently-selected locale. +.SH SEE ALSO +.ad l +\fBtar\fP(1), +\fBarchive_entry\fP(3), +\fBarchive_read\fP(3), +\fBarchive_util\fP(3), +\fBarchive_write\fP(3), +\fBtar\fP(5) +.SH HISTORY +.ad l +The +\fB\%libarchive\fP +library first appeared in +FreeBSD 5.3. +.SH AUTHORS +.ad l +-nosplit +The +\fB\%libarchive\fP +library was written by +Tim Kientzle \% +.SH BUGS +.ad l +Some archive formats support information that is not supported by +Tn struct archive_entry. +Such information cannot be fully archived or restored using this library. +This includes, for example, comments, character sets, +or the arbitrary key/value pairs that can appear in +pax interchange format archives. +.PP +Conversely, of course, not all of the information that can be +stored in an +Tn struct archive_entry +is supported by all formats. +For example, cpio formats do not support nanosecond timestamps; +old tar formats do not support large device numbers. -- cgit v1.2.3