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
|
<!-- Creator : groff version 1.22.3 -->
<!-- CreationDate: Mon Sep 3 22:55:07 2018 -->
<!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_behavior</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> —
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_behavior</b>(<i>struct archive *</i>,
<i>int</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>const char
*</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>const char
*</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-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_behavior</b>()</p>
<p style="margin-left:17%;">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:27%;">Skip files and directories with
the nodump file attribute (file flag) set. By default, the
nodump file atrribute is ignored.</p>
<p><b>ARCHIVE_READDISK_MAC_COPYFILE</b></p>
<p style="margin-left:27%;">Mac OS X specific. Read
metadata (ACLs and extended attributes) with copyfile(3). By
default, metadata is read using copyfile(3).</p>
<p><b>ARCHIVE_READDISK_NO_ACL</b></p>
<p style="margin-left:27%;">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:27%;">Do not read file attributes
(file flags). By default, file attributes are read from
disk. See chattr(1) (Linux) or chflags(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:27%;">Do not traverse mount points.
By defaut, moint points are traversed.</p>
<p><b>ARCHIVE_READDISK_NO_XATTR</b></p>
<p style="margin-left:27%;">Do not read extended file
attributes (xattrs). By default, extended file attributes
are read from disk. See xattr(7) (Linux), xattr(2) (Mac OS
X), or getextattr(8) (FreeBSD) for more information on
extended file attributes.</p>
<p><b>ARCHIVE_READDISK_RESTORE_ATIME</b></p>
<p style="margin-left:27%;">Restore access time of
traversed files. By default, access time of traversed files
is not restored.</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-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
April 3, 2017 BSD</p>
<hr>
</body>
</html>
|
