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
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
|
<!-- Creator : groff version 1.23.0 -->
<!-- CreationDate: Mon Jan 5 10:42:43 2026 -->
<!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><i>ARCHIVE_READ_DISK</i>(3) Library Functions Manual
<i>ARCHIVE_READ_DISK</i>(3)</p>
<p style="margin-top: 1em"><b>NAME</b></p>
<p style="margin-left:9%;">archive_read_disk_new,
archive_read_disk_open, archive_read_disk_open_w,
archive_read_disk_set_behavior,
archive_read_disk_set_symlink_logical,
archive_read_disk_set_symlink_physical,
archive_read_disk_set_symlink_hybrid,
archive_read_disk_entry_from_file, archive_read_disk_gname,
archive_read_disk_uname, archive_read_disk_set_uname_lookup,
archive_read_disk_set_gname_lookup,
archive_read_disk_set_standard_lookup,
archive_read_disk_descend, archive_read_disk_can_descend,
archive_read_disk_current_filesystem,
archive_read_disk_current_filesystem_is_synthetic,
archive_read_disk_current_filesystem_is_remote,
archive_read_disk_set_matching,
archive_read_disk_set_metadata_filter_callback, —
functions for reading objects from disk</p>
<p style="margin-top: 1em"><b>LIBRARY</b></p>
<p style="margin-left:9%;">Streaming Archive Library
(libarchive, -larchive)</p>
<p style="margin-top: 1em"><b>SYNOPSIS</b></p>
<p style="margin-left:9%;"><b>#include
<archive.h></b></p>
<p style="margin-left:9%; margin-top: 1em"><i>struct
archive *</i></p>
<p style="margin-left:14%;"><b>archive_read_disk_new</b>(<i>void</i>);</p>
<p style="margin-left:9%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:14%;"><b>archive_read_disk_open</b>(<i>struct archive *</i>,
<i>const char *</i>);</p>
<p style="margin-left:9%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:14%;"><b>archive_read_disk_open_w</b>(<i>struct archive *</i>,
<i>const wchar_t *</i>);</p>
<p style="margin-left:9%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:14%;"><b>archive_read_disk_set_behavior</b>(<i>struct archive *</i>,
<i>int</i>);</p>
<p style="margin-left:9%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:14%;"><b>archive_read_disk_set_symlink_logical</b>(<i>struct archive *</i>);</p>
<p style="margin-left:9%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:14%;"><b>archive_read_disk_set_symlink_physical</b>(<i>struct archive *</i>);</p>
<p style="margin-left:9%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:14%;"><b>archive_read_disk_set_symlink_hybrid</b>(<i>struct archive *</i>);</p>
<p style="margin-left:9%; margin-top: 1em"><i>const char
*</i></p>
<p style="margin-left:14%;"><b>archive_read_disk_gname</b>(<i>struct archive *</i>,
<i>gid_t</i>);</p>
<p style="margin-left:9%; margin-top: 1em"><i>const char
*</i></p>
<p style="margin-left:14%;"><b>archive_read_disk_uname</b>(<i>struct archive *</i>,
<i>uid_t</i>);</p>
<p style="margin-left:9%; 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:9%; 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:9%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:14%;"><b>archive_read_disk_set_standard_lookup</b>(<i>struct archive *</i>);</p>
<p style="margin-left:9%; 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:9%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:14%;"><b>archive_read_disk_descend</b>(<i>struct archive *</i>);</p>
<p style="margin-left:9%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:14%;"><b>archive_read_disk_can_descend</b>(<i>struct archive *</i>);</p>
<p style="margin-left:9%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:14%;"><b>archive_read_disk_current_filesystem</b>(<i>struct archive *</i>);</p>
<p style="margin-left:9%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:14%;"><b>archive_read_disk_current_filesystem_is_synthetic</b>(<i>struct archive *</i>);</p>
<p style="margin-left:9%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:14%;"><b>archive_read_disk_current_filesystem_is_remote</b>(<i>struct archive *</i>);</p>
<p style="margin-left:9%; margin-top: 1em"><i>int</i></p>
<p><b>archive_read_disk_set_matching</b>(<i>struct archive *</i>,
<i>struct archive *</i>,
<i>void (*excluded_func)(struct archive *, void *, struct archive entry *)</i>,
<i>void *</i>);</p>
<p style="margin-left:9%; margin-top: 1em"><i>int</i></p>
<p><b>archive_read_disk_set_metadata_filter_callback</b>(<i>struct archive *</i>,
<i>int (*metadata_filter_func)(struct archive *, void*, struct archive_entry *)</i>,
<i>void *</i>);</p>
<p style="margin-top: 1em"><b>DESCRIPTION</b></p>
<p style="margin-left:9%;">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:19%;">Allocates and initializes a
struct archive object suitable for reading object
information from disk.</p>
<p style="margin-top: 1em"><b>archive_read_disk_open</b>()</p>
<p style="margin-left:19%;">Opens the file or directory
from the given path and prepares the struct archive to read
it from disk.</p>
<p style="margin-top: 1em"><b>archive_read_disk_open_w</b>()</p>
<p style="margin-left:19%;">Opens the file or directory
from the given path as a wide character string and prepares
the struct archive to read it from disk.</p>
<p style="margin-top: 1em"><b>archive_read_disk_set_behavior</b>()</p>
<p style="margin-left:19%;">Configures various behavior
options when reading entries from disk. The flags field
consists of a bitwise OR of one or more of the following
values:</p>
<p><b>ARCHIVE_READDISK_HONOR_NODUMP</b></p>
<p style="margin-left:29%;">Skip files and directories with
the nodump file attribute (file flag) set. By default, the
nodump file attribute is ignored.</p>
<p><b>ARCHIVE_READDISK_MAC_COPYFILE</b></p>
<p style="margin-left:29%;">Mac OS X specific. Read
metadata (ACLs and extended attributes) with
<i>copyfile</i>(3). By default, metadata is read using
<i>copyfile</i>(3).</p>
<p><b>ARCHIVE_READDISK_NO_ACL</b></p>
<p style="margin-left:29%;">Do not read Access Control
Lists. By default, ACLs are read from disk.</p>
<p><b>ARCHIVE_READDISK_NO_FFLAGS</b></p>
<p style="margin-left:29%;">Do not read file attributes
(file flags). By default, file attributes are read from
disk. See <i>chattr</i>(1) (Linux) or <i>chflags</i>(1)
(FreeBSD, Mac OS X) for more information on file
attributes.</p>
<p><b>ARCHIVE_READDISK_NO_TRAVERSE_MOUNTS</b></p>
<p style="margin-left:29%;">Do not traverse mount points.
By default, mount points are traversed.</p>
<p><b>ARCHIVE_READDISK_NO_XATTR</b></p>
<p style="margin-left:29%;">Do not read extended file
attributes (xattrs). By default, extended file attributes
are read from disk. See <i>xattr</i>(7) (Linux),
<i>xattr</i>(2) (Mac OS X), or <i>getextattr</i>(8)
(FreeBSD) for more information on extended file
attributes.</p>
<p><b>ARCHIVE_READDISK_RESTORE_ATIME</b></p>
<p style="margin-left:29%;">Restore access time of
traversed files. By default, access time of traversed files
is not restored.</p>
<p><b>ARCHIVE_READDISK_NO_SPARSE</b></p>
<p style="margin-left:29%;">Do not read sparse file
information. By default, sparse file information is read
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:19%;">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:19%;">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:19%;">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:19%;">This convenience function
installs a standard set of user and group name lookup
functions. These functions use <i>getpwuid</i>(3) and
<i>getgrgid</i>(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 <i>getpwuid</i>(3) and <i>getgrgid</i>(3).</p>
<p style="margin-top: 1em"><b>archive_read_disk_entry_from_file</b>()</p>
<p style="margin-left:19%;">Populates a struct
archive_entry object with information about a particular
file. The archive_entry object must have already been
created with <i>archive_entry_new</i>(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:19%; 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:19%; 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:19%; 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_disk_descend</b>()</p>
<p style="margin-left:19%;">If the current entry can be
descended, this function will mark the directory as the next
entry for <i>archive_read_header</i>(3) to visit.</p>
<p style="margin-top: 1em"><b>archive_read_disk_can_descend</b>()</p>
<p style="margin-left:19%;">Returns 1 if the current entry
is an unvisited directory and 0 otherwise.</p>
<p style="margin-top: 1em"><b>archive_read_disk_current_filesystem</b>()</p>
<p style="margin-left:19%;">Returns the index of the most
recent filesystem entry that has been visited through
archive_read_disk</p>
<p style="margin-top: 1em"><b>archive_read_disk_current_filesystem_is_synthetic</b>()</p>
<p style="margin-left:19%;">Returns 1 if the current
filesystem is a virtual filesystem. Returns 0 if the current
filesystem is not a virtual filesystem. Returns -1 if it is
unknown.</p>
<p style="margin-top: 1em"><b>archive_read_disk_current_filesystem_is_remote</b>()</p>
<p style="margin-left:19%;">Returns 1 if the current
filesystem is a remote filesystem. Returns 0 if the current
filesystem is not a remote filesystem. Returns -1 if it is
unknown.</p>
<p style="margin-top: 1em"><b>archive_read_disk_set_matching</b>()</p>
<p style="margin-left:19%;">Allows the caller to set struct
archive *_ma to compare each entry during
<i>archive_read_header</i>(3) calls. If matched based on
calls to archive_match_path_excluded,
archive_match_time_excluded, or
archive_match_owner_excluded, then the callback function
specified by the _excluded_func parameter will execute. This
function will receive data provided to the fourth parameter,
void *_client_data.</p>
<p style="margin-top: 1em"><b>archive_read_disk_set_metadata_filter_callback</b>()</p>
<p style="margin-left:19%;">Allows the caller to set a
callback function during calls to
<i>archive_read_header</i>(3) to filter out metadata for
each entry. The callback function receives the struct
archive object, void* custom filter data, and the struct
archive_entry. If the callback function returns an error,
ARCHIVE_RETRY will be returned and the entry will not be
further processed.</p>
<p style="margin-left:9%;">More information about the
<i>struct archive</i> object and the overall design of the
library can be found in the <i>libarchive</i>(3)
overview.</p>
<p style="margin-top: 1em"><b>EXAMPLES</b></p>
<p style="margin-left:9%;">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:17%; 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:17%; 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:9%;">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:9%; 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:9%; 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:9%;">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:9%;"><i>tar</i>(1),
<i>archive_read</i>(3), <i>archive_util</i>(3),
<i>archive_write</i>(3), <i>archive_write_disk</i>(3),
<i>libarchive</i>(3)</p>
<p style="margin-top: 1em"><b>HISTORY</b></p>
<p style="margin-left:9%;">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:9%;">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:9%;">The “standard” user
name and group name lookup functions are not the defaults
because <i>getgrgid</i>(3) and <i>getpwuid</i>(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:9%; 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:9%; 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:9%; 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
<i>archive_read</i>(3) API. When such methods are
implemented, the “hybrid” symbolic link mode
will make sense. Debian April 3, 2017
<i>ARCHIVE_READ_DISK</i>(3)</p>
<hr>
</body>
</html>
|
