diff options
Diffstat (limited to 'libarchive/libarchive-2.4.17/doc/man/archive_write_disk.3')
| -rw-r--r-- | libarchive/libarchive-2.4.17/doc/man/archive_write_disk.3 | 464 |
1 files changed, 0 insertions, 464 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 deleted file mode 100644 index 4e81e1c..0000000 --- a/libarchive/libarchive-2.4.17/doc/man/archive_write_disk.3 +++ /dev/null @@ -1,464 +0,0 @@ -.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. |