diff options
Diffstat (limited to 'libarchive/libarchive-2.8.0/doc/man')
| -rw-r--r-- | libarchive/libarchive-2.8.0/doc/man/Makefile | 46 | ||||
| -rw-r--r-- | libarchive/libarchive-2.8.0/doc/man/archive_entry.3 | 519 | ||||
| -rw-r--r-- | libarchive/libarchive-2.8.0/doc/man/archive_read.3 | 733 | ||||
| -rw-r--r-- | libarchive/libarchive-2.8.0/doc/man/archive_read_disk.3 | 300 | ||||
| -rw-r--r-- | libarchive/libarchive-2.8.0/doc/man/archive_util.3 | 163 | ||||
| -rw-r--r-- | libarchive/libarchive-2.8.0/doc/man/archive_write.3 | 670 | ||||
| -rw-r--r-- | libarchive/libarchive-2.8.0/doc/man/archive_write_disk.3 | 386 | ||||
| -rw-r--r-- | libarchive/libarchive-2.8.0/doc/man/bsdcpio.1 | 446 | ||||
| -rw-r--r-- | libarchive/libarchive-2.8.0/doc/man/bsdtar.1 | 1024 | ||||
| -rw-r--r-- | libarchive/libarchive-2.8.0/doc/man/cpio.5 | 329 | ||||
| -rw-r--r-- | libarchive/libarchive-2.8.0/doc/man/libarchive-formats.5 | 341 | ||||
| -rw-r--r-- | libarchive/libarchive-2.8.0/doc/man/libarchive.3 | 315 | ||||
| -rw-r--r-- | libarchive/libarchive-2.8.0/doc/man/libarchive_internals.3 | 361 | ||||
| -rw-r--r-- | libarchive/libarchive-2.8.0/doc/man/mtree.5 | 282 | ||||
| -rw-r--r-- | libarchive/libarchive-2.8.0/doc/man/tar.5 | 869 |
15 files changed, 6784 insertions, 0 deletions
diff --git a/libarchive/libarchive-2.8.0/doc/man/Makefile b/libarchive/libarchive-2.8.0/doc/man/Makefile new file mode 100644 index 0000000..d3a9019 --- /dev/null +++ b/libarchive/libarchive-2.8.0/doc/man/Makefile @@ -0,0 +1,46 @@ + +default: all + + +archive_entry.3: ../mdoc2man.awk ../../libarchive/archive_entry.3 + awk -f ../mdoc2man.awk < ../../libarchive/archive_entry.3 > archive_entry.3 + +archive_read.3: ../mdoc2man.awk ../../libarchive/archive_read.3 + awk -f ../mdoc2man.awk < ../../libarchive/archive_read.3 > archive_read.3 + +archive_read_disk.3: ../mdoc2man.awk ../../libarchive/archive_read_disk.3 + awk -f ../mdoc2man.awk < ../../libarchive/archive_read_disk.3 > archive_read_disk.3 + +archive_util.3: ../mdoc2man.awk ../../libarchive/archive_util.3 + awk -f ../mdoc2man.awk < ../../libarchive/archive_util.3 > archive_util.3 + +archive_write.3: ../mdoc2man.awk ../../libarchive/archive_write.3 + awk -f ../mdoc2man.awk < ../../libarchive/archive_write.3 > archive_write.3 + +archive_write_disk.3: ../mdoc2man.awk ../../libarchive/archive_write_disk.3 + awk -f ../mdoc2man.awk < ../../libarchive/archive_write_disk.3 > archive_write_disk.3 + +cpio.5: ../mdoc2man.awk ../../libarchive/cpio.5 + awk -f ../mdoc2man.awk < ../../libarchive/cpio.5 > cpio.5 + +libarchive-formats.5: ../mdoc2man.awk ../../libarchive/libarchive-formats.5 + awk -f ../mdoc2man.awk < ../../libarchive/libarchive-formats.5 > libarchive-formats.5 + +libarchive.3: ../mdoc2man.awk ../../libarchive/libarchive.3 + awk -f ../mdoc2man.awk < ../../libarchive/libarchive.3 > libarchive.3 + +libarchive_internals.3: ../mdoc2man.awk ../../libarchive/libarchive_internals.3 + awk -f ../mdoc2man.awk < ../../libarchive/libarchive_internals.3 > libarchive_internals.3 + +mtree.5: ../mdoc2man.awk ../../libarchive/mtree.5 + awk -f ../mdoc2man.awk < ../../libarchive/mtree.5 > mtree.5 + +tar.5: ../mdoc2man.awk ../../libarchive/tar.5 + awk -f ../mdoc2man.awk < ../../libarchive/tar.5 > tar.5 + +bsdtar.1: ../mdoc2man.awk ../../tar/bsdtar.1 + awk -f ../mdoc2man.awk < ../../tar/bsdtar.1 > bsdtar.1 + +bsdcpio.1: ../mdoc2man.awk ../../cpio/bsdcpio.1 + awk -f ../mdoc2man.awk < ../../cpio/bsdcpio.1 > bsdcpio.1 +all: archive_entry.3 archive_read.3 archive_read_disk.3 archive_util.3 archive_write.3 archive_write_disk.3 cpio.5 libarchive-formats.5 libarchive.3 libarchive_internals.3 mtree.5 tar.5 bsdtar.1 bsdcpio.1 diff --git a/libarchive/libarchive-2.8.0/doc/man/archive_entry.3 b/libarchive/libarchive-2.8.0/doc/man/archive_entry.3 new file mode 100644 index 0000000..d459f00 --- /dev/null +++ b/libarchive/libarchive-2.8.0/doc/man/archive_entry.3 @@ -0,0 +1,519 @@ +.TH archive_entry 3 "May 12, 2008" "" +.SH NAME +.ad l +\fB\%archive_entry_acl_add_entry\fP, +\fB\%archive_entry_acl_add_entry_w\fP, +\fB\%archive_entry_acl_clear\fP, +\fB\%archive_entry_acl_count\fP, +\fB\%archive_entry_acl_next\fP, +\fB\%archive_entry_acl_next_w\fP, +\fB\%archive_entry_acl_reset\fP, +\fB\%archive_entry_acl_text_w\fP, +\fB\%archive_entry_atime\fP, +\fB\%archive_entry_atime_nsec\fP, +\fB\%archive_entry_clear\fP, +\fB\%archive_entry_clone\fP, +\fB\%archive_entry_copy_fflags_text\fP, +\fB\%archive_entry_copy_fflags_text_w\fP, +\fB\%archive_entry_copy_gname\fP, +\fB\%archive_entry_copy_gname_w\fP, +\fB\%archive_entry_copy_hardlink\fP, +\fB\%archive_entry_copy_hardlink_w\fP, +\fB\%archive_entry_copy_link\fP, +\fB\%archive_entry_copy_link_w\fP, +\fB\%archive_entry_copy_pathname_w\fP, +\fB\%archive_entry_copy_sourcepath\fP, +\fB\%archive_entry_copy_stat\fP, +\fB\%archive_entry_copy_symlink\fP, +\fB\%archive_entry_copy_symlink_w\fP, +\fB\%archive_entry_copy_uname\fP, +\fB\%archive_entry_copy_uname_w\fP, +\fB\%archive_entry_dev\fP, +\fB\%archive_entry_devmajor\fP, +\fB\%archive_entry_devminor\fP, +\fB\%archive_entry_filetype\fP, +\fB\%archive_entry_fflags\fP, +\fB\%archive_entry_fflags_text\fP, +\fB\%archive_entry_free\fP, +\fB\%archive_entry_gid\fP, +\fB\%archive_entry_gname\fP, +\fB\%archive_entry_hardlink\fP, +\fB\%archive_entry_ino\fP, +\fB\%archive_entry_mode\fP, +\fB\%archive_entry_mtime\fP, +\fB\%archive_entry_mtime_nsec\fP, +\fB\%archive_entry_nlink\fP, +\fB\%archive_entry_new\fP, +\fB\%archive_entry_pathname\fP, +\fB\%archive_entry_pathname_w\fP, +\fB\%archive_entry_rdev\fP, +\fB\%archive_entry_rdevmajor\fP, +\fB\%archive_entry_rdevminor\fP, +\fB\%archive_entry_set_atime\fP, +\fB\%archive_entry_set_ctime\fP, +\fB\%archive_entry_set_dev\fP, +\fB\%archive_entry_set_devmajor\fP, +\fB\%archive_entry_set_devminor\fP, +\fB\%archive_entry_set_filetype\fP, +\fB\%archive_entry_set_fflags\fP, +\fB\%archive_entry_set_gid\fP, +\fB\%archive_entry_set_gname\fP, +\fB\%archive_entry_set_hardlink\fP, +\fB\%archive_entry_set_link\fP, +\fB\%archive_entry_set_mode\fP, +\fB\%archive_entry_set_mtime\fP, +\fB\%archive_entry_set_pathname\fP, +\fB\%archive_entry_set_rdevmajor\fP, +\fB\%archive_entry_set_rdevminor\fP, +\fB\%archive_entry_set_size\fP, +\fB\%archive_entry_set_symlink\fP, +\fB\%archive_entry_set_uid\fP, +\fB\%archive_entry_set_uname\fP, +\fB\%archive_entry_size\fP, +\fB\%archive_entry_sourcepath\fP, +\fB\%archive_entry_stat\fP, +\fB\%archive_entry_symlink\fP, +\fB\%archive_entry_uid\fP, +\fB\%archive_entry_uname\fP +\- functions for manipulating archive entry descriptions +.SH SYNOPSIS +.ad l +\fB#include <archive_entry.h>\fP +.br +\fIvoid\fP +.br +\fB\%archive_entry_acl_add_entry\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%int\ type\fP, \fI\%int\ permset\fP, \fI\%int\ tag\fP, \fI\%int\ qual\fP, \fI\%const\ char\ *name\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_acl_add_entry_w\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%int\ type\fP, \fI\%int\ permset\fP, \fI\%int\ tag\fP, \fI\%int\ qual\fP, \fI\%const\ wchar_t\ *name\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_acl_clear\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_entry_acl_count\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%int\ type\fP); +.br +\fIint\fP +.br +\fB\%archive_entry_acl_next\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%int\ want_type\fP, \fI\%int\ *type\fP, \fI\%int\ *permset\fP, \fI\%int\ *tag\fP, \fI\%int\ *qual\fP, \fI\%const\ char\ **name\fP); +.br +\fIint\fP +.br +\fB\%archive_entry_acl_next_w\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%int\ want_type\fP, \fI\%int\ *type\fP, \fI\%int\ *permset\fP, \fI\%int\ *tag\fP, \fI\%int\ *qual\fP, \fI\%const\ wchar_t\ **name\fP); +.br +\fIint\fP +.br +\fB\%archive_entry_acl_reset\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%int\ want_type\fP); +.br +\fIconst wchar_t *\fP +.br +\fB\%archive_entry_acl_text_w\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%int\ flags\fP); +.br +\fItime_t\fP +.br +\fB\%archive_entry_atime\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fIlong\fP +.br +\fB\%archive_entry_atime_nsec\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fIstruct archive_entry *\fP +.br +\fB\%archive_entry_clear\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fIstruct archive_entry *\fP +.br +\fB\%archive_entry_clone\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fIconst char * *\fP +.br +\fB\%archive_entry_copy_fflags_text_w\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ char\ *\fP); +.br +\fIconst wchar_t *\fP +.br +\fB\%archive_entry_copy_fflags_text_w\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ wchar_t\ *\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_copy_gname\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ char\ *\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_copy_gname_w\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ wchar_t\ *\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_copy_hardlink\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ char\ *\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_copy_hardlink_w\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ wchar_t\ *\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_copy_sourcepath\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ char\ *\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_copy_pathname_w\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ wchar_t\ *\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_copy_stat\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ struct\ stat\ *\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_copy_symlink\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ char\ *\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_copy_symlink_w\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ wchar_t\ *\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_copy_uname\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ char\ *\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_copy_uname_w\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ wchar_t\ *\fP); +.br +\fIdev_t\fP +.br +\fB\%archive_entry_dev\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fIdev_t\fP +.br +\fB\%archive_entry_devmajor\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fIdev_t\fP +.br +\fB\%archive_entry_devminor\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fImode_t\fP +.br +\fB\%archive_entry_filetype\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_fflags\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%unsigned\ long\ *set\fP, \fI\%unsigned\ long\ *clear\fP); +.br +\fIconst char *\fP +.br +\fB\%archive_entry_fflags_text\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_free\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fIconst char *\fP +.br +\fB\%archive_entry_gname\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fIconst char *\fP +.br +\fB\%archive_entry_hardlink\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fIino_t\fP +.br +\fB\%archive_entry_ino\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fImode_t\fP +.br +\fB\%archive_entry_mode\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fItime_t\fP +.br +\fB\%archive_entry_mtime\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fIlong\fP +.br +\fB\%archive_entry_mtime_nsec\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fIunsigned int\fP +.br +\fB\%archive_entry_nlink\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fIstruct archive_entry *\fP +.br +\fB\%archive_entry_new\fP(\fI\%void\fP); +.br +\fIconst char *\fP +.br +\fB\%archive_entry_pathname\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fIconst wchar_t *\fP +.br +\fB\%archive_entry_pathname_w\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fIdev_t\fP +.br +\fB\%archive_entry_rdev\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fIdev_t\fP +.br +\fB\%archive_entry_rdevmajor\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fIdev_t\fP +.br +\fB\%archive_entry_rdevminor\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_set_dev\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%dev_t\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_set_devmajor\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%dev_t\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_set_devminor\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%dev_t\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_set_filetype\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%unsigned\ int\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_set_fflags\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%unsigned\ long\ set\fP, \fI\%unsigned\ long\ clear\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_set_gid\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%gid_t\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_set_gname\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ char\ *\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_set_hardlink\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ char\ *\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_set_ino\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%unsigned\ long\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_set_link\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ char\ *\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_set_mode\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%mode_t\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_set_mtime\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%time_t\fP, \fI\%long\ nanos\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_set_nlink\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%unsigned\ int\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_set_pathname\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ char\ *\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_set_rdev\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%dev_t\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_set_rdevmajor\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%dev_t\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_set_rdevminor\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%dev_t\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_set_size\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%int64_t\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_set_symlink\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ char\ *\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_set_uid\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%uid_t\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_set_uname\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ char\ *\fP); +.br +\fIint64_t\fP +.br +\fB\%archive_entry_size\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fIconst char *\fP +.br +\fB\%archive_entry_sourcepath\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fIconst struct stat *\fP +.br +\fB\%archive_entry_stat\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fIconst char *\fP +.br +\fB\%archive_entry_symlink\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fIconst char *\fP +.br +\fB\%archive_entry_uname\fP(\fI\%struct\ archive_entry\ *\fP); +.SH DESCRIPTION +.ad l +These functions create and manipulate data objects that +represent entries within an archive. +You can think of a +Tn struct archive_entry +as a heavy-duty version of +Tn struct stat: +it includes everything from +Tn struct stat +plus associated pathname, textual group and user names, etc. +These objects are used by +\fBlibarchive\fP(3) +to represent the metadata associated with a particular +entry in an archive. +.SS Create and Destroy +There are functions to allocate, destroy, clear, and copy +\fIarchive_entry\fP +objects: +.RS 5 +.TP +\fB\%archive_entry_clear\fP() +Erases the object, resetting all internal fields to the +same state as a newly-created object. +This is provided to allow you to quickly recycle objects +without thrashing the heap. +.TP +\fB\%archive_entry_clone\fP() +A deep copy operation; all text fields are duplicated. +.TP +\fB\%archive_entry_free\fP() +Releases the +Tn struct archive_entry +object. +.TP +\fB\%archive_entry_new\fP() +Allocate and return a blank +Tn struct archive_entry +object. +.RE +.SS Set and Get Functions +Most of the functions here set or read entries in an object. +Such functions have one of the following forms: +.RS 5 +.TP +\fB\%archive_entry_set_XXXX\fP() +Stores the provided data in the object. +In particular, for strings, the pointer is stored, +not the referenced string. +.TP +\fB\%archive_entry_copy_XXXX\fP() +As above, except that the referenced data is copied +into the object. +.TP +\fB\%archive_entry_XXXX\fP() +Returns the specified data. +In the case of strings, a const-qualified pointer to +the string is returned. +.RE +String data can be set or accessed as wide character strings +or normal +\fIchar\fP +strings. +The functions that use wide character strings are suffixed with +\fB_w\fP. +Note that these are different representations of the same data: +For example, if you store a narrow string and read the corresponding +wide string, the object will transparently convert formats +using the current locale. +Similarly, if you store a wide string and then store a +narrow string for the same data, the previously-set wide string will +be discarded in favor of the new data. +.PP +There are a few set/get functions that merit additional description: +.RS 5 +.TP +\fB\%archive_entry_set_link\fP() +This function sets the symlink field if it is already set. +Otherwise, it sets the hardlink field. +.RE +.SS File Flags +File flags are transparently converted between a bitmap +representation and a textual format. +For example, if you set the bitmap and ask for text, the library +will build a canonical text format. +However, if you set a text format and request a text format, +you will get back the same text, even if it is ill-formed. +If you need to canonicalize a textual flags string, you should first set the +text form, then request the bitmap form, then use that to set the bitmap form. +Setting the bitmap format will clear the internal text representation +and force it to be reconstructed when you next request the text form. +.PP +The bitmap format consists of two integers, one containing bits +that should be set, the other specifying bits that should be +cleared. +Bits not mentioned in either bitmap will be ignored. +Usually, the bitmap of bits to be cleared will be set to zero. +In unusual circumstances, you can force a fully-specified set +of file flags by setting the bitmap of flags to clear to the complement +of the bitmap of flags to set. +(This differs from +\fBfflagstostr\fP(3), +which only includes names for set bits.) +Converting a bitmap to a textual string is a platform-specific +operation; bits that are not meaningful on the current platform +will be ignored. +.PP +The canonical text format is a comma-separated list of flag names. +The +\fB\%archive_entry_copy_fflags_text\fP() +and +\fB\%archive_entry_copy_fflags_text_w\fP() +functions parse the provided text and sets the internal bitmap values. +This is a platform-specific operation; names that are not meaningful +on the current platform will be ignored. +The function returns a pointer to the start of the first name that was not +recognized, or NULL if every name was recognized. +Note that every name--including names that follow an unrecognized name--will +be evaluated, and the bitmaps will be set to reflect every name that is +recognized. +(In particular, this differs from +\fBstrtofflags\fP(3), +which stops parsing at the first unrecognized name.) +.SS ACL Handling +XXX This needs serious help. +XXX +.PP +An +``Access Control List'' +(ACL) is a list of permissions that grant access to particular users or +groups beyond what would normally be provided by standard POSIX mode bits. +The ACL handling here addresses some deficiencies in the POSIX.1e draft 17 ACL +specification. +In particular, POSIX.1e draft 17 specifies several different formats, but +none of those formats include both textual user/group names and numeric +UIDs/GIDs. +.PP +XXX explain ACL stuff XXX +.SH SEE ALSO +.ad l +\fBarchive\fP(3) +.SH HISTORY +.ad l +The +\fB\%libarchive\fP +library first appeared in +FreeBSD 5.3. +.SH AUTHORS +.ad l +-nosplit +The +\fB\%libarchive\fP +library was written by +Tim Kientzle \%<kientzle@acm.org.> diff --git a/libarchive/libarchive-2.8.0/doc/man/archive_read.3 b/libarchive/libarchive-2.8.0/doc/man/archive_read.3 new file mode 100644 index 0000000..b1bd4f3 --- /dev/null +++ b/libarchive/libarchive-2.8.0/doc/man/archive_read.3 @@ -0,0 +1,733 @@ +.TH archive_read 3 "April 13, 2009" "" +.SH NAME +.ad l +\fB\%archive_read_new\fP, +\fB\%archive_read_set_filter_options\fP, +\fB\%archive_read_set_format_options\fP, +\fB\%archive_read_set_options\fP, +\fB\%archive_read_support_compression_all\fP, +\fB\%archive_read_support_compression_bzip2\fP, +\fB\%archive_read_support_compression_compress\fP, +\fB\%archive_read_support_compression_gzip\fP, +\fB\%archive_read_support_compression_lzma\fP, +\fB\%archive_read_support_compression_none\fP, +\fB\%archive_read_support_compression_xz\fP, +\fB\%archive_read_support_compression_program\fP, +\fB\%archive_read_support_compression_program_signature\fP, +\fB\%archive_read_support_format_all\fP, +\fB\%archive_read_support_format_ar\fP, +\fB\%archive_read_support_format_cpio\fP, +\fB\%archive_read_support_format_empty\fP, +\fB\%archive_read_support_format_iso9660\fP, +\fB\%archive_read_support_format_mtree,\fP +\fB\%archive_read_support_format_raw,\fP +\fB\%archive_read_support_format_tar\fP, +\fB\%archive_read_support_format_zip\fP, +\fB\%archive_read_open\fP, +\fB\%archive_read_open2\fP, +\fB\%archive_read_open_fd\fP, +\fB\%archive_read_open_FILE\fP, +\fB\%archive_read_open_filename\fP, +\fB\%archive_read_open_memory\fP, +\fB\%archive_read_next_header\fP, +\fB\%archive_read_next_header2\fP, +\fB\%archive_read_data\fP, +\fB\%archive_read_data_block\fP, +\fB\%archive_read_data_skip\fP, +\fB\%archive_read_data_into_buffer\fP, +\fB\%archive_read_data_into_fd\fP, +\fB\%archive_read_extract\fP, +\fB\%archive_read_extract2\fP, +\fB\%archive_read_extract_set_progress_callback\fP, +\fB\%archive_read_close\fP, +\fB\%archive_read_finish\fP +\- functions for reading streaming archives +.SH SYNOPSIS +.ad l +\fB#include <archive.h>\fP +.br +\fIstruct archive *\fP +.br +\fB\%archive_read_new\fP(\fI\%void\fP); +.br +\fIint\fP +.br +\fB\%archive_read_support_compression_all\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_read_support_compression_bzip2\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_read_support_compression_compress\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_read_support_compression_gzip\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_read_support_compression_lzma\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_read_support_compression_none\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_read_support_compression_xz\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_read_support_compression_program\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ char\ *cmd\fP); +.br +\fIint\fP +.br +\fB\%archive_read_support_compression_program_signature\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ char\ *cmd\fP, \fI\%const\ void\ *signature\fP, \fI\%size_t\ signature_length\fP); +.br +\fIint\fP +.br +\fB\%archive_read_support_format_all\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_read_support_format_ar\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_read_support_format_cpio\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_read_support_format_empty\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_read_support_format_iso9660\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_read_support_format_mtree\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_read_support_format_raw\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_read_support_format_tar\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_read_support_format_zip\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_read_set_filter_options\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ char\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_read_set_format_options\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ char\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_read_set_options\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ char\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_read_open\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *client_data\fP, \fI\%archive_open_callback\ *\fP, \fI\%archive_read_callback\ *\fP, \fI\%archive_close_callback\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_read_open2\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *client_data\fP, \fI\%archive_open_callback\ *\fP, \fI\%archive_read_callback\ *\fP, \fI\%archive_skip_callback\ *\fP, \fI\%archive_close_callback\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_read_open_FILE\fP(\fI\%struct\ archive\ *\fP, \fI\%FILE\ *file\fP); +.br +\fIint\fP +.br +\fB\%archive_read_open_fd\fP(\fI\%struct\ archive\ *\fP, \fI\%int\ fd\fP, \fI\%size_t\ block_size\fP); +.br +\fIint\fP +.br +\fB\%archive_read_open_filename\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ char\ *filename\fP, \fI\%size_t\ block_size\fP); +.br +\fIint\fP +.br +\fB\%archive_read_open_memory\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *buff\fP, \fI\%size_t\ size\fP); +.br +\fIint\fP +.br +\fB\%archive_read_next_header\fP(\fI\%struct\ archive\ *\fP, \fI\%struct\ archive_entry\ **\fP); +.br +\fIint\fP +.br +\fB\%archive_read_next_header2\fP(\fI\%struct\ archive\ *\fP, \fI\%struct\ archive_entry\ *\fP); +.br +\fIssize_t\fP +.br +\fB\%archive_read_data\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *buff\fP, \fI\%size_t\ len\fP); +.br +\fIint\fP +.br +\fB\%archive_read_data_block\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ void\ **buff\fP, \fI\%size_t\ *len\fP, \fI\%off_t\ *offset\fP); +.br +\fIint\fP +.br +\fB\%archive_read_data_skip\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_read_data_into_buffer\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *\fP, \fI\%ssize_t\ len\fP); +.br +\fIint\fP +.br +\fB\%archive_read_data_into_fd\fP(\fI\%struct\ archive\ *\fP, \fI\%int\ fd\fP); +.br +\fIint\fP +.br +\fB\%archive_read_extract\fP(\fI\%struct\ archive\ *\fP, \fI\%struct\ archive_entry\ *\fP, \fI\%int\ flags\fP); +.br +\fIint\fP +.br +\fB\%archive_read_extract2\fP(\fI\%struct\ archive\ *src\fP, \fI\%struct\ archive_entry\ *\fP, \fI\%struct\ archive\ *dest\fP); +.br +\fIvoid\fP +.br +\fB\%archive_read_extract_set_progress_callback\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ (*func)(void\ *)\fP, \fI\%void\ *user_data\fP); +.br +\fIint\fP +.br +\fB\%archive_read_close\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_read_finish\fP(\fI\%struct\ archive\ *\fP); +.SH DESCRIPTION +.ad l +These functions provide a complete API for reading streaming archives. +The general process is to first create the +Tn struct archive +object, set options, initialize the reader, iterate over the archive +headers and associated data, then close the archive and release all +resources. +The following summary describes the functions in approximately the +order they would be used: +.RS 5 +.TP +\fB\%archive_read_new\fP() +Allocates and initializes a +Tn struct archive +object suitable for reading from an archive. +.TP +\fB\%archive_read_support_compression_bzip2\fP(), +\fB\%archive_read_support_compression_compress\fP(), +\fB\%archive_read_support_compression_gzip\fP(), +\fB\%archive_read_support_compression_lzma\fP(), +\fB\%archive_read_support_compression_none\fP(), +\fB\%archive_read_support_compression_xz\fP() +Enables auto-detection code and decompression support for the +specified compression. +Returns +\fBARCHIVE_OK\fP +if the compression is fully supported, or +\fBARCHIVE_WARN\fP +if the compression is supported only through an external program. +Note that decompression using an external program is usually slower than +decompression through built-in libraries. +Note that +``none'' +is always enabled by default. +.TP +\fB\%archive_read_support_compression_all\fP() +Enables all available decompression filters. +.TP +\fB\%archive_read_support_compression_program\fP() +Data is fed through the specified external program before being dearchived. +Note that this disables automatic detection of the compression format, +so it makes no sense to specify this in conjunction with any other +decompression option. +.TP +\fB\%archive_read_support_compression_program_signature\fP() +This feeds data through the specified external program +but only if the initial bytes of the data match the specified +signature value. +.TP +\fB\%archive_read_support_format_all\fP(), +\fB\%archive_read_support_format_ar\fP(), +\fB\%archive_read_support_format_cpio\fP(), +\fB\%archive_read_support_format_empty\fP(), +\fB\%archive_read_support_format_iso9660\fP(), +\fB\%archive_read_support_format_mtree\fP(), +\fB\%archive_read_support_format_tar\fP(), +\fB\%archive_read_support_format_zip\fP() +Enables support---including auto-detection code---for the +specified archive format. +For example, +\fB\%archive_read_support_format_tar\fP() +enables support for a variety of standard tar formats, old-style tar, +ustar, pax interchange format, and many common variants. +For convenience, +\fB\%archive_read_support_format_all\fP() +enables support for all available formats. +Only empty archives are supported by default. +.TP +\fB\%archive_read_support_format_raw\fP() +The +``raw'' +format handler allows libarchive to be used to read arbitrary data. +It treats any data stream as an archive with a single entry. +The pathname of this entry is +``data ;'' +all other entry fields are unset. +This is not enabled by +\fB\%archive_read_support_format_all\fP() +in order to avoid erroneous handling of damaged archives. +.TP +\fB\%archive_read_set_filter_options\fP(), +\fB\%archive_read_set_format_options\fP(), +\fB\%archive_read_set_options\fP() +Specifies options that will be passed to currently-registered +filters (including decompression filters) and/or format readers. +The argument is a comma-separated list of individual options. +Individual options have one of the following forms: +.RS 5 +.TP +\fIoption=value\fP +The option/value pair will be provided to every module. +Modules that do not accept an option with this name will ignore it. +.TP +\fIoption\fP +The option will be provided to every module with a value of +``1''. +.TP +\fI!option\fP +The option will be provided to every module with a NULL value. +.TP +\fImodule:option=value\fP, \fImodule:option\fP, \fImodule:!option\fP +As above, but the corresponding option and value will be provided +only to modules whose name matches +\fImodule\fP. +.RE +The return value will be +\fBARCHIVE_OK\fP +if any module accepts the option, or +\fBARCHIVE_WARN\fP +if no module accepted the option, or +\fBARCHIVE_FATAL\fP +if there was a fatal error while attempting to process the option. +.PP +The currently supported options are: +.RS 5 +.TP +Format iso9660 +.RS 5 +.TP +\fBjoliet\fP +Support Joliet extensions. +Defaults to enabled, use +\fB!joliet\fP +to disable. +.RE +.RE +.TP +\fB\%archive_read_open\fP() +The same as +\fB\%archive_read_open2\fP(), +except that the skip callback is assumed to be +.BR NULL. +.TP +\fB\%archive_read_open2\fP() +Freeze the settings, open the archive, and prepare for reading entries. +This is the most generic version of this call, which accepts +four callback functions. +Most clients will want to use +\fB\%archive_read_open_filename\fP(), +\fB\%archive_read_open_FILE\fP(), +\fB\%archive_read_open_fd\fP(), +or +\fB\%archive_read_open_memory\fP() +instead. +The library invokes the client-provided functions to obtain +raw bytes from the archive. +.TP +\fB\%archive_read_open_FILE\fP() +Like +\fB\%archive_read_open\fP(), +except that it accepts a +\fIFILE *\fP +pointer. +This function should not be used with tape drives or other devices +that require strict I/O blocking. +.TP +\fB\%archive_read_open_fd\fP() +Like +\fB\%archive_read_open\fP(), +except that it accepts a file descriptor and block size rather than +a set of function pointers. +Note that the file descriptor will not be automatically closed at +end-of-archive. +This function is safe for use with tape drives or other blocked devices. +.TP +\fB\%archive_read_open_file\fP() +This is a deprecated synonym for +\fB\%archive_read_open_filename\fP(). +.TP +\fB\%archive_read_open_filename\fP() +Like +\fB\%archive_read_open\fP(), +except that it accepts a simple filename and a block size. +A NULL filename represents standard input. +This function is safe for use with tape drives or other blocked devices. +.TP +\fB\%archive_read_open_memory\fP() +Like +\fB\%archive_read_open\fP(), +except that it accepts a pointer and size of a block of +memory containing the archive data. +.TP +\fB\%archive_read_next_header\fP() +Read the header for the next entry and return a pointer to +a +Tn struct archive_entry. +This is a convenience wrapper around +\fB\%archive_read_next_header2\fP() +that reuses an internal +Tn struct archive_entry +object for each request. +.TP +\fB\%archive_read_next_header2\fP() +Read the header for the next entry and populate the provided +Tn struct archive_entry. +.TP +\fB\%archive_read_data\fP() +Read data associated with the header just read. +Internally, this is a convenience function that calls +\fB\%archive_read_data_block\fP() +and fills any gaps with nulls so that callers see a single +continuous stream of data. +.TP +\fB\%archive_read_data_block\fP() +Return the next available block of data for this entry. +Unlike +\fB\%archive_read_data\fP(), +the +\fB\%archive_read_data_block\fP() +function avoids copying data and allows you to correctly handle +sparse files, as supported by some archive formats. +The library guarantees that offsets will increase and that blocks +will not overlap. +Note that the blocks returned from this function can be much larger +than the block size read from disk, due to compression +and internal buffer optimizations. +.TP +\fB\%archive_read_data_skip\fP() +A convenience function that repeatedly calls +\fB\%archive_read_data_block\fP() +to skip all of the data for this archive entry. +.TP +\fB\%archive_read_data_into_buffer\fP() +This function is deprecated and will be removed. +Use +\fB\%archive_read_data\fP() +instead. +.TP +\fB\%archive_read_data_into_fd\fP() +A convenience function that repeatedly calls +\fB\%archive_read_data_block\fP() +to copy the entire entry to the provided file descriptor. +.TP +\fB\%archive_read_extract\fP(), \fB\%archive_read_extract_set_skip_file\fP() +A convenience function that wraps the corresponding +\fBarchive_write_disk\fP(3) +interfaces. +The first call to +\fB\%archive_read_extract\fP() +creates a restore object using +\fBarchive_write_disk_new\fP(3) +and +\fBarchive_write_disk_set_standard_lookup\fP(3), +then transparently invokes +\fBarchive_write_disk_set_options\fP(3), +\fBarchive_write_header\fP(3), +\fBarchive_write_data\fP(3), +and +\fBarchive_write_finish_entry\fP(3) +to create the entry on disk and copy data into it. +The +\fIflags\fP +argument is passed unmodified to +\fBarchive_write_disk_set_options\fP(3). +.TP +\fB\%archive_read_extract2\fP() +This is another version of +\fB\%archive_read_extract\fP() +that allows you to provide your own restore object. +In particular, this allows you to override the standard lookup functions +using +\fBarchive_write_disk_set_group_lookup\fP(3), +and +\fBarchive_write_disk_set_user_lookup\fP(3). +Note that +\fB\%archive_read_extract2\fP() +does not accept a +\fIflags\fP +argument; you should use +\fB\%archive_write_disk_set_options\fP() +to set the restore options yourself. +.TP +\fB\%archive_read_extract_set_progress_callback\fP() +Sets a pointer to a user-defined callback that can be used +for updating progress displays during extraction. +The progress function will be invoked during the extraction of large +regular files. +The progress function will be invoked with the pointer provided to this call. +Generally, the data pointed to should include a reference to the archive +object and the archive_entry object so that various statistics +can be retrieved for the progress display. +.TP +\fB\%archive_read_close\fP() +Complete the archive and invoke the close callback. +.TP +\fB\%archive_read_finish\fP() +Invokes +\fB\%archive_read_close\fP() +if it was not invoked manually, then release all resources. +Note: In libarchive 1.x, this function was declared to return +\fIvoid ,\fP +which made it impossible to detect certain errors when +\fB\%archive_read_close\fP() +was invoked implicitly from this function. +The declaration is corrected beginning with libarchive 2.0. +.RE +.PP +Note that the library determines most of the relevant information about +the archive by inspection. +In particular, it automatically detects +\fBgzip\fP(1) +or +\fBbzip2\fP(1) +compression and transparently performs the appropriate decompression. +It also automatically detects the archive format. +.PP +A complete description of the +Tn struct archive +and +Tn struct archive_entry +objects can be found in the overview manual page for +\fBlibarchive\fP(3). +.SH CLIENT CALLBACKS +.ad l +The callback functions must match the following prototypes: +.RS 5 +.IP +\fItypedef ssize_t\fP +\fB\%archive_read_callback\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *client_data\fP, \fI\%const\ void\ **buffer\fP) +.IP +\fItypedef int\fP +\fB\%archive_skip_callback\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *client_data\fP, \fI\%size_t\ request\fP) +.IP +\fItypedef int\fP +\fB\%archive_open_callback\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *client_data\fP) +.IP +\fItypedef int\fP +\fB\%archive_close_callback\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *client_data\fP) +.RE +.PP +The open callback is invoked by +\fB\%archive_open\fP(). +It should return +\fBARCHIVE_OK\fP +if the underlying file or data source is successfully +opened. +If the open fails, it should call +\fB\%archive_set_error\fP() +to register an error code and message and return +\fBARCHIVE_FATAL\fP. +.PP +The read callback is invoked whenever the library +requires raw bytes from the archive. +The read callback should read data into a buffer, +set the +.RS 4 +const void **buffer +.RE +argument to point to the available data, and +return a count of the number of bytes available. +The library will invoke the read callback again +only after it has consumed this data. +The library imposes no constraints on the size +of the data blocks returned. +On end-of-file, the read callback should +return zero. +On error, the read callback should invoke +\fB\%archive_set_error\fP() +to register an error code and message and +return -1. +.PP +The skip callback is invoked when the +library wants to ignore a block of data. +The return value is the number of bytes actually +skipped, which may differ from the request. +If the callback cannot skip data, it should return +zero. +If the skip callback is not provided (the +function pointer is +.BR NULL ), +the library will invoke the read function +instead and simply discard the result. +A skip callback can provide significant +performance gains when reading uncompressed +archives from slow disk drives or other media +that can skip quickly. +.PP +The close callback is invoked by archive_close when +the archive processing is complete. +The callback should return +\fBARCHIVE_OK\fP +on success. +On failure, the callback should invoke +\fB\%archive_set_error\fP() +to register an error code and message and +return +\fBARCHIVE_FATAL.\fP +.SH EXAMPLE +.ad l +The following illustrates basic usage of the library. +In this example, +the callback functions are simply wrappers around the standard +\fBopen\fP(2), +\fBread\fP(2), +and +\fBclose\fP(2) +system calls. +.RS 4 +.nf +void +list_archive(const char *name) +{ + struct mydata *mydata; + struct archive *a; + struct archive_entry *entry; + mydata = malloc(sizeof(struct mydata)); + a = archive_read_new(); + mydata->name = name; + archive_read_support_compression_all(a); + archive_read_support_format_all(a); + archive_read_open(a, mydata, myopen, myread, myclose); + while (archive_read_next_header(a, &entry) == ARCHIVE_OK) { + printf("%s\\n",archive_entry_pathname(entry)); + archive_read_data_skip(a); + } + archive_read_finish(a); + free(mydata); +} +ssize_t +myread(struct archive *a, void *client_data, const void **buff) +{ + struct mydata *mydata = client_data; + *buff = mydata->buff; + return (read(mydata->fd, mydata->buff, 10240)); +} +int +myopen(struct archive *a, void *client_data) +{ + struct mydata *mydata = client_data; + mydata->fd = open(mydata->name, O_RDONLY); + return (mydata->fd >= 0 ? ARCHIVE_OK : ARCHIVE_FATAL); +} +int +myclose(struct archive *a, void *client_data) +{ + struct mydata *mydata = client_data; + if (mydata->fd > 0) + close(mydata->fd); + return (ARCHIVE_OK); +} +.RE +.SH RETURN VALUES +.ad l +Most functions return zero on success, non-zero on error. +The possible return codes include: +\fBARCHIVE_OK\fP +(the operation succeeded), +\fBARCHIVE_WARN\fP +(the operation succeeded but a non-critical error was encountered), +\fBARCHIVE_EOF\fP +(end-of-archive was encountered), +\fBARCHIVE_RETRY\fP +(the operation failed but can be retried), +and +\fBARCHIVE_FATAL\fP +(there was a fatal error; the archive should be closed immediately). +Detailed error codes and textual descriptions are available from the +\fB\%archive_errno\fP() +and +\fB\%archive_error_string\fP() +functions. +.PP +\fB\%archive_read_new\fP() +returns a pointer to a freshly allocated +Tn struct archive +object. +It returns +.BR NULL +on error. +.PP +\fB\%archive_read_data\fP() +returns a count of bytes actually read or zero at the end of the entry. +On error, a value of +\fBARCHIVE_FATAL\fP, +\fBARCHIVE_WARN\fP, +or +\fBARCHIVE_RETRY\fP +is returned and an error code and textual description can be retrieved from the +\fB\%archive_errno\fP() +and +\fB\%archive_error_string\fP() +functions. +.PP +The library expects the client callbacks to behave similarly. +If there is an error, you can use +\fB\%archive_set_error\fP() +to set an appropriate error code and description, +then return one of the non-zero values above. +(Note that the value eventually returned to the client may +not be the same; many errors that are not critical at the level +of basic I/O can prevent the archive from being properly read, +thus most I/O errors eventually cause +\fBARCHIVE_FATAL\fP +to be returned.) +.SH SEE ALSO +.ad l +\fBtar\fP(1), +\fBarchive\fP(3), +\fBarchive_util\fP(3), +\fBtar\fP(5) +.SH HISTORY +.ad l +The +\fB\%libarchive\fP +library first appeared in +FreeBSD 5.3. +.SH AUTHORS +.ad l +-nosplit +The +\fB\%libarchive\fP +library was written by +Tim Kientzle \%<kientzle@acm.org.> +.SH BUGS +.ad l +Many traditional archiver programs treat +empty files as valid empty archives. +For example, many implementations of +\fBtar\fP(1) +allow you to append entries to an empty file. +Of course, it is impossible to determine the format of an empty file +by inspecting the contents, so this library treats empty files as +having a special +``empty'' +format. diff --git a/libarchive/libarchive-2.8.0/doc/man/archive_read_disk.3 b/libarchive/libarchive-2.8.0/doc/man/archive_read_disk.3 new file mode 100644 index 0000000..6e10f4f --- /dev/null +++ b/libarchive/libarchive-2.8.0/doc/man/archive_read_disk.3 @@ -0,0 +1,300 @@ +.TH archive_read_disk 3 "March 10, 2009" "" +.SH NAME +.ad l +\fB\%archive_read_disk_new\fP, +\fB\%archive_read_disk_set_symlink_logical\fP, +\fB\%archive_read_disk_set_symlink_physical\fP, +\fB\%archive_read_disk_set_symlink_hybrid\fP, +\fB\%archive_read_disk_entry_from_file\fP, +\fB\%archive_read_disk_gname\fP, +\fB\%archive_read_disk_uname\fP, +\fB\%archive_read_disk_set_uname_lookup\fP, +\fB\%archive_read_disk_set_gname_lookup\fP, +\fB\%archive_read_disk_set_standard_lookup\fP, +\fB\%archive_read_close\fP, +\fB\%archive_read_finish\fP +\- functions for reading objects from disk +.SH SYNOPSIS +.ad l +\fB#include <archive.h>\fP +.br +\fIstruct archive *\fP +.br +\fB\%archive_read_disk_new\fP(\fI\%void\fP); +.br +\fIint\fP +.br +\fB\%archive_read_disk_set_symlink_logical\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_read_disk_set_symlink_physical\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_read_disk_set_symlink_hybrid\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_read_disk_gname\fP(\fI\%struct\ archive\ *\fP, \fI\%gid_t\fP); +.br +\fIint\fP +.br +\fB\%archive_read_disk_uname\fP(\fI\%struct\ archive\ *\fP, \fI\%uid_t\fP); +.br +\fIint\fP +.br +\fB\%archive_read_disk_set_gname_lookup\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *\fP, \fI\%const\ char\ *(*lookup)(void\ *,\ gid_t)\fP, \fI\%void\ (*cleanup)(void\ *)\fP); +.br +\fIint\fP +.br +\fB\%archive_read_disk_set_uname_lookup\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *\fP, \fI\%const\ char\ *(*lookup)(void\ *,\ uid_t)\fP, \fI\%void\ (*cleanup)(void\ *)\fP); +.br +\fIint\fP +.br +\fB\%archive_read_disk_set_standard_lookup\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_read_disk_entry_from_file\fP(\fI\%struct\ archive\ *\fP, \fI\%struct\ archive_entry\ *\fP, \fI\%int\ fd\fP, \fI\%const\ struct\ stat\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_read_close\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_read_finish\fP(\fI\%struct\ archive\ *\fP); +.SH DESCRIPTION +.ad l +These functions provide an API for reading information about +objects on disk. +In particular, they provide an interface for populating +Tn struct archive_entry +objects. +.RS 5 +.TP +\fB\%archive_read_disk_new\fP() +Allocates and initializes a +Tn struct archive +object suitable for reading object information from disk. +.TP +\fB\%archive_read_disk_set_symlink_logical\fP(), +\fB\%archive_read_disk_set_symlink_physical\fP(), +\fB\%archive_read_disk_set_symlink_hybrid\fP() +This sets the mode used for handling symbolic links. +The +``logical'' +mode follows all symbolic links. +The +``physical'' +mode does not follow any symbolic links. +The +``hybrid'' +mode currently behaves identically to the +``logical'' +mode. +.TP +\fB\%archive_read_disk_gname\fP(), +\fB\%archive_read_disk_uname\fP() +Returns a user or group name given a gid or uid value. +By default, these always return a NULL string. +.TP +\fB\%archive_read_disk_set_gname_lookup\fP(), +\fB\%archive_read_disk_set_uname_lookup\fP() +These allow you to override the functions used for +user and group name lookups. +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 or when new lookup functions are registered. +.TP +\fB\%archive_read_disk_set_standard_lookup\fP() +This convenience function installs a standard set of user +and group name lookup functions. +These functions use +\fBgetpwid\fP(3) +and +\fBgetgrid\fP(3) +to convert ids to names, defaulting to NULL if the names cannot +be looked up. +These functions also implement a simple memory cache to reduce +the number of calls to +\fBgetpwid\fP(3) +and +\fBgetgrid\fP(3). +.TP +\fB\%archive_read_disk_entry_from_file\fP() +Populates a +Tn struct archive_entry +object with information about a particular file. +The +Tn archive_entry +object must have already been created with +\fBarchive_entry_new\fP(3) +and at least one of the source path or path fields must already be set. +(If both are set, the source path will be used.) +.PP +Information is read from disk using the path name from the +Tn struct archive_entry +object. +If a file descriptor is provided, some information will be obtained using +that file descriptor, on platforms that support the appropriate +system calls. +.PP +If a pointer to a +Tn struct stat +is provided, information from that structure will be used instead +of reading from the disk where appropriate. +This can provide performance benefits in scenarios where +Tn struct stat +information has already been read from the disk as a side effect +of some other operation. +(For example, directory traversal libraries often provide this information.) +.PP +Where necessary, user and group ids are converted to user and group names +using the currently registered lookup functions above. +This affects the file ownership fields and ACL values in the +Tn struct archive_entry +object. +.TP +\fB\%archive_read_close\fP() +This currently does nothing. +.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. +.SH EXAMPLE +.ad l +The following illustrates basic usage of the library by +showing how to use it to copy an item on disk into an archive. +.RS 4 +.nf +void +file_to_archive(struct archive *a, const char *name) +{ + char buff[8192]; + size_t bytes_read; + struct archive *ard; + struct archive_entry *entry; + int fd; + ard = archive_read_disk_new(); + archive_read_disk_set_standard_lookup(ard); + entry = archive_entry_new(); + fd = open(name, O_RDONLY); + if (fd < 0) + return; + archive_entry_copy_sourcepath(entry, name); + archive_read_disk_entry_from_file(ard, entry, fd, NULL); + archive_write_header(a, entry); + while ((bytes_read = read(fd, buff, sizeof(buff))) > 0) + archive_write_data(a, buff, bytes_read); + archive_write_finish_entry(a); + archive_read_finish(ard); + archive_entry_free(entry); +} +.RE +.SH RETURN VALUES +.ad l +Most functions return +\fBARCHIVE_OK\fP +(zero) on success, or one of several negative +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 +\fBarchive_errno\fP(3) +and +\fBarchive_error_string\fP(3) +functions can be used to retrieve an appropriate error code and a +textual error message. +(See +\fBarchive_util\fP(3) +for details.) +.PP +\fB\%archive_read_disk_new\fP() +returns a pointer to a newly-allocated +Tn struct archive +object or NULL if the allocation failed for any reason. +.PP +\fB\%archive_read_disk_gname\fP() +and +\fB\%archive_read_disk_uname\fP() +return +Tn const char * +pointers to the textual name or NULL if the lookup failed for any reason. +The returned pointer points to internal storage that +may be reused on the next call to either of these functions; +callers should copy the string if they need to continue accessing it. +.PP +.SH SEE ALSO +.ad l +\fBarchive_read\fP(3), +\fBarchive_write\fP(3), +\fBarchive_write_disk\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_read_disk\fP +interface was added to +\fB\%libarchive\fP 2.6 +and first appeared in +FreeBSD 8.0. +.SH AUTHORS +.ad l +-nosplit +The +\fB\%libarchive\fP +library was written by +Tim Kientzle \%<kientzle@freebsd.org.> +.SH BUGS +.ad l +The +``standard'' +user name and group name lookup functions are not the defaults because +\fBgetgrid\fP(3) +and +\fBgetpwid\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 +The full list of metadata read from disk by +\fB\%archive_read_disk_entry_from_file\fP() +is necessarily system-dependent. +.PP +The +\fB\%archive_read_disk_entry_from_file\fP() +function reads as much information as it can from disk. +Some method should be provided to limit this so that clients who +do not need ACLs, for instance, can avoid the extra work needed +to look up such information. +.PP +This API should provide a set of methods for walking a directory tree. +That would make it a direct parallel of the +\fBarchive_read\fP(3) +API. +When such methods are implemented, the +``hybrid'' +symbolic link mode will make sense. diff --git a/libarchive/libarchive-2.8.0/doc/man/archive_util.3 b/libarchive/libarchive-2.8.0/doc/man/archive_util.3 new file mode 100644 index 0000000..60375af --- /dev/null +++ b/libarchive/libarchive-2.8.0/doc/man/archive_util.3 @@ -0,0 +1,163 @@ +.TH archive_util 3 "January 8, 2005" "" +.SH NAME +.ad l +\fB\%archive_clear_error\fP, +\fB\%archive_compression\fP, +\fB\%archive_compression_name\fP, +\fB\%archive_copy_error\fP, +\fB\%archive_errno\fP, +\fB\%archive_error_string\fP, +\fB\%archive_file_count\fP, +\fB\%archive_format\fP, +\fB\%archive_format_name\fP, +\fB\%archive_set_error\fP +\- libarchive utility functions +.SH SYNOPSIS +.ad l +\fB#include <archive.h>\fP +.br +\fIvoid\fP +.br +\fB\%archive_clear_error\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_compression\fP(\fI\%struct\ archive\ *\fP); +.br +\fIconst char *\fP +.br +\fB\%archive_compression_name\fP(\fI\%struct\ archive\ *\fP); +.br +\fIvoid\fP +.br +\fB\%archive_copy_error\fP(\fI\%struct\ archive\ *\fP, \fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_errno\fP(\fI\%struct\ archive\ *\fP); +.br +\fIconst char *\fP +.br +\fB\%archive_error_string\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_file_count\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_format\fP(\fI\%struct\ archive\ *\fP); +.br +\fIconst char *\fP +.br +\fB\%archive_format_name\fP(\fI\%struct\ archive\ *\fP); +.br +\fIvoid\fP +.br +\fB\%archive_set_error\fP(\fI\%struct\ archive\ *\fP, \fI\%int\ error_code\fP, \fI\%const\ char\ *fmt\fP, \fI\%...\fP); +.SH DESCRIPTION +.ad l +These functions provide access to various information about the +Tn struct archive +object used in the +\fBlibarchive\fP(3) +library. +.RS 5 +.TP +\fB\%archive_clear_error\fP() +Clears any error information left over from a previous call. +Not generally used in client code. +.TP +\fB\%archive_compression\fP() +Returns a numeric code indicating the current compression. +This value is set by +\fB\%archive_read_open\fP(). +.TP +\fB\%archive_compression_name\fP() +Returns a text description of the current compression suitable for display. +.TP +\fB\%archive_copy_error\fP() +Copies error information from one archive to another. +.TP +\fB\%archive_errno\fP() +Returns a numeric error code (see +\fBerrno\fP(2)) +indicating the reason for the most recent error return. +.TP +\fB\%archive_error_string\fP() +Returns a textual error message suitable for display. +The error message here is usually more specific than that +obtained from passing the result of +\fB\%archive_errno\fP() +to +\fBstrerror\fP(3). +.TP +\fB\%archive_file_count\fP() +Returns a count of the number of files processed by this archive object. +The count is incremented by calls to +\fBarchive_write_header\fP() +or +\fBarchive_read_next_header\fP(.) +.TP +\fB\%archive_format\fP() +Returns a numeric code indicating the format of the current +archive entry. +This value is set by a successful call to +\fB\%archive_read_next_header\fP(). +Note that it is common for this value to change from +entry to entry. +For example, a tar archive might have several entries that +utilize GNU tar extensions and several entries that do not. +These entries will have different format codes. +.TP +\fB\%archive_format_name\fP() +A textual description of the format of the current entry. +.TP +\fB\%archive_set_error\fP() +Sets the numeric error code and error description that will be returned +by +\fB\%archive_errno\fP() +and +\fB\%archive_error_string\fP(). +This function should be used within I/O callbacks to set system-specific +error codes and error descriptions. +This function accepts a printf-like format string and arguments. +However, you should be careful to use only the following printf +format specifiers: +``%c'', +``%d'', +``%jd'', +``%jo'', +``%ju'', +``%jx'', +``%ld'', +``%lo'', +``%lu'', +``%lx'', +``%o'', +``%u'', +``%s'', +``%x'', +``%%''. +Field-width specifiers and other printf features are +not uniformly supported and should not be used. +.RE +.SH SEE ALSO +.ad l +\fBarchive_read\fP(3), +\fBarchive_write\fP(3), +\fBlibarchive\fP(3), +\fBprintf\fP(3) +.SH HISTORY +.ad l +The +\fB\%libarchive\fP +library first appeared in +FreeBSD 5.3. +.SH AUTHORS +.ad l +-nosplit +The +\fB\%libarchive\fP +library was written by +Tim Kientzle \%<kientzle@acm.org.> diff --git a/libarchive/libarchive-2.8.0/doc/man/archive_write.3 b/libarchive/libarchive-2.8.0/doc/man/archive_write.3 new file mode 100644 index 0000000..b485dcf --- /dev/null +++ b/libarchive/libarchive-2.8.0/doc/man/archive_write.3 @@ -0,0 +1,670 @@ +.TH archive_write 3 "May 11, 2008" "" +.SH NAME +.ad l +\fB\%archive_write_new\fP, +\fB\%archive_write_set_format_cpio\fP, +\fB\%archive_write_set_format_pax\fP, +\fB\%archive_write_set_format_pax_restricted\fP, +\fB\%archive_write_set_format_shar\fP, +\fB\%archive_write_set_format_shar_binary\fP, +\fB\%archive_write_set_format_ustar\fP, +\fB\%archive_write_get_bytes_per_block\fP, +\fB\%archive_write_set_bytes_per_block\fP, +\fB\%archive_write_set_bytes_in_last_block\fP, +\fB\%archive_write_set_compression_bzip2\fP, +\fB\%archive_write_set_compression_compress\fP, +\fB\%archive_write_set_compression_gzip\fP, +\fB\%archive_write_set_compression_none\fP, +\fB\%archive_write_set_compression_program\fP, +\fB\%archive_write_set_compressor_options\fP, +\fB\%archive_write_set_format_options\fP, +\fB\%archive_write_set_options\fP, +\fB\%archive_write_open\fP, +\fB\%archive_write_open_fd\fP, +\fB\%archive_write_open_FILE\fP, +\fB\%archive_write_open_filename\fP, +\fB\%archive_write_open_memory\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 archives +.SH SYNOPSIS +.ad l +\fB#include <archive.h>\fP +.br +\fIstruct archive *\fP +.br +\fB\%archive_write_new\fP(\fI\%void\fP); +.br +\fIint\fP +.br +\fB\%archive_write_get_bytes_per_block\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_write_set_bytes_per_block\fP(\fI\%struct\ archive\ *\fP, \fI\%int\ bytes_per_block\fP); +.br +\fIint\fP +.br +\fB\%archive_write_set_bytes_in_last_block\fP(\fI\%struct\ archive\ *\fP, \fI\%int\fP); +.br +\fIint\fP +.br +\fB\%archive_write_set_compression_bzip2\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_write_set_compression_compress\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_write_set_compression_gzip\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_write_set_compression_none\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_write_set_compression_program\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ char\ *\ cmd\fP); +.br +\fIint\fP +.br +\fB\%archive_write_set_format_cpio\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_write_set_format_pax\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_write_set_format_pax_restricted\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_write_set_format_shar\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_write_set_format_shar_binary\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_write_set_format_ustar\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_write_set_format_options\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ char\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_write_set_compressor_options\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ char\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_write_set_options\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ char\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_write_open\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *client_data\fP, \fI\%archive_open_callback\ *\fP, \fI\%archive_write_callback\ *\fP, \fI\%archive_close_callback\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_write_open_fd\fP(\fI\%struct\ archive\ *\fP, \fI\%int\ fd\fP); +.br +\fIint\fP +.br +\fB\%archive_write_open_FILE\fP(\fI\%struct\ archive\ *\fP, \fI\%FILE\ *file\fP); +.br +\fIint\fP +.br +\fB\%archive_write_open_filename\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ char\ *filename\fP); +.br +\fIint\fP +.br +\fB\%archive_write_open_memory\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *buffer\fP, \fI\%size_t\ bufferSize\fP, \fI\%size_t\ *outUsed\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 streaming +archive files. +The general process is to first create the +Tn struct archive +object, set any desired options, initialize the archive, append entries, then +close the archive and release all resources. +The following summary describes the functions in approximately +the order they are ordinarily used: +.RS 5 +.TP +\fB\%archive_write_new\fP() +Allocates and initializes a +Tn struct archive +object suitable for writing a tar archive. +.TP +\fB\%archive_write_set_bytes_per_block\fP() +Sets the block size used for writing the archive data. +Every call to the write callback function, except possibly the last one, will +use this value for the length. +The third parameter is a boolean that specifies whether or not the final block +written will be padded to the full block size. +If it is zero, the last block will not be padded. +If it is non-zero, padding will be added both before and after compression. +The default is to use a block size of 10240 bytes and to pad the last block. +Note that a block size of zero will suppress internal blocking +and cause writes to be sent directly to the write callback as they occur. +.TP +\fB\%archive_write_get_bytes_per_block\fP() +Retrieve the block size to be used for writing. +A value of -1 here indicates that the library should use default values. +A value of zero indicates that internal blocking is suppressed. +.TP +\fB\%archive_write_set_bytes_in_last_block\fP() +Sets the block size used for writing the last block. +If this value is zero, the last block will be padded to the same size +as the other blocks. +Otherwise, the final block will be padded to a multiple of this size. +In particular, setting it to 1 will cause the final block to not be padded. +For compressed output, any padding generated by this option +is applied only after the compression. +The uncompressed data is always unpadded. +The default is to pad the last block to the full block size (note that +\fB\%archive_write_open_filename\fP() +will set this based on the file type). +Unlike the other +``set'' +functions, this function can be called after the archive is opened. +.TP +\fB\%archive_write_get_bytes_in_last_block\fP() +Retrieve the currently-set value for last block size. +A value of -1 here indicates that the library should use default values. +.TP +\fB\%archive_write_set_format_cpio\fP(), +\fB\%archive_write_set_format_pax\fP(), +\fB\%archive_write_set_format_pax_restricted\fP(), +\fB\%archive_write_set_format_shar\fP(), +\fB\%archive_write_set_format_shar_binary\fP(), +\fB\%archive_write_set_format_ustar\fP() +Sets the format that will be used for the archive. +The library can write +POSIX octet-oriented cpio format archives, +POSIX-standard +``pax interchange'' +format archives, +traditional +``shar'' +archives, +enhanced +``binary'' +shar archives that store a variety of file attributes and handle binary files, +and +POSIX-standard +``ustar'' +archives. +The pax interchange format is a backwards-compatible tar format that +adds key/value attributes to each entry and supports arbitrary +filenames, linknames, uids, sizes, etc. +``Restricted pax interchange format'' +is the library default; this is the same as pax format, but suppresses +the pax extended header for most normal files. +In most cases, this will result in ordinary ustar archives. +.TP +\fB\%archive_write_set_compression_bzip2\fP(), +\fB\%archive_write_set_compression_compress\fP(), +\fB\%archive_write_set_compression_gzip\fP(), +\fB\%archive_write_set_compression_none\fP() +The resulting archive will be compressed as specified. +Note that the compressed output is always properly blocked. +.TP +\fB\%archive_write_set_compression_program\fP() +The archive will be fed into the specified compression program. +The output of that program is blocked and written to the client +write callbacks. +.TP +\fB\%archive_write_set_compressor_options\fP(), +\fB\%archive_write_set_format_options\fP(), +\fB\%archive_write_set_options\fP() +Specifies options that will be passed to the currently-enabled +compressor and/or format writer. +The argument is a comma-separated list of individual options. +Individual options have one of the following forms: +.RS 5 +.TP +\fIoption=value\fP +The option/value pair will be provided to every module. +Modules that do not accept an option with this name will ignore it. +.TP +\fIoption\fP +The option will be provided to every module with a value of +``1''. +.TP +\fI!option\fP +The option will be provided to every module with a NULL value. +.TP +\fImodule:option=value\fP, \fImodule:option\fP, \fImodule:!option\fP +As above, but the corresponding option and value will be provided +only to modules whose name matches +\fImodule\fP. +.RE +The return value will be +\fBARCHIVE_OK\fP +if any module accepts the option, or +\fBARCHIVE_WARN\fP +if no module accepted the option, or +\fBARCHIVE_FATAL\fP +if there was a fatal error while attempting to process the option. +.PP +The currently supported options are: +.RS 5 +.TP +Compressor gzip +.RS 5 +.TP +\fBcompression-level\fP +The value is interpreted as a decimal integer specifying the +gzip compression level. +.RE +.TP +Compressor xz +.RS 5 +.TP +\fBcompression-level\fP +The value is interpreted as a decimal integer specifying the +compression level. +.RE +.TP +Format mtree +.RS 5 +.TP +\fBcksum\fP, \fBdevice\fP, \fBflags\fP, \fBgid\fP, \fBgname\fP, \fBindent\fP, \fBlink\fP, \fBmd5\fP, \fBmode\fP, \fBnlink\fP, \fBrmd160\fP, \fBsha1\fP, \fBsha256\fP, \fBsha384\fP, \fBsha512\fP, \fBsize\fP, \fBtime\fP, \fBuid\fP, \fBuname\fP +Enable a particular keyword in the mtree output. +Prefix with an exclamation mark to disable the corresponding keyword. +The default is equivalent to +``device, flags, gid, gname, link, mode, nlink, size, time, type, uid, uname''. +.TP +\fBall\fP +Enables all of the above keywords. +.TP +\fBuse-set\fP +Enables generation of +\fB/set\fP +lines that specify default values for the following files and/or directories. +.TP +\fBindent\fP +XXX needs explanation XXX +.RE +.RE +.TP +\fB\%archive_write_open\fP() +Freeze the settings, open the archive, and prepare for writing entries. +This is the most generic form of this function, which accepts +pointers to three callback functions which will be invoked by +the compression layer to write the constructed archive. +.TP +\fB\%archive_write_open_fd\fP() +A convenience form of +\fB\%archive_write_open\fP() +that accepts a file descriptor. +The +\fB\%archive_write_open_fd\fP() +function is safe for use with tape drives or other +block-oriented devices. +.TP +\fB\%archive_write_open_FILE\fP() +A convenience form of +\fB\%archive_write_open\fP() +that accepts a +\fIFILE *\fP +pointer. +Note that +\fB\%archive_write_open_FILE\fP() +is not safe for writing to tape drives or other devices +that require correct blocking. +.TP +\fB\%archive_write_open_file\fP() +A deprecated synonym for +\fB\%archive_write_open_filename\fP(). +.TP +\fB\%archive_write_open_filename\fP() +A convenience form of +\fB\%archive_write_open\fP() +that accepts a filename. +A NULL argument indicates that the output should be written to standard output; +an argument of +``-'' +will open a file with that name. +If you have not invoked +\fB\%archive_write_set_bytes_in_last_block\fP(), +then +\fB\%archive_write_open_filename\fP() +will adjust the last-block padding depending on the file: +it will enable padding when writing to standard output or +to a character or block device node, it will disable padding otherwise. +You can override this by manually invoking +\fB\%archive_write_set_bytes_in_last_block\fP() +before calling +\fB\%archive_write_open\fP(). +The +\fB\%archive_write_open_filename\fP() +function is safe for use with tape drives or other +block-oriented devices. +.TP +\fB\%archive_write_open_memory\fP() +A convenience form of +\fB\%archive_write_open\fP() +that accepts a pointer to a block of memory that will receive +the archive. +The final +\fIsize_t *\fP +argument points to a variable that will be updated +after each write to reflect how much of the buffer +is currently in use. +You should be careful to ensure that this variable +remains allocated until after the archive is +closed. +.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. +In particular, this writes out the final padding required by some formats. +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() +Complete the archive and invoke the close callback. +.TP +\fB\%archive_write_finish\fP() +Invokes +\fB\%archive_write_close\fP() +if it was not invoked manually, then releases all resources. +Note that this function was declared to return +\fIvoid\fP +in libarchive 1.x, which made it impossible to detect errors when +\fB\%archive_write_close\fP() +was invoked implicitly from this function. +This is corrected beginning with libarchive 2.0. +.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. +.SH IMPLEMENTATION +.ad l +Compression support is built-in to libarchive, which uses zlib and bzlib +to handle gzip and bzip2 compression, respectively. +.SH CLIENT CALLBACKS +.ad l +To use this library, you will need to define and register +callback functions that will be invoked to write data to the +resulting archive. +These functions are registered by calling +\fB\%archive_write_open\fP(): +.RS 5 +.IP +\fItypedef int\fP +\fB\%archive_open_callback\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *client_data\fP) +.RE +.PP +The open callback is invoked by +\fB\%archive_write_open\fP(). +It should return +\fBARCHIVE_OK\fP +if the underlying file or data source is successfully +opened. +If the open fails, it should call +\fB\%archive_set_error\fP() +to register an error code and message and return +\fBARCHIVE_FATAL\fP. +.RS 5 +.IP +\fItypedef ssize_t\fP +\fB\%archive_write_callback\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *client_data\fP, \fI\%const\ void\ *buffer\fP, \fI\%size_t\ length\fP) +.RE +.PP +The write callback is invoked whenever the library +needs to write raw bytes to the archive. +For correct blocking, each call to the write callback function +should translate into a single +\fBwrite\fP(2) +system call. +This is especially critical when writing archives to tape drives. +On success, the write callback should return the +number of bytes actually written. +On error, the callback should invoke +\fB\%archive_set_error\fP() +to register an error code and message and return -1. +.RS 5 +.IP +\fItypedef int\fP +\fB\%archive_close_callback\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *client_data\fP) +.RE +.PP +The close callback is invoked by archive_close when +the archive processing is complete. +The callback should return +\fBARCHIVE_OK\fP +on success. +On failure, the callback should invoke +\fB\%archive_set_error\fP() +to register an error code and message and +return +\fBARCHIVE_FATAL.\fP +.SH EXAMPLE +.ad l +The following sketch illustrates basic usage of the library. +In this example, +the callback functions are simply wrappers around the standard +\fBopen\fP(2), +\fBwrite\fP(2), +and +\fBclose\fP(2) +system calls. +.RS 4 +.nf +#ifdef __linux__ +#define _FILE_OFFSET_BITS 64 +#endif +#include <sys/stat.h> +#include <archive.h> +#include <archive_entry.h> +#include <fcntl.h> +#include <stdlib.h> +#include <unistd.h> +struct mydata { + const char *name; + int fd; +}; +int +myopen(struct archive *a, void *client_data) +{ + struct mydata *mydata = client_data; + mydata->fd = open(mydata->name, O_WRONLY | O_CREAT, 0644); + if (mydata->fd >= 0) + return (ARCHIVE_OK); + else + return (ARCHIVE_FATAL); +} +ssize_t +mywrite(struct archive *a, void *client_data, const void *buff, size_t n) +{ + struct mydata *mydata = client_data; + return (write(mydata->fd, buff, n)); +} +int +myclose(struct archive *a, void *client_data) +{ + struct mydata *mydata = client_data; + if (mydata->fd > 0) + close(mydata->fd); + return (0); +} +void +write_archive(const char *outname, const char **filename) +{ + struct mydata *mydata = malloc(sizeof(struct mydata)); + struct archive *a; + struct archive_entry *entry; + struct stat st; + char buff[8192]; + int len; + int fd; + a = archive_write_new(); + mydata->name = outname; + archive_write_set_compression_gzip(a); + archive_write_set_format_ustar(a); + archive_write_open(a, mydata, myopen, mywrite, myclose); + while (*filename) { + stat(*filename, &st); + entry = archive_entry_new(); + archive_entry_copy_stat(entry, &st); + archive_entry_set_pathname(entry, *filename); + archive_write_header(a, entry); + fd = open(*filename, O_RDONLY); + len = read(fd, buff, sizeof(buff)); + while ( len > 0 ) { + archive_write_data(a, buff, len); + len = read(fd, buff, sizeof(buff)); + } + archive_entry_free(entry); + filename++; + } + archive_write_finish(a); +} +int main(int argc, const char **argv) +{ + const char *outname; + argv++; + outname = argv++; + write_archive(outname, argv); + return 0; +} +.RE +.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_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. +Note that if the client-provided write callback function +returns a non-zero value, that error will be propagated back to the caller +through whatever API function resulted in that call, which +may include +\fB\%archive_write_header\fP(), +\fB\%archive_write_data\fP(), +\fB\%archive_write_close\fP(), +or +\fB\%archive_write_finish\fP(). +The client callback can call +\fB\%archive_set_error\fP() +to provide values that can then be retrieved by +\fB\%archive_errno\fP() +and +\fB\%archive_error_string\fP(). +.SH SEE ALSO +.ad l +\fBtar\fP(1), +\fBlibarchive\fP(3), +\fBtar\fP(5) +.SH HISTORY +.ad l +The +\fB\%libarchive\fP +library first appeared in +FreeBSD 5.3. +.SH AUTHORS +.ad l +-nosplit +The +\fB\%libarchive\fP +library was written by +Tim Kientzle \%<kientzle@acm.org.> +.SH BUGS +.ad l +There are many peculiar bugs in historic tar implementations that may cause +certain programs to reject archives written by this library. +For example, several historic implementations calculated header checksums +incorrectly and will thus reject valid archives; GNU tar does not fully support +pax interchange format; some old tar implementations required specific +field terminations. +.PP +The default pax interchange format eliminates most of the historic +tar limitations and provides a generic key/value attribute facility +for vendor-defined extensions. +One oversight in POSIX is the failure to provide a standard attribute +for large device numbers. +This library uses +``SCHILY.devminor'' +and +``SCHILY.devmajor'' +for device numbers that exceed the range supported by the backwards-compatible +ustar header. +These keys are compatible with Joerg Schilling's +\fB\%star\fP +archiver. +Other implementations may not recognize these keys and will thus be unable +to correctly restore device nodes with large device numbers from archives +created by this library. 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. diff --git a/libarchive/libarchive-2.8.0/doc/man/bsdcpio.1 b/libarchive/libarchive-2.8.0/doc/man/bsdcpio.1 new file mode 100644 index 0000000..76217b4 --- /dev/null +++ b/libarchive/libarchive-2.8.0/doc/man/bsdcpio.1 @@ -0,0 +1,446 @@ +.TH BSDCPIO 1 "December 21, 2007" "" +.SH NAME +.ad l +\fB\%cpio\fP +\- copy files to and from archives +.SH SYNOPSIS +.ad l +.br +\fB\%cpio\fP +{\fB\-i\fP} +[\fIoptions\fP] +[\fIpattern\fP ...] +[\fI<\fP archive] +.br +\fB\%cpio\fP +{\fB\-o\fP} +[\fIoptions\fP] +\fI<\fP name-list +[\fI>\fP archive] +.br +\fB\%cpio\fP +{\fB\-p\fP} +[\fIoptions\fP] +\fIdest-dir\fP +\fI<\fP name-list +.SH DESCRIPTION +.ad l +\fB\%cpio\fP +copies files between archives and directories. +This implementation can extract from tar, pax, cpio, zip, jar, ar, +and ISO 9660 cdrom images and can create tar, pax, cpio, ar, +and shar archives. +.PP +The first option to +\fB\%cpio\fP +is a mode indicator from the following list: +.RS 5 +.TP +\fB\-i\fP +Input. +Read an archive from standard input (unless overriden) and extract the +contents to disk or (if the +\fB\-t\fP +option is specified) +list the contents to standard output. +If one or more file patterns are specified, only files matching +one of the patterns will be extracted. +.TP +\fB\-o\fP +Output. +Read a list of filenames from standard input and produce a new archive +on standard output (unless overriden) containing the specified items. +.TP +\fB\-p\fP +Pass-through. +Read a list of filenames from standard input and copy the files to the +specified directory. +.RE +.PP +.SH OPTIONS +.ad l +Unless specifically stated otherwise, options are applicable in +all operating modes. +.RS 5 +.TP +\fB\-0\fP +Read filenames separated by NUL characters instead of newlines. +This is necessary if any of the filenames being read might contain newlines. +.TP +\fB\-A\fP +(o mode only) +Append to the specified archive. +(Not yet implemented.) +.TP +\fB\-a\fP +(o and p modes) +Reset access times on files after they are read. +.TP +\fB\-B\fP +(o mode only) +Block output to records of 5120 bytes. +.TP +\fB\-C\fP \fIsize\fP +(o mode only) +Block output to records of +\fIsize\fP +bytes. +.TP +\fB\-c\fP +(o mode only) +Use the old POSIX portable character format. +Equivalent to +\fB\--format\fP \fIodc\fP. +.TP +\fB\-d\fP +(i and p modes) +Create directories as necessary. +.TP +\fB\-E\fP \fIfile\fP +(i mode only) +Read list of file name patterns from +\fIfile\fP +to list and extract. +.TP +\fB\-F\fP \fIfile\fP +Read archive from or write archive to +\fIfile\fP. +.TP +\fB\-f\fP \fIpattern\fP +(i mode only) +Ignore files that match +\fIpattern\fP. +.TP +\fB\--format\fP \fIformat\fP +(o mode only) +Produce the output archive in the specified format. +Supported formats include: +.PP +.RS 5 +.TP +\fIcpio\fP +Synonym for +\fIodc\fP. +.TP +\fInewc\fP +The SVR4 portable cpio format. +.TP +\fIodc\fP +The old POSIX.1 portable octet-oriented cpio format. +.TP +\fIpax\fP +The POSIX.1 pax format, an extension of the ustar format. +.TP +\fIustar\fP +The POSIX.1 tar format. +.RE +.PP +The default format is +\fIodc\fP. +See +\fBlibarchive_formats\fP(5) +for more complete information about the +formats currently supported by the underlying +\fBlibarchive\fP(3) +library. +.TP +\fB\-H\fP \fIformat\fP +Synonym for +\fB\--format\fP. +.TP +\fB\-h\fP, \fB\--help\fP +Print usage information. +.TP +\fB\-I\fP \fIfile\fP +Read archive from +\fIfile\fP. +.TP +\fB\-i\fP +Input mode. +See above for description. +.TP +\fB\--insecure\fP +(i and p mode only) +Disable security checks during extraction or copying. +This allows extraction via symbolic links and path names containing +Sq .. +in the name. +.TP +\fB\-J\fP +(o mode only) +Compress the file with xz-compatible compression before writing it. +In input mode, this option is ignored; xz compression is recognized +automatically on input. +.TP +\fB\-j\fP +Synonym for +\fB\-y\fP. +.TP +\fB\-L\fP +(o and p modes) +All symbolic links will be followed. +Normally, symbolic links are archived and copied as symbolic links. +With this option, the target of the link will be archived or copied instead. +.TP +\fB\-l\fP +(p mode only) +Create links from the target directory to the original files, +instead of copying. +.TP +\fB\-lzma\fP +(o mode only) +Compress the file with lzma-compatible compression before writing it. +In input mode, this option is ignored; lzma compression is recognized +automatically on input. +.TP +\fB\-m\fP +(i and p modes) +Set file modification time on created files to match +those in the source. +.TP +\fB\-n\fP +(i mode, only with +\fB\-t\fP) +Display numeric uid and gid. +By default, +\fB\%cpio\fP +displays the user and group names when they are provided in the +archive, or looks up the user and group names in the system +password database. +.TP +\fB\-no-preserve-owner\fP +(i mode only) +Do not attempt to restore file ownership. +This is the default when run by non-root users. +.TP +\fB\-O\fP \fIfile\fP +Write archive to +\fIfile\fP. +.TP +\fB\-o\fP +Output mode. +See above for description. +.TP +\fB\-p\fP +Pass-through mode. +See above for description. +.TP +\fB\-preserve-owner\fP +(i mode only) +Restore file ownership. +This is the default when run by the root user. +.TP +\fB\--quiet\fP +Suppress unnecessary messages. +.TP +\fB\-R\fP [user] [:] [group] +Set the owner and/or group on files in the output. +If group is specified with no user +(for example, +\fB\-R\fP \fI:wheel\fP) +then the group will be set but not the user. +If the user is specified with a trailing colon and no group +(for example, +\fB\-R\fP \fIroot:\fP) +then the group will be set to the user's default group. +If the user is specified with no trailing colon, then +the user will be set but not the group. +In +\fB\-i\fP +and +\fB\-p\fP +modes, this option can only be used by the super-user. +(For compatibility, a period can be used in place of the colon.) +.TP +\fB\-r\fP +(All modes.) +Rename files interactively. +For each file, a prompt is written to +\fI/dev/tty\fP +containing the name of the file and a line is read from +\fI/dev/tty\fP. +If the line read is blank, the file is skipped. +If the line contains a single period, the file is processed normally. +Otherwise, the line is taken to be the new name of the file. +.TP +\fB\-t\fP +(i mode only) +List the contents of the archive to stdout; +do not restore the contents to disk. +.TP +\fB\-u\fP +(i and p modes) +Unconditionally overwrite existing files. +Ordinarily, an older file will not overwrite a newer file on disk. +.TP +\fB\-v\fP +Print the name of each file to stderr as it is processed. +With +\fB\-t\fP, +provide a detailed listing of each file. +.TP +\fB\--version\fP +Print the program version information and exit. +.TP +\fB\-y\fP +(o mode only) +Compress the archive with bzip2-compatible compression before writing it. +In input mode, this option is ignored; +bzip2 compression is recognized automatically on input. +.TP +\fB\-Z\fP +(o mode only) +Compress the archive with compress-compatible compression before writing it. +In input mode, this option is ignored; +compression is recognized automatically on input. +.TP +\fB\-z\fP +(o mode only) +Compress the archive with gzip-compatible compression before writing it. +In input mode, this option is ignored; +gzip compression is recognized automatically on input. +.RE +.SH ENVIRONMENT +.ad l +The following environment variables affect the execution of +\fB\%cpio\fP: +.RS 5 +.TP +.B LANG +The locale to use. +See +\fBenviron\fP(7) +for more information. +.TP +.B TZ +The timezone to use when displaying dates. +See +\fBenviron\fP(7) +for more information. +.RE +.SH EXIT STATUS +.ad l +The \fBcpio\fP utility exits 0 on success, and >0 if an error occurs. +.SH EXAMPLES +.ad l +The +\fB\%cpio\fP +command is traditionally used to copy file heirarchies in conjunction +with the +\fBfind\fP(1) +command. +The first example here simply copies all files from +\fIsrc\fP +to +\fIdest\fP: +.RS 4 +\fB\%find\fP \fIsrc\fP | \fB\%cpio\fP \fB\-pmud\fP \fIdest\fP +.RE +.PP +By carefully selecting options to the +\fBfind\fP(1) +command and combining it with other standard utilities, +it is possible to exercise very fine control over which files are copied. +This next example copies files from +\fIsrc\fP +to +\fIdest\fP +that are more than 2 days old and whose names match a particular pattern: +.RS 4 +\fB\%find\fP \fIsrc\fP \fB\-mtime\fP \fI+2\fP | \fB\%grep\fP foo[bar] | \fB\%cpio\fP \fB\-pdmu\fP \fIdest\fP +.RE +.PP +This example copies files from +\fIsrc\fP +to +\fIdest\fP +that are more than 2 days old and which contain the word +``foobar'': +.RS 4 +\fB\%find\fP \fIsrc\fP \fB\-mtime\fP \fI+2\fP | \fB\%xargs\fP \fB\%grep\fP -l foobar | \fB\%cpio\fP \fB\-pdmu\fP \fIdest\fP +.RE +.SH COMPATIBILITY +.ad l +The mode options i, o, and p and the options +a, B, c, d, f, l, m, r, t, u, and v comply with SUSv2. +.PP +The old POSIX.1 standard specified that only +\fB\-i\fP, +\fB\-o\fP, +and +\fB\-p\fP +were interpreted as command-line options. +Each took a single argument of a list of modifier +characters. +For example, the standard syntax allows +\fB\-imu\fP +but does not support +\fB\-miu\fP +or +\fB\-i\fP \fB\-m\fP \fB\-u\fP, +since +\fIm\fP +and +\fIu\fP +are only modifiers to +\fB\-i\fP, +they are not command-line options in their own right. +The syntax supported by this implementation is backwards-compatible +with the standard. +For best compatibility, scripts should limit themselves to the +standard syntax. +.SH SEE ALSO +.ad l +\fBbzip2\fP(1), +\fBtar\fP(1), +\fBgzip\fP(1), +\fBmt\fP(1), +\fBpax\fP(1), +\fBlibarchive\fP(3), +\fBcpio\fP(5), +\fBlibarchive-formats\fP(5), +\fBtar\fP(5) +.SH STANDARDS +.ad l +There is no current POSIX standard for the cpio command; it appeared +in +ISO/IEC 9945-1:1996 (``POSIX.1'') +but was dropped from +IEEE Std 1003.1-2001 (``POSIX.1''). +.PP +The cpio, ustar, and pax interchange file formats are defined by +IEEE Std 1003.1-2001 (``POSIX.1'') +for the pax command. +.SH HISTORY +.ad l +The original +\fB\%cpio\fP +and +\fB\%find\fP +utilities were written by Dick Haight +while working in AT&T's Unix Support Group. +They first appeared in 1977 in PWB/UNIX 1.0, the +``Programmer's Work Bench'' +system developed for use within AT&T. +They were first released outside of AT&T as part of System III Unix in 1981. +As a result, +\fB\%cpio\fP +actually predates +\fB\%tar\fP, +even though it was not well-known outside of AT&T until some time later. +.PP +This is a complete re-implementation based on the +\fBlibarchive\fP(3) +library. +.SH BUGS +.ad l +The cpio archive format has several basic limitations: +It does not store user and group names, only numbers. +As a result, it cannot be reliably used to transfer +files between systems with dissimilar user and group numbering. +Older cpio formats limit the user and group numbers to +16 or 18 bits, which is insufficient for modern systems. +The cpio archive formats cannot support files over 4 gigabytes, +except for the +``odc'' +variant, which can support files up to 8 gigabytes. diff --git a/libarchive/libarchive-2.8.0/doc/man/bsdtar.1 b/libarchive/libarchive-2.8.0/doc/man/bsdtar.1 new file mode 100644 index 0000000..bd9f618 --- /dev/null +++ b/libarchive/libarchive-2.8.0/doc/man/bsdtar.1 @@ -0,0 +1,1024 @@ +.TH BSDTAR 1 "Oct 12, 2009" "" +.SH NAME +.ad l +\fB\%tar\fP +\- manipulate tape archives +.SH SYNOPSIS +.ad l +.br +\fB\%tar\fP +[\fIbundled-flags\fP <args>] +[<\fIfile\fP> | <\fIpattern\fP> ...] +.br +\fB\%tar\fP +{\fB\-c\fP} +[\fIoptions\fP] +[\fIfiles\fP | \fIdirectories\fP] +.br +\fB\%tar\fP +{\fB\-r\fP | \fB\-u\fP} +\fB\-f\fP \fIarchive-file\fP +[\fIoptions\fP] +[\fIfiles\fP | \fIdirectories\fP] +.br +\fB\%tar\fP +{\fB\-t\fP | \fB\-x\fP} +[\fIoptions\fP] +[\fIpatterns\fP] +.SH DESCRIPTION +.ad l +\fB\%tar\fP +creates and manipulates streaming archive files. +This implementation can extract from tar, pax, cpio, zip, jar, ar, +and ISO 9660 cdrom images and can create tar, pax, cpio, ar, +and shar archives. +.PP +The first synopsis form shows a +``bundled'' +option word. +This usage is provided for compatibility with historical implementations. +See COMPATIBILITY below for details. +.PP +The other synopsis forms show the preferred usage. +The first option to +\fB\%tar\fP +is a mode indicator from the following list: +.RS 5 +.TP +\fB\-c\fP +Create a new archive containing the specified items. +.TP +\fB\-r\fP +Like +\fB\-c\fP, +but new entries are appended to the archive. +Note that this only works on uncompressed archives stored in regular files. +The +\fB\-f\fP +option is required. +.TP +\fB\-t\fP +List archive contents to stdout. +.TP +\fB\-u\fP +Like +\fB\-r\fP, +but new entries are added only if they have a modification date +newer than the corresponding entry in the archive. +Note that this only works on uncompressed archives stored in regular files. +The +\fB\-f\fP +option is required. +.TP +\fB\-x\fP +Extract to disk from the archive. +If a file with the same name appears more than once in the archive, +each copy will be extracted, with later copies overwriting (replacing) +earlier copies. +.RE +.PP +In +\fB\-c\fP, +\fB\-r\fP, +or +\fB\-u\fP +mode, each specified file or directory is added to the +archive in the order specified on the command line. +By default, the contents of each directory are also archived. +.PP +In extract or list mode, the entire command line +is read and parsed before the archive is opened. +The pathnames or patterns on the command line indicate +which items in the archive should be processed. +Patterns are shell-style globbing patterns as +documented in +\fBtcsh\fP(1). +.SH OPTIONS +.ad l +Unless specifically stated otherwise, options are applicable in +all operating modes. +.RS 5 +.TP +\fB@\fP \fIarchive\fP +(c and r mode only) +The specified archive is opened and the entries +in it will be appended to the current archive. +As a simple example, +.RS 4 +\fB\%tar\fP \fB\-c\fP \fB\-f\fP \fI-\fP \fInewfile\fP \fB@\fP \fIoriginal.tar\fP +.RE +writes a new archive to standard output containing a file +\fInewfile\fP +and all of the entries from +\fIoriginal.tar\fP. +In contrast, +.RS 4 +\fB\%tar\fP \fB\-c\fP \fB\-f\fP \fI-\fP \fInewfile\fP \fIoriginal.tar\fP +.RE +creates a new archive with only two entries. +Similarly, +.RS 4 +\fB\%tar\fP \fB\-czf\fP \fI-\fP \fB\--format\fP \fBpax\fP \fB@\fP \fI-\fP +.RE +reads an archive from standard input (whose format will be determined +automatically) and converts it into a gzip-compressed +pax-format archive on stdout. +In this way, +\fB\%tar\fP +can be used to convert archives from one format to another. +.TP +\fB\-b\fP \fIblocksize\fP +Specify the block size, in 512-byte records, for tape drive I/O. +As a rule, this argument is only needed when reading from or writing +to tape drives, and usually not even then as the default block size of +20 records (10240 bytes) is very common. +.TP +\fB\-C\fP \fIdirectory\fP +In c and r mode, this changes the directory before adding +the following files. +In x mode, change directories after opening the archive +but before extracting entries from the archive. +.TP +\fB\--check-links\fP +(c and r modes only) +Issue a warning message unless all links to each file are archived. +.TP +\fB\--chroot\fP +(x mode only) +\fB\%chroot\fP() +to the current directory after processing any +\fB\-C\fP +options and before extracting any files. +.TP +\fB\--exclude\fP \fIpattern\fP +Do not process files or directories that match the +specified pattern. +Note that exclusions take precedence over patterns or filenames +specified on the command line. +.TP +\fB\--format\fP \fIformat\fP +(c, r, u mode only) +Use the specified format for the created archive. +Supported formats include +``cpio'', +``pax'', +``shar'', +and +``ustar''. +Other formats may also be supported; see +\fBlibarchive-formats\fP(5) +for more information about currently-supported formats. +In r and u modes, when extending an existing archive, the format specified +here must be compatible with the format of the existing archive on disk. +.TP +\fB\-f\fP \fIfile\fP +Read the archive from or write the archive to the specified file. +The filename can be +\fI-\fP +for standard input or standard output. +If not specified, the default tape device will be used. +(On +FreeBSD, +the default tape device is +\fI/dev/sa0\fP.) +.TP +\fB\-H\fP +(c and r mode only) +Symbolic links named on the command line will be followed; the +target of the link will be archived, not the link itself. +.TP +\fB\-h\fP +(c and r mode only) +Synonym for +\fB\-L\fP. +.TP +\fB\-I\fP +Synonym for +\fB\-T\fP. +.TP +\fB\--include\fP \fIpattern\fP +Process only files or directories that match the specified pattern. +Note that exclusions specified with +\fB\--exclude\fP +take precedence over inclusions. +If no inclusions are explicitly specified, all entries are processed by +default. +The +\fB\--include\fP +option is especially useful when filtering archives. +For example, the command +.RS 4 +\fB\%tar\fP \fB\-c\fP \fB\-f\fP \fInew.tar\fP \fB\--include='*foo*'\fP \fB@\fP \fIold.tgz\fP +.RE +creates a new archive +\fInew.tar\fP +containing only the entries from +\fIold.tgz\fP +containing the string +Sq foo. +.TP +\fB\-j\fP +(c mode only) +Compress the resulting archive with +\fBbzip2\fP(1). +In extract or list modes, this option is ignored. +Note that, unlike other +\fB\%tar\fP +implementations, this implementation recognizes bzip2 compression +automatically when reading archives. +.TP +\fB\-k\fP +(x mode only) +Do not overwrite existing files. +In particular, if a file appears more than once in an archive, +later copies will not overwrite earlier copies. +.TP +\fB\--keep-newer-files\fP +(x mode only) +Do not overwrite existing files that are newer than the +versions appearing in the archive being extracted. +.TP +\fB\-L\fP +(c and r mode only) +All symbolic links will be followed. +Normally, symbolic links are archived as such. +With this option, the target of the link will be archived instead. +.TP +\fB\-l\fP +This is a synonym for the +\fB\--check-links\fP +option. +.TP +\fB\-m\fP +(x mode only) +Do not extract modification time. +By default, the modification time is set to the time stored in the archive. +.TP +\fB\-n\fP +(c, r, u modes only) +Do not recursively archive the contents of directories. +.TP +\fB\--newer\fP \fIdate\fP +(c, r, u modes only) +Only include files and directories newer than the specified date. +This compares ctime entries. +.TP +\fB\--newer-mtime\fP \fIdate\fP +(c, r, u modes only) +Like +\fB\--newer\fP, +except it compares mtime entries instead of ctime entries. +.TP +\fB\--newer-than\fP \fIfile\fP +(c, r, u modes only) +Only include files and directories newer than the specified file. +This compares ctime entries. +.TP +\fB\--newer-mtime-than\fP \fIfile\fP +(c, r, u modes only) +Like +\fB\--newer-than\fP, +except it compares mtime entries instead of ctime entries. +.TP +\fB\--nodump\fP +(c and r modes only) +Honor the nodump file flag by skipping this file. +.TP +\fB\--null\fP +(use with +\fB\-I\fP, +\fB\-T\fP, +or +\fB\-X\fP) +Filenames or patterns are separated by null characters, +not by newlines. +This is often used to read filenames output by the +\fB\-print0\fP +option to +\fBfind\fP(1). +.TP +\fB\--numeric-owner\fP +(x mode only) +Ignore symbolic user and group names when restoring archives to disk, +only numeric uid and gid values will be obeyed. +.TP +\fB\-O\fP +(x, t modes only) +In extract (-x) mode, files will be written to standard out rather than +being extracted to disk. +In list (-t) mode, the file listing will be written to stderr rather than +the usual stdout. +.TP +\fB\-o\fP +(x mode) +Use the user and group of the user running the program rather +than those specified in the archive. +Note that this has no significance unless +\fB\-p\fP +is specified, and the program is being run by the root user. +In this case, the file modes and flags from +the archive will be restored, but ACLs or owner information in +the archive will be discarded. +.TP +\fB\-o\fP +(c, r, u mode) +A synonym for +\fB\--format\fP \fIustar\fP +.TP +\fB\--one-file-system\fP +(c, r, and u modes) +Do not cross mount points. +.TP +\fB\--options\fP \fIoptions\fP +Select optional behaviors for particular modules. +The argument is a text string containing comma-separated +keywords and values. +These are passed to the modules that handle particular +formats to control how those formats will behave. +Each option has one of the following forms: +.RS 5 +.TP +\fIkey=value\fP +The key will be set to the specified value in every module that supports it. +Modules that do not support this key will ignore it. +.TP +\fIkey\fP +The key will be enabled in every module that supports it. +This is equivalent to +\fIkey\fP \fB=1\fP. +.TP +\fI!key\fP +The key will be disabled in every module that supports it. +.TP +\fImodule:key=value\fP, \fImodule:key\fP, \fImodule:!key\fP +As above, but the corresponding key and value will be provided +only to modules whose name matches +\fImodule\fP. +.RE +The currently supported modules and keys are: +.RS 5 +.TP +\fBiso9660:joliet\fP +Support Joliet extensions. +This is enabled by default, use +\fB!joliet\fP +or +\fBiso9660:!joliet\fP +to disable. +.TP +\fBiso9660:rockridge\fP +Support Rock Ridge extensions. +This is enabled by default, use +\fB!rockridge\fP +or +\fBiso9660:!rockridge\fP +to disable. +.TP +\fBgzip:compression-level\fP +A decimal integer from 0 to 9 specifying the gzip compression level. +.TP +\fBxz:compression-level\fP +A decimal integer from 0 to 9 specifying the xz compression level. +.TP +\fBmtree:\fP \fIkeyword\fP +The mtree writer module allows you to specify which mtree keywords +will be included in the output. +Supported keywords include: +\fBcksum\fP, \fBdevice\fP, \fBflags\fP, \fBgid\fP, \fBgname\fP, \fBindent\fP, +\fBlink\fP, \fBmd5\fP, \fBmode\fP, \fBnlink\fP, \fBrmd160\fP, \fBsha1\fP, \fBsha256\fP, +\fBsha384\fP, \fBsha512\fP, \fBsize\fP, \fBtime\fP, \fBuid\fP, \fBuname\fP. +The default is equivalent to: +``device, flags, gid, gname, link, mode, nlink, size, time, type, uid, uname''. +.TP +\fBmtree:all\fP +Enables all of the above keywords. +You can also use +\fBmtree:!all\fP +to disable all keywords. +.TP +\fBmtree:use-set\fP +Enable generation of +\fB/set\fP +lines in the output. +.TP +\fBmtree:indent\fP +Produce human-readable output by indenting options and splitting lines +to fit into 80 columns. +.TP +\fBzip:compression\fP=\fItype\fP +Use +\fItype\fP +as compression method. +Supported values are store (uncompressed) and deflate (gzip algorithm). +.RE +If a provided option is not supported by any module, that +is a fatal error. +.TP +\fB\-P\fP +Preserve pathnames. +By default, absolute pathnames (those that begin with a / +character) have the leading slash removed both when creating archives +and extracting from them. +Also, +\fB\%tar\fP +will refuse to extract archive entries whose pathnames contain +\fI\& ..\fP +or whose target directory would be altered by a symlink. +This option suppresses these behaviors. +.TP +\fB\-p\fP +(x mode only) +Preserve file permissions. +Attempt to restore the full permissions, including owner, file modes, file +flags and ACLs, if available, for each item extracted from the archive. +By default, newly-created files are owned by the user running +\fB\%tar\fP, +the file mode is restored for newly-created regular files, and +all other types of entries receive default permissions. +If +\fB\%tar\fP +is being run by root, the default is to restore the owner unless the +\fB\-o\fP +option is also specified. +.TP +\fB\-q\fP (\fB\--fast-read\fP) +(x and t mode only) +Extract or list only the first archive entry that matches each pattern +or filename operand. +Exit as soon as each specified pattern or filename has been matched. +By default, the archive is always read to the very end, since +there can be multiple entries with the same name and, by convention, +later entries overwrite earlier entries. +This option is provided as a performance optimization. +.TP +\fB\-S\fP +(x mode only) +Extract files as sparse files. +For every block on disk, check first if it contains only NULL bytes and seek +over it otherwise. +This works similiar to the conv=sparse option of dd. +.TP +\fB\--strip-components\fP \fIcount\fP +(x mode only) +Remove the specified number of leading path elements. +Pathnames with fewer elements will be silently skipped. +Note that the pathname is edited after checking inclusion/exclusion patterns +but before security checks. +.TP +\fB\-s\fP \fIpattern\fP +Modify file or archive member names according to +\fIpattern\fP. +The pattern has the format +\fI/old/new/\fP [gps] +where +\fIold\fP +is a basic regular expression, +\fInew\fP +is the replacement string of the matched part, +and the optional trailing letters modify +how the replacement is handled. +If +\fIold\fP +is not matched, the pattern is skipped. +Within +\fInew\fP, +~ is substituted with the match, \1 to \9 with the content of +the corresponding captured group. +The optional trailing g specifies that matching should continue +after the matched part and stopped on the first unmatched pattern. +The optional trailing s specifies that the pattern applies to the value +of symbolic links. +The optional trailing p specifies that after a successful substitution +the original path name and the new path name should be printed to +standard error. +.TP +\fB\-T\fP \fIfilename\fP +In x or t mode, +\fB\%tar\fP +will read the list of names to be extracted from +\fIfilename\fP. +In c mode, +\fB\%tar\fP +will read names to be archived from +\fIfilename\fP. +The special name +``-C'' +on a line by itself will cause the current directory to be changed to +the directory specified on the following line. +Names are terminated by newlines unless +\fB\--null\fP +is specified. +Note that +\fB\--null\fP +also disables the special handling of lines containing +``-C''. +.TP +\fB\-U\fP +(x mode only) +Unlink files before creating them. +Without this option, +\fB\%tar\fP +overwrites existing files, which preserves existing hardlinks. +With this option, existing hardlinks will be broken, as will any +symlink that would affect the location of an extracted file. +.TP +\fB\--use-compress-program\fP \fIprogram\fP +Pipe the input (in x or t mode) or the output (in c mode) through +\fIprogram\fP +instead of using the builtin compression support. +.TP +\fB\-v\fP +Produce verbose output. +In create and extract modes, +\fB\%tar\fP +will list each file name as it is read from or written to +the archive. +In list mode, +\fB\%tar\fP +will produce output similar to that of +\fBls\fP(1). +Additional +\fB\-v\fP +options will provide additional detail. +.TP +\fB\--version\fP +Print version of +\fB\%tar\fP +and +\fB\%libarchive\fP, +and exit. +.TP +\fB\-w\fP +Ask for confirmation for every action. +.TP +\fB\-X\fP \fIfilename\fP +Read a list of exclusion patterns from the specified file. +See +\fB\--exclude\fP +for more information about the handling of exclusions. +.TP +\fB\-y\fP +(c mode only) +Compress the resulting archive with +\fBbzip2\fP(1). +In extract or list modes, this option is ignored. +Note that, unlike other +\fB\%tar\fP +implementations, this implementation recognizes bzip2 compression +automatically when reading archives. +.TP +\fB\-z\fP +(c mode only) +Compress the resulting archive with +\fBgzip\fP(1). +In extract or list modes, this option is ignored. +Note that, unlike other +\fB\%tar\fP +implementations, this implementation recognizes gzip compression +automatically when reading archives. +.TP +\fB\-Z\fP +(c mode only) +Compress the resulting archive with +\fBcompress\fP(1). +In extract or list modes, this option is ignored. +Note that, unlike other +\fB\%tar\fP +implementations, this implementation recognizes compress compression +automatically when reading archives. +.RE +.SH ENVIRONMENT +.ad l +The following environment variables affect the execution of +\fB\%tar\fP: +.RS 5 +.TP +.B LANG +The locale to use. +See +\fBenviron\fP(7) +for more information. +.TP +.B TAPE +The default tape device. +The +\fB\-f\fP +option overrides this. +.TP +.B TZ +The timezone to use when displaying dates. +See +\fBenviron\fP(7) +for more information. +.RE +.SH FILES +.ad l +.RS 5 +.TP +.B /dev/sa0 +The default tape device, if not overridden by the +.IR TAPE +environment variable or the +\fB\-f\fP +option. +.RE +.SH EXIT STATUS +.ad l +The \fBtar\fP utility exits 0 on success, and >0 if an error occurs. +.SH EXAMPLES +.ad l +The following creates a new archive +called +\fIfile.tar.gz\fP +that contains two files +\fIsource.c\fP +and +\fIsource.h\fP: +.RS 4 +\fB\%tar\fP \fB\-czf\fP \fIfile.tar.gz\fP \fIsource.c\fP \fIsource.h\fP +.RE +.PP +To view a detailed table of contents for this +archive: +.RS 4 +\fB\%tar\fP \fB\-tvf\fP \fIfile.tar.gz\fP +.RE +.PP +To extract all entries from the archive on +the default tape drive: +.RS 4 +\fB\%tar\fP \fB\-x\fP +.RE +.PP +To examine the contents of an ISO 9660 cdrom image: +.RS 4 +\fB\%tar\fP \fB\-tf\fP \fIimage.iso\fP +.RE +.PP +To move file hierarchies, invoke +\fB\%tar\fP +as +.RS 4 +\fB\%tar\fP \fB\-cf\fP \fI-\fP \fB\-C\fP \fIsrcdir\\fP. | \fB\%tar\fP \fB\-xpf\fP \fI-\fP \fB\-C\fP \fIdestdir\fP +.RE +or more traditionally +.RS 4 +cd srcdir \&; \fB\%tar\fP \fB\-cf\fP \fI-\\fP. | (cd destdir \&; \fB\%tar\fP \fB\-xpf\fP \fI-\fP) +.RE +.PP +In create mode, the list of files and directories to be archived +can also include directory change instructions of the form +\fB-C\fP \fIfoo/baz\fP +and archive inclusions of the form +\fB@\fP \fIarchive-file\fP. +For example, the command line +.RS 4 +\fB\%tar\fP \fB\-c\fP \fB\-f\fP \fInew.tar\fP \fIfoo1\fP \fB@\fP \fIold.tgz\fP \fB-C\fP \fI/tmp\fP \fIfoo2\fP +.RE +will create a new archive +\fInew.tar\fP. +\fB\%tar\fP +will read the file +\fIfoo1\fP +from the current directory and add it to the output archive. +It will then read each entry from +\fIold.tgz\fP +and add those entries to the output archive. +Finally, it will switch to the +\fI/tmp\fP +directory and add +\fIfoo2\fP +to the output archive. +.PP +An input file in +\fBmtree\fP(5) +format can be used to create an output archive with arbitrary ownership, +permissions, or names that differ from existing data on disk: +.PP +.RS 4 +$ cat input.mtree +.RE +.RS 4 +#mtree +.RE +.RS 4 +usr/bin uid=0 gid=0 mode=0755 type=dir +.RE +.RS 4 +usr/bin/ls uid=0 gid=0 mode=0755 type=file content=myls +.RE +.RS 4 +$ tar -cvf output.tar @input.mtree +.RE +.PP +The +\fB\--newer\fP +and +\fB\--newer-mtime\fP +switches accept a variety of common date and time specifications, including +``12 Mar 2005 7:14:29pm'', +``2005-03-12 19:14'', +``5 minutes ago'', +and +``19:14 PST May 1''. +.PP +The +\fB\--options\fP +argument can be used to control various details of archive generation +or reading. +For example, you can generate mtree output which only contains +\fBtype\fP, \fBtime\fP, +and +\fBuid\fP +keywords: +.RS 4 +\fB\%tar\fP \fB\-cf\fP \fIfile.tar\fP \fB\--format=mtree\fP \fB\--options='!all,type,time,uid'\fP \fIdir\fP +.RE +or you can set the compression level used by gzip or xz compression: +.RS 4 +\fB\%tar\fP \fB\-czf\fP \fIfile.tar\fP \fB\--options='compression-level=9'\fP. +.RE +For more details, see the explanation of the +\fB\%archive_read_set_options\fP() +and +\fB\%archive_write_set_options\fP() +API calls that are described in +\fBarchive_read\fP(3) +and +\fBarchive_write\fP(3). +.SH COMPATIBILITY +.ad l +The bundled-arguments format is supported for compatibility +with historic implementations. +It consists of an initial word (with no leading - character) in which +each character indicates an option. +Arguments follow as separate words. +The order of the arguments must match the order +of the corresponding characters in the bundled command word. +For example, +.RS 4 +\fB\%tar\fP \fBtbf\fP 32 \fIfile.tar\fP +.RE +specifies three flags +\fBt\fP, +\fBb\fP, +and +\fBf\fP. +The +\fBb\fP +and +\fBf\fP +flags both require arguments, +so there must be two additional items +on the command line. +The +\fI32\fP +is the argument to the +\fBb\fP +flag, and +\fIfile.tar\fP +is the argument to the +\fBf\fP +flag. +.PP +The mode options c, r, t, u, and x and the options +b, f, l, m, o, v, and w comply with SUSv2. +.PP +For maximum portability, scripts that invoke +\fB\%tar\fP +should use the bundled-argument format above, should limit +themselves to the +\fBc\fP, +\fBt\fP, +and +\fBx\fP +modes, and the +\fBb\fP, +\fBf\fP, +\fBm\fP, +\fBv\fP, +and +\fBw\fP +options. +.PP +Additional long options are provided to improve compatibility with other +tar implementations. +.SH SECURITY +.ad l +Certain security issues are common to many archiving programs, including +\fB\%tar\fP. +In particular, carefully-crafted archives can request that +\fB\%tar\fP +extract files to locations outside of the target directory. +This can potentially be used to cause unwitting users to overwrite +files they did not intend to overwrite. +If the archive is being extracted by the superuser, any file +on the system can potentially be overwritten. +There are three ways this can happen. +Although +\fB\%tar\fP +has mechanisms to protect against each one, +savvy users should be aware of the implications: +.RS 5 +.IP \(bu +Archive entries can have absolute pathnames. +By default, +\fB\%tar\fP +removes the leading +\fI/\fP +character from filenames before restoring them to guard against this problem. +.IP \(bu +Archive entries can have pathnames that include +\fI\& ..\fP +components. +By default, +\fB\%tar\fP +will not extract files containing +\fI\& ..\fP +components in their pathname. +.IP \(bu +Archive entries can exploit symbolic links to restore +files to other directories. +An archive can restore a symbolic link to another directory, +then use that link to restore a file into that directory. +To guard against this, +\fB\%tar\fP +checks each extracted path for symlinks. +If the final path element is a symlink, it will be removed +and replaced with the archive entry. +If +\fB\-U\fP +is specified, any intermediate symlink will also be unconditionally removed. +If neither +\fB\-U\fP +nor +\fB\-P\fP +is specified, +\fB\%tar\fP +will refuse to extract the entry. +.RE +To protect yourself, you should be wary of any archives that +come from untrusted sources. +You should examine the contents of an archive with +.RS 4 +\fB\%tar\fP \fB\-tf\fP \fIfilename\fP +.RE +before extraction. +You should use the +\fB\-k\fP +option to ensure that +\fB\%tar\fP +will not overwrite any existing files or the +\fB\-U\fP +option to remove any pre-existing files. +You should generally not extract archives while running with super-user +privileges. +Note that the +\fB\-P\fP +option to +\fB\%tar\fP +disables the security checks above and allows you to extract +an archive while preserving any absolute pathnames, +\fI\& ..\fP +components, or symlinks to other directories. +.SH SEE ALSO +.ad l +\fBbzip2\fP(1), +\fBcompress\fP(1), +\fBcpio\fP(1), +\fBgzip\fP(1), +\fBmt\fP(1), +\fBpax\fP(1), +\fBshar\fP(1), +\fBlibarchive\fP(3), +\fBlibarchive-formats\fP(5), +\fBtar\fP(5) +.SH STANDARDS +.ad l +There is no current POSIX standard for the tar command; it appeared +in +ISO/IEC 9945-1:1996 (``POSIX.1'') +but was dropped from +IEEE Std 1003.1-2001 (``POSIX.1''). +The options used by this implementation were developed by surveying a +number of existing tar implementations as well as the old POSIX specification +for tar and the current POSIX specification for pax. +.PP +The ustar and pax interchange file formats are defined by +IEEE Std 1003.1-2001 (``POSIX.1'') +for the pax command. +.SH HISTORY +.ad l +A +\fB\%tar\fP +command appeared in Seventh Edition Unix, which was released in January, 1979. +There have been numerous other implementations, +many of which extended the file format. +John Gilmore's +\fB\%pdtar\fP +public-domain implementation (circa November, 1987) +was quite influential, and formed the basis of GNU tar. +GNU tar was included as the standard system tar +in +FreeBSD +beginning with +FreeBSD 1.0. +.PP +This is a complete re-implementation based on the +\fBlibarchive\fP(3) +library. +.SH BUGS +.ad l +This program follows +ISO/IEC 9945-1:1996 (``POSIX.1'') +for the definition of the +\fB\-l\fP +option. +Note that GNU tar prior to version 1.15 treated +\fB\-l\fP +as a synonym for the +\fB\--one-file-system\fP +option. +.PP +The +\fB\-C\fP \fIdir\fP +option may differ from historic implementations. +.PP +All archive output is written in correctly-sized blocks, even +if the output is being compressed. +Whether or not the last output block is padded to a full +block size varies depending on the format and the +output device. +For tar and cpio formats, the last block of output is padded +to a full block size if the output is being +written to standard output or to a character or block device such as +a tape drive. +If the output is being written to a regular file, the last block +will not be padded. +Many compressors, including +\fBgzip\fP(1) +and +\fBbzip2\fP(1), +complain about the null padding when decompressing an archive created by +\fB\%tar\fP, +although they still extract it correctly. +.PP +The compression and decompression is implemented internally, so +there may be insignificant differences between the compressed output +generated by +.RS 4 +\fB\%tar\fP \fB\-czf\fP \fI-\fP file +.RE +and that generated by +.RS 4 +\fB\%tar\fP \fB\-cf\fP \fI-\fP file | \fB\%gzip\fP +.RE +.PP +The default should be to read and write archives to the standard I/O paths, +but tradition (and POSIX) dictates otherwise. +.PP +The +\fBr\fP +and +\fBu\fP +modes require that the archive be uncompressed +and located in a regular file on disk. +Other archives can be modified using +\fBc\fP +mode with the +\fI@archive-file\fP +extension. +.PP +To archive a file called +\fI@foo\fP +or +\fI-foo\fP +you must specify it as +\fI\& ./@foo\fP +or +\fI\& ./-foo\fP, +respectively. +.PP +In create mode, a leading +\fI\& ./\fP +is always removed. +A leading +\fI/\fP +is stripped unless the +\fB\-P\fP +option is specified. +.PP +There needs to be better support for file selection on both create +and extract. +.PP +There is not yet any support for multi-volume archives or for archiving +sparse files. +.PP +Converting between dissimilar archive formats (such as tar and cpio) using the +\fB@\fP \fI-\fP +convention can cause hard link information to be lost. +(This is a consequence of the incompatible ways that different archive +formats store hardlink information.) +.PP +There are alternative long options for many of the short options that +are deliberately not documented. diff --git a/libarchive/libarchive-2.8.0/doc/man/cpio.5 b/libarchive/libarchive-2.8.0/doc/man/cpio.5 new file mode 100644 index 0000000..922df01 --- /dev/null +++ b/libarchive/libarchive-2.8.0/doc/man/cpio.5 @@ -0,0 +1,329 @@ +.TH CPIO 5 "October 5, 2007" "" +.SH NAME +.ad l +\fB\%cpio\fP +\- format of cpio archive files +.SH DESCRIPTION +.ad l +The +\fB\%cpio\fP +archive format collects any number of files, directories, and other +file system objects (symbolic links, device nodes, etc.) into a single +stream of bytes. +.SS General Format +Each file system object in a +\fB\%cpio\fP +archive comprises a header record with basic numeric metadata +followed by the full pathname of the entry and the file data. +The header record stores a series of integer values that generally +follow the fields in +\fIstruct\fP stat. +(See +\fBstat\fP(2) +for details.) +The variants differ primarily in how they store those integers +(binary, octal, or hexadecimal). +The header is followed by the pathname of the +entry (the length of the pathname is stored in the header) +and any file data. +The end of the archive is indicated by a special record with +the pathname +``TRAILER!!!''. +.SS PWB format +XXX Any documentation of the original PWB/UNIX 1.0 format? XXX +.SS Old Binary Format +The old binary +\fB\%cpio\fP +format stores numbers as 2-byte and 4-byte binary values. +Each entry begins with a header in the following format: +.RS 4 +.nf +struct header_old_cpio { + unsigned short c_magic; + unsigned short c_dev; + unsigned short c_ino; + unsigned short c_mode; + unsigned short c_uid; + unsigned short c_gid; + unsigned short c_nlink; + unsigned short c_rdev; + unsigned short c_mtime[2]; + unsigned short c_namesize; + unsigned short c_filesize[2]; +}; +.RE +.PP +The +\fIunsigned\fP short +fields here are 16-bit integer values; the +\fIunsigned\fP int +fields are 32-bit integer values. +The fields are as follows +.RS 5 +.TP +\fImagic\fP +The integer value octal 070707. +This value can be used to determine whether this archive is +written with little-endian or big-endian integers. +.TP +\fIdev\fP, \fIino\fP +The device and inode numbers from the disk. +These are used by programs that read +\fB\%cpio\fP +archives to determine when two entries refer to the same file. +Programs that synthesize +\fB\%cpio\fP +archives should be careful to set these to distinct values for each entry. +.TP +\fImode\fP +The mode specifies both the regular permissions and the file type. +It consists of several bit fields as follows: +.RS 5 +.TP +0170000 +This masks the file type bits. +.TP +0140000 +File type value for sockets. +.TP +0120000 +File type value for symbolic links. +For symbolic links, the link body is stored as file data. +.TP +0100000 +File type value for regular files. +.TP +0060000 +File type value for block special devices. +.TP +0040000 +File type value for directories. +.TP +0020000 +File type value for character special devices. +.TP +0010000 +File type value for named pipes or FIFOs. +.TP +0004000 +SUID bit. +.TP +0002000 +SGID bit. +.TP +0001000 +Sticky bit. +On some systems, this modifies the behavior of executables and/or directories. +.TP +0000777 +The lower 9 bits specify read/write/execute permissions +for world, group, and user following standard POSIX conventions. +.RE +.TP +\fIuid\fP, \fIgid\fP +The numeric user id and group id of the owner. +.TP +\fInlink\fP +The number of links to this file. +Directories always have a value of at least two here. +Note that hardlinked files include file data with every copy in the archive. +.TP +\fIrdev\fP +For block special and character special entries, +this field contains the associated device number. +For all other entry types, it should be set to zero by writers +and ignored by readers. +.TP +\fImtime\fP +Modification time of the file, indicated as the number +of seconds since the start of the epoch, +00:00:00 UTC January 1, 1970. +The four-byte integer is stored with the most-significant 16 bits first +followed by the least-significant 16 bits. +Each of the two 16 bit values are stored in machine-native byte order. +.TP +\fInamesize\fP +The number of bytes in the pathname that follows the header. +This count includes the trailing NUL byte. +.TP +\fIfilesize\fP +The size of the file. +Note that this archive format is limited to +four gigabyte file sizes. +See +\fImtime\fP +above for a description of the storage of four-byte integers. +.RE +.PP +The pathname immediately follows the fixed header. +If the +\fBnamesize\fP +is odd, an additional NUL byte is added after the pathname. +The file data is then appended, padded with NUL +bytes to an even length. +.PP +Hardlinked files are not given special treatment; +the full file contents are included with each copy of the +file. +.SS Portable ASCII Format +Version 2 of the Single UNIX Specification (``SUSv2'') +standardized an ASCII variant that is portable across all +platforms. +It is commonly known as the +``old character'' +format or as the +``odc'' +format. +It stores the same numeric fields as the old binary format, but +represents them as 6-character or 11-character octal values. +.RS 4 +.nf +struct cpio_odc_header { + char c_magic[6]; + char c_dev[6]; + char c_ino[6]; + char c_mode[6]; + char c_uid[6]; + char c_gid[6]; + char c_nlink[6]; + char c_rdev[6]; + char c_mtime[11]; + char c_namesize[6]; + char c_filesize[11]; +}; +.RE +.PP +The fields are identical to those in the old binary format. +The name and file body follow the fixed header. +Unlike the old binary format, there is no additional padding +after the pathname or file contents. +If the files being archived are themselves entirely ASCII, then +the resulting archive will be entirely ASCII, except for the +NUL byte that terminates the name field. +.SS New ASCII Format +The "new" ASCII format uses 8-byte hexadecimal fields for +all numbers and separates device numbers into separate fields +for major and minor numbers. +.RS 4 +.nf +struct cpio_newc_header { + char c_magic[6]; + char c_ino[8]; + char c_mode[8]; + char c_uid[8]; + char c_gid[8]; + char c_nlink[8]; + char c_mtime[8]; + char c_filesize[8]; + char c_devmajor[8]; + char c_devminor[8]; + char c_rdevmajor[8]; + char c_rdevminor[8]; + char c_namesize[8]; + char c_check[8]; +}; +.RE +.PP +Except as specified below, the fields here match those specified +for the old binary format above. +.RS 5 +.TP +\fImagic\fP +The string +``070701''. +.TP +\fIcheck\fP +This field is always set to zero by writers and ignored by readers. +See the next section for more details. +.RE +.PP +The pathname is followed by NUL bytes so that the total size +of the fixed header plus pathname is a multiple of four. +Likewise, the file data is padded to a multiple of four bytes. +Note that this format supports only 4 gigabyte files (unlike the +older ASCII format, which supports 8 gigabyte files). +.PP +In this format, hardlinked files are handled by setting the +filesize to zero for each entry except the last one that +appears in the archive. +.SS New CRC Format +The CRC format is identical to the new ASCII format described +in the previous section except that the magic field is set +to +``070702'' +and the +\fIcheck\fP +field is set to the sum of all bytes in the file data. +This sum is computed treating all bytes as unsigned values +and using unsigned arithmetic. +Only the least-significant 32 bits of the sum are stored. +.SS HP variants +The +\fB\%cpio\fP +implementation distributed with HPUX used XXXX but stored +device numbers differently XXX. +.SS Other Extensions and Variants +Sun Solaris uses additional file types to store extended file +data, including ACLs and extended attributes, as special +entries in cpio archives. +.PP +XXX Others? XXX +.SH BUGS +.ad l +The +``CRC'' +format is mis-named, as it uses a simple checksum and +not a cyclic redundancy check. +.PP +The old binary format is limited to 16 bits for user id, +group id, device, and inode numbers. +It is limited to 4 gigabyte file sizes. +.PP +The old ASCII format is limited to 18 bits for +the user id, group id, device, and inode numbers. +It is limited to 8 gigabyte file sizes. +.PP +The new ASCII format is limited to 4 gigabyte file sizes. +.PP +None of the cpio formats store user or group names, +which are essential when moving files between systems with +dissimilar user or group numbering. +.PP +Especially when writing older cpio variants, it may be necessary +to map actual device/inode values to synthesized values that +fit the available fields. +With very large filesystems, this may be necessary even for +the newer formats. +.SH SEE ALSO +.ad l +\fBcpio\fP(1), +\fBtar\fP(5) +.SH STANDARDS +.ad l +The +\fB\%cpio\fP +utility is no longer a part of POSIX or the Single Unix Standard. +It last appeared in +Version 2 of the Single UNIX Specification (``SUSv2''). +It has been supplanted in subsequent standards by +\fBpax\fP(1). +The portable ASCII format is currently part of the specification for the +\fBpax\fP(1) +utility. +.SH HISTORY +.ad l +The original cpio utility was written by Dick Haight +while working in AT&T's Unix Support Group. +It appeared in 1977 as part of PWB/UNIX 1.0, the +``Programmer's Work Bench'' +derived from +At v6 +that was used internally at AT&T. +Both the old binary and old character formats were in use +by 1980, according to the System III source released +by SCO under their +``Ancient Unix'' +license. +The character format was adopted as part of +IEEE Std 1003.1-1988 (``POSIX.1''). +XXX when did "newc" appear? Who invented it? When did HP come out with their variant? When did Sun introduce ACLs and extended attributes? XXX diff --git a/libarchive/libarchive-2.8.0/doc/man/libarchive-formats.5 b/libarchive/libarchive-2.8.0/doc/man/libarchive-formats.5 new file mode 100644 index 0000000..ff87c8b --- /dev/null +++ b/libarchive/libarchive-2.8.0/doc/man/libarchive-formats.5 @@ -0,0 +1,341 @@ +.TH libarchive-formats 5 "December 27, 2009" "" +.SH NAME +.ad l +\fB\%libarchive-formats\fP +\- archive formats supported by the libarchive library +.SH DESCRIPTION +.ad l +The +\fBlibarchive\fP(3) +library reads and writes a variety of streaming archive formats. +Generally speaking, all of these archive formats consist of a series of +``entries''. +Each entry stores a single file system object, such as a file, directory, +or symbolic link. +.PP +The following provides a brief description of each format supported +by libarchive, with some information about recognized extensions or +limitations of the current library support. +Note that just because a format is supported by libarchive does not +imply that a program that uses libarchive will support that format. +Applications that use libarchive specify which formats they wish +to support, though many programs do use libarchive convenience +functions to enable all supported formats. +.SS Tar Formats +The +\fBlibarchive\fP(3) +library can read most tar archives. +However, it only writes POSIX-standard +``ustar'' +and +``pax interchange'' +formats. +.PP +All tar formats store each entry in one or more 512-byte records. +The first record is used for file metadata, including filename, +timestamp, and mode information, and the file data is stored in +subsequent records. +Later variants have extended this by either appropriating undefined +areas of the header record, extending the header to multiple records, +or by storing special entries that modify the interpretation of +subsequent entries. +.PP +.RS 5 +.TP +\fBgnutar\fP +The +\fBlibarchive\fP(3) +library can read GNU-format tar archives. +It currently supports the most popular GNU extensions, including +modern long filename and linkname support, as well as atime and ctime data. +The libarchive library does not support multi-volume +archives, nor the old GNU long filename format. +It can read GNU sparse file entries, including the new POSIX-based +formats, but cannot write GNU sparse file entries. +.TP +\fBpax\fP +The +\fBlibarchive\fP(3) +library can read and write POSIX-compliant pax interchange format +archives. +Pax interchange format archives are an extension of the older ustar +format that adds a separate entry with additional attributes stored +as key/value pairs immediately before each regular entry. +The presence of these additional entries is the only difference between +pax interchange format and the older ustar format. +The extended attributes are of unlimited length and are stored +as UTF-8 Unicode strings. +Keywords defined in the standard are in all lowercase; vendors are allowed +to define custom keys by preceding them with the vendor name in all uppercase. +When writing pax archives, libarchive uses many of the SCHILY keys +defined by Joerg Schilling's +``star'' +archiver and a few LIBARCHIVE keys. +The libarchive library can read most of the SCHILY keys +and most of the GNU keys introduced by GNU tar. +It silently ignores any keywords that it does not understand. +.TP +\fBrestricted\fP pax +The libarchive library can also write pax archives in which it +attempts to suppress the extended attributes entry whenever +possible. +The result will be identical to a ustar archive unless the +extended attributes entry is required to store a long file +name, long linkname, extended ACL, file flags, or if any of the standard +ustar data (user name, group name, UID, GID, etc) cannot be fully +represented in the ustar header. +In all cases, the result can be dearchived by any program that +can read POSIX-compliant pax interchange format archives. +Programs that correctly read ustar format (see below) will also be +able to read this format; any extended attributes will be extracted as +separate files stored in +\fIPaxHeader\fP +directories. +.TP +\fBustar\fP +The libarchive library can both read and write this format. +This format has the following limitations: +.RS 5 +.IP \(bu +Device major and minor numbers are limited to 21 bits. +Nodes with larger numbers will not be added to the archive. +.IP \(bu +Path names in the archive are limited to 255 bytes. +(Shorter if there is no / character in exactly the right place.) +.IP \(bu +Symbolic links and hard links are stored in the archive with +the name of the referenced file. +This name is limited to 100 bytes. +.IP \(bu +Extended attributes, file flags, and other extended +security information cannot be stored. +.IP \(bu +Archive entries are limited to 8 gigabytes in size. +.RE +Note that the pax interchange format has none of these restrictions. +.RE +.PP +The libarchive library also reads a variety of commonly-used extensions to +the basic tar format. +These extensions are recognized automatically whenever they appear. +.RS 5 +.TP +Numeric extensions. +The POSIX standards require fixed-length numeric fields to be written with +some character position reserved for terminators. +Libarchive allows these fields to be written without terminator characters. +This extends the allowable range; in particular, ustar archives with this +extension can support entries up to 64 gigabytes in size. +Libarchive also recognizes base-256 values in most numeric fields. +This essentially removes all limitations on file size, modification time, +and device numbers. +.TP +Solaris extensions +Libarchive recognizes ACL and extended attribute records written +by Solaris tar. +Currently, libarchive only has support for old-style ACLs; the +newer NFSv4 ACLs are recognized but discarded. +.RE +.PP +The first tar program appeared in Seventh Edition Unix in 1979. +The first official standard for the tar file format was the +``ustar'' +(Unix Standard Tar) format defined by POSIX in 1988. +POSIX.1-2001 extended the ustar format to create the +``pax interchange'' +format. +.SS Cpio Formats +The libarchive library can read a number of common cpio variants and can write +``odc'' +and +``newc'' +format archives. +A cpio archive stores each entry as a fixed-size header followed +by a variable-length filename and variable-length data. +Unlike the tar format, the cpio format does only minimal padding +of the header or file data. +There are several cpio variants, which differ primarily in +how they store the initial header: some store the values as +octal or hexadecimal numbers in ASCII, others as binary values of +varying byte order and length. +.RS 5 +.TP +\fBbinary\fP +The libarchive library transparently reads both big-endian and little-endian +variants of the original binary cpio format. +This format used 32-bit binary values for file size and mtime, +and 16-bit binary values for the other fields. +.TP +\fBodc\fP +The libarchive library can both read and write this +POSIX-standard format, which is officially known as the +``cpio interchange format'' +or the +``octet-oriented cpio archive format'' +and sometimes unofficially referred to as the +``old character format''. +This format stores the header contents as octal values in ASCII. +It is standard, portable, and immune from byte-order confusion. +File sizes and mtime are limited to 33 bits (8GB file size), +other fields are limited to 18 bits. +.TP +\fBSVR4\fP +The libarchive library can read both CRC and non-CRC variants of +this format. +The SVR4 format uses eight-digit hexadecimal values for +all header fields. +This limits file size to 4GB, and also limits the mtime and +other fields to 32 bits. +The SVR4 format can optionally include a CRC of the file +contents, although libarchive does not currently verify this CRC. +.RE +.PP +Cpio first appeared in PWB/UNIX 1.0, which was released within +AT&T in 1977. +PWB/UNIX 1.0 formed the basis of System III Unix, released outside +of AT&T in 1981. +This makes cpio older than tar, although cpio was not included +in Version 7 AT&T Unix. +As a result, the tar command became much better known in universities +and research groups that used Version 7. +The combination of the +\fB\%find\fP +and +\fB\%cpio\fP +utilities provided very precise control over file selection. +Unfortunately, the format has many limitations that make it unsuitable +for widespread use. +Only the POSIX format permits files over 4GB, and its 18-bit +limit for most other fields makes it unsuitable for modern systems. +In addition, cpio formats only store numeric UID/GID values (not +usernames and group names), which can make it very difficult to correctly +transfer archives across systems with dissimilar user numbering. +.SS Shar Formats +A +``shell archive'' +is a shell script that, when executed on a POSIX-compliant +system, will recreate a collection of file system objects. +The libarchive library can write two different kinds of shar archives: +.RS 5 +.TP +\fBshar\fP +The traditional shar format uses a limited set of POSIX +commands, including +\fBecho\fP(1), +\fBmkdir\fP(1), +and +\fBsed\fP(1). +It is suitable for portably archiving small collections of plain text files. +However, it is not generally well-suited for large archives +(many implementations of +\fBsh\fP(1) +have limits on the size of a script) nor should it be used with non-text files. +.TP +\fBshardump\fP +This format is similar to shar but encodes files using +\fBuuencode\fP(1) +so that the result will be a plain text file regardless of the file contents. +It also includes additional shell commands that attempt to reproduce as +many file attributes as possible, including owner, mode, and flags. +The additional commands used to restore file attributes make +shardump archives less portable than plain shar archives. +.RE +.SS ISO9660 format +Libarchive can read and extract from files containing ISO9660-compliant +CDROM images. +In many cases, this can remove the need to burn a physical CDROM +just in order to read the files contained in an ISO9660 image. +It also avoids security and complexity issues that come with +virtual mounts and loopback devices. +Libarchive supports the most common Rockridge extensions and has partial +support for Joliet extensions. +If both extensions are present, the Joliet extensions will be +used and the Rockridge extensions will be ignored. +In particular, this can create problems with hardlinks and symlinks, +which are supported by Rockridge but not by Joliet. +.SS Zip format +Libarchive can read and write zip format archives that have +uncompressed entries and entries compressed with the +``deflate'' +algorithm. +Older zip compression algorithms are not supported. +It can extract jar archives, archives that use Zip64 extensions and many +self-extracting zip archives. +Libarchive reads Zip archives as they are being streamed, +which allows it to read archives of arbitrary size. +It currently does not use the central directory; this +limits libarchive's ability to support some self-extracting +archives and ones that have been modified in certain ways. +.SS Archive (library) file format +The Unix archive format (commonly created by the +\fBar\fP(1) +archiver) is a general-purpose format which is +used almost exclusively for object files to be +read by the link editor +\fBld\fP(1). +The ar format has never been standardised. +There are two common variants: +the GNU format derived from SVR4, +and the BSD format, which first appeared in 4.4BSD. +The two differ primarily in their handling of filenames +longer than 15 characters: +the GNU/SVR4 variant writes a filename table at the beginning of the archive; +the BSD format stores each long filename in an extension +area adjacent to the entry. +Libarchive can read both extensions, +including archives that may include both types of long filenames. +Programs using libarchive can write GNU/SVR4 format +if they provide a filename table to be written into +the archive before any of the entries. +Any entries whose names are not in the filename table +will be written using BSD-style long filenames. +This can cause problems for programs such as +GNU ld that do not support the BSD-style long filenames. +.SS mtree +Libarchive can read and write files in +\fBmtree\fP(5) +format. +This format is not a true archive format, but rather a textual description +of a file hierarchy in which each line specifies the name of a file and +provides specific metadata about that file. +Libarchive can read all of the keywords supported by both +the NetBSD and FreeBSD versions of +\fBmtree\fP(1), +although many of the keywords cannot currently be stored in an +Tn archive_entry +object. +When writing, libarchive supports use of the +\fBarchive_write_set_options\fP(3) +interface to specify which keywords should be included in the +output. +If libarchive was compiled with access to suitable +cryptographic libraries (such as the OpenSSL libraries), +it can compute hash entries such as +\fBsha512\fP +or +\fBmd5\fP +from file data being written to the mtree writer. +.PP +When reading an mtree file, libarchive will locate the corresponding +files on disk using the +\fBcontents\fP +keyword if present or the regular filename. +If it can locate and open the file on disk, it will use that +to fill in any metadata that is missing from the mtree file +and will read the file contents and return those to the program +using libarchive. +If it cannot locate and open the file on disk, libarchive +will return an error for any attempt to read the entry +body. +.SH SEE ALSO +.ad l +\fBar\fP(1), +\fBcpio\fP(1), +\fBmkisofs\fP(1), +\fBshar\fP(1), +\fBtar\fP(1), +\fBzip\fP(1), +\fBzlib\fP(3), +\fBcpio\fP(5), +\fBmtree\fP(5), +\fBtar\fP(5) diff --git a/libarchive/libarchive-2.8.0/doc/man/libarchive.3 b/libarchive/libarchive-2.8.0/doc/man/libarchive.3 new file mode 100644 index 0000000..1af1861 --- /dev/null +++ b/libarchive/libarchive-2.8.0/doc/man/libarchive.3 @@ -0,0 +1,315 @@ +.TH LIBARCHIVE 3 "August 19, 2006" "" +.SH NAME +.ad l +\fB\%libarchive\fP +\- functions for reading and writing streaming archives +.SH LIBRARY +.ad l +Lb libarchive +.SH OVERVIEW +.ad l +The +\fB\%libarchive\fP +library provides a flexible interface for reading and writing +streaming archive files such as tar and cpio. +The library is inherently stream-oriented; readers serially iterate through +the archive, writers serially add things to the archive. +In particular, note that there is no built-in support for +random access nor for in-place modification. +.PP +When reading an archive, the library automatically detects the +format and the compression. +The library currently has read support for: +.RS 5 +.IP \(bu +old-style tar archives, +.IP \(bu +most variants of the POSIX +``ustar'' +format, +.IP \(bu +the POSIX +``pax interchange'' +format, +.IP \(bu +GNU-format tar archives, +.IP \(bu +most common cpio archive formats, +.IP \(bu +ISO9660 CD images (with or without RockRidge extensions), +.IP \(bu +Zip archives. +.RE +The library automatically detects archives compressed with +\fBgzip\fP(1), +\fBbzip2\fP(1), +or +\fBcompress\fP(1) +and decompresses them transparently. +.PP +When writing an archive, you can specify the compression +to be used and the format to use. +The library can write +.RS 5 +.IP \(bu +POSIX-standard +``ustar'' +archives, +.IP \(bu +POSIX +``pax interchange format'' +archives, +.IP \(bu +POSIX octet-oriented cpio archives, +.IP \(bu +two different variants of shar archives. +.RE +Pax interchange format is an extension of the tar archive format that +eliminates essentially all of the limitations of historic tar formats +in a standard fashion that is supported +by POSIX-compliant +\fBpax\fP(1) +implementations on many systems as well as several newer implementations of +\fBtar\fP(1). +Note that the default write format will suppress the pax extended +attributes for most entries; explicitly requesting pax format will +enable those attributes for all entries. +.PP +The read and write APIs are accessed through the +\fB\%archive_read_XXX\fP() +functions and the +\fB\%archive_write_XXX\fP() +functions, respectively, and either can be used independently +of the other. +.PP +The rest of this manual page provides an overview of the library +operation. +More detailed information can be found in the individual manual +pages for each API or utility function. +.SH READING AN ARCHIVE +.ad l +To read an archive, you must first obtain an initialized +Tn struct archive +object from +\fB\%archive_read_new\fP(). +You can then modify this object for the desired operations with the +various +\fB\%archive_read_set_XXX\fP() +and +\fB\%archive_read_support_XXX\fP() +functions. +In particular, you will need to invoke appropriate +\fB\%archive_read_support_XXX\fP() +functions to enable the corresponding compression and format +support. +Note that these latter functions perform two distinct operations: +they cause the corresponding support code to be linked into your +program, and they enable the corresponding auto-detect code. +Unless you have specific constraints, you will generally want +to invoke +\fB\%archive_read_support_compression_all\fP() +and +\fB\%archive_read_support_format_all\fP() +to enable auto-detect for all formats and compression types +currently supported by the library. +.PP +Once you have prepared the +Tn struct archive +object, you call +\fB\%archive_read_open\fP() +to actually open the archive and prepare it for reading. +There are several variants of this function; +the most basic expects you to provide pointers to several +functions that can provide blocks of bytes from the archive. +There are convenience forms that allow you to +specify a filename, file descriptor, +\fIFILE *\fP +object, or a block of memory from which to read the archive data. +Note that the core library makes no assumptions about the +size of the blocks read; +callback functions are free to read whatever block size is +most appropriate for the medium. +.PP +Each archive entry consists of a header followed by a certain +amount of data. +You can obtain the next header with +\fB\%archive_read_next_header\fP(), +which returns a pointer to an +Tn struct archive_entry +structure with information about the current archive element. +If the entry is a regular file, then the header will be followed +by the file data. +You can use +\fB\%archive_read_data\fP() +(which works much like the +\fBread\fP(2) +system call) +to read this data from the archive. +You may prefer to use the higher-level +\fB\%archive_read_data_skip\fP(), +which reads and discards the data for this entry, +\fB\%archive_read_data_to_buffer\fP(), +which reads the data into an in-memory buffer, +\fB\%archive_read_data_to_file\fP(), +which copies the data to the provided file descriptor, or +\fB\%archive_read_extract\fP(), +which recreates the specified entry on disk and copies data +from the archive. +In particular, note that +\fB\%archive_read_extract\fP() +uses the +Tn struct archive_entry +structure that you provide it, which may differ from the +entry just read from the archive. +In particular, many applications will want to override the +pathname, file permissions, or ownership. +.PP +Once you have finished reading data from the archive, you +should call +\fB\%archive_read_close\fP() +to close the archive, then call +\fB\%archive_read_finish\fP() +to release all resources, including all memory allocated by the library. +.PP +The +\fBarchive_read\fP(3) +manual page provides more detailed calling information for this API. +.SH WRITING AN ARCHIVE +.ad l +You use a similar process to write an archive. +The +\fB\%archive_write_new\fP() +function creates an archive object useful for writing, +the various +\fB\%archive_write_set_XXX\fP() +functions are used to set parameters for writing the archive, and +\fB\%archive_write_open\fP() +completes the setup and opens the archive for writing. +.PP +Individual archive entries are written in a three-step +process: +You first initialize a +Tn struct archive_entry +structure with information about the new entry. +At a minimum, you should set the pathname of the +entry and provide a +\fIstruct\fP stat +with a valid +\fIst_mode\fP +field, which specifies the type of object and +\fIst_size\fP +field, which specifies the size of the data portion of the object. +The +\fB\%archive_write_header\fP() +function actually writes the header data to the archive. +You can then use +\fB\%archive_write_data\fP() +to write the actual data. +.PP +After all entries have been written, use the +\fB\%archive_write_finish\fP() +function to release all resources. +.PP +The +\fBarchive_write\fP(3) +manual page provides more detailed calling information for this API. +.SH DESCRIPTION +.ad l +Detailed descriptions of each function are provided by the +corresponding manual pages. +.PP +All of the functions utilize an opaque +Tn struct archive +datatype that provides access to the archive contents. +.PP +The +Tn struct archive_entry +structure contains a complete description of a single archive +entry. +It uses an opaque interface that is fully documented in +\fBarchive_entry\fP(3). +.PP +Users familiar with historic formats should be aware that the newer +variants have eliminated most restrictions on the length of textual fields. +Clients should not assume that filenames, link names, user names, or +group names are limited in length. +In particular, pax interchange format can easily accommodate pathnames +in arbitrary character sets that exceed +\fIPATH_MAX\fP. +.SH RETURN VALUES +.ad l +Most functions return zero on success, non-zero on error. +The return value indicates the general severity of the error, ranging +from +\fBARCHIVE_WARN\fP, +which indicates a minor problem that should probably be reported +to the user, to +\fBARCHIVE_FATAL\fP, +which indicates a serious problem that will prevent any further +operations on this archive. +On error, the +\fB\%archive_errno\fP() +function can be used to retrieve a numeric error code (see +\fBerrno\fP(2)). +The +\fB\%archive_error_string\fP() +returns a textual error message suitable for display. +.PP +\fB\%archive_read_new\fP() +and +\fB\%archive_write_new\fP() +return pointers to an allocated and initialized +Tn struct archive +object. +.PP +\fB\%archive_read_data\fP() +and +\fB\%archive_write_data\fP() +return a count of the number of bytes actually read or written. +A value of zero indicates the end of the data for this entry. +A negative value indicates an error, in which case the +\fB\%archive_errno\fP() +and +\fB\%archive_error_string\fP() +functions can be used to obtain more information. +.SH ENVIRONMENT +.ad l +There are character set conversions within the +\fBarchive_entry\fP(3) +functions that are impacted by the currently-selected locale. +.SH SEE ALSO +.ad l +\fBtar\fP(1), +\fBarchive_entry\fP(3), +\fBarchive_read\fP(3), +\fBarchive_util\fP(3), +\fBarchive_write\fP(3), +\fBtar\fP(5) +.SH HISTORY +.ad l +The +\fB\%libarchive\fP +library first appeared in +FreeBSD 5.3. +.SH AUTHORS +.ad l +-nosplit +The +\fB\%libarchive\fP +library was written by +Tim Kientzle \%<kientzle@acm.org.> +.SH BUGS +.ad l +Some archive formats support information that is not supported by +Tn struct archive_entry. +Such information cannot be fully archived or restored using this library. +This includes, for example, comments, character sets, +or the arbitrary key/value pairs that can appear in +pax interchange format archives. +.PP +Conversely, of course, not all of the information that can be +stored in an +Tn struct archive_entry +is supported by all formats. +For example, cpio formats do not support nanosecond timestamps; +old tar formats do not support large device numbers. diff --git a/libarchive/libarchive-2.8.0/doc/man/libarchive_internals.3 b/libarchive/libarchive-2.8.0/doc/man/libarchive_internals.3 new file mode 100644 index 0000000..98b99a3 --- /dev/null +++ b/libarchive/libarchive-2.8.0/doc/man/libarchive_internals.3 @@ -0,0 +1,361 @@ +.TH LIBARCHIVE 3 "April 16, 2007" "" +.SH NAME +.ad l +\fB\%libarchive_internals\fP +\- description of libarchive internal interfaces +.SH OVERVIEW +.ad l +The +\fB\%libarchive\fP +library provides a flexible interface for reading and writing +streaming archive files such as tar and cpio. +Internally, it follows a modular layered design that should +make it easy to add new archive and compression formats. +.SH GENERAL ARCHITECTURE +.ad l +Externally, libarchive exposes most operations through an +opaque, object-style interface. +The +\fBarchive_entry\fP(1) +objects store information about a single filesystem object. +The rest of the library provides facilities to write +\fBarchive_entry\fP(1) +objects to archive files, +read them from archive files, +and write them to disk. +(There are plans to add a facility to read +\fBarchive_entry\fP(1) +objects from disk as well.) +.PP +The read and write APIs each have four layers: a public API +layer, a format layer that understands the archive file format, +a compression layer, and an I/O layer. +The I/O layer is completely exposed to clients who can replace +it entirely with their own functions. +.PP +In order to provide as much consistency as possible for clients, +some public functions are virtualized. +Eventually, it should be possible for clients to open +an archive or disk writer, and then use a single set of +code to select and write entries, regardless of the target. +.SH READ ARCHITECTURE +.ad l +From the outside, clients use the +\fBarchive_read\fP(3) +API to manipulate an +\fB\%archive\fP +object to read entries and bodies from an archive stream. +Internally, the +\fB\%archive\fP +object is cast to an +\fB\%archive_read\fP +object, which holds all read-specific data. +The API has four layers: +The lowest layer is the I/O layer. +This layer can be overridden by clients, but most clients use +the packaged I/O callbacks provided, for example, by +\fBarchive_read_open_memory\fP(3), +and +\fBarchive_read_open_fd\fP(3). +The compression layer calls the I/O layer to +read bytes and decompresses them for the format layer. +The format layer unpacks a stream of uncompressed bytes and +creates +\fB\%archive_entry\fP +objects from the incoming data. +The API layer tracks overall state +(for example, it prevents clients from reading data before reading a header) +and invokes the format and compression layer operations +through registered function pointers. +In particular, the API layer drives the format-detection process: +When opening the archive, it reads an initial block of data +and offers it to each registered compression handler. +The one with the highest bid is initialized with the first block. +Similarly, the format handlers are polled to see which handler +is the best for each archive. +(Prior to 2.4.0, the format bidders were invoked for each +entry, but this design hindered error recovery.) +.SS I/O Layer and Client Callbacks +The read API goes to some lengths to be nice to clients. +As a result, there are few restrictions on the behavior of +the client callbacks. +.PP +The client read callback is expected to provide a block +of data on each call. +A zero-length return does indicate end of file, but otherwise +blocks may be as small as one byte or as large as the entire file. +In particular, blocks may be of different sizes. +.PP +The client skip callback returns the number of bytes actually +skipped, which may be much smaller than the skip requested. +The only requirement is that the skip not be larger. +In particular, clients are allowed to return zero for any +skip that they don't want to handle. +The skip callback must never be invoked with a negative value. +.PP +Keep in mind that not all clients are reading from disk: +clients reading from networks may provide different-sized +blocks on every request and cannot skip at all; +advanced clients may use +\fBmmap\fP(2) +to read the entire file into memory at once and return the +entire file to libarchive as a single block; +other clients may begin asynchronous I/O operations for the +next block on each request. +.SS Decompresssion Layer +The decompression layer not only handles decompression, +it also buffers data so that the format handlers see a +much nicer I/O model. +The decompression API is a two stage peek/consume model. +A read_ahead request specifies a minimum read amount; +the decompression layer must provide a pointer to at least +that much data. +If more data is immediately available, it should return more: +the format layer handles bulk data reads by asking for a minimum +of one byte and then copying as much data as is available. +.PP +A subsequent call to the +\fB\%consume\fP() +function advances the read pointer. +Note that data returned from a +\fB\%read_ahead\fP() +call is guaranteed to remain in place until +the next call to +\fB\%read_ahead\fP(). +Intervening calls to +\fB\%consume\fP() +should not cause the data to move. +.PP +Skip requests must always be handled exactly. +Decompression handlers that cannot seek forward should +not register a skip handler; +the API layer fills in a generic skip handler that reads and discards data. +.PP +A decompression handler has a specific lifecycle: +.RS 5 +.TP +Registration/Configuration +When the client invokes the public support function, +the decompression handler invokes the internal +\fB\%__archive_read_register_compression\fP() +function to provide bid and initialization functions. +This function returns +\fBNULL\fP +on error or else a pointer to a +\fBstruct\fP decompressor_t. +This structure contains a +\fIvoid\fP * config +slot that can be used for storing any customization information. +.TP +Bid +The bid function is invoked with a pointer and size of a block of data. +The decompressor can access its config data +through the +\fIdecompressor\fP +element of the +\fBarchive_read\fP +object. +The bid function is otherwise stateless. +In particular, it must not perform any I/O operations. +.PP +The value returned by the bid function indicates its suitability +for handling this data stream. +A bid of zero will ensure that this decompressor is never invoked. +Return zero if magic number checks fail. +Otherwise, your initial implementation should return the number of bits +actually checked. +For example, if you verify two full bytes and three bits of another +byte, bid 19. +Note that the initial block may be very short; +be careful to only inspect the data you are given. +(The current decompressors require two bytes for correct bidding.) +.TP +Initialize +The winning bidder will have its init function called. +This function should initialize the remaining slots of the +\fIstruct\fP decompressor_t +object pointed to by the +\fIdecompressor\fP +element of the +\fIarchive_read\fP +object. +In particular, it should allocate any working data it needs +in the +\fIdata\fP +slot of that structure. +The init function is called with the block of data that +was used for tasting. +At this point, the decompressor is responsible for all I/O +requests to the client callbacks. +The decompressor is free to read more data as and when +necessary. +.TP +Satisfy I/O requests +The format handler will invoke the +\fIread_ahead\fP, +\fIconsume\fP, +and +\fIskip\fP +functions as needed. +.TP +Finish +The finish method is called only once when the archive is closed. +It should release anything stored in the +\fIdata\fP +and +\fIconfig\fP +slots of the +\fIdecompressor\fP +object. +It should not invoke the client close callback. +.RE +.SS Format Layer +The read formats have a similar lifecycle to the decompression handlers: +.RS 5 +.TP +Registration +Allocate your private data and initialize your pointers. +.TP +Bid +Formats bid by invoking the +\fB\%read_ahead\fP() +decompression method but not calling the +\fB\%consume\fP() +method. +This allows each bidder to look ahead in the input stream. +Bidders should not look further ahead than necessary, as long +look aheads put pressure on the decompression layer to buffer +lots of data. +Most formats only require a few hundred bytes of look ahead; +look aheads of a few kilobytes are reasonable. +(The ISO9660 reader sometimes looks ahead by 48k, which +should be considered an upper limit.) +.TP +Read header +The header read is usually the most complex part of any format. +There are a few strategies worth mentioning: +For formats such as tar or cpio, reading and parsing the header is +straightforward since headers alternate with data. +For formats that store all header data at the beginning of the file, +the first header read request may have to read all headers into +memory and store that data, sorted by the location of the file +data. +Subsequent header read requests will skip forward to the +beginning of the file data and return the corresponding header. +.TP +Read Data +The read data interface supports sparse files; this requires that +each call return a block of data specifying the file offset and +size. +This may require you to carefully track the location so that you +can return accurate file offsets for each read. +Remember that the decompressor will return as much data as it has. +Generally, you will want to request one byte, +examine the return value to see how much data is available, and +possibly trim that to the amount you can use. +You should invoke consume for each block just before you return it. +.TP +Skip All Data +The skip data call should skip over all file data and trailing padding. +This is called automatically by the API layer just before each +header read. +It is also called in response to the client calling the public +\fB\%data_skip\fP() +function. +.TP +Cleanup +On cleanup, the format should release all of its allocated memory. +.RE +.SS API Layer +XXX to do XXX +.SH WRITE ARCHITECTURE +.ad l +The write API has a similar set of four layers: +an API layer, a format layer, a compression layer, and an I/O layer. +The registration here is much simpler because only +one format and one compression can be registered at a time. +.SS I/O Layer and Client Callbacks +XXX To be written XXX +.SS Compression Layer +XXX To be written XXX +.SS Format Layer +XXX To be written XXX +.SS API Layer +XXX To be written XXX +.SH WRITE_DISK ARCHITECTURE +.ad l +The write_disk API is intended to look just like the write API +to clients. +Since it does not handle multiple formats or compression, it +is not layered internally. +.SH GENERAL SERVICES +.ad l +The +\fB\%archive_read\fP, +\fB\%archive_write\fP, +and +\fB\%archive_write_disk\fP +objects all contain an initial +\fB\%archive\fP +object which provides common support for a set of standard services. +(Recall that ANSI/ISO C90 guarantees that you can cast freely between +a pointer to a structure and a pointer to the first element of that +structure.) +The +\fB\%archive\fP +object has a magic value that indicates which API this object +is associated with, +slots for storing error information, +and function pointers for virtualized API functions. +.SH MISCELLANEOUS NOTES +.ad l +Connecting existing archiving libraries into libarchive is generally +quite difficult. +In particular, many existing libraries strongly assume that you +are reading from a file; they seek forwards and backwards as necessary +to locate various pieces of information. +In contrast, libarchive never seeks backwards in its input, which +sometimes requires very different approaches. +.PP +For example, libarchive's ISO9660 support operates very differently +from most ISO9660 readers. +The libarchive support utilizes a work-queue design that +keeps a list of known entries sorted by their location in the input. +Whenever libarchive's ISO9660 implementation is asked for the next +header, checks this list to find the next item on the disk. +Directories are parsed when they are encountered and new +items are added to the list. +This design relies heavily on the ISO9660 image being optimized so that +directories always occur earlier on the disk than the files they +describe. +.PP +Depending on the specific format, such approaches may not be possible. +The ZIP format specification, for example, allows archivers to store +key information only at the end of the file. +In theory, it is possible to create ZIP archives that cannot +be read without seeking. +Fortunately, such archives are very rare, and libarchive can read +most ZIP archives, though it cannot always extract as much information +as a dedicated ZIP program. +.SH SEE ALSO +.ad l +\fBarchive\fP(3), +\fBarchive_entry\fP(3), +\fBarchive_read\fP(3), +\fBarchive_write\fP(3), +\fBarchive_write_disk\fP(3) +.SH HISTORY +.ad l +The +\fB\%libarchive\fP +library first appeared in +FreeBSD 5.3. +.SH AUTHORS +.ad l +-nosplit +The +\fB\%libarchive\fP +library was written by +Tim Kientzle \%<kientzle@acm.org.> +.SH BUGS +.ad l diff --git a/libarchive/libarchive-2.8.0/doc/man/mtree.5 b/libarchive/libarchive-2.8.0/doc/man/mtree.5 new file mode 100644 index 0000000..2cf2e3a --- /dev/null +++ b/libarchive/libarchive-2.8.0/doc/man/mtree.5 @@ -0,0 +1,282 @@ +.TH MTREE 5 "August 20, 2007" "" +.SH NAME +.ad l +\fB\%mtree\fP +\- format of mtree dir hierarchy files +.SH DESCRIPTION +.ad l +The +\fB\%mtree\fP +format is a textual format that describes a collection of filesystem objects. +Such files are typically used to create or verify directory hierarchies. +.SS General Format +An +\fB\%mtree\fP +file consists of a series of lines, each providing information +about a single filesystem object. +Leading whitespace is always ignored. +.PP +When encoding file or pathnames, any backslash character or +character outside of the 95 printable ASCII characters must be +encoded as a a backslash followed by three +octal digits. +When reading mtree files, any appearance of a backslash +followed by three octal digits should be converted into the +corresponding character. +.PP +Each line is interpreted independently as one of the following types: +.RS 5 +.TP +Signature +The first line of any mtree file must begin with +``#mtree''. +If a file contains any full path entries, the first line should +begin with +``#mtree v2.0'', +otherwise, the first line should begin with +``#mtree v1.0''. +.TP +Blank +Blank lines are ignored. +.TP +Comment +Lines beginning with +\fB#\fP +are ignored. +.TP +Special +Lines beginning with +\fB/\fP +are special commands that influence +the interpretation of later lines. +.TP +Relative +If the first whitespace-delimited word has no +\fB/\fP +characters, +it is the name of a file in the current directory. +Any relative entry that describes a directory changes the +current directory. +.TP +dot-dot +As a special case, a relative entry with the filename +\fI\& ..\fP +changes the current directory to the parent directory. +Options on dot-dot entries are always ignored. +.TP +Full +If the first whitespace-delimited word has a +\fB/\fP +character after +the first character, it is the pathname of a file relative to the +starting directory. +There can be multiple full entries describing the same file. +.RE +.PP +Some tools that process +\fB\%mtree\fP +files may require that multiple lines describing the same file +occur consecutively. +It is not permitted for the same file to be mentioned using +both a relative and a full file specification. +.SS Special commands +Two special commands are currently defined: +.RS 5 +.TP +\fB/set\fP +This command defines default values for one or more keywords. +It is followed on the same line by one or more whitespace-separated +keyword definitions. +These definitions apply to all following files that do not specify +a value for that keyword. +.TP +\fB/unset\fP +This command removes any default value set by a previous +\fB/set\fP +command. +It is followed on the same line by one or more keywords +separated by whitespace. +.RE +.SS Keywords +After the filename, a full or relative entry consists of zero +or more whitespace-separated keyword definitions. +Each such definition consists of a key from the following +list immediately followed by an '=' sign +and a value. +Software programs reading mtree files should warn about +unrecognized keywords. +.PP +Currently supported keywords are as follows: +.RS 5 +.TP +\fBcksum\fP +The checksum of the file using the default algorithm specified by +the +\fBcksum\fP(1) +utility. +.TP +\fBcontents\fP +The full pathname of a file that holds the contents of this file. +.TP +\fBflags\fP +The file flags as a symbolic name. +See +\fBchflags\fP(1) +for information on these names. +If no flags are to be set the string +``none'' +may be used to override the current default. +.TP +\fBgid\fP +The file group as a numeric value. +.TP +\fBgname\fP +The file group as a symbolic name. +.TP +\fBignore\fP +Ignore any file hierarchy below this file. +.TP +\fBlink\fP +The target of the symbolic link when type=link. +.TP +\fBmd5\fP +The MD5 message digest of the file. +.TP +\fBmd5digest\fP +A synonym for +\fBmd5\fP. +.TP +\fBmode\fP +The current file's permissions as a numeric (octal) or symbolic +value. +.TP +\fBnlink\fP +The number of hard links the file is expected to have. +.TP +\fBnochange\fP +Make sure this file or directory exists but otherwise ignore all attributes. +.TP +\fBripemd160digest\fP +The +Tn RIPEMD160 +message digest of the file. +.TP +\fBrmd160\fP +A synonym for +\fBripemd160digest\fP. +.TP +\fBrmd160digest\fP +A synonym for +\fBripemd160digest\fP. +.TP +\fBsha1\fP +The +Tn FIPS +160-1 +(``Tn SHA-1'') +message digest of the file. +.TP +\fBsha1digest\fP +A synonym for +\fBsha1\fP. +.TP +\fBsha256\fP +The +Tn FIPS +180-2 +(``Tn SHA-256'') +message digest of the file. +.TP +\fBsha256digest\fP +A synonym for +\fBsha256\fP. +.TP +\fBsize\fP +The size, in bytes, of the file. +.TP +\fBtime\fP +The last modification time of the file. +.TP +\fBtype\fP +The type of the file; may be set to any one of the following: +.PP +.RS 5 +.TP +\fBblock\fP +block special device +.TP +\fBchar\fP +character special device +.TP +\fBdir\fP +directory +.TP +\fBfifo\fP +fifo +.TP +\fBfile\fP +regular file +.TP +\fBlink\fP +symbolic link +.TP +\fBsocket\fP +socket +.RE +.TP +\fBuid\fP +The file owner as a numeric value. +.TP +\fBuname\fP +The file owner as a symbolic name. +.RE +.PP +.SH SEE ALSO +.ad l +\fBcksum\fP(1), +\fBfind\fP(1), +\fBmtree\fP(8) +.SH BUGS +.ad l +The +FreeBSD +implementation of mtree does not currently support +the +\fB\%mtree\fP +2.0 +format. +The requirement for a +``#mtree'' +signature line is new and not yet widely implemented. +.SH HISTORY +.ad l +The +\fB\%mtree\fP +utility appeared in +Bx 4.3 Reno. +The +Tn MD5 +digest capability was added in +FreeBSD 2.1, +in response to the widespread use of programs which can spoof +\fBcksum\fP(1). +The +Tn SHA-1 +and +Tn RIPEMD160 +digests were added in +FreeBSD 4.0, +as new attacks have demonstrated weaknesses in +Tn MD5. +The +Tn SHA-256 +digest was added in +FreeBSD 6.0. +Support for file flags was added in +FreeBSD 4.0, +and mostly comes from +NetBSD. +The +``full'' +entry format was added by +NetBSD. diff --git a/libarchive/libarchive-2.8.0/doc/man/tar.5 b/libarchive/libarchive-2.8.0/doc/man/tar.5 new file mode 100644 index 0000000..ab19958 --- /dev/null +++ b/libarchive/libarchive-2.8.0/doc/man/tar.5 @@ -0,0 +1,869 @@ +.TH tar 5 "December 27, 2009" "" +.SH NAME +.ad l +\fB\%tar\fP +\- format of tape archive files +.SH DESCRIPTION +.ad l +The +\fB\%tar\fP +archive format collects any number of files, directories, and other +file system objects (symbolic links, device nodes, etc.) into a single +stream of bytes. +The format was originally designed to be used with +tape drives that operate with fixed-size blocks, but is widely used as +a general packaging mechanism. +.SS General Format +A +\fB\%tar\fP +archive consists of a series of 512-byte records. +Each file system object requires a header record which stores basic metadata +(pathname, owner, permissions, etc.) and zero or more records containing any +file data. +The end of the archive is indicated by two records consisting +entirely of zero bytes. +.PP +For compatibility with tape drives that use fixed block sizes, +programs that read or write tar files always read or write a fixed +number of records with each I/O operation. +These +``blocks'' +are always a multiple of the record size. +The maximum block size supported by early +implementations was 10240 bytes or 20 records. +This is still the default for most implementations +although block sizes of 1MiB (2048 records) or larger are +commonly used with modern high-speed tape drives. +(Note: the terms +``block'' +and +``record'' +here are not entirely standard; this document follows the +convention established by John Gilmore in documenting +\fB\%pdtar\fP.) +.SS Old-Style Archive Format +The original tar archive format has been extended many times to +include additional information that various implementors found +necessary. +This section describes the variant implemented by the tar command +included in +At v7, +which seems to be the earliest widely-used version of the tar program. +.PP +The header record for an old-style +\fB\%tar\fP +archive consists of the following: +.RS 4 +.nf +struct header_old_tar { + char name[100]; + char mode[8]; + char uid[8]; + char gid[8]; + char size[12]; + char mtime[12]; + char checksum[8]; + char linkflag[1]; + char linkname[100]; + char pad[255]; +}; +.RE +All unused bytes in the header record are filled with nulls. +.RS 5 +.TP +\fIname\fP +Pathname, stored as a null-terminated string. +Early tar implementations only stored regular files (including +hardlinks to those files). +One common early convention used a trailing "/" character to indicate +a directory name, allowing directory permissions and owner information +to be archived and restored. +.TP +\fImode\fP +File mode, stored as an octal number in ASCII. +.TP +\fIuid\fP, \fIgid\fP +User id and group id of owner, as octal numbers in ASCII. +.TP +\fIsize\fP +Size of file, as octal number in ASCII. +For regular files only, this indicates the amount of data +that follows the header. +In particular, this field was ignored by early tar implementations +when extracting hardlinks. +Modern writers should always store a zero length for hardlink entries. +.TP +\fImtime\fP +Modification time of file, as an octal number in ASCII. +This indicates the number of seconds since the start of the epoch, +00:00:00 UTC January 1, 1970. +Note that negative values should be avoided +here, as they are handled inconsistently. +.TP +\fIchecksum\fP +Header checksum, stored as an octal number in ASCII. +To compute the checksum, set the checksum field to all spaces, +then sum all bytes in the header using unsigned arithmetic. +This field should be stored as six octal digits followed by a null and a space +character. +Note that many early implementations of tar used signed arithmetic +for the checksum field, which can cause interoperability problems +when transferring archives between systems. +Modern robust readers compute the checksum both ways and accept the +header if either computation matches. +.TP +\fIlinkflag\fP, \fIlinkname\fP +In order to preserve hardlinks and conserve tape, a file +with multiple links is only written to the archive the first +time it is encountered. +The next time it is encountered, the +\fIlinkflag\fP +is set to an ASCII +Sq 1 +and the +\fIlinkname\fP +field holds the first name under which this file appears. +(Note that regular files have a null value in the +\fIlinkflag\fP +field.) +.RE +.PP +Early tar implementations varied in how they terminated these fields. +The tar command in +At v7 +used the following conventions (this is also documented in early BSD manpages): +the pathname must be null-terminated; +the mode, uid, and gid fields must end in a space and a null byte; +the size and mtime fields must end in a space; +the checksum is terminated by a null and a space. +Early implementations filled the numeric fields with leading spaces. +This seems to have been common practice until the +IEEE Std 1003.1-1988 (``POSIX.1'') +standard was released. +For best portability, modern implementations should fill the numeric +fields with leading zeros. +.SS Pre-POSIX Archives +An early draft of +IEEE Std 1003.1-1988 (``POSIX.1'') +served as the basis for John Gilmore's +\fB\%pdtar\fP +program and many system implementations from the late 1980s +and early 1990s. +These archives generally follow the POSIX ustar +format described below with the following variations: +.RS 5 +.IP \(bu +The magic value is +``ustar\ \&'' +(note the following space). +The version field contains a space character followed by a null. +.IP \(bu +The numeric fields are generally filled with leading spaces +(not leading zeros as recommended in the final standard). +.IP \(bu +The prefix field is often not used, limiting pathnames to +the 100 characters of old-style archives. +.RE +.SS POSIX ustar Archives +IEEE Std 1003.1-1988 (``POSIX.1'') +defined a standard tar file format to be read and written +by compliant implementations of +\fBtar\fP(1). +This format is often called the +``ustar'' +format, after the magic value used +in the header. +(The name is an acronym for +``Unix Standard TAR''.) +It extends the historic format with new fields: +.RS 4 +.nf +struct header_posix_ustar { + char name[100]; + char mode[8]; + char uid[8]; + char gid[8]; + char size[12]; + char mtime[12]; + char checksum[8]; + char typeflag[1]; + char linkname[100]; + char magic[6]; + char version[2]; + char uname[32]; + char gname[32]; + char devmajor[8]; + char devminor[8]; + char prefix[155]; + char pad[12]; +}; +.RE +.RS 5 +.TP +\fItypeflag\fP +Type of entry. +POSIX extended the earlier +\fIlinkflag\fP +field with several new type values: +.RS 5 +.TP +``0'' +Regular file. +NUL should be treated as a synonym, for compatibility purposes. +.TP +``1'' +Hard link. +.TP +``2'' +Symbolic link. +.TP +``3'' +Character device node. +.TP +``4'' +Block device node. +.TP +``5'' +Directory. +.TP +``6'' +FIFO node. +.TP +``7'' +Reserved. +.TP +Other +A POSIX-compliant implementation must treat any unrecognized typeflag value +as a regular file. +In particular, writers should ensure that all entries +have a valid filename so that they can be restored by readers that do not +support the corresponding extension. +Uppercase letters "A" through "Z" are reserved for custom extensions. +Note that sockets and whiteout entries are not archivable. +.RE +It is worth noting that the +\fIsize\fP +field, in particular, has different meanings depending on the type. +For regular files, of course, it indicates the amount of data +following the header. +For directories, it may be used to indicate the total size of all +files in the directory, for use by operating systems that pre-allocate +directory space. +For all other types, it should be set to zero by writers and ignored +by readers. +.TP +\fImagic\fP +Contains the magic value +``ustar'' +followed by a NUL byte to indicate that this is a POSIX standard archive. +Full compliance requires the uname and gname fields be properly set. +.TP +\fIversion\fP +Version. +This should be +``00'' +(two copies of the ASCII digit zero) for POSIX standard archives. +.TP +\fIuname\fP, \fIgname\fP +User and group names, as null-terminated ASCII strings. +These should be used in preference to the uid/gid values +when they are set and the corresponding names exist on +the system. +.TP +\fIdevmajor\fP, \fIdevminor\fP +Major and minor numbers for character device or block device entry. +.TP +\fIname\fP, \fIprefix\fP +If the pathname is too long to fit in the 100 bytes provided by the standard +format, it can be split at any +\fI/\fP +character with the first portion going into the prefix field. +If the prefix field is not empty, the reader will prepend +the prefix value and a +\fI/\fP +character to the regular name field to obtain the full pathname. +The standard does not require a trailing +\fI/\fP +character on directory names, though most implementations still +include this for compatibility reasons. +.RE +.PP +Note that all unused bytes must be set to +.BR NUL. +.PP +Field termination is specified slightly differently by POSIX +than by previous implementations. +The +\fImagic\fP, +\fIuname\fP, +and +\fIgname\fP +fields must have a trailing +.BR NUL. +The +\fIpathname\fP, +\fIlinkname\fP, +and +\fIprefix\fP +fields must have a trailing +.BR NUL +unless they fill the entire field. +(In particular, it is possible to store a 256-character pathname if it +happens to have a +\fI/\fP +as the 156th character.) +POSIX requires numeric fields to be zero-padded in the front, and requires +them to be terminated with either space or +.BR NUL +characters. +.PP +Currently, most tar implementations comply with the ustar +format, occasionally extending it by adding new fields to the +blank area at the end of the header record. +.SS Pax Interchange Format +There are many attributes that cannot be portably stored in a +POSIX ustar archive. +IEEE Std 1003.1-2001 (``POSIX.1'') +defined a +``pax interchange format'' +that uses two new types of entries to hold text-formatted +metadata that applies to following entries. +Note that a pax interchange format archive is a ustar archive in every +respect. +The new data is stored in ustar-compatible archive entries that use the +``x'' +or +``g'' +typeflag. +In particular, older implementations that do not fully support these +extensions will extract the metadata into regular files, where the +metadata can be examined as necessary. +.PP +An entry in a pax interchange format archive consists of one or +two standard ustar entries, each with its own header and data. +The first optional entry stores the extended attributes +for the following entry. +This optional first entry has an "x" typeflag and a size field that +indicates the total size of the extended attributes. +The extended attributes themselves are stored as a series of text-format +lines encoded in the portable UTF-8 encoding. +Each line consists of a decimal number, a space, a key string, an equals +sign, a value string, and a new line. +The decimal number indicates the length of the entire line, including the +initial length field and the trailing newline. +An example of such a field is: +.RS 4 +25 ctime=1084839148.1212\en +.RE +Keys in all lowercase are standard keys. +Vendors can add their own keys by prefixing them with an all uppercase +vendor name and a period. +Note that, unlike the historic header, numeric values are stored using +decimal, not octal. +A description of some common keys follows: +.RS 5 +.TP +\fBatime\fP, \fBctime\fP, \fBmtime\fP +File access, inode change, and modification times. +These fields can be negative or include a decimal point and a fractional value. +.TP +\fBuname\fP, \fBuid\fP, \fBgname\fP, \fBgid\fP +User name, group name, and numeric UID and GID values. +The user name and group name stored here are encoded in UTF8 +and can thus include non-ASCII characters. +The UID and GID fields can be of arbitrary length. +.TP +\fBlinkpath\fP +The full path of the linked-to file. +Note that this is encoded in UTF8 and can thus include non-ASCII characters. +.TP +\fBpath\fP +The full pathname of the entry. +Note that this is encoded in UTF8 and can thus include non-ASCII characters. +.TP +\fBrealtime.*\fP, \fBsecurity.*\fP +These keys are reserved and may be used for future standardization. +.TP +\fBsize\fP +The size of the file. +Note that there is no length limit on this field, allowing conforming +archives to store files much larger than the historic 8GB limit. +.TP +\fBSCHILY.*\fP +Vendor-specific attributes used by Joerg Schilling's +\fB\%star\fP +implementation. +.TP +\fBSCHILY.acl.access\fP, \fBSCHILY.acl.default\fP +Stores the access and default ACLs as textual strings in a format +that is an extension of the format specified by POSIX.1e draft 17. +In particular, each user or group access specification can include a fourth +colon-separated field with the numeric UID or GID. +This allows ACLs to be restored on systems that may not have complete +user or group information available (such as when NIS/YP or LDAP services +are temporarily unavailable). +.TP +\fBSCHILY.devminor\fP, \fBSCHILY.devmajor\fP +The full minor and major numbers for device nodes. +.TP +\fBSCHILY.fflags\fP +The file flags. +.TP +\fBSCHILY.realsize\fP +The full size of the file on disk. +XXX explain? XXX +.TP +\fBSCHILY.dev,\fP \fBSCHILY.ino\fP, \fBSCHILY.nlinks\fP +The device number, inode number, and link count for the entry. +In particular, note that a pax interchange format archive using Joerg +Schilling's +\fBSCHILY.*\fP +extensions can store all of the data from +\fIstruct\fP stat. +.TP +\fBLIBARCHIVE.xattr.\fP \fInamespace\fP.\fIkey\fP +Libarchive stores POSIX.1e-style extended attributes using +keys of this form. +The +\fIkey\fP +value is URL-encoded: +All non-ASCII characters and the two special characters +``='' +and +``%'' +are encoded as +``%'' +followed by two uppercase hexadecimal digits. +The value of this key is the extended attribute value +encoded in base 64. +XXX Detail the base-64 format here XXX +.TP +\fBVENDOR.*\fP +XXX document other vendor-specific extensions XXX +.RE +.PP +Any values stored in an extended attribute override the corresponding +values in the regular tar header. +Note that compliant readers should ignore the regular fields when they +are overridden. +This is important, as existing archivers are known to store non-compliant +values in the standard header fields in this situation. +There are no limits on length for any of these fields. +In particular, numeric fields can be arbitrarily large. +All text fields are encoded in UTF8. +Compliant writers should store only portable 7-bit ASCII characters in +the standard ustar header and use extended +attributes whenever a text value contains non-ASCII characters. +.PP +In addition to the +\fBx\fP +entry described above, the pax interchange format +also supports a +\fBg\fP +entry. +The +\fBg\fP +entry is identical in format, but specifies attributes that serve as +defaults for all subsequent archive entries. +The +\fBg\fP +entry is not widely used. +.PP +Besides the new +\fBx\fP +and +\fBg\fP +entries, the pax interchange format has a few other minor variations +from the earlier ustar format. +The most troubling one is that hardlinks are permitted to have +data following them. +This allows readers to restore any hardlink to a file without +having to rewind the archive to find an earlier entry. +However, it creates complications for robust readers, as it is no longer +clear whether or not they should ignore the size field for hardlink entries. +.SS GNU Tar Archives +The GNU tar program started with a pre-POSIX format similar to that +described earlier and has extended it using several different mechanisms: +It added new fields to the empty space in the header (some of which was later +used by POSIX for conflicting purposes); +it allowed the header to be continued over multiple records; +and it defined new entries that modify following entries +(similar in principle to the +\fBx\fP +entry described above, but each GNU special entry is single-purpose, +unlike the general-purpose +\fBx\fP +entry). +As a result, GNU tar archives are not POSIX compatible, although +more lenient POSIX-compliant readers can successfully extract most +GNU tar archives. +.RS 4 +.nf +struct header_gnu_tar { + char name[100]; + char mode[8]; + char uid[8]; + char gid[8]; + char size[12]; + char mtime[12]; + char checksum[8]; + char typeflag[1]; + char linkname[100]; + char magic[6]; + char version[2]; + char uname[32]; + char gname[32]; + char devmajor[8]; + char devminor[8]; + char atime[12]; + char ctime[12]; + char offset[12]; + char longnames[4]; + char unused[1]; + struct { + char offset[12]; + char numbytes[12]; + } sparse[4]; + char isextended[1]; + char realsize[12]; + char pad[17]; +}; +.RE +.RS 5 +.TP +\fItypeflag\fP +GNU tar uses the following special entry types, in addition to +those defined by POSIX: +.RS 5 +.TP +7 +GNU tar treats type "7" records identically to type "0" records, +except on one obscure RTOS where they are used to indicate the +pre-allocation of a contiguous file on disk. +.TP +D +This indicates a directory entry. +Unlike the POSIX-standard "5" +typeflag, the header is followed by data records listing the names +of files in this directory. +Each name is preceded by an ASCII "Y" +if the file is stored in this archive or "N" if the file is not +stored in this archive. +Each name is terminated with a null, and +an extra null marks the end of the name list. +The purpose of this +entry is to support incremental backups; a program restoring from +such an archive may wish to delete files on disk that did not exist +in the directory when the archive was made. +.PP +Note that the "D" typeflag specifically violates POSIX, which requires +that unrecognized typeflags be restored as normal files. +In this case, restoring the "D" entry as a file could interfere +with subsequent creation of the like-named directory. +.TP +K +The data for this entry is a long linkname for the following regular entry. +.TP +L +The data for this entry is a long pathname for the following regular entry. +.TP +M +This is a continuation of the last file on the previous volume. +GNU multi-volume archives guarantee that each volume begins with a valid +entry header. +To ensure this, a file may be split, with part stored at the end of one volume, +and part stored at the beginning of the next volume. +The "M" typeflag indicates that this entry continues an existing file. +Such entries can only occur as the first or second entry +in an archive (the latter only if the first entry is a volume label). +The +\fIsize\fP +field specifies the size of this entry. +The +\fIoffset\fP +field at bytes 369-380 specifies the offset where this file fragment +begins. +The +\fIrealsize\fP +field specifies the total size of the file (which must equal +\fIsize\fP +plus +\fIoffset\fP). +When extracting, GNU tar checks that the header file name is the one it is +expecting, that the header offset is in the correct sequence, and that +the sum of offset and size is equal to realsize. +.TP +N +Type "N" records are no longer generated by GNU tar. +They contained a +list of files to be renamed or symlinked after extraction; this was +originally used to support long names. +The contents of this record +are a text description of the operations to be done, in the form +``Rename %s to %s\en'' +or +``Symlink %s to %s\en ;'' +in either case, both +filenames are escaped using K&R C syntax. +Due to security concerns, "N" records are now generally ignored +when reading archives. +.TP +S +This is a +``sparse'' +regular file. +Sparse files are stored as a series of fragments. +The header contains a list of fragment offset/length pairs. +If more than four such entries are required, the header is +extended as necessary with +``extra'' +header extensions (an older format that is no longer used), or +``sparse'' +extensions. +.TP +V +The +\fIname\fP +field should be interpreted as a tape/volume header name. +This entry should generally be ignored on extraction. +.RE +.TP +\fImagic\fP +The magic field holds the five characters +``ustar'' +followed by a space. +Note that POSIX ustar archives have a trailing null. +.TP +\fIversion\fP +The version field holds a space character followed by a null. +Note that POSIX ustar archives use two copies of the ASCII digit +``0''. +.TP +\fIatime\fP, \fIctime\fP +The time the file was last accessed and the time of +last change of file information, stored in octal as with +\fImtime\fP. +.TP +\fIlongnames\fP +This field is apparently no longer used. +.TP +Sparse \fIoffset\fP / \fInumbytes\fP +Each such structure specifies a single fragment of a sparse +file. +The two fields store values as octal numbers. +The fragments are each padded to a multiple of 512 bytes +in the archive. +On extraction, the list of fragments is collected from the +header (including any extension headers), and the data +is then read and written to the file at appropriate offsets. +.TP +\fIisextended\fP +If this is set to non-zero, the header will be followed by additional +``sparse header'' +records. +Each such record contains information about as many as 21 additional +sparse blocks as shown here: +.RS 4 +.nf +struct gnu_sparse_header { + struct { + char offset[12]; + char numbytes[12]; + } sparse[21]; + char isextended[1]; + char padding[7]; +}; +.RE +.TP +\fIrealsize\fP +A binary representation of the file's complete size, with a much larger range +than the POSIX file size. +In particular, with +\fBM\fP +type files, the current entry is only a portion of the file. +In that case, the POSIX size field will indicate the size of this +entry; the +\fIrealsize\fP +field will indicate the total size of the file. +.RE +.SS GNU tar pax archives +GNU tar 1.14 (XXX check this XXX) and later will write +pax interchange format archives when you specify the +\fB\--posix\fP +flag. +This format uses custom keywords to store sparse file information. +There have been three iterations of this support, referred to +as +``0.0'', +``0.1'', +and +``1.0''. +.RS 5 +.TP +\fBGNU.sparse.numblocks\fP, \fBGNU.sparse.offset\fP, \fBGNU.sparse.numbytes\fP, \fBGNU.sparse.size\fP +The +``0.0'' +format used an initial +\fBGNU.sparse.numblocks\fP +attribute to indicate the number of blocks in the file, a pair of +\fBGNU.sparse.offset\fP +and +\fBGNU.sparse.numbytes\fP +to indicate the offset and size of each block, +and a single +\fBGNU.sparse.size\fP +to indicate the full size of the file. +This is not the same as the size in the tar header because the +latter value does not include the size of any holes. +This format required that the order of attributes be preserved and +relied on readers accepting multiple appearances of the same attribute +names, which is not officially permitted by the standards. +.TP +\fBGNU.sparse.map\fP +The +``0.1'' +format used a single attribute that stored a comma-separated +list of decimal numbers. +Each pair of numbers indicated the offset and size, respectively, +of a block of data. +This does not work well if the archive is extracted by an archiver +that does not recognize this extension, since many pax implementations +simply discard unrecognized attributes. +.TP +\fBGNU.sparse.major\fP, \fBGNU.sparse.minor\fP, \fBGNU.sparse.name\fP, \fBGNU.sparse.realsize\fP +The +``1.0'' +format stores the sparse block map in one or more 512-byte blocks +prepended to the file data in the entry body. +The pax attributes indicate the existence of this map +(via the +\fBGNU.sparse.major\fP +and +\fBGNU.sparse.minor\fP +fields) +and the full size of the file. +The +\fBGNU.sparse.name\fP +holds the true name of the file. +To avoid confusion, the name stored in the regular tar header +is a modified name so that extraction errors will be apparent +to users. +.RE +.SS Solaris Tar +XXX More Details Needed XXX +.PP +Solaris tar (beginning with SunOS XXX 5.7 ?? XXX) supports an +``extended'' +format that is fundamentally similar to pax interchange format, +with the following differences: +.RS 5 +.IP \(bu +Extended attributes are stored in an entry whose type is +\fBX\fP, +not +\fBx\fP, +as used by pax interchange format. +The detailed format of this entry appears to be the same +as detailed above for the +\fBx\fP +entry. +.IP \(bu +An additional +\fBA\fP +entry is used to store an ACL for the following regular entry. +The body of this entry contains a seven-digit octal number +followed by a zero byte, followed by the +textual ACL description. +The octal value is the number of ACL entries +plus a constant that indicates the ACL type: 01000000 +for POSIX.1e ACLs and 03000000 for NFSv4 ACLs. +.RE +.SS AIX Tar +XXX More details needed XXX +.SS Mac OS X Tar +The tar distributed with Apple's Mac OS X stores most regular files +as two separate entries in the tar archive. +The two entries have the same name except that the first +one has +``._'' +added to the beginning of the name. +This first entry stores the +``resource fork'' +with additional attributes for the file. +The Mac OS X +\fB\%CopyFile\fP() +API is used to separate a file on disk into separate +resource and data streams and to reassemble those separate +streams when the file is restored to disk. +.SS Other Extensions +One obvious extension to increase the size of files is to +eliminate the terminating characters from the various +numeric fields. +For example, the standard only allows the size field to contain +11 octal digits, reserving the twelfth byte for a trailing +NUL character. +Allowing 12 octal digits allows file sizes up to 64 GB. +.PP +Another extension, utilized by GNU tar, star, and other newer +\fB\%tar\fP +implementations, permits binary numbers in the standard numeric fields. +This is flagged by setting the high bit of the first byte. +This permits 95-bit values for the length and time fields +and 63-bit values for the uid, gid, and device numbers. +GNU tar supports this extension for the +length, mtime, ctime, and atime fields. +Joerg Schilling's star program supports this extension for +all numeric fields. +Note that this extension is largely obsoleted by the extended attribute +record provided by the pax interchange format. +.PP +Another early GNU extension allowed base-64 values rather than octal. +This extension was short-lived and is no longer supported by any +implementation. +.SH SEE ALSO +.ad l +\fBar\fP(1), +\fBpax\fP(1), +\fBtar\fP(1) +.SH STANDARDS +.ad l +The +\fB\%tar\fP +utility is no longer a part of POSIX or the Single Unix Standard. +It last appeared in +Version 2 of the Single UNIX Specification (``SUSv2''). +It has been supplanted in subsequent standards by +\fBpax\fP(1). +The ustar format is currently part of the specification for the +\fBpax\fP(1) +utility. +The pax interchange file format is new with +IEEE Std 1003.1-2001 (``POSIX.1''). +.SH HISTORY +.ad l +A +\fB\%tar\fP +command appeared in Seventh Edition Unix, which was released in January, 1979. +It replaced the +\fB\%tp\fP +program from Fourth Edition Unix which in turn replaced the +\fB\%tap\fP +program from First Edition Unix. +John Gilmore's +\fB\%pdtar\fP +public-domain implementation (circa 1987) was highly influential +and formed the basis of +\fB\%GNU\fP tar +(circa 1988). +Joerg Shilling's +\fB\%star\fP +archiver is another open-source (GPL) archiver (originally developed +circa 1985) which features complete support for pax interchange +format. +.PP +This documentation was written as part of the +\fB\%libarchive\fP +and +\fB\%bsdtar\fP +project by +Tim Kientzle \%<kientzle@FreeBSD.org.> |