diff options
Diffstat (limited to 'libarchive/libarchive-2.5.5/doc/man/libarchive.3')
| -rw-r--r-- | libarchive/libarchive-2.5.5/doc/man/libarchive.3 | 379 |
1 files changed, 0 insertions, 379 deletions
diff --git a/libarchive/libarchive-2.5.5/doc/man/libarchive.3 b/libarchive/libarchive-2.5.5/doc/man/libarchive.3 deleted file mode 100644 index 722b765..0000000 --- a/libarchive/libarchive-2.5.5/doc/man/libarchive.3 +++ /dev/null @@ -1,379 +0,0 @@ -.TH LIBARCHIVE 3 "August 19, 2006" "" -.SH NAME -\fBlibarchive\fP -\- functions for reading and writing streaming archives -.SH LIBRARY -Lb libarchive -.SH OVERVIEW -The -\fBlibarchive\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. -When reading an archive, the library automatically detects the -format and the compression. -The library currently has read support for: -.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. -The library automatically detects archives compressed with -\fBgzip\fP(1), -\fBbzip2\fP(1), -or -\fBcompress\fP(1) -and decompresses them transparently. -When writing an archive, you can specify the compression -to be used and the format to use. -The library can write -.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. -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. -The read and write APIs are accessed through the -.nh -\fBarchive_read_XXX\fP -.hy -(); -functions and the -.nh -\fBarchive_write_XXX\fP -.hy -(); -functions, respectively, and either can be used independently -of the other. -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 -To read an archive, you must first obtain an initialized -Tn struct archive -object from -.nh -\fBarchive_read_new\fP -.hy -(.); -You can then modify this object for the desired operations with the -various -.nh -\fBarchive_read_set_XXX\fP -.hy -(); -and -.nh -\fBarchive_read_support_XXX\fP -.hy -(); -functions. -In particular, you will need to invoke appropriate -.nh -\fBarchive_read_support_XXX\fP -.hy -(); -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 -.nh -\fBarchive_read_support_compression_all\fP -.hy -(); -and -.nh -\fBarchive_read_support_format_all\fP -.hy -(); -to enable auto-detect for all formats and compression types -currently supported by the library. -Once you have prepared the -Tn struct archive -object, you call -.nh -\fBarchive_read_open\fP -.hy -(); -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, -\fI"FILE *"\fP -.RE -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. -Each archive entry consists of a header followed by a certain -amount of data. -You can obtain the next header with -.nh -\fBarchive_read_next_header\fP -.hy -(,); -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 -.nh -\fBarchive_read_data\fP -.hy -(); -(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 -.nh -\fBarchive_read_data_skip\fP -.hy -(,); -which reads and discards the data for this entry, -.nh -\fBarchive_read_data_to_buffer\fP -.hy -(,); -which reads the data into an in-memory buffer, -.nh -\fBarchive_read_data_to_file\fP -.hy -(,); -which copies the data to the provided file descriptor, or -.nh -\fBarchive_read_extract\fP -.hy -(,); -which recreates the specified entry on disk and copies data -from the archive. -In particular, note that -.nh -\fBarchive_read_extract\fP -.hy -(); -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. -Once you have finished reading data from the archive, you -should call -.nh -\fBarchive_read_close\fP -.hy -(); -to close the archive, then call -.nh -\fBarchive_read_finish\fP -.hy -(); -to release all resources, including all memory allocated by the library. -The -\fBarchive_read\fP(3) -manual page provides more detailed calling information for this API. -.SH WRITING AN ARCHIVE -You use a similar process to write an archive. -The -.nh -\fBarchive_write_new\fP -.hy -(); -function creates an archive object useful for writing, -the various -.nh -\fBarchive_write_set_XXX\fP -.hy -(); -functions are used to set parameters for writing the archive, and -.nh -\fBarchive_write_open\fP -.hy -(); -completes the setup and opens the archive for writing. -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 -.nh -\fBarchive_write_header\fP -.hy -(); -function actually writes the header data to the archive. -You can then use -.nh -\fBarchive_write_data\fP -.hy -(); -to write the actual data. -After all entries have been written, use the -.nh -\fBarchive_write_finish\fP -.hy -(); -function to release all resources. -The -\fBarchive_write\fP(3) -manual page provides more detailed calling information for this API. -.SH DESCRIPTION -Detailed descriptions of each function are provided by the -corresponding manual pages. -All of the functions utilize an opaque -Tn struct archive -datatype that provides access to the archive contents. -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). -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 -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 -.nh -\fBarchive_errno\fP -.hy -(); -function can be used to retrieve a numeric error code (see -\fBerrno\fP(2)). -The -.nh -\fBarchive_error_string\fP -.hy -(); -returns a textual error message suitable for display. -.nh -\fBarchive_read_new\fP -.hy -(); -and -.nh -\fBarchive_write_new\fP -.hy -(); -return pointers to an allocated and initialized -Tn struct archive -object. -.nh -\fBarchive_read_data\fP -.hy -(); -and -.nh -\fBarchive_write_data\fP -.hy -(); -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 -.nh -\fBarchive_errno\fP -.hy -(); -and -.nh -\fBarchive_error_string\fP -.hy -(); -functions can be used to obtain more information. -.SH ENVIRONMENT -There are character set conversions within the -\fBarchive_entry\fP(3) -functions that are impacted by the currently-selected locale. -.SH SEE ALSO -\fBtar\fP(1), -\fBarchive_entry\fP(3), -\fBarchive_read\fP(3), -\fBarchive_util\fP(3), -\fBarchive_write\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 -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. -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. |