diff options
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, 0 insertions, 329 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 deleted file mode 100644 index f02d7cb..0000000 --- a/libarchive/libarchive-2.8.0/doc/html/libarchive.3.html +++ /dev/null @@ -1,329 +0,0 @@ -<!-- 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> |