|
Packit |
08bd4c |
ARCHIVE_WRITE_DISK(3) BSD Library Functions Manual ARCHIVE_WRITE_DISK(3)
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
NAME
|
|
Packit |
08bd4c |
archive_write_disk_new, archive_write_disk_set_options,
|
|
Packit |
08bd4c |
archive_write_disk_set_skip_file, archive_write_disk_set_group_lookup,
|
|
Packit |
08bd4c |
archive_write_disk_set_standard_lookup,
|
|
Packit |
08bd4c |
archive_write_disk_set_user_lookup — functions for creating objects on
|
|
Packit |
08bd4c |
disk
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
LIBRARY
|
|
Packit |
08bd4c |
Streaming Archive Library (libarchive, -larchive)
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
SYNOPSIS
|
|
Packit |
08bd4c |
#include <archive.h>
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
struct archive *
|
|
Packit |
08bd4c |
archive_write_disk_new(void);
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
int
|
|
Packit |
08bd4c |
archive_write_disk_set_options(struct archive *, int flags);
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
int
|
|
Packit |
08bd4c |
archive_write_disk_set_skip_file(struct archive *, dev_t, ino_t);
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
int
|
|
Packit |
08bd4c |
archive_write_disk_set_group_lookup(struct archive *, void *,
|
|
Packit |
08bd4c |
gid_t (*)(void *, const char *gname, gid_t gid),
|
|
Packit |
08bd4c |
void (*cleanup)(void *));
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
int
|
|
Packit |
08bd4c |
archive_write_disk_set_standard_lookup(struct archive *);
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
int
|
|
Packit |
08bd4c |
archive_write_disk_set_user_lookup(struct archive *, void *,
|
|
Packit |
08bd4c |
uid_t (*)(void *, const char *uname, uid_t uid),
|
|
Packit |
08bd4c |
void (*cleanup)(void *));
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
DESCRIPTION
|
|
Packit |
08bd4c |
These functions provide a complete API for creating objects on disk from
|
|
Packit |
08bd4c |
struct archive_entry descriptions. They are most naturally used when
|
|
Packit |
08bd4c |
extracting objects from an archive using the archive_read() interface.
|
|
Packit |
08bd4c |
The general process is to read struct archive_entry objects from an ar‐
|
|
Packit |
08bd4c |
chive, then write those objects to a struct archive object created using
|
|
Packit |
08bd4c |
the archive_write_disk() family functions. This interface is deliber‐
|
|
Packit |
08bd4c |
ately very similar to the archive_write() interface used to write objects
|
|
Packit |
08bd4c |
to a streaming archive.
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
archive_write_disk_new()
|
|
Packit |
08bd4c |
Allocates and initializes a struct archive object suitable for
|
|
Packit |
08bd4c |
writing objects to disk.
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
archive_write_disk_set_skip_file()
|
|
Packit |
08bd4c |
Records the device and inode numbers of a file that should not be
|
|
Packit |
08bd4c |
overwritten. This is typically used to ensure that an extraction
|
|
Packit |
08bd4c |
process does not overwrite the archive from which objects are
|
|
Packit |
08bd4c |
being read. This capability is technically unnecessary but can
|
|
Packit |
08bd4c |
be a significant performance optimization in practice.
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
archive_write_disk_set_options()
|
|
Packit |
08bd4c |
The options field consists of a bitwise OR of one or more of the
|
|
Packit |
08bd4c |
following values:
|
|
Packit |
08bd4c |
ARCHIVE_EXTRACT_ACL
|
|
Packit |
08bd4c |
Attempt to restore Access Control Lists. By default,
|
|
Packit |
08bd4c |
extended ACLs are ignored.
|
|
Packit |
08bd4c |
ARCHIVE_EXTRACT_CLEAR_NOCHANGE_FFLAGS
|
|
Packit |
08bd4c |
Before removing a file system object prior to replacing
|
|
Packit |
08bd4c |
it, clear platform-specific file flags which might pre‐
|
|
Packit |
08bd4c |
vent its removal.
|
|
Packit |
08bd4c |
ARCHIVE_EXTRACT_FFLAGS
|
|
Packit |
08bd4c |
Attempt to restore file attributes (file flags). By
|
|
Packit |
08bd4c |
default, file attributes are ignored. See chattr(1)
|
|
Packit |
08bd4c |
(Linux) or chflags(1) (FreeBSD, Mac OS X) for more infor‐
|
|
Packit |
08bd4c |
mation on file attributes.
|
|
Packit |
08bd4c |
ARCHIVE_EXTRACT_MAC_METADATA
|
|
Packit |
08bd4c |
Mac OS X specific. Restore metadata using copyfile(3).
|
|
Packit |
08bd4c |
By default, copyfile(3) metadata is ignored.
|
|
Packit |
08bd4c |
ARCHIVE_EXTRACT_NO_OVERWRITE
|
|
Packit |
08bd4c |
Existing files on disk will not be overwritten. By
|
|
Packit |
08bd4c |
default, existing regular files are truncated and over‐
|
|
Packit |
08bd4c |
written; existing directories will have their permissions
|
|
Packit |
08bd4c |
updated; other pre-existing objects are unlinked and
|
|
Packit |
08bd4c |
recreated from scratch.
|
|
Packit |
08bd4c |
ARCHIVE_EXTRACT_OWNER
|
|
Packit |
08bd4c |
The user and group IDs should be set on the restored
|
|
Packit |
08bd4c |
file. By default, the user and group IDs are not
|
|
Packit |
08bd4c |
restored.
|
|
Packit |
08bd4c |
ARCHIVE_EXTRACT_PERM
|
|
Packit |
08bd4c |
Full permissions (including SGID, SUID, and sticky bits)
|
|
Packit |
08bd4c |
should be restored exactly as specified, without obeying
|
|
Packit |
08bd4c |
the current umask. Note that SUID and SGID bits can only
|
|
Packit |
08bd4c |
be restored if the user and group ID of the object on
|
|
Packit |
08bd4c |
disk are correct. If ARCHIVE_EXTRACT_OWNER is not speci‐
|
|
Packit |
08bd4c |
fied, then SUID and SGID bits will only be restored if
|
|
Packit |
08bd4c |
the default user and group IDs of newly-created objects
|
|
Packit |
08bd4c |
on disk happen to match those specified in the archive
|
|
Packit |
08bd4c |
entry. By default, only basic permissions are restored,
|
|
Packit |
08bd4c |
and umask is obeyed.
|
|
Packit |
08bd4c |
ARCHIVE_EXTRACT_SECURE_NOABSOLUTEPATHS
|
|
Packit |
08bd4c |
Refuse to extract an absolute path. The default is to
|
|
Packit |
08bd4c |
not refuse such paths.
|
|
Packit |
08bd4c |
ARCHIVE_EXTRACT_SECURE_NODOTDOT
|
|
Packit |
08bd4c |
Refuse to extract a path that contains a .. element any‐
|
|
Packit |
08bd4c |
where within it. The default is to not refuse such
|
|
Packit |
08bd4c |
paths. Note that paths ending in .. always cause an
|
|
Packit |
08bd4c |
error, regardless of this flag.
|
|
Packit |
08bd4c |
ARCHIVE_EXTRACT_SECURE_SYMLINKS
|
|
Packit |
08bd4c |
Refuse to extract any object whose final location would
|
|
Packit |
08bd4c |
be altered by a symlink on disk. This is intended to
|
|
Packit |
08bd4c |
help guard against a variety of mischief caused by ar‐
|
|
Packit |
08bd4c |
chives that (deliberately or otherwise) extract files
|
|
Packit |
08bd4c |
outside of the current directory. The default is not to
|
|
Packit |
08bd4c |
perform this check. If
|
|
Packit |
08bd4c |
ARCHIVE_EXTRACT_SPARSE
|
|
Packit |
08bd4c |
Scan data for blocks of NUL bytes and try to recreate
|
|
Packit |
08bd4c |
them with holes. This results in sparse files, indepen‐
|
|
Packit |
08bd4c |
dent of whether the archive format supports or uses them.
|
|
Packit |
08bd4c |
ARCHIVE_EXTRACT_UNLINK is specified together with this
|
|
Packit |
08bd4c |
option, the library will remove any intermediate symlinks
|
|
Packit |
08bd4c |
it finds and return an error only if such symlink could
|
|
Packit |
08bd4c |
not be removed.
|
|
Packit |
08bd4c |
ARCHIVE_EXTRACT_TIME
|
|
Packit |
08bd4c |
The timestamps (mtime, ctime, and atime) should be
|
|
Packit |
08bd4c |
restored. By default, they are ignored. Note that
|
|
Packit |
08bd4c |
restoring of atime is not currently supported.
|
|
Packit |
08bd4c |
ARCHIVE_EXTRACT_UNLINK
|
|
Packit |
08bd4c |
Existing files on disk will be unlinked before any
|
|
Packit |
08bd4c |
attempt to create them. In some cases, this can prove to
|
|
Packit |
08bd4c |
be a significant performance improvement. By default,
|
|
Packit |
08bd4c |
existing files are truncated and rewritten, but the file
|
|
Packit |
08bd4c |
is not recreated. In particular, the default behavior
|
|
Packit |
08bd4c |
does not break existing hard links.
|
|
Packit |
08bd4c |
ARCHIVE_EXTRACT_XATTR
|
|
Packit |
08bd4c |
Attempt to restore extended file attributes. By default,
|
|
Packit |
08bd4c |
they are ignored. See xattr(7) (Linux), xattr(2) (Mac OS
|
|
Packit |
08bd4c |
X), or getextattr(8) (FreeBSD) for more information on
|
|
Packit |
08bd4c |
extended file attributes.
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
archive_write_disk_set_group_lookup(),
|
|
Packit |
08bd4c |
archive_write_disk_set_user_lookup()
|
|
Packit |
08bd4c |
The struct archive_entry objects contain both names and ids that
|
|
Packit |
08bd4c |
can be used to identify users and groups. These names and ids
|
|
Packit |
08bd4c |
describe the ownership of the file itself and also appear in ACL
|
|
Packit |
08bd4c |
lists. By default, the library uses the ids and ignores the
|
|
Packit |
08bd4c |
names, but this can be overridden by registering user and group
|
|
Packit |
08bd4c |
lookup functions. To register, you must provide a lookup func‐
|
|
Packit |
08bd4c |
tion which accepts both a name and id and returns a suitable id.
|
|
Packit |
08bd4c |
You may also provide a void * pointer to a private data structure
|
|
Packit |
08bd4c |
and a cleanup function for that data. The cleanup function will
|
|
Packit |
08bd4c |
be invoked when the struct archive object is destroyed.
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
archive_write_disk_set_standard_lookup()
|
|
Packit |
08bd4c |
This convenience function installs a standard set of user and
|
|
Packit |
08bd4c |
group lookup functions. These functions use getpwnam(3) and
|
|
Packit |
08bd4c |
getgrnam(3) to convert names to ids, defaulting to the ids if the
|
|
Packit |
08bd4c |
names cannot be looked up. These functions also implement a sim‐
|
|
Packit |
08bd4c |
ple memory cache to reduce the number of calls to getpwnam(3) and
|
|
Packit |
08bd4c |
getgrnam(3).
|
|
Packit |
08bd4c |
More information about the struct archive object and the overall design
|
|
Packit |
08bd4c |
of the library can be found in the libarchive(3) overview. Many of these
|
|
Packit |
08bd4c |
functions are also documented under archive_write(3).
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
RETURN VALUES
|
|
Packit |
08bd4c |
Most functions return ARCHIVE_OK (zero) on success, or one of several
|
|
Packit |
08bd4c |
non-zero error codes for errors. Specific error codes include:
|
|
Packit |
08bd4c |
ARCHIVE_RETRY for operations that might succeed if retried, ARCHIVE_WARN
|
|
Packit |
08bd4c |
for unusual conditions that do not prevent further operations, and
|
|
Packit |
08bd4c |
ARCHIVE_FATAL for serious errors that make remaining operations impossi‐
|
|
Packit |
08bd4c |
ble.
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
archive_write_disk_new() returns a pointer to a newly-allocated struct
|
|
Packit |
08bd4c |
archive object.
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
archive_write_data() returns a count of the number of bytes actually
|
|
Packit |
08bd4c |
written, or -1 on error.
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
ERRORS
|
|
Packit |
08bd4c |
Detailed error codes and textual descriptions are available from the
|
|
Packit |
08bd4c |
archive_errno() and archive_error_string() functions.
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
SEE ALSO
|
|
Packit |
08bd4c |
archive_read(3), archive_write(3), tar(1), libarchive(3)
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
HISTORY
|
|
Packit |
08bd4c |
The libarchive library first appeared in FreeBSD 5.3. The
|
|
Packit |
08bd4c |
archive_write_disk interface was added to libarchive 2.0 and first
|
|
Packit |
08bd4c |
appeared in FreeBSD 6.3.
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
AUTHORS
|
|
Packit |
08bd4c |
The libarchive library was written by Tim Kientzle <kientzle@acm.org>.
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
BUGS
|
|
Packit |
08bd4c |
Directories are actually extracted in two distinct phases. Directories
|
|
Packit |
08bd4c |
are created during archive_write_header(), but final permissions are not
|
|
Packit |
08bd4c |
set until archive_write_close(). This separation is necessary to cor‐
|
|
Packit |
08bd4c |
rectly handle borderline cases such as a non-writable directory contain‐
|
|
Packit |
08bd4c |
ing files, but can cause unexpected results. In particular, directory
|
|
Packit |
08bd4c |
permissions are not fully restored until the archive is closed. If you
|
|
Packit |
08bd4c |
use chdir(2) to change the current directory between calls to
|
|
Packit |
08bd4c |
archive_read_extract() or before calling archive_read_close(), you may
|
|
Packit |
08bd4c |
confuse the permission-setting logic with the result that directory per‐
|
|
Packit |
08bd4c |
missions are restored incorrectly.
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
The library attempts to create objects with filenames longer than
|
|
Packit |
08bd4c |
PATH_MAX by creating prefixes of the full path and changing the current
|
|
Packit |
08bd4c |
directory. Currently, this logic is limited in scope; the fixup pass
|
|
Packit |
08bd4c |
does not work correctly for such objects and the symlink security check
|
|
Packit |
08bd4c |
option disables the support for very long pathnames.
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
Restoring the path aa/../bb does create each intermediate directory. In
|
|
Packit |
08bd4c |
particular, the directory aa is created as well as the final object bb.
|
|
Packit |
08bd4c |
In theory, this can be exploited to create an entire directory hierarchy
|
|
Packit |
08bd4c |
with a single request. Of course, this does not work if the
|
|
Packit |
08bd4c |
ARCHIVE_EXTRACT_NODOTDOT option is specified.
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
Implicit directories are always created obeying the current umask.
|
|
Packit |
08bd4c |
Explicit objects are created obeying the current umask unless
|
|
Packit |
08bd4c |
ARCHIVE_EXTRACT_PERM is specified, in which case they current umask is
|
|
Packit |
08bd4c |
ignored.
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
SGID and SUID bits are restored only if the correct user and group could
|
|
Packit |
08bd4c |
be set. If ARCHIVE_EXTRACT_OWNER is not specified, then no attempt is
|
|
Packit |
08bd4c |
made to set the ownership. In this case, SGID and SUID bits are restored
|
|
Packit |
08bd4c |
only if the user and group of the final object happen to match those
|
|
Packit |
08bd4c |
specified in the entry.
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
The “standard” user-id and group-id lookup functions are not the defaults
|
|
Packit |
08bd4c |
because getgrnam(3) and getpwnam(3) are sometimes too large for particu‐
|
|
Packit |
08bd4c |
lar applications. The current design allows the application author to
|
|
Packit |
08bd4c |
use a more compact implementation when appropriate.
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
There should be a corresponding archive_read_disk interface that walks a
|
|
Packit |
08bd4c |
directory hierarchy and returns archive entry objects.
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
BSD April 3, 2017 BSD
|