|
Packit Service |
1d0348 |
.TH LIBARCHIVE 3 "March 18, 2012" ""
|
|
Packit Service |
1d0348 |
.SH NAME
|
|
Packit Service |
1d0348 |
.ad l
|
|
Packit Service |
1d0348 |
\fB\%libarchive\fP
|
|
Packit Service |
1d0348 |
\- functions for reading and writing streaming archives
|
|
Packit Service |
1d0348 |
.SH OVERVIEW
|
|
Packit Service |
1d0348 |
.ad l
|
|
Packit Service |
1d0348 |
The
|
|
Packit Service |
1d0348 |
\fB\%libarchive\fP
|
|
Packit Service |
1d0348 |
library provides a flexible interface for reading and writing
|
|
Packit Service |
1d0348 |
archives in various formats such as tar and cpio.
|
|
Packit Service |
1d0348 |
\fB\%libarchive\fP
|
|
Packit Service |
1d0348 |
also supports reading and writing archives compressed using
|
|
Packit Service |
1d0348 |
various compression filters such as gzip and bzip2.
|
|
Packit Service |
1d0348 |
The library is inherently stream-oriented; readers serially iterate through
|
|
Packit Service |
1d0348 |
the archive, writers serially add things to the archive.
|
|
Packit Service |
1d0348 |
In particular, note that there is currently no built-in support for
|
|
Packit Service |
1d0348 |
random access nor for in-place modification.
|
|
Packit Service |
1d0348 |
.PP
|
|
Packit Service |
1d0348 |
When reading an archive, the library automatically detects the
|
|
Packit Service |
1d0348 |
format and the compression.
|
|
Packit Service |
1d0348 |
The library currently has read support for:
|
|
Packit Service |
1d0348 |
.RS 5
|
|
Packit Service |
1d0348 |
.IP \(bu
|
|
Packit Service |
1d0348 |
old-style tar archives,
|
|
Packit Service |
1d0348 |
.IP \(bu
|
|
Packit Service |
1d0348 |
most variants of the POSIX
|
|
Packit Service |
1d0348 |
``ustar''
|
|
Packit Service |
1d0348 |
format,
|
|
Packit Service |
1d0348 |
.IP \(bu
|
|
Packit Service |
1d0348 |
the POSIX
|
|
Packit Service |
1d0348 |
``pax interchange''
|
|
Packit Service |
1d0348 |
format,
|
|
Packit Service |
1d0348 |
.IP \(bu
|
|
Packit Service |
1d0348 |
GNU-format tar archives,
|
|
Packit Service |
1d0348 |
.IP \(bu
|
|
Packit Service |
1d0348 |
most common cpio archive formats,
|
|
Packit Service |
1d0348 |
.IP \(bu
|
|
Packit Service |
1d0348 |
ISO9660 CD images (including RockRidge and Joliet extensions),
|
|
Packit Service |
1d0348 |
.IP \(bu
|
|
Packit Service |
1d0348 |
Zip archives,
|
|
Packit Service |
1d0348 |
.IP \(bu
|
|
Packit Service |
1d0348 |
ar archives (including GNU/SysV and BSD extensions),
|
|
Packit Service |
1d0348 |
.IP \(bu
|
|
Packit Service |
1d0348 |
Microsoft CAB archives,
|
|
Packit Service |
1d0348 |
.IP \(bu
|
|
Packit Service |
1d0348 |
LHA archives,
|
|
Packit Service |
1d0348 |
.IP \(bu
|
|
Packit Service |
1d0348 |
mtree file tree descriptions,
|
|
Packit Service |
1d0348 |
.IP \(bu
|
|
Packit Service |
1d0348 |
RAR archives,
|
|
Packit Service |
1d0348 |
.IP \(bu
|
|
Packit Service |
1d0348 |
XAR archives.
|
|
Packit Service |
1d0348 |
.RE
|
|
Packit Service |
1d0348 |
The library automatically detects archives compressed with
|
|
Packit Service |
1d0348 |
\fBgzip\fP(1),
|
|
Packit Service |
1d0348 |
\fBbzip2\fP(1),
|
|
Packit Service |
1d0348 |
\fBxz\fP(1),
|
|
Packit Service |
1d0348 |
\fBlzip\fP(1),
|
|
Packit Service |
1d0348 |
or
|
|
Packit Service |
1d0348 |
\fBcompress\fP(1)
|
|
Packit Service |
1d0348 |
and decompresses them transparently.
|
|
Packit Service |
1d0348 |
It can similarly detect and decode archives processed with
|
|
Packit Service |
1d0348 |
\fBuuencode\fP(1)
|
|
Packit Service |
1d0348 |
or which have an
|
|
Packit Service |
1d0348 |
\fBrpm\fP(1)
|
|
Packit Service |
1d0348 |
header.
|
|
Packit Service |
1d0348 |
.PP
|
|
Packit Service |
1d0348 |
When writing an archive, you can specify the compression
|
|
Packit Service |
1d0348 |
to be used and the format to use.
|
|
Packit Service |
1d0348 |
The library can write
|
|
Packit Service |
1d0348 |
.RS 5
|
|
Packit Service |
1d0348 |
.IP \(bu
|
|
Packit Service |
1d0348 |
POSIX-standard
|
|
Packit Service |
1d0348 |
``ustar''
|
|
Packit Service |
1d0348 |
archives,
|
|
Packit Service |
1d0348 |
.IP \(bu
|
|
Packit Service |
1d0348 |
POSIX
|
|
Packit Service |
1d0348 |
``pax interchange format''
|
|
Packit Service |
1d0348 |
archives,
|
|
Packit Service |
1d0348 |
.IP \(bu
|
|
Packit Service |
1d0348 |
POSIX octet-oriented cpio archives,
|
|
Packit Service |
1d0348 |
.IP \(bu
|
|
Packit Service |
1d0348 |
Zip archive,
|
|
Packit Service |
1d0348 |
.IP \(bu
|
|
Packit Service |
1d0348 |
two different variants of shar archives,
|
|
Packit Service |
1d0348 |
.IP \(bu
|
|
Packit Service |
1d0348 |
ISO9660 CD images,
|
|
Packit Service |
1d0348 |
.IP \(bu
|
|
Packit Service |
1d0348 |
7-Zip archives,
|
|
Packit Service |
1d0348 |
.IP \(bu
|
|
Packit Service |
1d0348 |
ar archives,
|
|
Packit Service |
1d0348 |
.IP \(bu
|
|
Packit Service |
1d0348 |
mtree file tree descriptions,
|
|
Packit Service |
1d0348 |
.IP \(bu
|
|
Packit Service |
1d0348 |
XAR archives.
|
|
Packit Service |
1d0348 |
.RE
|
|
Packit Service |
1d0348 |
Pax interchange format is an extension of the tar archive format that
|
|
Packit Service |
1d0348 |
eliminates essentially all of the limitations of historic tar formats
|
|
Packit Service |
1d0348 |
in a standard fashion that is supported
|
|
Packit Service |
1d0348 |
by POSIX-compliant
|
|
Packit Service |
1d0348 |
\fBpax\fP(1)
|
|
Packit Service |
1d0348 |
implementations on many systems as well as several newer implementations of
|
|
Packit Service |
1d0348 |
\fBtar\fP(1).
|
|
Packit Service |
1d0348 |
Note that the default write format will suppress the pax extended
|
|
Packit Service |
1d0348 |
attributes for most entries; explicitly requesting pax format will
|
|
Packit Service |
1d0348 |
enable those attributes for all entries.
|
|
Packit Service |
1d0348 |
.PP
|
|
Packit Service |
1d0348 |
The read and write APIs are accessed through the
|
|
Packit Service |
1d0348 |
\fB\%archive_read_XXX\fP()
|
|
Packit Service |
1d0348 |
functions and the
|
|
Packit Service |
1d0348 |
\fB\%archive_write_XXX\fP()
|
|
Packit Service |
1d0348 |
functions, respectively, and either can be used independently
|
|
Packit Service |
1d0348 |
of the other.
|
|
Packit Service |
1d0348 |
.PP
|
|
Packit Service |
1d0348 |
The rest of this manual page provides an overview of the library
|
|
Packit Service |
1d0348 |
operation.
|
|
Packit Service |
1d0348 |
More detailed information can be found in the individual manual
|
|
Packit Service |
1d0348 |
pages for each API or utility function.
|
|
Packit Service |
1d0348 |
.SH READING AN ARCHIVE
|
|
Packit Service |
1d0348 |
.ad l
|
|
Packit Service |
1d0348 |
See
|
|
Packit Service |
1d0348 |
\fBarchive_read\fP(3).
|
|
Packit Service |
1d0348 |
.SH WRITING AN ARCHIVE
|
|
Packit Service |
1d0348 |
.ad l
|
|
Packit Service |
1d0348 |
See
|
|
Packit Service |
1d0348 |
\fBarchive_write\fP(3).
|
|
Packit Service |
1d0348 |
.SH WRITING ENTRIES TO DISK
|
|
Packit Service |
1d0348 |
.ad l
|
|
Packit Service |
1d0348 |
The
|
|
Packit Service |
1d0348 |
\fBarchive_write_disk\fP(3)
|
|
Packit Service |
1d0348 |
API allows you to write
|
|
Packit Service |
1d0348 |
\fBarchive_entry\fP(3)
|
|
Packit Service |
1d0348 |
objects to disk using the same API used by
|
|
Packit Service |
1d0348 |
\fBarchive_write\fP(3).
|
|
Packit Service |
1d0348 |
The
|
|
Packit Service |
1d0348 |
\fBarchive_write_disk\fP(3)
|
|
Packit Service |
1d0348 |
API is used internally by
|
|
Packit Service |
1d0348 |
\fB\%archive_read_extract\fP(\fI\%;\fP)
|
|
Packit Service |
1d0348 |
using it directly can provide greater control over how entries
|
|
Packit Service |
1d0348 |
get written to disk.
|
|
Packit Service |
1d0348 |
This API also makes it possible to share code between
|
|
Packit Service |
1d0348 |
archive-to-archive copy and archive-to-disk extraction
|
|
Packit Service |
1d0348 |
operations.
|
|
Packit Service |
1d0348 |
.SH READING ENTRIES FROM DISK
|
|
Packit Service |
1d0348 |
.ad l
|
|
Packit Service |
1d0348 |
The
|
|
Packit Service |
1d0348 |
\fBarchive_read_disk\fP(3)
|
|
Packit Service |
1d0348 |
supports for populating
|
|
Packit Service |
1d0348 |
\fBarchive_entry\fP(3)
|
|
Packit Service |
1d0348 |
objects from information in the filesystem.
|
|
Packit Service |
1d0348 |
This includes the information accessible from the
|
|
Packit Service |
1d0348 |
\fBstat\fP(2)
|
|
Packit Service |
1d0348 |
system call as well as ACLs, extended attributes,
|
|
Packit Service |
1d0348 |
and other metadata.
|
|
Packit Service |
1d0348 |
The
|
|
Packit Service |
1d0348 |
\fBarchive_read_disk\fP(3)
|
|
Packit Service |
1d0348 |
API also supports iterating over directory trees,
|
|
Packit Service |
1d0348 |
which allows directories of files to be read using
|
|
Packit Service |
1d0348 |
an API compatible with
|
|
Packit Service |
1d0348 |
the
|
|
Packit Service |
1d0348 |
\fBarchive_read\fP(3)
|
|
Packit Service |
1d0348 |
API.
|
|
Packit Service |
1d0348 |
.SH DESCRIPTION
|
|
Packit Service |
1d0348 |
.ad l
|
|
Packit Service |
1d0348 |
Detailed descriptions of each function are provided by the
|
|
Packit Service |
1d0348 |
corresponding manual pages.
|
|
Packit Service |
1d0348 |
.PP
|
|
Packit Service |
1d0348 |
All of the functions utilize an opaque
|
|
Packit Service |
1d0348 |
Tn struct archive
|
|
Packit Service |
1d0348 |
datatype that provides access to the archive contents.
|
|
Packit Service |
1d0348 |
.PP
|
|
Packit Service |
1d0348 |
The
|
|
Packit Service |
1d0348 |
Tn struct archive_entry
|
|
Packit Service |
1d0348 |
structure contains a complete description of a single archive
|
|
Packit Service |
1d0348 |
entry.
|
|
Packit Service |
1d0348 |
It uses an opaque interface that is fully documented in
|
|
Packit Service |
1d0348 |
\fBarchive_entry\fP(3).
|
|
Packit Service |
1d0348 |
.PP
|
|
Packit Service |
1d0348 |
Users familiar with historic formats should be aware that the newer
|
|
Packit Service |
1d0348 |
variants have eliminated most restrictions on the length of textual fields.
|
|
Packit Service |
1d0348 |
Clients should not assume that filenames, link names, user names, or
|
|
Packit Service |
1d0348 |
group names are limited in length.
|
|
Packit Service |
1d0348 |
In particular, pax interchange format can easily accommodate pathnames
|
|
Packit Service |
1d0348 |
in arbitrary character sets that exceed
|
|
Packit Service |
1d0348 |
\fIPATH_MAX\fP.
|
|
Packit Service |
1d0348 |
.SH RETURN VALUES
|
|
Packit Service |
1d0348 |
.ad l
|
|
Packit Service |
1d0348 |
Most functions return
|
|
Packit Service |
1d0348 |
\fBARCHIVE_OK\fP
|
|
Packit Service |
1d0348 |
(zero) on success, non-zero on error.
|
|
Packit Service |
1d0348 |
The return value indicates the general severity of the error, ranging
|
|
Packit Service |
1d0348 |
from
|
|
Packit Service |
1d0348 |
\fBARCHIVE_WARN\fP,
|
|
Packit Service |
1d0348 |
which indicates a minor problem that should probably be reported
|
|
Packit Service |
1d0348 |
to the user, to
|
|
Packit Service |
1d0348 |
\fBARCHIVE_FATAL\fP,
|
|
Packit Service |
1d0348 |
which indicates a serious problem that will prevent any further
|
|
Packit Service |
1d0348 |
operations on this archive.
|
|
Packit Service |
1d0348 |
On error, the
|
|
Packit Service |
1d0348 |
\fB\%archive_errno\fP()
|
|
Packit Service |
1d0348 |
function can be used to retrieve a numeric error code (see
|
|
Packit Service |
1d0348 |
\fBerrno\fP(2)).
|
|
Packit Service |
1d0348 |
The
|
|
Packit Service |
1d0348 |
\fB\%archive_error_string\fP()
|
|
Packit Service |
1d0348 |
returns a textual error message suitable for display.
|
|
Packit Service |
1d0348 |
.PP
|
|
Packit Service |
1d0348 |
\fB\%archive_read_new\fP()
|
|
Packit Service |
1d0348 |
and
|
|
Packit Service |
1d0348 |
\fB\%archive_write_new\fP()
|
|
Packit Service |
1d0348 |
return pointers to an allocated and initialized
|
|
Packit Service |
1d0348 |
Tn struct archive
|
|
Packit Service |
1d0348 |
object.
|
|
Packit Service |
1d0348 |
.PP
|
|
Packit Service |
1d0348 |
\fB\%archive_read_data\fP()
|
|
Packit Service |
1d0348 |
and
|
|
Packit Service |
1d0348 |
\fB\%archive_write_data\fP()
|
|
Packit Service |
1d0348 |
return a count of the number of bytes actually read or written.
|
|
Packit Service |
1d0348 |
A value of zero indicates the end of the data for this entry.
|
|
Packit Service |
1d0348 |
A negative value indicates an error, in which case the
|
|
Packit Service |
1d0348 |
\fB\%archive_errno\fP()
|
|
Packit Service |
1d0348 |
and
|
|
Packit Service |
1d0348 |
\fB\%archive_error_string\fP()
|
|
Packit Service |
1d0348 |
functions can be used to obtain more information.
|
|
Packit Service |
1d0348 |
.SH ENVIRONMENT
|
|
Packit Service |
1d0348 |
.ad l
|
|
Packit Service |
1d0348 |
There are character set conversions within the
|
|
Packit Service |
1d0348 |
\fBarchive_entry\fP(3)
|
|
Packit Service |
1d0348 |
functions that are impacted by the currently-selected locale.
|
|
Packit Service |
1d0348 |
.SH SEE ALSO
|
|
Packit Service |
1d0348 |
.ad l
|
|
Packit Service |
1d0348 |
\fBtar\fP(1),
|
|
Packit Service |
1d0348 |
\fBarchive_entry\fP(3),
|
|
Packit Service |
1d0348 |
\fBarchive_read\fP(3),
|
|
Packit Service |
1d0348 |
\fBarchive_util\fP(3),
|
|
Packit Service |
1d0348 |
\fBarchive_write\fP(3),
|
|
Packit Service |
1d0348 |
\fBtar\fP(5)
|
|
Packit Service |
1d0348 |
.SH HISTORY
|
|
Packit Service |
1d0348 |
.ad l
|
|
Packit Service |
1d0348 |
The
|
|
Packit Service |
1d0348 |
\fB\%libarchive\fP
|
|
Packit Service |
1d0348 |
library first appeared in
|
|
Packit Service |
1d0348 |
FreeBSD 5.3.
|
|
Packit Service |
1d0348 |
.SH AUTHORS
|
|
Packit Service |
1d0348 |
.ad l
|
|
Packit Service |
1d0348 |
-nosplit
|
|
Packit Service |
1d0348 |
The
|
|
Packit Service |
1d0348 |
\fB\%libarchive\fP
|
|
Packit Service |
1d0348 |
library was originally written by
|
|
Packit Service |
1d0348 |
Tim Kientzle \%<kientzle@acm.org.>
|
|
Packit Service |
1d0348 |
.SH BUGS
|
|
Packit Service |
1d0348 |
.ad l
|
|
Packit Service |
1d0348 |
Some archive formats support information that is not supported by
|
|
Packit Service |
1d0348 |
Tn struct archive_entry.
|
|
Packit Service |
1d0348 |
Such information cannot be fully archived or restored using this library.
|
|
Packit Service |
1d0348 |
This includes, for example, comments, character sets,
|
|
Packit Service |
1d0348 |
or the arbitrary key/value pairs that can appear in
|
|
Packit Service |
1d0348 |
pax interchange format archives.
|
|
Packit Service |
1d0348 |
.PP
|
|
Packit Service |
1d0348 |
Conversely, of course, not all of the information that can be
|
|
Packit Service |
1d0348 |
stored in an
|
|
Packit Service |
1d0348 |
Tn struct archive_entry
|
|
Packit Service |
1d0348 |
is supported by all formats.
|
|
Packit Service |
1d0348 |
For example, cpio formats do not support nanosecond timestamps;
|
|
Packit Service |
1d0348 |
old tar formats do not support large device numbers.
|
|
Packit Service |
1d0348 |
.PP
|
|
Packit Service |
1d0348 |
The ISO9660 reader cannot yet read all ISO9660 images;
|
|
Packit Service |
1d0348 |
it should learn how to seek.
|
|
Packit Service |
1d0348 |
.PP
|
|
Packit Service |
1d0348 |
The AR writer requires the client program to use
|
|
Packit Service |
1d0348 |
two passes, unlike all other libarchive writers.
|