diff options
Diffstat (limited to 'libarchive/libarchive-2.8.0/doc/man/archive_write_disk.3')
| -rw-r--r-- | libarchive/libarchive-2.8.0/doc/man/archive_write_disk.3 | 386 |
1 files changed, 386 insertions, 0 deletions
diff --git a/libarchive/libarchive-2.8.0/doc/man/archive_write_disk.3 b/libarchive/libarchive-2.8.0/doc/man/archive_write_disk.3 new file mode 100644 index 0000000..a58181e --- /dev/null +++ b/libarchive/libarchive-2.8.0/doc/man/archive_write_disk.3 @@ -0,0 +1,386 @@ +.TH archive_write_disk 3 "August 5, 2008" "" +.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, +\fB\%archive_write_header\fP, +\fB\%archive_write_data\fP, +\fB\%archive_write_finish_entry\fP, +\fB\%archive_write_close\fP, +\fB\%archive_write_finish\fP +\- functions for creating objects on disk +.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); +.br +\fIint\fP +.br +\fB\%archive_write_header\fP(\fI\%struct\ archive\ *\fP, \fI\%struct\ archive_entry\ *\fP); +.br +\fIssize_t\fP +.br +\fB\%archive_write_data\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ void\ *\fP, \fI\%size_t\fP); +.br +\fIint\fP +.br +\fB\%archive_write_finish_entry\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_write_close\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_write_finish\fP(\fI\%struct\ archive\ *\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_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 +\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. +.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). +.TP +\fB\%archive_write_header\fP() +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 +\fB\%archive_write_data\fP() +Write data corresponding to the header just written. +Returns number of bytes written or -1 on error. +.TP +\fB\%archive_write_finish_entry\fP() +Close out the entry just written. +Ordinarily, clients never need to call this, as it +is called automatically by +\fB\%archive_write_next_header\fP() +and +\fB\%archive_write_close\fP() +as needed. +.TP +\fB\%archive_write_close\fP() +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 +\fB\%archive_write_disk_new\fP +library maintains a list of all such deferred attributes and +sets them when this function is invoked. +.TP +\fB\%archive_write_finish\fP() +Invokes +\fB\%archive_write_close\fP() +if it was not invoked manually, then releases all resources. +.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. +The +\fB\%archive_errno\fP() +and +\fB\%archive_error_string\fP() +functions can be used to retrieve an appropriate error code and a +textual error message. +.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. +On error, -1 is returned and the +\fB\%archive_errno\fP() +and +\fB\%archive_error_string\fP() +functions will return appropriate values. +.SH SEE ALSO +.ad l +\fBarchive_read\fP(3), +\fBarchive_write\fP(3), +\fBtar\fP(1), +\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 heirarchy +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 heirarchy and returns archive +entry objects. |