diff options
| author | Tomas Bzatek <tbzatek@redhat.com> | 2010-02-05 11:06:31 +0100 |
|---|---|---|
| committer | Tomas Bzatek <tbzatek@redhat.com> | 2010-02-05 11:06:31 +0100 |
| commit | baea7d877d3cf69679a39e8512a120658a478073 (patch) | |
| tree | 37c9a98cb3d3a322f3f91c8ca656ccd6bd2eaebe /libarchive/libarchive-2.8.0/doc/html/libarchive.3.html | |
| parent | e42a4ff3031aa1c1aaf27aa34d9395fec185924b (diff) | |
| download | tuxcmd-modules-baea7d877d3cf69679a39e8512a120658a478073.tar.xz | |
Rebase libarchive to 2.8.0
Diffstat (limited to 'libarchive/libarchive-2.8.0/doc/html/libarchive.3.html')
| -rw-r--r-- | libarchive/libarchive-2.8.0/doc/html/libarchive.3.html | 329 |
1 files changed, 329 insertions, 0 deletions
diff --git a/libarchive/libarchive-2.8.0/doc/html/libarchive.3.html b/libarchive/libarchive-2.8.0/doc/html/libarchive.3.html new file mode 100644 index 0000000..f02d7cb --- /dev/null +++ b/libarchive/libarchive-2.8.0/doc/html/libarchive.3.html @@ -0,0 +1,329 @@ +<!-- Creator : groff version 1.19.2 --> +<!-- CreationDate: Thu Feb 4 20:36:35 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">LIBARCHIVE(3) FreeBSD Library Functions +Manual LIBARCHIVE(3)</p> + +<p style="margin-top: 1em" valign="top"><b>NAME</b></p> + +<p style="margin-left:8%;"><b>libarchive</b> — +functions for reading and writing streaming archives</p> + +<p style="margin-top: 1em" valign="top"><b>LIBRARY</b></p> + +<p style="margin-left:8%;">Streaming Archive Library +(libarchive, −larchive)</p> + + +<p style="margin-top: 1em" valign="top"><b>OVERVIEW</b></p> + +<p style="margin-left:8%;">The <b>libarchive</b> 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.</p> + +<p style="margin-left:8%; margin-top: 1em">When reading an +archive, the library automatically detects the format and +the compression. The library currently has read support +for:</p> + +<p valign="top"><b>•</b></p> + +<p style="margin-left:14%;">old-style tar archives,</p> + +<p valign="top"><b>•</b></p> + +<p style="margin-left:14%;">most variants of the POSIX +‘‘ustar’’ format,</p> + +<p valign="top"><b>•</b></p> + +<p style="margin-left:14%;">the POSIX ‘‘pax +interchange’’ format,</p> + +<p valign="top"><b>•</b></p> + +<p style="margin-left:14%;">GNU-format tar archives,</p> + +<p valign="top"><b>•</b></p> + +<p style="margin-left:14%;">most common cpio archive +formats,</p> + +<p valign="top"><b>•</b></p> + +<p style="margin-left:14%;">ISO9660 CD images (with or +without RockRidge extensions),</p> + +<p valign="top"><b>•</b></p> + +<p style="margin-left:14%;">Zip archives.</p> + +<p style="margin-left:8%;">The library automatically +detects archives compressed with gzip(1), bzip2(1), or +compress(1) and decompresses them transparently.</p> + +<p style="margin-left:8%; margin-top: 1em">When writing an +archive, you can specify the compression to be used and the +format to use. The library can write</p> + +<p valign="top"><b>•</b></p> + +<p style="margin-left:14%;">POSIX-standard +‘‘ustar’’ archives,</p> + +<p valign="top"><b>•</b></p> + +<p style="margin-left:14%;">POSIX ‘‘pax +interchange format’’ archives,</p> + +<p valign="top"><b>•</b></p> + +<p style="margin-left:14%;">POSIX octet-oriented cpio +archives,</p> + +<p valign="top"><b>•</b></p> + +<p style="margin-left:14%;">two different variants of shar +archives.</p> + +<p style="margin-left:8%;">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 +pax(1) implementations on many systems as well as several +newer implementations of tar(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.</p> + +<p style="margin-left:8%; margin-top: 1em">The read and +write APIs are accessed through the +<b>archive_read_XXX</b>() functions and the +<b>archive_write_XXX</b>() functions, respectively, and +either can be used independently of the other.</p> + +<p style="margin-left:8%; margin-top: 1em">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.</p> + +<p style="margin-top: 1em" valign="top"><b>READING AN +ARCHIVE</b></p> + +<p style="margin-left:8%;">To read an archive, you must +first obtain an initialized struct archive object from +<b>archive_read_new</b>(). You can then modify this object +for the desired operations with the various +<b>archive_read_set_XXX</b>() and +<b>archive_read_support_XXX</b>() functions. In particular, +you will need to invoke appropriate +<b>archive_read_support_XXX</b>() 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 <b>archive_read_support_compression_all</b>() +and <b>archive_read_support_format_all</b>() to enable +auto-detect for all formats and compression types currently +supported by the library.</p> + +<p style="margin-left:8%; margin-top: 1em">Once you have +prepared the struct archive object, you call +<b>archive_read_open</b>() 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, <i>FILE *</i> 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.</p> + +<p style="margin-left:8%; margin-top: 1em">Each archive +entry consists of a header followed by a certain amount of +data. You can obtain the next header with +<b>archive_read_next_header</b>(), which returns a pointer +to an 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 <b>archive_read_data</b>() (which works much like the +read(2) system call) to read this data from the archive. You +may prefer to use the higher-level +<b>archive_read_data_skip</b>(), which reads and discards +the data for this entry, +<b>archive_read_data_to_buffer</b>(), which reads the data +into an in-memory buffer, +<b>archive_read_data_to_file</b>(), which copies the data to +the provided file descriptor, or +<b>archive_read_extract</b>(), which recreates the specified +entry on disk and copies data from the archive. In +particular, note that <b>archive_read_extract</b>() uses the +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.</p> + +<p style="margin-left:8%; margin-top: 1em">Once you have +finished reading data from the archive, you should call +<b>archive_read_close</b>() to close the archive, then call +<b>archive_read_finish</b>() to release all resources, +including all memory allocated by the library.</p> + +<p style="margin-left:8%; margin-top: 1em">The +archive_read(3) manual page provides more detailed calling +information for this API.</p> + +<p style="margin-top: 1em" valign="top"><b>WRITING AN +ARCHIVE</b></p> + +<p style="margin-left:8%;">You use a similar process to +write an archive. The <b>archive_write_new</b>() function +creates an archive object useful for writing, the various +<b>archive_write_set_XXX</b>() functions are used to set +parameters for writing the archive, and +<b>archive_write_open</b>() completes the setup and opens +the archive for writing.</p> + +<p style="margin-left:8%; margin-top: 1em">Individual +archive entries are written in a three-step process: You +first initialize a struct archive_entry structure with +information about the new entry. At a minimum, you should +set the pathname of the entry and provide a <i>struct +stat</i> with a valid <i>st_mode</i> field, which specifies +the type of object and <i>st_size</i> field, which specifies +the size of the data portion of the object. The +<b>archive_write_header</b>() function actually writes the +header data to the archive. You can then use +<b>archive_write_data</b>() to write the actual data.</p> + +<p style="margin-left:8%; margin-top: 1em">After all +entries have been written, use the +<b>archive_write_finish</b>() function to release all +resources.</p> + +<p style="margin-left:8%; margin-top: 1em">The +archive_write(3) manual page provides more detailed calling +information for this API.</p> + + +<p style="margin-top: 1em" valign="top"><b>DESCRIPTION</b></p> + +<p style="margin-left:8%;">Detailed descriptions of each +function are provided by the corresponding manual pages.</p> + +<p style="margin-left:8%; margin-top: 1em">All of the +functions utilize an opaque struct archive datatype that +provides access to the archive contents.</p> + +<p style="margin-left:8%; margin-top: 1em">The struct +archive_entry structure contains a complete description of a +single archive entry. It uses an opaque interface that is +fully documented in archive_entry(3).</p> + +<p style="margin-left:8%; margin-top: 1em">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 <i>PATH_MAX</i>.</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 return value indicates the +general severity of the error, ranging from +<b>ARCHIVE_WARN</b>, which indicates a minor problem that +should probably be reported to the user, to +<b>ARCHIVE_FATAL</b>, which indicates a serious problem that +will prevent any further operations on this archive. On +error, the <b>archive_errno</b>() function can be used to +retrieve a numeric error code (see errno(2)). The +<b>archive_error_string</b>() returns a textual error +message suitable for display.</p> + + +<p style="margin-left:8%; margin-top: 1em"><b>archive_read_new</b>() +and <b>archive_write_new</b>() return pointers to an +allocated and initialized struct archive object.</p> + + +<p style="margin-left:8%; margin-top: 1em"><b>archive_read_data</b>() +and <b>archive_write_data</b>() 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 <b>archive_errno</b>() +and <b>archive_error_string</b>() functions can be used to +obtain more information.</p> + + +<p style="margin-top: 1em" valign="top"><b>ENVIRONMENT</b></p> + +<p style="margin-left:8%;">There are character set +conversions within the archive_entry(3) functions that are +impacted by the currently-selected locale.</p> + +<p style="margin-top: 1em" valign="top"><b>SEE ALSO</b></p> + +<p style="margin-left:8%;">tar(1), archive_entry(3), +archive_read(3), archive_util(3), archive_write(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%;">Some archive formats support +information that is not supported by 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.</p> + +<p style="margin-left:8%; margin-top: 1em">Conversely, of +course, not all of the information that can be stored in an +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.</p> + + +<p style="margin-left:8%; margin-top: 1em">FreeBSD 8.0 +August 19, 2006 FreeBSD 8.0</p> +<hr> +</body> +</html> |