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