source-git / libarchive

Clone
Source Code
GIT

Blame doc/html/archive_read.3.html

c8 c8s master
  1.   cc8190ec3d70c1de180e29fbbd40106e3d7cc46b
  2.   doc
  3.   html
  4.   archive_read.3.html
Blob History Raw
Packit Service 1d0348
Packit Service 1d0348
Packit Service 1d0348
Packit Service 1d0348 
"http://www.w3.org/TR/html4/loose.dtd">
Packit Service 1d0348 
<html>
Packit Service 1d0348 
<head>
Packit Service 1d0348 
<meta name="generator" content="groff -Thtml, see www.gnu.org">
Packit Service 1d0348 
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
Packit Service 1d0348 
<meta name="Content-Style" content="text/css">
Packit Service 1d0348 
<style type="text/css">
Packit Service 1d0348 
       p       { margin-top: 0; margin-bottom: 0; vertical-align: top }
Packit Service 1d0348 
       pre     { margin-top: 0; margin-bottom: 0; vertical-align: top }
Packit Service 1d0348 
       table   { margin-top: 0; margin-bottom: 0; vertical-align: top }
Packit Service 1d0348 
       h1      { text-align: center }
Packit Service 1d0348 
</style>
Packit Service 1d0348 
<title></title>
Packit Service 1d0348 
</head>
Packit Service 1d0348 
<body>
Packit Service 1d0348
Packit Service 1d0348
Packit Service 1d0348
Packit Service 1d0348
Packit Service 1d0348 
ARCHIVE_READ(3) BSD Library Functions Manual
Packit Service 1d0348 
ARCHIVE_READ(3)
Packit Service 1d0348
Packit Service 1d0348 
NAME
Packit Service 1d0348
Packit Service 1d0348 
archive_read —
Packit Service 1d0348 
functions for reading streaming archives
Packit Service 1d0348
Packit Service 1d0348 
LIBRARY
Packit Service 1d0348
Packit Service 1d0348 
Streaming Archive Library
Packit Service 1d0348 
(libarchive, -larchive)
Packit Service 1d0348
Packit Service 1d0348 
SYNOPSIS
Packit Service 1d0348
Packit Service 1d0348 
#include
Packit Service 1d0348 
<archive.h>
Packit Service 1d0348
Packit Service 1d0348 
DESCRIPTION
Packit Service 1d0348
Packit Service 1d0348 
These functions provide a
Packit Service 1d0348 
complete API for reading streaming archives. The general
Packit Service 1d0348 
process is to first create the struct archive object, set
Packit Service 1d0348 
options, initialize the reader, iterate over the archive
Packit Service 1d0348 
headers and associated data, then close the archive and
Packit Service 1d0348 
release all resources.
Packit Service 1d0348
Packit Service 1d0348 
Create
Packit Service 1d0348 
archive object
Packit Service 1d0348 
See archive_read_new(3).
Packit Service 1d0348
Packit Service 1d0348 
To read an
Packit Service 1d0348 
archive, you must first obtain an initialized struct archive
Packit Service 1d0348 
object from archive_read_new().
Packit Service 1d0348
Packit Service 1d0348 
Enable
Packit Service 1d0348 
filters and formats
Packit Service 1d0348 
See archive_read_filter(3) and archive_read_format(3).
Packit Service 1d0348
Packit Service 1d0348 
You can then
Packit Service 1d0348 
modify this object for the desired operations with the
Packit Service 1d0348 
various archive_read_set_XXX() and
Packit Service 1d0348 
archive_read_support_XXX() functions. In particular,
Packit Service 1d0348 
you will need to invoke appropriate
Packit Service 1d0348 
archive_read_support_XXX() functions to enable the
Packit Service 1d0348 
corresponding compression and format support. Note that
Packit Service 1d0348 
these latter functions perform two distinct operations: they
Packit Service 1d0348 
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
Packit Service 1d0348 
want to invoke archive_read_support_filter_all() and
Packit Service 1d0348 
archive_read_support_format_all() to enable
Packit Service 1d0348 
auto-detect for all formats and compression types currently
Packit Service 1d0348 
supported by the library.
Packit Service 1d0348
Packit Service 1d0348 
Set
Packit Service 1d0348 
options
Packit Service 1d0348 
See archive_read_set_options(3).
Packit Service 1d0348
Packit Service 1d0348 
Open
Packit Service 1d0348 
archive
Packit Service 1d0348 
See archive_read_open(3).
Packit Service 1d0348
Packit Service 1d0348 
Once you have
Packit Service 1d0348 
prepared the struct archive object, you call
Packit Service 1d0348 
archive_read_open() to actually open the archive and
Packit Service 1d0348 
prepare it for reading. There are several variants of this
Packit Service 1d0348 
function; the most basic expects you to provide pointers to
Packit Service 1d0348 
several functions that can provide blocks of bytes from the
Packit Service 1d0348 
archive. There are convenience forms that allow you to
Packit Service 1d0348 
specify a filename, file descriptor, FILE * object,
Packit Service 1d0348 
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; callback functions are free to read
Packit Service 1d0348 
whatever block size is most appropriate for the medium.
Packit Service 1d0348
Packit Service 1d0348 
Consume
Packit Service 1d0348 
archive
Packit Service 1d0348 
See archive_read_header(3), archive_read_data(3) and
Packit Service 1d0348 
archive_read_extract(3).
Packit Service 1d0348
Packit Service 1d0348 
Each archive
Packit Service 1d0348 
entry consists of a header followed by a certain amount of
Packit Service 1d0348 
data. You can obtain the next header with
Packit Service 1d0348 
archive_read_next_header(), which returns a pointer
Packit Service 1d0348 
to an struct archive_entry structure with information about
Packit Service 1d0348 
the current archive element. If the entry is a regular file,
Packit Service 1d0348 
then the header will be followed by the file data. You can
Packit Service 1d0348 
use archive_read_data() (which works much like the
Packit Service 1d0348 
read(2) system call) to read this data from the archive, or
Packit Service 1d0348 
archive_read_data_block() which provides a slightly
Packit Service 1d0348 
more efficient interface. You may prefer to use the
Packit Service 1d0348 
higher-level archive_read_data_skip(), which reads
Packit Service 1d0348 
and discards the data for this entry,
Packit Service 1d0348 
archive_read_data_into_fd(), which copies the data to
Packit Service 1d0348 
the provided file descriptor, or
Packit Service 1d0348 
archive_read_extract(), which recreates the specified
Packit Service 1d0348 
entry on disk and copies data from the archive. In
Packit Service 1d0348 
particular, note that archive_read_extract() uses the
Packit Service 1d0348 
struct archive_entry structure that you provide it, which
Packit Service 1d0348 
may differ from the entry just read from the archive. In
Packit Service 1d0348 
particular, many applications will want to override the
Packit Service 1d0348 
pathname, file permissions, or ownership.
Packit Service 1d0348
Packit Service 1d0348 
Release
Packit Service 1d0348 
resources
Packit Service 1d0348 
See archive_read_free(3).
Packit Service 1d0348
Packit Service 1d0348 
Once you have
Packit Service 1d0348 
finished reading data from the archive, you should call
Packit Service 1d0348 
archive_read_close() to close the archive, then call
Packit Service 1d0348 
archive_read_free() to release all resources,
Packit Service 1d0348 
including all memory allocated by the library.
Packit Service 1d0348
Packit Service 1d0348 
EXAMPLE
Packit Service 1d0348
Packit Service 1d0348 
The following illustrates basic
Packit Service 1d0348 
usage of the library. In this example, the callback
Packit Service 1d0348 
functions are simply wrappers around the standard open(2),
Packit Service 1d0348 
read(2), and close(2) system calls.
Packit Service 1d0348
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
Packit Service 1d0348 
mydata =
Packit Service 1d0348 
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) ==
Packit Service 1d0348 
ARCHIVE_OK) {
Packit Service 1d0348 
printf("%s\n",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
Packit Service 1d0348 
la_ssize_t
Packit Service 1d0348 
myread(struct archive *a, void *client_data, const void
Packit Service 1d0348 
**buff)
Packit Service 1d0348 
{
Packit Service 1d0348 
struct mydata *mydata = client_data;
Packit Service 1d0348
Packit Service 1d0348 
*buff =
Packit Service 1d0348 
mydata->buff;
Packit Service 1d0348 
return (read(mydata->fd, mydata->buff, 10240));
Packit Service 1d0348 
}
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
Packit Service 1d0348 
mydata->fd =
Packit Service 1d0348 
open(mydata->name, O_RDONLY);
Packit Service 1d0348 
return (mydata->fd >= 0 ? ARCHIVE_OK : ARCHIVE_FATAL);
Packit Service 1d0348

Packit Service 1d0348 
}
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
Packit Service 1d0348 
if
Packit Service 1d0348 
(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
Packit Service 1d0348 
tar(1), libarchive(3),
Packit Service 1d0348 
archive_read_new(3), archive_read_data(3),
Packit Service 1d0348 
archive_read_extract(3), archive_read_filter(3),
Packit Service 1d0348 
archive_read_format(3), archive_read_header(3),
Packit Service 1d0348 
archive_read_open(3), archive_read_set_options(3),
Packit Service 1d0348 
archive_util(3), tar(5)
Packit Service 1d0348
Packit Service 1d0348 
HISTORY
Packit Service 1d0348
Packit Service 1d0348 
The libarchive library
Packit Service 1d0348 
first appeared in FreeBSD 5.3.
Packit Service 1d0348
Packit Service 1d0348 
AUTHORS
Packit Service 1d0348
Packit Service 1d0348 
The libarchive library
Packit Service 1d0348 
was written by Tim Kientzle <kientzle@acm.org>.
Packit Service 1d0348
Packit Service 1d0348 
BUGS
Packit Service 1d0348
Packit Service 1d0348 
Many traditional archiver
Packit Service 1d0348 
programs treat empty files as valid empty archives. For
Packit Service 1d0348 
example, many implementations of tar(1) allow you to append
Packit Service 1d0348 
entries to an empty file. Of course, it is impossible to
Packit Service 1d0348 
determine the format of an empty file by inspecting the
Packit Service 1d0348 
contents, so this library treats empty files as having a
Packit Service 1d0348 
special ’’empty’’ format.
Packit Service 1d0348
Packit Service 1d0348 
BSD
Packit Service 1d0348 
February 2, 2012 BSD
Packit Service 1d0348
Packit Service 1d0348 
</body>
Packit Service 1d0348 
</html>

Powered by Pagure 5.14.1

SSH Hostkey/Fingerprint | Documentation