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
28 .Dt ARCHIVE_READ_DISK 3
31 .Nm archive_read_disk_new ,
32 .Nm archive_read_disk_set_behavior ,
33 .Nm archive_read_disk_set_symlink_logical ,
34 .Nm archive_read_disk_set_symlink_physical ,
35 .Nm archive_read_disk_set_symlink_hybrid ,
36 .Nm archive_read_disk_entry_from_file ,
37 .Nm archive_read_disk_gname ,
38 .Nm archive_read_disk_uname ,
39 .Nm archive_read_disk_set_uname_lookup ,
40 .Nm archive_read_disk_set_gname_lookup ,
41 .Nm archive_read_disk_set_standard_lookup
42 .Nd functions for reading objects from disk
44 Streaming Archive Library (libarchive, -larchive)
48 .Fn archive_read_disk_new "void"
50 .Fn archive_read_disk_set_behavior "struct archive *" "int"
52 .Fn archive_read_disk_set_symlink_logical "struct archive *"
54 .Fn archive_read_disk_set_symlink_physical "struct archive *"
56 .Fn archive_read_disk_set_symlink_hybrid "struct archive *"
58 .Fn archive_read_disk_gname "struct archive *" "gid_t"
60 .Fn archive_read_disk_uname "struct archive *" "uid_t"
62 .Fo archive_read_disk_set_gname_lookup
63 .Fa "struct archive *"
65 .Fa "const char *(*lookup)(void *, gid_t)"
66 .Fa "void (*cleanup)(void *)"
69 .Fo archive_read_disk_set_uname_lookup
70 .Fa "struct archive *"
72 .Fa "const char *(*lookup)(void *, uid_t)"
73 .Fa "void (*cleanup)(void *)"
76 .Fn archive_read_disk_set_standard_lookup "struct archive *"
78 .Fo archive_read_disk_entry_from_file
79 .Fa "struct archive *"
80 .Fa "struct archive_entry *"
82 .Fa "const struct stat *"
85 These functions provide an API for reading information about
87 In particular, they provide an interface for populating
88 .Tn struct archive_entry
90 .Bl -tag -width indent
91 .It Fn archive_read_disk_new
92 Allocates and initializes a
94 object suitable for reading object information from disk.
95 .It Fn archive_read_disk_set_behavior
96 Configures various behavior options when reading entries from disk.
97 The flags field consists of a bitwise OR of one or more of the
99 .Bl -tag -compact -width "indent"
100 .It Cm ARCHIVE_READDISK_HONOR_NODUMP
101 Skip files and directories with the nodump file attribute (file flag) set.
102 By default, the nodump file atrribute is ignored.
103 .It Cm ARCHIVE_READDISK_MAC_COPYFILE
104 Mac OS X specific. Read metadata (ACLs and extended attributes) with
106 By default, metadata is read using
108 .It Cm ARCHIVE_READDISK_NO_ACL
109 Do not read Access Control Lists.
110 By default, ACLs are read from disk.
111 .It Cm ARCHIVE_READDISK_NO_FFLAGS
112 Do not read file attributes (file flags).
113 By default, file attributes are read from disk.
119 .Pq FreeBSD, Mac OS X
120 for more information on file attributes.
121 .It Cm ARCHIVE_READDISK_NO_TRAVERSE_MOUNTS
122 Do not traverse mount points.
123 By defaut, moint points are traversed.
124 .It Cm ARCHIVE_READDISK_NO_XATTR
125 Do not read extended file attributes (xattrs).
126 By default, extended file attributes are read from disk.
135 for more information on extended file attributes.
136 .It Cm ARCHIVE_READDISK_RESTORE_ATIME
137 Restore access time of traversed files.
138 By default, access time of traversed files is not restored.
141 .Fn archive_read_disk_set_symlink_logical ,
142 .Fn archive_read_disk_set_symlink_physical ,
143 .Fn archive_read_disk_set_symlink_hybrid
145 This sets the mode used for handling symbolic links.
148 mode follows all symbolic links.
151 mode does not follow any symbolic links.
154 mode currently behaves identically to the
158 .Fn archive_read_disk_gname ,
159 .Fn archive_read_disk_uname
161 Returns a user or group name given a gid or uid value.
162 By default, these always return a NULL string.
164 .Fn archive_read_disk_set_gname_lookup ,
165 .Fn archive_read_disk_set_uname_lookup
167 These allow you to override the functions used for
168 user and group name lookups.
169 You may also provide a
171 pointer to a private data structure and a cleanup function for
173 The cleanup function will be invoked when the
175 object is destroyed or when new lookup functions are registered.
176 .It Fn archive_read_disk_set_standard_lookup
177 This convenience function installs a standard set of user
178 and group name lookup functions.
183 to convert ids to names, defaulting to NULL if the names cannot
185 These functions also implement a simple memory cache to reduce
186 the number of calls to
190 .It Fn archive_read_disk_entry_from_file
192 .Tn struct archive_entry
193 object with information about a particular file.
196 object must have already been created with
197 .Xr archive_entry_new 3
198 and at least one of the source path or path fields must already be set.
199 (If both are set, the source path will be used.)
201 Information is read from disk using the path name from the
202 .Tn struct archive_entry
204 If a file descriptor is provided, some information will be obtained using
205 that file descriptor, on platforms that support the appropriate
210 is provided, information from that structure will be used instead
211 of reading from the disk where appropriate.
212 This can provide performance benefits in scenarios where
214 information has already been read from the disk as a side effect
215 of some other operation.
216 (For example, directory traversal libraries often provide this information.)
218 Where necessary, user and group ids are converted to user and group names
219 using the currently registered lookup functions above.
220 This affects the file ownership fields and ACL values in the
221 .Tn struct archive_entry
224 More information about the
226 object and the overall design of the library can be found in the
230 The following illustrates basic usage of the library by
231 showing how to use it to copy an item on disk into an archive.
232 .Bd -literal -offset indent
234 file_to_archive(struct archive *a, const char *name)
239 struct archive_entry *entry;
242 ard = archive_read_disk_new();
243 archive_read_disk_set_standard_lookup(ard);
244 entry = archive_entry_new();
245 fd = open(name, O_RDONLY);
248 archive_entry_copy_pathname(entry, name);
249 archive_read_disk_entry_from_file(ard, entry, fd, NULL);
250 archive_write_header(a, entry);
251 while ((bytes_read = read(fd, buff, sizeof(buff))) > 0)
252 archive_write_data(a, buff, bytes_read);
253 archive_write_finish_entry(a);
254 archive_read_free(ard);
255 archive_entry_free(entry);
259 Most functions return
261 (zero) on success, or one of several negative
262 error codes for errors.
263 Specific error codes include:
265 for operations that might succeed if retried,
267 for unusual conditions that do not prevent further operations, and
269 for serious errors that make remaining operations impossible.
271 .Fn archive_read_disk_new
272 returns a pointer to a newly-allocated
274 object or NULL if the allocation failed for any reason.
276 .Fn archive_read_disk_gname
278 .Fn archive_read_disk_uname
281 pointers to the textual name or NULL if the lookup failed for any reason.
282 The returned pointer points to internal storage that
283 may be reused on the next call to either of these functions;
284 callers should copy the string if they need to continue accessing it.
287 Detailed error codes and textual descriptions are available from the
290 .Fn archive_error_string
296 .Xr archive_write 3 ,
297 .Xr archive_write_disk 3 ,
303 library first appeared in
306 .Nm archive_read_disk
307 interface was added to
309 and first appeared in
315 library was written by
316 .An Tim Kientzle Aq kientzle@FreeBSD.org .
320 user name and group name lookup functions are not the defaults because
324 are sometimes too large for particular applications.
325 The current design allows the application author to use a more
326 compact implementation when appropriate.
328 The full list of metadata read from disk by
329 .Fn archive_read_disk_entry_from_file
330 is necessarily system-dependent.
333 .Fn archive_read_disk_entry_from_file
334 function reads as much information as it can from disk.
335 Some method should be provided to limit this so that clients who
336 do not need ACLs, for instance, can avoid the extra work needed
337 to look up such information.
339 This API should provide a set of methods for walking a directory tree.
340 That would make it a direct parallel of the
343 When such methods are implemented, the
345 symbolic link mode will make sense.