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