1ARCHIVE_READ_DISK(3) BSD Library Functions Manual ARCHIVE_READ_DISK(3)
2
4 archive_read_disk_new, archive_read_disk_open, archive_read_disk_open_w,
5 archive_read_disk_set_behavior, archive_read_disk_set_symlink_logical,
6 archive_read_disk_set_symlink_physical,
7 archive_read_disk_set_symlink_hybrid, archive_read_disk_entry_from_file,
8 archive_read_disk_gname, archive_read_disk_uname,
9 archive_read_disk_set_uname_lookup, archive_read_disk_set_gname_lookup,
10 archive_read_disk_set_standard_lookup, archive_read_disk_descend,
11 archive_read_disk_can_descend, archive_read_disk_current_filesystem,
12 archive_read_disk_current_filesystem_is_synthetic,
13 archive_read_disk_current_filesystem_is_remote,
14 archive_read_disk_set_matching,
15 archive_read_disk_set_metadata_filter_callback, — functions for reading
16 objects from disk
17
19 Streaming Archive Library (libarchive, -larchive)
20
22 #include <archive.h>
23 struct archive *
25 archive_read_disk_new(void);
26 int
28 archive_read_disk_open(struct archive *, const char *);
29 int
31 archive_read_disk_open_w(struct archive *, const wchar_t *);
32 int
34 archive_read_disk_set_behavior(struct archive *, int);
35 int
37 archive_read_disk_set_symlink_logical(struct archive *);
38 int
40 archive_read_disk_set_symlink_physical(struct archive *);
41 int
43 archive_read_disk_set_symlink_hybrid(struct archive *);
44 const char *
46 archive_read_disk_gname(struct archive *, gid_t);
47 const char *
49 archive_read_disk_uname(struct archive *, uid_t);
50 int
52 archive_read_disk_set_gname_lookup(struct archive *, void *,
53 const char *(*lookup)(void *, gid_t), void (*cleanup)(void *));
54 int
56 archive_read_disk_set_uname_lookup(struct archive *, void *,
57 const char *(*lookup)(void *, uid_t), void (*cleanup)(void *));
58 int
60 archive_read_disk_set_standard_lookup(struct archive *);
61 int
63 archive_read_disk_entry_from_file(struct archive *,
64 struct archive_entry *, int fd, const struct stat *);
65 int
67 archive_read_disk_descend(struct archive *);
68 int
70 archive_read_disk_can_descend(struct archive *);
71 int
73 archive_read_disk_current_filesystem(struct archive *);
74 int
76 archive_read_disk_current_filesystem_is_synthetic(struct archive *);
77 int
79 archive_read_disk_current_filesystem_is_remote(struct archive *);
80 int
82 archive_read_disk_set_matching(struct archive *, struct archive *,
83 void (*excluded_func)(struct archive *, void *, struct archive entry *),
84 void *);
85 int
87 archive_read_disk_set_metadata_filter_callback(struct archive *,
88 int (*metadata_filter_func)(struct archive *, void*, struct archive_entry *),
89 void *);
90
92 These functions provide an API for reading information about objects on
93 disk. In particular, they provide an interface for populating struct
94 archive_entry objects.
95 archive_read_disk_new()
97 Allocates and initializes a struct archive object suitable for
98 reading object information from disk.
99 archive_read_disk_open()
101 Opens the file or directory from the given path and prepares the
102 struct archive to read it from disk.
103 archive_read_disk_open_w()
105 Opens the file or directory from the given path as a wide charac‐
106 ter string and prepares the struct archive to read it from disk.
107 archive_read_disk_set_behavior()
109 Configures various behavior options when reading entries from
110 disk. The flags field consists of a bitwise OR of one or more of
111 the following values:
112 ARCHIVE_READDISK_HONOR_NODUMP
113 Skip files and directories with the nodump file attribute
114 (file flag) set. By default, the nodump file attribute
115 is ignored.
116 ARCHIVE_READDISK_MAC_COPYFILE
117 Mac OS X specific. Read metadata (ACLs and extended at‐
118 tributes) with copyfile(3). By default, metadata is read
119 using copyfile(3).
120 ARCHIVE_READDISK_NO_ACL
121 Do not read Access Control Lists. By default, ACLs are
122 read from disk.
123 ARCHIVE_READDISK_NO_FFLAGS
124 Do not read file attributes (file flags). By default,
125 file attributes are read from disk. See chattr(1)
126 (Linux) or chflags(1) (FreeBSD, Mac OS X) for more infor‐
127 mation on file attributes.
128 ARCHIVE_READDISK_NO_TRAVERSE_MOUNTS
129 Do not traverse mount points. By default, mount points
130 are traversed.
131 ARCHIVE_READDISK_NO_XATTR
132 Do not read extended file attributes (xattrs). By de‐
133 fault, extended file attributes are read from disk. See
134 xattr(7) (Linux), xattr(2) (Mac OS X), or getextattr(8)
135 (FreeBSD) for more information on extended file at‐
136 tributes.
137 ARCHIVE_READDISK_RESTORE_ATIME
138 Restore access time of traversed files. By default, ac‐
139 cess time of traversed files is not restored.
140 ARCHIVE_READDISK_NO_SPARSE
141 Do not read sparse file information. By default, sparse
142 file information is read from disk.
143 archive_read_disk_set_symlink_logical(),
145 archive_read_disk_set_symlink_physical(),
146 archive_read_disk_set_symlink_hybrid()
147 This sets the mode used for handling symbolic links. The
148 “logical” mode follows all symbolic links. The “physical” mode
149 does not follow any symbolic links. The “hybrid” mode currently
150 behaves identically to the “logical” mode.
151 archive_read_disk_gname(), archive_read_disk_uname()
153 Returns a user or group name given a gid or uid value. By de‐
154 fault, these always return a NULL string.
155 archive_read_disk_set_gname_lookup(),
157 archive_read_disk_set_uname_lookup()
158 These allow you to override the functions used for user and group
159 name lookups. You may also provide a void * pointer to a private
160 data structure and a cleanup function for that data. The cleanup
161 function will be invoked when the struct archive object is de‐
162 stroyed or when new lookup functions are registered.
163 archive_read_disk_set_standard_lookup()
165 This convenience function installs a standard set of user and
166 group name lookup functions. These functions use getpwuid(3) and
167 getgrgid(3) to convert ids to names, defaulting to NULL if the
168 names cannot be looked up. These functions also implement a sim‐
169 ple memory cache to reduce the number of calls to getpwuid(3) and
170 getgrgid(3).
171 archive_read_disk_entry_from_file()
173 Populates a struct archive_entry object with information about a
174 particular file. The archive_entry object must have already been
175 created with archive_entry_new(3) and at least one of the source
176 path or path fields must already be set. (If both are set, the
177 source path will be used.)
178 Information is read from disk using the path name from the struct
180 archive_entry object. If a file descriptor is provided, some in‐
181 formation will be obtained using that file descriptor, on plat‐
182 forms that support the appropriate system calls.
183 If a pointer to a struct stat is provided, information from that
185 structure will be used instead of reading from the disk where ap‐
186 propriate. This can provide performance benefits in scenarios
187 where struct stat information has already been read from the disk
188 as a side effect of some other operation. (For example, direc‐
189 tory traversal libraries often provide this information.)
190 Where necessary, user and group ids are converted to user and
192 group names using the currently-registered lookup functions
193 above. This affects the file ownership fields and ACL values in
194 the struct archive_entry object.
195 archive_read_disk_descend()
197 If the current entry can be descended, this function will mark
198 the directory as the next entry for archive_read_header(3) to
199 visit.
200 archive_read_disk_can_descend()
202 Returns 1 if the current entry is an unvisited directory and 0
203 otherwise.
204 archive_read_disk_current_filesystem()
206 Returns the index of the most recent filesystem entry that has
207 been visited through archive_read_disk
208 archive_read_disk_current_filesystem_is_synthetic()
210 Returns 1 if the current filesystem is a virtual filesystem. Re‐
211 turns 0 if the current filesystem is not a virtual filesystem.
212 Returns -1 if it is unknown.
213 archive_read_disk_current_filesystem_is_remote()
215 Returns 1 if the current filesystem is a remote filesystem. Re‐
216 turns 0 if the current filesystem is not a remote filesystem. Re‐
217 turns -1 if it is unknown.
218 archive_read_disk_set_matching()
220 Allows the caller to set struct archive *_ma to compare each en‐
221 try during archive_read_header(3) calls. If matched based on
222 calls to archive_match_path_excluded,
223 archive_match_time_excluded, or archive_match_owner_excluded,
224 then the callback function specified by the _excluded_func param‐
225 eter will execute. This function will recieve data provided to
226 the fourth parameter, void *_client_data.
227 archive_read_disk_set_metadata_filter_callback()
229 Allows the caller to set a callback function during calls to
230 archive_read_header(3) to filter out metadata for each entry. The
231 callback function recieves the struct archive object, void* cus‐
232 tom filter data, and the struct archive_entry. If the callback
233 function returns an error, ARCHIVE_RETRY will be returned and the
234 entry will not be further processed.
235 More information about the struct archive object and the overall design
236 of the library can be found in the libarchive(3) overview.
237
239 The following illustrates basic usage of the library by showing how to
240 use it to copy an item on disk into an archive.
241 void
243 file_to_archive(struct archive *a, const char *name)
244 {
245 char buff[8192];
246 size_t bytes_read;
247 struct archive *ard;
248 struct archive_entry *entry;
249 int fd;
250 ard = archive_read_disk_new();
252 archive_read_disk_set_standard_lookup(ard);
253 entry = archive_entry_new();
254 fd = open(name, O_RDONLY);
255 if (fd < 0)
256 return;
257 archive_entry_copy_pathname(entry, name);
258 archive_read_disk_entry_from_file(ard, entry, fd, NULL);
259 archive_write_header(a, entry);
260 while ((bytes_read = read(fd, buff, sizeof(buff))) > 0)
261 archive_write_data(a, buff, bytes_read);
262 archive_write_finish_entry(a);
263 archive_read_free(ard);
264 archive_entry_free(entry);
265 }
266
268 Most functions return ARCHIVE_OK (zero) on success, or one of several
269 negative error codes for errors. Specific error codes include:
270 ARCHIVE_RETRY for operations that might succeed if retried, ARCHIVE_WARN
271 for unusual conditions that do not prevent further operations, and
272 ARCHIVE_FATAL for serious errors that make remaining operations impossi‐
273 ble.
274 archive_read_disk_new() returns a pointer to a newly-allocated struct
276 archive object or NULL if the allocation failed for any reason.
277 archive_read_disk_gname() and archive_read_disk_uname() return const char
279 * pointers to the textual name or NULL if the lookup failed for any rea‐
280 son. The returned pointer points to internal storage that may be reused
281 on the next call to either of these functions; callers should copy the
282 string if they need to continue accessing it.
283
285 Detailed error codes and textual descriptions are available from the
286 archive_errno() and archive_error_string() functions.
287
289 tar(1), archive_read(3), archive_util(3), archive_write(3),
290 archive_write_disk(3), libarchive(3)
291
293 The libarchive library first appeared in FreeBSD 5.3. The
294 archive_read_disk interface was added to libarchive 2.6 and first ap‐
295 peared in FreeBSD 8.0.
296
298 The libarchive library was written by Tim Kientzle
299 <kientzle@FreeBSD.org>.
300
302 The “standard” user name and group name lookup functions are not the de‐
303 faults because getgrgid(3) and getpwuid(3) are sometimes too large for
304 particular applications. The current design allows the application au‐
305 thor to use a more compact implementation when appropriate.
306 The full list of metadata read from disk by
308 archive_read_disk_entry_from_file() is necessarily system-dependent.
309 The archive_read_disk_entry_from_file() function reads as much informa‐
311 tion as it can from disk. Some method should be provided to limit this
312 so that clients who do not need ACLs, for instance, can avoid the extra
313 work needed to look up such information.
314 This API should provide a set of methods for walking a directory tree.
316 That would make it a direct parallel of the archive_read(3) API. When
317 such methods are implemented, the “hybrid” symbolic link mode will make
318 sense.
319BSD April 3, 2017 BSD