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