Qt/QML edition

dependencies/libarchive-3.4.2/doc/man/archive_write_disk.3

@@ -0,0 +1,364 @@
+.TH ARCHIVE_WRITE_DISK 3 "January 19, 2020" ""
+.SH NAME
+.ad l
+\fB\%archive_write_disk_new\fP,
+\fB\%archive_write_disk_set_options\fP,
+\fB\%archive_write_disk_set_skip_file\fP,
+\fB\%archive_write_disk_set_group_lookup\fP,
+\fB\%archive_write_disk_set_standard_lookup\fP,
+\fB\%archive_write_disk_set_user_lookup\fP
+\- functions for creating objects on disk
+.SH LIBRARY
+.ad l
+Streaming Archive Library (libarchive, -larchive)
+.SH SYNOPSIS
+.ad l
+\fB#include <archive.h>\fP
+.br
+\fIstruct archive *\fP
+.br
+\fB\%archive_write_disk_new\fP(\fI\%void\fP);
+.br
+\fIint\fP
+.br
+\fB\%archive_write_disk_set_options\fP(\fI\%struct\ archive\ *\fP, \fI\%int\ flags\fP);
+.br
+\fIint\fP
+.br
+\fB\%archive_write_disk_set_skip_file\fP(\fI\%struct\ archive\ *\fP, \fI\%dev_t\fP, \fI\%ino_t\fP);
+.br
+\fIint\fP
+.br
+\fB\%archive_write_disk_set_group_lookup\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *\fP, \fI\%gid_t\ (*)(void\ *,\ const\ char\ *gname,\ gid_t\ gid)\fP, \fI\%void\ (*cleanup)(void\ *)\fP);
+.br
+\fIint\fP
+.br
+\fB\%archive_write_disk_set_standard_lookup\fP(\fI\%struct\ archive\ *\fP);
+.br
+\fIint\fP
+.br
+\fB\%archive_write_disk_set_user_lookup\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *\fP, \fI\%uid_t\ (*)(void\ *,\ const\ char\ *uname,\ uid_t\ uid)\fP, \fI\%void\ (*cleanup)(void\ *)\fP);
+.SH DESCRIPTION
+.ad l
+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
+\fB\%archive_read\fP()
+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
+\fB\%archive_write_disk\fP()
+family functions.
+This interface is deliberately very similar to the
+\fB\%archive_write\fP()
+interface used to write objects to a streaming archive.
+.RS 5
+.TP
+\fB\%archive_write_disk_new\fP()
+Allocates and initializes a
+Tn struct archive
+object suitable for writing objects to disk.
+.TP
+\fB\%archive_write_disk_set_skip_file\fP()
+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
+\fB\%archive_write_disk_set_options\fP()
+The options field consists of a bitwise OR of one or more of the
+following values:
+.RS 5
+.TP
+\fBARCHIVE_EXTRACT_ACL\fP
+Attempt to restore Access Control Lists.
+By default, extended ACLs are ignored.
+.TP
+\fBARCHIVE_EXTRACT_CLEAR_NOCHANGE_FFLAGS\fP
+Before removing a file system object prior to replacing it, clear
+platform-specific file flags which might prevent its removal.
+.TP
+\fBARCHIVE_EXTRACT_FFLAGS\fP
+Attempt to restore file attributes (file flags).
+By default, file attributes are ignored.
+See
+\fBchattr\fP(1)
+(Linux)
+or
+\fBchflags\fP(1)
+(FreeBSD, Mac OS X)
+for more information on file attributes.
+.TP
+\fBARCHIVE_EXTRACT_MAC_METADATA\fP
+Mac OS X specific.
+Restore metadata using
+\fBcopyfile\fP(3).
+By default,
+\fBcopyfile\fP(3)
+metadata is ignored.
+.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_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_SAFE_WRITES\fP
+Extract files atomically, by first creating a unique temporary file and then
+renaming it to its required destination name.
+This avoids a race where an application might see a partial file (or no
+file) during extraction.
+.TP
+\fBARCHIVE_EXTRACT_SECURE_NOABSOLUTEPATHS\fP
+Refuse to extract an absolute path.
+The default is to not refuse such paths.
+.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
+\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
+.TP
+\fBARCHIVE_EXTRACT_SPARSE\fP
+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.
+\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_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_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_XATTR\fP
+Attempt to restore extended file attributes.
+By default, they are ignored.
+See
+\fBxattr\fP(7)
+(Linux,)
+\fBxattr\fP(2)
+(Mac OS X,)
+or
+\fBgetextattr\fP(8)
+(FreeBSD)
+for more information on extended file attributes.
+.RE
+.TP
+\fB\%archive_write_disk_set_group_lookup\fP(),
+\fB\%archive_write_disk_set_user_lookup\fP()
+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
+\fB\%archive_write_disk_set_standard_lookup\fP()
+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).
+.RE
+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
+.ad l
+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.
+.PP
+\fB\%archive_write_disk_new\fP()
+returns a pointer to a newly-allocated
+Tn struct archive
+object.
+.PP
+\fB\%archive_write_data\fP()
+returns a count of the number of bytes actually written,
+or
+.RS 4
+-1
+.RE
+on error.
+.SH ERRORS
+.ad l
+Detailed error codes and textual descriptions are available from the
+\fB\%archive_errno\fP()
+and
+\fB\%archive_error_string\fP()
+functions.
+.SH SEE ALSO
+.ad l
+\fBtar\fP(1),
+\fBarchive_read\fP(3),
+\fBarchive_write\fP(3),
+\fBlibarchive\fP(3)
+.SH HISTORY
+.ad l
+The
+\fB\%libarchive\fP
+library first appeared in
+FreeBSD 5.3.
+The
+\fB\%archive_write_disk\fP
+interface was added to
+\fB\%libarchive\fP 2.0
+and first appeared in
+FreeBSD 6.3.
+.SH AUTHORS
+.ad l
+-nosplit
+The
+\fB\%libarchive\fP
+library was written by
+Tim Kientzle \%<kientzle@acm.org.>
+.SH BUGS
+.ad l
+Directories are actually extracted in two distinct phases.
+Directories are created during
+\fB\%archive_write_header\fP(),
+but final permissions are not set until
+\fB\%archive_write_close\fP().
+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
+\fB\%archive_read_extract\fP()
+or before calling
+\fB\%archive_read_close\fP(),
+you may confuse the permission-setting logic with
+the result that directory permissions are restored
+incorrectly.
+.PP
+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.
+.PP
+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 hierarchy
+with a single request.
+Of course, this does not work if the
+\fBARCHIVE_EXTRACT_NODOTDOT\fP
+option is specified.
+.PP
+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.
+.PP
+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.
+.PP
+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.
+.PP
+There should be a corresponding
+\fB\%archive_read_disk\fP
+interface that walks a directory hierarchy and returns archive
+entry objects.