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