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