|
Packit Service |
1d0348 |
ARCHIVE_READ(3) manual page
|
|
Packit Service |
1d0348 |
== NAME ==
|
|
Packit Service |
1d0348 |
'''archive_read'''
|
|
Packit Service |
1d0348 |
- functions for reading streaming archives
|
|
Packit Service |
1d0348 |
== LIBRARY ==
|
|
Packit Service |
1d0348 |
Streaming Archive Library (libarchive, -larchive)
|
|
Packit Service |
1d0348 |
== SYNOPSIS ==
|
|
Packit Service |
1d0348 |
'''<nowiki>#include <archive.h></nowiki>'''
|
|
Packit Service |
1d0348 |
== DESCRIPTION ==
|
|
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 |
'''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 |
=== Create archive object===
|
|
Packit Service |
1d0348 |
See
|
|
Packit Service |
1d0348 |
[[ManPagerchiveeadew3]].
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
To read an archive, you must first obtain an initialized
|
|
Packit Service |
1d0348 |
'''struct archive'''
|
|
Packit Service |
1d0348 |
object from
|
|
Packit Service |
1d0348 |
'''archive_read_new'''().
|
|
Packit Service |
1d0348 |
=== Enable filters and formats===
|
|
Packit Service |
1d0348 |
See
|
|
Packit Service |
1d0348 |
[[ManPagerchiveeadilter3]]
|
|
Packit Service |
1d0348 |
and
|
|
Packit Service |
1d0348 |
[[ManPagerchiveeadormat3]].
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
You can then modify this object for the desired operations with the
|
|
Packit Service |
1d0348 |
various
|
|
Packit Service |
1d0348 |
'''archive_read_set_XXX'''()
|
|
Packit Service |
1d0348 |
and
|
|
Packit Service |
1d0348 |
'''archive_read_support_XXX'''()
|
|
Packit Service |
1d0348 |
functions.
|
|
Packit Service |
1d0348 |
In particular, you will need to invoke appropriate
|
|
Packit Service |
1d0348 |
'''archive_read_support_XXX'''()
|
|
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 |
'''archive_read_support_filter_all'''()
|
|
Packit Service |
1d0348 |
and
|
|
Packit Service |
1d0348 |
'''archive_read_support_format_all'''()
|
|
Packit Service |
1d0348 |
to enable auto-detect for all formats and compression types
|
|
Packit Service |
1d0348 |
currently supported by the library.
|
|
Packit Service |
1d0348 |
=== Set options===
|
|
Packit Service |
1d0348 |
See
|
|
Packit Service |
1d0348 |
[[ManPagerchiveeadetptions3]].
|
|
Packit Service |
1d0348 |
=== Open archive===
|
|
Packit Service |
1d0348 |
See
|
|
Packit Service |
1d0348 |
[[ManPagerchiveeadpen3]].
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
Once you have prepared the
|
|
Packit Service |
1d0348 |
'''struct archive'''
|
|
Packit Service |
1d0348 |
object, you call
|
|
Packit Service |
1d0348 |
'''archive_read_open'''()
|
|
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 |
''FILE *''
|
|
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 |
=== Consume archive===
|
|
Packit Service |
1d0348 |
See
|
|
Packit Service |
1d0348 |
[[ManPagerchiveeadeader3]],
|
|
Packit Service |
1d0348 |
[[ManPagerchiveeadata3]]
|
|
Packit Service |
1d0348 |
and
|
|
Packit Service |
1d0348 |
[[ManPagerchiveeadxtract3]].
|
|
Packit Service |
1d0348 |
|
|
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 |
'''archive_read_next_header'''(),
|
|
Packit Service |
1d0348 |
which returns a pointer to an
|
|
Packit Service |
1d0348 |
'''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 |
'''archive_read_data'''()
|
|
Packit Service |
1d0348 |
(which works much like the
|
|
Packit Service |
1d0348 |
[[read(2)|http://www.freebsd.org/cgi/man.cgi?query=read&sektion=2]]
|
|
Packit Service |
1d0348 |
system call)
|
|
Packit Service |
1d0348 |
to read this data from the archive, or
|
|
Packit Service |
1d0348 |
'''archive_read_data_block'''()
|
|
Packit Service |
1d0348 |
which provides a slightly more efficient interface.
|
|
Packit Service |
1d0348 |
You may prefer to use the higher-level
|
|
Packit Service |
1d0348 |
'''archive_read_data_skip'''(),
|
|
Packit Service |
1d0348 |
which reads and discards the data for this entry,
|
|
Packit Service |
1d0348 |
'''archive_read_data_into_fd'''(),
|
|
Packit Service |
1d0348 |
which copies the data to the provided file descriptor, or
|
|
Packit Service |
1d0348 |
'''archive_read_extract'''(),
|
|
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 |
'''archive_read_extract'''()
|
|
Packit Service |
1d0348 |
uses the
|
|
Packit Service |
1d0348 |
'''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 |
=== Release resources===
|
|
Packit Service |
1d0348 |
See
|
|
Packit Service |
1d0348 |
[[ManPagerchiveeadree3]].
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
Once you have finished reading data from the archive, you
|
|
Packit Service |
1d0348 |
should call
|
|
Packit Service |
1d0348 |
'''archive_read_close'''()
|
|
Packit Service |
1d0348 |
to close the archive, then call
|
|
Packit Service |
1d0348 |
'''archive_read_free'''()
|
|
Packit Service |
1d0348 |
to release all resources, including all memory allocated by the library.
|
|
Packit Service |
1d0348 |
== EXAMPLE ==
|
|
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 |
[[open(2)|http://www.freebsd.org/cgi/man.cgi?query=open&sektion=2]],
|
|
Packit Service |
1d0348 |
[[read(2)|http://www.freebsd.org/cgi/man.cgi?query=read&sektion=2]],
|
|
Packit Service |
1d0348 |
and
|
|
Packit Service |
1d0348 |
[[close(2)|http://www.freebsd.org/cgi/man.cgi?query=close&sektion=2]]
|
|
Packit Service |
1d0348 |
system calls.
|
|
Packit Service |
1d0348 |
```text
|
|
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 |
```
|
|
Packit Service |
1d0348 |
== SEE ALSO ==
|
|
Packit Service |
1d0348 |
[[ManPageBsdtar1]],
|
|
Packit Service |
1d0348 |
[[ManPageibarchive3]],
|
|
Packit Service |
1d0348 |
[[ManPagerchiveeadew3]],
|
|
Packit Service |
1d0348 |
[[ManPagerchiveeadata3]],
|
|
Packit Service |
1d0348 |
[[ManPagerchiveeadxtract3]],
|
|
Packit Service |
1d0348 |
[[ManPagerchiveeadilter3]],
|
|
Packit Service |
1d0348 |
[[ManPagerchiveeadormat3]],
|
|
Packit Service |
1d0348 |
[[ManPagerchiveeadeader3]],
|
|
Packit Service |
1d0348 |
[[ManPagerchiveeadpen3]],
|
|
Packit Service |
1d0348 |
[[ManPagerchiveeadetptions3]],
|
|
Packit Service |
1d0348 |
[[ManPagerchivetil3]],
|
|
Packit Service |
1d0348 |
[[ManPageTar5]]
|
|
Packit Service |
1d0348 |
== HISTORY ==
|
|
Packit Service |
1d0348 |
The
|
|
Packit Service |
1d0348 |
'''libarchive'''
|
|
Packit Service |
1d0348 |
library first appeared in
|
|
Packit Service |
1d0348 |
FreeBSD 5.3.
|
|
Packit Service |
1d0348 |
== AUTHORS ==
|
|
Packit Service |
1d0348 |
The
|
|
Packit Service |
1d0348 |
'''libarchive'''
|
|
Packit Service |
1d0348 |
library was written by
|
|
Packit Service |
1d0348 |
Tim Kientzle <kientzle@acm.org.>
|
|
Packit Service |
1d0348 |
== BUGS ==
|
|
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 |
[[ManPageBsdtar1]]
|
|
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.
|