1
.\" Copyright (c) 2003-2009 Tim Kientzle
2
.\" All rights reserved.
4
.\" Redistribution and use in source and binary forms, with or without
5
.\" modification, are permitted provided that the following conditions
7
.\" 1. Redistributions of source code must retain the above copyright
8
.\" notice, this list of conditions and the following disclaimer.
9
.\" 2. Redistributions in binary form must reproduce the above copyright
10
.\" notice, this list of conditions and the following disclaimer in the
11
.\" documentation and/or other materials provided with the distribution.
13
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
25
.\" $FreeBSD: head/lib/libarchive/archive_read_disk.3 190957 2009-04-12 05:04:02Z kientzle $
28
.Dt archive_read_disk 3
31
.Nm archive_read_disk_new ,
32
.Nm archive_read_disk_set_symlink_logical ,
33
.Nm archive_read_disk_set_symlink_physical ,
34
.Nm archive_read_disk_set_symlink_hybrid ,
35
.Nm archive_read_disk_entry_from_file ,
36
.Nm archive_read_disk_gname ,
37
.Nm archive_read_disk_uname ,
38
.Nm archive_read_disk_set_uname_lookup ,
39
.Nm archive_read_disk_set_gname_lookup ,
40
.Nm archive_read_disk_set_standard_lookup ,
41
.Nm archive_read_close ,
42
.Nm archive_read_finish
43
.Nd functions for reading objects from disk
47
.Fn archive_read_disk_new "void"
49
.Fn archive_read_disk_set_symlink_logical "struct archive *"
51
.Fn archive_read_disk_set_symlink_physical "struct archive *"
53
.Fn archive_read_disk_set_symlink_hybrid "struct archive *"
55
.Fn archive_read_disk_gname "struct archive *" "gid_t"
57
.Fn archive_read_disk_uname "struct archive *" "uid_t"
59
.Fo archive_read_disk_set_gname_lookup
60
.Fa "struct archive *"
62
.Fa "const char *(*lookup)(void *, gid_t)"
63
.Fa "void (*cleanup)(void *)"
66
.Fo archive_read_disk_set_uname_lookup
67
.Fa "struct archive *"
69
.Fa "const char *(*lookup)(void *, uid_t)"
70
.Fa "void (*cleanup)(void *)"
73
.Fn archive_read_disk_set_standard_lookup "struct archive *"
75
.Fo archive_read_disk_entry_from_file
76
.Fa "struct archive *"
77
.Fa "struct archive_entry *"
79
.Fa "const struct stat *"
82
.Fn archive_read_close "struct archive *"
84
.Fn archive_read_finish "struct archive *"
86
These functions provide an API for reading information about
88
In particular, they provide an interface for populating
89
.Tn struct archive_entry
91
.Bl -tag -width indent
92
.It Fn archive_read_disk_new
93
Allocates and initializes a
95
object suitable for reading object information from disk.
97
.Fn archive_read_disk_set_symlink_logical ,
98
.Fn archive_read_disk_set_symlink_physical ,
99
.Fn archive_read_disk_set_symlink_hybrid
101
This sets the mode used for handling symbolic links.
104
mode follows all symbolic links.
107
mode does not follow any symbolic links.
110
mode currently behaves identically to the
114
.Fn archive_read_disk_gname ,
115
.Fn archive_read_disk_uname
117
Returns a user or group name given a gid or uid value.
118
By default, these always return a NULL string.
120
.Fn archive_read_disk_set_gname_lookup ,
121
.Fn archive_read_disk_set_uname_lookup
123
These allow you to override the functions used for
124
user and group name lookups.
125
You may also provide a
127
pointer to a private data structure and a cleanup function for
129
The cleanup function will be invoked when the
131
object is destroyed or when new lookup functions are registered.
132
.It Fn archive_read_disk_set_standard_lookup
133
This convenience function installs a standard set of user
134
and group name lookup functions.
139
to convert ids to names, defaulting to NULL if the names cannot
141
These functions also implement a simple memory cache to reduce
142
the number of calls to
146
.It Fn archive_read_disk_entry_from_file
148
.Tn struct archive_entry
149
object with information about a particular file.
152
object must have already been created with
153
.Xr archive_entry_new 3
154
and at least one of the source path or path fields must already be set.
155
(If both are set, the source path will be used.)
157
Information is read from disk using the path name from the
158
.Tn struct archive_entry
160
If a file descriptor is provided, some information will be obtained using
161
that file descriptor, on platforms that support the appropriate
166
is provided, information from that structure will be used instead
167
of reading from the disk where appropriate.
168
This can provide performance benefits in scenarios where
170
information has already been read from the disk as a side effect
171
of some other operation.
172
(For example, directory traversal libraries often provide this information.)
174
Where necessary, user and group ids are converted to user and group names
175
using the currently registered lookup functions above.
176
This affects the file ownership fields and ACL values in the
177
.Tn struct archive_entry
179
.It Fn archive_read_close
180
This currently does nothing.
181
.It Fn archive_write_finish
183
.Fn archive_write_close
184
if it was not invoked manually, then releases all resources.
186
More information about the
188
object and the overall design of the library can be found in the
192
The following illustrates basic usage of the library by
193
showing how to use it to copy an item on disk into an archive.
194
.Bd -literal -offset indent
196
file_to_archive(struct archive *a, const char *name)
201
struct archive_entry *entry;
204
ard = archive_read_disk_new();
205
archive_read_disk_set_standard_lookup(ard);
206
entry = archive_entry_new();
207
fd = open(name, O_RDONLY);
210
archive_entry_copy_sourcepath(entry, name);
211
archive_read_disk_entry_from_file(ard, entry, fd, NULL);
212
archive_write_header(a, entry);
213
while ((bytes_read = read(fd, buff, sizeof(buff))) > 0)
214
archive_write_data(a, buff, bytes_read);
215
archive_write_finish_entry(a);
216
archive_read_finish(ard);
217
archive_entry_free(entry);
221
Most functions return
223
(zero) on success, or one of several negative
224
error codes for errors.
225
Specific error codes include:
227
for operations that might succeed if retried,
229
for unusual conditions that do not prevent further operations, and
231
for serious errors that make remaining operations impossible.
235
.Xr archive_error_string 3
236
functions can be used to retrieve an appropriate error code and a
237
textual error message.
242
.Fn archive_read_disk_new
243
returns a pointer to a newly-allocated
245
object or NULL if the allocation failed for any reason.
247
.Fn archive_read_disk_gname
249
.Fn archive_read_disk_uname
252
pointers to the textual name or NULL if the lookup failed for any reason.
253
The returned pointer points to internal storage that
254
may be reused on the next call to either of these functions;
255
callers should copy the string if they need to continue accessing it.
259
.Xr archive_write 3 ,
260
.Xr archive_write_disk 3 ,
266
library first appeared in
269
.Nm archive_read_disk
270
interface was added to
272
and first appeared in
278
library was written by
279
.An Tim Kientzle Aq kientzle@freebsd.org .
283
user name and group name lookup functions are not the defaults because
287
are sometimes too large for particular applications.
288
The current design allows the application author to use a more
289
compact implementation when appropriate.
291
The full list of metadata read from disk by
292
.Fn archive_read_disk_entry_from_file
293
is necessarily system-dependent.
296
.Fn archive_read_disk_entry_from_file
297
function reads as much information as it can from disk.
298
Some method should be provided to limit this so that clients who
299
do not need ACLs, for instance, can avoid the extra work needed
300
to look up such information.
302
This API should provide a set of methods for walking a directory tree.
303
That would make it a direct parallel of the
306
When such methods are implemented, the
308
symbolic link mode will make sense.