diff options
| author | joerg <joerg@pkgsrc.org> | 2010-02-20 03:48:25 +0000 |
|---|---|---|
| committer | joerg <joerg@pkgsrc.org> | 2010-02-20 03:48:25 +0000 |
| commit | 813e1c65cfea70db0fa02bd006013a08731f470f (patch) | |
| tree | f2e9909a57c8ba8f986b13e36ed04e225fc44b2a /archivers/libarchive/files/doc/html/archive_write_disk.3.html | |
| parent | a3bb8bd3027e67eb07c16f479613f290fb214f4a (diff) | |
| download | pkgsrc-813e1c65cfea70db0fa02bd006013a08731f470f.tar.gz | |
Import libarchive 2.8.0:
- Infrastructure:
- Allow command line tools as fallback for missing compression
libraries. If compiled without gzip for example, gunzip will
be used automatically.
- Improved support for a number of platforms like high-resolution
timestamps and Extended Attributes on various Unix systems
- New convience interface for creating archives based on disk content,
complement of the archive_write_disk interface.
- Frontends:
- bsdcpio ready for public consumption
- hand-written date parser replaces the yacc code
- Filter system:
- Simplified read filter chains
- Option support for filters
- LZMA, XZ, uudecode handled
- Format support:
- Write support for mtree files based on file system or archive
content
- Basic read support for Joliet
- Write support for zip files
- Write support for shar archives, both text-only and binary-safe
Diffstat (limited to 'archivers/libarchive/files/doc/html/archive_write_disk.3.html')
| -rw-r--r-- | archivers/libarchive/files/doc/html/archive_write_disk.3.html | 421 |
1 files changed, 421 insertions, 0 deletions
diff --git a/archivers/libarchive/files/doc/html/archive_write_disk.3.html b/archivers/libarchive/files/doc/html/archive_write_disk.3.html new file mode 100644 index 00000000000..3d7ef6367ed --- /dev/null +++ b/archivers/libarchive/files/doc/html/archive_write_disk.3.html @@ -0,0 +1,421 @@ +<!-- Creator : groff version 1.19.2 --> +<!-- CreationDate: Thu Feb 4 20:36:34 2010 --> +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" +"http://www.w3.org/TR/html4/loose.dtd"> +<html> +<head> +<meta name="generator" content="groff -Thtml, see www.gnu.org"> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<meta name="Content-Style" content="text/css"> +<style type="text/css"> + p { margin-top: 0; margin-bottom: 0; } + pre { margin-top: 0; margin-bottom: 0; } + table { margin-top: 0; margin-bottom: 0; } +</style> +<title></title> +</head> +<body> + +<hr> + + +<p valign="top">archive_write_disk(3) FreeBSD Library +Functions Manual archive_write_disk(3)</p> + +<p style="margin-top: 1em" valign="top"><b>NAME</b></p> + +<p style="margin-left:8%;"><b>archive_write_disk_new</b>, +<b>archive_write_disk_set_options</b>, +<b>archive_write_disk_set_skip_file</b>, +<b>archive_write_disk_set_group_lookup</b>, +<b>archive_write_disk_set_standard_lookup</b>, +<b>archive_write_disk_set_user_lookup</b>, +<b>archive_write_header</b>, <b>archive_write_data</b>, +<b>archive_write_finish_entry</b>, +<b>archive_write_close</b>, <b>archive_write_finish</b> +— functions for creating objects on disk</p> + + +<p style="margin-top: 1em" valign="top"><b>SYNOPSIS</b></p> + +<p style="margin-left:8%;"><b>#include +<archive.h></b></p> + +<p style="margin-left:8%; margin-top: 1em"><i>struct +archive *</i></p> + + +<p style="margin-left:14%;"><b>archive_write_disk_new</b>(<i>void</i>);</p> + +<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> + + +<p style="margin-left:14%;"><b>archive_write_disk_set_options</b>(<i>struct archive *</i>, +<i>int flags</i>);</p> + +<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> + + +<p style="margin-left:14%;"><b>archive_write_disk_set_skip_file</b>(<i>struct archive *</i>, +<i>dev_t</i>, <i>ino_t</i>);</p> + +<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> + + +<p valign="top"><b>archive_write_disk_set_group_lookup</b>(<i>struct archive *</i>, +<i>void *</i>, +<i>gid_t (*)(void *, const char *gname, gid_t gid)</i>, +<i>void (*cleanup)(void *)</i>);</p> + +<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> + + +<p style="margin-left:14%;"><b>archive_write_disk_set_standard_lookup</b>(<i>struct archive *</i>);</p> + +<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> + + +<p valign="top"><b>archive_write_disk_set_user_lookup</b>(<i>struct archive *</i>, +<i>void *</i>, +<i>uid_t (*)(void *, const char *uname, uid_t uid)</i>, +<i>void (*cleanup)(void *)</i>);</p> + +<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> + + +<p style="margin-left:14%;"><b>archive_write_header</b>(<i>struct archive *</i>, +<i>struct archive_entry *</i>);</p> + + +<p style="margin-left:8%; margin-top: 1em"><i>ssize_t</i></p> + + +<p style="margin-left:14%;"><b>archive_write_data</b>(<i>struct archive *</i>, +<i>const void *</i>, <i>size_t</i>);</p> + +<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> + + +<p style="margin-left:14%;"><b>archive_write_finish_entry</b>(<i>struct archive *</i>);</p> + +<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> + + +<p style="margin-left:14%;"><b>archive_write_close</b>(<i>struct archive *</i>);</p> + +<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> + + +<p style="margin-left:14%;"><b>archive_write_finish</b>(<i>struct archive *</i>);</p> + + +<p style="margin-top: 1em" valign="top"><b>DESCRIPTION</b></p> + +<p style="margin-left:8%;">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 +<b>archive_read</b>() 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 <b>archive_write_disk</b>() family functions. This +interface is deliberately very similar to the +<b>archive_write</b>() interface used to write objects to a +streaming archive.</p> + + +<p style="margin-top: 1em" valign="top"><b>archive_write_disk_new</b>()</p> + +<p style="margin-left:20%;">Allocates and initializes a +struct archive object suitable for writing objects to +disk.</p> + + +<p style="margin-top: 1em" valign="top"><b>archive_write_disk_set_skip_file</b>()</p> + +<p style="margin-left:20%;">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.</p> + + +<p style="margin-top: 1em" valign="top"><b>archive_write_disk_set_options</b>()</p> + +<p style="margin-left:20%;">The options field consists of a +bitwise OR of one or more of the following values:</p> + +<p valign="top"><b>ARCHIVE_EXTRACT_OWNER</b></p> + +<p style="margin-left:32%;">The user and group IDs should +be set on the restored file. By default, the user and group +IDs are not restored.</p> + +<p valign="top"><b>ARCHIVE_EXTRACT_PERM</b></p> + +<p style="margin-left:32%;">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 +<b>ARCHIVE_EXTRACT_OWNER</b> 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.</p> + +<p valign="top"><b>ARCHIVE_EXTRACT_TIME</b></p> + +<p style="margin-left:32%;">The timestamps (mtime, ctime, +and atime) should be restored. By default, they are ignored. +Note that restoring of atime is not currently supported.</p> + +<p valign="top"><b>ARCHIVE_EXTRACT_NO_OVERWRITE</b></p> + +<p style="margin-left:32%;">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.</p> + +<p valign="top"><b>ARCHIVE_EXTRACT_UNLINK</b></p> + +<p style="margin-left:32%;">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.</p> + +<p valign="top"><b>ARCHIVE_EXTRACT_ACL</b></p> + +<p style="margin-left:32%;">Attempt to restore ACLs. By +default, extended ACLs are ignored.</p> + +<p valign="top"><b>ARCHIVE_EXTRACT_FFLAGS</b></p> + +<p style="margin-left:32%;">Attempt to restore extended +file flags. By default, file flags are ignored.</p> + +<p valign="top"><b>ARCHIVE_EXTRACT_XATTR</b></p> + +<p style="margin-left:32%;">Attempt to restore POSIX.1e +extended attributes. By default, they are ignored.</p> + +<p valign="top"><b>ARCHIVE_EXTRACT_SECURE_SYMLINKS</b></p> + +<p style="margin-left:32%;">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 <b>ARCHIVE_EXTRACT_UNLINK</b> 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.</p> + +<p valign="top"><b>ARCHIVE_EXTRACT_SECURE_NODOTDOT</b></p> + +<p style="margin-left:32%;">Refuse to extract a path that +contains a <i>..</i> element anywhere within it. The default +is to not refuse such paths. Note that paths ending in +<i>..</i> always cause an error, regardless of this +flag.</p> + +<p valign="top"><b>ARCHIVE_EXTRACT_SPARSE</b></p> + +<p style="margin-left:32%;">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.</p> + + +<p style="margin-top: 1em" valign="top"><b>archive_write_disk_set_group_lookup</b>(), +<b>archive_write_disk_set_user_lookup</b>()</p> + +<p style="margin-left:20%;">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.</p> + + +<p style="margin-top: 1em" valign="top"><b>archive_write_disk_set_standard_lookup</b>()</p> + +<p style="margin-left:20%;">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).</p> + + +<p style="margin-top: 1em" valign="top"><b>archive_write_header</b>()</p> + +<p style="margin-left:20%;">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.</p> + + +<p style="margin-top: 1em" valign="top"><b>archive_write_data</b>()</p> + +<p style="margin-left:20%;">Write data corresponding to the +header just written. Returns number of bytes written or -1 +on error.</p> + + +<p style="margin-top: 1em" valign="top"><b>archive_write_finish_entry</b>()</p> + +<p style="margin-left:20%;">Close out the entry just +written. Ordinarily, clients never need to call this, as it +is called automatically by +<b>archive_write_next_header</b>() and +<b>archive_write_close</b>() as needed.</p> + + +<p style="margin-top: 1em" valign="top"><b>archive_write_close</b>()</p> + +<p style="margin-left:20%;">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 <b>archive_write_disk_new</b> library +maintains a list of all such deferred attributes and sets +them when this function is invoked.</p> + + +<p style="margin-top: 1em" valign="top"><b>archive_write_finish</b>()</p> + +<p style="margin-left:20%;">Invokes +<b>archive_write_close</b>() if it was not invoked manually, +then releases all resources.</p> + +<p style="margin-left:8%;">More information about the +<i>struct archive</i> 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).</p> + +<p style="margin-top: 1em" valign="top"><b>RETURN +VALUES</b></p> + +<p style="margin-left:8%;">Most functions return +<b>ARCHIVE_OK</b> (zero) on success, or one of several +non-zero error codes for errors. Specific error codes +include: <b>ARCHIVE_RETRY</b> for operations that might +succeed if retried, <b>ARCHIVE_WARN</b> for unusual +conditions that do not prevent further operations, and +<b>ARCHIVE_FATAL</b> for serious errors that make remaining +operations impossible. The <b>archive_errno</b>() and +<b>archive_error_string</b>() functions can be used to +retrieve an appropriate error code and a textual error +message.</p> + + +<p style="margin-left:8%; margin-top: 1em"><b>archive_write_disk_new</b>() +returns a pointer to a newly-allocated struct archive +object.</p> + + +<p style="margin-left:8%; margin-top: 1em"><b>archive_write_data</b>() +returns a count of the number of bytes actually written. On +error, -1 is returned and the <b>archive_errno</b>() and +<b>archive_error_string</b>() functions will return +appropriate values.</p> + +<p style="margin-top: 1em" valign="top"><b>SEE ALSO</b></p> + +<p style="margin-left:8%;">archive_read(3), +archive_write(3), tar(1), libarchive(3)</p> + +<p style="margin-top: 1em" valign="top"><b>HISTORY</b></p> + +<p style="margin-left:8%;">The <b>libarchive</b> library +first appeared in FreeBSD 5.3. The +<b>archive_write_disk</b> interface was added to +<b>libarchive 2.0</b> and first appeared in +FreeBSD 6.3.</p> + +<p style="margin-top: 1em" valign="top"><b>AUTHORS</b></p> + +<p style="margin-left:8%;">The <b>libarchive</b> library +was written by Tim Kientzle +⟨kientzle@acm.org⟩.</p> + +<p style="margin-top: 1em" valign="top"><b>BUGS</b></p> + +<p style="margin-left:8%;">Directories are actually +extracted in two distinct phases. Directories are created +during <b>archive_write_header</b>(), but final permissions +are not set until <b>archive_write_close</b>(). 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 <b>archive_read_extract</b>() or before +calling <b>archive_read_close</b>(), you may confuse the +permission-setting logic with the result that directory +permissions are restored incorrectly.</p> + +<p style="margin-left:8%; margin-top: 1em">The library +attempts to create objects with filenames longer than +<b>PATH_MAX</b> 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.</p> + +<p style="margin-left:8%; margin-top: 1em">Restoring the +path <i>aa/../bb</i> does create each intermediate +directory. In particular, the directory <i>aa</i> is created +as well as the final object <i>bb</i>. In theory, this can +be exploited to create an entire directory heirarchy with a +single request. Of course, this does not work if the +<b>ARCHIVE_EXTRACT_NODOTDOT</b> option is specified.</p> + +<p style="margin-left:8%; margin-top: 1em">Implicit +directories are always created obeying the current umask. +Explicit objects are created obeying the current umask +unless <b>ARCHIVE_EXTRACT_PERM</b> is specified, in which +case they current umask is ignored.</p> + +<p style="margin-left:8%; margin-top: 1em">SGID and SUID +bits are restored only if the correct user and group could +be set. If <b>ARCHIVE_EXTRACT_OWNER</b> 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.</p> + +<p style="margin-left:8%; margin-top: 1em">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.</p> + +<p style="margin-left:8%; margin-top: 1em">There should be +a corresponding <b>archive_read_disk</b> interface that +walks a directory heirarchy and returns archive entry +objects.</p> + + +<p style="margin-left:8%; margin-top: 1em">FreeBSD 8.0 +August 5, 2008 FreeBSD 8.0</p> +<hr> +</body> +</html> |