ARCHIVE_READ_DISK(3) Library Functions Manual ARCHIVE_READ_DISK(3)
NAME
archive_read_disk_new, archive_read_disk_open, archive_read_disk_open_w, archive_read_disk_set_behavior, archive_read_disk_set_symlink_logical, archive_read_disk_set_symlink_physical, archive_read_disk_set_symlink_hybrid, archive_read_disk_entry_from_file, archive_read_disk_gname, archive_read_disk_uname, archive_read_disk_set_uname_lookup, archive_read_disk_set_gname_lookup, archive_read_disk_set_standard_lookup, archive_read_disk_descend, archive_read_disk_can_descend, archive_read_disk_current_filesystem, archive_read_disk_current_filesystem_is_synthetic, archive_read_disk_current_filesystem_is_remote, archive_read_disk_set_matching, archive_read_disk_set_metadata_filter_callback, — functions for reading objects from disk
LIBRARY
Streaming Archive Library (libarchive, -larchive)
SYNOPSIS
#include <archive.h>
struct archive *
archive_read_disk_new(void);
int
archive_read_disk_open(struct archive *, const char *);
int
archive_read_disk_open_w(struct archive *, const wchar_t *);
int
archive_read_disk_set_behavior(struct archive *, int);
int
archive_read_disk_set_symlink_logical(struct archive *);
int
archive_read_disk_set_symlink_physical(struct archive *);
int
archive_read_disk_set_symlink_hybrid(struct archive *);
const char *
archive_read_disk_gname(struct archive *, gid_t);
const char *
archive_read_disk_uname(struct archive *, uid_t);
int
archive_read_disk_set_gname_lookup(struct archive *, void *, const char *(*lookup)(void *, gid_t), void (*cleanup)(void *));
int
archive_read_disk_set_uname_lookup(struct archive *, void *, const char *(*lookup)(void *, uid_t), void (*cleanup)(void *));
int
archive_read_disk_set_standard_lookup(struct archive *);
int
archive_read_disk_entry_from_file(struct archive *, struct archive_entry *, int fd, const struct stat *);
int
archive_read_disk_descend(struct archive *);
int
archive_read_disk_can_descend(struct archive *);
int
archive_read_disk_current_filesystem(struct archive *);
int
archive_read_disk_current_filesystem_is_synthetic(struct archive *);
int
archive_read_disk_current_filesystem_is_remote(struct archive *);
int
archive_read_disk_set_matching(struct archive *, struct archive *, void (*excluded_func)(struct archive *, void *, struct archive entry *), void *);
int
archive_read_disk_set_metadata_filter_callback(struct archive *, int (*metadata_filter_func)(struct archive *, void*, struct archive_entry *), void *);
DESCRIPTION
These functions provide an API for reading information about objects on disk. In particular, they provide an interface for populating struct archive_entry objects.
archive_read_disk_new()
Allocates and initializes a struct archive object suitable for reading object information from disk.
archive_read_disk_open()
Opens the file or directory from the given path and prepares the struct archive to read it from disk.
archive_read_disk_open_w()
Opens the file or directory from the given path as a wide character string and prepares the struct archive to read it from disk.
archive_read_disk_set_behavior()
Configures various behavior options when reading entries from disk. The flags field consists of a bitwise OR of one or more of the following values:
ARCHIVE_READDISK_HONOR_NODUMP
Skip files and directories with the nodump file attribute (file flag) set. By default, the nodump file attribute is ignored.
ARCHIVE_READDISK_MAC_COPYFILE
Mac OS X specific. Read metadata (ACLs and extended attributes) with copyfile(3). By default, metadata is read using copyfile(3).
ARCHIVE_READDISK_NO_ACL
Do not read Access Control Lists. By default, ACLs are read from disk.
ARCHIVE_READDISK_NO_FFLAGS
Do not read file attributes (file flags). By default, file attributes are read from disk. See chattr(1) (Linux) or chflags(1) (FreeBSD, Mac OS X) for more information on file attributes.
ARCHIVE_READDISK_NO_TRAVERSE_MOUNTS
Do not traverse mount points. By default, mount points are traversed.
ARCHIVE_READDISK_NO_XATTR
Do not read extended file attributes (xattrs). By default, extended file attributes are read from disk. See xattr(7) (Linux), xattr(2) (Mac OS X), or getextattr(8) (FreeBSD) for more information on extended file attributes.
ARCHIVE_READDISK_RESTORE_ATIME
Restore access time of traversed files. By default, access time of traversed files is not restored.
ARCHIVE_READDISK_NO_SPARSE
Do not read sparse file information. By default, sparse file information is read from disk.
archive_read_disk_set_symlink_logical(), archive_read_disk_set_symlink_physical(), archive_read_disk_set_symlink_hybrid()
This sets the mode used for handling symbolic links. The “logical” mode follows all symbolic links. The “physical” mode does not follow any symbolic links. The “hybrid” mode currently behaves identically to the “logical” mode.
archive_read_disk_gname(), archive_read_disk_uname()
Returns a user or group name given a gid or uid value. By default, these always return a NULL string.
archive_read_disk_set_gname_lookup(), archive_read_disk_set_uname_lookup()
These allow you to override the functions used for user and group name lookups. You may also provide a void * pointer to a private data structure and a cleanup function for that data. The cleanup function will be invoked when the struct archive object is destroyed or when new lookup functions are registered.
archive_read_disk_set_standard_lookup()
This convenience function installs a standard set of user and group name lookup functions. These functions use getpwuid(3) and getgrgid(3) to convert ids to names, defaulting to NULL if the names cannot be looked up. These functions also implement a simple memory cache to reduce the number of calls to getpwuid(3) and getgrgid(3).
archive_read_disk_entry_from_file()
Populates a struct archive_entry object with information about a particular file. The archive_entry object must have already been created with archive_entry_new(3) and at least one of the source path or path fields must already be set. (If both are set, the source path will be used.)
Information is read from disk using the path name from the struct archive_entry object. If a file descriptor is provided, some information will be obtained using that file descriptor, on platforms that support the appropriate system calls.
If a pointer to a struct stat is provided, information from that structure will be used instead of reading from the disk where appropriate. This can provide performance benefits in scenarios where struct stat information has already been read from the disk as a side effect of some other operation. (For example, directory traversal libraries often provide this information.)
Where necessary, user and group ids are converted to user and group names using the currently-registered lookup functions above. This affects the file ownership fields and ACL values in the struct archive_entry object.
archive_read_disk_descend()
If the current entry can be descended, this function will mark the directory as the next entry for archive_read_header(3) to visit.
archive_read_disk_can_descend()
Returns 1 if the current entry is an unvisited directory and 0 otherwise.
archive_read_disk_current_filesystem()
Returns the index of the most recent filesystem entry that has been visited through archive_read_disk
archive_read_disk_current_filesystem_is_synthetic()
Returns 1 if the current filesystem is a virtual filesystem. Returns 0 if the current filesystem is not a virtual filesystem. Returns -1 if it is unknown.
archive_read_disk_current_filesystem_is_remote()
Returns 1 if the current filesystem is a remote filesystem. Returns 0 if the current filesystem is not a remote filesystem. Returns -1 if it is unknown.
archive_read_disk_set_matching()
Allows the caller to set struct archive *_ma to compare each entry during archive_read_header(3) calls. If matched based on calls to archive_match_path_excluded, archive_match_time_excluded, or archive_match_owner_excluded, then the callback function specified by the _excluded_func parameter will execute. This function will receive data provided to the fourth parameter, void *_client_data.
archive_read_disk_set_metadata_filter_callback()
Allows the caller to set a callback function during calls to archive_read_header(3) to filter out metadata for each entry. The callback function receives the struct archive object, void* custom filter data, and the struct archive_entry. If the callback function returns an error, ARCHIVE_RETRY will be returned and the entry will not be further processed.
More information about the struct archive object and the overall design of the library can be found in the libarchive(3) overview.
EXAMPLES
The following illustrates basic usage of the library by showing how to use it to copy an item on disk into an archive.
void
file_to_archive(struct archive *a, const char *name)
{
char buff[8192];
size_t bytes_read;
struct archive *ard;
struct archive_entry *entry;
int fd;
ard =
archive_read_disk_new();
archive_read_disk_set_standard_lookup(ard);
entry = archive_entry_new();
fd = open(name, O_RDONLY);
if (fd < 0)
return;
archive_entry_copy_pathname(entry, name);
archive_read_disk_entry_from_file(ard, entry, fd, NULL);
archive_write_header(a, entry);
while ((bytes_read = read(fd, buff, sizeof(buff))) > 0)
archive_write_data(a, buff, bytes_read);
archive_write_finish_entry(a);
archive_read_free(ard);
archive_entry_free(entry);
}
RETURN VALUES
Most functions return ARCHIVE_OK (zero) on success, or one of several negative error codes for errors. Specific error codes include: ARCHIVE_RETRY for operations that might succeed if retried, ARCHIVE_WARN for unusual conditions that do not prevent further operations, and ARCHIVE_FATAL for serious errors that make remaining operations impossible.
archive_read_disk_new() returns a pointer to a newly-allocated struct archive object or NULL if the allocation failed for any reason.
archive_read_disk_gname() and archive_read_disk_uname() return const char * pointers to the textual name or NULL if the lookup failed for any reason. The returned pointer points to internal storage that may be reused on the next call to either of these functions; callers should copy the string if they need to continue accessing it.
ERRORS
Detailed error codes and textual descriptions are available from the archive_errno() and archive_error_string() functions.
SEE ALSO
tar(1), archive_read(3), archive_util(3), archive_write(3), archive_write_disk(3), libarchive(3)
HISTORY
The libarchive library first appeared in FreeBSD 5.3. The archive_read_disk interface was added to libarchive 2.6 and first appeared in FreeBSD 8.0.
AUTHORS
The libarchive library was written by Tim Kientzle <kientzle@@FreeBSD.org>.
BUGS
The “standard” user name and group name lookup functions are not the defaults because getgrgid(3) and getpwuid(3) are sometimes too large for particular applications. The current design allows the application author to use a more compact implementation when appropriate.
The full list of metadata read from disk by archive_read_disk_entry_from_file() is necessarily system-dependent.
The archive_read_disk_entry_from_file() function reads as much information as it can from disk. Some method should be provided to limit this so that clients who do not need ACLs, for instance, can avoid the extra work needed to look up such information.
This API should provide a set of methods for walking a directory tree. That would make it a direct parallel of the archive_read(3) API. When such methods are implemented, the “hybrid” symbolic link mode will make sense. Debian April 3, 2017 ARCHIVE_READ_DISK(3)
ARCHIVE_READ_DISK(3) BSD Library Functions Manual ARCHIVE_READ_DISK(3)
d28 17 a44 21archive_read_disk_new, archive_read_disk_open, archive_read_disk_open_w, archive_read_disk_set_behavior, archive_read_disk_set_symlink_logical, archive_read_disk_set_symlink_physical, archive_read_disk_set_symlink_hybrid, archive_read_disk_entry_from_file, archive_read_disk_gname, archive_read_disk_uname, archive_read_disk_set_uname_lookup, archive_read_disk_set_gname_lookup, archive_read_disk_set_standard_lookup, archive_read_disk_descend, archive_read_disk_can_descend, archive_read_disk_current_filesystem, archive_read_disk_current_filesystem_is_synthetic, archive_read_disk_current_filesystem_is_remote, archive_read_disk_set_matching, archive_read_disk_set_metadata_filter_callback, — functions for reading objects from disk
d48 1 a48 1Streaming Archive Library d53 1 a53 1
#include d56 1 a56 1
struct d60 1 a60 1
archive_read_disk_new(void);
d62 1 a62 1int
d65 1 a65 1archive_read_disk_open(struct archive *, d68 1 a68 1
int
d71 1 a71 1archive_read_disk_open_w(struct archive *, d74 1 a74 1
int
d77 1 a77 1archive_read_disk_set_behavior(struct archive *, d80 1 a80 1
int
d83 1 a83 1archive_read_disk_set_symlink_logical(struct archive *);
d85 1 a85 1int
d88 1 a88 1archive_read_disk_set_symlink_physical(struct archive *);
d90 1 a90 1int
d93 1 a93 1archive_read_disk_set_symlink_hybrid(struct archive *);
d95 1 a95 1const char d99 1 a99 1
archive_read_disk_gname(struct archive *, d102 1 a102 1
const char d106 1 a106 1
archive_read_disk_uname(struct archive *, d109 1 a109 1
int
d117 1 a117 1int
d125 1 a125 1int
d128 1 a128 1archive_read_disk_set_standard_lookup(struct archive *);
d130 1 a130 1int
d137 1 a137 1int
d140 1 a140 1archive_read_disk_descend(struct archive *);
d142 1 a142 1int
d145 1 a145 1archive_read_disk_can_descend(struct archive *);
d147 1 a147 1int
d150 1 a150 1archive_read_disk_current_filesystem(struct archive *);
d152 1 a152 1int
d155 1 a155 1archive_read_disk_current_filesystem_is_synthetic(struct archive *);
d157 1 a157 1int
d160 1 a160 1archive_read_disk_current_filesystem_is_remote(struct archive *);
d162 1 a162 1int
d170 1 a170 1int
d179 1 a179 1These functions provide an API d187 1 a187 1
Allocates and initializes a d194 1 a194 1
Opens the file or directory d201 1 a201 1
Opens the file or directory d208 1 a208 1
Configures various behavior d215 1 a215 1
Skip files and directories with d221 4 a224 3
Mac OS X specific. Read metadata (ACLs and extended attributes) with copyfile(3). By default, metadata is read using copyfile(3).
d228 1 a228 1Do not read Access Control d233 1 a233 1
Do not read file attributes d235 3 a237 2 disk. See chattr(1) (Linux) or chflags(1) (FreeBSD, Mac OS X) for more information on file attributes.
d241 1 a241 1Do not traverse mount points. d246 1 a246 1
Do not read extended file d248 4 a251 3 are read from disk. See xattr(7) (Linux), xattr(2) (Mac OS X), or getextattr(8) (FreeBSD) for more information on extended file attributes.
d255 1 a255 1Restore access time of d261 1 a261 1
Do not read sparse file d270 1 a270 1
This sets the mode used for d281 1 a281 1
Returns a user or group name d289 1 a289 1
These allow you to override the d299 1 a299 1
This convenience function d301 5 a305 5 functions. These functions use getpwuid(3) and getgrgid(3) to convert ids to names, defaulting to NULL if the names cannot be looked up. These functions also implement a simple memory cache to reduce the number of calls to getpwuid(3) and getgrgid(3).
d310 1 a310 1Populates a struct d313 3 a315 3 created with archive_entry_new(3) and at least one of the source path or path fields must already be set. (If both are set, the source path will be used.)
d317 1 a317 1Information is d323 1 a323 1
If a pointer to d332 1 a332 1
Where d341 1 a341 1
If the current entry can be d343 1 a343 1 entry for archive_read_header(3) to visit.
d348 1 a348 1Returns 1 if the current entry d354 1 a354 1
Returns the index of the most d361 1 a361 1
Returns 1 if the current d369 1 a369 1
Returns 1 if the current d377 1 a377 1
Allows the caller to set struct d379 3 a381 2 archive_read_header(3) calls. If matched based on calls to archive_match_path_excluded, archive_match_time_excluded, or d390 8 a397 7
Allows the caller to set a callback function during calls to archive_read_header(3) to filter out metadata for each entry. The callback function receives the struct archive object, void* custom filter data, and the struct archive_entry. If the callback function returns an error, ARCHIVE_RETRY will be returned and the entry will not be further processed.
d399 1 a399 1More information about the d401 2 a402 1 library can be found in the libarchive(3) overview.
d406 1 a406 1The following illustrates basic d410 1 a410 1
void
d419 1
a419 1
ard = d440 1 a440 1
Most functions return d450 1 a450 1
archive_read_disk_new() d455 1 a455 1
archive_read_disk_gname() d465 1 a465 1
Detailed error codes and textual d471 4 a474 3
tar(1), archive_read(3), archive_util(3), archive_write(3), archive_write_disk(3), libarchive(3)
d478 1 a478 1The libarchive library d486 1 a486 1
The libarchive library d492 1 a492 1
The “standard” user d494 4 a497 4 because getgrgid(3) and getpwuid(3) are sometimes too large for particular applications. The current design allows the application author to use a more compact implementation when appropriate.
d499 1 a499 1The full list of d504 1 a504 1
The d511 1 a511 1
This API should d513 5 a517 6 would make it a direct parallel of the archive_read(3) API. When such methods are implemented, the “hybrid” symbolic link mode will make sense.
BSD April 3, 2017 BSD
@ 1.11 log @libarchive: updated to 3.7.4 Libarchive 3.7.4 is a bugfix and security release Security fixes: rar: Fix OOB in rar e8 filter (CVE-2024-26256) zip: Fix out of boundary access Important bugfixes: 7zip: Limit amount of properties bsdtar: Fix error handling around strtol() usages passphrase: Improve newline handling on Windows passphrase: Never allow empty passwords rar: Fix "File CRC Error" when extracting specific rar4 archives xar: Avoid infinite link loop zip: Update AppleDouble support for directories zstd: Implement core detection @ text @d2 1 a2 1 @ 1.10 log @libarchive: updated to 3.7.3 Libarchive 3.7.3 is a feature, security and bugfix release. New features: PCRE2 support add trailing letter b to bsdtar(1) substitute pattern add support for long options "--group" and "--owner" to tar(1) Security fixes: Fix possible vulnerability in tar error reporting introduced in f27c173 Important bugfixes: ISO9660: preserve the natural order of links rar5: fix decoding unicode filenames on Windows rar5: fix infinite loop if during rar5 decompression the last block produced no data xz filter: fix incorrect eof at the end of an lzip member zip: fix end-of-data marker processing when decompressing zip archives multiple bsdunzip(1) fixes filetime truncation fix on Windows @ text @d2 1 a2 1 d384 1 a384 1 function will recieve data provided to the fourth parameter, d393 1 a393 1 recieves the struct archive object, void* custom filter @ 1.9 log @libarchive: updated to 3.7.2 Libarchive 3.7.2 is a security, bugfix and feature release. Security fixes: Multiple vulnerabilities have been fixed in the PAX writer (1b4e0d0) Important bugfixes: bsdunzip(1) now correctly handles arguments following an -x after the zipfile New features: bsdunzip(1) now supports the "--version" flag 7-zip reader now translates Windows permissions into UNIX permissions uudecode filter in raw mode now supports file name and file mode zstd filter now supports the "long" write option Libarchive 3.7.1 is a security, feature and bugfix release. Security fixes: SEGV and stack buffer overflow in verbose mode of cpio Feature updates: bsdunzip updated to match latest upstream code Important bugfixes: miscellaneous functional bugfixes build fixes on multiple platforms Libarchive 3.7.0 is a feature and bugfix release. New features: bsdunzip: new tool ported from FreeBSD drop-in replacement for Info-ZIP unzip, not yet ported for Windows 7zip reader: support for Zstandard compression 7zip reader: support for ARM64 filter zstd filter: support for multi-frame zstd archives Other notable bugfixes and improvements: pax: fix year 2038 problem on platforms with 64-bit time_t Windows: Universal Windows Platform (UWP) fixes and improvements Windows: bcrypt usage fixes and improvements Windows: time function usage fixes and improvements @ text @d2 1 a2 1 @ 1.8 log @libarchive: Update to 3.4.3 Libarchive 3.4.3 is a feature and bugfix release. New features: support for pzstd compressed files (#1357) support for RHT.security.selinux tar extended attribute (#1348) Important bugfixes: various zstd fixes and improvements (#1342 #1352 #1359) child process handling fixes (#1372) Libarchive 3.4.2 is a feature and security release. New features: support for atomic file extraction (bsdtar -x --safe-writes) (#1289) support for mbed TLS (PolarSSL) (#1301) Important bugfixes: security fixes in RAR5 reader (#1280 #1326) compression buffer fix in XAR writer (#1317) fix uname and gname longer than 32 characters in PAX writer (#1319) fix segfault when archiving hard links in ISO9660 and XAR writers (#1325) fix support for extracting 7z archive entries with Delta filter (#987) Libarchive 3.4.1 is a feature and security release. New features: Unicode filename support for reading lha/lzh archives New pax write option "xattrhdr" Important bugfixes: security fixes in wide string processing (#1276 #1298) security fixes in RAR5 reader (#1212 #1217 #1296) security fixes and optimizations to write filter logic (#351) security fix related to use of readlink(2) (1dae5a5) sparse file handling fixes (#1218 #1260) Thanks to all contributors and bug reporters. Special thanks to Christos Zoulas (@@zoulasc) from NetBSD for the atomic file extraction feature. @ text @d1 2 a2 2 d29 2 d40 9 a48 2 archive_read_disk_set_standard_lookup — functions for reading objects from disk d69 12 d141 40 d196 14 d260 6 d272 5 a276 7 handling symbolic links. The ’’logical’’ mode follows all symbolic links. The ’’physical’’ mode does not follow any symbolic links. The ’’hybrid’’ mode currently behaves identically to the ’’logical’’ mode. d339 59 d489 4 a492 5The ’’standard’’ user name and group name lookup functions are not the defaults because getgrgid(3) and getpwuid(3) are sometimes too large for particular applications. The current design allows the d511 2 a512 3 When such methods are implemented, the ’’hybrid’’ symbolic link mode will make sense.
@ 1.7 log @Update for libarchive-3.4.0: - improvements for Android APK and JAR archives - better support for non-recursive list and extract - tar --exclude-vcs support - fixes for file attributes and flags handling - zipx support - rar 5.0 reader @ text @d1 2 a2 2 d146 1 a146 1 nodump file atrribute is ignored. d169 1 a169 1 By defaut, moint points are traversed. d191 7 a197 5 handling symbolic links. The “logical” mode follows all symbolic links. The “physical” mode does not follow any symbolic links. The “hybrid” mode currently behaves identically to the “logical” mode. d256 1 a256 1 group names using the currently registered lookup functions d264 1 a264 1EXAMPLE
d331 1 a331 1archive_read(3), d333 1 a333 1 tar(1), libarchive(3)
d351 5 a355 4The “standard” user name and group name lookup functions are not the defaults because getgrgid(3) and getpwuid(3) are sometimes too large for particular applications. The current design allows the d374 3 a376 2 When such methods are implemented, the “hybrid” symbolic link mode will make sense.
@ 1.6 log @libarchive: updated to 3.3.3 libarchive 3.3.3: Avoid super-linear slowdown on malformed mtree files Many fixes for building with Visual Studio NO_OVERWRITE doesn't change existing directory attributes New support for Zstandard read and write filters @ text @d1 2 a2 2 d191 5 a195 7 handling symbolic links. The ’’logical’’ mode follows all symbolic links. The ’’physical’’ mode does not follow any symbolic links. The ’’hybrid’’ mode currently behaves identically to the ’’logical’’ mode. d349 4 a352 5The ’’standard’’ user name and group name lookup functions are not the defaults because getgrgid(3) and getpwuid(3) are sometimes too large for particular applications. The current design allows the d371 2 a372 3 When such methods are implemented, the ’’hybrid’’ symbolic link mode will make sense.
@ 1.5 log @Merge for libarchive-3.3.2. @ text @d2 1 a2 1 @ 1.4 log @Merge libarchive-3.3.1. @ text @d2 1 a2 1 d29 1 d38 2 a39 4 archive_read_disk_set_standard_lookup, archive_read_close, archive_read_finish, archive_read_free — functions for reading objects from disk d60 6 d120 23 a142 1int
d144 3 d148 1 a148 1archive_read_close(struct archive *);
d150 3 a152 1int
d154 1 d156 2 a157 1archive_read_finish(struct archive *);
d159 1 a159 1int
d161 4 d166 1 a166 1archive_read_free(struct archive *);
d168 2 a169 1DESCRIPTION
d171 1 a171 4These functions provide an API for reading information about objects on disk. In particular, they provide an interface for populating struct archive_entry objects.
d173 5 d179 1 a179 1archive_read_disk_new()
d181 3 a183 3Allocates and initializes a struct archive object suitable for reading object information from disk.
d192 2 a193 2 ‘‘logical’’ mode follows all symbolic links. The ‘‘physical’’ d195 2 a196 2 ‘‘hybrid’’ mode currently behaves identically to the ‘‘logical’’ a259 17archive_read_close()
Does nothing for archive_read_disk handles.
archive_read_finish()
This is a deprecated synonym for archive_read_free().
archive_read_free()
Invokes archive_read_close() if it was not invoked manually, then releases all resources.
d352 1 a352 1 ‘‘standard’’ user name and group d375 1 a375 1 ‘‘hybrid’’ symbolic link mode will d379 1 a379 1 December 30, 2016 BSD @ 1.3 log @Update for libarchive 3.2.1. @ text @d2 1 a2 1 d73 2 a74 1int
d80 2 a81 1int
d151 2 a152 2 ’’logical’’ mode follows all symbolic links. The ’’physical’’ d154 2 a155 2 ’’hybrid’’ mode currently behaves identically to the ’’logical’’ d328 1 a328 1 ’’standard’’ user name and group d351 1 a351 1 ’’hybrid’’ symbolic link mode will d355 1 a355 1 February 2, 2012 BSD @ 1.2 log @Changes 3.1.2: This is a maintenance update to fix issues with the new RAR seeking feature. This new release also contains fixes for build failures when building libarchive using Visual Studio 2012 and MinGW. @ text @d1 2 a2 2 d320 2 a321 2 was written by Tim Kientzle ⟨ kientzle@@FreeBSD.org⟩ . @ 1.1 log @Initial revision @ text @d1 2 a2 2 d11 4 a14 3 p { margin-top: 0; margin-bottom: 0; } pre { margin-top: 0; margin-bottom: 0; } table { margin-top: 0; margin-bottom: 0; } d23 2 a24 2archive_read_disk(3) FreeBSD Library Functions Manual archive_read_disk(3)
d26 1 a26 1NAME
d28 1 a28 1archive_read_disk_new, d38 3 a40 2 archive_read_close, archive_read_finish — functions for reading objects from disk
d42 1 d44 2 a45 1SYNOPSIS
d47 3 a49 1#include d52 1 a52 1
struct d56 1 a56 1
archive_read_disk_new(void);
d58 1 a58 1int
d61 1 a61 1archive_read_disk_set_symlink_logical(struct archive *);
d63 1 a63 1int
d66 1 a66 1archive_read_disk_set_symlink_physical(struct archive *);
d68 1 a68 1int
d71 1 a71 1archive_read_disk_set_symlink_hybrid(struct archive *);
d73 1 a73 1int
d76 1 a76 1archive_read_disk_gname(struct archive *, d79 1 a79 1
int
d82 1 a82 1archive_read_disk_uname(struct archive *, d85 1 a85 1
int
d88 1 a88 1archive_read_disk_set_gname_lookup(struct archive *, d93 1 a93 1
int
d96 1 a96 1archive_read_disk_set_uname_lookup(struct archive *, d101 1 a101 1
int
d104 1 a104 1archive_read_disk_set_standard_lookup(struct archive *);
d106 1 a106 1int
d109 1 a109 1archive_read_disk_entry_from_file(struct archive *, d113 2 a114 1
int
d116 1 d118 1 a118 1archive_read_close(struct archive *);
a119 1int
d121 1 d123 1 a123 1archive_read_finish(struct archive *);
d126 1 a126 1DESCRIPTION
d128 3 a130 1These functions provide an API d136 1 a136 1
archive_read_disk_new()
d138 1 a138 1Allocates and initializes a d143 1 a143 1
archive_read_disk_set_symlink_logical(), d147 1 a147 1
This sets the mode used for d149 2 a150 2 ‘‘logical’’ mode follows all symbolic links. The ‘‘physical’’ d152 2 a153 2 ‘‘hybrid’’ mode currently behaves identically to the ‘‘logical’’ d157 1 a157 1
archive_read_disk_gname(), d160 1 a160 1
Returns a user or group name d165 1 a165 1
archive_read_disk_set_gname_lookup(), d168 1 a168 1
These allow you to override the d176 1 a176 1
archive_read_disk_set_standard_lookup()
d178 1 a178 1This convenience function d180 5 a184 5 functions. These functions use getpwid(3) and getgrid(3) to convert ids to names, defaulting to NULL if the names cannot be looked up. These functions also implement a simple memory cache to reduce the number of calls to getpwid(3) and getgrid(3).
d187 1 a187 1archive_read_disk_entry_from_file()
d189 1 a189 1Populates a struct d196 1 a196 1
Information is d202 1 a202 1
If a pointer to d211 1 a211 1
Where d217 4 a221 1
archive_read_close()
d223 1 a223 2This currently does nothing.
d225 2 d228 1 a228 1archive_write_finish()
d230 2 a231 2Invokes archive_write_close() if it was not invoked manually, d234 1 a234 1
More information about the d238 1 a238 1
EXAMPLE
d240 1 a240 1The following illustrates basic d244 1 a244 1
void
d253 1
a253 1
ard =
d260 1
a260 1
archive_entry_copy_sourcepath(entry, name);
d268 1
a268 1
archive_read_finish(ard);
d272 1
a272 2
RETURN VALUES
d274 1 a274 1Most functions return d281 1 a281 4 operations impossible. The archive_errno(3) and archive_error_string(3) functions can be used to retrieve an appropriate error code and a textual error message. (See archive_util(3) for details.)
d284 1 a284 1archive_read_disk_new() d289 1 a289 1
archive_read_disk_gname() d297 1 a297 1
SEE ALSO
d299 3 a301 3archive_read(3), archive_write(3), archive_write_disk(3), tar(1), libarchive(3)
d303 1 a303 1HISTORY
d305 7 a311 1The libarchive library d317 1 a317 1
AUTHORS
d319 3 a321 3The libarchive library was written by Tim Kientzle ⟨kientzle@@freebsd.org⟩.
d323 1 a323 1BUGS
d325 2 a326 2The ‘‘standard’’ user name and group d328 1 a328 1 getgrid(3) and getpwid(3) are sometimes too large for d333 1 a333 1
The full list of d338 1 a338 1
The d345 1 a345 1
This API should d349 1 a349 1 ‘‘hybrid’’ symbolic link mode will d352 2 a353 3
FreeBSD 8.0 March 10, 2009 FreeBSD 8.0
@ 1.1.1.1 log @Import libarchive 2.8.0: - Infrastructure: - Allow command line tools as fallback for missing compression libraries. If compiled without gzip for example, gunzip will be used automatically. - Improved support for a number of platforms like high-resolution timestamps and Extended Attributes on various Unix systems - New convience interface for creating archives based on disk content, complement of the archive_write_disk interface. - Frontends: - bsdcpio ready for public consumption - hand-written date parser replaces the yacc code - Filter system: - Simplified read filter chains - Option support for filters - LZMA, XZ, uudecode handled - Format support: - Write support for mtree files based on file system or archive content - Basic read support for Joliet - Write support for zip files - Write support for shar archives, both text-only and binary-safe @ text @@ 1.1.1.2 log @libarchive-2.8.2: - Fix NULL deference for short self-extracting zip archives - Don't dereference symlinks on Linux when reading ACLs - Better detection of SHA2 support for old OpenSSL versions - Fix parsing of input files for bsdtar -T - Do not leak setup_xattr into the global namespace - Fix build when an older libarchive is already installed - Use O_BINARY opening files in bsdtar - Include missing archive_crc32.h - Correctly include iconv.h required by libxml2 @ text @d1 341 a341 765 %!PS-Adobe-3.0 %%Creator: groff version 1.19.2 %%CreationDate: Sun Mar 14 02:49:16 2010 %%DocumentNeededResources: font Times-Roman %%DocumentSuppliedResources: procset grops 1.19 2 %%Pages: 53 %%PageOrder: Ascend %%DocumentMedia: Default 612 792 0 () () %%Orientation: Portrait %%EndComments %%BeginDefaults %%PageMedia: Default %%EndDefaults %%BeginProlog %%BeginResource: procset grops 1.19 2 %!PS-Adobe-3.0 Resource-ProcSet /setpacking where{ pop currentpacking true setpacking }if /grops 120 dict dup begin /SC 32 def /A/show load def /B{0 SC 3 -1 roll widthshow}bind def /C{0 exch ashow}bind def /D{0 exch 0 SC 5 2 roll awidthshow}bind def /E{0 rmoveto show}bind def /F{0 rmoveto 0 SC 3 -1 roll widthshow}bind def /G{0 rmoveto 0 exch ashow}bind def /H{0 rmoveto 0 exch 0 SC 5 2 roll awidthshow}bind def /I{0 exch rmoveto show}bind def /J{0 exch rmoveto 0 SC 3 -1 roll widthshow}bind def /K{0 exch rmoveto 0 exch ashow}bind def /L{0 exch rmoveto 0 exch 0 SC 5 2 roll awidthshow}bind def /M{rmoveto show}bind def /N{rmoveto 0 SC 3 -1 roll widthshow}bind def /O{rmoveto 0 exch ashow}bind def /P{rmoveto 0 exch 0 SC 5 2 roll awidthshow}bind def /Q{moveto show}bind def /R{moveto 0 SC 3 -1 roll widthshow}bind def /S{moveto 0 exch ashow}bind def /T{moveto 0 exch 0 SC 5 2 roll awidthshow}bind def /SF{ findfont exch [exch dup 0 exch 0 exch neg 0 0]makefont dup setfont [exch/setfont cvx]cvx bind def }bind def /MF{ findfont [5 2 roll 0 3 1 roll neg 0 0]makefont dup setfont [exch/setfont cvx]cvx bind def }bind def /level0 0 def /RES 0 def /PL 0 def /LS 0 def /MANUAL{ statusdict begin/manualfeed true store end }bind def /PLG{ gsave newpath clippath pathbbox grestore exch pop add exch pop }bind def /BP{ /level0 save def 1 setlinecap 1 setlinejoin 72 RES div dup scale LS{ 90 rotate }{ 0 PL translate }ifelse 1 -1 scale }bind def /EP{ level0 restore showpage }def /DA{ newpath arcn stroke }bind def /SN{ transform .25 sub exch .25 sub exch round .25 add exch round .25 add exch itransform }bind def /DL{ SN moveto SN lineto stroke }bind def /DC{ newpath 0 360 arc closepath }bind def /TM matrix def /DE{ TM currentmatrix pop translate scale newpath 0 0 .5 0 360 arc closepath TM setmatrix }bind def /RC/rcurveto load def /RL/rlineto load def /ST/stroke load def /MT/moveto load def /CL/closepath load def /Fr{ setrgbcolor fill }bind def /setcmykcolor where{ pop /Fk{ setcmykcolor fill }bind def }if /Fg{ setgray fill }bind def /FL/fill load def /LW/setlinewidth load def /Cr/setrgbcolor load def /setcmykcolor where{ pop /Ck/setcmykcolor load def }if /Cg/setgray load def /RE{ findfont dup maxlength 1 index/FontName known not{1 add}if dict begin { 1 index/FID ne{def}{pop pop}ifelse }forall /Encoding exch def dup/FontName exch def currentdict end definefont pop }bind def /DEFS 0 def /EBEGIN{ moveto DEFS begin }bind def /EEND/end load def /CNT 0 def /level1 0 def /PBEGIN{ /level1 save def translate div 3 1 roll div exch scale neg exch neg exch translate 0 setgray 0 setlinecap 1 setlinewidth 0 setlinejoin 10 setmiterlimit []0 setdash /setstrokeadjust where{ pop false setstrokeadjust }if /setoverprint where{ pop false setoverprint }if newpath /CNT countdictstack def userdict begin /showpage{}def /setpagedevice{}def }bind def /PEND{ countdictstack CNT sub{end}repeat level1 restore }bind def end def /setpacking where{ pop setpacking }if %%EndResource %%EndProlog %%BeginSetup %%BeginFeature: *PageSize Default << /PageSize [ 612 792 ] /ImagingBBox null >> setpagedevice %%EndFeature %%IncludeResource: font Times-Roman grops begin/DEFS 1 dict def DEFS begin/u{.001 mul}bind def end/RES 72 def/PL 792 def/LS false def/ENC0[/asciicircum/asciitilde/Scaron/Zcaron /scaron/zcaron/Ydieresis/trademark/quotesingle/Euro/.notdef/.notdef /.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef /.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef /.notdef/.notdef/space/exclam/quotedbl/numbersign/dollar/percent /ampersand/quoteright/parenleft/parenright/asterisk/plus/comma/hyphen /period/slash/zero/one/two/three/four/five/six/seven/eight/nine/colon /semicolon/less/equal/greater/question/at/A/B/C/D/E/F/G/H/I/J/K/L/M/N/O /P/Q/R/S/T/U/V/W/X/Y/Z/bracketleft/backslash/bracketright/circumflex /underscore/quoteleft/a/b/c/d/e/f/g/h/i/j/k/l/m/n/o/p/q/r/s/t/u/v/w/x/y /z/braceleft/bar/braceright/tilde/.notdef/quotesinglbase/guillemotleft /guillemotright/bullet/florin/fraction/perthousand/dagger/daggerdbl /endash/emdash/ff/fi/fl/ffi/ffl/dotlessi/dotlessj/grave/hungarumlaut /dotaccent/breve/caron/ring/ogonek/quotedblleft/quotedblright/oe/lslash /quotedblbase/OE/Lslash/.notdef/exclamdown/cent/sterling/currency/yen /brokenbar/section/dieresis/copyright/ordfeminine/guilsinglleft /logicalnot/minus/registered/macron/degree/plusminus/twosuperior /threesuperior/acute/mu/paragraph/periodcentered/cedilla/onesuperior /ordmasculine/guilsinglright/onequarter/onehalf/threequarters /questiondown/Agrave/Aacute/Acircumflex/Atilde/Adieresis/Aring/AE /Ccedilla/Egrave/Eacute/Ecircumflex/Edieresis/Igrave/Iacute/Icircumflex /Idieresis/Eth/Ntilde/Ograve/Oacute/Ocircumflex/Otilde/Odieresis /multiply/Oslash/Ugrave/Uacute/Ucircumflex/Udieresis/Yacute/Thorn /germandbls/agrave/aacute/acircumflex/atilde/adieresis/aring/ae/ccedilla /egrave/eacute/ecircumflex/edieresis/igrave/iacute/icircumflex/idieresis /eth/ntilde/ograve/oacute/ocircumflex/otilde/odieresis/divide/oslash /ugrave/uacute/ucircumflex/udieresis/yacute/thorn/ydieresis]def /Times-Roman@@0 ENC0/Times-Roman RE %%EndSetup %%Page: 1 1 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF()0 12 Q()0 24 Q(struct archi)0 24 Q -.15(ve)
-.25 G( *).15 E(archi)0 36 Q -.15(ve)-.25 G
(_read_disk_ne).15 E(w\(v)-.25 E(oid\))-.2
E(int)0 48 Q(archi)0 60 Q -.15(ve)
-.25 G
(_read_disk_set_symlink_logical\(struct archi).15
E .3 -.15(ve *)-.25 H(\)).15 E
(int)0 72 Q 0 Cg EP
%%Page: 8 8
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(archi)0 12 Q -.15(ve)-.25 G
(_read_disk_set_symlink_ph).15 E
(ysical\(struct archi)-.05 E .3 -.15(ve *)-.25 H
(\)).15 E(int)0 24 Q(archi)0
36 Q -.15(ve)-.25 G(_read_disk_set_symlink_h).15 E
(ybrid\(struct archi)-.05 E .3 -.15(ve *)-.25 H
(\)).15 E(int)0 48 Q(archi)0
60 Q -.15(ve)-.25 G
(_read_disk_gname\(struct archi).15 E .3 -.15
(ve *)-.25 H(, gid_t\)).15 E
(int)0 72 Q 0 Cg EP
%%Page: 9 9
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(archi)0 12 Q -.15(ve)-.25 G
(_read_disk_uname\(struct archi).15 E .3 -.15
(ve *)-.25 H(, uid_t\)).15 E
(int)0 24 Q(archi)0 36 Q -.15(ve)
-.25 G(_read_disk_set_gname_lookup\(struct archi)0 48 Q .3 -.15(ve *)-.25 H().15
E(v)0 60 Q(oid *)-.2 E
(const char *\(*lookup\)\(v)0 72 Q
(oid *, gid_t\))-.2 E 0 Cg EP
%%Page: 10 10
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(v)0 12 Q(oid \(*cleanup\)\(v)
-.2 E(oid *\))-.2 E(\))0 24 Q
(int)0 36 Q(archi)0 48 Q -.15(ve)
-.25 G(_read_disk_set_uname_lookup\(struct archi)0 60 Q .3 -.15(ve *)-.25 H().15
E(v)0 72 Q(oid *)-.2 E 0 Cg EP
%%Page: 11 11
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(const char *\(*lookup\)\(v)0
12 Q(oid *, uid_t\))-.2 E(v)0 24 Q
(oid \(*cleanup\)\(v)-.2 E(oid *\))-.2 E(\))0 36 Q
(int)0 48 Q(archi)0 60 Q -.15(ve)
-.25 G
(_read_disk_set_standard_lookup\(struct archi).15
E .3 -.15(ve *)-.25 H(\)).15 E
(int)0 72 Q 0 Cg EP
%%Page: 12 12
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(archi)0 12 Q -.15(ve)-.25 G
(_read_disk_entry_from_\214le\(struct archi)0 24 Q .3 -.15(ve *)-.25 H().15
E(struct archi)0 36 Q -.15(ve)-.25 G(_entry *)
.15 E(int fd)0 48 Q
(const struct stat *)0 60 Q(\))0 72 Q 0 Cg EP
%%Page: 13 13
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(int)0 12 Q
(archi)0 24 Q -.15(ve)-.25 G
(_read_close\(struct archi).15 E .3 -.15(ve *)
-.25 H(\)).15 E(int)0 36 Q
(archi)0 48 Q -.15(ve)-.25 G
(_read_\214nish\(struct archi).15 E .3 -.15(ve *)
-.25 H(\)).15 E()36 36 Q
(Information is read from disk using the path name from the)0 48 Q(
) 36 48 Q(If a pointer to a)0 60 Q(struct stat)0 72 Q 0 Cg EP %%Page: 27 27 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF(is pro)0 12 Q (vided, information from that structure will be used instead)-.15 E (of reading from the disk where appropriate.)0 24 Q(This can pro)0 36 Q (vide performance bene\214ts in scenarios where)-.15 E(\ struct stat)0 48 Q (information has already been read from the disk as a side ef)0 60 Q (fect)-.25 E(of some other operation.)0 72 Q 0 Cg EP %%Page: 28 28 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF(\(F)0 12 Q(or e)-.15 E(xample, directory tra) -.15 E -.15(ve)-.2 G(rsal libraries often pro).15 E (vide this information.\))-.15 E(
)36 24 Q(Where necessary)0 36 Q 2.5
(,u)-.65 G(ser and group ids are con)-2.5 E -.15(ve)-.4 G
(rted to user and group names).15 E(using the currently re)0 48 Q
(gistered lookup functions abo)-.15 E -.15(ve)-.15 G(.).15 E(This af)0
60 Q(fects the \214le o)-.25 E(wnership \214elds and A)-.25 E(CL v)-.4 E
(alues in the)-.25 E(struct archi)0 72 Q -.15(ve)-.25 G(_entry).15 E 0 Cg
EP
%%Page: 29 29
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(object.)0 12 Q(\)\)\)).15 E 0 Cg EP
%%Page: 30 30
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(if it w)0 12 Q(as not in)-.1 E -.2(vo)-.4 G -.1
(ke).2 G 2.5(dm).1 G(anually)-2.5 E 2.5(,t)-.65 G
(hen releases all resources.)-2.5 E(
)0 24 Q()
0 36 Q -.2(vo)0 48 S(id).2 E(\214le_to_archi)0 60 Q -.15(ve)-.25 G
(\(struct archi).15 E .3 -.15(ve *)-.25 H(a, const char *name\)).15 E({)
0 72 Q 0 Cg EP
%%Page: 33 33
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(char b)5 12 Q(uf)-.2 E(f[8192];)-.25 E
(size_t bytes_read;)5 24 Q(struct archi)5 36 Q .3 -.15(ve *)-.25 H(ard;)
.15 E(struct archi)5 48 Q -.15(ve)-.25 G(_entry *entry;).15 E(int fd;)5
60 Q()36 72 Q 0 Cg EP
%%Page: 34 34
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(ard = archi)5 12 Q -.15(ve)-.25 G(_read_disk_ne)
.15 E(w\(\);)-.25 E(archi)5 24 Q -.15(ve)-.25 G
(_read_disk_set_standard_lookup\(ard\);).15 E(entry = archi)5 36 Q -.15
(ve)-.25 G(_entry_ne).15 E(w\(\);)-.25 E(fd = open\(name, O_RDONL)5 48 Q
(Y\);)-1 E(if \(fd < 0\))5 60 Q(return;)12.5 72 Q 0 Cg EP
%%Page: 35 35
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(archi)5 12 Q -.15(ve)-.25 G(_entry_cop).15 E
(y_sourcepath\(entry)-.1 E 2.5(,n)-.65 G(ame\);)-2.5 E(archi)5 24 Q -.15
(ve)-.25 G(_read_disk_entry_from_\214le\(ard, entry).15 E 2.5(,f)-.65 G
(d, NULL\);)-2.5 E(archi)5 36 Q -.15(ve)-.25 G
(_write_header\(a, entry\);).15 E(while \(\(bytes_read = read\(fd, b)5
48 Q(uf)-.2 E(f, sizeof\(b)-.25 E(uf)-.2 E(f\)\)\) > 0\))-.25 E(archi)10
60 Q -.15(ve)-.25 G(_write_data\(a, b).15 E(uf)-.2 E(f, bytes_read\);)
-.25 E(archi)5 72 Q -.15(ve)-.25 G(_write_\214nish_entry\(a\);).15 E 0
Cg EP
%%Page: 36 36
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(archi)5 12 Q -.15(ve)-.25 G
(_read_\214nish\(ard\);).15 E(archi)5 24 Q -.15(ve)-.25 G
(_entry_free\(entry\);).15 E(})0 36 Q(
)0 48 Q()0 60 Q
()36 72 Q 0 Cg EP
%%Page: 41 41
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(archi)0 12 Q -.15(ve)-.25 G(_read_disk_ne).15
E(w\( )36 60 Q(archi)0 72 Q -.15(ve)-.25 G
(_read_disk_gname\(\))-.25 E(returns a pointer to a ne)0 24 Q
(wly-allocated)-.25 E(struct archi)0 36 Q -.15(ve)-.25 G().15 E
(object or NULL if the allocation f)0 48 Q(ailed for an)-.1 E 2.5(yr)
-.15 G(eason.)-2.5 E(\)).15 E 0 Cg EP
%%Page: 42 42
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(and)0 12 Q(archi)0 24 Q -.15(ve)-.25 G
(_read_disk_uname\(\)).15 E(return)0 36 Q(const char
)36 36 Q(
)36 48 Q(The)0 60 Q(libarchi)0 72 Q -.15(ve)-.25 G().15 E 0 Cg EP %%Page: 48 48 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF(library w)0 12 Q(as written by)-.1 E -.35(Ti)0 24 S 2.5(mK).35 G(ientzle <kientzle@@freebsd.or)-2.5 E(g>.)-.18 E (
)36 36 Q
(The full list of metadata read from disk by)0 48 Q(archi)0 60 Q -.15
(ve)-.25 G(_read_disk_entry_from_\214le\(\)).15 E
(is necessarily system-dependent.)0 72 Q 0 Cg EP
%%Page: 51 51
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(
)36 12 Q(The)0 24 Q(archi)0 36 Q -.15(ve)
-.25 G(_read_disk_entry_from_\214le\(\)).15 E
(function reads as much information as it can from disk.)0 48 Q
(Some method should be pro)0 60 Q
(vided to limit this so that clients who)-.15 E(do not need A)0 72 Q
(CLs, for instance, can a)-.4 E -.2(vo)-.2 G(id the e).2 E(xtra w)-.15 E
(ork needed)-.1 E 0 Cg EP
%%Page: 52 52
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(to look up such information.)0 12 Q(
)36 24 Q (This API should pro)0 36 Q(vide a set of methods for w)-.15 E (alking a directory tree.)-.1 E(That w)0 48 Q(ould mak)-.1 E 2.5(ei)-.1 G 2.5(tad)-2.5 G(irect parallel of the)-2.5 E(archi).15 E -.15(ve)-.25 G (_read\(3\)).15 E(API.)0 72 Q 0 Cg EP %%Page: 53 53 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF(When such methods are implemented, the)0 12 Q -.74(``)0 24 S -.05(hy).74 G(brid').05 E(')-.74 E (symbolic link mode will mak)0 36 Q 2.5(es)-.1 G(ense.)-2.5 E()0 48 Q()0 60 Q 0 Cg EP %%Trailer end %%EOF @ 1.1.1.3 log @libarchive-2.8.3: Build fix for Linux @ text @d1 765 a765 341
archive_read_disk(3) FreeBSD Library Functions Manual archive_read_disk(3)
NAME
archive_read_disk_new, archive_read_disk_set_symlink_logical, archive_read_disk_set_symlink_physical, archive_read_disk_set_symlink_hybrid, archive_read_disk_entry_from_file, archive_read_disk_gname, archive_read_disk_uname, archive_read_disk_set_uname_lookup, archive_read_disk_set_gname_lookup, archive_read_disk_set_standard_lookup, archive_read_close, archive_read_finish — functions for reading objects from disk
SYNOPSIS
#include <archive.h>
struct archive *
archive_read_disk_new(void);
int
archive_read_disk_set_symlink_logical(struct archive *);
int
archive_read_disk_set_symlink_physical(struct archive *);
int
archive_read_disk_set_symlink_hybrid(struct archive *);
int
archive_read_disk_gname(struct archive *, gid_t);
int
archive_read_disk_uname(struct archive *, uid_t);
int
archive_read_disk_set_gname_lookup(struct archive *, void *, const char *(*lookup)(void *, gid_t), void (*cleanup)(void *));
int
archive_read_disk_set_uname_lookup(struct archive *, void *, const char *(*lookup)(void *, uid_t), void (*cleanup)(void *));
int
archive_read_disk_set_standard_lookup(struct archive *);
int
archive_read_disk_entry_from_file(struct archive *, struct archive_entry *, int fd, const struct stat *);
int
archive_read_close(struct archive *);
int
archive_read_finish(struct archive *);
DESCRIPTION
These functions provide an API for reading information about objects on disk. In particular, they provide an interface for populating struct archive_entry objects.
archive_read_disk_new()
Allocates and initializes a struct archive object suitable for reading object information from disk.
archive_read_disk_set_symlink_logical(), archive_read_disk_set_symlink_physical(), archive_read_disk_set_symlink_hybrid()
This sets the mode used for handling symbolic links. The ‘‘logical’’ mode follows all symbolic links. The ‘‘physical’’ mode does not follow any symbolic links. The ‘‘hybrid’’ mode currently behaves identically to the ‘‘logical’’ mode.
archive_read_disk_gname(), archive_read_disk_uname()
Returns a user or group name given a gid or uid value. By default, these always return a NULL string.
archive_read_disk_set_gname_lookup(), archive_read_disk_set_uname_lookup()
These allow you to override the functions used for user and group name lookups. You may also provide a void * pointer to a private data structure and a cleanup function for that data. The cleanup function will be invoked when the struct archive object is destroyed or when new lookup functions are registered.
archive_read_disk_set_standard_lookup()
This convenience function installs a standard set of user and group name lookup functions. These functions use getpwid(3) and getgrid(3) to convert ids to names, defaulting to NULL if the names cannot be looked up. These functions also implement a simple memory cache to reduce the number of calls to getpwid(3) and getgrid(3).
archive_read_disk_entry_from_file()
Populates a struct archive_entry object with information about a particular file. The archive_entry object must have already been created with archive_entry_new(3) and at least one of the source path or path fields must already be set. (If both are set, the source path will be used.)
Information is read from disk using the path name from the struct archive_entry object. If a file descriptor is provided, some information will be obtained using that file descriptor, on platforms that support the appropriate system calls.
If a pointer to a struct stat is provided, information from that structure will be used instead of reading from the disk where appropriate. This can provide performance benefits in scenarios where struct stat information has already been read from the disk as a side effect of some other operation. (For example, directory traversal libraries often provide this information.)
Where necessary, user and group ids are converted to user and group names using the currently registered lookup functions above. This affects the file ownership fields and ACL values in the struct archive_entry object.
archive_read_close()
This currently does nothing.
archive_write_finish()
Invokes archive_write_close() if it was not invoked manually, then releases all resources.
More information about the struct archive object and the overall design of the library can be found in the libarchive(3) overview.
EXAMPLE
The following illustrates basic usage of the library by showing how to use it to copy an item on disk into an archive.
void
file_to_archive(struct archive *a, const char *name)
{
char buff[8192];
size_t bytes_read;
struct archive *ard;
struct archive_entry *entry;
int fd;
ard =
archive_read_disk_new();
archive_read_disk_set_standard_lookup(ard);
entry = archive_entry_new();
fd = open(name, O_RDONLY);
if (fd < 0)
return;
archive_entry_copy_sourcepath(entry, name);
archive_read_disk_entry_from_file(ard, entry, fd, NULL);
archive_write_header(a, entry);
while ((bytes_read = read(fd, buff, sizeof(buff))) > 0)
archive_write_data(a, buff, bytes_read);
archive_write_finish_entry(a);
archive_read_finish(ard);
archive_entry_free(entry);
}
RETURN VALUES
Most functions return ARCHIVE_OK (zero) on success, or one of several negative error codes for errors. Specific error codes include: ARCHIVE_RETRY for operations that might succeed if retried, ARCHIVE_WARN for unusual conditions that do not prevent further operations, and ARCHIVE_FATAL for serious errors that make remaining operations impossible. The archive_errno(3) and archive_error_string(3) functions can be used to retrieve an appropriate error code and a textual error message. (See archive_util(3) for details.)
archive_read_disk_new() returns a pointer to a newly-allocated struct archive object or NULL if the allocation failed for any reason.
archive_read_disk_gname() and archive_read_disk_uname() return const char * pointers to the textual name or NULL if the lookup failed for any reason. The returned pointer points to internal storage that may be reused on the next call to either of these functions; callers should copy the string if they need to continue accessing it.
SEE ALSO
archive_read(3), archive_write(3), archive_write_disk(3), tar(1), libarchive(3)
HISTORY
The libarchive library first appeared in FreeBSD 5.3. The archive_read_disk interface was added to libarchive 2.6 and first appeared in FreeBSD 8.0.
AUTHORS
The libarchive library was written by Tim Kientzle ⟨kientzle@@freebsd.org⟩.
BUGS
The ‘‘standard’’ user name and group name lookup functions are not the defaults because getgrid(3) and getpwid(3) are sometimes too large for particular applications. The current design allows the application author to use a more compact implementation when appropriate.
The full list of metadata read from disk by archive_read_disk_entry_from_file() is necessarily system-dependent.
The archive_read_disk_entry_from_file() function reads as much information as it can from disk. Some method should be provided to limit this so that clients who do not need ACLs, for instance, can avoid the extra work needed to look up such information.
This API should provide a set of methods for walking a directory tree. That would make it a direct parallel of the archive_read(3) API. When such methods are implemented, the ‘‘hybrid’’ symbolic link mode will make sense.
FreeBSD 9.0 March 10, 2009 FreeBSD 9.0
struct archi)0 24 Q -.15(ve)
-.25 G( *).15 E(archi)0 36 Q -.15(ve)-.25 G
(_read_disk_ne).15 E(w\(v)-.25 E(oid\))-.2
E(int)0 48 Q(archi)0 60 Q -.15(ve)
-.25 G
(_read_disk_set_symlink_logical\(struct archi).15
E .3 -.15(ve *)-.25 H(\)).15 E
(int)0 72 Q 0 Cg EP
%%Page: 8 8
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(archi)0 12 Q -.15(ve)-.25 G
(_read_disk_set_symlink_ph).15 E
(ysical\(struct archi)-.05 E .3 -.15(ve *)-.25 H
(\)).15 E(int)0 24 Q(archi)0
36 Q -.15(ve)-.25 G(_read_disk_set_symlink_h).15 E
(ybrid\(struct archi)-.05 E .3 -.15(ve *)-.25 H
(\)).15 E(int)0 48 Q(archi)0
60 Q -.15(ve)-.25 G
(_read_disk_gname\(struct archi).15 E .3 -.15
(ve *)-.25 H(, gid_t\)).15 E
(int)0 72 Q 0 Cg EP
%%Page: 9 9
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(archi)0 12 Q -.15(ve)-.25 G
(_read_disk_uname\(struct archi).15 E .3 -.15
(ve *)-.25 H(, uid_t\)).15 E
(int)0 24 Q(archi)0 36 Q -.15(ve)
-.25 G(_read_disk_set_gname_lookup\(struct archi)0 48 Q .3 -.15(ve *)-.25 H().15
E(v)0 60 Q(oid *)-.2 E
(const char *\(*lookup\)\(v)0 72 Q
(oid *, gid_t\))-.2 E 0 Cg EP
%%Page: 10 10
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(v)0 12 Q(oid \(*cleanup\)\(v)
-.2 E(oid *\))-.2 E(\))0 24 Q
(int)0 36 Q(archi)0 48 Q -.15(ve)
-.25 G(_read_disk_set_uname_lookup\(struct archi)0 60 Q .3 -.15(ve *)-.25 H().15
E(v)0 72 Q(oid *)-.2 E 0 Cg EP
%%Page: 11 11
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(const char *\(*lookup\)\(v)0
12 Q(oid *, uid_t\))-.2 E(v)0 24 Q
(oid \(*cleanup\)\(v)-.2 E(oid *\))-.2 E(\))0 36 Q
(int)0 48 Q(archi)0 60 Q -.15(ve)
-.25 G
(_read_disk_set_standard_lookup\(struct archi).15
E .3 -.15(ve *)-.25 H(\)).15 E
(int)0 72 Q 0 Cg EP
%%Page: 12 12
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(archi)0 12 Q -.15(ve)-.25 G
(_read_disk_entry_from_\214le\(struct archi)0 24 Q .3 -.15(ve *)-.25 H().15
E(struct archi)0 36 Q -.15(ve)-.25 G(_entry *)
.15 E(int fd)0 48 Q
(const struct stat *)0 60 Q(\))0 72 Q 0 Cg EP
%%Page: 13 13
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(int)0 12 Q
(archi)0 24 Q -.15(ve)-.25 G
(_read_close\(struct archi).15 E .3 -.15(ve *)
-.25 H(\)).15 E(int)0 36 Q
(archi)0 48 Q -.15(ve)-.25 G
(_read_\214nish\(struct archi).15 E .3 -.15(ve *)
-.25 H(\)).15 E()36 36 Q
(Information is read from disk using the path name from the)0 48 Q(
) 36 48 Q(If a pointer to a)0 60 Q(struct stat)0 72 Q 0 Cg EP %%Page: 27 27 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF(is pro)0 12 Q (vided, information from that structure will be used instead)-.15 E (of reading from the disk where appropriate.)0 24 Q(This can pro)0 36 Q (vide performance bene\214ts in scenarios where)-.15 E(\ struct stat)0 48 Q (information has already been read from the disk as a side ef)0 60 Q (fect)-.25 E(of some other operation.)0 72 Q 0 Cg EP %%Page: 28 28 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF(\(F)0 12 Q(or e)-.15 E(xample, directory tra) -.15 E -.15(ve)-.2 G(rsal libraries often pro).15 E (vide this information.\))-.15 E(
)36 24 Q(Where necessary)0 36 Q 2.5
(,u)-.65 G(ser and group ids are con)-2.5 E -.15(ve)-.4 G
(rted to user and group names).15 E(using the currently re)0 48 Q
(gistered lookup functions abo)-.15 E -.15(ve)-.15 G(.).15 E(This af)0
60 Q(fects the \214le o)-.25 E(wnership \214elds and A)-.25 E(CL v)-.4 E
(alues in the)-.25 E(struct archi)0 72 Q -.15(ve)-.25 G(_entry).15 E 0 Cg
EP
%%Page: 29 29
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(object.)0 12 Q(\)\)\)).15 E 0 Cg EP
%%Page: 30 30
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(if it w)0 12 Q(as not in)-.1 E -.2(vo)-.4 G -.1
(ke).2 G 2.5(dm).1 G(anually)-2.5 E 2.5(,t)-.65 G
(hen releases all resources.)-2.5 E(
)0 24 Q()
0 36 Q -.2(vo)0 48 S(id).2 E(\214le_to_archi)0 60 Q -.15(ve)-.25 G
(\(struct archi).15 E .3 -.15(ve *)-.25 H(a, const char *name\)).15 E({)
0 72 Q 0 Cg EP
%%Page: 33 33
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(char b)5 12 Q(uf)-.2 E(f[8192];)-.25 E
(size_t bytes_read;)5 24 Q(struct archi)5 36 Q .3 -.15(ve *)-.25 H(ard;)
.15 E(struct archi)5 48 Q -.15(ve)-.25 G(_entry *entry;).15 E(int fd;)5
60 Q()36 72 Q 0 Cg EP
%%Page: 34 34
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(ard = archi)5 12 Q -.15(ve)-.25 G(_read_disk_ne)
.15 E(w\(\);)-.25 E(archi)5 24 Q -.15(ve)-.25 G
(_read_disk_set_standard_lookup\(ard\);).15 E(entry = archi)5 36 Q -.15
(ve)-.25 G(_entry_ne).15 E(w\(\);)-.25 E(fd = open\(name, O_RDONL)5 48 Q
(Y\);)-1 E(if \(fd < 0\))5 60 Q(return;)12.5 72 Q 0 Cg EP
%%Page: 35 35
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(archi)5 12 Q -.15(ve)-.25 G(_entry_cop).15 E
(y_sourcepath\(entry)-.1 E 2.5(,n)-.65 G(ame\);)-2.5 E(archi)5 24 Q -.15
(ve)-.25 G(_read_disk_entry_from_\214le\(ard, entry).15 E 2.5(,f)-.65 G
(d, NULL\);)-2.5 E(archi)5 36 Q -.15(ve)-.25 G
(_write_header\(a, entry\);).15 E(while \(\(bytes_read = read\(fd, b)5
48 Q(uf)-.2 E(f, sizeof\(b)-.25 E(uf)-.2 E(f\)\)\) > 0\))-.25 E(archi)10
60 Q -.15(ve)-.25 G(_write_data\(a, b).15 E(uf)-.2 E(f, bytes_read\);)
-.25 E(archi)5 72 Q -.15(ve)-.25 G(_write_\214nish_entry\(a\);).15 E 0
Cg EP
%%Page: 36 36
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(archi)5 12 Q -.15(ve)-.25 G
(_read_\214nish\(ard\);).15 E(archi)5 24 Q -.15(ve)-.25 G
(_entry_free\(entry\);).15 E(})0 36 Q(
)0 48 Q()0 60 Q
()36 72 Q 0 Cg EP
%%Page: 41 41
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(archi)0 12 Q -.15(ve)-.25 G(_read_disk_ne).15
E(w\( )36 60 Q(archi)0 72 Q -.15(ve)-.25 G
(_read_disk_gname\(\))-.25 E(returns a pointer to a ne)0 24 Q
(wly-allocated)-.25 E(struct archi)0 36 Q -.15(ve)-.25 G().15 E
(object or NULL if the allocation f)0 48 Q(ailed for an)-.1 E 2.5(yr)
-.15 G(eason.)-2.5 E(\)).15 E 0 Cg EP
%%Page: 42 42
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(and)0 12 Q(archi)0 24 Q -.15(ve)-.25 G
(_read_disk_uname\(\)).15 E(return)0 36 Q(const char
)36 36 Q(
)36 48 Q(The)0 60 Q(libarchi)0 72 Q -.15(ve)-.25 G().15 E 0 Cg EP %%Page: 48 48 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF(library w)0 12 Q(as written by)-.1 E -.35(Ti)0 24 S 2.5(mK).35 G(ientzle <kientzle@@freebsd.or)-2.5 E(g>.)-.18 E (
)36 36 Q
(The full list of metadata read from disk by)0 48 Q(archi)0 60 Q -.15
(ve)-.25 G(_read_disk_entry_from_\214le\(\)).15 E
(is necessarily system-dependent.)0 72 Q 0 Cg EP
%%Page: 51 51
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(
)36 12 Q(The)0 24 Q(archi)0 36 Q -.15(ve)
-.25 G(_read_disk_entry_from_\214le\(\)).15 E
(function reads as much information as it can from disk.)0 48 Q
(Some method should be pro)0 60 Q
(vided to limit this so that clients who)-.15 E(do not need A)0 72 Q
(CLs, for instance, can a)-.4 E -.2(vo)-.2 G(id the e).2 E(xtra w)-.15 E
(ork needed)-.1 E 0 Cg EP
%%Page: 52 52
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(to look up such information.)0 12 Q(
)36 24 Q (This API should pro)0 36 Q(vide a set of methods for w)-.15 E (alking a directory tree.)-.1 E(That w)0 48 Q(ould mak)-.1 E 2.5(ei)-.1 G 2.5(tad)-2.5 G(irect parallel of the)-2.5 E(archi).15 E -.15(ve)-.25 G (_read\(3\)).15 E(API.)0 72 Q 0 Cg EP %%Page: 53 53 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF(When such methods are implemented, the)0 12 Q -.74(``)0 24 S -.05(hy).74 G(brid').05 E(')-.74 E (symbolic link mode will mak)0 36 Q 2.5(es)-.1 G(ense.)-2.5 E()0 48 Q()0 60 Q 0 Cg EP %%Trailer end %%EOF @ 1.1.1.5 log @Import libarchive-3.2.1: - security fixes and other bugfixes - support for multhreading in xz 5.2+ @ text @d1 765 a765 356
ARCHIVE_READ_DISK(3) BSD Library Functions Manual ARCHIVE_READ_DISK(3)
NAME
archive_read_disk_new, archive_read_disk_set_symlink_logical, archive_read_disk_set_symlink_physical, archive_read_disk_set_symlink_hybrid, archive_read_disk_entry_from_file, archive_read_disk_gname, archive_read_disk_uname, archive_read_disk_set_uname_lookup, archive_read_disk_set_gname_lookup, archive_read_disk_set_standard_lookup, archive_read_close, archive_read_finish, archive_read_free — functions for reading objects from disk
LIBRARY
Streaming Archive Library (libarchive, -larchive)
SYNOPSIS
#include <archive.h>
struct archive *
archive_read_disk_new(void);
int
archive_read_disk_set_symlink_logical(struct archive *);
int
archive_read_disk_set_symlink_physical(struct archive *);
int
archive_read_disk_set_symlink_hybrid(struct archive *);
int
archive_read_disk_gname(struct archive *, gid_t);
int
archive_read_disk_uname(struct archive *, uid_t);
int
archive_read_disk_set_gname_lookup(struct archive *, void *, const char *(*lookup)(void *, gid_t), void (*cleanup)(void *));
int
archive_read_disk_set_uname_lookup(struct archive *, void *, const char *(*lookup)(void *, uid_t), void (*cleanup)(void *));
int
archive_read_disk_set_standard_lookup(struct archive *);
int
archive_read_disk_entry_from_file(struct archive *, struct archive_entry *, int fd, const struct stat *);
int
archive_read_close(struct archive *);
int
archive_read_finish(struct archive *);
int
archive_read_free(struct archive *);
DESCRIPTION
These functions provide an API for reading information about objects on disk. In particular, they provide an interface for populating struct archive_entry objects.
archive_read_disk_new()
Allocates and initializes a struct archive object suitable for reading object information from disk.
archive_read_disk_set_symlink_logical(), archive_read_disk_set_symlink_physical(), archive_read_disk_set_symlink_hybrid()
This sets the mode used for handling symbolic links. The ’’logical’’ mode follows all symbolic links. The ’’physical’’ mode does not follow any symbolic links. The ’’hybrid’’ mode currently behaves identically to the ’’logical’’ mode.
archive_read_disk_gname(), archive_read_disk_uname()
Returns a user or group name given a gid or uid value. By default, these always return a NULL string.
archive_read_disk_set_gname_lookup(), archive_read_disk_set_uname_lookup()
These allow you to override the functions used for user and group name lookups. You may also provide a void * pointer to a private data structure and a cleanup function for that data. The cleanup function will be invoked when the struct archive object is destroyed or when new lookup functions are registered.
archive_read_disk_set_standard_lookup()
This convenience function installs a standard set of user and group name lookup functions. These functions use getpwuid(3) and getgrgid(3) to convert ids to names, defaulting to NULL if the names cannot be looked up. These functions also implement a simple memory cache to reduce the number of calls to getpwuid(3) and getgrgid(3).
archive_read_disk_entry_from_file()
Populates a struct archive_entry object with information about a particular file. The archive_entry object must have already been created with archive_entry_new(3) and at least one of the source path or path fields must already be set. (If both are set, the source path will be used.)
Information is read from disk using the path name from the struct archive_entry object. If a file descriptor is provided, some information will be obtained using that file descriptor, on platforms that support the appropriate system calls.
If a pointer to a struct stat is provided, information from that structure will be used instead of reading from the disk where appropriate. This can provide performance benefits in scenarios where struct stat information has already been read from the disk as a side effect of some other operation. (For example, directory traversal libraries often provide this information.)
Where necessary, user and group ids are converted to user and group names using the currently registered lookup functions above. This affects the file ownership fields and ACL values in the struct archive_entry object.
archive_read_close()
Does nothing for archive_read_disk handles.
archive_read_finish()
This is a deprecated synonym for archive_read_free().
archive_read_free()
Invokes archive_read_close() if it was not invoked manually, then releases all resources.
More information about the struct archive object and the overall design of the library can be found in the libarchive(3) overview.
EXAMPLE
The following illustrates basic usage of the library by showing how to use it to copy an item on disk into an archive.
void
file_to_archive(struct archive *a, const char *name)
{
char buff[8192];
size_t bytes_read;
struct archive *ard;
struct archive_entry *entry;
int fd;
ard =
archive_read_disk_new();
archive_read_disk_set_standard_lookup(ard);
entry = archive_entry_new();
fd = open(name, O_RDONLY);
if (fd < 0)
return;
archive_entry_copy_pathname(entry, name);
archive_read_disk_entry_from_file(ard, entry, fd, NULL);
archive_write_header(a, entry);
while ((bytes_read = read(fd, buff, sizeof(buff))) > 0)
archive_write_data(a, buff, bytes_read);
archive_write_finish_entry(a);
archive_read_free(ard);
archive_entry_free(entry);
}
RETURN VALUES
Most functions return ARCHIVE_OK (zero) on success, or one of several negative error codes for errors. Specific error codes include: ARCHIVE_RETRY for operations that might succeed if retried, ARCHIVE_WARN for unusual conditions that do not prevent further operations, and ARCHIVE_FATAL for serious errors that make remaining operations impossible.
archive_read_disk_new() returns a pointer to a newly-allocated struct archive object or NULL if the allocation failed for any reason.
archive_read_disk_gname() and archive_read_disk_uname() return const char * pointers to the textual name or NULL if the lookup failed for any reason. The returned pointer points to internal storage that may be reused on the next call to either of these functions; callers should copy the string if they need to continue accessing it.
ERRORS
Detailed error codes and textual descriptions are available from the archive_errno() and archive_error_string() functions.
SEE ALSO
archive_read(3), archive_util(3), archive_write(3), archive_write_disk(3), tar(1), libarchive(3)
HISTORY
The libarchive library first appeared in FreeBSD 5.3. The archive_read_disk interface was added to libarchive 2.6 and first appeared in FreeBSD 8.0.
AUTHORS
The libarchive library was written by Tim Kientzle <kientzle@@FreeBSD.org>.
BUGS
The ’’standard’’ user name and group name lookup functions are not the defaults because getgrgid(3) and getpwuid(3) are sometimes too large for particular applications. The current design allows the application author to use a more compact implementation when appropriate.
The full list of metadata read from disk by archive_read_disk_entry_from_file() is necessarily system-dependent.
The archive_read_disk_entry_from_file() function reads as much information as it can from disk. Some method should be provided to limit this so that clients who do not need ACLs, for instance, can avoid the extra work needed to look up such information.
This API should provide a set of methods for walking a directory tree. That would make it a direct parallel of the archive_read(3) API. When such methods are implemented, the ’’hybrid’’ symbolic link mode will make sense.
BSD February 2, 2012 BSD
const char *
d79 1 a79 2const char *
d149 2 a150 2 ‘‘logical’’ mode follows all symbolic links. The ‘‘physical’’ d152 2 a153 2 ‘‘hybrid’’ mode currently behaves identically to the ‘‘logical’’ d326 1 a326 1 ‘‘standard’’ user name and group d349 1 a349 1 ‘‘hybrid’’ symbolic link mode will d353 1 a353 1 December 30, 2016 BSD @ 1.1.1.7 log @Import libarchive-3.3.2 + 9de5f3 + f9dacbf: - Support NFS4 ACLs on Linux - Bugfixes @ text @d2 1 a2 1 a28 1 archive_read_disk_set_behavior, d37 4 a40 2 archive_read_disk_set_standard_lookup — functions for reading objects from disk a60 6archive_read_disk_set_behavior(struct archive *, int);
int
d115 15 a144 51archive_read_disk_set_behavior()
Configures various behavior options when reading entries from disk. The flags field consists of a bitwise OR of one or more of the following values:
ARCHIVE_READDISK_HONOR_NODUMP
Skip files and directories with the nodump file attribute (file flag) set. By default, the nodump file atrribute is ignored.
ARCHIVE_READDISK_MAC_COPYFILE
Mac OS X specific. Read metadata (ACLs and extended attributes) with copyfile(3). By default, metadata is read using copyfile(3).
ARCHIVE_READDISK_NO_ACL
Do not read Access Control Lists. By default, ACLs are read from disk.
ARCHIVE_READDISK_NO_FFLAGS
Do not read file attributes (file flags). By default, file attributes are read from disk. See chattr(1) (Linux) or chflags(1) (FreeBSD, Mac OS X) for more information on file attributes.
ARCHIVE_READDISK_NO_TRAVERSE_MOUNTS
Do not traverse mount points. By defaut, moint points are traversed.
ARCHIVE_READDISK_NO_XATTR
Do not read extended file attributes (xattrs). By default, extended file attributes are read from disk. See xattr(7) (Linux), xattr(2) (Mac OS X), or getextattr(8) (FreeBSD) for more information on extended file attributes.
ARCHIVE_READDISK_RESTORE_ATIME
Restore access time of traversed files. By default, access time of traversed files is not restored.
d151 2 a152 2 ’’logical’’ mode follows all symbolic links. The ’’physical’’ d154 2 a155 2 ’’hybrid’’ mode currently behaves identically to the ’’logical’’ d219 17 d328 1 a328 1 ’’standard’’ user name and group d351 1 a351 1 ’’hybrid’’ symbolic link mode will d355 1 a355 1 April 3, 2017 BSD @ 1.1.1.8 log @Import libarchive-3.3.3 as should have done originally. @ text @d2 1 a2 1 @ 1.1.1.9 log @Import libarchive 3.4.0 @ text @d1 2 a2 2 d191 7 a197 5 handling symbolic links. The “logical” mode follows all symbolic links. The “physical” mode does not follow any symbolic links. The “hybrid” mode currently behaves identically to the “logical” mode. d351 5 a355 4The “standard” user name and group name lookup functions are not the defaults because getgrgid(3) and getpwuid(3) are sometimes too large for particular applications. The current design allows the d374 3 a376 2 When such methods are implemented, the “hybrid” symbolic link mode will make sense.
@ 1.1.1.10 log @Import libarchive 3.7.2 @ text @d2 1 a2 1 a28 2 archive_read_disk_open, archive_read_disk_open_w, d38 2 a39 9 archive_read_disk_set_standard_lookup, archive_read_disk_descend, archive_read_disk_can_descend, archive_read_disk_current_filesystem, archive_read_disk_current_filesystem_is_synthetic, archive_read_disk_current_filesystem_is_remote, archive_read_disk_set_matching, archive_read_disk_set_metadata_filter_callback, — functions for reading objects from disk a59 12archive_read_disk_open(struct archive *, const char *);
int
archive_read_disk_open_w(struct archive *, const wchar_t *);
int
a119 40int
archive_read_disk_descend(struct archive *);
int
archive_read_disk_can_descend(struct archive *);
int
archive_read_disk_current_filesystem(struct archive *);
int
archive_read_disk_current_filesystem_is_synthetic(struct archive *);
int
archive_read_disk_current_filesystem_is_remote(struct archive *);
int
archive_read_disk_set_matching(struct archive *, struct archive *, void (*excluded_func)(struct archive *, void *, struct archive entry *), void *);
int
archive_read_disk_set_metadata_filter_callback(struct archive *, int (*metadata_filter_func)(struct archive *, void*, struct archive_entry *), void *);
a134 14archive_read_disk_open()
Opens the file or directory from the given path and prepares the struct archive to read it from disk.
archive_read_disk_open_w()
Opens the file or directory from the given path as a wide character string and prepares the struct archive to read it from disk.
d146 1 a146 1 nodump file attribute is ignored. d169 1 a169 1 By default, mount points are traversed. a184 6ARCHIVE_READDISK_NO_SPARSE
Do not read sparse file information. By default, sparse file information is read from disk.
d254 1 a254 1 group names using the currently-registered lookup functions a257 59archive_read_disk_descend()
If the current entry can be descended, this function will mark the directory as the next entry for archive_read_header(3) to visit.
archive_read_disk_can_descend()
Returns 1 if the current entry is an unvisited directory and 0 otherwise.
archive_read_disk_current_filesystem()
Returns the index of the most recent filesystem entry that has been visited through archive_read_disk
archive_read_disk_current_filesystem_is_synthetic()
Returns 1 if the current filesystem is a virtual filesystem. Returns 0 if the current filesystem is not a virtual filesystem. Returns -1 if it is unknown.
archive_read_disk_current_filesystem_is_remote()
Returns 1 if the current filesystem is a remote filesystem. Returns 0 if the current filesystem is not a remote filesystem. Returns -1 if it is unknown.
archive_read_disk_set_matching()
Allows the caller to set struct archive *_ma to compare each entry during archive_read_header(3) calls. If matched based on calls to archive_match_path_excluded, archive_match_time_excluded, or archive_match_owner_excluded, then the callback function specified by the _excluded_func parameter will execute. This function will recieve data provided to the fourth parameter, void *_client_data.
archive_read_disk_set_metadata_filter_callback()
Allows the caller to set a callback function during calls to archive_read_header(3) to filter out metadata for each entry. The callback function recieves the struct archive object, void* custom filter data, and the struct archive_entry. If the callback function returns an error, ARCHIVE_RETRY will be returned and the entry will not be further processed.
d262 1 a262 1EXAMPLES
d329 1 a329 1tar(1), archive_read(3), d331 1 a331 1 libarchive(3)
@ 1.1.1.11 log @libarchive: import version 3.7.3 @ text @d2 1 a2 1 @ 1.1.1.12 log @Libarchive 3.7.4 is a bugfix and security release Security fixes: rar: Fix OOB in rar e8 filter (CVE-2024-26256) zip: Fix out of boundary access Important bugfixes: 7zip: Limit amount of properties bsdtar: Fix error handling around strtol() usages passphrase: Improve newline handling on Windows passphrase: Never allow empty passwords rar: Fix "File CRC Error" when extracting specific rar4 archives xar: Avoid infinite link loop zip: Update AppleDouble support for directories zstd: Implement core detection @ text @d2 1 a2 1 d384 1 a384 1 function will receive data provided to the fourth parameter, d393 1 a393 1 receives the struct archive object, void* custom filter @ 1.1.1.13 log @libarchive: imported version 3.7.5 Libarchive 3.7.5 Security fixes: fix multiple vulnerabilities identified by SAST cpio: ignore out-of-range gid/uid/size/ino and harden AFIO parsing lzop: prevent integer overflow rar4: protect copy_from_lzss_window_to_unp() rar4: fix CVE-2024-26256 rar4: fix OOB in delta and audio filter rar4: fix out of boundary access with large files rar4: add boundary checks to rgb filter rar4: fix OOB access with unicode filenames rar5: clear 'data ready' cache on window buffer reallocs rpm: calculate huge header sizes correctly unzip: unify EOF handling util: fix out of boundary access in mktemp functions uu: stop processing if lines are too long Important bugfixes: 7zip: fix issue when skipping first file in 7zip archive that is a multiple of 65536 bytes ar: fix archive entries having no type lha: do not allow negative file sizes lha: fix integer truncation on 32-bit systems shar: check strdup return value rar5: don't try to read rediculously long names xar: fix another infinite loop and expat error handling many Windows fixes, cleanups and improvements @ text @d2 1 a2 1 @ 1.1.1.14 log @libarchove: import version 3.7.7 @ text @d1 2 a2 2 d23 2 a24 2ARCHIVE_READ_DISK(3) Library Functions Manual ARCHIVE_READ_DISK(3)
d28 21 a48 17archive_read_disk_new, archive_read_disk_open, archive_read_disk_open_w, archive_read_disk_set_behavior, archive_read_disk_set_symlink_logical, archive_read_disk_set_symlink_physical, archive_read_disk_set_symlink_hybrid, archive_read_disk_entry_from_file, archive_read_disk_gname, archive_read_disk_uname, archive_read_disk_set_uname_lookup, archive_read_disk_set_gname_lookup, archive_read_disk_set_standard_lookup, archive_read_disk_descend, archive_read_disk_can_descend, archive_read_disk_current_filesystem, archive_read_disk_current_filesystem_is_synthetic, archive_read_disk_current_filesystem_is_remote, archive_read_disk_set_matching, archive_read_disk_set_metadata_filter_callback, — functions for reading objects from disk
d52 1 a52 1Streaming Archive Library d57 1 a57 1
#include d60 1 a60 1
struct d64 1 a64 1
archive_read_disk_new(void);
d66 1 a66 1int
d69 1 a69 1archive_read_disk_open(struct archive *, d72 1 a72 1
int
d75 1 a75 1archive_read_disk_open_w(struct archive *, d78 1 a78 1
int
d81 1 a81 1archive_read_disk_set_behavior(struct archive *, d84 1 a84 1
int
d87 1 a87 1archive_read_disk_set_symlink_logical(struct archive *);
d89 1 a89 1int
d92 1 a92 1archive_read_disk_set_symlink_physical(struct archive *);
d94 1 a94 1int
d97 1 a97 1archive_read_disk_set_symlink_hybrid(struct archive *);
d99 1 a99 1const char d103 1 a103 1
archive_read_disk_gname(struct archive *, d106 1 a106 1
const char d110 1 a110 1
archive_read_disk_uname(struct archive *, d113 1 a113 1
int
d121 1 a121 1int
d129 1 a129 1int
d132 1 a132 1archive_read_disk_set_standard_lookup(struct archive *);
d134 1 a134 1int
d141 1 a141 1int
d144 1 a144 1archive_read_disk_descend(struct archive *);
d146 1 a146 1int
d149 1 a149 1archive_read_disk_can_descend(struct archive *);
d151 1 a151 1int
d154 1 a154 1archive_read_disk_current_filesystem(struct archive *);
d156 1 a156 1int
d159 1 a159 1archive_read_disk_current_filesystem_is_synthetic(struct archive *);
d161 1 a161 1int
d164 1 a164 1archive_read_disk_current_filesystem_is_remote(struct archive *);
d166 1 a166 1int
d174 1 a174 1int
d183 1 a183 1These functions provide an API d191 1 a191 1
Allocates and initializes a d198 1 a198 1
Opens the file or directory d205 1 a205 1
Opens the file or directory d212 1 a212 1
Configures various behavior d219 1 a219 1
Skip files and directories with d225 3 a227 4
Mac OS X specific. Read metadata (ACLs and extended attributes) with copyfile(3). By default, metadata is read using copyfile(3).
d231 1 a231 1Do not read Access Control d236 1 a236 1
Do not read file attributes d238 2 a239 3 disk. See chattr(1) (Linux) or chflags(1) (FreeBSD, Mac OS X) for more information on file attributes.
d243 1 a243 1Do not traverse mount points. d248 1 a248 1
Do not read extended file d250 3 a252 4 are read from disk. See xattr(7) (Linux), xattr(2) (Mac OS X), or getextattr(8) (FreeBSD) for more information on extended file attributes.
d256 1 a256 1Restore access time of d262 1 a262 1
Do not read sparse file d271 1 a271 1
This sets the mode used for d282 1 a282 1
Returns a user or group name d290 1 a290 1
These allow you to override the d300 1 a300 1
This convenience function d302 5 a306 5 functions. These functions use getpwuid(3) and getgrgid(3) to convert ids to names, defaulting to NULL if the names cannot be looked up. These functions also implement a simple memory cache to reduce the number of calls to getpwuid(3) and getgrgid(3).
d311 1 a311 1Populates a struct d314 3 a316 3 created with archive_entry_new(3) and at least one of the source path or path fields must already be set. (If both are set, the source path will be used.)
d318 1 a318 1Information is d324 1 a324 1
If a pointer to d333 1 a333 1
Where d342 1 a342 1
If the current entry can be d344 1 a344 1 entry for archive_read_header(3) to visit.
d349 1 a349 1Returns 1 if the current entry d355 1 a355 1
Returns the index of the most d362 1 a362 1
Returns 1 if the current d370 1 a370 1
Returns 1 if the current d378 1 a378 1
Allows the caller to set struct d380 2 a381 3 archive_read_header(3) calls. If matched based on calls to archive_match_path_excluded, archive_match_time_excluded, or d390 7 a396 8
Allows the caller to set a callback function during calls to archive_read_header(3) to filter out metadata for each entry. The callback function receives the struct archive object, void* custom filter data, and the struct archive_entry. If the callback function returns an error, ARCHIVE_RETRY will be returned and the entry will not be further processed.
d398 1 a398 1More information about the d400 1 a400 2 library can be found in the libarchive(3) overview.
d404 1 a404 1The following illustrates basic d408 1 a408 1
void
d417 1
a417 1
ard = d438 1 a438 1
Most functions return d448 1 a448 1
archive_read_disk_new() d453 1 a453 1
archive_read_disk_gname() d463 1 a463 1
Detailed error codes and textual d469 3 a471 4
tar(1), archive_read(3), archive_util(3), archive_write(3), archive_write_disk(3), libarchive(3)
d475 1 a475 1The libarchive library d483 1 a483 1
The libarchive library d489 1 a489 1
The “standard” user d491 4 a494 4 because getgrgid(3) and getpwuid(3) are sometimes too large for particular applications. The current design allows the application author to use a more compact implementation when appropriate.
d496 1 a496 1The full list of d501 1 a501 1
The d508 1 a508 1
This API should d510 6 a515 5 would make it a direct parallel of the archive_read(3) API. When such methods are implemented, the “hybrid” symbolic link mode will make sense. Debian April 3, 2017 ARCHIVE_READ_DISK(3)
@ 1.1.1.15 log @libarchive: imported version 3.7.9 @ text @d2 1 a2 1 @ 1.1.1.16 log @libarchive: import version 3.8.0 Libarchive 3.8.0 is a feature and bugfix release. New features: bsdtar: support --mtime and --clamp-mtime lib: mbedtls 3.x compatibility 7-zip reader: improve self-extracting archive detection xar: xmllite support for the XAR reader and writer zip writer: added XZ, LZMA, ZSTD and BZIP2 support zip writer: added LZMA + RISCV BCJ filter Notable security fixes: rar: do not skip past EOF while reading rar: fix double free with over 4 billion nodes rar: fix heap-buffer-overflow warc: prevent signed integer overflow tar: fix overflow in build_ustar_entry Notable bugfixes: bsdtar: don't hardlink negative inode files together gz: allow setting the original filename for gzip compressed files lib: improve lseek handling lib: support @@-prefixed Unix epoch timestamps as date strings rar: support large headers on 32 bit systems tar reader: Improve LFS support on 32 bit systems @ text @d2 1 a2 1 @ 1.1.1.17 log @libarchive: import version 3.8.1 @ text @d2 1 a2 1 @ 1.1.1.18 log @libarchive: imported version 3.8.2 @ text @d2 1 a2 1 @ 1.1.1.19 log @libarchive: import version 3.8.3 @ text @d2 1 a2 1 @ 1.1.1.20 log @libarchive: import 3.8.4 @ text @d2 1 a2 1 @ 1.1.1.21 log @libarchive: import version 3.8.5 @ text @d2 1 a2 1 @ 1.1.1.22 log @libarchive: imported version 3.8.6 @ text @d2 1 a2 1 @ 1.1.1.23 log @libarchive: imported version 3.8.7 @ text @d2 1 a2 1 @ 1.1.1.24 log @libarchive: import 3.8.8 @ text @d2 1 a2 1 @