1ARCHIVE_READ_DISK(3) BSD Library Functions Manual ARCHIVE_READ_DISK(3)
2
4 archive_read_disk_new, archive_read_disk_set_symlink_logical,
5 archive_read_disk_set_symlink_physical,
6 archive_read_disk_set_symlink_hybrid, archive_read_disk_entry_from_file,
7 archive_read_disk_gname, archive_read_disk_uname,
8 archive_read_disk_set_uname_lookup, archive_read_disk_set_gname_lookup,
9 archive_read_disk_set_standard_lookup, archive_read_close,
10 archive_read_finish, archive_read_free — 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_symlink_logical(struct archive *);
24 int
26 archive_read_disk_set_symlink_physical(struct archive *);
27 int
29 archive_read_disk_set_symlink_hybrid(struct archive *);
30 int
32 archive_read_disk_gname(struct archive *, gid_t);
33 int
35 archive_read_disk_uname(struct archive *, uid_t);
36 int
38 archive_read_disk_set_gname_lookup(struct archive *, void *,
39 const char *(*lookup)(void *, gid_t), void (*cleanup)(void *));
40 int
42 archive_read_disk_set_uname_lookup(struct archive *, void *,
43 const char *(*lookup)(void *, uid_t), void (*cleanup)(void *));
44 int
46 archive_read_disk_set_standard_lookup(struct archive *);
47 int
49 archive_read_disk_entry_from_file(struct archive *,
50 struct archive_entry *, int fd, const struct stat *);
51 int
53 archive_read_close(struct archive *);
54 int
56 archive_read_finish(struct archive *);
57 int
59 archive_read_free(struct archive *);
60
62 These functions provide an API for reading information about objects on
63 disk. In particular, they provide an interface for populating struct
64 archive_entry objects.
65 archive_read_disk_new()
67 Allocates and initializes a struct archive object suitable for
68 reading object information from disk.
69 archive_read_disk_set_symlink_logical(),
71 archive_read_disk_set_symlink_physical(),
72 archive_read_disk_set_symlink_hybrid()
73 This sets the mode used for handling symbolic links. The
74 “logical” mode follows all symbolic links. The “physical” mode
75 does not follow any symbolic links. The “hybrid” mode currently
76 behaves identically to the “logical” mode.
77 archive_read_disk_gname(), archive_read_disk_uname()
79 Returns a user or group name given a gid or uid value. By
80 default, these always return a NULL string.
81 archive_read_disk_set_gname_lookup(),
83 archive_read_disk_set_uname_lookup()
84 These allow you to override the functions used for user and group
85 name lookups. You may also provide a void * pointer to a private
86 data structure and a cleanup function for that data. The cleanup
87 function will be invoked when the struct archive object is
88 destroyed or when new lookup functions are registered.
89 archive_read_disk_set_standard_lookup()
91 This convenience function installs a standard set of user and
92 group name lookup functions. These functions use getpwuid(3) and
93 getgrgid(3) to convert ids to names, defaulting to NULL if the
94 names cannot be looked up. These functions also implement a sim‐
95 ple memory cache to reduce the number of calls to getpwuid(3) and
96 getgrgid(3).
97 archive_read_disk_entry_from_file()
99 Populates a struct archive_entry object with information about a
100 particular file. The archive_entry object must have already been
101 created with archive_entry_new(3) and at least one of the source
102 path or path fields must already be set. (If both are set, the
103 source path will be used.)
104 Information is read from disk using the path name from the struct
106 archive_entry object. If a file descriptor is provided, some
107 information will be obtained using that file descriptor, on plat‐
108 forms that support the appropriate system calls.
109 If a pointer to a struct stat is provided, information from that
111 structure will be used instead of reading from the disk where
112 appropriate. This can provide performance benefits in scenarios
113 where struct stat information has already been read from the disk
114 as a side effect of some other operation. (For example, direc‐
115 tory traversal libraries often provide this information.)
116 Where necessary, user and group ids are converted to user and
118 group names using the currently registered lookup functions
119 above. This affects the file ownership fields and ACL values in
120 the struct archive_entry object.
121 archive_read_close()
123 Does nothing for archive_read_disk handles.
124 archive_read_finish()
126 This is a deprecated synonym for archive_read_free().
127 archive_read_free()
129 Invokes archive_read_close() if it was not invoked manually, then
130 releases all resources.
131 More information about the struct archive object and the overall design
132 of the library can be found in the libarchive(3) overview.
133
135 The following illustrates basic usage of the library by showing how to
136 use it to copy an item on disk into an archive.
137 void
139 file_to_archive(struct archive *a, const char *name)
140 {
141 char buff[8192];
142 size_t bytes_read;
143 struct archive *ard;
144 struct archive_entry *entry;
145 int fd;
146 ard = archive_read_disk_new();
148 archive_read_disk_set_standard_lookup(ard);
149 entry = archive_entry_new();
150 fd = open(name, O_RDONLY);
151 if (fd < 0)
152 return;
153 archive_entry_copy_pathname(entry, name);
154 archive_read_disk_entry_from_file(ard, entry, fd, NULL);
155 archive_write_header(a, entry);
156 while ((bytes_read = read(fd, buff, sizeof(buff))) > 0)
157 archive_write_data(a, buff, bytes_read);
158 archive_write_finish_entry(a);
159 archive_read_free(ard);
160 archive_entry_free(entry);
161 }
162
164 Most functions return ARCHIVE_OK (zero) on success, or one of several
165 negative error codes for errors. Specific error codes include:
166 ARCHIVE_RETRY for operations that might succeed if retried, ARCHIVE_WARN
167 for unusual conditions that do not prevent further operations, and
168 ARCHIVE_FATAL for serious errors that make remaining operations impossi‐
169 ble.
170 archive_read_disk_new() returns a pointer to a newly-allocated struct
172 archive object or NULL if the allocation failed for any reason.
173 archive_read_disk_gname() and archive_read_disk_uname() return const char
175 * pointers to the textual name or NULL if the lookup failed for any rea‐
176 son. The returned pointer points to internal storage that may be reused
177 on the next call to either of these functions; callers should copy the
178 string if they need to continue accessing it.
179
181 Detailed error codes and textual descriptions are available from the
182 archive_errno() and archive_error_string() functions.
183
185 archive_read(3), archive_util(3), archive_write(3),
186 archive_write_disk(3), tar(1), libarchive(3)
187
189 The libarchive library first appeared in FreeBSD 5.3. The
190 archive_read_disk interface was added to libarchive 2.6 and first
191 appeared in FreeBSD 8.0.
192
194 The libarchive library was written by Tim Kientzle
195 <kientzle@FreeBSD.org>.
196
198 The “standard” user name and group name lookup functions are not the
199 defaults because getgrgid(3) and getpwuid(3) are sometimes too large for
200 particular applications. The current design allows the application
201 author to use a more compact implementation when appropriate.
202 The full list of metadata read from disk by
204 archive_read_disk_entry_from_file() is necessarily system-dependent.
205 The archive_read_disk_entry_from_file() function reads as much informa‐
207 tion as it can from disk. Some method should be provided to limit this
208 so that clients who do not need ACLs, for instance, can avoid the extra
209 work needed to look up such information.
210 This API should provide a set of methods for walking a directory tree.
212 That would make it a direct parallel of the archive_read(3) API. When
213 such methods are implemented, the “hybrid” symbolic link mode will make
214 sense.
215BSD February 2, 2012 BSD