1ARCHIVE_READ_DISK(3)     BSD Library Functions Manual     ARCHIVE_READ_DISK(3)
2

NAME

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

LIBRARY

14     Streaming Archive Library (libarchive, -larchive)
15

SYNOPSIS

17     #include <archive.h>
18
19     struct archive *
20     archive_read_disk_new(void);
21
22     int
23     archive_read_disk_set_behavior(struct archive *, int);
24
25     int
26     archive_read_disk_set_symlink_logical(struct archive *);
27
28     int
29     archive_read_disk_set_symlink_physical(struct archive *);
30
31     int
32     archive_read_disk_set_symlink_hybrid(struct archive *);
33
34     const char *
35     archive_read_disk_gname(struct archive *, gid_t);
36
37     const char *
38     archive_read_disk_uname(struct archive *, uid_t);
39
40     int
41     archive_read_disk_set_gname_lookup(struct archive *, void *,
42         const char *(*lookup)(void *, gid_t), void (*cleanup)(void *));
43
44     int
45     archive_read_disk_set_uname_lookup(struct archive *, void *,
46         const char *(*lookup)(void *, uid_t), void (*cleanup)(void *));
47
48     int
49     archive_read_disk_set_standard_lookup(struct archive *);
50
51     int
52     archive_read_disk_entry_from_file(struct archive *,
53         struct archive_entry *, int fd, const struct stat *);
54

DESCRIPTION

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
60     archive_read_disk_new()
61             Allocates and initializes a struct archive object suitable for
62             reading object information from disk.
63
64     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 atrribute
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 defaut, moint 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
97     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
105     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
109     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
117     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
125     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
132             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
137             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
144             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

EXAMPLE

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
155           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
164             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

RETURN VALUES

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
188     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
191     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

ERRORS

198     Detailed error codes and textual descriptions are available from the
199     archive_errno() and archive_error_string() functions.
200

SEE ALSO

202     archive_read(3), archive_util(3), archive_write(3),
203     archive_write_disk(3), tar(1), libarchive(3)
204

HISTORY

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

AUTHORS

211     The libarchive library was written by Tim Kientzle
212     <kientzle@FreeBSD.org>.
213

BUGS

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
220     The full list of metadata read from disk by
221     archive_read_disk_entry_from_file() is necessarily system-dependent.
222
223     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
228     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.
232
233BSD                              April 3, 2017                             BSD
Impressum