|
Packit |
08bd4c |
LIBARCHIVE(3) BSD Library Functions Manual LIBARCHIVE(3)
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
NAME
|
|
Packit |
08bd4c |
libarchive — functions for reading and writing streaming archives
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
OVERVIEW
|
|
Packit |
08bd4c |
The libarchive library provides a flexible interface for reading and
|
|
Packit |
08bd4c |
writing archives in various formats such as tar and cpio. libarchive
|
|
Packit |
08bd4c |
also supports reading and writing archives compressed using various com‐
|
|
Packit |
08bd4c |
pression filters such as gzip and bzip2. The library is inherently
|
|
Packit |
08bd4c |
stream-oriented; readers serially iterate through the archive, writers
|
|
Packit |
08bd4c |
serially add things to the archive. In particular, note that there is
|
|
Packit |
08bd4c |
currently no built-in support for random access nor for in-place modifi‐
|
|
Packit |
08bd4c |
cation.
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
When reading an archive, the library automatically detects the format and
|
|
Packit |
08bd4c |
the compression. The library currently has read support for:
|
|
Packit |
08bd4c |
· old-style tar archives,
|
|
Packit |
08bd4c |
· most variants of the POSIX “ustar” format,
|
|
Packit |
08bd4c |
· the POSIX “pax interchange” format,
|
|
Packit |
08bd4c |
· GNU-format tar archives,
|
|
Packit |
08bd4c |
· most common cpio archive formats,
|
|
Packit |
08bd4c |
· ISO9660 CD images (including RockRidge and Joliet extensions),
|
|
Packit |
08bd4c |
· Zip archives,
|
|
Packit |
08bd4c |
· ar archives (including GNU/SysV and BSD extensions),
|
|
Packit |
08bd4c |
· Microsoft CAB archives,
|
|
Packit |
08bd4c |
· LHA archives,
|
|
Packit |
08bd4c |
· mtree file tree descriptions,
|
|
Packit |
08bd4c |
· RAR archives,
|
|
Packit |
08bd4c |
· XAR archives.
|
|
Packit |
08bd4c |
The library automatically detects archives compressed with gzip(1),
|
|
Packit |
08bd4c |
bzip2(1), xz(1), lzip(1), or compress(1) and decompresses them transpar‐
|
|
Packit |
08bd4c |
ently. It can similarly detect and decode archives processed with
|
|
Packit |
08bd4c |
uuencode(1) or which have an rpm(1) header.
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
When writing an archive, you can specify the compression to be used and
|
|
Packit |
08bd4c |
the format to use. The library can write
|
|
Packit |
08bd4c |
· POSIX-standard “ustar” archives,
|
|
Packit |
08bd4c |
· POSIX “pax interchange format” archives,
|
|
Packit |
08bd4c |
· POSIX octet-oriented cpio archives,
|
|
Packit |
08bd4c |
· Zip archive,
|
|
Packit |
08bd4c |
· two different variants of shar archives,
|
|
Packit |
08bd4c |
· ISO9660 CD images,
|
|
Packit |
08bd4c |
· 7-Zip archives,
|
|
Packit |
08bd4c |
· ar archives,
|
|
Packit |
08bd4c |
· mtree file tree descriptions,
|
|
Packit |
08bd4c |
· XAR archives.
|
|
Packit |
08bd4c |
Pax interchange format is an extension of the tar archive format that
|
|
Packit |
08bd4c |
eliminates essentially all of the limitations of historic tar formats in
|
|
Packit |
08bd4c |
a standard fashion that is supported by POSIX-compliant pax(1) implemen‐
|
|
Packit |
08bd4c |
tations on many systems as well as several newer implementations of
|
|
Packit |
08bd4c |
tar(1). Note that the default write format will suppress the pax
|
|
Packit |
08bd4c |
extended attributes for most entries; explicitly requesting pax format
|
|
Packit |
08bd4c |
will enable those attributes for all entries.
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
The read and write APIs are accessed through the archive_read_XXX() func‐
|
|
Packit |
08bd4c |
tions and the archive_write_XXX() functions, respectively, and either can
|
|
Packit |
08bd4c |
be used independently of the other.
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
The rest of this manual page provides an overview of the library opera‐
|
|
Packit |
08bd4c |
tion. More detailed information can be found in the individual manual
|
|
Packit |
08bd4c |
pages for each API or utility function.
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
READING AN ARCHIVE
|
|
Packit |
08bd4c |
See archive_read(3).
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
WRITING AN ARCHIVE
|
|
Packit |
08bd4c |
See archive_write(3).
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
WRITING ENTRIES TO DISK
|
|
Packit |
08bd4c |
The archive_write_disk(3) API allows you to write archive_entry(3)
|
|
Packit |
08bd4c |
objects to disk using the same API used by archive_write(3). The
|
|
Packit |
08bd4c |
archive_write_disk(3) API is used internally by archive_read_extract();
|
|
Packit |
08bd4c |
using it directly can provide greater control over how entries get writ‐
|
|
Packit |
08bd4c |
ten to disk. This API also makes it possible to share code between ar‐
|
|
Packit |
08bd4c |
chive-to-archive copy and archive-to-disk extraction operations.
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
READING ENTRIES FROM DISK
|
|
Packit |
08bd4c |
The archive_read_disk(3) supports for populating archive_entry(3) objects
|
|
Packit |
08bd4c |
from information in the filesystem. This includes the information acces‐
|
|
Packit |
08bd4c |
sible from the stat(2) system call as well as ACLs, extended attributes,
|
|
Packit |
08bd4c |
and other metadata. The archive_read_disk(3) API also supports iterating
|
|
Packit |
08bd4c |
over directory trees, which allows directories of files to be read using
|
|
Packit |
08bd4c |
an API compatible with the archive_read(3) API.
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
DESCRIPTION
|
|
Packit |
08bd4c |
Detailed descriptions of each function are provided by the corresponding
|
|
Packit |
08bd4c |
manual pages.
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
All of the functions utilize an opaque struct archive datatype that pro‐
|
|
Packit |
08bd4c |
vides access to the archive contents.
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
The struct archive_entry structure contains a complete description of a
|
|
Packit |
08bd4c |
single archive entry. It uses an opaque interface that is fully docu‐
|
|
Packit |
08bd4c |
mented in archive_entry(3).
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
Users familiar with historic formats should be aware that the newer vari‐
|
|
Packit |
08bd4c |
ants have eliminated most restrictions on the length of textual fields.
|
|
Packit |
08bd4c |
Clients should not assume that filenames, link names, user names, or
|
|
Packit |
08bd4c |
group names are limited in length. In particular, pax interchange format
|
|
Packit |
08bd4c |
can easily accommodate pathnames in arbitrary character sets that exceed
|
|
Packit |
08bd4c |
PATH_MAX.
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
RETURN VALUES
|
|
Packit |
08bd4c |
Most functions return ARCHIVE_OK (zero) on success, non-zero on error.
|
|
Packit |
08bd4c |
The return value indicates the general severity of the error, ranging
|
|
Packit |
08bd4c |
from ARCHIVE_WARN, which indicates a minor problem that should probably
|
|
Packit |
08bd4c |
be reported to the user, to ARCHIVE_FATAL, which indicates a serious
|
|
Packit |
08bd4c |
problem that will prevent any further operations on this archive. On
|
|
Packit |
08bd4c |
error, the archive_errno() function can be used to retrieve a numeric
|
|
Packit |
08bd4c |
error code (see errno(2)). The archive_error_string() returns a textual
|
|
Packit |
08bd4c |
error message suitable for display.
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
archive_read_new() and archive_write_new() return pointers to an allo‐
|
|
Packit |
08bd4c |
cated and initialized struct archive object.
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
archive_read_data() and archive_write_data() return a count of the number
|
|
Packit |
08bd4c |
of bytes actually read or written. A value of zero indicates the end of
|
|
Packit |
08bd4c |
the data for this entry. A negative value indicates an error, in which
|
|
Packit |
08bd4c |
case the archive_errno() and archive_error_string() functions can be used
|
|
Packit |
08bd4c |
to obtain more information.
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
ENVIRONMENT
|
|
Packit |
08bd4c |
There are character set conversions within the archive_entry(3) functions
|
|
Packit |
08bd4c |
that are impacted by the currently-selected locale.
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
SEE ALSO
|
|
Packit |
08bd4c |
tar(1), archive_entry(3), archive_read(3), archive_util(3),
|
|
Packit |
08bd4c |
archive_write(3), tar(5)
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
HISTORY
|
|
Packit |
08bd4c |
The libarchive library first appeared in FreeBSD 5.3.
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
AUTHORS
|
|
Packit |
08bd4c |
The libarchive library was originally written by Tim Kientzle
|
|
Packit |
08bd4c |
<kientzle@acm.org>.
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
BUGS
|
|
Packit |
08bd4c |
Some archive formats support information that is not supported by struct
|
|
Packit |
08bd4c |
archive_entry. Such information cannot be fully archived or restored
|
|
Packit |
08bd4c |
using this library. This includes, for example, comments, character
|
|
Packit |
08bd4c |
sets, or the arbitrary key/value pairs that can appear in pax interchange
|
|
Packit |
08bd4c |
format archives.
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
Conversely, of course, not all of the information that can be stored in
|
|
Packit |
08bd4c |
an struct archive_entry is supported by all formats. For example, cpio
|
|
Packit |
08bd4c |
formats do not support nanosecond timestamps; old tar formats do not sup‐
|
|
Packit |
08bd4c |
port large device numbers.
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
The ISO9660 reader cannot yet read all ISO9660 images; it should learn
|
|
Packit |
08bd4c |
how to seek.
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
The AR writer requires the client program to use two passes, unlike all
|
|
Packit |
08bd4c |
other libarchive writers.
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
BSD March 18, 2012 BSD
|