Initial commitv0.6.36release-0.6.36-dev

1 files changed, 253 insertions, 0 deletions

diff --git a/libarchive/libarchive-2.4.17/doc/text/archive_write_disk.3 b/libarchive/libarchive-2.4.17/doc/text/archive_write_disk.3
new file mode 100644
index 0000000..18e4e50
--- /dev/null
+++ b/libarchive/libarchive-2.4.17/doc/text/archive_write_disk.3
@@ -0,0 +1,253 @@
+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 ar-
+     chive, then write those objects to a struct archive object created using
+     the archive_write_disk() family functions.  This interface is deliber-
+     ately 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 speci-
+		     fied, 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 over-
+		     written; 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 ar-
+		     chives that (deliberately or otherwise) extract files
+		     outside of the current directory.	The default is not to
+		     perform this check.  If ARCHIVE_EXTRACT_UNLINK is speci-
+		     fied 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 any-
+		     where within it.  The default is to not refuse such
+		     paths.  Note that paths ending in .. always cause an
+		     error, regardless of this flag.
+
+     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 func-
+	     tion 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 sim-
+	     ple 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 ini-
+	     tially because restoring a subsequent file would alter that time-
+	     stamp.  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 impossi-
+     ble.  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 cor-
+     rectly handle borderline cases such as a non-writable directory contain-
+     ing 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 per-
+     missions 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 6.0			 March 2, 2007			   FreeBSD 6.0