329 lines
10 KiB
Groff
329 lines
10 KiB
Groff
.\" Copyright (c) 2003-2006 Tim Kientzle
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd August 19, 2006
|
|
.Dt LIBARCHIVE 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm libarchive
|
|
.Nd functions for reading and writing streaming archives
|
|
.Sh LIBRARY
|
|
.Lb libarchive
|
|
.Sh OVERVIEW
|
|
The
|
|
.Nm
|
|
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.
|
|
.Pp
|
|
When reading an archive, the library automatically detects the
|
|
format and the compression.
|
|
The library currently has read support for:
|
|
.Bl -bullet -compact
|
|
.It
|
|
old-style tar
|
|
.It
|
|
most variants of the POSIX
|
|
.Dq ustar
|
|
format,
|
|
.It
|
|
the POSIX
|
|
.Dq pax interchange
|
|
format,
|
|
.It
|
|
GNU-format tar archives,
|
|
.It
|
|
POSIX octet-oriented cpio archives.
|
|
.El
|
|
The library automatically detects archives compressed with
|
|
.Xr gzip 1 ,
|
|
.Xr bzip2 1 ,
|
|
or
|
|
.Xr compress 1
|
|
and decompresses them transparently.
|
|
.Pp
|
|
When writing an archive, you can specify the compression
|
|
to be used and the format to use.
|
|
The library can write
|
|
.Bl -bullet -compact
|
|
.It
|
|
POSIX-standard
|
|
.Dq ustar
|
|
archives,
|
|
.It
|
|
POSIX
|
|
.Dq pax interchange format
|
|
archives,
|
|
.It
|
|
POSIX octet-oriented cpio archives,
|
|
.It
|
|
two different variants of shar archives.
|
|
.El
|
|
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
|
|
.Xr pax 1
|
|
implementations on many systems as well as several newer implementations of
|
|
.Xr 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.
|
|
.Pp
|
|
The read and write APIs are accessed through the
|
|
.Fn archive_read_XXX
|
|
functions and the
|
|
.Fn archive_write_XXX
|
|
functions, respectively, and either can be used independently
|
|
of the other.
|
|
.Pp
|
|
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.
|
|
.Sh READING AN ARCHIVE
|
|
To read an archive, you must first obtain an initialized
|
|
.Tn struct archive
|
|
object from
|
|
.Fn archive_read_new .
|
|
You can then modify this object for the desired operations with the
|
|
various
|
|
.Fn archive_read_set_XXX
|
|
and
|
|
.Fn archive_read_support_XXX
|
|
functions.
|
|
In particular, you will need to invoke appropriate
|
|
.Fn 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
|
|
.Fn archive_read_support_compression_all
|
|
and
|
|
.Fn archive_read_support_format_all
|
|
to enable auto-detect for all formats and compression types
|
|
currently supported by the library.
|
|
.Pp
|
|
Once you have prepared the
|
|
.Tn struct archive
|
|
object, you call
|
|
.Fn 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,
|
|
.Ft "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.
|
|
.Pp
|
|
Each archive entry consists of a header followed by a certain
|
|
amount of data.
|
|
You can obtain the next header with
|
|
.Fn archive_read_next_header ,
|
|
which returns a pointer to an
|
|
.Tn 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
|
|
.Fn archive_read_data
|
|
(which works much like the
|
|
.Xr read 2
|
|
system call)
|
|
to read this data from the archive.
|
|
You may prefer to use the higher-level
|
|
.Fn archive_read_data_skip ,
|
|
which reads and discards the data for this entry,
|
|
.Fn archive_read_data_to_buffer ,
|
|
which reads the data into an in-memory buffer,
|
|
.Fn archive_read_data_to_file ,
|
|
which copies the data to the provided file descriptor, or
|
|
.Fn archive_read_extract ,
|
|
which recreates the specified entry on disk and copies data
|
|
from the archive.
|
|
In particular, note that
|
|
.Fn archive_read_extract
|
|
uses the
|
|
.Tn 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.
|
|
.Pp
|
|
Once you have finished reading data from the archive, you
|
|
should call
|
|
.Fn archive_read_finish
|
|
to release all resources.
|
|
In particular,
|
|
.Fn archive_read_finish
|
|
closes the archive and frees any memory that was allocated by the library.
|
|
.Pp
|
|
The
|
|
.Xr archive_read 3
|
|
manual page provides more detailed calling information for this API.
|
|
.Sh WRITING AN ARCHIVE
|
|
You use a similar process to write an archive.
|
|
The
|
|
.Fn archive_write_new
|
|
function creates an archive object useful for writing,
|
|
the various
|
|
.Fn archive_write_set_XXX
|
|
functions are used to set parameters for writing the archive, and
|
|
.Fn archive_write_open
|
|
completes the setup and opens the archive for writing.
|
|
.Pp
|
|
Individual archive entries are written in a three-step
|
|
process:
|
|
You first initialize a
|
|
.Tn struct archive_entry
|
|
structure with information about the new entry.
|
|
At a minimum, you should set the pathname of the
|
|
entry and provide a
|
|
.Va struct stat
|
|
with a valid
|
|
.Va st_mode
|
|
field, which specifies the type of object and
|
|
.Va st_size
|
|
field, which specifies the size of the data portion of the object.
|
|
The
|
|
.Fn archive_write_header
|
|
function actually writes the header data to the archive.
|
|
You can then use
|
|
.Fn archive_write_data
|
|
to write the actual data.
|
|
.Pp
|
|
After all entries have been written, use the
|
|
.Fn archive_write_finish
|
|
function to release all resources.
|
|
.Pp
|
|
The
|
|
.Xr archive_write 3
|
|
manual page provides more detailed calling information for this API.
|
|
.Sh DESCRIPTION
|
|
Detailed descriptions of each function are provided by the
|
|
corresponding manual pages.
|
|
.Pp
|
|
All of the functions utilize an opaque
|
|
.Tn struct archive
|
|
datatype that provides access to the archive contents.
|
|
.Pp
|
|
The
|
|
.Tn struct archive_entry
|
|
structure contains a complete description of a single archive
|
|
entry.
|
|
It uses an opaque interface that is fully documented in
|
|
.Xr archive_entry 3 .
|
|
.Pp
|
|
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 accomodate pathnames
|
|
in arbitrary character sets that exceed
|
|
.Va PATH_MAX .
|
|
.Sh RETURN VALUES
|
|
Most functions return zero on success, non-zero on error.
|
|
The return value indicates the general severity of the error, ranging
|
|
from
|
|
.Cm ARCHIVE_WARNING ,
|
|
which indicates a minor problem that should probably be reported
|
|
to the user, to
|
|
.Cm ARCHIVE_FATAL ,
|
|
which indicates a serious problem that will prevent any further
|
|
operations on this archive.
|
|
On error, the
|
|
.Fn archive_errno
|
|
function can be used to retrieve a numeric error code (see
|
|
.Xr errno 2 ) .
|
|
The
|
|
.Fn archive_error_string
|
|
returns a textual error message suitable for display.
|
|
.Pp
|
|
.Fn archive_read_new
|
|
and
|
|
.Fn archive_write_new
|
|
return pointers to an allocated and initialized
|
|
.Tn struct archive
|
|
object.
|
|
.Pp
|
|
.Fn archive_read_data
|
|
and
|
|
.Fn 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
|
|
.Fn archive_errno
|
|
and
|
|
.Fn archive_error_string
|
|
functions can be used to obtain more information.
|
|
.Sh ENVIRONMENT
|
|
There are character set conversions within the
|
|
.Xr archive_entry 3
|
|
functions that are impacted by the currently-selected locale.
|
|
.Sh SEE ALSO
|
|
.Xr tar 1 ,
|
|
.Xr archive_entry 3 ,
|
|
.Xr archive_read 3 ,
|
|
.Xr archive_util 3 ,
|
|
.Xr archive_write 3 ,
|
|
.Xr tar 5
|
|
.Sh HISTORY
|
|
The
|
|
.Nm libarchive
|
|
library first appeared in
|
|
.Fx 5.3 .
|
|
.Sh AUTHORS
|
|
.An -nosplit
|
|
The
|
|
.Nm libarchive
|
|
library was written by
|
|
.An Tim Kientzle Aq kientzle@acm.org .
|
|
.Sh BUGS
|
|
Some archive formats support information that is not supported by
|
|
.Tn 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.
|
|
.Pp
|
|
Conversely, of course, not all of the information that can be
|
|
stored in an
|
|
.Tn 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.
|