| 1 |
<!-- Creator : groff version 1.22.3 --> |
| 2 |
<!-- CreationDate: Sun Jun 19 19:54:06 2016 --> |
| 3 |
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" |
| 4 |
"http://www.w3.org/TR/html4/loose.dtd"> |
| 5 |
<html> |
| 6 |
<head> |
| 7 |
<meta name="generator" content="groff -Thtml, see www.gnu.org"> |
| 8 |
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> |
| 9 |
<meta name="Content-Style" content="text/css"> |
| 10 |
<style type="text/css"> |
| 11 |
p { margin-top: 0; margin-bottom: 0; vertical-align: top } |
| 12 |
pre { margin-top: 0; margin-bottom: 0; vertical-align: top } |
| 13 |
table { margin-top: 0; margin-bottom: 0; vertical-align: top } |
| 14 |
h1 { text-align: center } |
| 15 |
</style> |
| 16 |
<title></title> |
| 17 |
</head> |
| 18 |
<body> |
| 19 |
|
| 20 |
<hr> |
| 21 |
|
| 22 |
|
| 23 |
<p>ARCHIVE_READ(3) BSD Library Functions Manual |
| 24 |
ARCHIVE_READ(3)</p> |
| 25 |
|
| 26 |
<p style="margin-top: 1em"><b>NAME</b></p> |
| 27 |
|
| 28 |
<p style="margin-left:6%;"><b>archive_read</b> — |
| 29 |
functions for reading streaming archives</p> |
| 30 |
|
| 31 |
<p style="margin-top: 1em"><b>LIBRARY</b></p> |
| 32 |
|
| 33 |
<p style="margin-left:6%;">Streaming Archive Library |
| 34 |
(libarchive, -larchive)</p> |
| 35 |
|
| 36 |
<p style="margin-top: 1em"><b>SYNOPSIS</b></p> |
| 37 |
|
| 38 |
<p style="margin-left:6%;"><b>#include |
| 39 |
<archive.h></b></p> |
| 40 |
|
| 41 |
<p style="margin-top: 1em"><b>DESCRIPTION</b></p> |
| 42 |
|
| 43 |
<p style="margin-left:6%;">These functions provide a |
| 44 |
complete API for reading streaming archives. The general |
| 45 |
process is to first create the struct archive object, set |
| 46 |
options, initialize the reader, iterate over the archive |
| 47 |
headers and associated data, then close the archive and |
| 48 |
release all resources.</p> |
| 49 |
|
| 50 |
<p style="margin-left:6%; margin-top: 1em"><b>Create |
| 51 |
archive object</b> <br> |
| 52 |
See archive_read_new(3).</p> |
| 53 |
|
| 54 |
<p style="margin-left:6%; margin-top: 1em">To read an |
| 55 |
archive, you must first obtain an initialized struct archive |
| 56 |
object from <b>archive_read_new</b>().</p> |
| 57 |
|
| 58 |
<p style="margin-left:6%; margin-top: 1em"><b>Enable |
| 59 |
filters and formats</b> <br> |
| 60 |
See archive_read_filter(3) and archive_read_format(3).</p> |
| 61 |
|
| 62 |
<p style="margin-left:6%; margin-top: 1em">You can then |
| 63 |
modify this object for the desired operations with the |
| 64 |
various <b>archive_read_set_XXX</b>() and |
| 65 |
<b>archive_read_support_XXX</b>() functions. In particular, |
| 66 |
you will need to invoke appropriate |
| 67 |
<b>archive_read_support_XXX</b>() functions to enable the |
| 68 |
corresponding compression and format support. Note that |
| 69 |
these latter functions perform two distinct operations: they |
| 70 |
cause the corresponding support code to be linked into your |
| 71 |
program, and they enable the corresponding auto-detect code. |
| 72 |
Unless you have specific constraints, you will generally |
| 73 |
want to invoke <b>archive_read_support_filter_all</b>() and |
| 74 |
<b>archive_read_support_format_all</b>() to enable |
| 75 |
auto-detect for all formats and compression types currently |
| 76 |
supported by the library.</p> |
| 77 |
|
| 78 |
<p style="margin-left:6%; margin-top: 1em"><b>Set |
| 79 |
options</b> <br> |
| 80 |
See archive_read_set_options(3).</p> |
| 81 |
|
| 82 |
<p style="margin-left:6%; margin-top: 1em"><b>Open |
| 83 |
archive</b> <br> |
| 84 |
See archive_read_open(3).</p> |
| 85 |
|
| 86 |
<p style="margin-left:6%; margin-top: 1em">Once you have |
| 87 |
prepared the struct archive object, you call |
| 88 |
<b>archive_read_open</b>() to actually open the archive and |
| 89 |
prepare it for reading. There are several variants of this |
| 90 |
function; the most basic expects you to provide pointers to |
| 91 |
several functions that can provide blocks of bytes from the |
| 92 |
archive. There are convenience forms that allow you to |
| 93 |
specify a filename, file descriptor, <i>FILE *</i> object, |
| 94 |
or a block of memory from which to read the archive data. |
| 95 |
Note that the core library makes no assumptions about the |
| 96 |
size of the blocks read; callback functions are free to read |
| 97 |
whatever block size is most appropriate for the medium.</p> |
| 98 |
|
| 99 |
<p style="margin-left:6%; margin-top: 1em"><b>Consume |
| 100 |
archive</b> <br> |
| 101 |
See archive_read_header(3), archive_read_data(3) and |
| 102 |
archive_read_extract(3).</p> |
| 103 |
|
| 104 |
<p style="margin-left:6%; margin-top: 1em">Each archive |
| 105 |
entry consists of a header followed by a certain amount of |
| 106 |
data. You can obtain the next header with |
| 107 |
<b>archive_read_next_header</b>(), which returns a pointer |
| 108 |
to an struct archive_entry structure with information about |
| 109 |
the current archive element. If the entry is a regular file, |
| 110 |
then the header will be followed by the file data. You can |
| 111 |
use <b>archive_read_data</b>() (which works much like the |
| 112 |
read(2) system call) to read this data from the archive, or |
| 113 |
<b>archive_read_data_block</b>() which provides a slightly |
| 114 |
more efficient interface. You may prefer to use the |
| 115 |
higher-level <b>archive_read_data_skip</b>(), which reads |
| 116 |
and discards the data for this entry, |
| 117 |
<b>archive_read_data_into_fd</b>(), which copies the data to |
| 118 |
the provided file descriptor, or |
| 119 |
<b>archive_read_extract</b>(), which recreates the specified |
| 120 |
entry on disk and copies data from the archive. In |
| 121 |
particular, note that <b>archive_read_extract</b>() uses the |
| 122 |
struct archive_entry structure that you provide it, which |
| 123 |
may differ from the entry just read from the archive. In |
| 124 |
particular, many applications will want to override the |
| 125 |
pathname, file permissions, or ownership.</p> |
| 126 |
|
| 127 |
<p style="margin-left:6%; margin-top: 1em"><b>Release |
| 128 |
resources</b> <br> |
| 129 |
See archive_read_free(3).</p> |
| 130 |
|
| 131 |
<p style="margin-left:6%; margin-top: 1em">Once you have |
| 132 |
finished reading data from the archive, you should call |
| 133 |
<b>archive_read_close</b>() to close the archive, then call |
| 134 |
<b>archive_read_free</b>() to release all resources, |
| 135 |
including all memory allocated by the library.</p> |
| 136 |
|
| 137 |
<p style="margin-top: 1em"><b>EXAMPLE</b></p> |
| 138 |
|
| 139 |
<p style="margin-left:6%;">The following illustrates basic |
| 140 |
usage of the library. In this example, the callback |
| 141 |
functions are simply wrappers around the standard open(2), |
| 142 |
read(2), and close(2) system calls.</p> |
| 143 |
|
| 144 |
<p style="margin-left:14%; margin-top: 1em">void <br> |
| 145 |
list_archive(const char *name) <br> |
| 146 |
{ <br> |
| 147 |
struct mydata *mydata; <br> |
| 148 |
struct archive *a; <br> |
| 149 |
struct archive_entry *entry;</p> |
| 150 |
|
| 151 |
<p style="margin-left:14%; margin-top: 1em">mydata = |
| 152 |
malloc(sizeof(struct mydata)); <br> |
| 153 |
a = archive_read_new(); <br> |
| 154 |
mydata->name = name; <br> |
| 155 |
archive_read_support_filter_all(a); <br> |
| 156 |
archive_read_support_format_all(a); <br> |
| 157 |
archive_read_open(a, mydata, myopen, myread, myclose); <br> |
| 158 |
while (archive_read_next_header(a, &entry) == |
| 159 |
ARCHIVE_OK) { <br> |
| 160 |
printf("%s\n",archive_entry_pathname(entry)); <br> |
| 161 |
archive_read_data_skip(a); <br> |
| 162 |
} <br> |
| 163 |
archive_read_free(a); <br> |
| 164 |
free(mydata); <br> |
| 165 |
}</p> |
| 166 |
|
| 167 |
<p style="margin-left:14%; margin-top: 1em">la_ssize_t <br> |
| 168 |
myread(struct archive *a, void *client_data, const void |
| 169 |
**buff) <br> |
| 170 |
{ <br> |
| 171 |
struct mydata *mydata = client_data;</p> |
| 172 |
|
| 173 |
<p style="margin-left:14%; margin-top: 1em">*buff = |
| 174 |
mydata->buff; <br> |
| 175 |
return (read(mydata->fd, mydata->buff, 10240)); <br> |
| 176 |
}</p> |
| 177 |
|
| 178 |
<p style="margin-left:14%; margin-top: 1em">int <br> |
| 179 |
myopen(struct archive *a, void *client_data) <br> |
| 180 |
{ <br> |
| 181 |
struct mydata *mydata = client_data;</p> |
| 182 |
|
| 183 |
<p style="margin-left:14%; margin-top: 1em">mydata->fd = |
| 184 |
open(mydata->name, O_RDONLY); <br> |
| 185 |
return (mydata->fd >= 0 ? ARCHIVE_OK : ARCHIVE_FATAL); |
| 186 |
<br> |
| 187 |
}</p> |
| 188 |
|
| 189 |
<p style="margin-left:14%; margin-top: 1em">int <br> |
| 190 |
myclose(struct archive *a, void *client_data) <br> |
| 191 |
{ <br> |
| 192 |
struct mydata *mydata = client_data;</p> |
| 193 |
|
| 194 |
<p style="margin-left:14%; margin-top: 1em">if |
| 195 |
(mydata->fd > 0) <br> |
| 196 |
close(mydata->fd); <br> |
| 197 |
return (ARCHIVE_OK); <br> |
| 198 |
}</p> |
| 199 |
|
| 200 |
<p style="margin-top: 1em"><b>SEE ALSO</b></p> |
| 201 |
|
| 202 |
<p style="margin-left:6%;">tar(1), libarchive(3), |
| 203 |
archive_read_new(3), archive_read_data(3), |
| 204 |
archive_read_extract(3), archive_read_filter(3), |
| 205 |
archive_read_format(3), archive_read_header(3), |
| 206 |
archive_read_open(3), archive_read_set_options(3), |
| 207 |
archive_util(3), tar(5)</p> |
| 208 |
|
| 209 |
<p style="margin-top: 1em"><b>HISTORY</b></p> |
| 210 |
|
| 211 |
<p style="margin-left:6%;">The <b>libarchive</b> library |
| 212 |
first appeared in FreeBSD 5.3.</p> |
| 213 |
|
| 214 |
<p style="margin-top: 1em"><b>AUTHORS</b></p> |
| 215 |
|
| 216 |
<p style="margin-left:6%;">The <b>libarchive</b> library |
| 217 |
was written by Tim Kientzle <kientzle@acm.org>.</p> |
| 218 |
|
| 219 |
<p style="margin-top: 1em"><b>BUGS</b></p> |
| 220 |
|
| 221 |
<p style="margin-left:6%;">Many traditional archiver |
| 222 |
programs treat empty files as valid empty archives. For |
| 223 |
example, many implementations of tar(1) allow you to append |
| 224 |
entries to an empty file. Of course, it is impossible to |
| 225 |
determine the format of an empty file by inspecting the |
| 226 |
contents, so this library treats empty files as having a |
| 227 |
special ’’empty’’ format.</p> |
| 228 |
|
| 229 |
<p style="margin-left:6%; margin-top: 1em">BSD |
| 230 |
February 2, 2012 BSD</p> |
| 231 |
<hr> |
| 232 |
</body> |
| 233 |
</html> |
