1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
|
<!-- Creator : groff version 1.22.4 -->
<!-- CreationDate: Wed Jun 12 21:10:16 2019 -->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta name="generator" content="groff -Thtml, see www.gnu.org">
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<meta name="Content-Style" content="text/css">
<style type="text/css">
p { margin-top: 0; margin-bottom: 0; vertical-align: top }
pre { margin-top: 0; margin-bottom: 0; vertical-align: top }
table { margin-top: 0; margin-bottom: 0; vertical-align: top }
h1 { text-align: center }
</style>
<title></title>
</head>
<body>
<hr>
<p>ARCHIVE_READ_OPEN(3) BSD Library Functions Manual
ARCHIVE_READ_OPEN(3)</p>
<p style="margin-top: 1em"><b>NAME</b></p>
<p style="margin-left:6%;"><b>archive_read_open</b>,
<b>archive_read_open2</b>, <b>archive_read_open_fd</b>,
<b>archive_read_open_FILE</b>,
<b>archive_read_open_filename</b>,
<b>archive_read_open_memory</b> — functions for
reading streaming archives</p>
<p style="margin-top: 1em"><b>LIBRARY</b></p>
<p style="margin-left:6%;">Streaming Archive Library
(libarchive, -larchive)</p>
<p style="margin-top: 1em"><b>SYNOPSIS</b></p>
<p style="margin-left:6%;"><b>#include
<archive.h></b></p>
<p style="margin-left:6%; margin-top: 1em"><i>int</i></p>
<p><b>archive_read_open</b>(<i>struct archive *</i>,
<i>void *client_data</i>,
<i>archive_open_callback *</i>,
<i>archive_read_callback *</i>,
<i>archive_close_callback *</i>);</p>
<p style="margin-left:6%; margin-top: 1em"><i>int</i></p>
<p><b>archive_read_open2</b>(<i>struct archive *</i>,
<i>void *client_data</i>,
<i>archive_open_callback *</i>,
<i>archive_read_callback *</i>,
<i>archive_skip_callback *</i>,
<i>archive_close_callback *</i>);</p>
<p style="margin-left:6%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:12%;"><b>archive_read_open_FILE</b>(<i>struct archive *</i>,
<i>FILE *file</i>);</p>
<p style="margin-left:6%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:12%;"><b>archive_read_open_fd</b>(<i>struct archive *</i>,
<i>int fd</i>, <i>size_t block_size</i>);</p>
<p style="margin-left:6%; margin-top: 1em"><i>int</i></p>
<p><b>archive_read_open_filename</b>(<i>struct archive *</i>,
<i>const char *filename</i>,
<i>size_t block_size</i>);</p>
<p style="margin-left:6%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:12%;"><b>archive_read_open_memory</b>(<i>struct archive *</i>,
<i>const void *buff</i>,
<i>size_t size</i>);</p>
<p style="margin-top: 1em"><b>DESCRIPTION <br>
archive_read_open</b>()</p>
<p style="margin-left:17%;">The same as
<b>archive_read_open2</b>(), except that the skip callback
is assumed to be NULL.</p>
<p><b>archive_read_open2</b>()</p>
<p style="margin-left:17%;">Freeze the settings, open the
archive, and prepare for reading entries. This is the most
generic version of this call, which accepts four callback
functions. Most clients will want to use
<b>archive_read_open_filename</b>(),
<b>archive_read_open_FILE</b>(),
<b>archive_read_open_fd</b>(), or
<b>archive_read_open_memory</b>() instead. The library
invokes the client-provided functions to obtain raw bytes
from the archive.</p>
<p><b>archive_read_open_FILE</b>()</p>
<p style="margin-left:17%;">Like
<b>archive_read_open</b>(), except that it accepts a <i>FILE
*</i> pointer. This function should not be used with tape
drives or other devices that require strict I/O
blocking.</p>
<p><b>archive_read_open_fd</b>()</p>
<p style="margin-left:17%;">Like
<b>archive_read_open</b>(), except that it accepts a file
descriptor and block size rather than a set of function
pointers. Note that the file descriptor will not be
automatically closed at end-of-archive. This function is
safe for use with tape drives or other blocked devices.</p>
<p><b>archive_read_open_file</b>()</p>
<p style="margin-left:17%;">This is a deprecated synonym
for <b>archive_read_open_filename</b>().</p>
<p><b>archive_read_open_filename</b>()</p>
<p style="margin-left:17%;">Like
<b>archive_read_open</b>(), except that it accepts a simple
filename and a block size. A NULL filename represents
standard input. This function is safe for use with tape
drives or other blocked devices.</p>
<p><b>archive_read_open_memory</b>()</p>
<p style="margin-left:17%;">Like
<b>archive_read_open</b>(), except that it accepts a pointer
and size of a block of memory containing the archive
data.</p>
<p style="margin-left:6%; margin-top: 1em">A complete
description of the struct archive and struct archive_entry
objects can be found in the overview manual page for
libarchive(3).</p>
<p style="margin-top: 1em"><b>CLIENT CALLBACKS</b></p>
<p style="margin-left:6%;">The callback functions must
match the following prototypes:</p>
<p style="margin-left:14%; margin-top: 1em"><i>typedef
la_ssize_t</i></p>
<p><b>archive_read_callback</b>(<i>struct archive *</i>,
<i>void *client_data</i>,
<i>const void **buffer</i>)</p>
<p style="margin-left:14%; margin-top: 1em"><i>typedef
la_int64_t</i></p>
<p><b>archive_skip_callback</b>(<i>struct archive *</i>,
<i>void *client_data</i>,
<i>off_t request</i>)</p>
<p style="margin-left:14%; margin-top: 1em"><i>typedef
int</i> <b>archive_open_callback</b>(<i>struct archive
*</i>, <i>void *client_data</i>)</p>
<p style="margin-left:14%; margin-top: 1em"><i>typedef
int</i> <b>archive_close_callback</b>(<i>struct archive
*</i>, <i>void *client_data</i>)</p>
<p style="margin-left:6%; margin-top: 1em">The open
callback is invoked by <b>archive_open</b>(). It should
return <b>ARCHIVE_OK</b> if the underlying file or data
source is successfully opened. If the open fails, it should
call <b>archive_set_error</b>() to register an error code
and message and return <b>ARCHIVE_FATAL</b>.</p>
<p style="margin-left:6%; margin-top: 1em">The read
callback is invoked whenever the library requires raw bytes
from the archive. The read callback should read data into a
buffer, set the const void **buffer argument to point to the
available data, and return a count of the number of bytes
available. The library will invoke the read callback again
only after it has consumed this data. The library imposes no
constraints on the size of the data blocks returned. On
end-of-file, the read callback should return zero. On error,
the read callback should invoke <b>archive_set_error</b>()
to register an error code and message and return -1.</p>
<p style="margin-left:6%; margin-top: 1em">The skip
callback is invoked when the library wants to ignore a block
of data. The return value is the number of bytes actually
skipped, which may differ from the request. If the callback
cannot skip data, it should return zero. If the skip
callback is not provided (the function pointer is NULL ),
the library will invoke the read function instead and simply
discard the result. A skip callback can provide significant
performance gains when reading uncompressed archives from
slow disk drives or other media that can skip quickly.</p>
<p style="margin-left:6%; margin-top: 1em">The close
callback is invoked by archive_close when the archive
processing is complete. The callback should return
<b>ARCHIVE_OK</b> on success. On failure, the callback
should invoke <b>archive_set_error</b>() to register an
error code and message and return <b>ARCHIVE_FATAL.</b></p>
<p style="margin-top: 1em"><b>RETURN VALUES</b></p>
<p style="margin-left:6%;">These functions return
<b>ARCHIVE_OK</b> on success, or <b>ARCHIVE_FATAL</b>.</p>
<p style="margin-top: 1em"><b>ERRORS</b></p>
<p style="margin-left:6%;">Detailed error codes and textual
descriptions are available from the <b>archive_errno</b>()
and <b>archive_error_string</b>() functions.</p>
<p style="margin-top: 1em"><b>SEE ALSO</b></p>
<p style="margin-left:6%;">tar(1), libarchive(3),
archive_read(3), archive_read_data(3),
archive_read_filter(3), archive_read_format(3),
archive_read_set_options(3), archive_util(3), tar(5)</p>
<p style="margin-left:6%; margin-top: 1em">BSD
February 2, 2012 BSD</p>
<hr>
</body>
</html>
|
