diff options
Diffstat (limited to 'libarchive/libarchive-2.5.5/doc/man')
| -rw-r--r-- | libarchive/libarchive-2.5.5/doc/man/Makefile | 43 | ||||
| -rw-r--r-- | libarchive/libarchive-2.5.5/doc/man/archive_entry.3 | 695 | ||||
| -rw-r--r-- | libarchive/libarchive-2.5.5/doc/man/archive_read.3 | 878 | ||||
| -rw-r--r-- | libarchive/libarchive-2.5.5/doc/man/archive_util.3 | 206 | ||||
| -rw-r--r-- | libarchive/libarchive-2.5.5/doc/man/archive_write.3 | 815 | ||||
| -rw-r--r-- | libarchive/libarchive-2.5.5/doc/man/archive_write_disk.3 | 476 | ||||
| -rw-r--r-- | libarchive/libarchive-2.5.5/doc/man/bsdcpio.1 | 370 | ||||
| -rw-r--r-- | libarchive/libarchive-2.5.5/doc/man/bsdtar.1 | 856 | ||||
| -rw-r--r-- | libarchive/libarchive-2.5.5/doc/man/cpio.5 | 301 | ||||
| -rw-r--r-- | libarchive/libarchive-2.5.5/doc/man/libarchive-formats.5 | 247 | ||||
| -rw-r--r-- | libarchive/libarchive-2.5.5/doc/man/libarchive.3 | 379 | ||||
| -rw-r--r-- | libarchive/libarchive-2.5.5/doc/man/libarchive_internals.3 | 358 | ||||
| -rw-r--r-- | libarchive/libarchive-2.5.5/doc/man/mtree.5 | 263 | ||||
| -rw-r--r-- | libarchive/libarchive-2.5.5/doc/man/tar.5 | 725 |
14 files changed, 6612 insertions, 0 deletions
diff --git a/libarchive/libarchive-2.5.5/doc/man/Makefile b/libarchive/libarchive-2.5.5/doc/man/Makefile new file mode 100644 index 0000000..c33aac4 --- /dev/null +++ b/libarchive/libarchive-2.5.5/doc/man/Makefile @@ -0,0 +1,43 @@ + +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_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_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.5.5/doc/man/archive_entry.3 b/libarchive/libarchive-2.5.5/doc/man/archive_entry.3 new file mode 100644 index 0000000..994b474 --- /dev/null +++ b/libarchive/libarchive-2.5.5/doc/man/archive_entry.3 @@ -0,0 +1,695 @@ +.TH archive_entry 3 "May 12, 2008" "" +.SH NAME +\fBarchive_entry_acl_add_entry\fP, +\fBarchive_entry_acl_add_entry_w\fP, +\fBarchive_entry_acl_clear\fP, +\fBarchive_entry_acl_count\fP, +\fBarchive_entry_acl_next\fP, +\fBarchive_entry_acl_next_w\fP, +\fBarchive_entry_acl_reset\fP, +\fBarchive_entry_acl_text_w\fP, +\fBarchive_entry_atime\fP, +\fBarchive_entry_atime_nsec\fP, +\fBarchive_entry_clear\fP, +\fBarchive_entry_clone\fP, +\fBarchive_entry_copy_fflags_text\fP, +\fBarchive_entry_copy_fflags_text_w\fP, +\fBarchive_entry_copy_gname\fP, +\fBarchive_entry_copy_gname_w\fP, +\fBarchive_entry_copy_hardlink\fP, +\fBarchive_entry_copy_hardlink_w\fP, +\fBarchive_entry_copy_link\fP, +\fBarchive_entry_copy_link_w\fP, +\fBarchive_entry_copy_pathname_w\fP, +\fBarchive_entry_copy_sourcepath\fP, +\fBarchive_entry_copy_stat\fP, +\fBarchive_entry_copy_symlink\fP, +\fBarchive_entry_copy_symlink_w\fP, +\fBarchive_entry_copy_uname\fP, +\fBarchive_entry_copy_uname_w\fP, +\fBarchive_entry_dev\fP, +\fBarchive_entry_devmajor\fP, +\fBarchive_entry_devminor\fP, +\fBarchive_entry_filetype\fP, +\fBarchive_entry_fflags\fP, +\fBarchive_entry_fflags_text\fP, +\fBarchive_entry_free\fP, +\fBarchive_entry_gid\fP, +\fBarchive_entry_gname\fP, +\fBarchive_entry_hardlink\fP, +\fBarchive_entry_ino\fP, +\fBarchive_entry_mode\fP, +\fBarchive_entry_mtime\fP, +\fBarchive_entry_mtime_nsec\fP, +\fBarchive_entry_nlink\fP, +\fBarchive_entry_new\fP, +\fBarchive_entry_pathname\fP, +\fBarchive_entry_pathname_w\fP, +\fBarchive_entry_rdev\fP, +\fBarchive_entry_rdevmajor\fP, +\fBarchive_entry_rdevminor\fP, +\fBarchive_entry_set_atime\fP, +\fBarchive_entry_set_ctime\fP, +\fBarchive_entry_set_dev\fP, +\fBarchive_entry_set_devmajor\fP, +\fBarchive_entry_set_devminor\fP, +\fBarchive_entry_set_filetype\fP, +\fBarchive_entry_set_fflags\fP, +\fBarchive_entry_set_gid\fP, +\fBarchive_entry_set_gname\fP, +\fBarchive_entry_set_hardlink\fP, +\fBarchive_entry_set_link\fP, +\fBarchive_entry_set_mode\fP, +\fBarchive_entry_set_mtime\fP, +\fBarchive_entry_set_pathname\fP, +\fBarchive_entry_set_rdevmajor\fP, +\fBarchive_entry_set_rdevminor\fP, +\fBarchive_entry_set_size\fP, +\fBarchive_entry_set_symlink\fP, +\fBarchive_entry_set_uid\fP, +\fBarchive_entry_set_uname\fP, +\fBarchive_entry_size\fP, +\fBarchive_entry_sourcepath\fP, +\fBarchive_entry_stat\fP, +\fBarchive_entry_symlink\fP, +\fBarchive_entry_uid\fP, +\fBarchive_entry_uname\fP +\- functions for manipulating archive entry descriptions +.SH SYNOPSIS +\fB#include <archive_entry.h>\fP +.br +\fIvoid\fP +.RE +Fo archive_entry_acl_add_entry +Fa "struct archive_entry *" +Fa "int type" +Fa "int permset" +Fa "int tag" +Fa "int qual" +Fa "const char *name" +Fc +\fIvoid\fP +.RE +Fo archive_entry_acl_add_entry_w +Fa "struct archive_entry *" +Fa "int type" +Fa "int permset" +Fa "int tag" +Fa "int qual" +Fa "const wchar_t *name" +Fc +\fIvoid\fP +.RE +.nh +\fBarchive_entry_acl_clear\fP +.hy +("struct archive_entry *"); +\fIint\fP +.RE +.nh +\fBarchive_entry_acl_count\fP +.hy +("struct archive_entry *" "int type"); +\fIint\fP +.RE +Fo archive_entry_acl_next +Fa "struct archive_entry *" +Fa "int want_type" +Fa "int *type" +Fa "int *permset" +Fa "int *tag" +Fa "int *qual" +Fa "const char **name" +Fc +\fIint\fP +.RE +Fo archive_entry_acl_next_w +Fa "struct archive_entry *" +Fa "int want_type" +Fa "int *type" +Fa "int *permset" +Fa "int *tag" +Fa "int *qual" +Fa "const wchar_t **name" +Fc +\fIint\fP +.RE +.nh +\fBarchive_entry_acl_reset\fP +.hy +("struct archive_entry *" "int want_type"); +\fIconst wchar_t *\fP +.RE +.nh +\fBarchive_entry_acl_text_w\fP +.hy +("struct archive_entry *" "int flags"); +\fItime_t\fP +.RE +.nh +\fBarchive_entry_atime\fP +.hy +("struct archive_entry *"); +\fIlong\fP +.RE +.nh +\fBarchive_entry_atime_nsec\fP +.hy +("struct archive_entry *"); +\fI"struct archive_entry *"\fP +.RE +.nh +\fBarchive_entry_clear\fP +.hy +("struct archive_entry *"); +\fIstruct archive_entry *\fP +.RE +.nh +\fBarchive_entry_clone\fP +.hy +("struct archive_entry *"); +\fIconst char * *\fP +.RE +.nh +\fBarchive_entry_copy_fflags_text_w\fP +.hy +("struct archive_entry *" "const char *"); +\fIconst wchar_t *\fP +.RE +.nh +\fBarchive_entry_copy_fflags_text_w\fP +.hy +("struct archive_entry *" "const wchar_t *"); +\fIvoid\fP +.RE +.nh +\fBarchive_entry_copy_gname\fP +.hy +("struct archive_entry *" "const char *"); +\fIvoid\fP +.RE +.nh +\fBarchive_entry_copy_gname_w\fP +.hy +("struct archive_entry *" "const wchar_t *"); +\fIvoid\fP +.RE +.nh +\fBarchive_entry_copy_hardlink\fP +.hy +("struct archive_entry *" "const char *"); +\fIvoid\fP +.RE +.nh +\fBarchive_entry_copy_hardlink_w\fP +.hy +("struct archive_entry *" "const wchar_t *"); +\fIvoid\fP +.RE +.nh +\fBarchive_entry_copy_sourcepath\fP +.hy +("struct archive_entry *" "const char *"); +\fIvoid\fP +.RE +.nh +\fBarchive_entry_copy_pathname_w\fP +.hy +("struct archive_entry *" "const wchar_t *"); +\fIvoid\fP +.RE +.nh +\fBarchive_entry_copy_stat\fP +.hy +("struct archive_entry *" "const struct stat *"); +\fIvoid\fP +.RE +.nh +\fBarchive_entry_copy_symlink\fP +.hy +("struct archive_entry *" "const char *"); +\fIvoid\fP +.RE +.nh +\fBarchive_entry_copy_symlink_w\fP +.hy +("struct archive_entry *" "const wchar_t *"); +\fIvoid\fP +.RE +.nh +\fBarchive_entry_copy_uname\fP +.hy +("struct archive_entry *" "const char *"); +\fIvoid\fP +.RE +.nh +\fBarchive_entry_copy_uname_w\fP +.hy +("struct archive_entry *" "const wchar_t *"); +\fIdev_t\fP +.RE +.nh +\fBarchive_entry_dev\fP +.hy +("struct archive_entry *"); +\fIdev_t\fP +.RE +.nh +\fBarchive_entry_devmajor\fP +.hy +("struct archive_entry *"); +\fIdev_t\fP +.RE +.nh +\fBarchive_entry_devminor\fP +.hy +("struct archive_entry *"); +\fImode_t\fP +.RE +.nh +\fBarchive_entry_filetype\fP +.hy +("struct archive_entry *"); +\fIvoid\fP +.RE +Fo archive_entry_fflags +Fa "struct archive_entry *" +Fa "unsigned long *set" +Fa "unsigned long *clear" +Fc +\fIconst char *\fP +.RE +.nh +\fBarchive_entry_fflags_text\fP +.hy +("struct archive_entry *"); +\fIvoid\fP +.RE +.nh +\fBarchive_entry_free\fP +.hy +("struct archive_entry *"); +\fIconst char *\fP +.RE +.nh +\fBarchive_entry_gname\fP +.hy +("struct archive_entry *"); +\fIconst char *\fP +.RE +.nh +\fBarchive_entry_hardlink\fP +.hy +("struct archive_entry *"); +\fIino_t\fP +.RE +.nh +\fBarchive_entry_ino\fP +.hy +("struct archive_entry *"); +\fImode_t\fP +.RE +.nh +\fBarchive_entry_mode\fP +.hy +("struct archive_entry *"); +\fItime_t\fP +.RE +.nh +\fBarchive_entry_mtime\fP +.hy +("struct archive_entry *"); +\fIlong\fP +.RE +.nh +\fBarchive_entry_mtime_nsec\fP +.hy +("struct archive_entry *"); +\fIunsigned int\fP +.RE +.nh +\fBarchive_entry_nlink\fP +.hy +("struct archive_entry *"); +\fIstruct archive_entry *\fP +.RE +.nh +\fBarchive_entry_new\fP +.hy +("void"); +\fIconst char *\fP +.RE +.nh +\fBarchive_entry_pathname\fP +.hy +("struct archive_entry *"); +\fIconst wchar_t *\fP +.RE +.nh +\fBarchive_entry_pathname_w\fP +.hy +("struct archive_entry *"); +\fIdev_t\fP +.RE +.nh +\fBarchive_entry_rdev\fP +.hy +("struct archive_entry *"); +\fIdev_t\fP +.RE +.nh +\fBarchive_entry_rdevmajor\fP +.hy +("struct archive_entry *"); +\fIdev_t\fP +.RE +.nh +\fBarchive_entry_rdevminor\fP +.hy +("struct archive_entry *"); +\fIvoid\fP +.RE +.nh +\fBarchive_entry_set_dev\fP +.hy +("struct archive_entry *" "dev_t"); +\fIvoid\fP +.RE +.nh +\fBarchive_entry_set_devmajor\fP +.hy +("struct archive_entry *" "dev_t"); +\fIvoid\fP +.RE +.nh +\fBarchive_entry_set_devminor\fP +.hy +("struct archive_entry *" "dev_t"); +\fIvoid\fP +.RE +.nh +\fBarchive_entry_set_filetype\fP +.hy +("struct archive_entry *" "unsigned int"); +\fIvoid\fP +.RE +Fo archive_entry_set_fflags +Fa "struct archive_entry *" +Fa "unsigned long set" +Fa "unsigned long clear" +Fc +\fIvoid\fP +.RE +.nh +\fBarchive_entry_set_gid\fP +.hy +("struct archive_entry *" "gid_t"); +\fIvoid\fP +.RE +.nh +\fBarchive_entry_set_gname\fP +.hy +("struct archive_entry *" "const char *"); +\fIvoid\fP +.RE +.nh +\fBarchive_entry_set_hardlink\fP +.hy +("struct archive_entry *" "const char *"); +\fIvoid\fP +.RE +.nh +\fBarchive_entry_set_ino\fP +.hy +("struct archive_entry *" "unsigned long"); +\fIvoid\fP +.RE +.nh +\fBarchive_entry_set_link\fP +.hy +("struct archive_entry *" "const char *"); +\fIvoid\fP +.RE +.nh +\fBarchive_entry_set_mode\fP +.hy +("struct archive_entry *" "mode_t"); +\fIvoid\fP +.RE +.nh +\fBarchive_entry_set_mtime\fP +.hy +("struct archive_entry *" "time_t" "long nanos"); +\fIvoid\fP +.RE +.nh +\fBarchive_entry_set_nlink\fP +.hy +("struct archive_entry *" "unsigned int"); +\fIvoid\fP +.RE +.nh +\fBarchive_entry_set_pathname\fP +.hy +("struct archive_entry *" "const char *"); +\fIvoid\fP +.RE +.nh +\fBarchive_entry_set_rdev\fP +.hy +("struct archive_entry *" "dev_t"); +\fIvoid\fP +.RE +.nh +\fBarchive_entry_set_rdevmajor\fP +.hy +("struct archive_entry *" "dev_t"); +\fIvoid\fP +.RE +.nh +\fBarchive_entry_set_rdevminor\fP +.hy +("struct archive_entry *" "dev_t"); +\fIvoid\fP +.RE +.nh +\fBarchive_entry_set_size\fP +.hy +("struct archive_entry *" "int64_t"); +\fIvoid\fP +.RE +.nh +\fBarchive_entry_set_symlink\fP +.hy +("struct archive_entry *" "const char *"); +\fIvoid\fP +.RE +.nh +\fBarchive_entry_set_uid\fP +.hy +("struct archive_entry *" "uid_t"); +\fIvoid\fP +.RE +.nh +\fBarchive_entry_set_uname\fP +.hy +("struct archive_entry *" "const char *"); +\fIint64_t\fP +.RE +.nh +\fBarchive_entry_size\fP +.hy +("struct archive_entry *"); +\fIconst char *\fP +.RE +.nh +\fBarchive_entry_sourcepath\fP +.hy +("struct archive_entry *"); +\fIconst struct stat *\fP +.RE +.nh +\fBarchive_entry_stat\fP +.hy +("struct archive_entry *"); +\fIconst char *\fP +.RE +.nh +\fBarchive_entry_symlink\fP +.hy +("struct archive_entry *"); +\fIconst char *\fP +.RE +.nh +\fBarchive_entry_uname\fP +.hy +("struct archive_entry *"); +.SH DESCRIPTION +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: +.TP +.nh +\fBarchive_entry_clear\fP +.hy +(); +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 +.nh +\fBarchive_entry_clone\fP +.hy +(); +A deep copy operation; all text fields are duplicated. +.TP +.nh +\fBarchive_entry_free\fP +.hy +(); +Releases the +Tn struct archive_entry +object. +.TP +.nh +\fBarchive_entry_new\fP +.hy +(); +Allocate and return a blank +Tn struct archive_entry +object. +.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: +.TP +.nh +\fBarchive_entry_set_XXXX\fP +.hy +(); +Stores the provided data in the object. +In particular, for strings, the pointer is stored, +not the referenced string. +.TP +.nh +\fBarchive_entry_copy_XXXX\fP +.hy +(); +As above, except that the referenced data is copied +into the object. +.TP +.nh +\fBarchive_entry_XXXX\fP +.hy +(); +Returns the specified data. +In the case of strings, a const-qualified pointer to +the string is returned. +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. +There are a few set/get functions that merit additional description: +.TP +.nh +\fBarchive_entry_set_link\fP +.hy +(); +This function sets the symlink field if it is already set. +Otherwise, it sets the hardlink field. +.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. +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. +The canonical text format is a comma-separated list of flag names. +The +.nh +\fBarchive_entry_copy_fflags_text\fP +.hy +(); +and +.nh +\fBarchive_entry_copy_fflags_text_w\fP +.hy +(); +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 +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. +XXX explain ACL stuff XXX +.SH SEE ALSO +\fBarchive\fP(3) +.SH HISTORY +The +\fBlibarchive\fP +library first appeared in +FreeBSD 5.3. +.SH AUTHORS +-nosplit +The +\fBlibarchive\fP +library was written by +Tim Kientzle <kientzle@acm.org.> diff --git a/libarchive/libarchive-2.5.5/doc/man/archive_read.3 b/libarchive/libarchive-2.5.5/doc/man/archive_read.3 new file mode 100644 index 0000000..91908e8 --- /dev/null +++ b/libarchive/libarchive-2.5.5/doc/man/archive_read.3 @@ -0,0 +1,878 @@ +.TH archive_read 3 "August 19, 2006" "" +.SH NAME +\fBarchive_read_new\fP, +\fBarchive_read_support_compression_all\fP, +\fBarchive_read_support_compression_bzip2\fP, +\fBarchive_read_support_compression_compress\fP, +\fBarchive_read_support_compression_gzip\fP, +\fBarchive_read_support_compression_none\fP, +\fBarchive_read_support_compression_program\fP, +\fBarchive_read_support_format_all\fP, +\fBarchive_read_support_format_cpio\fP, +\fBarchive_read_support_format_empty\fP, +\fBarchive_read_support_format_iso9660\fP, +\fBarchive_read_support_format_tar\fP, +\fBarchive_read_support_format_zip\fP, +\fBarchive_read_open\fP, +\fBarchive_read_open2\fP, +\fBarchive_read_open_fd\fP, +\fBarchive_read_open_FILE\fP, +\fBarchive_read_open_filename\fP, +\fBarchive_read_open_memory\fP, +\fBarchive_read_next_header\fP, +\fBarchive_read_data\fP, +\fBarchive_read_data_block\fP, +\fBarchive_read_data_skip\fP, +\fBarchive_read_data_into_buffer\fP, +\fBarchive_read_data_into_fd\fP, +\fBarchive_read_extract\fP, +\fBarchive_read_extract2\fP, +\fBarchive_read_extract_set_progress_callback\fP, +\fBarchive_read_close\fP, +\fBarchive_read_finish\fP +\- functions for reading streaming archives +.SH SYNOPSIS +\fB#include <archive.h>\fP +.br +\fIstruct archive *\fP +.RE +.nh +\fBarchive_read_new\fP +.hy +("void"); +\fIint\fP +.RE +.nh +\fBarchive_read_support_compression_all\fP +.hy +("struct archive *"); +\fIint\fP +.RE +.nh +\fBarchive_read_support_compression_bzip2\fP +.hy +("struct archive *"); +\fIint\fP +.RE +.nh +\fBarchive_read_support_compression_compress\fP +.hy +("struct archive *"); +\fIint\fP +.RE +.nh +\fBarchive_read_support_compression_gzip\fP +.hy +("struct archive *"); +\fIint\fP +.RE +.nh +\fBarchive_read_support_compression_none\fP +.hy +("struct archive *"); +\fIint\fP +.RE +Fo archive_read_support_compression_program +Fa "struct archive *" +Fa "const char *cmd" +Fc +\fIint\fP +.RE +.nh +\fBarchive_read_support_format_all\fP +.hy +("struct archive *"); +\fIint\fP +.RE +.nh +\fBarchive_read_support_format_cpio\fP +.hy +("struct archive *"); +\fIint\fP +.RE +.nh +\fBarchive_read_support_format_empty\fP +.hy +("struct archive *"); +\fIint\fP +.RE +.nh +\fBarchive_read_support_format_iso9660\fP +.hy +("struct archive *"); +\fIint\fP +.RE +.nh +\fBarchive_read_support_format_tar\fP +.hy +("struct archive *"); +\fIint\fP +.RE +.nh +\fBarchive_read_support_format_zip\fP +.hy +("struct archive *"); +\fIint\fP +.RE +Fo archive_read_open +Fa "struct archive *" +Fa "void *client_data" +Fa "archive_open_callback *" +Fa "archive_read_callback *" +Fa "archive_close_callback *" +Fc +\fIint\fP +.RE +Fo archive_read_open2 +Fa "struct archive *" +Fa "void *client_data" +Fa "archive_open_callback *" +Fa "archive_read_callback *" +Fa "archive_skip_callback *" +Fa "archive_close_callback *" +Fc +\fIint\fP +.RE +.nh +\fBarchive_read_open_FILE\fP +.hy +("struct archive *" "FILE *file"); +\fIint\fP +.RE +.nh +\fBarchive_read_open_fd\fP +.hy +("struct archive *" "int fd" "size_t block_size"); +\fIint\fP +.RE +Fo archive_read_open_filename +Fa "struct archive *" +Fa "const char *filename" +Fa "size_t block_size" +Fc +\fIint\fP +.RE +.nh +\fBarchive_read_open_memory\fP +.hy +("struct archive *" "void *buff" "size_t size"); +\fIint\fP +.RE +.nh +\fBarchive_read_next_header\fP +.hy +("struct archive *" "struct archive_entry **"); +\fIssize_t\fP +.RE +.nh +\fBarchive_read_data\fP +.hy +("struct archive *" "void *buff" "size_t len"); +\fIint\fP +.RE +Fo archive_read_data_block +Fa "struct archive *" +Fa "const void **buff" +Fa "size_t *len" +Fa "off_t *offset" +Fc +\fIint\fP +.RE +.nh +\fBarchive_read_data_skip\fP +.hy +("struct archive *"); +\fIint\fP +.RE +.nh +\fBarchive_read_data_into_buffer\fP +.hy +("struct archive *" "void *" "ssize_t len"); +\fIint\fP +.RE +.nh +\fBarchive_read_data_into_fd\fP +.hy +("struct archive *" "int fd"); +\fIint\fP +.RE +Fo archive_read_extract +Fa "struct archive *" +Fa "struct archive_entry *" +Fa "int flags" +Fc +\fIint\fP +.RE +Fo archive_read_extract2 +Fa "struct archive *src" +Fa "struct archive_entry *" +Fa "struct archive *dest" +Fc +\fIvoid\fP +.RE +Fo archive_read_extract_set_progress_callback +Fa "struct archive *" +Fa "void (*func)(void *)" +Fa "void *user_data" +Fc +\fIint\fP +.RE +.nh +\fBarchive_read_close\fP +.hy +("struct archive *"); +\fIint\fP +.RE +.nh +\fBarchive_read_finish\fP +.hy +("struct archive *"); +.SH DESCRIPTION +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: +.TP +.nh +\fBarchive_read_new\fP +.hy +(); +Allocates and initializes a +Tn struct archive +object suitable for reading from an archive. +.TP +Xo +.nh +\fBarchive_read_support_compression_all\fP +.hy +(,); +.nh +\fBarchive_read_support_compression_bzip2\fP +.hy +(,); +.nh +\fBarchive_read_support_compression_compress\fP +.hy +(,); +.nh +\fBarchive_read_support_compression_gzip\fP +.hy +(,); +.nh +\fBarchive_read_support_compression_none\fP +.hy +(); +Xc +Enables auto-detection code and decompression support for the +specified compression. +Note that +``none'' +is always enabled by default. +For convenience, +.nh +\fBarchive_read_support_compression_all\fP +.hy +(); +enables all available decompression code. +.TP +.nh +\fBarchive_read_support_compression_program\fP +.hy +(); +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 +Xo +.nh +\fBarchive_read_support_format_all\fP +.hy +(,); +.nh +\fBarchive_read_support_format_cpio\fP +.hy +(,); +.nh +\fBarchive_read_support_format_empty\fP +.hy +(,); +.nh +\fBarchive_read_support_format_iso9660\fP +.hy +(,); +.nh +\fBarchive_read_support_format_tar\fP +.hy +(,); +.nh +\fBarchive_read_support_format_zip\fP +.hy +(); +Xc +Enables support---including auto-detection code---for the +specified archive format. +For example, +.nh +\fBarchive_read_support_format_tar\fP +.hy +(); +enables support for a variety of standard tar formats, old-style tar, +ustar, pax interchange format, and many common variants. +For convenience, +.nh +\fBarchive_read_support_format_all\fP +.hy +(); +enables support for all available formats. +Only empty archives are supported by default. +.TP +.nh +\fBarchive_read_open\fP +.hy +(); +The same as +.nh +\fBarchive_read_open2\fP +.hy +(,); +except that the skip callback is assumed to be +.BR NULL. +.TP +.nh +\fBarchive_read_open2\fP +.hy +(); +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 +.nh +\fBarchive_read_open_filename\fP +.hy +(,); +.nh +\fBarchive_read_open_FILE\fP +.hy +(,); +.nh +\fBarchive_read_open_fd\fP +.hy +(,); +or +.nh +\fBarchive_read_open_memory\fP +.hy +(); +instead. +The library invokes the client-provided functions to obtain +raw bytes from the archive. +.TP +.nh +\fBarchive_read_open_FILE\fP +.hy +(); +Like +.nh +\fBarchive_read_open\fP +.hy +(,); +except that it accepts a +\fI"FILE *"\fP +.RE +pointer. +This function should not be used with tape drives or other devices +that require strict I/O blocking. +.TP +.nh +\fBarchive_read_open_fd\fP +.hy +(); +Like +.nh +\fBarchive_read_open\fP +.hy +(,); +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 +.nh +\fBarchive_read_open_file\fP +.hy +(); +This is a deprecated synonym for +.nh +\fBarchive_read_open_filename\fP +.hy +(.); +.TP +.nh +\fBarchive_read_open_filename\fP +.hy +(); +Like +.nh +\fBarchive_read_open\fP +.hy +(,); +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 +.nh +\fBarchive_read_open_memory\fP +.hy +(); +Like +.nh +\fBarchive_read_open\fP +.hy +(,); +except that it accepts a pointer and size of a block of +memory containing the archive data. +.TP +.nh +\fBarchive_read_next_header\fP +.hy +(); +Read the header for the next entry and return a pointer to +a +Tn struct archive_entry. +.TP +.nh +\fBarchive_read_data\fP +.hy +(); +Read data associated with the header just read. +Internally, this is a convenience function that calls +.nh +\fBarchive_read_data_block\fP +.hy +(); +and fills any gaps with nulls so that callers see a single +continuous stream of data. +.TP +.nh +\fBarchive_read_data_block\fP +.hy +(); +Return the next available block of data for this entry. +Unlike +.nh +\fBarchive_read_data\fP +.hy +(,); +the +.nh +\fBarchive_read_data_block\fP +.hy +(); +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 +.nh +\fBarchive_read_data_skip\fP +.hy +(); +A convenience function that repeatedly calls +.nh +\fBarchive_read_data_block\fP +.hy +(); +to skip all of the data for this archive entry. +.TP +.nh +\fBarchive_read_data_into_buffer\fP +.hy +(); +This function is deprecated and will be removed. +Use +.nh +\fBarchive_read_data\fP +.hy +(); +instead. +.TP +.nh +\fBarchive_read_data_into_fd\fP +.hy +(); +A convenience function that repeatedly calls +.nh +\fBarchive_read_data_block\fP +.hy +(); +to copy the entire entry to the provided file descriptor. +.TP +.nh +\fBarchive_read_extract\fP +.hy +(, .nh); +\fBarchive_read_extract_set_skip_file\fP +.hy +(); +A convenience function that wraps the corresponding +\fBarchive_write_disk\fP(3) +interfaces. +The first call to +.nh +\fBarchive_read_extract\fP +.hy +(); +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 +.nh +\fBarchive_read_extract2\fP +.hy +(); +This is another version of +.nh +\fBarchive_read_extract\fP +.hy +(); +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 +.nh +\fBarchive_read_extract2\fP +.hy +(); +does not accept a +\fIflags\fP +argument; you should use +.nh +\fBarchive_write_disk_set_options\fP +.hy +(); +to set the restore options yourself. +.TP +.nh +\fBarchive_read_extract_set_progress_callback\fP +.hy +(); +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 +.nh +\fBarchive_read_close\fP +.hy +(); +Complete the archive and invoke the close callback. +.TP +.nh +\fBarchive_read_finish\fP +.hy +(); +Invokes +.nh +\fBarchive_read_close\fP +.hy +(); +if it was not invoked manually, then release all resources. +Note: In libarchive 1.x, this function was declared to return +\fIvoid,\fP +.RE +which made it impossible to detect certain errors when +.nh +\fBarchive_read_close\fP +.hy +(); +was invoked implicitly from this function. +The declaration is corrected beginning with libarchive 2.0. +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. +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 +The callback functions must match the following prototypes: +.IP +\fItypedef ssize_t\fP +.RE +Fo archive_read_callback +Fa "struct archive *" +Fa "void *client_data" +Fa "const void **buffer" +Fc +.IP +\fItypedef int\fP +.RE +Fo archive_skip_callback +Fa "struct archive *" +Fa "void *client_data" +Fa "size_t request" +Fc +.IP +\fItypedef int\fP +.RE +.nh +\fBarchive_open_callback\fP +.hy +("struct archive *" "void *client_data"); +.IP +\fItypedef int\fP +.RE +.nh +\fBarchive_close_callback\fP +.hy +("struct archive *" "void *client_data"); +The open callback is invoked by +.nh +\fBarchive_open\fP +.hy +(.); +It should return +\fBARCHIVE_OK\fP +if the underlying file or data source is successfully +opened. +If the open fails, it should call +.nh +\fBarchive_set_error\fP +.hy +(); +to register an error code and message and return +\fBARCHIVE_FATAL\fP. +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 +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 +.nh +\fBarchive_set_error\fP +.hy +(); +to register an error code and message and +return -1. +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. +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 +.nh +\fBarchive_set_error\fP +.hy +(); +to register an error code and message and +return +\fBARCHIVE_FATAL.\fP +.SH EXAMPLE +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 +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 +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 +.nh +\fBarchive_errno\fP +.hy +(); +and +.nh +\fBarchive_error_string\fP +.hy +(); +functions. +.nh +\fBarchive_read_new\fP +.hy +(); +returns a pointer to a freshly allocated +Tn struct archive +object. +It returns +.BR NULL +on error. +.nh +\fBarchive_read_data\fP +.hy +(); +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 +.nh +\fBarchive_errno\fP +.hy +(); +and +.nh +\fBarchive_error_string\fP +.hy +(); +functions. +The library expects the client callbacks to behave similarly. +If there is an error, you can use +.nh +\fBarchive_set_error\fP +.hy +(); +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 +\fBtar\fP(1), +\fBarchive\fP(3), +\fBarchive_util\fP(3), +\fBtar\fP(5) +.SH HISTORY +The +\fBlibarchive\fP +library first appeared in +FreeBSD 5.3. +.SH AUTHORS +-nosplit +The +\fBlibarchive\fP +library was written by +Tim Kientzle <kientzle@acm.org.> +.SH BUGS +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.5.5/doc/man/archive_util.3 b/libarchive/libarchive-2.5.5/doc/man/archive_util.3 new file mode 100644 index 0000000..6a9b7f5 --- /dev/null +++ b/libarchive/libarchive-2.5.5/doc/man/archive_util.3 @@ -0,0 +1,206 @@ +.TH archive_util 3 "January 8, 2005" "" +.SH NAME +\fBarchive_clear_error\fP, +\fBarchive_compression\fP, +\fBarchive_compression_name\fP, +\fBarchive_copy_error\fP, +\fBarchive_errno\fP, +\fBarchive_error_string\fP, +\fBarchive_format\fP, +\fBarchive_format_name\fP, +\fBarchive_set_error\fP +\- libarchive utility functions +.SH SYNOPSIS +\fB#include <archive.h>\fP +.br +\fIvoid\fP +.RE +.nh +\fBarchive_clear_error\fP +.hy +("struct archive *"); +\fIint\fP +.RE +.nh +\fBarchive_compression\fP +.hy +("struct archive *"); +\fIconst char *\fP +.RE +.nh +\fBarchive_compression_name\fP +.hy +("struct archive *"); +\fIvoid\fP +.RE +.nh +\fBarchive_copy_error\fP +.hy +("struct archive *" "struct archive *"); +\fIint\fP +.RE +.nh +\fBarchive_errno\fP +.hy +("struct archive *"); +\fIconst char *\fP +.RE +.nh +\fBarchive_error_string\fP +.hy +("struct archive *"); +\fIint\fP +.RE +.nh +\fBarchive_format\fP +.hy +("struct archive *"); +\fIconst char *\fP +.RE +.nh +\fBarchive_format_name\fP +.hy +("struct archive *"); +\fIvoid\fP +.RE +Fo archive_set_error +Fa "struct archive *" +Fa "int error_code" +Fa "const char *fmt" +Fa "..." +Fc +.SH DESCRIPTION +These functions provide access to various information about the +Tn struct archive +object used in the +\fBlibarchive\fP(3) +library. +.TP +.nh +\fBarchive_clear_error\fP +.hy +(); +Clears any error information left over from a previous call. +Not generally used in client code. +.TP +.nh +\fBarchive_compression\fP +.hy +(); +Returns a numeric code indicating the current compression. +This value is set by +.nh +\fBarchive_read_open\fP +.hy +(.); +.TP +.nh +\fBarchive_compression_name\fP +.hy +(); +Returns a text description of the current compression suitable for display. +.TP +.nh +\fBarchive_copy_error\fP +.hy +(); +Copies error information from one archive to another. +.TP +.nh +\fBarchive_errno\fP +.hy +(); +Returns a numeric error code (see +\fBerrno\fP(2)) +indicating the reason for the most recent error return. +.TP +.nh +\fBarchive_error_string\fP +.hy +(); +Returns a textual error message suitable for display. +The error message here is usually more specific than that +obtained from passing the result of +.nh +\fBarchive_errno\fP +.hy +(); +to +\fBstrerror\fP(3). +.TP +.nh +\fBarchive_format\fP +.hy +(); +Returns a numeric code indicating the format of the current +archive entry. +This value is set by a successful call to +.nh +\fBarchive_read_next_header\fP +.hy +(.); +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 +.nh +\fBarchive_format_name\fP +.hy +(); +A textual description of the format of the current entry. +.TP +.nh +\fBarchive_set_error\fP +.hy +(); +Sets the numeric error code and error description that will be returned +by +.nh +\fBarchive_errno\fP +.hy +(); +and +.nh +\fBarchive_error_string\fP +.hy +(.); +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. +.SH SEE ALSO +\fBarchive_read\fP(3), +\fBarchive_write\fP(3), +\fBlibarchive\fP(3), +\fBprintf\fP(3) +.SH HISTORY +The +\fBlibarchive\fP +library first appeared in +FreeBSD 5.3. +.SH AUTHORS +-nosplit +The +\fBlibarchive\fP +library was written by +Tim Kientzle <kientzle@acm.org.> diff --git a/libarchive/libarchive-2.5.5/doc/man/archive_write.3 b/libarchive/libarchive-2.5.5/doc/man/archive_write.3 new file mode 100644 index 0000000..3c02d52 --- /dev/null +++ b/libarchive/libarchive-2.5.5/doc/man/archive_write.3 @@ -0,0 +1,815 @@ +.TH archive_write 3 "May 11, 2008" "" +.SH NAME +\fBarchive_write_new\fP, +\fBarchive_write_set_format_cpio\fP, +\fBarchive_write_set_format_pax\fP, +\fBarchive_write_set_format_pax_restricted\fP, +\fBarchive_write_set_format_shar\fP, +\fBarchive_write_set_format_shar_binary\fP, +\fBarchive_write_set_format_ustar\fP, +\fBarchive_write_get_bytes_per_block\fP, +\fBarchive_write_set_bytes_per_block\fP, +\fBarchive_write_set_bytes_in_last_block\fP, +\fBarchive_write_set_compression_bzip2\fP, +\fBarchive_write_set_compression_compress\fP, +\fBarchive_write_set_compression_gzip\fP, +\fBarchive_write_set_compression_none\fP, +\fBarchive_write_set_compression_program\fP, +\fBarchive_write_open\fP, +\fBarchive_write_open_fd\fP, +\fBarchive_write_open_FILE\fP, +\fBarchive_write_open_filename\fP, +\fBarchive_write_open_memory\fP, +\fBarchive_write_header\fP, +\fBarchive_write_data\fP, +\fBarchive_write_finish_entry\fP, +\fBarchive_write_close\fP, +\fBarchive_write_finish\fP +\- functions for creating archives +.SH SYNOPSIS +\fB#include <archive.h>\fP +.br +\fIstruct archive *\fP +.RE +.nh +\fBarchive_write_new\fP +.hy +("void"); +\fIint\fP +.RE +.nh +\fBarchive_write_get_bytes_per_block\fP +.hy +("struct archive *"); +\fIint\fP +.RE +.nh +\fBarchive_write_set_bytes_per_block\fP +.hy +("struct archive *" "int bytes_per_block"); +\fIint\fP +.RE +.nh +\fBarchive_write_set_bytes_in_last_block\fP +.hy +("struct archive *" "int"); +\fIint\fP +.RE +.nh +\fBarchive_write_set_compression_bzip2\fP +.hy +("struct archive *"); +\fIint\fP +.RE +.nh +\fBarchive_write_set_compression_compress\fP +.hy +("struct archive *"); +\fIint\fP +.RE +.nh +\fBarchive_write_set_compression_gzip\fP +.hy +("struct archive *"); +\fIint\fP +.RE +.nh +\fBarchive_write_set_compression_none\fP +.hy +("struct archive *"); +\fIint\fP +.RE +Fo archive_write_set_compression_program +Fa "struct archive *" +Fa "const char * cmd" +Fc +\fIint\fP +.RE +.nh +\fBarchive_write_set_format_cpio\fP +.hy +("struct archive *"); +\fIint\fP +.RE +.nh +\fBarchive_write_set_format_pax\fP +.hy +("struct archive *"); +\fIint\fP +.RE +.nh +\fBarchive_write_set_format_pax_restricted\fP +.hy +("struct archive *"); +\fIint\fP +.RE +.nh +\fBarchive_write_set_format_shar\fP +.hy +("struct archive *"); +\fIint\fP +.RE +.nh +\fBarchive_write_set_format_shar_binary\fP +.hy +("struct archive *"); +\fIint\fP +.RE +.nh +\fBarchive_write_set_format_ustar\fP +.hy +("struct archive *"); +\fIint\fP +.RE +Fo archive_write_open +Fa "struct archive *" +Fa "void *client_data" +Fa "archive_open_callback *" +Fa "archive_write_callback *" +Fa "archive_close_callback *" +Fc +\fIint\fP +.RE +.nh +\fBarchive_write_open_fd\fP +.hy +("struct archive *" "int fd"); +\fIint\fP +.RE +.nh +\fBarchive_write_open_FILE\fP +.hy +("struct archive *" "FILE *file"); +\fIint\fP +.RE +.nh +\fBarchive_write_open_filename\fP +.hy +("struct archive *" "const char *filename"); +\fIint\fP +.RE +Fo archive_write_open_memory +Fa "struct archive *" +Fa "void *buffer" +Fa "size_t bufferSize" +Fa "size_t *outUsed" +Fc +\fIint\fP +.RE +.nh +\fBarchive_write_header\fP +.hy +("struct archive *" "struct archive_entry *"); +\fIssize_t\fP +.RE +.nh +\fBarchive_write_data\fP +.hy +("struct archive *" "const void *" "size_t"); +\fIint\fP +.RE +.nh +\fBarchive_write_finish_entry\fP +.hy +("struct archive *"); +\fIint\fP +.RE +.nh +\fBarchive_write_close\fP +.hy +("struct archive *"); +\fIint\fP +.RE +.nh +\fBarchive_write_finish\fP +.hy +("struct archive *"); +.SH DESCRIPTION +These functions provide a complete API for creating 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: +.TP +.nh +\fBarchive_write_new\fP +.hy +(); +Allocates and initializes a +Tn struct archive +object suitable for writing a tar archive. +.TP +.nh +\fBarchive_write_set_bytes_per_block\fP +.hy +(); +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 +.nh +\fBarchive_write_get_bytes_per_block\fP +.hy +(); +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 +.nh +\fBarchive_write_set_bytes_in_last_block\fP +.hy +(); +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 +.nh +\fBarchive_write_open_filename\fP +.hy +(); +will set this based on the file type). +Unlike the other +``set'' +functions, this function can be called after the archive is opened. +.TP +.nh +\fBarchive_write_get_bytes_in_last_block\fP +.hy +(); +Retrieve the currently-set value for last block size. +A value of -1 here indicates that the library should use default values. +.TP +Xo +.nh +\fBarchive_write_set_format_cpio\fP +.hy +(,); +.nh +\fBarchive_write_set_format_pax\fP +.hy +(,); +.nh +\fBarchive_write_set_format_pax_restricted\fP +.hy +(,); +.nh +\fBarchive_write_set_format_shar\fP +.hy +(,); +.nh +\fBarchive_write_set_format_shar_binary\fP +.hy +(,); +.nh +\fBarchive_write_set_format_ustar\fP +.hy +(); +Xc +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 +Xo +.nh +\fBarchive_write_set_compression_bzip2\fP +.hy +(,); +.nh +\fBarchive_write_set_compression_compress\fP +.hy +(,); +.nh +\fBarchive_write_set_compression_gzip\fP +.hy +(,); +.nh +\fBarchive_write_set_compression_none\fP +.hy +(); +Xc +The resulting archive will be compressed as specified. +Note that the compressed output is always properly blocked. +.TP +.nh +\fBarchive_write_set_compression_program\fP +.hy +(); +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 +.nh +\fBarchive_write_open\fP +.hy +(); +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 +.nh +\fBarchive_write_open_fd\fP +.hy +(); +A convenience form of +.nh +\fBarchive_write_open\fP +.hy +(); +that accepts a file descriptor. +The +.nh +\fBarchive_write_open_fd\fP +.hy +(); +function is safe for use with tape drives or other +block-oriented devices. +.TP +.nh +\fBarchive_write_open_FILE\fP +.hy +(); +A convenience form of +.nh +\fBarchive_write_open\fP +.hy +(); +that accepts a +\fI"FILE *"\fP +.RE +pointer. +Note that +.nh +\fBarchive_write_open_FILE\fP +.hy +(); +is not safe for writing to tape drives or other devices +that require correct blocking. +.TP +.nh +\fBarchive_write_open_file\fP +.hy +(); +A deprecated synonym for +.nh +\fBarchive_write_open_filename\fP +.hy +(.); +.TP +.nh +\fBarchive_write_open_filename\fP +.hy +(); +A convenience form of +.nh +\fBarchive_write_open\fP +.hy +(); +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 +.nh +\fBarchive_write_set_bytes_in_last_block\fP +.hy +(,); +then +.nh +\fBarchive_write_open_filename\fP +.hy +(); +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 +.nh +\fBarchive_write_set_bytes_in_last_block\fP +.hy +(); +before calling +.nh +\fBarchive_write_open\fP +.hy +(.); +The +.nh +\fBarchive_write_open_filename\fP +.hy +(); +function is safe for use with tape drives or other +block-oriented devices. +.TP +.nh +\fBarchive_write_open_memory\fP +.hy +(); +A convenience form of +.nh +\fBarchive_write_open\fP +.hy +(); +that accepts a pointer to a block of memory that will receive +the archive. +The final +\fI"size_t *"\fP +.RE +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 +.nh +\fBarchive_write_header\fP +.hy +(); +Build and write a header using the data in the provided +Tn struct archive_entry +structure. +See +\fBarchive_entry\fP(3) +for information on creating and populating +Tn struct archive_entry +objects. +.TP +.nh +\fBarchive_write_data\fP +.hy +(); +Write data corresponding to the header just written. +Returns number of bytes written or -1 on error. +.TP +.nh +\fBarchive_write_finish_entry\fP +.hy +(); +Close out the entry just written. +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 +.nh +\fBarchive_write_next_header\fP +.hy +(); +and +.nh +\fBarchive_write_close\fP +.hy +(); +as needed. +.TP +.nh +\fBarchive_write_close\fP +.hy +(); +Complete the archive and invoke the close callback. +.TP +.nh +\fBarchive_write_finish\fP +.hy +(); +Invokes +.nh +\fBarchive_write_close\fP +.hy +(); +if it was not invoked manually, then releases all resources. +Note that this function was declared to return +\fIvoid\fP +.RE +in libarchive 1.x, which made it impossible to detect errors when +.nh +\fBarchive_write_close\fP +.hy +(); +was invoked implicitly from this function. +This is corrected beginning with libarchive 2.0. +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 +Compression support is built-in to libarchive, which uses zlib and bzlib +to handle gzip and bzip2 compression, respectively. +.SH CLIENT CALLBACKS +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 +.nh +\fBarchive_write_open\fP +.hy +(:); +.IP +\fItypedef int\fP +.RE +.nh +\fBarchive_open_callback\fP +.hy +("struct archive *" "void *client_data"); +The open callback is invoked by +.nh +\fBarchive_write_open\fP +.hy +(.); +It should return +\fBARCHIVE_OK\fP +if the underlying file or data source is successfully +opened. +If the open fails, it should call +.nh +\fBarchive_set_error\fP +.hy +(); +to register an error code and message and return +\fBARCHIVE_FATAL\fP. +.IP +\fItypedef ssize_t\fP +.RE +Fo archive_write_callback +Fa "struct archive *" +Fa "void *client_data" +Fa "void *buffer" +Fa "size_t length" +Fc +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 +.nh +\fBarchive_set_error\fP +.hy +(); +to register an error code and message and return -1. +.IP +\fItypedef int\fP +.RE +.nh +\fBarchive_close_callback\fP +.hy +("struct archive *" "void *client_data"); +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 +.nh +\fBarchive_set_error\fP +.hy +(); +to register an error code and message and +return +\fBARCHIVE_FATAL.\fP +.SH EXAMPLE +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 +#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, 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 +Most functions return +\fBARCHIVE_OK\fP +(zero) on success, or one of several non-zero +error codes for errors. +Specific error codes include: +\fBARCHIVE_RETRY\fP +for operations that might succeed if retried, +\fBARCHIVE_WARN\fP +for unusual conditions that do not prevent further operations, and +\fBARCHIVE_FATAL\fP +for serious errors that make remaining operations impossible. +The +.nh +\fBarchive_errno\fP +.hy +(); +and +.nh +\fBarchive_error_string\fP +.hy +(); +functions can be used to retrieve an appropriate error code and a +textual error message. +.nh +\fBarchive_write_new\fP +.hy +(); +returns a pointer to a newly-allocated +Tn struct archive +object. +.nh +\fBarchive_write_data\fP +.hy +(); +returns a count of the number of bytes actually written. +On error, -1 is returned and the +.nh +\fBarchive_errno\fP +.hy +(); +and +.nh +\fBarchive_error_string\fP +.hy +(); +functions will return appropriate values. +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 +.nh +\fBarchive_write_header\fP +.hy +(,); +.nh +\fBarchive_write_data\fP +.hy +(,); +.nh +\fBarchive_write_close\fP +.hy +(,); +or +.nh +\fBarchive_write_finish\fP +.hy +(.); +The client callback can call +.nh +\fBarchive_set_error\fP +.hy +(); +to provide values that can then be retrieved by +.nh +\fBarchive_errno\fP +.hy +(); +and +.nh +\fBarchive_error_string\fP +.hy +(.); +.SH SEE ALSO +\fBtar\fP(1), +\fBlibarchive\fP(3), +\fBtar\fP(5) +.SH HISTORY +The +\fBlibarchive\fP +library first appeared in +FreeBSD 5.3. +.SH AUTHORS +-nosplit +The +\fBlibarchive\fP +library was written by +Tim Kientzle <kientzle@acm.org.> +.SH BUGS +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. +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 +\fBstar\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.5.5/doc/man/archive_write_disk.3 b/libarchive/libarchive-2.5.5/doc/man/archive_write_disk.3 new file mode 100644 index 0000000..e48292d --- /dev/null +++ b/libarchive/libarchive-2.5.5/doc/man/archive_write_disk.3 @@ -0,0 +1,476 @@ +.TH archive_write_disk 3 "March 2, 2007" "" +.SH NAME +\fBarchive_write_disk_new\fP, +\fBarchive_write_disk_set_options\fP, +\fBarchive_write_disk_set_skip_file\fP, +\fBarchive_write_disk_set_group_lookup\fP, +\fBarchive_write_disk_set_standard_lookup\fP, +\fBarchive_write_disk_set_user_lookup\fP, +\fBarchive_write_header\fP, +\fBarchive_write_data\fP, +\fBarchive_write_finish_entry\fP, +\fBarchive_write_close\fP, +\fBarchive_write_finish\fP +\- functions for creating objects on disk +.SH SYNOPSIS +\fB#include <archive.h>\fP +.br +\fIstruct archive *\fP +.RE +.nh +\fBarchive_write_disk_new\fP +.hy +("void"); +\fIint\fP +.RE +.nh +\fBarchive_write_disk_set_options\fP +.hy +("struct archive *" "int flags"); +\fIint\fP +.RE +.nh +\fBarchive_write_disk_set_skip_file\fP +.hy +("struct archive *" "dev_t" "ino_t"); +\fIint\fP +.RE +Fo archive_write_disk_set_group_lookup +Fa "struct archive *" +Fa "void *" +Fa "gid_t (*)(void *, const char *gname, gid_t gid)" +Fa "void (*cleanup)(void *)" +Fc +\fIint\fP +.RE +.nh +\fBarchive_write_disk_set_standard_lookup\fP +.hy +("struct archive *"); +\fIint\fP +.RE +Fo archive_write_disk_set_user_lookup +Fa "struct archive *" +Fa "void *" +Fa "uid_t (*)(void *, const char *uname, uid_t uid)" +Fa "void (*cleanup)(void *)" +Fc +\fIint\fP +.RE +.nh +\fBarchive_write_header\fP +.hy +("struct archive *" "struct archive_entry *"); +\fIssize_t\fP +.RE +.nh +\fBarchive_write_data\fP +.hy +("struct archive *" "const void *" "size_t"); +\fIint\fP +.RE +.nh +\fBarchive_write_finish_entry\fP +.hy +("struct archive *"); +\fIint\fP +.RE +.nh +\fBarchive_write_close\fP +.hy +("struct archive *"); +\fIint\fP +.RE +.nh +\fBarchive_write_finish\fP +.hy +("struct archive *"); +.SH DESCRIPTION +These functions provide a complete API for creating objects on +disk from +Tn struct archive_entry +descriptions. +They are most naturally used when extracting objects from an archive +using the +.nh +\fBarchive_read\fP +.hy +(); +interface. +The general process is to read +Tn struct archive_entry +objects from an archive, then write those objects to a +Tn struct archive +object created using the +.nh +\fBarchive_write_disk\fP +.hy +(); +family functions. +This interface is deliberately very similar to the +.nh +\fBarchive_write\fP +.hy +(); +interface used to write objects to a streaming archive. +.TP +.nh +\fBarchive_write_disk_new\fP +.hy +(); +Allocates and initializes a +Tn struct archive +object suitable for writing objects to disk. +.TP +.nh +\fBarchive_write_disk_set_skip_file\fP +.hy +(); +Records the device and inode numbers of a file that should not be +overwritten. +This is typically used to ensure that an extraction process does not +overwrite the archive from which objects are being read. +This capability is technically unnecessary but can be a significant +performance optimization in practice. +.TP +.nh +\fBarchive_write_disk_set_options\fP +.hy +(); +The options field consists of a bitwise OR of one or more of the +following values: +.TP +\fBARCHIVE_EXTRACT_OWNER\fP +The user and group IDs should be set on the restored file. +By default, the user and group IDs are not restored. +.TP +\fBARCHIVE_EXTRACT_PERM\fP +Full permissions (including SGID, SUID, and sticky bits) should +be restored exactly as specified, without obeying the +current umask. +Note that SUID and SGID bits can only be restored if the +user and group ID of the object on disk are correct. +If +\fBARCHIVE_EXTRACT_OWNER\fP +is not specified, then SUID and SGID bits will only be restored +if the default user and group IDs of newly-created objects on disk +happen to match those specified in the archive entry. +By default, only basic permissions are restored, and umask is obeyed. +.TP +\fBARCHIVE_EXTRACT_TIME\fP +The timestamps (mtime, ctime, and atime) should be restored. +By default, they are ignored. +Note that restoring of atime is not currently supported. +.TP +\fBARCHIVE_EXTRACT_NO_OVERWRITE\fP +Existing files on disk will not be overwritten. +By default, existing regular files are truncated and overwritten; +existing directories will have their permissions updated; +other pre-existing objects are unlinked and recreated from scratch. +.TP +\fBARCHIVE_EXTRACT_UNLINK\fP +Existing files on disk will be unlinked before any attempt to +create them. +In some cases, this can prove to be a significant performance improvement. +By default, existing files are truncated and rewritten, but +the file is not recreated. +In particular, the default behavior does not break existing hard links. +.TP +\fBARCHIVE_EXTRACT_ACL\fP +Attempt to restore ACLs. +By default, extended ACLs are ignored. +.TP +\fBARCHIVE_EXTRACT_FFLAGS\fP +Attempt to restore extended file flags. +By default, file flags are ignored. +.TP +\fBARCHIVE_EXTRACT_XATTR\fP +Attempt to restore POSIX.1e extended attributes. +By default, they are ignored. +.TP +\fBARCHIVE_EXTRACT_SECURE_SYMLINKS\fP +Refuse to extract any object whose final location would be altered +by a symlink on disk. +This is intended to help guard against a variety of mischief +caused by archives that (deliberately or otherwise) extract +files outside of the current directory. +The default is not to perform this check. +If +\fBARCHIVE_EXTRACT_UNLINK\fP +is specified together with this option, the library will +remove any intermediate symlinks it finds and return an +error only if such symlink could not be removed. +.TP +\fBARCHIVE_EXTRACT_SECURE_NODOTDOT\fP +Refuse to extract a path that contains a +\fI\& ..\fP +element anywhere within it. +The default is to not refuse such paths. +Note that paths ending in +\fI\& ..\fP +always cause an error, regardless of this flag. +.TP +\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. +.TP +Xo +.nh +\fBarchive_write_disk_set_group_lookup\fP +.hy +(,); +.nh +\fBarchive_write_disk_set_user_lookup\fP +.hy +(); +Xc +The +Tn struct archive_entry +objects contain both names and ids that can be used to identify users +and groups. +These names and ids describe the ownership of the file itself and +also appear in ACL lists. +By default, the library uses the ids and ignores the names, but +this can be overridden by registering user and group lookup functions. +To register, you must provide a lookup function which +accepts both a name and id and returns a suitable id. +You may also provide a +Tn void * +pointer to a private data structure and a cleanup function for +that data. +The cleanup function will be invoked when the +Tn struct archive +object is destroyed. +.TP +.nh +\fBarchive_write_disk_set_standard_lookup\fP +.hy +(); +This convenience function installs a standard set of user +and group lookup functions. +These functions use +\fBgetpwnam\fP(3) +and +\fBgetgrnam\fP(3) +to convert names to ids, defaulting to the ids if the names cannot +be looked up. +These functions also implement a simple memory cache to reduce +the number of calls to +\fBgetpwnam\fP(3) +and +\fBgetgrnam\fP(3). +.TP +.nh +\fBarchive_write_header\fP +.hy +(); +Build and write a header using the data in the provided +Tn struct archive_entry +structure. +See +\fBarchive_entry\fP(3) +for information on creating and populating +Tn struct archive_entry +objects. +.TP +.nh +\fBarchive_write_data\fP +.hy +(); +Write data corresponding to the header just written. +Returns number of bytes written or -1 on error. +.TP +.nh +\fBarchive_write_finish_entry\fP +.hy +(); +Close out the entry just written. +Ordinarily, clients never need to call this, as it +is called automatically by +.nh +\fBarchive_write_next_header\fP +.hy +(); +and +.nh +\fBarchive_write_close\fP +.hy +(); +as needed. +.TP +.nh +\fBarchive_write_close\fP +.hy +(); +Set any attributes that could not be set during the initial restore. +For example, directory timestamps are not restored initially because +restoring a subsequent file would alter that timestamp. +Similarly, non-writable directories are initially created with +write permissions (so that their contents can be restored). +The +\fBarchive_write_disk_new\fP +library maintains a list of all such deferred attributes and +sets them when this function is invoked. +.TP +.nh +\fBarchive_write_finish\fP +.hy +(); +Invokes +.nh +\fBarchive_write_close\fP +.hy +(); +if it was not invoked manually, then releases all resources. +More information about the +\fIstruct\fP archive +object and the overall design of the library can be found in the +\fBlibarchive\fP(3) +overview. +Many of these functions are also documented under +\fBarchive_write\fP(3). +.SH RETURN VALUES +Most functions return +\fBARCHIVE_OK\fP +(zero) on success, or one of several non-zero +error codes for errors. +Specific error codes include: +\fBARCHIVE_RETRY\fP +for operations that might succeed if retried, +\fBARCHIVE_WARN\fP +for unusual conditions that do not prevent further operations, and +\fBARCHIVE_FATAL\fP +for serious errors that make remaining operations impossible. +The +.nh +\fBarchive_errno\fP +.hy +(); +and +.nh +\fBarchive_error_string\fP +.hy +(); +functions can be used to retrieve an appropriate error code and a +textual error message. +.nh +\fBarchive_write_disk_new\fP +.hy +(); +returns a pointer to a newly-allocated +Tn struct archive +object. +.nh +\fBarchive_write_data\fP +.hy +(); +returns a count of the number of bytes actually written. +On error, -1 is returned and the +.nh +\fBarchive_errno\fP +.hy +(); +and +.nh +\fBarchive_error_string\fP +.hy +(); +functions will return appropriate values. +.SH SEE ALSO +\fBarchive_read\fP(3), +\fBarchive_write\fP(3), +\fBtar\fP(1), +\fBlibarchive\fP(3) +.SH HISTORY +The +\fBlibarchive\fP +library first appeared in +FreeBSD 5.3. +The +\fBarchive_write_disk\fP +interface was added to +\fBlibarchive\fP 2.0 +and first appeared in +FreeBSD 6.3. +.SH AUTHORS +-nosplit +The +\fBlibarchive\fP +library was written by +Tim Kientzle <kientzle@acm.org.> +.SH BUGS +Directories are actually extracted in two distinct phases. +Directories are created during +.nh +\fBarchive_write_header\fP +.hy +(,); +but final permissions are not set until +.nh +\fBarchive_write_close\fP +.hy +(.); +This separation is necessary to correctly handle borderline +cases such as a non-writable directory containing +files, but can cause unexpected results. +In particular, directory permissions are not fully +restored until the archive is closed. +If you use +\fBchdir\fP(2) +to change the current directory between calls to +.nh +\fBarchive_read_extract\fP +.hy +(); +or before calling +.nh +\fBarchive_read_close\fP +.hy +(,); +you may confuse the permission-setting logic with +the result that directory permissions are restored +incorrectly. +The library attempts to create objects with filenames longer than +\fBPATH_MAX\fP +by creating prefixes of the full path and changing the current directory. +Currently, this logic is limited in scope; the fixup pass does +not work correctly for such objects and the symlink security check +option disables the support for very long pathnames. +Restoring the path +\fIaa/../bb\fP +does create each intermediate directory. +In particular, the directory +\fIaa\fP +is created as well as the final object +\fIbb\fP. +In theory, this can be exploited to create an entire directory heirarchy +with a single request. +Of course, this does not work if the +\fBARCHIVE_EXTRACT_NODOTDOT\fP +option is specified. +Implicit directories are always created obeying the current umask. +Explicit objects are created obeying the current umask unless +\fBARCHIVE_EXTRACT_PERM\fP +is specified, in which case they current umask is ignored. +SGID and SUID bits are restored only if the correct user and +group could be set. +If +\fBARCHIVE_EXTRACT_OWNER\fP +is not specified, then no attempt is made to set the ownership. +In this case, SGID and SUID bits are restored only if the +user and group of the final object happen to match those specified +in the entry. +The +``standard'' +user-id and group-id lookup functions are not the defaults because +\fBgetgrnam\fP(3) +and +\fBgetpwnam\fP(3) +are sometimes too large for particular applications. +The current design allows the application author to use a more +compact implementation when appropriate. +There should be a corresponding +\fBarchive_read_disk\fP +interface that walks a directory heirarchy and returns archive +entry objects. diff --git a/libarchive/libarchive-2.5.5/doc/man/bsdcpio.1 b/libarchive/libarchive-2.5.5/doc/man/bsdcpio.1 new file mode 100644 index 0000000..fa1bd72 --- /dev/null +++ b/libarchive/libarchive-2.5.5/doc/man/bsdcpio.1 @@ -0,0 +1,370 @@ +.TH BSDCPIO 1 "December 21, 2007" "" +.SH NAME +\fBcpio\fP +\- copy files to and from archives +.SH SYNOPSIS +.br +\fBcpio\fP +{\fB\-i\fP} +[\fIoptions\fP] +[\fIpattern\fP ...] +[\fI<\fP archive] +.br +\fBcpio\fP +{\fB\-o\fP} +[\fIoptions\fP] +\fI<\fP name-list +[\fI>\fP archive] +.br +\fBcpio\fP +{\fB\-p\fP} +[\fIoptions\fP] +\fIdest-dir\fP +\fI<\fP name-list +.SH DESCRIPTION +\fBcpio\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. +The first option to +\fBcpio\fP +is a mode indicator from the following list: +.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. +.SH OPTIONS +Unless specifically stated otherwise, options are applicable in +all operating modes. +.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: +.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. +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\-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\-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\-m\fP +(i and p modes) +Set file modification time on created files to match +those in the source. +.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\--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. +.SH ENVIRONMENT +The following environment variables affect the execution of +\fB:\fP +.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. +.SH EXIT STATUS +The \fBcpio\fP utility exits 0 on success, and >0 if an error occurs. +.SH EXAMPLES +The +\fBcpio\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 +\fBcpio\fP find \fIsrc\fP | \fBcpio\fP \fB\-pmud\fP \fIdest\fP +.RE +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 +\fBcpio\fP find \fIsrc\fP \fB\-mtime\fP \fI+2\fP | \fINm\fP grep foo[bar] | \fBcpio\fP \fB\-pdmu\fP \fIdest\fP +.RE +This example copies files from +\fIsrc\fP +to +\fIdest\fP +that are more than 2 days old and which contain the word +Do foobar Dc: +.RS +\fBcpio\fP find \fIsrc\fP \fB\-mtime\fP \fI+2\fP | \fINm\fP xargs \fBcpio\fP grep -l foobar | \fBcpio\fP \fB\-pdmu\fP \fIdest\fP +.RE +.SH COMPATIBILITY +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. +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 +\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 +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''). +The cpio, ustar, and pax interchange file formats are defined by +IEEE Std 1003.1-2001 (``POSIX.1'') +for the pax command. +.SH HISTORY +The original +\fBcpio\fP +and +\fBfind\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, +\fBcpio\fP +actually predates +\fBtar\fP, +even though it was not well-known outside of AT&T until some time later. +This is a complete re-implementation based on the +\fBlibarchive\fP(3) +library. +.SH BUGS +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.5.5/doc/man/bsdtar.1 b/libarchive/libarchive-2.5.5/doc/man/bsdtar.1 new file mode 100644 index 0000000..c1088d9 --- /dev/null +++ b/libarchive/libarchive-2.5.5/doc/man/bsdtar.1 @@ -0,0 +1,856 @@ +.TH BSDTAR 1 "May 15, 2008" "" +.SH NAME +\fBtar\fP +\- manipulate tape archives +.SH SYNOPSIS +.br +\fBtar\fP +[\fIbundled-flags\fP <args>] +[<\fIfile\fP> | <\fIpattern\fP> ...] +.br +\fBtar\fP +{\fB\-c\fP} +[\fIoptions\fP] +[\fIfiles\fP | \fIdirectories\fP] +.br +\fBtar\fP +{\fB\-r\fP | \fB\-u\fP} +\fB\-f\fP \fIarchive-file\fP +[\fIoptions\fP] +[\fIfiles\fP | \fIdirectories\fP] +.br +\fBtar\fP +{\fB\-t\fP | \fB\-x\fP} +[\fIoptions\fP] +[\fIpatterns\fP] +.SH DESCRIPTION +\fBtar\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. +The first synopsis form shows a +``bundled'' +option word. +This usage is provided for compatibility with historical implementations. +See COMPATIBILITY below for details. +The other synopsis forms show the preferred usage. +The first option to +\fBtar\fP +is a mode indicator from the following list: +.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. +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. +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 +Unless specifically stated otherwise, options are applicable in +all operating modes. +.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 +\fBtar\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 +\fBtar\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 +\fBtar\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, +\fBtar\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 (\fB\-W\fP \fBcheck-links\fP) +(c and r modes only) +Issue a warning message unless all links to each file are archived. +.TP +\fB\--chroot\fP (\fB\-W\fP \fBchroot\fP) +(x mode only) +.nh +\fBchroot\fP +.hy +(); +to the current directory after processing any +\fB\-C\fP +options and before extracting any files. +.TP +\fB\--exclude\fP \fIpattern\fP (\fB\-W\fP \fBexclude\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 (\fB\-W\fP \fBformat\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 (\fB\-W\fP \fBinclude\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 +\fBtar\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 +\fBtar\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 (\fB\-W\fP \fBkeep-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 (\fB\-W\fP \fBnewer\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 (\fB\-W\fP \fBnewer-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 (\fB\-W\fP \fBnewer-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 (\fB\-W\fP \fBnewer-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 (\fB\-W\fP \fBnodump\fP) +(c and r modes only) +Honor the nodump file flag by skipping this file. +.TP +\fB\--null\fP (\fB\-W\fP \fBnull\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 (\fB\-W\fP \fBone-file-system\fP) +(c, r, and u modes) +Do not cross mount points. +.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, +\fBtar\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,\fP +the file mode is restored for newly-created regular files, and +all other types of entries receive default permissions. +If +\fBtar\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 (\fB\-W\fP \fBstrip-components\fP=\fIcount\fP) +(x and t 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 /old/new/[gps]. +old is a basic regular expression. +If it doesn't apply, the pattern is skipped. +new is the replacement string of the matched part. +~ 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, +\fBtar\fP +will read the list of names to be extracted from +\fIfilename\fP. +In c mode, +\fBtar\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, +\fBtar\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, +\fBtar\fP +will list each file name as it is read from or written to +the archive. +In list mode, +\fBtar\fP +will produce output similar to that of +\fBls\fP(1). +Additional +\fB\-v\fP +options will provide additional detail. +.TP +\fB\-W\fP \fIlongopt=value\fP +Long options (preceded by +\fB\--\fP) +are only supported directly on systems that have the +\fBgetopt_long\fP(3) +function. +The +\fB\-W\fP +option can be used to access long options on systems that +do not support this function. +.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 +\fBtar\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 +\fBtar\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 +\fBtar\fP +implementations, this implementation recognizes compress compression +automatically when reading archives. +.SH ENVIRONMENT +The following environment variables affect the execution of +\fB:\fP +.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. +.SH FILES +.TP +.B /dev/sa0 +The default tape device, if not overridden by the +.IR TAPE +environment variable or the +\fB\-f\fP +option. +.SH EXIT STATUS +The \fBtar\fP utility exits 0 on success, and >0 if an error occurs. +.SH EXAMPLES +The following creates a new archive +called +\fIfile.tar.gz\fP +that contains two files +\fIsource.c\fP +and +\fIsource.h\fP: +.RS +\fBtar\fP \fB\-czf\fP \fIfile.tar.gz\fP \fIsource.c\fP \fIsource.h\fP +.RE +To view a detailed table of contents for this +archive: +.RS +\fBtar\fP \fB\-tvf\fP \fIfile.tar.gz\fP +.RE +To extract all entries from the archive on +the default tape drive: +.RS +\fBtar\fP \fB\-x\fP +.RE +To examine the contents of an ISO 9660 cdrom image: +.RS +\fBtar\fP \fB\-tf\fP \fIimage.iso\fP +.RE +To move file hierarchies, invoke +\fBtar\fP +as +.RS +\fBtar\fP \fB\-cf\fP \fI-\fP \fB\-C\fP \fIsrcdir\\fP. | \fBtar\fP \fB\-xpf\fP \fI-\fP \fB\-C\fP \fIdestdir\fP +.RE +or more traditionally +.RS +cd srcdir \&; \fBtar\fP \fB\-cf\fP \fI-\\fP. | (cd destdir \&; \fBtar\fP \fB\-xpf\fP \fI-\fP) +.RE +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 +\fBtar\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. +\fBtar\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. +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: +.RS +$ cat input.mtree +.RE +.RS +usr/bin uid=0 gid=0 mode=0755 type=dir +.RE +.RS +usr/bin/ls uid=0 gid=0 mode=0755 type=file content=myls +.RE +.RS +$ tar -cvf output.tar @input.mtree +.RE +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''. +.SH COMPATIBILITY +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 +\fBtar\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. +The mode options c, r, t, u, and x and the options +b, f, l, m, o, v, and w comply with SUSv2. +For maximum portability, scripts that invoke +\fBtar\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. +On systems that support getopt_long(), additional long options +are available to improve compatibility with other tar implementations. +.SH SECURITY +Certain security issues are common to many archiving programs, including +\fB.\fP +In particular, carefully-crafted archives can request that +\fBtar\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 +\fBtar\fP +has mechanisms to protect against each one, +savvy users should be aware of the implications: +.IP \(bu +Archive entries can have absolute pathnames. +By default, +\fBtar\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, +\fBtar\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, +\fBtar\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, +\fBtar\fP +will refuse to extract the entry. +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 +\fBtar\fP \fB\-tf\fP \fIfilename\fP +.RE +before extraction. +You should use the +\fB\-k\fP +option to ensure that +\fBtar\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 +\fBtar\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 +\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 +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. +The ustar and pax interchange file formats are defined by +IEEE Std 1003.1-2001 (``POSIX.1'') +for the pax command. +.SH HISTORY +A +\fBtar\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 +\fBpdtar\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. +This is a complete re-implementation based on the +\fBlibarchive\fP(3) +library. +.SH BUGS +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. +The +\fB\-C\fP \fIdir\fP +option may differ from historic implementations. +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,\fP +although they still extract it correctly. +The compression and decompression is implemented internally, so +there may be insignificant differences between the compressed output +generated by +.RS +\fBtar\fP \fB\-czf\fP \fI-\fP file +.RE +and that generated by +.RS +\fBtar\fP \fB\-cf\fP \fI-\fP file | \fBtar\fP gzip +.RE +The default should be to read and write archives to the standard I/O paths, +but tradition (and POSIX) dictates otherwise. +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. +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. +In create mode, a leading +\fI\& ./\fP +is always removed. +A leading +\fI/\fP +is stripped unless the +\fB\-P\fP +option is specified. +There needs to be better support for file selection on both create +and extract. +There is not yet any support for multi-volume archives or for archiving +sparse files. +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.) +There are alternative long options for many of the short options that +are deliberately not documented. diff --git a/libarchive/libarchive-2.5.5/doc/man/cpio.5 b/libarchive/libarchive-2.5.5/doc/man/cpio.5 new file mode 100644 index 0000000..e389f71 --- /dev/null +++ b/libarchive/libarchive-2.5.5/doc/man/cpio.5 @@ -0,0 +1,301 @@ +.TH CPIO 5 "October 5, 2007" "" +.SH NAME +\fBcpio\fP +\- format of cpio archive files +.SH DESCRIPTION +The +\fBcpio\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 +\fBcpio\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 +\fBcpio\fP +format stores numbers as 2-byte and 4-byte binary values. +Each entry begins with a header in the following format: +.RS +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 +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 +.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 +\fBcpio\fP +archives to determine when two entries refer to the same file. +Programs that synthesize +\fBcpio\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: +.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. +.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. +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. +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 +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 +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 +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 +Except as specified below, the fields here match those specified +for the old binary format above. +.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. +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). +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 +\fBcpio\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. +XXX Others? XXX +.SH BUGS +The +``CRC'' +format is mis-named, as it uses a simple checksum and +not a cyclic redundancy check. +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. +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. +The new ASCII format is limited to 4 gigabyte file sizes. +None of the cpio formats store user or group names, +which are essential when moving files between systems with +dissimilar user or group numbering. +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 +\fBcpio\fP(1), +\fBtar\fP(5) +.SH STANDARDS +The +\fBcpio\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 +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.5.5/doc/man/libarchive-formats.5 b/libarchive/libarchive-2.5.5/doc/man/libarchive-formats.5 new file mode 100644 index 0000000..580aaea --- /dev/null +++ b/libarchive/libarchive-2.5.5/doc/man/libarchive-formats.5 @@ -0,0 +1,247 @@ +.TH libarchive-formats 3 "April 27, 2004" "" +.SH NAME +\fBlibarchive-formats\fP +\- archive formats supported by the libarchive library +.SH DESCRIPTION +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. +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. +.SS Tar Formats +The +\fBlibarchive\fP(3) +library can read most tar archives. +However, it only writes POSIX-standard +``ustar'' +and +``pax interchange'' +formats. +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. +.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. +The presence of this additional entry 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. +The libarchive library can read most of the SCHILY keys. +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: +.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 2 gigabytes in size. +Note that the pax interchange format has none of these restrictions. +The libarchive library can also read a variety of commonly-used extensions to +the basic tar format. +In particular, it supports base-256 values in certain numeric fields. +This essentially removes the limitations on file size, modification time, +and device numbers. +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 tar, cpio does only minimal padding of the header or file data. +There are a variety of cpio formats, 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. +.TP +\fBbinary\fP +The libarchive library can read 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. +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. +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 +\fBfind\fP +and +\fBcpio\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: +.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. +.SS ISO9660 format +Libarchive can read and extract from files containing ISO9660-compliant +CDROM images. +It also has partial support for Rockridge extensions. +In many cases, this can remove the need to burn a physical CDROM. +It also avoids security and complexity issues that come with +virtual mounts and loopback devices. +.SS Zip format +Libarchive can extract from most zip format archives. +It currently only supports uncompressed entries and entries +compressed with the +``deflate'' +algorithm. +Older zip compression algorithms are not supported. +.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. +Libarchive provides read and write support for both variants. +.SS mtree +Libarchive can read files in +\fBmtree\fP(5) +format. This format is not a true archive format, but rather a description +of a file hierarchy. When requested, libarchive obtains the contents of +the files described by the +\fBmtree\fP(5) +format from files on disk instead. +.SH SEE ALSO +\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.5.5/doc/man/libarchive.3 b/libarchive/libarchive-2.5.5/doc/man/libarchive.3 new file mode 100644 index 0000000..722b765 --- /dev/null +++ b/libarchive/libarchive-2.5.5/doc/man/libarchive.3 @@ -0,0 +1,379 @@ +.TH LIBARCHIVE 3 "August 19, 2006" "" +.SH NAME +\fBlibarchive\fP +\- functions for reading and writing streaming archives +.SH LIBRARY +Lb libarchive +.SH OVERVIEW +The +\fBlibarchive\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. +When reading an archive, the library automatically detects the +format and the compression. +The library currently has read support for: +.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. +The library automatically detects archives compressed with +\fBgzip\fP(1), +\fBbzip2\fP(1), +or +\fBcompress\fP(1) +and decompresses them transparently. +When writing an archive, you can specify the compression +to be used and the format to use. +The library can write +.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. +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. +The read and write APIs are accessed through the +.nh +\fBarchive_read_XXX\fP +.hy +(); +functions and the +.nh +\fBarchive_write_XXX\fP +.hy +(); +functions, respectively, and either can be used independently +of the other. +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 +To read an archive, you must first obtain an initialized +Tn struct archive +object from +.nh +\fBarchive_read_new\fP +.hy +(.); +You can then modify this object for the desired operations with the +various +.nh +\fBarchive_read_set_XXX\fP +.hy +(); +and +.nh +\fBarchive_read_support_XXX\fP +.hy +(); +functions. +In particular, you will need to invoke appropriate +.nh +\fBarchive_read_support_XXX\fP +.hy +(); +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 +.nh +\fBarchive_read_support_compression_all\fP +.hy +(); +and +.nh +\fBarchive_read_support_format_all\fP +.hy +(); +to enable auto-detect for all formats and compression types +currently supported by the library. +Once you have prepared the +Tn struct archive +object, you call +.nh +\fBarchive_read_open\fP +.hy +(); +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, +\fI"FILE *"\fP +.RE +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. +Each archive entry consists of a header followed by a certain +amount of data. +You can obtain the next header with +.nh +\fBarchive_read_next_header\fP +.hy +(,); +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 +.nh +\fBarchive_read_data\fP +.hy +(); +(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 +.nh +\fBarchive_read_data_skip\fP +.hy +(,); +which reads and discards the data for this entry, +.nh +\fBarchive_read_data_to_buffer\fP +.hy +(,); +which reads the data into an in-memory buffer, +.nh +\fBarchive_read_data_to_file\fP +.hy +(,); +which copies the data to the provided file descriptor, or +.nh +\fBarchive_read_extract\fP +.hy +(,); +which recreates the specified entry on disk and copies data +from the archive. +In particular, note that +.nh +\fBarchive_read_extract\fP +.hy +(); +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. +Once you have finished reading data from the archive, you +should call +.nh +\fBarchive_read_close\fP +.hy +(); +to close the archive, then call +.nh +\fBarchive_read_finish\fP +.hy +(); +to release all resources, including all memory allocated by the library. +The +\fBarchive_read\fP(3) +manual page provides more detailed calling information for this API. +.SH WRITING AN ARCHIVE +You use a similar process to write an archive. +The +.nh +\fBarchive_write_new\fP +.hy +(); +function creates an archive object useful for writing, +the various +.nh +\fBarchive_write_set_XXX\fP +.hy +(); +functions are used to set parameters for writing the archive, and +.nh +\fBarchive_write_open\fP +.hy +(); +completes the setup and opens the archive for writing. +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 +.nh +\fBarchive_write_header\fP +.hy +(); +function actually writes the header data to the archive. +You can then use +.nh +\fBarchive_write_data\fP +.hy +(); +to write the actual data. +After all entries have been written, use the +.nh +\fBarchive_write_finish\fP +.hy +(); +function to release all resources. +The +\fBarchive_write\fP(3) +manual page provides more detailed calling information for this API. +.SH DESCRIPTION +Detailed descriptions of each function are provided by the +corresponding manual pages. +All of the functions utilize an opaque +Tn struct archive +datatype that provides access to the archive contents. +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). +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 +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 +.nh +\fBarchive_errno\fP +.hy +(); +function can be used to retrieve a numeric error code (see +\fBerrno\fP(2)). +The +.nh +\fBarchive_error_string\fP +.hy +(); +returns a textual error message suitable for display. +.nh +\fBarchive_read_new\fP +.hy +(); +and +.nh +\fBarchive_write_new\fP +.hy +(); +return pointers to an allocated and initialized +Tn struct archive +object. +.nh +\fBarchive_read_data\fP +.hy +(); +and +.nh +\fBarchive_write_data\fP +.hy +(); +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 +.nh +\fBarchive_errno\fP +.hy +(); +and +.nh +\fBarchive_error_string\fP +.hy +(); +functions can be used to obtain more information. +.SH ENVIRONMENT +There are character set conversions within the +\fBarchive_entry\fP(3) +functions that are impacted by the currently-selected locale. +.SH SEE ALSO +\fBtar\fP(1), +\fBarchive_entry\fP(3), +\fBarchive_read\fP(3), +\fBarchive_util\fP(3), +\fBarchive_write\fP(3), +\fBtar\fP(5) +.SH HISTORY +The +\fBlibarchive\fP +library first appeared in +FreeBSD 5.3. +.SH AUTHORS +-nosplit +The +\fBlibarchive\fP +library was written by +Tim Kientzle <kientzle@acm.org.> +.SH BUGS +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. +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.5.5/doc/man/libarchive_internals.3 b/libarchive/libarchive-2.5.5/doc/man/libarchive_internals.3 new file mode 100644 index 0000000..fae95d8 --- /dev/null +++ b/libarchive/libarchive-2.5.5/doc/man/libarchive_internals.3 @@ -0,0 +1,358 @@ +.TH LIBARCHIVE 3 "April 16, 2007" "" +.SH NAME +\fBlibarchive_internals\fP +\- description of libarchive internal interfaces +.SH OVERVIEW +The +\fBlibarchive\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 +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.) +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. +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 +From the outside, clients use the +\fBarchive_read\fP(3) +API to manipulate an +\fBarchive\fP +object to read entries and bodies from an archive stream. +Internally, the +\fBarchive\fP +object is cast to an +\fBarchive_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 +\fBarchive_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. +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. +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. +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. +A subsequent call to the +.nh +\fBconsume\fP +.hy +(); +function advances the read pointer. +Note that data returned from a +.nh +\fBread_ahead\fP +.hy +(); +call is guaranteed to remain in place until +the next call to +.nh +\fBread_ahead\fP +.hy +(.); +Intervening calls to +.nh +\fBconsume\fP +.hy +(); +should not cause the data to move. +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. +A decompression handler has a specific lifecycle: +.TP +Registration/Configuration +When the client invokes the public support function, +the decompression handler invokes the internal +.nh +\fB__archive_read_register_compression\fP +.hy +(); +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. +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. +.SS Format Layer +The read formats have a similar lifecycle to the decompression handlers: +.TP +Registration +Allocate your private data and initialize your pointers. +.TP +Bid +Formats bid by invoking the +.nh +\fBread_ahead\fP +.hy +(); +decompression method but not calling the +.nh +\fBconsume\fP +.hy +(); +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 +.nh +\fBdata_skip\fP +.hy +(); +function. +.TP +Cleanup +On cleanup, the format should release all of its allocated memory. +.SS API Layer +XXX to do XXX +.SH WRITE ARCHITECTURE +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 +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 +The +\fBarchive_read\fP, +\fBarchive_write\fP, +and +\fBarchive_write_disk\fP +objects all contain an initial +\fBarchive\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 +\fBarchive\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 +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. +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. +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 +\fBarchive\fP(3), +\fBarchive_entry\fP(3), +\fBarchive_read\fP(3), +\fBarchive_write\fP(3), +\fBarchive_write_disk\fP(3) +.SH HISTORY +The +\fBlibarchive\fP +library first appeared in +FreeBSD 5.3. +.SH AUTHORS +-nosplit +The +\fBlibarchive\fP +library was written by +Tim Kientzle <kientzle@acm.org.> +.SH BUGS diff --git a/libarchive/libarchive-2.5.5/doc/man/mtree.5 b/libarchive/libarchive-2.5.5/doc/man/mtree.5 new file mode 100644 index 0000000..0f4c255 --- /dev/null +++ b/libarchive/libarchive-2.5.5/doc/man/mtree.5 @@ -0,0 +1,263 @@ +.TH MTREE 5 "August 20, 2007" "" +.SH NAME +\fBmtree\fP +\- format of mtree dir hierarchy files +.SH DESCRIPTION +The +\fBmtree\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 +\fBmtree\fP +file consists of a series of lines, each providing information +about a single filesystem object. +Leading whitespace is always ignored. +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. +Each line is interpreted independently as one of the following types: +.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. +Some tools that process +\fBmtree\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: +.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. +.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. +Currently supported keywords are as follows: +.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: +.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 +.TP +\fBuid\fP +The file owner as a numeric value. +.TP +\fBuname\fP +The file owner as a symbolic name. +.SH SEE ALSO +\fBcksum\fP(1), +\fBfind\fP(1), +\fBmtree\fP(8) +.SH BUGS +The +FreeBSD +implementation of mtree does not currently support +the +\fBmtree\fP +2.0 +format. +The requirement for a +``#mtree'' +signature line is new and not yet widely implemented. +.SH HISTORY +The +\fBmtree\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.5.5/doc/man/tar.5 b/libarchive/libarchive-2.5.5/doc/man/tar.5 new file mode 100644 index 0000000..4901e2c --- /dev/null +++ b/libarchive/libarchive-2.5.5/doc/man/tar.5 @@ -0,0 +1,725 @@ +.TH TAR 5 "May 20, 2004" "" +.SH NAME +\fBtar\fP +\- format of tape archive files +.SH DESCRIPTION +The +\fBtar\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 +\fBtar\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. +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 most common block size\(emand the maximum supported by historic +implementations\(emis 10240 bytes or 20 records. +(Note: the terms +``block'' +and +``record'' +here are not entirely standard; this document follows the +convention established by John Gilmore in documenting +\fBpdtar\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 is one of the earliest widely-used versions of the tar program. +The header record for an old-style +\fBtar\fP +archive consists of the following: +.RS +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. +.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.) +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 +\fBpdtar\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: +.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. +.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 +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 +.TP +\fItypeflag\fP +Type of entry. +POSIX extended the earlier +\fIlinkflag\fP +field with several new type values: +.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. +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 +\fIprefix\fP +First part of pathname. +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 here. +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. +Note that all unused bytes must be set to +.BR NUL. +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 allows +them to be terminated with either space or +.BR NUL +characters. +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. +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 +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: +.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 +\fBstar\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.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 +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. +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. +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 +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 +.TP +\fItypeflag\fP +GNU tar uses the following special entry types, in addition to +those defined by POSIX: +.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. +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. +FreeBSD's version of GNU tar does not handle the corner case of an +archive's being continued in the middle of a long name or other +extension header. +.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. +.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. +.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 +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. +.SS Solaris Tar +XXX More Details Needed XXX +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: +.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 +(whose value is 01000000 plus the number of ACL entries) +followed by a zero byte, followed by the +textual ACL description. +.SS Other Extensions +One common extension, utilized by GNU tar, star, and other newer +\fBtar\fP +implementations, permits binary numbers in the standard numeric +fields. +This is flagged by setting the high bit of the first character. +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. +Another early GNU extension allowed base-64 values rather +than octal. +This extension was short-lived and such archives are almost never seen. +However, there is still code in GNU tar to support them; this code is +responsible for a very cryptic warning message that is sometimes seen when +GNU tar encounters a damaged archive. +.SH SEE ALSO +\fBar\fP(1), +\fBpax\fP(1), +\fBtar\fP(1) +.SH STANDARDS +The +\fBtar\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 +A +\fBtar\fP +command appeared in Seventh Edition Unix, which was released in January, 1979. +It replaced the +\fBtp\fP +program from Fourth Edition Unix which in turn replaced the +\fBtap\fP +program from First Edition Unix. +John Gilmore's +\fBpdtar\fP +public-domain implementation (circa 1987) was highly influential +and formed the basis of +\fBGNU\fP tar. +Joerg Shilling's +\fBstar\fP +archiver is another open-source (GPL) archiver (originally developed +circa 1985) which features complete support for pax interchange +format. |