Initial commitv0.6.36release-0.6.36-dev

1 files changed, 464 insertions, 0 deletions

diff --git a/libarchive/libarchive-2.4.17/doc/man/archive_write_disk.3 b/libarchive/libarchive-2.4.17/doc/man/archive_write_disk.3
new file mode 100644
index 0000000..4e81e1c
--- /dev/null
+++ b/libarchive/libarchive-2.4.17/doc/man/archive_write_disk.3
@@ -0,0 +1,464 @@
+.TH archive_write_disk 3 "March 2, 2007" ""
+.SH NAME
+\fBarchive_write_disk_new\fP,
+\fBarchive_write_disk_set_options\fP,
+\fBarchive_write_disk_set_skip_file\fP,
+\fBarchive_write_disk_set_group_lookup\fP,
+\fBarchive_write_disk_set_standard_lookup\fP,
+\fBarchive_write_disk_set_user_lookup\fP,
+\fBarchive_write_header\fP,
+\fBarchive_write_data\fP,
+\fBarchive_write_finish_entry\fP,
+\fBarchive_write_close\fP,
+\fBarchive_write_finish\fP
+\- functions for creating objects on disk
+.SH SYNOPSIS
+\fB#include <archive.h>\fP
+.br
+\fIstruct archive *\fP
+.RE
+.nh
+\fBarchive_write_disk_new\fP
+.hy
+("void");
+\fIint\fP
+.RE
+.nh
+\fBarchive_write_disk_set_options\fP
+.hy
+("struct archive *" "int flags");
+\fIint\fP
+.RE
+.nh
+\fBarchive_write_disk_set_skip_file\fP
+.hy
+("struct archive *" "dev_t" "ino_t");
+\fIint\fP
+.RE
+.nh
+\fBarchive_write_disk_set_group_lookup\fP
+.hy
+("struct archive *" "void *" "gid_t (*)(void *, const char *gname, gid_t gid)" "void (*cleanup)(void *)");
+\fIint\fP
+.RE
+.nh
+\fBarchive_write_disk_set_standard_lookup\fP
+.hy
+("struct archive *");
+\fIint\fP
+.RE
+.nh
+\fBarchive_write_disk_set_user_lookup\fP
+.hy
+("struct archive *" "void *" "uid_t (*)(void *, const char *uname, uid_t uid)" "void (*cleanup)(void *)");
+\fIint\fP
+.RE
+.nh
+\fBarchive_write_header\fP
+.hy
+("struct archive *" "struct archive_entry *");
+\fIssize_t\fP
+.RE
+.nh
+\fBarchive_write_data\fP
+.hy
+("struct archive *" "const void *" "size_t");
+\fIint\fP
+.RE
+.nh
+\fBarchive_write_finish_entry\fP
+.hy
+("struct archive *");
+\fIint\fP
+.RE
+.nh
+\fBarchive_write_close\fP
+.hy
+("struct archive *");
+\fIint\fP
+.RE
+.nh
+\fBarchive_write_finish\fP
+.hy
+("struct archive *");
+.SH DESCRIPTION
+These functions provide a complete API for creating objects on
+disk from
+Tn struct archive_entry
+descriptions.
+They are most naturally used when extracting objects from an archive
+using the
+.nh
+\fBarchive_read\fP
+.hy
+();
+interface.
+The general process is to read
+Tn struct archive_entry
+objects from an archive, then write those objects to a
+Tn struct archive
+object created using the
+.nh
+\fBarchive_write_disk\fP
+.hy
+();
+family functions.
+This interface is deliberately very similar to the
+.nh
+\fBarchive_write\fP
+.hy
+();
+interface used to write objects to a streaming archive.
+.TP
+.nh
+\fBarchive_write_disk_new\fP
+.hy
+();
+Allocates and initializes a
+Tn struct archive
+object suitable for writing objects to disk.
+.TP
+.nh
+\fBarchive_write_disk_set_skip_file\fP
+.hy
+();
+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.
+.TP
+.nh
+\fBarchive_write_disk_set_options\fP
+.hy
+();
+The options field consists of a bitwise OR of one or more of the
+following values:
+.TP
+\fBARCHIVE_EXTRACT_OWNER\fP
+The user and group IDs should be set on the restored file.
+By default, the user and group IDs are not restored.
+.TP
+\fBARCHIVE_EXTRACT_PERM\fP
+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
+\fBARCHIVE_EXTRACT_OWNER\fP
+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.
+.TP
+\fBARCHIVE_EXTRACT_TIME\fP
+The timestamps (mtime, ctime, and atime) should be restored.
+By default, they are ignored.
+Note that restoring of atime is not currently supported.
+.TP
+\fBARCHIVE_EXTRACT_NO_OVERWRITE\fP
+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.
+.TP
+\fBARCHIVE_EXTRACT_UNLINK\fP
+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.
+.TP
+\fBARCHIVE_EXTRACT_ACL\fP
+Attempt to restore ACLs.
+By default, extended ACLs are ignored.
+.TP
+\fBARCHIVE_EXTRACT_FFLAGS\fP
+Attempt to restore extended file flags.
+By default, file flags are ignored.
+.TP
+\fBARCHIVE_EXTRACT_XATTR\fP
+Attempt to restore POSIX.1e extended attributes.
+By default, they are ignored.
+.TP
+\fBARCHIVE_EXTRACT_SECURE_SYMLINKS\fP
+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
+\fBARCHIVE_EXTRACT_UNLINK\fP
+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.
+.TP
+\fBARCHIVE_EXTRACT_SECURE_NODOTDOT\fP
+Refuse to extract a path that contains a
+\fI\& ..\fP
+element anywhere within it.
+The default is to not refuse such paths.
+Note that paths ending in
+\fI\& ..\fP
+always cause an error, regardless of this flag.
+.TP
+.nh
+\fBarchive_write_disk_set_group_lookup\fP
+.hy
+(, .nh);
+\fBarchive_write_disk_set_user_lookup\fP
+.hy
+();
+The
+Tn 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
+Tn void *
+pointer to a private data structure and a cleanup function for
+that data.
+The cleanup function will be invoked when the
+Tn struct archive
+object is destroyed.
+.TP
+.nh
+\fBarchive_write_disk_set_standard_lookup\fP
+.hy
+();
+This convenience function installs a standard set of user
+and group lookup functions.
+These functions use
+\fBgetpwnam\fP(3)
+and
+\fBgetgrnam\fP(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
+\fBgetpwnam\fP(3)
+and
+\fBgetgrnam\fP(3).
+.TP
+.nh
+\fBarchive_write_header\fP
+.hy
+();
+Build and write a header using the data in the provided
+Tn struct archive_entry
+structure.
+See
+\fBarchive_entry\fP(3)
+for information on creating and populating
+Tn struct archive_entry
+objects.
+.TP
+.nh
+\fBarchive_write_data\fP
+.hy
+();
+Write data corresponding to the header just written.
+Returns number of bytes written or -1 on error.
+.TP
+.nh
+\fBarchive_write_finish_entry\fP
+.hy
+();
+Close out the entry just written.
+Ordinarily, clients never need to call this, as it
+is called automatically by
+.nh
+\fBarchive_write_next_header\fP
+.hy
+();
+and
+.nh
+\fBarchive_write_close\fP
+.hy
+();
+as needed.
+.TP
+.nh
+\fBarchive_write_close\fP
+.hy
+();
+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
+\fBarchive_write_disk_new\fP
+library maintains a list of all such deferred attributes and
+sets them when this function is invoked.
+.TP
+.nh
+\fBarchive_write_finish\fP
+.hy
+();
+Invokes
+.nh
+\fBarchive_write_close\fP
+.hy
+();
+if it was not invoked manually, then releases all resources.
+More information about the
+\fIstruct\fP archive
+object and the overall design of the library can be found in the
+\fBlibarchive\fP(3)
+overview.
+Many of these functions are also documented under
+\fBarchive_write\fP(3).
+.SH RETURN VALUES
+Most functions return
+\fBARCHIVE_OK\fP
+(zero) on success, or one of several non-zero
+error codes for errors.
+Specific error codes include:
+\fBARCHIVE_RETRY\fP
+for operations that might succeed if retried,
+\fBARCHIVE_WARN\fP
+for unusual conditions that do not prevent further operations, and
+\fBARCHIVE_FATAL\fP
+for serious errors that make remaining operations impossible.
+The
+.nh
+\fBarchive_errno\fP
+.hy
+();
+and
+.nh
+\fBarchive_error_string\fP
+.hy
+();
+functions can be used to retrieve an appropriate error code and a
+textual error message.
+.nh
+\fBarchive_write_disk_new\fP
+.hy
+();
+returns a pointer to a newly-allocated
+Tn struct archive
+object.
+.nh
+\fBarchive_write_data\fP
+.hy
+();
+returns a count of the number of bytes actually written.
+On error, -1 is returned and the
+.nh
+\fBarchive_errno\fP
+.hy
+();
+and
+.nh
+\fBarchive_error_string\fP
+.hy
+();
+functions will return appropriate values.
+.SH SEE ALSO
+\fBarchive_read\fP(3),
+\fBarchive_write\fP(3),
+\fBtar\fP(1),
+\fBlibarchive\fP(3)
+.SH HISTORY
+The
+\fBlibarchive\fP
+library first appeared in
+FreeBSD 5.3.
+The
+\fBarchive_write_disk\fP
+interface was added to
+\fBlibarchive\fP 2.0
+and first appeared in
+FreeBSD 6.3.
+.SH AUTHORS
+-nosplit
+The
+\fBlibarchive\fP
+library was written by
+Tim Kientzle <kientzle@acm.org.>
+.SH BUGS
+Directories are actually extracted in two distinct phases.
+Directories are created during
+.nh
+\fBarchive_write_header\fP
+.hy
+(,);
+but final permissions are not set until
+.nh
+\fBarchive_write_close\fP
+.hy
+(.);
+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
+\fBchdir\fP(2)
+to change the current directory between calls to
+.nh
+\fBarchive_read_extract\fP
+.hy
+();
+or before calling
+.nh
+\fBarchive_read_close\fP
+.hy
+(,);
+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
+\fBPATH_MAX\fP
+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
+\fIaa/../bb\fP
+does create each intermediate directory.
+In particular, the directory
+\fIaa\fP
+is created as well as the final object
+\fIbb\fP.
+In theory, this can be exploited to create an entire directory heirarchy
+with a single request.
+Of course, this does not work if the
+\fBARCHIVE_EXTRACT_NODOTDOT\fP
+option is specified.
+Implicit directories are always created obeying the current umask.
+Explicit objects are created obeying the current umask unless
+\fBARCHIVE_EXTRACT_PERM\fP
+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
+\fBARCHIVE_EXTRACT_OWNER\fP
+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
+\fBgetgrnam\fP(3)
+and
+\fBgetpwnam\fP(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
+\fBarchive_read_disk\fP
+interface that walks a directory heirarchy and returns archive
+entry objects.