ARCHIVE_WRITE_DISK(3) | Library Functions Manual | ARCHIVE_WRITE_DISK(3) |
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
Streaming Archive Library (libarchive, -larchive)
#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 *));
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
()archive_write_disk_set_skip_file
()archive_write_disk_set_options
()ARCHIVE_EXTRACT_ACL
ARCHIVE_EXTRACT_CLEAR_NOCHANGE_FFLAGS
ARCHIVE_EXTRACT_FFLAGS
ARCHIVE_EXTRACT_MAC_METADATA
ARCHIVE_EXTRACT_NO_OVERWRITE
ARCHIVE_EXTRACT_OWNER
ARCHIVE_EXTRACT_PERM
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
ARCHIVE_EXTRACT_SECURE_NOABSOLUTEPATHS
ARCHIVE_EXTRACT_SECURE_NODOTDOT
ARCHIVE_EXTRACT_SECURE_SYMLINKS
ARCHIVE_EXTRACT_SPARSE
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_TIME
ARCHIVE_EXTRACT_UNLINK
ARCHIVE_EXTRACT_XATTR
archive_write_disk_set_group_lookup
(),
archive_write_disk_set_user_lookup
()archive_write_disk_set_standard_lookup
()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.
Detailed error codes and textual descriptions are available from
the archive_errno
() and
archive_error_string
() functions.
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.
The libarchive
library was written by
Tim Kientzle ⟨kientzle@acm.org⟩.
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.
January 19, 2020 | macOS 14.6 |