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 ,
44 .Nd functions for reading objects from disk
48 .Fn archive_read_disk_new "void"
50 .Fn archive_read_disk_set_symlink_logical "struct archive *"
52 .Fn archive_read_disk_set_symlink_physical "struct archive *"
54 .Fn archive_read_disk_set_symlink_hybrid "struct archive *"
56 .Fn archive_read_disk_gname "struct archive *" "gid_t"
58 .Fn archive_read_disk_uname "struct archive *" "uid_t"
60 .Fo archive_read_disk_set_gname_lookup
61 .Fa "struct archive *"
63 .Fa "const char *(*lookup)(void *, gid_t)"
64 .Fa "void (*cleanup)(void *)"
67 .Fo archive_read_disk_set_uname_lookup
68 .Fa "struct archive *"
70 .Fa "const char *(*lookup)(void *, uid_t)"
71 .Fa "void (*cleanup)(void *)"
74 .Fn archive_read_disk_set_standard_lookup "struct archive *"
76 .Fo archive_read_disk_entry_from_file
77 .Fa "struct archive *"
78 .Fa "struct archive_entry *"
80 .Fa "const struct stat *"
83 .Fn archive_read_close "struct archive *"
85 .Fn archive_read_finish "struct archive *"
87 .Fn archive_read_free "struct archive *"
89 These functions provide an API for reading information about
91 In particular, they provide an interface for populating
92 .Tn struct archive_entry
94 .Bl -tag -width indent
95 .It Fn archive_read_disk_new
96 Allocates and initializes a
98 object suitable for reading object information from disk.
100 .Fn archive_read_disk_set_symlink_logical ,
101 .Fn archive_read_disk_set_symlink_physical ,
102 .Fn archive_read_disk_set_symlink_hybrid
104 This sets the mode used for handling symbolic links.
107 mode follows all symbolic links.
110 mode does not follow any symbolic links.
113 mode currently behaves identically to the
117 .Fn archive_read_disk_gname ,
118 .Fn archive_read_disk_uname
120 Returns a user or group name given a gid or uid value.
121 By default, these always return a NULL string.
123 .Fn archive_read_disk_set_gname_lookup ,
124 .Fn archive_read_disk_set_uname_lookup
126 These allow you to override the functions used for
127 user and group name lookups.
128 You may also provide a
130 pointer to a private data structure and a cleanup function for
132 The cleanup function will be invoked when the
134 object is destroyed or when new lookup functions are registered.
135 .It Fn archive_read_disk_set_standard_lookup
136 This convenience function installs a standard set of user
137 and group name lookup functions.
142 to convert ids to names, defaulting to NULL if the names cannot
144 These functions also implement a simple memory cache to reduce
145 the number of calls to
149 .It Fn archive_read_disk_entry_from_file
151 .Tn struct archive_entry
152 object with information about a particular file.
155 object must have already been created with
156 .Xr archive_entry_new 3
157 and at least one of the source path or path fields must already be set.
158 (If both are set, the source path will be used.)
160 Information is read from disk using the path name from the
161 .Tn struct archive_entry
163 If a file descriptor is provided, some information will be obtained using
164 that file descriptor, on platforms that support the appropriate
169 is provided, information from that structure will be used instead
170 of reading from the disk where appropriate.
171 This can provide performance benefits in scenarios where
173 information has already been read from the disk as a side effect
174 of some other operation.
175 (For example, directory traversal libraries often provide this information.)
177 Where necessary, user and group ids are converted to user and group names
178 using the currently registered lookup functions above.
179 This affects the file ownership fields and ACL values in the
180 .Tn struct archive_entry
182 .It Fn archive_read_close
184 .Tn archive_read_disk
186 .It Fn archive_read_finish
187 This is a deprecated synonym for
188 .Fn archive_read_free .
189 .It Fn archive_read_free
191 .Fn archive_read_close
192 if it was not invoked manually, then releases all resources.
194 More information about the
196 object and the overall design of the library can be found in the
200 The following illustrates basic usage of the library by
201 showing how to use it to copy an item on disk into an archive.
202 .Bd -literal -offset indent
204 file_to_archive(struct archive *a, const char *name)
209 struct archive_entry *entry;
212 ard = archive_read_disk_new();
213 archive_read_disk_set_standard_lookup(ard);
214 entry = archive_entry_new();
215 fd = open(name, O_RDONLY);
218 archive_entry_copy_pathname(entry, name);
219 archive_read_disk_entry_from_file(ard, entry, fd, NULL);
220 archive_write_header(a, entry);
221 while ((bytes_read = read(fd, buff, sizeof(buff))) > 0)
222 archive_write_data(a, buff, bytes_read);
223 archive_write_finish_entry(a);
224 archive_read_free(ard);
225 archive_entry_free(entry);
229 Most functions return
231 (zero) on success, or one of several negative
232 error codes for errors.
233 Specific error codes include:
235 for operations that might succeed if retried,
237 for unusual conditions that do not prevent further operations, and
239 for serious errors that make remaining operations impossible.
241 .Fn archive_read_disk_new
242 returns a pointer to a newly-allocated
244 object or NULL if the allocation failed for any reason.
246 .Fn archive_read_disk_gname
248 .Fn archive_read_disk_uname
251 pointers to the textual name or NULL if the lookup failed for any reason.
252 The returned pointer points to internal storage that
253 may be reused on the next call to either of these functions;
254 callers should copy the string if they need to continue accessing it.
257 Detailed error codes and textual descriptions are available from the
260 .Fn archive_error_string
266 .Xr archive_write 3 ,
267 .Xr archive_write_disk 3 ,
273 library first appeared in
276 .Nm archive_read_disk
277 interface was added to
279 and first appeared in
285 library was written by
286 .An Tim Kientzle Aq kientzle@FreeBSD.org .
290 user name and group name lookup functions are not the defaults because
294 are sometimes too large for particular applications.
295 The current design allows the application author to use a more
296 compact implementation when appropriate.
298 The full list of metadata read from disk by
299 .Fn archive_read_disk_entry_from_file
300 is necessarily system-dependent.
303 .Fn archive_read_disk_entry_from_file
304 function reads as much information as it can from disk.
305 Some method should be provided to limit this so that clients who
306 do not need ACLs, for instance, can avoid the extra work needed
307 to look up such information.
309 This API should provide a set of methods for walking a directory tree.
310 That would make it a direct parallel of the
313 When such methods are implemented, the
315 symbolic link mode will make sense.