source-git / libarchive

Clone
Source Code
GIT

Blame doc/html/archive_write_disk.3.html

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

Powered by Pagure 5.13.3

SSH Hostkey/Fingerprint | Documentation