diff options
author | joerg <joerg@pkgsrc.org> | 2010-02-20 03:48:25 +0000 |
---|---|---|
committer | joerg <joerg@pkgsrc.org> | 2010-02-20 03:48:25 +0000 |
commit | 813e1c65cfea70db0fa02bd006013a08731f470f (patch) | |
tree | f2e9909a57c8ba8f986b13e36ed04e225fc44b2a /archivers/libarchive/files/doc/wiki/ManPageLibarchive3.wiki | |
parent | a3bb8bd3027e67eb07c16f479613f290fb214f4a (diff) | |
download | pkgsrc-813e1c65cfea70db0fa02bd006013a08731f470f.tar.gz |
Import libarchive 2.8.0:
- Infrastructure:
- Allow command line tools as fallback for missing compression
libraries. If compiled without gzip for example, gunzip will
be used automatically.
- Improved support for a number of platforms like high-resolution
timestamps and Extended Attributes on various Unix systems
- New convience interface for creating archives based on disk content,
complement of the archive_write_disk interface.
- Frontends:
- bsdcpio ready for public consumption
- hand-written date parser replaces the yacc code
- Filter system:
- Simplified read filter chains
- Option support for filters
- LZMA, XZ, uudecode handled
- Format support:
- Write support for mtree files based on file system or archive
content
- Basic read support for Joliet
- Write support for zip files
- Write support for shar archives, both text-only and binary-safe
Diffstat (limited to 'archivers/libarchive/files/doc/wiki/ManPageLibarchive3.wiki')
-rw-r--r-- | archivers/libarchive/files/doc/wiki/ManPageLibarchive3.wiki | 302 |
1 files changed, 302 insertions, 0 deletions
diff --git a/archivers/libarchive/files/doc/wiki/ManPageLibarchive3.wiki b/archivers/libarchive/files/doc/wiki/ManPageLibarchive3.wiki new file mode 100644 index 00000000000..997212f1232 --- /dev/null +++ b/archivers/libarchive/files/doc/wiki/ManPageLibarchive3.wiki @@ -0,0 +1,302 @@ +#summary LIBARCHIVE 3 manual page +== NAME == +*libarchive* +- functions for reading and writing streaming archives +== LIBRARY == +Lb libarchive +== OVERVIEW == +The +*libarchive* +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: +<ul> +<li> +old-style tar archives, +</li><li> +most variants of the POSIX +"ustar" +format, +</li><li> +the POSIX +"pax interchange" +format, +</li><li> +GNU-format tar archives, +</li><li> +most common cpio archive formats, +</li><li> +ISO9660 CD images (with or without RockRidge extensions), +</li><li> +Zip archives. +</li></ul> +The library automatically detects archives compressed with +*gzip*(1), +*bzip2*(1), +or +*compress*(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 +<ul> +<li> +POSIX-standard +"ustar" +archives, +</li><li> +POSIX +"pax interchange format" +archives, +</li><li> +POSIX octet-oriented cpio archives, +</li><li> +two different variants of shar archives. +</li></ul> +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. + +The read and write APIs are accessed through the +*archive_read_XXX*() +functions and the +*archive_write_XXX*() +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. +== READING AN ARCHIVE == +To read an archive, you must first obtain an initialized +*struct archive* +object from +*archive_read_new*(). +You can then modify this object for the desired operations with the +various +*archive_read_set_XXX*() +and +*archive_read_support_XXX*() +functions. +In particular, you will need to invoke appropriate +*archive_read_support_XXX*() +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 +*archive_read_support_compression_all*() +and +*archive_read_support_format_all*() +to enable auto-detect for all formats and compression types +currently supported by the library. + +Once you have prepared the +*struct archive* +object, you call +*archive_read_open*() +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, +*FILE `*`* +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 +*archive_read_next_header*(), +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 +*archive_read_data*() +(which works much like the +*read*(2) +system call) +to read this data from the archive. +You may prefer to use the higher-level +*archive_read_data_skip*(), +which reads and discards the data for this entry, +*archive_read_data_to_buffer*(), +which reads the data into an in-memory buffer, +*archive_read_data_to_file*(), +which copies the data to the provided file descriptor, or +*archive_read_extract*(), +which recreates the specified entry on disk and copies data +from the archive. +In particular, note that +*archive_read_extract*() +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. + +Once you have finished reading data from the archive, you +should call +*archive_read_close*() +to close the archive, then call +*archive_read_finish*() +to release all resources, including all memory allocated by the library. + +The +*archive_read*(3) +manual page provides more detailed calling information for this API. +== WRITING AN ARCHIVE == +You use a similar process to write an archive. +The +*archive_write_new*() +function creates an archive object useful for writing, +the various +*archive_write_set_XXX*() +functions are used to set parameters for writing the archive, and +*archive_write_open*() +completes the setup and opens the archive for writing. + +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 +_struct_ stat +with a valid +_st_mode_ +field, which specifies the type of object and +_st_size_ +field, which specifies the size of the data portion of the object. +The +*archive_write_header*() +function actually writes the header data to the archive. +You can then use +*archive_write_data*() +to write the actual data. + +After all entries have been written, use the +*archive_write_finish*() +function to release all resources. + +The +*archive_write*(3) +manual page provides more detailed calling information for this API. +== DESCRIPTION == +Detailed descriptions of each function are provided by the +corresponding manual pages. + +All of the functions utilize an opaque +*struct archive* +datatype that provides access to the archive contents. + +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). + +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 +_PATH_MAX_. +== RETURN VALUES == +Most functions return zero on success, non-zero on error. +The return value indicates the general severity of the error, ranging +from +*ARCHIVE_WARN*, +which indicates a minor problem that should probably be reported +to the user, to +*ARCHIVE_FATAL*, +which indicates a serious problem that will prevent any further +operations on this archive. +On error, the +*archive_errno*() +function can be used to retrieve a numeric error code (see +*errno*(2)). +The +*archive_error_string*() +returns a textual error message suitable for display. + +*archive_read_new*() +and +*archive_write_new*() +return pointers to an allocated and initialized +*struct archive* +object. + +*archive_read_data*() +and +*archive_write_data*() +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 +*archive_errno*() +and +*archive_error_string*() +functions can be used to obtain more information. +== ENVIRONMENT == +There are character set conversions within the +*archive_entry*(3) +functions that are impacted by the currently-selected locale. +== SEE ALSO == +*tar*(1), +*archive_entry*(3), +*archive_read*(3), +*archive_util*(3), +*archive_write*(3), +*tar*(5) +== HISTORY == +The +*libarchive* +library first appeared in +FreeBSD 5.3. +== AUTHORS == +The +*libarchive* +library was written by +Tim Kientzle <kientzle@acm.org.> +== BUGS == +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. + +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. |