From baea7d877d3cf69679a39e8512a120658a478073 Mon Sep 17 00:00:00 2001 From: Tomas Bzatek Date: Fri, 5 Feb 2010 11:06:31 +0100 Subject: Rebase libarchive to 2.8.0 --- .../doc/html/archive_write_disk.3.html | 421 +++++++++++++++++++++ 1 file changed, 421 insertions(+) create mode 100644 libarchive/libarchive-2.8.0/doc/html/archive_write_disk.3.html (limited to 'libarchive/libarchive-2.8.0/doc/html/archive_write_disk.3.html') diff --git a/libarchive/libarchive-2.8.0/doc/html/archive_write_disk.3.html b/libarchive/libarchive-2.8.0/doc/html/archive_write_disk.3.html new file mode 100644 index 0000000..3d7ef63 --- /dev/null +++ b/libarchive/libarchive-2.8.0/doc/html/archive_write_disk.3.html @@ -0,0 +1,421 @@ + + + + + + + + + + + + + +
+ + +

archive_write_disk(3) FreeBSD Library +Functions Manual archive_write_disk(3)

+ +

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>

+ +

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 *));

+ +

int

+ + +

archive_write_header(struct archive *, +struct archive_entry *);

+ + +

ssize_t

+ + +

archive_write_data(struct archive *, +const void *, size_t);

+ +

int

+ + +

archive_write_finish_entry(struct archive *);

+ +

int

+ + +

archive_write_close(struct archive *);

+ +

int

+ + +

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.

+ + +

archive_write_disk_new()

+ +

Allocates and initializes a +struct archive object suitable for writing objects to +disk.

+ + +

archive_write_disk_set_skip_file()

+ +

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.

+ + +

archive_write_disk_set_options()

+ +

The options field consists of a +bitwise OR of one or more of the following values:

+ +

ARCHIVE_EXTRACT_OWNER

+ +

The user and group IDs should +be set on the restored file. By default, the user and group +IDs are not restored.

+ +

ARCHIVE_EXTRACT_PERM

+ +

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.

+ +

ARCHIVE_EXTRACT_TIME

+ +

The timestamps (mtime, ctime, +and atime) should be restored. By default, they are ignored. +Note that restoring of atime is not currently supported.

+ +

ARCHIVE_EXTRACT_NO_OVERWRITE

+ +

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.

+ +

ARCHIVE_EXTRACT_UNLINK

+ +

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.

+ +

ARCHIVE_EXTRACT_ACL

+ +

Attempt to restore ACLs. By +default, extended ACLs are ignored.

+ +

ARCHIVE_EXTRACT_FFLAGS

+ +

Attempt to restore extended +file flags. By default, file flags are ignored.

+ +

ARCHIVE_EXTRACT_XATTR

+ +

Attempt to restore POSIX.1e +extended attributes. By default, they are ignored.

+ +

ARCHIVE_EXTRACT_SECURE_SYMLINKS

+ +

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.

+ +

ARCHIVE_EXTRACT_SECURE_NODOTDOT

+ +

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.

+ +

ARCHIVE_EXTRACT_SPARSE

+ +

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.

+ + +

archive_write_disk_set_group_lookup(), +archive_write_disk_set_user_lookup()

+ +

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.

+ + +

archive_write_disk_set_standard_lookup()

+ +

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).

+ + +

archive_write_header()

+ +

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.

+ + +

archive_write_data()

+ +

Write data corresponding to the +header just written. Returns number of bytes written or -1 +on error.

+ + +

archive_write_finish_entry()

+ +

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.

+ + +

archive_write_close()

+ +

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.

+ + +

archive_write_finish()

+ +

Invokes +archive_write_close() if it was not invoked manually, +then releases all resources.

+ +

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.

+ + +

FreeBSD 8.0 +August 5, 2008 FreeBSD 8.0

+
+ + -- cgit v1.2.3