359 lines
11 KiB
Plaintext
359 lines
11 KiB
Plaintext
#summary archive_write_disk 3 manual page
|
|
== NAME ==
|
|
*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*,
|
|
*archive_write_header*,
|
|
*archive_write_data*,
|
|
*archive_write_finish_entry*,
|
|
*archive_write_close*,
|
|
*archive_write_finish*
|
|
- functions for creating objects on disk
|
|
== SYNOPSIS ==
|
|
*#include <archive.h>*
|
|
<br>
|
|
*struct archive `*`*
|
|
<br>
|
|
*archive_write_disk_new*(_void_);
|
|
<br>
|
|
*int*
|
|
<br>
|
|
*archive_write_disk_set_options*(_struct archive `*`_, _int flags_);
|
|
<br>
|
|
*int*
|
|
<br>
|
|
*archive_write_disk_set_skip_file*(_struct archive `*`_, _dev_t_, _ino_t_);
|
|
<br>
|
|
*int*
|
|
<br>
|
|
*archive_write_disk_set_group_lookup*(_struct archive `*`_, _void `*`_, _gid_t (`*`)(void `*`, const char `*`gname, gid_t gid)_, _void (`*`cleanup)(void `*`)_);
|
|
<br>
|
|
*int*
|
|
<br>
|
|
*archive_write_disk_set_standard_lookup*(_struct archive `*`_);
|
|
<br>
|
|
*int*
|
|
<br>
|
|
*archive_write_disk_set_user_lookup*(_struct archive `*`_, _void `*`_, _uid_t (`*`)(void `*`, const char `*`uname, uid_t uid)_, _void (`*`cleanup)(void `*`)_);
|
|
<br>
|
|
*int*
|
|
<br>
|
|
*archive_write_header*(_struct archive `*`_, _struct archive_entry `*`_);
|
|
<br>
|
|
*ssize_t*
|
|
<br>
|
|
*archive_write_data*(_struct archive `*`_, _const void `*`_, _size_t_);
|
|
<br>
|
|
*int*
|
|
<br>
|
|
*archive_write_finish_entry*(_struct archive `*`_);
|
|
<br>
|
|
*int*
|
|
<br>
|
|
*archive_write_close*(_struct archive `*`_);
|
|
<br>
|
|
*int*
|
|
<br>
|
|
*archive_write_finish*(_struct archive `*`_);
|
|
== DESCRIPTION ==
|
|
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.
|
|
<dl>
|
|
<dt>*archive_write_disk_new*()</dt><dd>
|
|
Allocates and initializes a
|
|
*struct archive*
|
|
object suitable for writing objects to disk.
|
|
</dd><dt>*archive_write_disk_set_skip_file*()</dt><dd>
|
|
Records the device and inode numbers of a file that should not be
|
|
overwritten.
|
|
This is typically used to ensure that an extraction process does not
|
|
overwrite the archive from which objects are being read.
|
|
This capability is technically unnecessary but can be a significant
|
|
performance optimization in practice.
|
|
</dd><dt>*archive_write_disk_set_options*()</dt><dd>
|
|
The options field consists of a bitwise OR of one or more of the
|
|
following values:
|
|
<dl>
|
|
<dt>*ARCHIVE_EXTRACT_OWNER*</dt><dd>
|
|
The user and group IDs should be set on the restored file.
|
|
By default, the user and group IDs are not restored.
|
|
</dd><dt>*ARCHIVE_EXTRACT_PERM*</dt><dd>
|
|
Full permissions (including SGID, SUID, and sticky bits) should
|
|
be restored exactly as specified, without obeying the
|
|
current umask.
|
|
Note that SUID and SGID bits can only be restored if the
|
|
user and group ID of the object on disk are correct.
|
|
If
|
|
*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.
|
|
</dd><dt>*ARCHIVE_EXTRACT_TIME*</dt><dd>
|
|
The timestamps (mtime, ctime, and atime) should be restored.
|
|
By default, they are ignored.
|
|
Note that restoring of atime is not currently supported.
|
|
</dd><dt>*ARCHIVE_EXTRACT_NO_OVERWRITE*</dt><dd>
|
|
Existing files on disk will not be overwritten.
|
|
By default, existing regular files are truncated and overwritten;
|
|
existing directories will have their permissions updated;
|
|
other pre-existing objects are unlinked and recreated from scratch.
|
|
</dd><dt>*ARCHIVE_EXTRACT_UNLINK*</dt><dd>
|
|
Existing files on disk will be unlinked before any attempt to
|
|
create them.
|
|
In some cases, this can prove to be a significant performance improvement.
|
|
By default, existing files are truncated and rewritten, but
|
|
the file is not recreated.
|
|
In particular, the default behavior does not break existing hard links.
|
|
</dd><dt>*ARCHIVE_EXTRACT_ACL*</dt><dd>
|
|
Attempt to restore ACLs.
|
|
By default, extended ACLs are ignored.
|
|
</dd><dt>*ARCHIVE_EXTRACT_FFLAGS*</dt><dd>
|
|
Attempt to restore extended file flags.
|
|
By default, file flags are ignored.
|
|
</dd><dt>*ARCHIVE_EXTRACT_XATTR*</dt><dd>
|
|
Attempt to restore POSIX.1e extended attributes.
|
|
By default, they are ignored.
|
|
</dd><dt>*ARCHIVE_EXTRACT_SECURE_SYMLINKS*</dt><dd>
|
|
Refuse to extract any object whose final location would be altered
|
|
by a symlink on disk.
|
|
This is intended to help guard against a variety of mischief
|
|
caused by archives that (deliberately or otherwise) extract
|
|
files outside of the current directory.
|
|
The default is not to perform this check.
|
|
If
|
|
*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.
|
|
</dd><dt>*ARCHIVE_EXTRACT_SECURE_NODOTDOT*</dt><dd>
|
|
Refuse to extract a path that contains a
|
|
_.._
|
|
element anywhere within it.
|
|
The default is to not refuse such paths.
|
|
Note that paths ending in
|
|
_.._
|
|
always cause an error, regardless of this flag.
|
|
</dd><dt>*ARCHIVE_EXTRACT_SPARSE*</dt><dd>
|
|
Scan data for blocks of NUL bytes and try to recreate them with holes.
|
|
This results in sparse files, independent of whether the archive format
|
|
supports or uses them.
|
|
</dd></dl>
|
|
</dd><dt>
|
|
*archive_write_disk_set_group_lookup*(),
|
|
*archive_write_disk_set_user_lookup*()
|
|
</dt> <dd>
|
|
The
|
|
*struct archive_entry*
|
|
objects contain both names and ids that can be used to identify users
|
|
and groups.
|
|
These names and ids describe the ownership of the file itself and
|
|
also appear in ACL lists.
|
|
By default, the library uses the ids and ignores the names, but
|
|
this can be overridden by registering user and group lookup functions.
|
|
To register, you must provide a lookup function which
|
|
accepts both a name and id and returns a suitable id.
|
|
You may also provide a
|
|
*void `*`*
|
|
pointer to a private data structure and a cleanup function for
|
|
that data.
|
|
The cleanup function will be invoked when the
|
|
*struct archive*
|
|
object is destroyed.
|
|
</dd><dt>*archive_write_disk_set_standard_lookup*()</dt><dd>
|
|
This convenience function installs a standard set of user
|
|
and group lookup functions.
|
|
These functions use
|
|
*getpwnam*(3)
|
|
and
|
|
*getgrnam*(3)
|
|
to convert names to ids, defaulting to the ids if the names cannot
|
|
be looked up.
|
|
These functions also implement a simple memory cache to reduce
|
|
the number of calls to
|
|
*getpwnam*(3)
|
|
and
|
|
*getgrnam*(3).
|
|
</dd><dt>*archive_write_header*()</dt><dd>
|
|
Build and write a header using the data in the provided
|
|
*struct archive_entry*
|
|
structure.
|
|
See
|
|
*archive_entry*(3)
|
|
for information on creating and populating
|
|
*struct archive_entry*
|
|
objects.
|
|
</dd><dt>*archive_write_data*()</dt><dd>
|
|
Write data corresponding to the header just written.
|
|
Returns number of bytes written or -1 on error.
|
|
</dd><dt>*archive_write_finish_entry*()</dt><dd>
|
|
Close out the entry just written.
|
|
Ordinarily, clients never need to call this, as it
|
|
is called automatically by
|
|
*archive_write_next_header*()
|
|
and
|
|
*archive_write_close*()
|
|
as needed.
|
|
</dd><dt>*archive_write_close*()</dt><dd>
|
|
Set any attributes that could not be set during the initial restore.
|
|
For example, directory timestamps are not restored initially because
|
|
restoring a subsequent file would alter that timestamp.
|
|
Similarly, non-writable directories are initially created with
|
|
write permissions (so that their contents can be restored).
|
|
The
|
|
*archive_write_disk_new*
|
|
library maintains a list of all such deferred attributes and
|
|
sets them when this function is invoked.
|
|
</dd><dt>*archive_write_finish*()</dt><dd>
|
|
Invokes
|
|
*archive_write_close*()
|
|
if it was not invoked manually, then releases all resources.
|
|
</dd></dl>
|
|
More information about the
|
|
_struct_ archive
|
|
object and the overall design of the library can be found in the
|
|
*libarchive*(3)
|
|
overview.
|
|
Many of these functions are also documented under
|
|
*archive_write*(3).
|
|
== RETURN VALUES ==
|
|
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.
|
|
The
|
|
*archive_errno*()
|
|
and
|
|
*archive_error_string*()
|
|
functions can be used to retrieve an appropriate error code and a
|
|
textual error message.
|
|
|
|
*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.
|
|
On error, -1 is returned and the
|
|
*archive_errno*()
|
|
and
|
|
*archive_error_string*()
|
|
functions will return appropriate values.
|
|
== SEE ALSO ==
|
|
*archive_read*(3),
|
|
*archive_write*(3),
|
|
*tar*(1),
|
|
*libarchive*(3)
|
|
== HISTORY ==
|
|
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.
|
|
== AUTHORS ==
|
|
The
|
|
*libarchive*
|
|
library was written by
|
|
Tim Kientzle <kientzle@acm.org.>
|
|
== BUGS ==
|
|
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 heirarchy
|
|
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 heirarchy and returns archive
|
|
entry objects.
|