1ARCHIVE_READ_DISK(3) BSD Library Functions Manual ARCHIVE_READ_DISK(3)
2
4 archive_read_disk_new, archive_read_disk_set_behavior,
5 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 — functions for reading objects
11 from disk
12
14 Streaming Archive Library (libarchive, -larchive)
15
17 #include <archive.h>
18 struct archive *
20 archive_read_disk_new(void);
21 int
23 archive_read_disk_set_behavior(struct archive *, int);
24 int
26 archive_read_disk_set_symlink_logical(struct archive *);
27 int
29 archive_read_disk_set_symlink_physical(struct archive *);
30 int
32 archive_read_disk_set_symlink_hybrid(struct archive *);
33 const char *
35 archive_read_disk_gname(struct archive *, gid_t);
36 const char *
38 archive_read_disk_uname(struct archive *, uid_t);
39 int
41 archive_read_disk_set_gname_lookup(struct archive *, void *,
42 const char *(*lookup)(void *, gid_t), void (*cleanup)(void *));
43 int
45 archive_read_disk_set_uname_lookup(struct archive *, void *,
46 const char *(*lookup)(void *, uid_t), void (*cleanup)(void *));
47 int
49 archive_read_disk_set_standard_lookup(struct archive *);
50 int
52 archive_read_disk_entry_from_file(struct archive *,
53 struct archive_entry *, int fd, const struct stat *);
54
56 These functions provide an API for reading information about objects on
57 disk. In particular, they provide an interface for populating struct
58 archive_entry objects.
59 archive_read_disk_new()
61 Allocates and initializes a struct archive object suitable for
62 reading object information from disk.
63 archive_read_disk_set_behavior()
65 Configures various behavior options when reading entries from
66 disk. The flags field consists of a bitwise OR of one or more of
67 the following values:
68 ARCHIVE_READDISK_HONOR_NODUMP
69 Skip files and directories with the nodump file attribute
70 (file flag) set. By default, the nodump file attribute
71 is ignored.
72 ARCHIVE_READDISK_MAC_COPYFILE
73 Mac OS X specific. Read metadata (ACLs and extended
74 attributes) with copyfile(3). By default, metadata is
75 read using copyfile(3).
76 ARCHIVE_READDISK_NO_ACL
77 Do not read Access Control Lists. By default, ACLs are
78 read from disk.
79 ARCHIVE_READDISK_NO_FFLAGS
80 Do not read file attributes (file flags). By default,
81 file attributes are read from disk. See chattr(1)
82 (Linux) or chflags(1) (FreeBSD, Mac OS X) for more infor‐
83 mation on file attributes.
84 ARCHIVE_READDISK_NO_TRAVERSE_MOUNTS
85 Do not traverse mount points. By default, mount points
86 are traversed.
87 ARCHIVE_READDISK_NO_XATTR
88 Do not read extended file attributes (xattrs). By
89 default, extended file attributes are read from disk.
90 See xattr(7) (Linux), xattr(2) (Mac OS X), or
91 getextattr(8) (FreeBSD) for more information on extended
92 file attributes.
93 ARCHIVE_READDISK_RESTORE_ATIME
94 Restore access time of traversed files. By default,
95 access time of traversed files is not restored.
96 archive_read_disk_set_symlink_logical(),
98 archive_read_disk_set_symlink_physical(),
99 archive_read_disk_set_symlink_hybrid()
100 This sets the mode used for handling symbolic links. The
101 “logical” mode follows all symbolic links. The “physical” mode
102 does not follow any symbolic links. The “hybrid” mode currently
103 behaves identically to the “logical” mode.
104 archive_read_disk_gname(), archive_read_disk_uname()
106 Returns a user or group name given a gid or uid value. By
107 default, these always return a NULL string.
108 archive_read_disk_set_gname_lookup(),
110 archive_read_disk_set_uname_lookup()
111 These allow you to override the functions used for user and group
112 name lookups. You may also provide a void * pointer to a private
113 data structure and a cleanup function for that data. The cleanup
114 function will be invoked when the struct archive object is
115 destroyed or when new lookup functions are registered.
116 archive_read_disk_set_standard_lookup()
118 This convenience function installs a standard set of user and
119 group name lookup functions. These functions use getpwuid(3) and
120 getgrgid(3) to convert ids to names, defaulting to NULL if the
121 names cannot be looked up. These functions also implement a sim‐
122 ple memory cache to reduce the number of calls to getpwuid(3) and
123 getgrgid(3).
124 archive_read_disk_entry_from_file()
126 Populates a struct archive_entry object with information about a
127 particular file. The archive_entry object must have already been
128 created with archive_entry_new(3) and at least one of the source
129 path or path fields must already be set. (If both are set, the
130 source path will be used.)
131 Information is read from disk using the path name from the struct
133 archive_entry object. If a file descriptor is provided, some
134 information will be obtained using that file descriptor, on plat‐
135 forms that support the appropriate system calls.
136 If a pointer to a struct stat is provided, information from that
138 structure will be used instead of reading from the disk where
139 appropriate. This can provide performance benefits in scenarios
140 where struct stat information has already been read from the disk
141 as a side effect of some other operation. (For example, direc‐
142 tory traversal libraries often provide this information.)
143 Where necessary, user and group ids are converted to user and
145 group names using the currently-registered lookup functions
146 above. This affects the file ownership fields and ACL values in
147 the struct archive_entry object.
148 More information about the struct archive object and the overall design
149 of the library can be found in the libarchive(3) overview.
150
152 The following illustrates basic usage of the library by showing how to
153 use it to copy an item on disk into an archive.
154 void
156 file_to_archive(struct archive *a, const char *name)
157 {
158 char buff[8192];
159 size_t bytes_read;
160 struct archive *ard;
161 struct archive_entry *entry;
162 int fd;
163 ard = archive_read_disk_new();
165 archive_read_disk_set_standard_lookup(ard);
166 entry = archive_entry_new();
167 fd = open(name, O_RDONLY);
168 if (fd < 0)
169 return;
170 archive_entry_copy_pathname(entry, name);
171 archive_read_disk_entry_from_file(ard, entry, fd, NULL);
172 archive_write_header(a, entry);
173 while ((bytes_read = read(fd, buff, sizeof(buff))) > 0)
174 archive_write_data(a, buff, bytes_read);
175 archive_write_finish_entry(a);
176 archive_read_free(ard);
177 archive_entry_free(entry);
178 }
179
181 Most functions return ARCHIVE_OK (zero) on success, or one of several
182 negative error codes for errors. Specific error codes include:
183 ARCHIVE_RETRY for operations that might succeed if retried, ARCHIVE_WARN
184 for unusual conditions that do not prevent further operations, and
185 ARCHIVE_FATAL for serious errors that make remaining operations impossi‐
186 ble.
187 archive_read_disk_new() returns a pointer to a newly-allocated struct
189 archive object or NULL if the allocation failed for any reason.
190 archive_read_disk_gname() and archive_read_disk_uname() return const char
192 * pointers to the textual name or NULL if the lookup failed for any rea‐
193 son. The returned pointer points to internal storage that may be reused
194 on the next call to either of these functions; callers should copy the
195 string if they need to continue accessing it.
196
198 Detailed error codes and textual descriptions are available from the
199 archive_errno() and archive_error_string() functions.
200
202 tar(1), archive_read(3), archive_util(3), archive_write(3),
203 archive_write_disk(3), libarchive(3)
204
206 The libarchive library first appeared in FreeBSD 5.3. The
207 archive_read_disk interface was added to libarchive 2.6 and first
208 appeared in FreeBSD 8.0.
209
211 The libarchive library was written by Tim Kientzle
212 <kientzle@FreeBSD.org>.
213
215 The “standard” user name and group name lookup functions are not the
216 defaults because getgrgid(3) and getpwuid(3) are sometimes too large for
217 particular applications. The current design allows the application
218 author to use a more compact implementation when appropriate.
219 The full list of metadata read from disk by
221 archive_read_disk_entry_from_file() is necessarily system-dependent.
222 The archive_read_disk_entry_from_file() function reads as much informa‐
224 tion as it can from disk. Some method should be provided to limit this
225 so that clients who do not need ACLs, for instance, can avoid the extra
226 work needed to look up such information.
227 This API should provide a set of methods for walking a directory tree.
229 That would make it a direct parallel of the archive_read(3) API. When
230 such methods are implemented, the “hybrid” symbolic link mode will make
231 sense.
232BSD April 3, 2017 BSD