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
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
|
<!-- Creator : groff version 1.22.3 -->
<!-- CreationDate: Sun Oct 23 20:38:26 2016 -->
<!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_DISK(3) BSD Library Functions Manual
ARCHIVE_READ_DISK(3)</p>
<p style="margin-top: 1em"><b>NAME</b></p>
<p style="margin-left:6%;"><b>archive_read_disk_new</b>,
<b>archive_read_disk_set_symlink_logical</b>,
<b>archive_read_disk_set_symlink_physical</b>,
<b>archive_read_disk_set_symlink_hybrid</b>,
<b>archive_read_disk_entry_from_file</b>,
<b>archive_read_disk_gname</b>,
<b>archive_read_disk_uname</b>,
<b>archive_read_disk_set_uname_lookup</b>,
<b>archive_read_disk_set_gname_lookup</b>,
<b>archive_read_disk_set_standard_lookup</b>,
<b>archive_read_close</b>, <b>archive_read_finish</b>,
<b>archive_read_free</b> — functions for reading
objects from disk</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>struct
archive *</i></p>
<p style="margin-left:12%;"><b>archive_read_disk_new</b>(<i>void</i>);</p>
<p style="margin-left:6%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:12%;"><b>archive_read_disk_set_symlink_logical</b>(<i>struct archive *</i>);</p>
<p style="margin-left:6%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:12%;"><b>archive_read_disk_set_symlink_physical</b>(<i>struct archive *</i>);</p>
<p style="margin-left:6%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:12%;"><b>archive_read_disk_set_symlink_hybrid</b>(<i>struct archive *</i>);</p>
<p style="margin-left:6%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:12%;"><b>archive_read_disk_gname</b>(<i>struct archive *</i>,
<i>gid_t</i>);</p>
<p style="margin-left:6%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:12%;"><b>archive_read_disk_uname</b>(<i>struct archive *</i>,
<i>uid_t</i>);</p>
<p style="margin-left:6%; margin-top: 1em"><i>int</i></p>
<p><b>archive_read_disk_set_gname_lookup</b>(<i>struct archive *</i>,
<i>void *</i>,
<i>const char *(*lookup)(void *, gid_t)</i>,
<i>void (*cleanup)(void *)</i>);</p>
<p style="margin-left:6%; margin-top: 1em"><i>int</i></p>
<p><b>archive_read_disk_set_uname_lookup</b>(<i>struct archive *</i>,
<i>void *</i>,
<i>const char *(*lookup)(void *, uid_t)</i>,
<i>void (*cleanup)(void *)</i>);</p>
<p style="margin-left:6%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:12%;"><b>archive_read_disk_set_standard_lookup</b>(<i>struct archive *</i>);</p>
<p style="margin-left:6%; margin-top: 1em"><i>int</i></p>
<p><b>archive_read_disk_entry_from_file</b>(<i>struct archive *</i>,
<i>struct archive_entry *</i>, <i>int fd</i>,
<i>const struct stat *</i>);</p>
<p style="margin-left:6%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:12%;"><b>archive_read_close</b>(<i>struct archive *</i>);</p>
<p style="margin-left:6%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:12%;"><b>archive_read_finish</b>(<i>struct archive *</i>);</p>
<p style="margin-left:6%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:12%;"><b>archive_read_free</b>(<i>struct archive *</i>);</p>
<p style="margin-top: 1em"><b>DESCRIPTION</b></p>
<p style="margin-left:6%;">These functions provide an API
for reading information about objects on disk. In
particular, they provide an interface for populating struct
archive_entry objects.</p>
<p style="margin-top: 1em"><b>archive_read_disk_new</b>()</p>
<p style="margin-left:17%;">Allocates and initializes a
struct archive object suitable for reading object
information from disk.</p>
<p style="margin-top: 1em"><b>archive_read_disk_set_symlink_logical</b>(),
<b>archive_read_disk_set_symlink_physical</b>(),
<b>archive_read_disk_set_symlink_hybrid</b>()</p>
<p style="margin-left:17%;">This sets the mode used for
handling symbolic links. The
’’logical’’ mode follows all
symbolic links. The ’’physical’’
mode does not follow any symbolic links. The
’’hybrid’’ mode currently behaves
identically to the ’’logical’’
mode.</p>
<p style="margin-top: 1em"><b>archive_read_disk_gname</b>(),
<b>archive_read_disk_uname</b>()</p>
<p style="margin-left:17%;">Returns a user or group name
given a gid or uid value. By default, these always return a
NULL string.</p>
<p style="margin-top: 1em"><b>archive_read_disk_set_gname_lookup</b>(),
<b>archive_read_disk_set_uname_lookup</b>()</p>
<p style="margin-left:17%;">These allow you to override the
functions used for user and group name lookups. You may also
provide a void * pointer to a private data structure and a
cleanup function for that data. The cleanup function will be
invoked when the struct archive object is destroyed or when
new lookup functions are registered.</p>
<p style="margin-top: 1em"><b>archive_read_disk_set_standard_lookup</b>()</p>
<p style="margin-left:17%;">This convenience function
installs a standard set of user and group name lookup
functions. These functions use getpwuid(3) and getgrgid(3)
to convert ids to names, defaulting to NULL if the names
cannot be looked up. These functions also implement a simple
memory cache to reduce the number of calls to getpwuid(3)
and getgrgid(3).</p>
<p style="margin-top: 1em"><b>archive_read_disk_entry_from_file</b>()</p>
<p style="margin-left:17%;">Populates a struct
archive_entry object with information about a particular
file. The archive_entry object must have already been
created with archive_entry_new(3) and at least one of the
source path or path fields must already be set. (If both are
set, the source path will be used.)</p>
<p style="margin-left:17%; margin-top: 1em">Information is
read from disk using the path name from the struct
archive_entry object. If a file descriptor is provided, some
information will be obtained using that file descriptor, on
platforms that support the appropriate system calls.</p>
<p style="margin-left:17%; margin-top: 1em">If a pointer to
a struct stat is provided, information from that structure
will be used instead of reading from the disk where
appropriate. This can provide performance benefits in
scenarios where struct stat information has already been
read from the disk as a side effect of some other operation.
(For example, directory traversal libraries often provide
this information.)</p>
<p style="margin-left:17%; margin-top: 1em">Where
necessary, user and group ids are converted to user and
group names using the currently registered lookup functions
above. This affects the file ownership fields and ACL values
in the struct archive_entry object.</p>
<p style="margin-top: 1em"><b>archive_read_close</b>()</p>
<p style="margin-left:17%;">Does nothing for
archive_read_disk handles.</p>
<p style="margin-top: 1em"><b>archive_read_finish</b>()</p>
<p style="margin-left:17%;">This is a deprecated synonym
for <b>archive_read_free</b>().</p>
<p style="margin-top: 1em"><b>archive_read_free</b>()</p>
<p style="margin-left:17%;">Invokes
<b>archive_read_close</b>() if it was not invoked manually,
then releases all resources.</p>
<p style="margin-left:6%;">More information about the
<i>struct archive</i> object and the overall design of the
library can be found in the libarchive(3) overview.</p>
<p style="margin-top: 1em"><b>EXAMPLE</b></p>
<p style="margin-left:6%;">The following illustrates basic
usage of the library by showing how to use it to copy an
item on disk into an archive.</p>
<p style="margin-left:14%; margin-top: 1em">void <br>
file_to_archive(struct archive *a, const char *name) <br>
{ <br>
char buff[8192]; <br>
size_t bytes_read; <br>
struct archive *ard; <br>
struct archive_entry *entry; <br>
int fd;</p>
<p style="margin-left:14%; margin-top: 1em">ard =
archive_read_disk_new(); <br>
archive_read_disk_set_standard_lookup(ard); <br>
entry = archive_entry_new(); <br>
fd = open(name, O_RDONLY); <br>
if (fd < 0) <br>
return; <br>
archive_entry_copy_pathname(entry, name); <br>
archive_read_disk_entry_from_file(ard, entry, fd, NULL);
<br>
archive_write_header(a, entry); <br>
while ((bytes_read = read(fd, buff, sizeof(buff))) > 0)
<br>
archive_write_data(a, buff, bytes_read); <br>
archive_write_finish_entry(a); <br>
archive_read_free(ard); <br>
archive_entry_free(entry); <br>
}</p>
<p style="margin-top: 1em"><b>RETURN VALUES</b></p>
<p style="margin-left:6%;">Most functions return
<b>ARCHIVE_OK</b> (zero) on success, or one of several
negative error codes for errors. Specific error codes
include: <b>ARCHIVE_RETRY</b> for operations that might
succeed if retried, <b>ARCHIVE_WARN</b> for unusual
conditions that do not prevent further operations, and
<b>ARCHIVE_FATAL</b> for serious errors that make remaining
operations impossible.</p>
<p style="margin-left:6%; margin-top: 1em"><b>archive_read_disk_new</b>()
returns a pointer to a newly-allocated struct archive object
or NULL if the allocation failed for any reason.</p>
<p style="margin-left:6%; margin-top: 1em"><b>archive_read_disk_gname</b>()
and <b>archive_read_disk_uname</b>() return const char *
pointers to the textual name or NULL if the lookup failed
for any reason. The returned pointer points to internal
storage that may be reused on the next call to either of
these functions; callers should copy the string if they need
to continue accessing it.</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%;">archive_read(3),
archive_util(3), archive_write(3), archive_write_disk(3),
tar(1), libarchive(3)</p>
<p style="margin-top: 1em"><b>HISTORY</b></p>
<p style="margin-left:6%;">The <b>libarchive</b> library
first appeared in FreeBSD 5.3. The
<b>archive_read_disk</b> interface was added to
<b>libarchive 2.6</b> and first appeared in
FreeBSD 8.0.</p>
<p style="margin-top: 1em"><b>AUTHORS</b></p>
<p style="margin-left:6%;">The <b>libarchive</b> library
was written by Tim Kientzle
<kientzle@FreeBSD.org>.</p>
<p style="margin-top: 1em"><b>BUGS</b></p>
<p style="margin-left:6%;">The
’’standard’’ user name and group
name lookup functions are not the defaults because
getgrgid(3) and getpwuid(3) are sometimes too large for
particular applications. The current design allows the
application author to use a more compact implementation when
appropriate.</p>
<p style="margin-left:6%; margin-top: 1em">The full list of
metadata read from disk by
<b>archive_read_disk_entry_from_file</b>() is necessarily
system-dependent.</p>
<p style="margin-left:6%; margin-top: 1em">The
<b>archive_read_disk_entry_from_file</b>() function reads as
much information as it can from disk. Some method should be
provided to limit this so that clients who do not need ACLs,
for instance, can avoid the extra work needed to look up
such information.</p>
<p style="margin-left:6%; margin-top: 1em">This API should
provide a set of methods for walking a directory tree. That
would make it a direct parallel of the archive_read(3) API.
When such methods are implemented, the
’’hybrid’’ symbolic link mode will
make sense.</p>
<p style="margin-left:6%; margin-top: 1em">BSD
February 2, 2012 BSD</p>
<hr>
</body>
</html>
|
