|
Packit Service |
1d0348 |
.TH ARCHIVE_READ 3 "February 2, 2012" ""
|
|
Packit Service |
1d0348 |
.SH NAME
|
|
Packit Service |
1d0348 |
.ad l
|
|
Packit Service |
1d0348 |
\fB\%archive_read\fP
|
|
Packit Service |
1d0348 |
\- functions for reading streaming archives
|
|
Packit Service |
1d0348 |
.SH LIBRARY
|
|
Packit Service |
1d0348 |
.ad l
|
|
Packit Service |
1d0348 |
Streaming Archive Library (libarchive, -larchive)
|
|
Packit Service |
1d0348 |
.SH SYNOPSIS
|
|
Packit Service |
1d0348 |
.ad l
|
|
Packit Service |
1d0348 |
\fB#include <archive.h>\fP
|
|
Packit Service |
1d0348 |
.SH DESCRIPTION
|
|
Packit Service |
1d0348 |
.ad l
|
|
Packit Service |
1d0348 |
These functions provide a complete API for reading streaming archives.
|
|
Packit Service |
1d0348 |
The general process is to first create the
|
|
Packit Service |
1d0348 |
Tn struct archive
|
|
Packit Service |
1d0348 |
object, set options, initialize the reader, iterate over the archive
|
|
Packit Service |
1d0348 |
headers and associated data, then close the archive and release all
|
|
Packit Service |
1d0348 |
resources.
|
|
Packit Service |
1d0348 |
.SS Create archive object
|
|
Packit Service |
1d0348 |
See
|
|
Packit Service |
1d0348 |
\fBarchive_read_new\fP(3).
|
|
Packit Service |
1d0348 |
.PP
|
|
Packit Service |
1d0348 |
To read an archive, you must first obtain an initialized
|
|
Packit Service |
1d0348 |
Tn struct archive
|
|
Packit Service |
1d0348 |
object from
|
|
Packit Service |
1d0348 |
\fB\%archive_read_new\fP().
|
|
Packit Service |
1d0348 |
.SS Enable filters and formats
|
|
Packit Service |
1d0348 |
See
|
|
Packit Service |
1d0348 |
\fBarchive_read_filter\fP(3)
|
|
Packit Service |
1d0348 |
and
|
|
Packit Service |
1d0348 |
\fBarchive_read_format\fP(3).
|
|
Packit Service |
1d0348 |
.PP
|
|
Packit Service |
1d0348 |
You can then modify this object for the desired operations with the
|
|
Packit Service |
1d0348 |
various
|
|
Packit Service |
1d0348 |
\fB\%archive_read_set_XXX\fP()
|
|
Packit Service |
1d0348 |
and
|
|
Packit Service |
1d0348 |
\fB\%archive_read_support_XXX\fP()
|
|
Packit Service |
1d0348 |
functions.
|
|
Packit Service |
1d0348 |
In particular, you will need to invoke appropriate
|
|
Packit Service |
1d0348 |
\fB\%archive_read_support_XXX\fP()
|
|
Packit Service |
1d0348 |
functions to enable the corresponding compression and format
|
|
Packit Service |
1d0348 |
support.
|
|
Packit Service |
1d0348 |
Note that these latter functions perform two distinct operations:
|
|
Packit Service |
1d0348 |
they cause the corresponding support code to be linked into your
|
|
Packit Service |
1d0348 |
program, and they enable the corresponding auto-detect code.
|
|
Packit Service |
1d0348 |
Unless you have specific constraints, you will generally want
|
|
Packit Service |
1d0348 |
to invoke
|
|
Packit Service |
1d0348 |
\fB\%archive_read_support_filter_all\fP()
|
|
Packit Service |
1d0348 |
and
|
|
Packit Service |
1d0348 |
\fB\%archive_read_support_format_all\fP()
|
|
Packit Service |
1d0348 |
to enable auto-detect for all formats and compression types
|
|
Packit Service |
1d0348 |
currently supported by the library.
|
|
Packit Service |
1d0348 |
.SS Set options
|
|
Packit Service |
1d0348 |
See
|
|
Packit Service |
1d0348 |
\fBarchive_read_set_options\fP(3).
|
|
Packit Service |
1d0348 |
.SS Open archive
|
|
Packit Service |
1d0348 |
See
|
|
Packit Service |
1d0348 |
\fBarchive_read_open\fP(3).
|
|
Packit Service |
1d0348 |
.PP
|
|
Packit Service |
1d0348 |
Once you have prepared the
|
|
Packit Service |
1d0348 |
Tn struct archive
|
|
Packit Service |
1d0348 |
object, you call
|
|
Packit Service |
1d0348 |
\fB\%archive_read_open\fP()
|
|
Packit Service |
1d0348 |
to actually open the archive and prepare it for reading.
|
|
Packit Service |
1d0348 |
There are several variants of this function;
|
|
Packit Service |
1d0348 |
the most basic expects you to provide pointers to several
|
|
Packit Service |
1d0348 |
functions that can provide blocks of bytes from the archive.
|
|
Packit Service |
1d0348 |
There are convenience forms that allow you to
|
|
Packit Service |
1d0348 |
specify a filename, file descriptor,
|
|
Packit Service |
1d0348 |
\fIFILE *\fP
|
|
Packit Service |
1d0348 |
object, or a block of memory from which to read the archive data.
|
|
Packit Service |
1d0348 |
Note that the core library makes no assumptions about the
|
|
Packit Service |
1d0348 |
size of the blocks read;
|
|
Packit Service |
1d0348 |
callback functions are free to read whatever block size is
|
|
Packit Service |
1d0348 |
most appropriate for the medium.
|
|
Packit Service |
1d0348 |
.SS Consume archive
|
|
Packit Service |
1d0348 |
See
|
|
Packit Service |
1d0348 |
\fBarchive_read_header\fP(3),
|
|
Packit Service |
1d0348 |
\fBarchive_read_data\fP(3)
|
|
Packit Service |
1d0348 |
and
|
|
Packit Service |
1d0348 |
\fBarchive_read_extract\fP(3).
|
|
Packit Service |
1d0348 |
.PP
|
|
Packit Service |
1d0348 |
Each archive entry consists of a header followed by a certain
|
|
Packit Service |
1d0348 |
amount of data.
|
|
Packit Service |
1d0348 |
You can obtain the next header with
|
|
Packit Service |
1d0348 |
\fB\%archive_read_next_header\fP(),
|
|
Packit Service |
1d0348 |
which returns a pointer to an
|
|
Packit Service |
1d0348 |
Tn struct archive_entry
|
|
Packit Service |
1d0348 |
structure with information about the current archive element.
|
|
Packit Service |
1d0348 |
If the entry is a regular file, then the header will be followed
|
|
Packit Service |
1d0348 |
by the file data.
|
|
Packit Service |
1d0348 |
You can use
|
|
Packit Service |
1d0348 |
\fB\%archive_read_data\fP()
|
|
Packit Service |
1d0348 |
(which works much like the
|
|
Packit Service |
1d0348 |
\fBread\fP(2)
|
|
Packit Service |
1d0348 |
system call)
|
|
Packit Service |
1d0348 |
to read this data from the archive, or
|
|
Packit Service |
1d0348 |
\fB\%archive_read_data_block\fP()
|
|
Packit Service |
1d0348 |
which provides a slightly more efficient interface.
|
|
Packit Service |
1d0348 |
You may prefer to use the higher-level
|
|
Packit Service |
1d0348 |
\fB\%archive_read_data_skip\fP(),
|
|
Packit Service |
1d0348 |
which reads and discards the data for this entry,
|
|
Packit Service |
1d0348 |
\fB\%archive_read_data_into_fd\fP(),
|
|
Packit Service |
1d0348 |
which copies the data to the provided file descriptor, or
|
|
Packit Service |
1d0348 |
\fB\%archive_read_extract\fP(),
|
|
Packit Service |
1d0348 |
which recreates the specified entry on disk and copies data
|
|
Packit Service |
1d0348 |
from the archive.
|
|
Packit Service |
1d0348 |
In particular, note that
|
|
Packit Service |
1d0348 |
\fB\%archive_read_extract\fP()
|
|
Packit Service |
1d0348 |
uses the
|
|
Packit Service |
1d0348 |
Tn struct archive_entry
|
|
Packit Service |
1d0348 |
structure that you provide it, which may differ from the
|
|
Packit Service |
1d0348 |
entry just read from the archive.
|
|
Packit Service |
1d0348 |
In particular, many applications will want to override the
|
|
Packit Service |
1d0348 |
pathname, file permissions, or ownership.
|
|
Packit Service |
1d0348 |
.SS Release resources
|
|
Packit Service |
1d0348 |
See
|
|
Packit Service |
1d0348 |
\fBarchive_read_free\fP(3).
|
|
Packit Service |
1d0348 |
.PP
|
|
Packit Service |
1d0348 |
Once you have finished reading data from the archive, you
|
|
Packit Service |
1d0348 |
should call
|
|
Packit Service |
1d0348 |
\fB\%archive_read_close\fP()
|
|
Packit Service |
1d0348 |
to close the archive, then call
|
|
Packit Service |
1d0348 |
\fB\%archive_read_free\fP()
|
|
Packit Service |
1d0348 |
to release all resources, including all memory allocated by the library.
|
|
Packit Service |
1d0348 |
.SH EXAMPLE
|
|
Packit Service |
1d0348 |
.ad l
|
|
Packit Service |
1d0348 |
The following illustrates basic usage of the library.
|
|
Packit Service |
1d0348 |
In this example,
|
|
Packit Service |
1d0348 |
the callback functions are simply wrappers around the standard
|
|
Packit Service |
1d0348 |
\fBopen\fP(2),
|
|
Packit Service |
1d0348 |
\fBread\fP(2),
|
|
Packit Service |
1d0348 |
and
|
|
Packit Service |
1d0348 |
\fBclose\fP(2)
|
|
Packit Service |
1d0348 |
system calls.
|
|
Packit Service |
1d0348 |
.RS 4
|
|
Packit Service |
1d0348 |
.nf
|
|
Packit Service |
1d0348 |
void
|
|
Packit Service |
1d0348 |
list_archive(const char *name)
|
|
Packit Service |
1d0348 |
{
|
|
Packit Service |
1d0348 |
struct mydata *mydata;
|
|
Packit Service |
1d0348 |
struct archive *a;
|
|
Packit Service |
1d0348 |
struct archive_entry *entry;
|
|
Packit Service |
1d0348 |
mydata = malloc(sizeof(struct mydata));
|
|
Packit Service |
1d0348 |
a = archive_read_new();
|
|
Packit Service |
1d0348 |
mydata->name = name;
|
|
Packit Service |
1d0348 |
archive_read_support_filter_all(a);
|
|
Packit Service |
1d0348 |
archive_read_support_format_all(a);
|
|
Packit Service |
1d0348 |
archive_read_open(a, mydata, myopen, myread, myclose);
|
|
Packit Service |
1d0348 |
while (archive_read_next_header(a, &entry) == ARCHIVE_OK) {
|
|
Packit Service |
1d0348 |
printf("%s\en",archive_entry_pathname(entry));
|
|
Packit Service |
1d0348 |
archive_read_data_skip(a);
|
|
Packit Service |
1d0348 |
}
|
|
Packit Service |
1d0348 |
archive_read_free(a);
|
|
Packit Service |
1d0348 |
free(mydata);
|
|
Packit Service |
1d0348 |
}
|
|
Packit Service |
1d0348 |
la_ssize_t
|
|
Packit Service |
1d0348 |
myread(struct archive *a, void *client_data, const void **buff)
|
|
Packit Service |
1d0348 |
{
|
|
Packit Service |
1d0348 |
struct mydata *mydata = client_data;
|
|
Packit Service |
1d0348 |
*buff = mydata->buff;
|
|
Packit Service |
1d0348 |
return (read(mydata->fd, mydata->buff, 10240));
|
|
Packit Service |
1d0348 |
}
|
|
Packit Service |
1d0348 |
int
|
|
Packit Service |
1d0348 |
myopen(struct archive *a, void *client_data)
|
|
Packit Service |
1d0348 |
{
|
|
Packit Service |
1d0348 |
struct mydata *mydata = client_data;
|
|
Packit Service |
1d0348 |
mydata->fd = open(mydata->name, O_RDONLY);
|
|
Packit Service |
1d0348 |
return (mydata->fd >= 0 ? ARCHIVE_OK : ARCHIVE_FATAL);
|
|
Packit Service |
1d0348 |
}
|
|
Packit Service |
1d0348 |
int
|
|
Packit Service |
1d0348 |
myclose(struct archive *a, void *client_data)
|
|
Packit Service |
1d0348 |
{
|
|
Packit Service |
1d0348 |
struct mydata *mydata = client_data;
|
|
Packit Service |
1d0348 |
if (mydata->fd > 0)
|
|
Packit Service |
1d0348 |
close(mydata->fd);
|
|
Packit Service |
1d0348 |
return (ARCHIVE_OK);
|
|
Packit Service |
1d0348 |
}
|
|
Packit Service |
1d0348 |
.RE
|
|
Packit Service |
1d0348 |
.SH SEE ALSO
|
|
Packit Service |
1d0348 |
.ad l
|
|
Packit Service |
1d0348 |
\fBtar\fP(1),
|
|
Packit Service |
1d0348 |
\fBlibarchive\fP(3),
|
|
Packit Service |
1d0348 |
\fBarchive_read_new\fP(3),
|
|
Packit Service |
1d0348 |
\fBarchive_read_data\fP(3),
|
|
Packit Service |
1d0348 |
\fBarchive_read_extract\fP(3),
|
|
Packit Service |
1d0348 |
\fBarchive_read_filter\fP(3),
|
|
Packit Service |
1d0348 |
\fBarchive_read_format\fP(3),
|
|
Packit Service |
1d0348 |
\fBarchive_read_header\fP(3),
|
|
Packit Service |
1d0348 |
\fBarchive_read_open\fP(3),
|
|
Packit Service |
1d0348 |
\fBarchive_read_set_options\fP(3),
|
|
Packit Service |
1d0348 |
\fBarchive_util\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 written by
|
|
Packit Service |
1d0348 |
Tim Kientzle \%<kientzle@acm.org.>
|
|
Packit Service |
1d0348 |
.SH BUGS
|
|
Packit Service |
1d0348 |
.ad l
|
|
Packit Service |
1d0348 |
Many traditional archiver programs treat
|
|
Packit Service |
1d0348 |
empty files as valid empty archives.
|
|
Packit Service |
1d0348 |
For example, many implementations of
|
|
Packit Service |
1d0348 |
\fBtar\fP(1)
|
|
Packit Service |
1d0348 |
allow you to append entries to an empty file.
|
|
Packit Service |
1d0348 |
Of course, it is impossible to determine the format of an empty file
|
|
Packit Service |
1d0348 |
by inspecting the contents, so this library treats empty files as
|
|
Packit Service |
1d0348 |
having a special
|
|
Packit Service |
1d0348 |
``empty''
|
|
Packit Service |
1d0348 |
format.
|