ARCHIVE_WRITE_DISK(3) Library Functions Manual ARCHIVE_WRITE_DISK(3)
NAME
archive_write_disk_new, archive_write_disk_set_options, archive_write_disk_set_skip_file, archive_write_disk_set_group_lookup, archive_write_disk_set_standard_lookup, archive_write_disk_set_user_lookup — functions for creating objects on disk
LIBRARY
Streaming Archive Library (libarchive, -larchive)
SYNOPSIS
#include <archive.h>
struct archive *
archive_write_disk_new(void);
int
archive_write_disk_set_options(struct archive *, int flags);
int
archive_write_disk_set_skip_file(struct archive *, dev_t, ino_t);
int
archive_write_disk_set_group_lookup(struct archive *, void *, gid_t (*)(void *, const char *gname, gid_t gid), void (*cleanup)(void *));
int
archive_write_disk_set_standard_lookup(struct archive *);
int
archive_write_disk_set_user_lookup(struct archive *, void *, uid_t (*)(void *, const char *uname, uid_t uid), void (*cleanup)(void *));
DESCRIPTION
These functions provide a complete API for creating objects on disk from struct archive_entry descriptions. They are most naturally used when extracting objects from an archive using the archive_read() interface. The general process is to read struct archive_entry objects from an archive, then write those objects to a struct archive object created using the archive_write_disk() family functions. This interface is deliberately very similar to the archive_write() interface used to write objects to a streaming archive.
archive_write_disk_new()
Allocates and initializes a struct archive object suitable for writing objects to disk.
archive_write_disk_set_skip_file()
Records the device and inode numbers of a file that should not be overwritten. This is typically used to ensure that an extraction process does not overwrite the archive from which objects are being read. This capability is technically unnecessary but can be a significant performance optimization in practice.
archive_write_disk_set_options()
The options field consists of a bitwise OR of one or more of the following values:
ARCHIVE_EXTRACT_ACL
Attempt to restore Access Control Lists. By default, extended ACLs are ignored.
ARCHIVE_EXTRACT_CLEAR_NOCHANGE_FFLAGS
Before removing a file system object prior to replacing it, clear platform-specific file flags which might prevent its removal.
ARCHIVE_EXTRACT_FFLAGS
Attempt to restore file attributes (file flags). By default, file attributes are ignored. See chattr(1) (Linux) or chflags(1) (FreeBSD, Mac OS X) for more information on file attributes.
ARCHIVE_EXTRACT_MAC_METADATA
Mac OS X specific. Restore metadata using copyfile(3). By default, copyfile(3) metadata is ignored.
ARCHIVE_EXTRACT_NO_OVERWRITE
Existing files on disk will not be overwritten. By default, existing regular files are truncated and overwritten; existing directories will have their permissions updated; other pre-existing objects are unlinked and recreated from scratch.
ARCHIVE_EXTRACT_OWNER
The user and group IDs should be set on the restored file. By default, the user and group IDs are not restored.
ARCHIVE_EXTRACT_PERM
Full permissions (including SGID, SUID, and sticky bits) should be restored exactly as specified, without obeying the current umask. Note that SUID and SGID bits can only be restored if the user and group ID of the object on disk are correct. If ARCHIVE_EXTRACT_OWNER is not specified, then SUID and SGID bits will only be restored if the default user and group IDs of newly-created objects on disk happen to match those specified in the archive entry. By default, only basic permissions are restored, and umask is obeyed.
ARCHIVE_EXTRACT_SAFE_WRITES
Extract files atomically, by first creating a unique temporary file and then renaming it to its required destination name. This avoids a race where an application might see a partial file (or no file) during extraction.
ARCHIVE_EXTRACT_SECURE_NOABSOLUTEPATHS
Refuse to extract an absolute path. The default is to not refuse such paths.
ARCHIVE_EXTRACT_SECURE_NODOTDOT
Refuse to extract a path that contains a .. element anywhere within it. The default is to not refuse such paths. Note that paths ending in .. always cause an error, regardless of this flag.
ARCHIVE_EXTRACT_SECURE_SYMLINKS
Refuse to extract any object whose final location would be altered by a symlink on disk. This is intended to help guard against a variety of mischief caused by archives that (deliberately or otherwise) extract files outside of the current directory. The default is not to perform this check. If ARCHIVE_EXTRACT_UNLINK is specified together with this option, the library will remove any intermediate symlinks it finds and return an error only if such symlink could not be removed.
ARCHIVE_EXTRACT_SPARSE
Scan data for blocks of NUL bytes and try to recreate them with holes. This results in sparse files, independent of whether the archive format supports or uses them.
ARCHIVE_EXTRACT_TIME
The timestamps (mtime, ctime, and atime) should be restored. By default, they are ignored. Note that restoring of atime is not currently supported.
ARCHIVE_EXTRACT_UNLINK
Existing files on disk will be unlinked before any attempt to create them. In some cases, this can prove to be a significant performance improvement. By default, existing files are truncated and rewritten, but the file is not recreated. In particular, the default behavior does not break existing hard links.
ARCHIVE_EXTRACT_XATTR
Attempt to restore extended file attributes. By default, they are ignored. See xattr(7) (Linux), xattr(2) (Mac OS X), or getextattr(8) (FreeBSD) for more information on extended file attributes.
archive_write_disk_set_group_lookup(), archive_write_disk_set_user_lookup()
The struct archive_entry objects contain both names and ids that can be used to identify users and groups. These names and ids describe the ownership of the file itself and also appear in ACL lists. By default, the library uses the ids and ignores the names, but this can be overridden by registering user and group lookup functions. To register, you must provide a lookup function which accepts both a name and id and returns a suitable id. 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.
archive_write_disk_set_standard_lookup()
This convenience function installs a standard set of user and group lookup functions. These functions use getpwnam(3) and getgrnam(3) to convert names to ids, defaulting to the ids if the names cannot be looked up. These functions also implement a simple memory cache to reduce the number of calls to getpwnam(3) and getgrnam(3).
More information about the struct archive object and the overall design of the library can be found in the libarchive(3) overview. Many of these functions are also documented under archive_write(3).
RETURN VALUES
Most functions return ARCHIVE_OK (zero) on success, or one of several non-zero 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_write_disk_new() returns a pointer to a newly-allocated struct archive object.
archive_write_data() returns a count of the number of bytes actually written, or -1 on error.
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_write(3), libarchive(3)
HISTORY
The libarchive library first appeared in FreeBSD 5.3. The archive_write_disk interface was added to libarchive 2.0 and first appeared in FreeBSD 6.3.
AUTHORS
The libarchive library was written by Tim Kientzle <kientzle@@acm.org>.
BUGS
Directories are actually extracted in two distinct phases. Directories are created during archive_write_header(), but final permissions are not set until archive_write_close(). This separation is necessary to correctly handle borderline cases such as a non-writable directory containing files, but can cause unexpected results. In particular, directory permissions are not fully restored until the archive is closed. If you use chdir(2) to change the current directory between calls to archive_read_extract() or before calling archive_read_close(), you may confuse the permission-setting logic with the result that directory permissions are restored incorrectly.
The library attempts to create objects with filenames longer than PATH_MAX by creating prefixes of the full path and changing the current directory. Currently, this logic is limited in scope; the fixup pass does not work correctly for such objects and the symlink security check option disables the support for very long pathnames.
Restoring the path aa/../bb does create each intermediate directory. In particular, the directory aa is created as well as the final object bb. In theory, this can be exploited to create an entire directory hierarchy with a single request. Of course, this does not work if the ARCHIVE_EXTRACT_NODOTDOT option is specified.
Implicit directories are always created obeying the current umask. Explicit objects are created obeying the current umask unless ARCHIVE_EXTRACT_PERM is specified, in which case they current umask is ignored.
SGID and SUID bits are restored only if the correct user and group could be set. If ARCHIVE_EXTRACT_OWNER is not specified, then no attempt is made to set the ownership. In this case, SGID and SUID bits are restored only if the user and group of the final object happen to match those specified in the entry.
The “standard” user-id and group-id lookup functions are not the defaults because getgrnam(3) and getpwnam(3) are sometimes too large for particular applications. The current design allows the application author to use a more compact implementation when appropriate.
There should be a corresponding archive_read_disk interface that walks a directory hierarchy and returns archive entry objects. Debian January 19, 2020 ARCHIVE_WRITE_DISK(3)
ARCHIVE_WRITE_DISK(3) BSD Library Functions Manual ARCHIVE_WRITE_DISK(3)
d28 7 a34 7archive_write_disk_new, archive_write_disk_set_options, archive_write_disk_set_skip_file, archive_write_disk_set_group_lookup, archive_write_disk_set_standard_lookup, archive_write_disk_set_user_lookup — functions for creating objects on disk
d38 1 a38 1Streaming Archive Library d43 1 a43 1
#include d46 1 a46 1
struct d50 1 a50 1
archive_write_disk_new(void);
d52 1 a52 1int
d55 1 a55 1archive_write_disk_set_options(struct archive *, d58 1 a58 1
int
d61 1 a61 1archive_write_disk_set_skip_file(struct archive *, d64 1 a64 1
int
d72 1 a72 1int
d75 1 a75 1archive_write_disk_set_standard_lookup(struct archive *);
d77 1 a77 1int
d87 1 a87 1These functions provide a d102 1 a102 1
Allocates and initializes a d109 1 a109 1
Records the device and inode d119 1 a119 1
The options field consists of a d124 1 a124 1
Attempt to restore Access d129 1 a129 1
Before removing a file system d135 1 a135 1
Attempt to restore file d137 3 a139 2 ignored. See chattr(1) (Linux) or chflags(1) (FreeBSD, Mac OS X) for more information on file attributes.
d143 3 a145 3Mac OS X specific. Restore metadata using copyfile(3). By default, copyfile(3) metadata is ignored.
d149 1 a149 1Existing files on disk will not d157 1 a157 1
The user and group IDs should d163 1 a163 1
Full permissions (including d176 1 a176 1
Extract files atomically, by d184 1 a184 1
Refuse to extract an absolute d189 1 a189 1
Refuse to extract a path that d197 1 a197 1
Refuse to extract any object d209 1 a209 1
Scan data for blocks of NUL d216 1 a216 1
The timestamps (mtime, ctime, d222 1 a222 1
Existing files on disk will be d231 5 a235 4
Attempt to restore extended file attributes. By default, they are ignored. See xattr(7) (Linux), xattr(2) (Mac OS X), or getextattr(8) (FreeBSD) for more information on extended file attributes.
d241 1 a241 1The struct archive_entry d257 1 a257 1
This convenience function d259 5 a263 5 These functions use getpwnam(3) and getgrnam(3) to convert names to ids, defaulting to the ids if the names cannot be looked up. These functions also implement a simple memory cache to reduce the number of calls to getpwnam(3) and getgrnam(3).
d265 1 a265 1More information about the d267 3 a269 3 library can be found in the libarchive(3) overview. Many of these functions are also documented under archive_write(3).
d273 1 a273 1Most functions return d283 1 a283 1
archive_write_disk_new() d288 1 a288 1
archive_write_data() d290 1 a290 1 -1 on error.
d294 1 a294 1Detailed error codes and textual d300 3 a302 2
tar(1), archive_read(3), archive_write(3), libarchive(3)
d306 1 a306 1The libarchive library d314 1 a314 1
The libarchive library d319 1 a319 1
Directories are actually d327 4 a330 4 closed. If you use chdir(2) to change the current directory between calls to archive_read_extract() or before calling archive_read_close(), you may confuse the permission-setting logic with the result that directory d333 1 a333 1
The library d341 1 a341 1
Restoring the d349 1 a349 1
Implicit d355 1 a355 1
SGID and SUID d363 1 a363 1
The d365 5 a369 4 are not the defaults because getgrnam(3) and getpwnam(3) are sometimes too large for particular applications. The current design allows the application author to use a more compact implementation when appropriate.
d371 1 a371 1There should be d374 2 a375 4 objects.
BSD January 19, 2020 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 @ 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 d201 4 a204 1 to perform this check. If d211 1 a211 4 supports or uses them. ARCHIVE_EXTRACT_UNLINK is specified together with this option, the library will remove any intermediate symlinks it finds and return an error only if such symlink could not be removed. d361 5 a365 6 ’’standard’’ user-id and group-id lookup functions are not the defaults because getgrnam(3) and getpwnam(3) are sometimes too large for particular applications. The current design allows the application author to use a more compact implementation when appropriate. @ 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 d173 8 d298 2 a299 2archive_read(3), archive_write(3), tar(1), libarchive(3)
d361 6 a366 5 “standard” user-id and group-id lookup functions are not the defaults because getgrnam(3) and getpwnam(3) are sometimes too large for particular applications. The current design allows the application author to use a more compact implementation when appropriate. d374 1 a374 1 April 3, 2017 BSD @ 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 d353 5 a357 6 ’’standard’’ user-id and group-id lookup functions are not the defaults because getgrnam(3) and getpwnam(3) are sometimes too large for particular applications. The current design allows the application author to use a more compact implementation when appropriate. @ 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 d33 2 a34 7 archive_write_disk_set_user_lookup, archive_write_header, archive_write_data, archive_write_data_block, archive_write_finish_entry, archive_write_close, archive_write_finish archive_write_free — functions for creating objects on disk a84 41int
archive_write_header(struct archive *, struct archive_entry *);
la_ssize_t
archive_write_data(struct archive *, const void *, size_t);
la_ssize_t
archive_write_data_block(struct archive *, const void *, size_t size, int64_t offset);
int
archive_write_finish_entry(struct archive *);
int
archive_write_close(struct archive *);
int
archive_write_finish(struct archive *);
int
archive_write_free(struct archive *);
d122 32 d173 1 a173 1ARCHIVE_EXTRACT_TIME
d175 2 a176 3The timestamps (mtime, ctime, and atime) should be restored. By default, they are ignored. Note that restoring of atime is not currently supported.
d178 1 a178 1ARCHIVE_EXTRACT_NO_OVERWRITE
d180 5 a184 29Existing files on disk will not be overwritten. By default, existing regular files are truncated and overwritten; existing directories will have their permissions updated; other pre-existing objects are unlinked and recreated from scratch.
ARCHIVE_EXTRACT_UNLINK
Existing files on disk will be unlinked before any attempt to create them. In some cases, this can prove to be a significant performance improvement. By default, existing files are truncated and rewritten, but the file is not recreated. In particular, the default behavior does not break existing hard links.
ARCHIVE_EXTRACT_ACL
Attempt to restore ACLs. By default, extended ACLs are ignored.
ARCHIVE_EXTRACT_FFLAGS
Attempt to restore extended file flags. By default, file flags are ignored.
ARCHIVE_EXTRACT_XATTR
Attempt to restore POSIX.1e extended attributes. By default, they are ignored.
d193 8 a200 1 to perform this check. If ARCHIVE_EXTRACT_UNLINK is d205 1 a205 1ARCHIVE_EXTRACT_SECURE_NODOTDOT
d207 3 a209 5Refuse to extract a path that contains a .. element anywhere within it. The default is to not refuse such paths. Note that paths ending in .. always cause an error, regardless of this flag.
d211 1 a211 1ARCHIVE_EXTRACT_SECURE_NOABSOLUTEPATHS
d213 6 a218 2Refuse to extract an absolute path. The default is to not refuse such paths.
d220 1 a220 1ARCHIVE_EXTRACT_SPARSE
d222 4 a225 10Scan data for blocks of NUL bytes and try to recreate them with holes. This results in sparse files, independent of whether the archive format supports or uses them.
ARCHIVE_EXTRACT_CLEAR_NOCHANGE_FFLAGS
Before removing a file system object prior to replacing it, clear platform-specific file flags which might prevent its removal.
a254 64archive_write_header()
Build and write a header using the data in the provided struct archive_entry structure. See archive_entry(3) for information on creating and populating struct archive_entry objects.
archive_write_data()
Write data corresponding to the header just written. Returns number of bytes written or -1 on error.
archive_write_data_block()
Write data corresponding to the header just written. This is like archive_write_data() except that it performs a seek on the file being written to the specified offset before writing the data. This is useful when restoring sparse files from archive formats that support sparse files. Returns number of bytes written or -1 on error. (Note: This is currently not supported for archive_write handles, only for archive_write_disk handles.)
archive_write_finish_entry()
Close out the entry just written. Ordinarily, clients never need to call this, as it is called automatically by archive_write_next_header() and archive_write_close() as needed. However, some file attributes are written to disk only after the file is closed, so this can be necessary if you need to work with the file on disk right away.
archive_write_close()
Set any attributes that could not be set during the initial restore. For example, directory timestamps are not restored initially because restoring a subsequent file would alter that timestamp. Similarly, non-writable directories are initially created with write permissions (so that their contents can be restored). The archive_write_disk_new library maintains a list of all such deferred attributes and sets them when this function is invoked.
archive_write_finish()
This is a deprecated synonym for archive_write_free().
archive_write_free()
Invokes archive_write_close() if it was not invoked manually, then releases all resources.
d353 1 a353 1 ‘‘standard’’ user-id and group-id d366 1 a366 1 February 2, 2012 BSD @ 1.3 log @Update for libarchive 3.2.1. @ text @d2 1 a2 1 d453 1 a453 1 ’’standard’’ user-id and group-id @ 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 d97 1 a97 1ssize_t
d104 1 a104 1ssize_t
d245 5 d257 6 d404 1 a404 2 was written by Tim Kientzle ⟨ kientzle@@acm.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_write_disk(3) FreeBSD Library Functions Manual archive_write_disk(3)
d26 1 a26 1NAME
d28 1 a28 1archive_write_disk_new, d35 1 d37 3 a39 2 archive_write_close, archive_write_finish — functions for creating objects on disk
d41 1 d43 2 a44 1SYNOPSIS
d46 3 a48 1#include d51 1 a51 1
struct d55 1 a55 1
archive_write_disk_new(void);
d57 1 a57 1int
d60 1 a60 1archive_write_disk_set_options(struct archive *, d63 1 a63 1
int
d66 1 a66 1archive_write_disk_set_skip_file(struct archive *, d69 1 a69 1
int
d72 1 a72 1archive_write_disk_set_group_lookup(struct archive *, d77 1 a77 1
int
d80 1 a80 1archive_write_disk_set_standard_lookup(struct archive *);
d82 1 a82 1int
d85 1 a85 1archive_write_disk_set_user_lookup(struct archive *, d90 1 a90 1
int
d93 1 a93 1archive_write_header(struct archive *, d97 1 a97 1
ssize_t
d100 1 a100 1archive_write_data(struct archive *, a102 1
int
d104 8 a112 1archive_write_finish_entry(struct archive *);
d114 1 a114 1int
d116 1 a117 1archive_write_close(struct archive *);
d119 1 a119 1int
d121 1 a122 1archive_write_finish(struct archive *);
d124 1 d126 1 a126 1DESCRIPTION
d128 6 a133 1These functions provide a d146 1 a146 1
archive_write_disk_new()
d148 1 a148 1Allocates and initializes a d153 1 a153 1
archive_write_disk_set_skip_file()
d155 1 a155 1Records the device and inode d163 1 a163 1
archive_write_disk_set_options()
d165 1 a165 1The options field consists of a d168 1 a168 1
ARCHIVE_EXTRACT_OWNER
d170 1 a170 1The user and group IDs should d174 1 a174 1
ARCHIVE_EXTRACT_PERM
d176 1 a176 1Full permissions (including d187 1 a187 1
ARCHIVE_EXTRACT_TIME
d189 1 a189 1The timestamps (mtime, ctime, d193 1 a193 1
ARCHIVE_EXTRACT_NO_OVERWRITE
d195 1 a195 1Existing files on disk will not d201 1 a201 1
ARCHIVE_EXTRACT_UNLINK
d203 1 a203 1Existing files on disk will be d210 1 a210 1
ARCHIVE_EXTRACT_ACL
d212 1 a212 1Attempt to restore ACLs. By d215 1 a215 1
ARCHIVE_EXTRACT_FFLAGS
d217 1 a217 1Attempt to restore extended d220 1 a220 1
ARCHIVE_EXTRACT_XATTR
d222 1 a222 1Attempt to restore POSIX.1e d225 1 a225 1
ARCHIVE_EXTRACT_SECURE_SYMLINKS
d227 1 a227 1Refuse to extract any object d237 1 a237 1
ARCHIVE_EXTRACT_SECURE_NODOTDOT
d239 1 a239 1Refuse to extract a path that d245 1 a245 1
ARCHIVE_EXTRACT_SPARSE
d247 1 a247 1Scan data for blocks of NUL d253 1 a253 1
archive_write_disk_set_group_lookup(), d256 1 a256 1
The struct archive_entry d270 1 a270 1
archive_write_disk_set_standard_lookup()
d272 1 a272 1This convenience function d281 1 a281 1
archive_write_header()
d283 1 a283 1Build and write a header using d288 1 d290 1 a290 3
archive_write_data()
Write data corresponding to the d295 1 a295 1
archive_write_finish_entry()
d297 14 a310 1Close out the entry just d314 4 a317 1 archive_write_close() as needed.
d320 1 a320 1archive_write_close()
d322 1 a322 1Set any attributes that could d333 4 a336 1
archive_write_finish()
d338 3 a340 1Invokes d344 1 a344 1
More information about the d350 1 a350 2
RETURN VALUES
d352 1 a352 1Most functions return d359 1 a359 4 operations impossible. The archive_errno() and archive_error_string() functions can be used to retrieve an appropriate error code and a textual error message.
d362 1 a362 1archive_write_disk_new() d367 5 a371 5
archive_write_data() returns a count of the number of bytes actually written. On error, -1 is returned and the archive_errno() and archive_error_string() functions will return appropriate values.
d373 3 a375 1SEE ALSO
d377 3 a379 1archive_read(3), d382 1 a382 1
HISTORY
d384 1 a384 1The libarchive library d390 1 a390 1
AUTHORS
d392 3 a394 3The libarchive library was written by Tim Kientzle ⟨kientzle@@acm.org⟩.
d396 1 a396 1BUGS
d398 1 a398 1Directories are actually d412 1 a412 1
The library d420 1 a420 1
Restoring the d424 1 a424 1 be exploited to create an entire directory heirarchy with a d428 1 a428 1
Implicit d434 1 a434 1
SGID and SUID d442 2 a443 2
The ‘‘standard’’ user-id and group-id d450 1 a450 1
There should be d452 1 a452 1 walks a directory heirarchy and returns archive entry d455 2 a456 3
FreeBSD 8.0 August 5, 2008 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 421 a421 892 %!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: 63 %%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 12 Q -.15(ve)
-.25 G( *).15 E(archi)0 24 Q -.15(ve)-.25 G
(_write_disk_ne).15 E(w\(v)-.25 E(oid\))
-.2 E(int)0 36 Q(archi)0 48 Q -.15
(ve)-.25 G(_write_disk_set_options\(struct archi)
.15 E .3 -.15(ve *)-.25 H(, int \215ags\)).15 E
(int)0 60 Q(archi)0 72 Q -.15(ve)
-.25 G(_write_disk_set_skip_\214le\(struct archi)
.15 E .3 -.15(ve *)-.25 H(, de).15 E
(v_t, ino_t\))-.25 E 0 Cg EP
%%Page: 8 8
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(int)0 12 Q
(archi)0 24 Q -.15(ve)-.25 G
(_write_disk_set_group_lookup\(struct archi)0 36 Q .3 -.15(ve *)-.25 H().15
E(v)0 48 Q(oid *)-.2 E
(v)0 72 Q
(oid \(*cleanup\)\(v)-.2 E(oid *\))-.2 E 0 Cg EP
%%Page: 9 9
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(\))0 12 Q(int)
0 24 Q(archi)0 36 Q -.15(ve)-.25 G
(_write_disk_set_standard_lookup\(struct archi)
.15 E .3 -.15(ve *)-.25 H(\)).15 E
(int)0 48 Q(archi)0 60 Q -.15(ve)
-.25 G(_write_disk_set_user_lookup\(struct archi)0 72 Q .3 -.15(ve *)-.25 H().15
E 0 Cg EP
%%Page: 10 10
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(v)0 12 Q(oid *)-.2 E
(v)0 36 Q
(oid \(*cleanup\)\(v)-.2 E(oid *\))-.2 E(\))0 48 Q
(int)0 60 Q(archi)0 72 Q -.15(ve)
-.25 G(_write_header\(struct archi).15 E .3 -.15
(ve *)-.25 H(, struct archi).15 E -.15(ve)-.25 G
(_entry *\)).15 E 0 Cg EP
%%Page: 11 11
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(ssize_t)0 12 Q
(archi)0 24 Q -.15(ve)-.25 G
(_write_data\(struct archi).15 E .3 -.15(ve *)
-.25 H(, const v).15 E(oid *, size_t\))
-.2 E(int)0 36 Q(archi)0 48 Q -.15
(ve)-.25 G(_write_\214nish_entry\(struct archi)
.15 E .3 -.15(ve *)-.25 H(\)).15 E
(int)0 60 Q(archi)0 72 Q -.15(ve)
-.25 G(_write_close\(struct archi).15 E .3 -.15
(ve *)-.25 H(\)).15 E 0 Cg EP
%%Page: 12 12
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(int)0 12 Q
(archi)0 24 Q -.15(ve)-.25 G
(_write_\214nish\(struct archi).15 E .3 -.15
(ve *)-.25 H(\)).15 E(..)0 48
Q(element an)0 60 Q(ywhere within it.)-.15 E(The def)0 72 Q
(ault is to not refuse such paths.)-.1 E 0 Cg EP
%%Page: 28 28
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(Note that paths ending in)0 12 Q
(..)0 24 Q(al)0 36 Q -.1(wa)-.1 G
(ys cause an error).1 E 2.5(,r)-.4 G -2.25 -.15(eg a)-2.5 H
(rdless of this \215ag.).15 E()36 36 Q(archi)0 48 Q -.15(ve)-.25 G
(_write_disk_ne).15 E(w\(\))-.25 E
(returns a pointer to a ne)0 60 Q(wly-allocated)-.25 E(\
struct archi)0 72 Q -.15
(ve)-.25 G().15 E 0 Cg EP
%%Page: 46 46
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(object.)0 12 Q(
)36 24 Q(archi)0 36 Q -.15
(ve)-.25 G(_write_data\(\)).15 E
(returns a count of the number of bytes actually written.)0 48 Q
(On error)0 60 Q 2.5(,-)-.4 G 2.5(1i)-2.5 G 2.5(sr)-2.5 G
(eturned and the)-2.5 E(archi)0 72 Q -.15(ve)-.25 G
(_errno\(\)).15 E 0 Cg EP
%%Page: 47 47
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(and)0 12 Q(archi)0 24 Q -.15(ve)-.25 G
(_error_string\(\)).15 E
(functions will return appropriate v)0 36 Q(alues.)-.25 E
(
)36 36 Q(The)0 48 Q(libarchi)0 60 Q -.15(ve)-.25 G().15 E(library w)0 72 Q(as written by)-.1 E 0 Cg EP %%Page: 52 52 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF -.35(Ti)0 12 S 2.5(mK).35 G (ientzle <kientzle@@acm.or)-2.5 E(g>.)-.18 E(
)36 72 Q 0 Cg EP %%Page: 56 56 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF (The library attempts to create objects with \214lenames longer than)0 12 Q(P)0 24 Q -1.11(AT)-.92 G(H_MAX)1.11 E (by creating pre\214x)0 36 Q (es of the full path and changing the current directory)-.15 E(.)-.65 E (Currently)0 48 Q 2.5(,t)-.65 G (his logic is limited in scope; the \214xup pass does)-2.5 E(not w)0 60 Q(ork correctly for such objects and the symlink security check)-.1 E (option disables the support for v)0 72 Q(ery long pathnames.)-.15 E 0 Cg EP %%Page: 57 57 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF(
)36 12 Q(Restoring the path)0 24 Q
(aa/../bb)0 36 Q
(does create each intermediate directory)0 48 Q(.)-.65 E(In particular)0
60 Q 2.5(,t)-.4 G(he directory)-2.5 E(aa)0 72
Q 0 Cg EP
%%Page: 58 58
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(is created as well as the \214nal object)0 12 Q
(bb.)0 24 Q(In theory)0 36 Q 2.5(,t)-.65 G
(his can be e)-2.5 E(xploited to create an entire directory heirarch)
-.15 E(y)-.05 E(with a single request.)0 48 Q
(Of course, this does not w)0 60 Q(ork if the)-.1 E
(ARCHIVE_EXTRA)0 72 Q(CT_NODO)-.4 E(TDO)-.4 E(T)-.4 E 0 Cg
EP
%%Page: 59 59
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(option is speci\214ed.)0 12 Q(
)36 24 Q (Implicit directories are al)0 36 Q -.1(wa)-.1 G(ys created obe).1 E (ying the current umask.)-.15 E(Explicit objects are created obe)0 48 Q (ying the current umask unless)-.15 E(ARCHIVE_EXTRA)0 60 Q (CT_PERM)-.4 E(is speci\214ed, in which case the)0 72 Q 2.5(yc)-.15 G(urrent umask is ignored.)-2.5 E 0 Cg EP %%Page: 60 60 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF(
)36 12 Q (SGID and SUID bits are restored only if the correct user and)0 24 Q (group could be set.)0 36 Q(If)0 48 Q(ARCHIVE_EXTRA)0 60 Q (CT_O)-.4 E(WNER)-.35 E (is not speci\214ed, then no attempt is made to set the o)0 72 Q (wnership.)-.25 E 0 Cg EP %%Page: 61 61 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF (In this case, SGID and SUID bits are restored only if the)0 12 Q (user and group of the \214nal object happen to match those speci\214ed) 0 24 Q(in the entry)0 36 Q(.)-.65 E(
)36 48 Q(The)0 60 Q -.74(``)0 72 S(standard').74 E(')-.74 E 0 Cg EP %%Page: 62 62 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF(user)0 12 Q (-id and group-id lookup functions are not the def)-.2 E(aults because) -.1 E(getgrnam\(3\))0 24 Q(and)0 36 Q(getpwnam\(3\))0 48 Q (are sometimes too lar)0 60 Q(ge for particular applications.)-.18 E (The current design allo)0 72 Q(ws the application author to use a more) -.25 E 0 Cg EP %%Page: 63 63 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF(compact implementation when appropriate.)0 12 Q (
)36 24 Q(There should be a corresponding)0 36 Q(archi)0 48 Q -.15 (ve)-.25 G(_read_disk).15 E(interf)0 60 Q(ace that w)-.1 E (alks a directory heirarch)-.1 E 2.5(ya)-.05 G(nd returns archi)-2.5 E -.15(ve)-.25 G(entry objects.)0 72 Q 0 Cg EP %%Trailer end %%EOF @ 1.1.1.3 log @libarchive-2.8.3: Build fix for Linux @ text @d1 892 a892 421
archive_write_disk(3) FreeBSD Library Functions Manual archive_write_disk(3)
NAME
archive_write_disk_new, archive_write_disk_set_options, archive_write_disk_set_skip_file, archive_write_disk_set_group_lookup, archive_write_disk_set_standard_lookup, archive_write_disk_set_user_lookup, archive_write_header, archive_write_data, archive_write_finish_entry, archive_write_close, archive_write_finish — functions for creating objects on disk
SYNOPSIS
#include <archive.h>
struct archive *
archive_write_disk_new(void);
int
archive_write_disk_set_options(struct archive *, int flags);
int
archive_write_disk_set_skip_file(struct archive *, dev_t, ino_t);
int
archive_write_disk_set_group_lookup(struct archive *, void *, gid_t (*)(void *, const char *gname, gid_t gid), void (*cleanup)(void *));
int
archive_write_disk_set_standard_lookup(struct archive *);
int
archive_write_disk_set_user_lookup(struct archive *, void *, uid_t (*)(void *, const char *uname, uid_t uid), void (*cleanup)(void *));
int
archive_write_header(struct archive *, struct archive_entry *);
ssize_t
archive_write_data(struct archive *, const void *, size_t);
int
archive_write_finish_entry(struct archive *);
int
archive_write_close(struct archive *);
int
archive_write_finish(struct archive *);
DESCRIPTION
These functions provide a complete API for creating objects on disk from struct archive_entry descriptions. They are most naturally used when extracting objects from an archive using the archive_read() interface. The general process is to read struct archive_entry objects from an archive, then write those objects to a struct archive object created using the archive_write_disk() family functions. This interface is deliberately very similar to the archive_write() interface used to write objects to a streaming archive.
archive_write_disk_new()
Allocates and initializes a struct archive object suitable for writing objects to disk.
archive_write_disk_set_skip_file()
Records the device and inode numbers of a file that should not be overwritten. This is typically used to ensure that an extraction process does not overwrite the archive from which objects are being read. This capability is technically unnecessary but can be a significant performance optimization in practice.
archive_write_disk_set_options()
The options field consists of a bitwise OR of one or more of the following values:
ARCHIVE_EXTRACT_OWNER
The user and group IDs should be set on the restored file. By default, the user and group IDs are not restored.
ARCHIVE_EXTRACT_PERM
Full permissions (including SGID, SUID, and sticky bits) should be restored exactly as specified, without obeying the current umask. Note that SUID and SGID bits can only be restored if the user and group ID of the object on disk are correct. If ARCHIVE_EXTRACT_OWNER is not specified, then SUID and SGID bits will only be restored if the default user and group IDs of newly-created objects on disk happen to match those specified in the archive entry. By default, only basic permissions are restored, and umask is obeyed.
ARCHIVE_EXTRACT_TIME
The timestamps (mtime, ctime, and atime) should be restored. By default, they are ignored. Note that restoring of atime is not currently supported.
ARCHIVE_EXTRACT_NO_OVERWRITE
Existing files on disk will not be overwritten. By default, existing regular files are truncated and overwritten; existing directories will have their permissions updated; other pre-existing objects are unlinked and recreated from scratch.
ARCHIVE_EXTRACT_UNLINK
Existing files on disk will be unlinked before any attempt to create them. In some cases, this can prove to be a significant performance improvement. By default, existing files are truncated and rewritten, but the file is not recreated. In particular, the default behavior does not break existing hard links.
ARCHIVE_EXTRACT_ACL
Attempt to restore ACLs. By default, extended ACLs are ignored.
ARCHIVE_EXTRACT_FFLAGS
Attempt to restore extended file flags. By default, file flags are ignored.
ARCHIVE_EXTRACT_XATTR
Attempt to restore POSIX.1e extended attributes. By default, they are ignored.
ARCHIVE_EXTRACT_SECURE_SYMLINKS
Refuse to extract any object whose final location would be altered by a symlink on disk. This is intended to help guard against a variety of mischief caused by archives that (deliberately or otherwise) extract files outside of the current directory. The default is not to perform this check. If ARCHIVE_EXTRACT_UNLINK is specified together with this option, the library will remove any intermediate symlinks it finds and return an error only if such symlink could not be removed.
ARCHIVE_EXTRACT_SECURE_NODOTDOT
Refuse to extract a path that contains a .. element anywhere within it. The default is to not refuse such paths. Note that paths ending in .. always cause an error, regardless of this flag.
ARCHIVE_EXTRACT_SPARSE
Scan data for blocks of NUL bytes and try to recreate them with holes. This results in sparse files, independent of whether the archive format supports or uses them.
archive_write_disk_set_group_lookup(), archive_write_disk_set_user_lookup()
The struct archive_entry objects contain both names and ids that can be used to identify users and groups. These names and ids describe the ownership of the file itself and also appear in ACL lists. By default, the library uses the ids and ignores the names, but this can be overridden by registering user and group lookup functions. To register, you must provide a lookup function which accepts both a name and id and returns a suitable id. 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.
archive_write_disk_set_standard_lookup()
This convenience function installs a standard set of user and group lookup functions. These functions use getpwnam(3) and getgrnam(3) to convert names to ids, defaulting to the ids if the names cannot be looked up. These functions also implement a simple memory cache to reduce the number of calls to getpwnam(3) and getgrnam(3).
archive_write_header()
Build and write a header using the data in the provided struct archive_entry structure. See archive_entry(3) for information on creating and populating struct archive_entry objects.
archive_write_data()
Write data corresponding to the header just written. Returns number of bytes written or -1 on error.
archive_write_finish_entry()
Close out the entry just written. Ordinarily, clients never need to call this, as it is called automatically by archive_write_next_header() and archive_write_close() as needed.
archive_write_close()
Set any attributes that could not be set during the initial restore. For example, directory timestamps are not restored initially because restoring a subsequent file would alter that timestamp. Similarly, non-writable directories are initially created with write permissions (so that their contents can be restored). The archive_write_disk_new library maintains a list of all such deferred attributes and sets them when this function is invoked.
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. Many of these functions are also documented under archive_write(3).
RETURN VALUES
Most functions return ARCHIVE_OK (zero) on success, or one of several non-zero 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() and archive_error_string() functions can be used to retrieve an appropriate error code and a textual error message.
archive_write_disk_new() returns a pointer to a newly-allocated struct archive object.
archive_write_data() returns a count of the number of bytes actually written. On error, -1 is returned and the archive_errno() and archive_error_string() functions will return appropriate values.
SEE ALSO
archive_read(3), archive_write(3), tar(1), libarchive(3)
HISTORY
The libarchive library first appeared in FreeBSD 5.3. The archive_write_disk interface was added to libarchive 2.0 and first appeared in FreeBSD 6.3.
AUTHORS
The libarchive library was written by Tim Kientzle ⟨kientzle@@acm.org⟩.
BUGS
Directories are actually extracted in two distinct phases. Directories are created during archive_write_header(), but final permissions are not set until archive_write_close(). This separation is necessary to correctly handle borderline cases such as a non-writable directory containing files, but can cause unexpected results. In particular, directory permissions are not fully restored until the archive is closed. If you use chdir(2) to change the current directory between calls to archive_read_extract() or before calling archive_read_close(), you may confuse the permission-setting logic with the result that directory permissions are restored incorrectly.
The library attempts to create objects with filenames longer than PATH_MAX by creating prefixes of the full path and changing the current directory. Currently, this logic is limited in scope; the fixup pass does not work correctly for such objects and the symlink security check option disables the support for very long pathnames.
Restoring the path aa/../bb does create each intermediate directory. In particular, the directory aa is created as well as the final object bb. In theory, this can be exploited to create an entire directory heirarchy with a single request. Of course, this does not work if the ARCHIVE_EXTRACT_NODOTDOT option is specified.
Implicit directories are always created obeying the current umask. Explicit objects are created obeying the current umask unless ARCHIVE_EXTRACT_PERM is specified, in which case they current umask is ignored.
SGID and SUID bits are restored only if the correct user and group could be set. If ARCHIVE_EXTRACT_OWNER is not specified, then no attempt is made to set the ownership. In this case, SGID and SUID bits are restored only if the user and group of the final object happen to match those specified in the entry.
The ‘‘standard’’ user-id and group-id lookup functions are not the defaults because getgrnam(3) and getpwnam(3) are sometimes too large for particular applications. The current design allows the application author to use a more compact implementation when appropriate.
There should be a corresponding archive_read_disk interface that walks a directory heirarchy and returns archive entry objects.
FreeBSD 9.0 August 5, 2008 FreeBSD 9.0
struct archi)0 12 Q -.15(ve)
-.25 G( *).15 E(archi)0 24 Q -.15(ve)-.25 G
(_write_disk_ne).15 E(w\(v)-.25 E(oid\))
-.2 E(int)0 36 Q(archi)0 48 Q -.15
(ve)-.25 G(_write_disk_set_options\(struct archi)
.15 E .3 -.15(ve *)-.25 H(, int \215ags\)).15 E
(int)0 60 Q(archi)0 72 Q -.15(ve)
-.25 G(_write_disk_set_skip_\214le\(struct archi)
.15 E .3 -.15(ve *)-.25 H(, de).15 E
(v_t, ino_t\))-.25 E 0 Cg EP
%%Page: 8 8
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(int)0 12 Q
(archi)0 24 Q -.15(ve)-.25 G
(_write_disk_set_group_lookup\(struct archi)0 36 Q .3 -.15(ve *)-.25 H().15
E(v)0 48 Q(oid *)-.2 E
(v)0 72 Q
(oid \(*cleanup\)\(v)-.2 E(oid *\))-.2 E 0 Cg EP
%%Page: 9 9
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(\))0 12 Q(int)
0 24 Q(archi)0 36 Q -.15(ve)-.25 G
(_write_disk_set_standard_lookup\(struct archi)
.15 E .3 -.15(ve *)-.25 H(\)).15 E
(int)0 48 Q(archi)0 60 Q -.15(ve)
-.25 G(_write_disk_set_user_lookup\(struct archi)0 72 Q .3 -.15(ve *)-.25 H().15
E 0 Cg EP
%%Page: 10 10
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(v)0 12 Q(oid *)-.2 E
(v)0 36 Q
(oid \(*cleanup\)\(v)-.2 E(oid *\))-.2 E(\))0 48 Q
(int)0 60 Q(archi)0 72 Q -.15(ve)
-.25 G(_write_header\(struct archi).15 E .3 -.15
(ve *)-.25 H(, struct archi).15 E -.15(ve)-.25 G
(_entry *\)).15 E 0 Cg EP
%%Page: 11 11
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(ssize_t)0 12 Q
(archi)0 24 Q -.15(ve)-.25 G
(_write_data\(struct archi).15 E .3 -.15(ve *)
-.25 H(, const v).15 E(oid *, size_t\))
-.2 E(int)0 36 Q(archi)0 48 Q -.15
(ve)-.25 G(_write_\214nish_entry\(struct archi)
.15 E .3 -.15(ve *)-.25 H(\)).15 E
(int)0 60 Q(archi)0 72 Q -.15(ve)
-.25 G(_write_close\(struct archi).15 E .3 -.15
(ve *)-.25 H(\)).15 E 0 Cg EP
%%Page: 12 12
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(int)0 12 Q
(archi)0 24 Q -.15(ve)-.25 G
(_write_\214nish\(struct archi).15 E .3 -.15
(ve *)-.25 H(\)).15 E(..)0 48
Q(element an)0 60 Q(ywhere within it.)-.15 E(The def)0 72 Q
(ault is to not refuse such paths.)-.1 E 0 Cg EP
%%Page: 28 28
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(Note that paths ending in)0 12 Q
(..)0 24 Q(al)0 36 Q -.1(wa)-.1 G
(ys cause an error).1 E 2.5(,r)-.4 G -2.25 -.15(eg a)-2.5 H
(rdless of this \215ag.).15 E()36 36 Q(archi)0 48 Q -.15(ve)-.25 G
(_write_disk_ne).15 E(w\(\))-.25 E
(returns a pointer to a ne)0 60 Q(wly-allocated)-.25 E(\
struct archi)0 72 Q -.15
(ve)-.25 G().15 E 0 Cg EP
%%Page: 46 46
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(object.)0 12 Q(
)36 24 Q(archi)0 36 Q -.15
(ve)-.25 G(_write_data\(\)).15 E
(returns a count of the number of bytes actually written.)0 48 Q
(On error)0 60 Q 2.5(,-)-.4 G 2.5(1i)-2.5 G 2.5(sr)-2.5 G
(eturned and the)-2.5 E(archi)0 72 Q -.15(ve)-.25 G
(_errno\(\)).15 E 0 Cg EP
%%Page: 47 47
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(and)0 12 Q(archi)0 24 Q -.15(ve)-.25 G
(_error_string\(\)).15 E
(functions will return appropriate v)0 36 Q(alues.)-.25 E
(
)36 36 Q(The)0 48 Q(libarchi)0 60 Q -.15(ve)-.25 G().15 E(library w)0 72 Q(as written by)-.1 E 0 Cg EP %%Page: 52 52 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF -.35(Ti)0 12 S 2.5(mK).35 G (ientzle <kientzle@@acm.or)-2.5 E(g>.)-.18 E(
)36 72 Q 0 Cg EP %%Page: 56 56 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF (The library attempts to create objects with \214lenames longer than)0 12 Q(P)0 24 Q -1.11(AT)-.92 G(H_MAX)1.11 E (by creating pre\214x)0 36 Q (es of the full path and changing the current directory)-.15 E(.)-.65 E (Currently)0 48 Q 2.5(,t)-.65 G (his logic is limited in scope; the \214xup pass does)-2.5 E(not w)0 60 Q(ork correctly for such objects and the symlink security check)-.1 E (option disables the support for v)0 72 Q(ery long pathnames.)-.15 E 0 Cg EP %%Page: 57 57 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF(
)36 12 Q(Restoring the path)0 24 Q
(aa/../bb)0 36 Q
(does create each intermediate directory)0 48 Q(.)-.65 E(In particular)0
60 Q 2.5(,t)-.4 G(he directory)-2.5 E(aa)0 72
Q 0 Cg EP
%%Page: 58 58
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(is created as well as the \214nal object)0 12 Q
(bb.)0 24 Q(In theory)0 36 Q 2.5(,t)-.65 G
(his can be e)-2.5 E(xploited to create an entire directory heirarch)
-.15 E(y)-.05 E(with a single request.)0 48 Q
(Of course, this does not w)0 60 Q(ork if the)-.1 E
(ARCHIVE_EXTRA)0 72 Q(CT_NODO)-.4 E(TDO)-.4 E(T)-.4 E 0 Cg
EP
%%Page: 59 59
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(option is speci\214ed.)0 12 Q(
)36 24 Q (Implicit directories are al)0 36 Q -.1(wa)-.1 G(ys created obe).1 E (ying the current umask.)-.15 E(Explicit objects are created obe)0 48 Q (ying the current umask unless)-.15 E(ARCHIVE_EXTRA)0 60 Q (CT_PERM)-.4 E(is speci\214ed, in which case the)0 72 Q 2.5(yc)-.15 G(urrent umask is ignored.)-2.5 E 0 Cg EP %%Page: 60 60 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF(
)36 12 Q (SGID and SUID bits are restored only if the correct user and)0 24 Q (group could be set.)0 36 Q(If)0 48 Q(ARCHIVE_EXTRA)0 60 Q (CT_O)-.4 E(WNER)-.35 E (is not speci\214ed, then no attempt is made to set the o)0 72 Q (wnership.)-.25 E 0 Cg EP %%Page: 61 61 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF (In this case, SGID and SUID bits are restored only if the)0 12 Q (user and group of the \214nal object happen to match those speci\214ed) 0 24 Q(in the entry)0 36 Q(.)-.65 E(
)36 48 Q(The)0 60 Q -.74(``)0 72 S(standard').74 E(')-.74 E 0 Cg EP %%Page: 62 62 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF(user)0 12 Q (-id and group-id lookup functions are not the def)-.2 E(aults because) -.1 E(getgrnam\(3\))0 24 Q(and)0 36 Q(getpwnam\(3\))0 48 Q (are sometimes too lar)0 60 Q(ge for particular applications.)-.18 E (The current design allo)0 72 Q(ws the application author to use a more) -.25 E 0 Cg EP %%Page: 63 63 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF(compact implementation when appropriate.)0 12 Q (
)36 24 Q(There should be a corresponding)0 36 Q(archi)0 48 Q -.15 (ve)-.25 G(_read_disk).15 E(interf)0 60 Q(ace that w)-.1 E (alks a directory heirarch)-.1 E 2.5(ya)-.05 G(nd returns archi)-2.5 E -.15(ve)-.25 G(entry objects.)0 72 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 892 a892 469
ARCHIVE_WRITE_DISK(3) BSD Library Functions Manual ARCHIVE_WRITE_DISK(3)
NAME
archive_write_disk_new, archive_write_disk_set_options, archive_write_disk_set_skip_file, archive_write_disk_set_group_lookup, archive_write_disk_set_standard_lookup, archive_write_disk_set_user_lookup, archive_write_header, archive_write_data, archive_write_data_block, archive_write_finish_entry, archive_write_close, archive_write_finish archive_write_free — functions for creating objects on disk
LIBRARY
Streaming Archive Library (libarchive, -larchive)
SYNOPSIS
#include <archive.h>
struct archive *
archive_write_disk_new(void);
int
archive_write_disk_set_options(struct archive *, int flags);
int
archive_write_disk_set_skip_file(struct archive *, dev_t, ino_t);
int
archive_write_disk_set_group_lookup(struct archive *, void *, gid_t (*)(void *, const char *gname, gid_t gid), void (*cleanup)(void *));
int
archive_write_disk_set_standard_lookup(struct archive *);
int
archive_write_disk_set_user_lookup(struct archive *, void *, uid_t (*)(void *, const char *uname, uid_t uid), void (*cleanup)(void *));
int
archive_write_header(struct archive *, struct archive_entry *);
la_ssize_t
archive_write_data(struct archive *, const void *, size_t);
la_ssize_t
archive_write_data_block(struct archive *, const void *, size_t size, int64_t offset);
int
archive_write_finish_entry(struct archive *);
int
archive_write_close(struct archive *);
int
archive_write_finish(struct archive *);
int
archive_write_free(struct archive *);
DESCRIPTION
These functions provide a complete API for creating objects on disk from struct archive_entry descriptions. They are most naturally used when extracting objects from an archive using the archive_read() interface. The general process is to read struct archive_entry objects from an archive, then write those objects to a struct archive object created using the archive_write_disk() family functions. This interface is deliberately very similar to the archive_write() interface used to write objects to a streaming archive.
archive_write_disk_new()
Allocates and initializes a struct archive object suitable for writing objects to disk.
archive_write_disk_set_skip_file()
Records the device and inode numbers of a file that should not be overwritten. This is typically used to ensure that an extraction process does not overwrite the archive from which objects are being read. This capability is technically unnecessary but can be a significant performance optimization in practice.
archive_write_disk_set_options()
The options field consists of a bitwise OR of one or more of the following values:
ARCHIVE_EXTRACT_OWNER
The user and group IDs should be set on the restored file. By default, the user and group IDs are not restored.
ARCHIVE_EXTRACT_PERM
Full permissions (including SGID, SUID, and sticky bits) should be restored exactly as specified, without obeying the current umask. Note that SUID and SGID bits can only be restored if the user and group ID of the object on disk are correct. If ARCHIVE_EXTRACT_OWNER is not specified, then SUID and SGID bits will only be restored if the default user and group IDs of newly-created objects on disk happen to match those specified in the archive entry. By default, only basic permissions are restored, and umask is obeyed.
ARCHIVE_EXTRACT_TIME
The timestamps (mtime, ctime, and atime) should be restored. By default, they are ignored. Note that restoring of atime is not currently supported.
ARCHIVE_EXTRACT_NO_OVERWRITE
Existing files on disk will not be overwritten. By default, existing regular files are truncated and overwritten; existing directories will have their permissions updated; other pre-existing objects are unlinked and recreated from scratch.
ARCHIVE_EXTRACT_UNLINK
Existing files on disk will be unlinked before any attempt to create them. In some cases, this can prove to be a significant performance improvement. By default, existing files are truncated and rewritten, but the file is not recreated. In particular, the default behavior does not break existing hard links.
ARCHIVE_EXTRACT_ACL
Attempt to restore ACLs. By default, extended ACLs are ignored.
ARCHIVE_EXTRACT_FFLAGS
Attempt to restore extended file flags. By default, file flags are ignored.
ARCHIVE_EXTRACT_XATTR
Attempt to restore POSIX.1e extended attributes. By default, they are ignored.
ARCHIVE_EXTRACT_SECURE_SYMLINKS
Refuse to extract any object whose final location would be altered by a symlink on disk. This is intended to help guard against a variety of mischief caused by archives that (deliberately or otherwise) extract files outside of the current directory. The default is not to perform this check. If ARCHIVE_EXTRACT_UNLINK is specified together with this option, the library will remove any intermediate symlinks it finds and return an error only if such symlink could not be removed.
ARCHIVE_EXTRACT_SECURE_NODOTDOT
Refuse to extract a path that contains a .. element anywhere within it. The default is to not refuse such paths. Note that paths ending in .. always cause an error, regardless of this flag.
ARCHIVE_EXTRACT_SECURE_NOABSOLUTEPATHS
Refuse to extract an absolute path. The default is to not refuse such paths.
ARCHIVE_EXTRACT_SPARSE
Scan data for blocks of NUL bytes and try to recreate them with holes. This results in sparse files, independent of whether the archive format supports or uses them.
ARCHIVE_EXTRACT_CLEAR_NOCHANGE_FFLAGS
Before removing a file system object prior to replacing it, clear platform-specific file flags which might prevent its removal.
archive_write_disk_set_group_lookup(), archive_write_disk_set_user_lookup()
The struct archive_entry objects contain both names and ids that can be used to identify users and groups. These names and ids describe the ownership of the file itself and also appear in ACL lists. By default, the library uses the ids and ignores the names, but this can be overridden by registering user and group lookup functions. To register, you must provide a lookup function which accepts both a name and id and returns a suitable id. 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.
archive_write_disk_set_standard_lookup()
This convenience function installs a standard set of user and group lookup functions. These functions use getpwnam(3) and getgrnam(3) to convert names to ids, defaulting to the ids if the names cannot be looked up. These functions also implement a simple memory cache to reduce the number of calls to getpwnam(3) and getgrnam(3).
archive_write_header()
Build and write a header using the data in the provided struct archive_entry structure. See archive_entry(3) for information on creating and populating struct archive_entry objects.
archive_write_data()
Write data corresponding to the header just written. Returns number of bytes written or -1 on error.
archive_write_data_block()
Write data corresponding to the header just written. This is like archive_write_data() except that it performs a seek on the file being written to the specified offset before writing the data. This is useful when restoring sparse files from archive formats that support sparse files. Returns number of bytes written or -1 on error. (Note: This is currently not supported for archive_write handles, only for archive_write_disk handles.)
archive_write_finish_entry()
Close out the entry just written. Ordinarily, clients never need to call this, as it is called automatically by archive_write_next_header() and archive_write_close() as needed. However, some file attributes are written to disk only after the file is closed, so this can be necessary if you need to work with the file on disk right away.
archive_write_close()
Set any attributes that could not be set during the initial restore. For example, directory timestamps are not restored initially because restoring a subsequent file would alter that timestamp. Similarly, non-writable directories are initially created with write permissions (so that their contents can be restored). The archive_write_disk_new library maintains a list of all such deferred attributes and sets them when this function is invoked.
archive_write_finish()
This is a deprecated synonym for archive_write_free().
archive_write_free()
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. Many of these functions are also documented under archive_write(3).
RETURN VALUES
Most functions return ARCHIVE_OK (zero) on success, or one of several non-zero 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_write_disk_new() returns a pointer to a newly-allocated struct archive object.
archive_write_data() returns a count of the number of bytes actually written, or -1 on error.
ERRORS
Detailed error codes and textual descriptions are available from the archive_errno() and archive_error_string() functions.
SEE ALSO
archive_read(3), archive_write(3), tar(1), libarchive(3)
HISTORY
The libarchive library first appeared in FreeBSD 5.3. The archive_write_disk interface was added to libarchive 2.0 and first appeared in FreeBSD 6.3.
AUTHORS
The libarchive library was written by Tim Kientzle <kientzle@@acm.org>.
BUGS
Directories are actually extracted in two distinct phases. Directories are created during archive_write_header(), but final permissions are not set until archive_write_close(). This separation is necessary to correctly handle borderline cases such as a non-writable directory containing files, but can cause unexpected results. In particular, directory permissions are not fully restored until the archive is closed. If you use chdir(2) to change the current directory between calls to archive_read_extract() or before calling archive_read_close(), you may confuse the permission-setting logic with the result that directory permissions are restored incorrectly.
The library attempts to create objects with filenames longer than PATH_MAX by creating prefixes of the full path and changing the current directory. Currently, this logic is limited in scope; the fixup pass does not work correctly for such objects and the symlink security check option disables the support for very long pathnames.
Restoring the path aa/../bb does create each intermediate directory. In particular, the directory aa is created as well as the final object bb. In theory, this can be exploited to create an entire directory hierarchy with a single request. Of course, this does not work if the ARCHIVE_EXTRACT_NODOTDOT option is specified.
Implicit directories are always created obeying the current umask. Explicit objects are created obeying the current umask unless ARCHIVE_EXTRACT_PERM is specified, in which case they current umask is ignored.
SGID and SUID bits are restored only if the correct user and group could be set. If ARCHIVE_EXTRACT_OWNER is not specified, then no attempt is made to set the ownership. In this case, SGID and SUID bits are restored only if the user and group of the final object happen to match those specified in the entry.
The ’’standard’’ user-id and group-id lookup functions are not the defaults because getgrnam(3) and getpwnam(3) are sometimes too large for particular applications. The current design allows the application author to use a more compact implementation when appropriate.
There should be a corresponding archive_read_disk interface that walks a directory hierarchy and returns archive entry objects.
BSD February 2, 2012 BSD
ARCHIVE_EXTRACT_ACL
Attempt to restore Access Control Lists. By default, extended ACLs are ignored.
ARCHIVE_EXTRACT_CLEAR_NOCHANGE_FFLAGS
Before removing a file system object prior to replacing it, clear platform-specific file flags which might prevent its removal.
ARCHIVE_EXTRACT_FFLAGS
Attempt to restore file attributes (file flags). By default, file attributes are ignored. See chattr(1) (Linux) or chflags(1) (FreeBSD, Mac OS X) for more information on file attributes.
ARCHIVE_EXTRACT_MAC_METADATA
Mac OS X specific. Restore metadata using copyfile(3). By default, copyfile(3) metadata is ignored.
ARCHIVE_EXTRACT_NO_OVERWRITE
Existing files on disk will not be overwritten. By default, existing regular files are truncated and overwritten; existing directories will have their permissions updated; other pre-existing objects are unlinked and recreated from scratch.
d187 29 a215 1ARCHIVE_EXTRACT_SECURE_NOABSOLUTEPATHS
d217 2 a218 2Refuse to extract an absolute path. The default is to not refuse such paths.
d220 1 a220 1ARCHIVE_EXTRACT_SECURE_NODOTDOT
d222 2 a223 5Refuse to extract a path that contains a .. element anywhere within it. The default is to not refuse such paths. Note that paths ending in .. always cause an error, regardless of this flag.
d232 1 a232 8 to perform this check. IfARCHIVE_EXTRACT_SPARSE
Scan data for blocks of NUL bytes and try to recreate them with holes. This results in sparse files, independent of whether the archive format supports or uses them. ARCHIVE_EXTRACT_UNLINK is d237 9 a245 1
ARCHIVE_EXTRACT_TIME
d247 2 a248 3The timestamps (mtime, ctime, and atime) should be restored. By default, they are ignored. Note that restoring of atime is not currently supported.
d250 1 a250 1ARCHIVE_EXTRACT_UNLINK
d252 4 a255 6Existing files on disk will be unlinked before any attempt to create them. In some cases, this can prove to be a significant performance improvement. By default, existing files are truncated and rewritten, but the file is not recreated. In particular, the default behavior does not break existing hard links.
d257 1 a257 1ARCHIVE_EXTRACT_XATTR
d259 3 a261 4Attempt to restore extended file attributes. By default, they are ignored. See xattr(7) (Linux), xattr(2) (Mac OS X), or getextattr(8) (FreeBSD) for more information on extended file attributes.
d291 64 d453 1 a453 1 ’’standard’’ user-id and group-id d466 1 a466 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 d353 6 a358 5 “standard” user-id and group-id lookup functions are not the defaults because getgrnam(3) and getpwnam(3) are sometimes too large for particular applications. The current design allows the application author to use a more compact implementation when appropriate. @ 1.1.1.10 log @Import libarchive 3.7.2 @ text @d2 1 a2 1 a172 8ARCHIVE_EXTRACT_SAFE_WRITES
Extract files atomically, by first creating a unique temporary file and then renaming it to its required destination name. This avoids a race where an application might see a partial file (or no file) during extraction.
d193 1 a193 4 to perform this check. If ARCHIVE_EXTRACT_UNLINK is specified together with this option, the library will remove any intermediate symlinks it finds and return an error only if such symlink could not be removed. d200 4 a203 1 supports or uses them. d290 2 a291 2tar(1), archive_read(3), archive_write(3), libarchive(3)
d365 1 a365 1 January 19, 2020 BSD @ 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 @ 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_WRITE_DISK(3) Library Functions Manual ARCHIVE_WRITE_DISK(3)
d28 7 a34 7archive_write_disk_new, archive_write_disk_set_options, archive_write_disk_set_skip_file, archive_write_disk_set_group_lookup, archive_write_disk_set_standard_lookup, archive_write_disk_set_user_lookup — functions for creating objects on disk
d38 1 a38 1Streaming Archive Library d43 1 a43 1
#include d46 1 a46 1
struct d50 1 a50 1
archive_write_disk_new(void);
d52 1 a52 1int
d55 1 a55 1archive_write_disk_set_options(struct archive *, d58 1 a58 1
int
d61 1 a61 1archive_write_disk_set_skip_file(struct archive *, d64 1 a64 1
int
d72 1 a72 1int
d75 1 a75 1archive_write_disk_set_standard_lookup(struct archive *);
d77 1 a77 1int
d87 1 a87 1These functions provide a d102 1 a102 1
Allocates and initializes a d109 1 a109 1
Records the device and inode d119 1 a119 1
The options field consists of a d124 1 a124 1
Attempt to restore Access d129 1 a129 1
Before removing a file system d135 1 a135 1
Attempt to restore file d137 2 a138 3 ignored. See chattr(1) (Linux) or chflags(1) (FreeBSD, Mac OS X) for more information on file attributes.
d142 3 a144 3Mac OS X specific. Restore metadata using copyfile(3). By default, copyfile(3) metadata is ignored.
d148 1 a148 1Existing files on disk will not d156 1 a156 1
The user and group IDs should d162 1 a162 1
Full permissions (including d175 1 a175 1
Extract files atomically, by d183 1 a183 1
Refuse to extract an absolute d188 1 a188 1
Refuse to extract a path that d196 1 a196 1
Refuse to extract any object d208 1 a208 1
Scan data for blocks of NUL d215 1 a215 1
The timestamps (mtime, ctime, d221 1 a221 1
Existing files on disk will be d230 4 a233 5
Attempt to restore extended file attributes. By default, they are ignored. See xattr(7) (Linux), xattr(2) (Mac OS X), or getextattr(8) (FreeBSD) for more information on extended file attributes.
d239 1 a239 1The struct archive_entry d255 1 a255 1
This convenience function d257 5 a261 5 These functions use getpwnam(3) and getgrnam(3) to convert names to ids, defaulting to the ids if the names cannot be looked up. These functions also implement a simple memory cache to reduce the number of calls to getpwnam(3) and getgrnam(3).
d263 1 a263 1More information about the d265 3 a267 3 library can be found in the libarchive(3) overview. Many of these functions are also documented under archive_write(3).
d271 1 a271 1Most functions return d281 1 a281 1
archive_write_disk_new() d286 1 a286 1
archive_write_data() d288 1 a288 1 -1 on error.
d292 1 a292 1Detailed error codes and textual d298 2 a299 3
tar(1), archive_read(3), archive_write(3), libarchive(3)
d303 1 a303 1The libarchive library d311 1 a311 1
The libarchive library d316 1 a316 1
Directories are actually d324 4 a327 4 closed. If you use chdir(2) to change the current directory between calls to archive_read_extract() or before calling archive_read_close(), you may confuse the permission-setting logic with the result that directory d330 1 a330 1
The library d338 1 a338 1
Restoring the d346 1 a346 1
Implicit d352 1 a352 1
SGID and SUID d360 1 a360 1
The d362 4 a365 5 are not the defaults because getgrnam(3) and getpwnam(3) are sometimes too large for particular applications. The current design allows the application author to use a more compact implementation when appropriate.
d367 1 a367 1There should be d370 4 a373 2 objects. Debian January 19, 2020 ARCHIVE_WRITE_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 @