diff options
Diffstat (limited to 'libarchive/libarchive-2.8.0/doc/wiki/ManPageArchiveWriteDisk3.wiki')
| -rw-r--r-- | libarchive/libarchive-2.8.0/doc/wiki/ManPageArchiveWriteDisk3.wiki | 358 |
1 files changed, 0 insertions, 358 deletions
diff --git a/libarchive/libarchive-2.8.0/doc/wiki/ManPageArchiveWriteDisk3.wiki b/libarchive/libarchive-2.8.0/doc/wiki/ManPageArchiveWriteDisk3.wiki deleted file mode 100644 index f71f85f..0000000 --- a/libarchive/libarchive-2.8.0/doc/wiki/ManPageArchiveWriteDisk3.wiki +++ /dev/null @@ -1,358 +0,0 @@ -#summary archive_write_disk 3 manual page -== 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>* -<br> -*struct archive `*`* -<br> -*archive_write_disk_new*(_void_); -<br> -*int* -<br> -*archive_write_disk_set_options*(_struct archive `*`_, _int flags_); -<br> -*int* -<br> -*archive_write_disk_set_skip_file*(_struct archive `*`_, _dev_t_, _ino_t_); -<br> -*int* -<br> -*archive_write_disk_set_group_lookup*(_struct archive `*`_, _void `*`_, _gid_t (`*`)(void `*`, const char `*`gname, gid_t gid)_, _void (`*`cleanup)(void `*`)_); -<br> -*int* -<br> -*archive_write_disk_set_standard_lookup*(_struct archive `*`_); -<br> -*int* -<br> -*archive_write_disk_set_user_lookup*(_struct archive `*`_, _void `*`_, _uid_t (`*`)(void `*`, const char `*`uname, uid_t uid)_, _void (`*`cleanup)(void `*`)_); -<br> -*int* -<br> -*archive_write_header*(_struct archive `*`_, _struct archive_entry `*`_); -<br> -*ssize_t* -<br> -*archive_write_data*(_struct archive `*`_, _const void `*`_, _size_t_); -<br> -*int* -<br> -*archive_write_finish_entry*(_struct archive `*`_); -<br> -*int* -<br> -*archive_write_close*(_struct archive `*`_); -<br> -*int* -<br> -*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 archive, then write those objects to a -*struct archive* -object created using the -*archive_write_disk*() -family functions. -This interface is deliberately very similar to the -*archive_write*() -interface used to write objects to a streaming archive. -<dl> -<dt>*archive_write_disk_new*()</dt><dd> -Allocates and initializes a -*struct archive* -object suitable for writing objects to disk. -</dd><dt>*archive_write_disk_set_skip_file*()</dt><dd> -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. -</dd><dt>*archive_write_disk_set_options*()</dt><dd> -The options field consists of a bitwise OR of one or more of the -following values: -<dl> -<dt>*ARCHIVE_EXTRACT_OWNER*</dt><dd> -The user and group IDs should be set on the restored file. -By default, the user and group IDs are not restored. -</dd><dt>*ARCHIVE_EXTRACT_PERM*</dt><dd> -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 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. -</dd><dt>*ARCHIVE_EXTRACT_TIME*</dt><dd> -The timestamps (mtime, ctime, and atime) should be restored. -By default, they are ignored. -Note that restoring of atime is not currently supported. -</dd><dt>*ARCHIVE_EXTRACT_NO_OVERWRITE*</dt><dd> -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. -</dd><dt>*ARCHIVE_EXTRACT_UNLINK*</dt><dd> -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. -</dd><dt>*ARCHIVE_EXTRACT_ACL*</dt><dd> -Attempt to restore ACLs. -By default, extended ACLs are ignored. -</dd><dt>*ARCHIVE_EXTRACT_FFLAGS*</dt><dd> -Attempt to restore extended file flags. -By default, file flags are ignored. -</dd><dt>*ARCHIVE_EXTRACT_XATTR*</dt><dd> -Attempt to restore POSIX.1e extended attributes. -By default, they are ignored. -</dd><dt>*ARCHIVE_EXTRACT_SECURE_SYMLINKS*</dt><dd> -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 -*ARCHIVE_EXTRACT_UNLINK* -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. -</dd><dt>*ARCHIVE_EXTRACT_SECURE_NODOTDOT*</dt><dd> -Refuse to extract a path that contains a -_.._ -element anywhere within it. -The default is to not refuse such paths. -Note that paths ending in -_.._ -always cause an error, regardless of this flag. -</dd><dt>*ARCHIVE_EXTRACT_SPARSE*</dt><dd> -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. -</dd></dl> -</dd><dt> -*archive_write_disk_set_group_lookup*(), -*archive_write_disk_set_user_lookup*() -</dt> <dd> -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. -</dd><dt>*archive_write_disk_set_standard_lookup*()</dt><dd> -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). -</dd><dt>*archive_write_header*()</dt><dd> -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. -</dd><dt>*archive_write_data*()</dt><dd> -Write data corresponding to the header just written. -Returns number of bytes written or -1 on error. -</dd><dt>*archive_write_finish_entry*()</dt><dd> -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. -</dd><dt>*archive_write_close*()</dt><dd> -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 -*archive_write_disk_new* -library maintains a list of all such deferred attributes and -sets them when this function is invoked. -</dd><dt>*archive_write_finish*()</dt><dd> -Invokes -*archive_write_close*() -if it was not invoked manually, then releases all resources. -</dd></dl> -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 impossible. -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 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 -*archive_read_extract*() -or before calling -*archive_read_close*(), -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 -*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. |