From 16f738ecee689c6feb2acb7e4ef4d9bb4144ae7d Mon Sep 17 00:00:00 2001 From: Tomas Bzatek Date: Sun, 8 Jun 2008 11:04:43 +0200 Subject: Initial commit --- libarchive/libarchive-2.4.17/doc/man/Makefile | 43 ++ .../libarchive-2.4.17/doc/man/archive_entry.3 | 647 ++++++++++++++++ .../libarchive-2.4.17/doc/man/archive_read.3 | 814 +++++++++++++++++++++ .../libarchive-2.4.17/doc/man/archive_util.3 | 204 ++++++ .../libarchive-2.4.17/doc/man/archive_write.3 | 786 ++++++++++++++++++++ .../libarchive-2.4.17/doc/man/archive_write_disk.3 | 464 ++++++++++++ libarchive/libarchive-2.4.17/doc/man/bsdcpio.1 | 330 +++++++++ libarchive/libarchive-2.4.17/doc/man/bsdtar.1 | 778 ++++++++++++++++++++ libarchive/libarchive-2.4.17/doc/man/cpio.5 | 301 ++++++++ .../libarchive-2.4.17/doc/man/libarchive-formats.5 | 239 ++++++ libarchive/libarchive-2.4.17/doc/man/libarchive.3 | 379 ++++++++++ .../doc/man/libarchive_internals.3 | 358 +++++++++ libarchive/libarchive-2.4.17/doc/man/mtree.5 | 264 +++++++ libarchive/libarchive-2.4.17/doc/man/tar.5 | 725 ++++++++++++++++++ libarchive/libarchive-2.4.17/doc/mdoc2man.awk | 328 +++++++++ libarchive/libarchive-2.4.17/doc/text/Makefile | 42 ++ .../libarchive-2.4.17/doc/text/archive_entry.3 | 350 +++++++++ .../libarchive-2.4.17/doc/text/archive_read.3 | 395 ++++++++++ .../libarchive-2.4.17/doc/text/archive_util.3 | 91 +++ .../libarchive-2.4.17/doc/text/archive_write.3 | 420 +++++++++++ .../doc/text/archive_write_disk.3 | 253 +++++++ libarchive/libarchive-2.4.17/doc/text/bsdcpio.1 | 187 +++++ libarchive/libarchive-2.4.17/doc/text/bsdtar.1 | 441 +++++++++++ libarchive/libarchive-2.4.17/doc/text/cpio.5 | 235 ++++++ .../doc/text/libarchive-formats.5 | 180 +++++ libarchive/libarchive-2.4.17/doc/text/libarchive.3 | 185 +++++ .../doc/text/libarchive_internals.3 | 248 +++++++ libarchive/libarchive-2.4.17/doc/text/mtree.5 | 158 ++++ libarchive/libarchive-2.4.17/doc/text/tar.5 | 534 ++++++++++++++ libarchive/libarchive-2.4.17/doc/update.sh | 47 ++ 30 files changed, 10426 insertions(+) create mode 100644 libarchive/libarchive-2.4.17/doc/man/Makefile create mode 100644 libarchive/libarchive-2.4.17/doc/man/archive_entry.3 create mode 100644 libarchive/libarchive-2.4.17/doc/man/archive_read.3 create mode 100644 libarchive/libarchive-2.4.17/doc/man/archive_util.3 create mode 100644 libarchive/libarchive-2.4.17/doc/man/archive_write.3 create mode 100644 libarchive/libarchive-2.4.17/doc/man/archive_write_disk.3 create mode 100644 libarchive/libarchive-2.4.17/doc/man/bsdcpio.1 create mode 100644 libarchive/libarchive-2.4.17/doc/man/bsdtar.1 create mode 100644 libarchive/libarchive-2.4.17/doc/man/cpio.5 create mode 100644 libarchive/libarchive-2.4.17/doc/man/libarchive-formats.5 create mode 100644 libarchive/libarchive-2.4.17/doc/man/libarchive.3 create mode 100644 libarchive/libarchive-2.4.17/doc/man/libarchive_internals.3 create mode 100644 libarchive/libarchive-2.4.17/doc/man/mtree.5 create mode 100644 libarchive/libarchive-2.4.17/doc/man/tar.5 create mode 100644 libarchive/libarchive-2.4.17/doc/mdoc2man.awk create mode 100644 libarchive/libarchive-2.4.17/doc/text/Makefile create mode 100644 libarchive/libarchive-2.4.17/doc/text/archive_entry.3 create mode 100644 libarchive/libarchive-2.4.17/doc/text/archive_read.3 create mode 100644 libarchive/libarchive-2.4.17/doc/text/archive_util.3 create mode 100644 libarchive/libarchive-2.4.17/doc/text/archive_write.3 create mode 100644 libarchive/libarchive-2.4.17/doc/text/archive_write_disk.3 create mode 100644 libarchive/libarchive-2.4.17/doc/text/bsdcpio.1 create mode 100644 libarchive/libarchive-2.4.17/doc/text/bsdtar.1 create mode 100644 libarchive/libarchive-2.4.17/doc/text/cpio.5 create mode 100644 libarchive/libarchive-2.4.17/doc/text/libarchive-formats.5 create mode 100644 libarchive/libarchive-2.4.17/doc/text/libarchive.3 create mode 100644 libarchive/libarchive-2.4.17/doc/text/libarchive_internals.3 create mode 100644 libarchive/libarchive-2.4.17/doc/text/mtree.5 create mode 100644 libarchive/libarchive-2.4.17/doc/text/tar.5 create mode 100755 libarchive/libarchive-2.4.17/doc/update.sh (limited to 'libarchive/libarchive-2.4.17/doc') diff --git a/libarchive/libarchive-2.4.17/doc/man/Makefile b/libarchive/libarchive-2.4.17/doc/man/Makefile new file mode 100644 index 0000000..c33aac4 --- /dev/null +++ b/libarchive/libarchive-2.4.17/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.4.17/doc/man/archive_entry.3 b/libarchive/libarchive-2.4.17/doc/man/archive_entry.3 new file mode 100644 index 0000000..a3548c2 --- /dev/null +++ b/libarchive/libarchive-2.4.17/doc/man/archive_entry.3 @@ -0,0 +1,647 @@ +.TH archive_entry 3 "December 15, 2003" "" +.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_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_pathname_w\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_stat\fP, +\fBarchive_entry_symlink\fP, +\fBarchive_entry_uid\fP, +\fBarchive_entry_uname\fP +\- functions for manipulating archive entry descriptions +.SH SYNOPSIS +\fB#include \fP +.br +\fIvoid\fP +.RE +.nh +\fBarchive_entry_acl_add_entry\fP +.hy +("struct archive_entry *" "int type" "int permset" "int tag" "int qual" "const char *name"); +\fIvoid\fP +.RE +.nh +\fBarchive_entry_acl_add_entry_w\fP +.hy +("struct archive_entry *" "int type" "int permset" "int tag" "int qual" "const wchar_t *name"); +\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 +.nh +\fBarchive_entry_acl_next\fP +.hy +("struct archive_entry *" "int want_type" "int *type" "int *permset" "int *tag" "int *qual" "const char **name"); +\fIint\fP +.RE +.nh +\fBarchive_entry_acl_next_w\fP +.hy +("struct archive_entry *" "int want_type" "int *type" "int *permset" "int *tag" "int *qual" "const wchar_t **name"); +\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 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_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 +.nh +\fBarchive_entry_fflags\fP +.hy +("struct archive_entry *" "unsigned long *set" "unsigned long *clear"); +\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 +.nh +\fBarchive_entry_set_fflags\fP +.hy +("struct archive_entry *" "unsigned long set" "unsigned long clear"); +\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 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_w\fP +.hy +(); +function parses 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 diff --git a/libarchive/libarchive-2.4.17/doc/man/archive_read.3 b/libarchive/libarchive-2.4.17/doc/man/archive_read.3 new file mode 100644 index 0000000..524c5a8 --- /dev/null +++ b/libarchive/libarchive-2.4.17/doc/man/archive_read.3 @@ -0,0 +1,814 @@ +.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_extract_set_progress_callback\fP, +\fBarchive_read_close\fP, +\fBarchive_read_finish\fP +\- functions for reading streaming archives +.SH SYNOPSIS +\fB#include \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 +.nh +\fBarchive_read_support_compression_program\fP +.hy +("struct archive *" "const char *cmd"); +\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 +.nh +\fBarchive_read_open\fP +.hy +("struct archive *" "void *client_data" "archive_open_callback *" "archive_read_callback *" "archive_close_callback *"); +\fIint\fP +.RE +.nh +\fBarchive_read_open2\fP +.hy +("struct archive *" "void *client_data" "archive_open_callback *" "archive_read_callback *" "archive_skip_callback *" "archive_close_callback *"); +\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 +.nh +\fBarchive_read_open_filename\fP +.hy +("struct archive *" "const char *filename" "size_t block_size"); +\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 +.nh +\fBarchive_read_data_block\fP +.hy +("struct archive *" "const void **buff" "size_t *len" "off_t *offset"); +\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 +.nh +\fBarchive_read_extract\fP +.hy +("struct archive *" "struct archive_entry *" "int flags"); +\fIvoid\fP +.RE +.nh +\fBarchive_read_extract_set_progress_callback\fP +.hy +("struct archive *" "void (*func)(void *)" "void *user_data"); +\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 +.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 +(); +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 +.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 +(); +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_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 +.nh +\fBarchive_read_callback\fP +.hy +("struct archive *" "void *client_data" "const void **buffer"); +.IP +\fItypedef int\fP +.RE +.nh +\fBarchive_skip_callback\fP +.hy +("struct archive *" "void *client_data" "size_t request"); +.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 +.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.4.17/doc/man/archive_util.3 b/libarchive/libarchive-2.4.17/doc/man/archive_util.3 new file mode 100644 index 0000000..e41c59f --- /dev/null +++ b/libarchive/libarchive-2.4.17/doc/man/archive_util.3 @@ -0,0 +1,204 @@ +.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 \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 +.nh +\fBarchive_set_error\fP +.hy +("struct archive *" "int error_code" "const char *fmt" "..."); +.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 diff --git a/libarchive/libarchive-2.4.17/doc/man/archive_write.3 b/libarchive/libarchive-2.4.17/doc/man/archive_write.3 new file mode 100644 index 0000000..c4b9395 --- /dev/null +++ b/libarchive/libarchive-2.4.17/doc/man/archive_write.3 @@ -0,0 +1,786 @@ +.TH archive_write 3 "August 19, 2006" "" +.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_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 \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_gzip\fP +.hy +("struct archive *"); +\fIint\fP +.RE +.nh +\fBarchive_write_set_compression_none\fP +.hy +("struct archive *"); +\fIint\fP +.RE +.nh +\fBarchive_write_set_compression_program\fP +.hy +("struct archive *" "const char * cmd"); +\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 +.nh +\fBarchive_write_open\fP +.hy +("struct archive *" "void *client_data" "archive_open_callback *" "archive_write_callback *" "archive_close_callback *"); +\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 +.nh +\fBarchive_write_open_memory\fP +.hy +("struct archive *" "void *buffer" "size_t bufferSize" "size_t *outUsed"); +\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 +.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 +(); +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 +.nh +\fBarchive_write_set_compression_bzip2\fP +.hy +(, .nh); +\fBarchive_write_set_compression_gzip\fP +.hy +(, .nh); +\fBarchive_write_set_compression_none\fP +.hy +(); +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 +.nh +\fBarchive_write_callback\fP +.hy +("struct archive *" "void *client_data" "void *buffer" "size_t length"); +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 +#include +#include +#include +#include +#include +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 +.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.4.17/doc/man/archive_write_disk.3 b/libarchive/libarchive-2.4.17/doc/man/archive_write_disk.3 new file mode 100644 index 0000000..4e81e1c --- /dev/null +++ b/libarchive/libarchive-2.4.17/doc/man/archive_write_disk.3 @@ -0,0 +1,464 @@ +.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 \fP +.br +\fIstruct archive *\fP +.RE +.nh +\fBarchive_write_disk_new\fP +.hy +("void"); +\fIint\fP +.RE +.nh +\fBarchive_write_disk_set_options\fP +.hy +("struct archive *" "int flags"); +\fIint\fP +.RE +.nh +\fBarchive_write_disk_set_skip_file\fP +.hy +("struct archive *" "dev_t" "ino_t"); +\fIint\fP +.RE +.nh +\fBarchive_write_disk_set_group_lookup\fP +.hy +("struct archive *" "void *" "gid_t (*)(void *, const char *gname, gid_t gid)" "void (*cleanup)(void *)"); +\fIint\fP +.RE +.nh +\fBarchive_write_disk_set_standard_lookup\fP +.hy +("struct archive *"); +\fIint\fP +.RE +.nh +\fBarchive_write_disk_set_user_lookup\fP +.hy +("struct archive *" "void *" "uid_t (*)(void *, const char *uname, uid_t uid)" "void (*cleanup)(void *)"); +\fIint\fP +.RE +.nh +\fBarchive_write_header\fP +.hy +("struct archive *" "struct archive_entry *"); +\fIssize_t\fP +.RE +.nh +\fBarchive_write_data\fP +.hy +("struct archive *" "const void *" "size_t"); +\fIint\fP +.RE +.nh +\fBarchive_write_finish_entry\fP +.hy +("struct archive *"); +\fIint\fP +.RE +.nh +\fBarchive_write_close\fP +.hy +("struct archive *"); +\fIint\fP +.RE +.nh +\fBarchive_write_finish\fP +.hy +("struct archive *"); +.SH DESCRIPTION +These functions provide a complete API for creating objects on +disk from +Tn struct archive_entry +descriptions. +They are most naturally used when extracting objects from an archive +using the +.nh +\fBarchive_read\fP +.hy +(); +interface. +The general process is to read +Tn struct archive_entry +objects from an archive, then write those objects to a +Tn struct archive +object created using the +.nh +\fBarchive_write_disk\fP +.hy +(); +family functions. +This interface is deliberately very similar to the +.nh +\fBarchive_write\fP +.hy +(); +interface used to write objects to a streaming archive. +.TP +.nh +\fBarchive_write_disk_new\fP +.hy +(); +Allocates and initializes a +Tn struct archive +object suitable for writing objects to disk. +.TP +.nh +\fBarchive_write_disk_set_skip_file\fP +.hy +(); +Records the device and inode numbers of a file that should not be +overwritten. +This is typically used to ensure that an extraction process does not +overwrite the archive from which objects are being read. +This capability is technically unnecessary but can be a significant +performance optimization in practice. +.TP +.nh +\fBarchive_write_disk_set_options\fP +.hy +(); +The options field consists of a bitwise OR of one or more of the +following values: +.TP +\fBARCHIVE_EXTRACT_OWNER\fP +The user and group IDs should be set on the restored file. +By default, the user and group IDs are not restored. +.TP +\fBARCHIVE_EXTRACT_PERM\fP +Full permissions (including SGID, SUID, and sticky bits) should +be restored exactly as specified, without obeying the +current umask. +Note that SUID and SGID bits can only be restored if the +user and group ID of the object on disk are correct. +If +\fBARCHIVE_EXTRACT_OWNER\fP +is not specified, then SUID and SGID bits will only be restored +if the default user and group IDs of newly-created objects on disk +happen to match those specified in the archive entry. +By default, only basic permissions are restored, and umask is obeyed. +.TP +\fBARCHIVE_EXTRACT_TIME\fP +The timestamps (mtime, ctime, and atime) should be restored. +By default, they are ignored. +Note that restoring of atime is not currently supported. +.TP +\fBARCHIVE_EXTRACT_NO_OVERWRITE\fP +Existing files on disk will not be overwritten. +By default, existing regular files are truncated and overwritten; +existing directories will have their permissions updated; +other pre-existing objects are unlinked and recreated from scratch. +.TP +\fBARCHIVE_EXTRACT_UNLINK\fP +Existing files on disk will be unlinked before any attempt to +create them. +In some cases, this can prove to be a significant performance improvement. +By default, existing files are truncated and rewritten, but +the file is not recreated. +In particular, the default behavior does not break existing hard links. +.TP +\fBARCHIVE_EXTRACT_ACL\fP +Attempt to restore ACLs. +By default, extended ACLs are ignored. +.TP +\fBARCHIVE_EXTRACT_FFLAGS\fP +Attempt to restore extended file flags. +By default, file flags are ignored. +.TP +\fBARCHIVE_EXTRACT_XATTR\fP +Attempt to restore POSIX.1e extended attributes. +By default, they are ignored. +.TP +\fBARCHIVE_EXTRACT_SECURE_SYMLINKS\fP +Refuse to extract any object whose final location would be altered +by a symlink on disk. +This is intended to help guard against a variety of mischief +caused by archives that (deliberately or otherwise) extract +files outside of the current directory. +The default is not to perform this check. +If +\fBARCHIVE_EXTRACT_UNLINK\fP +is specified together with this option, the library will +remove any intermediate symlinks it finds and return an +error only if such symlink could not be removed. +.TP +\fBARCHIVE_EXTRACT_SECURE_NODOTDOT\fP +Refuse to extract a path that contains a +\fI\& ..\fP +element anywhere within it. +The default is to not refuse such paths. +Note that paths ending in +\fI\& ..\fP +always cause an error, regardless of this flag. +.TP +.nh +\fBarchive_write_disk_set_group_lookup\fP +.hy +(, .nh); +\fBarchive_write_disk_set_user_lookup\fP +.hy +(); +The +Tn struct archive_entry +objects contain both names and ids that can be used to identify users +and groups. +These names and ids describe the ownership of the file itself and +also appear in ACL lists. +By default, the library uses the ids and ignores the names, but +this can be overridden by registering user and group lookup functions. +To register, you must provide a lookup function which +accepts both a name and id and returns a suitable id. +You may also provide a +Tn void * +pointer to a private data structure and a cleanup function for +that data. +The cleanup function will be invoked when the +Tn struct archive +object is destroyed. +.TP +.nh +\fBarchive_write_disk_set_standard_lookup\fP +.hy +(); +This convenience function installs a standard set of user +and group lookup functions. +These functions use +\fBgetpwnam\fP(3) +and +\fBgetgrnam\fP(3) +to convert names to ids, defaulting to the ids if the names cannot +be looked up. +These functions also implement a simple memory cache to reduce +the number of calls to +\fBgetpwnam\fP(3) +and +\fBgetgrnam\fP(3). +.TP +.nh +\fBarchive_write_header\fP +.hy +(); +Build and write a header using the data in the provided +Tn struct archive_entry +structure. +See +\fBarchive_entry\fP(3) +for information on creating and populating +Tn struct archive_entry +objects. +.TP +.nh +\fBarchive_write_data\fP +.hy +(); +Write data corresponding to the header just written. +Returns number of bytes written or -1 on error. +.TP +.nh +\fBarchive_write_finish_entry\fP +.hy +(); +Close out the entry just written. +Ordinarily, clients never need to call this, as it +is called automatically by +.nh +\fBarchive_write_next_header\fP +.hy +(); +and +.nh +\fBarchive_write_close\fP +.hy +(); +as needed. +.TP +.nh +\fBarchive_write_close\fP +.hy +(); +Set any attributes that could not be set during the initial restore. +For example, directory timestamps are not restored initially because +restoring a subsequent file would alter that timestamp. +Similarly, non-writable directories are initially created with +write permissions (so that their contents can be restored). +The +\fBarchive_write_disk_new\fP +library maintains a list of all such deferred attributes and +sets them when this function is invoked. +.TP +.nh +\fBarchive_write_finish\fP +.hy +(); +Invokes +.nh +\fBarchive_write_close\fP +.hy +(); +if it was not invoked manually, then releases all resources. +More information about the +\fIstruct\fP archive +object and the overall design of the library can be found in the +\fBlibarchive\fP(3) +overview. +Many of these functions are also documented under +\fBarchive_write\fP(3). +.SH RETURN VALUES +Most functions return +\fBARCHIVE_OK\fP +(zero) on success, or one of several non-zero +error codes for errors. +Specific error codes include: +\fBARCHIVE_RETRY\fP +for operations that might succeed if retried, +\fBARCHIVE_WARN\fP +for unusual conditions that do not prevent further operations, and +\fBARCHIVE_FATAL\fP +for serious errors that make remaining operations impossible. +The +.nh +\fBarchive_errno\fP +.hy +(); +and +.nh +\fBarchive_error_string\fP +.hy +(); +functions can be used to retrieve an appropriate error code and a +textual error message. +.nh +\fBarchive_write_disk_new\fP +.hy +(); +returns a pointer to a newly-allocated +Tn struct archive +object. +.nh +\fBarchive_write_data\fP +.hy +(); +returns a count of the number of bytes actually written. +On error, -1 is returned and the +.nh +\fBarchive_errno\fP +.hy +(); +and +.nh +\fBarchive_error_string\fP +.hy +(); +functions will return appropriate values. +.SH SEE ALSO +\fBarchive_read\fP(3), +\fBarchive_write\fP(3), +\fBtar\fP(1), +\fBlibarchive\fP(3) +.SH HISTORY +The +\fBlibarchive\fP +library first appeared in +FreeBSD 5.3. +The +\fBarchive_write_disk\fP +interface was added to +\fBlibarchive\fP 2.0 +and first appeared in +FreeBSD 6.3. +.SH AUTHORS +-nosplit +The +\fBlibarchive\fP +library was written by +Tim Kientzle +.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.4.17/doc/man/bsdcpio.1 b/libarchive/libarchive-2.4.17/doc/man/bsdcpio.1 new file mode 100644 index 0000000..26c5c1d --- /dev/null +++ b/libarchive/libarchive-2.4.17/doc/man/bsdcpio.1 @@ -0,0 +1,330 @@ +.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 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 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 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 +(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\-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 +Input mode. +See above for description. +.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 +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 to stdout. +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 gzip-compatible compression before writing +it to stdout. +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.4.17/doc/man/bsdtar.1 b/libarchive/libarchive-2.4.17/doc/man/bsdtar.1 new file mode 100644 index 0000000..b0e4523 --- /dev/null +++ b/libarchive/libarchive-2.4.17/doc/man/bsdtar.1 @@ -0,0 +1,778 @@ +.TH BSDTAR 1 "April 13, 2004" "" +.SH NAME +\fBtar\fP +\- manipulate tape archives +.SH SYNOPSIS +.br +\fBtar\fP +[\fIbundled-flags\fP ] +[<\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\--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 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. +.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\--fast-read\fP (\fB\-W\fP \fBfast-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\-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\-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\-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 only) +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\--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\--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\-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. +.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. +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), +\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.4.17/doc/man/cpio.5 b/libarchive/libarchive-2.4.17/doc/man/cpio.5 new file mode 100644 index 0000000..a77d96b --- /dev/null +++ b/libarchive/libarchive-2.4.17/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 NULL 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 NULL byte is added after the pathname. +The file data is then appended, padded with NULL +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 +NULL 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 NULL 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.4.17/doc/man/libarchive-formats.5 b/libarchive/libarchive-2.4.17/doc/man/libarchive-formats.5 new file mode 100644 index 0000000..1e88dd2 --- /dev/null +++ b/libarchive/libarchive-2.4.17/doc/man/libarchive-formats.5 @@ -0,0 +1,239 @@ +.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. +.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.4.17/doc/man/libarchive.3 b/libarchive/libarchive-2.4.17/doc/man/libarchive.3 new file mode 100644 index 0000000..722b765 --- /dev/null +++ b/libarchive/libarchive-2.4.17/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 +.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.4.17/doc/man/libarchive_internals.3 b/libarchive/libarchive-2.4.17/doc/man/libarchive_internals.3 new file mode 100644 index 0000000..fae95d8 --- /dev/null +++ b/libarchive/libarchive-2.4.17/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 +.SH BUGS diff --git a/libarchive/libarchive-2.4.17/doc/man/mtree.5 b/libarchive/libarchive-2.4.17/doc/man/mtree.5 new file mode 100644 index 0000000..10ad85b --- /dev/null +++ b/libarchive/libarchive-2.4.17/doc/man/mtree.5 @@ -0,0 +1,264 @@ +.TH MTREE 5 "August 20, 2007" "" +.SH NAME +\fBmtree\fP +\- format of mtree dir heirarchy 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 heirarchies. +.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 definitions 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 whose contents should be +compared to 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 +\fBignore\fP +Ignore any file hierarchy below this file. +.TP +\fBgid\fP +The file group as a numeric value. +.TP +\fBgname\fP +The file group as a symbolic name. +.TP +\fBmd5\fP +The MD5 message digest of the file. +.TP +\fBmd5digest\fP +A synonym for +\fBmd5\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 +\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 +\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 +\fBuid\fP +The file owner as a numeric value. +.TP +\fBuname\fP +The file owner as a symbolic name. +.TP +\fBsize\fP +The size, in bytes, of the file. +.TP +\fBlink\fP +The file the symbolic link is expected to reference. +.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 +.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.4.17/doc/man/tar.5 b/libarchive/libarchive-2.4.17/doc/man/tar.5 new file mode 100644 index 0000000..3b4414f --- /dev/null +++ b/libarchive/libarchive-2.4.17/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. +NULL 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 NULL 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 NULL. +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 NULL. +The +\fIpathname\fP, +\fIlinkname\fP, +and +\fIprefix\fP +fields must have a trailing +.BR NULL +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 NULL +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. diff --git a/libarchive/libarchive-2.4.17/doc/mdoc2man.awk b/libarchive/libarchive-2.4.17/doc/mdoc2man.awk new file mode 100644 index 0000000..c71e528 --- /dev/null +++ b/libarchive/libarchive-2.4.17/doc/mdoc2man.awk @@ -0,0 +1,328 @@ +#!/usr/bin/awk +# +# Copyright (c) 2003 Peter Stuge +# +# Permission to use, copy, modify, and distribute this software for any +# purpose with or without fee is hereby granted, provided that the above +# copyright notice and this permission notice appear in all copies. +# +# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + +# Dramatically overhauled by Tim Kientzle. This version almost +# handles library-style pages with Fn, Ft, etc commands. Still +# a lot of problems... + +BEGIN { + displaylines = 0 + trailer = "" + out = "" + sep = "" + nextsep = " " +} + +# Add a word with appropriate preceding whitespace +# Maintain a short queue of the expected upcoming word separators. +function add(str) { + out=out sep str + sep = nextsep + nextsep = " " +} + +# Add a word with no following whitespace +# Use for opening punctuation such as '(' +function addopen(str) { + add(str) + sep = "" +} + +# Add a word with no preceding whitespace +# Use for closing punctuation such as ')' or '.' +function addclose(str) { + sep = "" + add(str) +} + +# Add a word with no space before or after +# Use for separating punctuation such as '=' +function addpunct(str) { + sep = "" + add(str) + sep = "" +} + +# Emit the current line so far +function endline() { + addclose(trailer) + trailer = "" + if(length(out) > 0) { + print out + out="" + } + if(displaylines > 0) { + displaylines = displaylines - 1 + if (displaylines == 0) + dispend() + } + # First word on next line has no preceding whitespace + sep = "" +} + +function linecmd(cmd) { + endline() + add(cmd) + endline() +} + +function breakline() { + linecmd(".br") +} + +# Start an indented display +function dispstart() { + linecmd(".RS") +} + +# End an indented display +function dispend() { + linecmd(".RE") +} + +# Collect rest of input line +function wtail() { + retval="" + while(w") + } else if(match(words[w],"^Dd$")) { + date=wtail() + next + } else if(match(words[w],"^Dt$")) { + id=wtail() + next + } else if(match(words[w],"^Ox$")) { + add("OpenBSD") + } else if(match(words[w],"^Fx$")) { + add("FreeBSD") + } else if(match(words[w],"^Nx$")) { + add("NetBSD") + } else if(match(words[w],"^St$")) { + if (match(words[w+1], "^-p1003.1$")) { + w++ + add("IEEE Std 1003.1 (``POSIX.1'')") + } else if(match(words[w+1], "^-p1003.1-96$")) { + w++ + add("ISO/IEC 9945-1:1996 (``POSIX.1'')") + } else if(match(words[w+1], "^-p1003.1-88$")) { + w++ + add("IEEE Std 1003.1-1988 (``POSIX.1'')") + } else if(match(words[w+1], "^-p1003.1-2001$")) { + w++ + add("IEEE Std 1003.1-2001 (``POSIX.1'')") + } else if(match(words[w+1], "^-susv2$")) { + w++ + add("Version 2 of the Single UNIX Specification (``SUSv2'')") + } + } else if(match(words[w],"^Ex$")) { + if (match(words[w+1], "^-std$")) { + w++ + add("The \\fB" name "\\fP utility exits 0 on success, and >0 if an error occurs.") + } + } else if(match(words[w],"^Os$")) { + add(".TH " id " \"" date "\" \"" wtail() "\"") + } else if(match(words[w],"^Sh$")) { + add(".SH") + section=words[w+1] + } else if(match(words[w],"^Xr$")) { + add("\\fB" words[++w] "\\fP(" words[++w] ")" words[++w]) + } else if(match(words[w],"^Nm$")) { + if(match(section,"SYNOPSIS")) + breakline() + if(w>1) + n=name + else { + n=words[++w] + if(!length(name)) + name=n + } + if(!length(n)) + n=name + add("\\fB" n "\\fP") + } else if(match(words[w],"^Nd$")) { + add("\\- " wtail()) + } else if(match(words[w],"^Fl$")) { + add("\\fB\\-" words[++w] "\\fP") + } else if(match(words[w],"^Ar$")) { + addopen("\\fI") + if(w==nwords) + add("file ...\\fP") + else { + add(words[++w] "\\fP") + while(match(words[w+1],"^\\|$")) + add(words[++w] " \\fI" words[++w] "\\fP") + } + } else if(match(words[w],"^Cm$")) { + add("\\fB" words[++w] "\\fP") + } else if(match(words[w],"^Op$")) { + addopen("[") + option=1 + trailer="]" trailer + } else if(match(words[w],"^Pp$")) { + endline() + } else if(match(words[w],"^An$")) { + endline() + } else if(match(words[w],"^Ss$")) { + add(".SS") + } else if(match(words[w],"^Ft$")) { + addopen("\\fI") + trailer = "\\fP" trailer + displaylines = 1 + } else if(match(words[w],"^Fn$")) { + # Using '.nh' to suppress hyphenation doesn't really work... + # TODO: Fix this. + add(".nh") + endline() + addopen("\\fB") + w++ + add(words[w]) + addclose("\\fP") + endline() + add(".hy") + endline() + addpunct("(") + # This is broken; Fn should peek ahead and put each double-quoted + # arg in .Ty and be smarter about following punct. + trailer = ");" trailer + } else if(match(words[w],"^Va$")) { + w++ + add("\\fI" words[w] "\\fP") + } else if(match(words[w],"^In$")) { + w++ + add("\\fB#include <" words[w] ">\\fP") + breakline() + } else if(match(words[w],"^Pa$")) { + addopen("\\fI") + w++ + if(match(words[w],"^\\.")) + add("\\&") + add(words[w] "\\fP") + } else if(match(words[w],"^Dv$")) { + add(".BR") + } else if(match(words[w],"^Em|Ev$")) { + add(".IR") + } else if(match(words[w],"^Pq$")) { + addopen("(") + trailer=")" trailer + } else if(match(words[w],"^Aq$")) { + addopen("<") + trailer=">" trailer + } else if(match(words[w],"^Brq$")) { + addopen("{") + trailer="}" trailer + } else if(match(words[w],"^S[xy]$")) { + add(".B " wtail()) + } else if(match(words[w],"^Ic$")) { + add("\\fB") + trailer="\\fP" trailer + } else if(match(words[w],"^Bl$")) { + oldoptlist=optlist + if(match(words[w+1],"-bullet")) + optlist=1 + else if(match(words[w+1],"-enum")) { + optlist=2 + enum=0 + } else if(match(words[w+1],"-tag")) + optlist=3 + else if(match(words[w+1],"-item")) + optlist=4 + else if(match(words[w+1],"-bullet")) + optlist=1 + w=nwords + } else if(match(words[w],"^El$")) { + optlist=oldoptlist + } else if(match(words[w],"^It$")&&optlist) { + if(optlist==1) + add(".IP \\(bu") + else if(optlist==2) + add(".IP " ++enum ".") + else if(optlist==3) { + add(".TP") + endline() + if(match(words[w+1],"^Pa$|^Ev$")) { + add(".B") + w++ + } + } else if(optlist==4) + add(".IP") + } else if(match(words[w],"^[=]$")) { + addpunct(words[w]) + } else if(match(words[w],"^[\[{(]$")) { + addopen(words[w]) + } else if(match(words[w],"^[\\\])}.,;:]$")) { + addclose(words[w]) + } else { + add(words[w]) + } + } + if(match(out,"^\\.[^a-zA-Z]")) + sub("^\\.","",out) + endline() +} diff --git a/libarchive/libarchive-2.4.17/doc/text/Makefile b/libarchive/libarchive-2.4.17/doc/text/Makefile new file mode 100644 index 0000000..a70eb18 --- /dev/null +++ b/libarchive/libarchive-2.4.17/doc/text/Makefile @@ -0,0 +1,42 @@ + +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 + + +archive_entry.3: ../../libarchive/archive_entry.3 + nroff -mdoc ../../libarchive/archive_entry.3 | col -b > archive_entry.3 + +archive_read.3: ../../libarchive/archive_read.3 + nroff -mdoc ../../libarchive/archive_read.3 | col -b > archive_read.3 + +archive_util.3: ../../libarchive/archive_util.3 + nroff -mdoc ../../libarchive/archive_util.3 | col -b > archive_util.3 + +archive_write.3: ../../libarchive/archive_write.3 + nroff -mdoc ../../libarchive/archive_write.3 | col -b > archive_write.3 + +archive_write_disk.3: ../../libarchive/archive_write_disk.3 + nroff -mdoc ../../libarchive/archive_write_disk.3 | col -b > archive_write_disk.3 + +cpio.5: ../../libarchive/cpio.5 + nroff -mdoc ../../libarchive/cpio.5 | col -b > cpio.5 + +libarchive-formats.5: ../../libarchive/libarchive-formats.5 + nroff -mdoc ../../libarchive/libarchive-formats.5 | col -b > libarchive-formats.5 + +libarchive.3: ../../libarchive/libarchive.3 + nroff -mdoc ../../libarchive/libarchive.3 | col -b > libarchive.3 + +libarchive_internals.3: ../../libarchive/libarchive_internals.3 + nroff -mdoc ../../libarchive/libarchive_internals.3 | col -b > libarchive_internals.3 + +mtree.5: ../../libarchive/mtree.5 + nroff -mdoc ../../libarchive/mtree.5 | col -b > mtree.5 + +tar.5: ../../libarchive/tar.5 + nroff -mdoc ../../libarchive/tar.5 | col -b > tar.5 + +bsdtar.1: ../../tar/bsdtar.1 + nroff -mdoc ../../tar/bsdtar.1 | col -b > bsdtar.1 + +bsdcpio.1: ../../cpio/bsdcpio.1 + nroff -mdoc ../../cpio/bsdcpio.1 | col -b > bsdcpio.1 diff --git a/libarchive/libarchive-2.4.17/doc/text/archive_entry.3 b/libarchive/libarchive-2.4.17/doc/text/archive_entry.3 new file mode 100644 index 0000000..5201c4f --- /dev/null +++ b/libarchive/libarchive-2.4.17/doc/text/archive_entry.3 @@ -0,0 +1,350 @@ +archive_entry(3) FreeBSD Library Functions Manual archive_entry(3) + +NAME + archive_entry_acl_add_entry, archive_entry_acl_add_entry_w, + archive_entry_acl_clear, archive_entry_acl_count, archive_entry_acl_next, + archive_entry_acl_next_w, archive_entry_acl_reset, + archive_entry_acl_text_w, archive_entry_atime, archive_entry_atime_nsec, + archive_entry_clear, archive_entry_clone, + archive_entry_copy_fflags_text_w, archive_entry_copy_gname, + archive_entry_copy_gname_w, archive_entry_copy_hardlink, + archive_entry_copy_hardlink_w, archive_entry_copy_pathname_w, + archive_entry_copy_stat, archive_entry_copy_symlink, + archive_entry_copy_symlink_w, archive_entry_copy_uname, + archive_entry_copy_uname_w, archive_entry_dev, archive_entry_devmajor, + archive_entry_devminor, archive_entry_filetype, archive_entry_fflags, + archive_entry_fflags_text, archive_entry_free, archive_entry_gid, + archive_entry_gname, archive_entry_hardlink, archive_entry_ino, + archive_entry_mode, archive_entry_mtime, archive_entry_mtime_nsec, + archive_entry_nlink, archive_entry_new, archive_entry_pathname, + archive_entry_pathname_w, archive_entry_rdev, archive_entry_rdevmajor, + archive_entry_rdevminor, archive_entry_set_atime, + archive_entry_set_ctime, archive_entry_set_dev, + archive_entry_set_devmajor, archive_entry_set_devminor, + archive_entry_set_filetype, archive_entry_set_fflags, + archive_entry_set_gid, archive_entry_set_gname, + archive_entry_set_hardlink, archive_entry_set_link, + archive_entry_set_mode, archive_entry_set_mtime, + archive_entry_set_pathname, archive_entry_set_rdevmajor, + archive_entry_set_rdevminor, archive_entry_set_size, + archive_entry_set_symlink, archive_entry_set_uid, + archive_entry_set_uname, archive_entry_size, archive_entry_stat, + archive_entry_symlink, archive_entry_uid, archive_entry_uname -- func- + tions for manipulating archive entry descriptions + +SYNOPSIS + #include + + void + archive_entry_acl_add_entry(struct archive_entry *, int type, + int permset, int tag, int qual, const char *name); + + void + archive_entry_acl_add_entry_w(struct archive_entry *, int type, + int permset, int tag, int qual, const wchar_t *name); + + void + archive_entry_acl_clear(struct archive_entry *); + + int + archive_entry_acl_count(struct archive_entry *, int type); + + int + archive_entry_acl_next(struct archive_entry *, int want_type, int *type, + int *permset, int *tag, int *qual, const char **name); + + int + archive_entry_acl_next_w(struct archive_entry *, int want_type, + int *type, int *permset, int *tag, int *qual, const wchar_t **name); + + int + archive_entry_acl_reset(struct archive_entry *, int want_type); + + const wchar_t * + archive_entry_acl_text_w(struct archive_entry *, int flags); + + time_t + archive_entry_atime(struct archive_entry *); + + long + archive_entry_atime_nsec(struct archive_entry *); + + struct archive_entry * + archive_entry_clear(struct archive_entry *); + + struct archive_entry * + archive_entry_clone(struct archive_entry *); + + const wchar_t * + archive_entry_copy_fflags_text_w(struct archive_entry *, + const wchar_t *); + + void + archive_entry_copy_gname(struct archive_entry *, const char *); + + void + archive_entry_copy_gname_w(struct archive_entry *, const wchar_t *); + + void + archive_entry_copy_hardlink(struct archive_entry *, const char *); + + void + archive_entry_copy_hardlink_w(struct archive_entry *, const wchar_t *); + + void + archive_entry_copy_pathname_w(struct archive_entry *, const wchar_t *); + + void + archive_entry_copy_stat(struct archive_entry *, const struct stat *); + + void + archive_entry_copy_symlink(struct archive_entry *, const char *); + + void + archive_entry_copy_symlink_w(struct archive_entry *, const wchar_t *); + + void + archive_entry_copy_uname(struct archive_entry *, const char *); + + void + archive_entry_copy_uname_w(struct archive_entry *, const wchar_t *); + + dev_t + archive_entry_dev(struct archive_entry *); + + dev_t + archive_entry_devmajor(struct archive_entry *); + + dev_t + archive_entry_devminor(struct archive_entry *); + + mode_t + archive_entry_filetype(struct archive_entry *); + + void + archive_entry_fflags(struct archive_entry *, unsigned long *set, + unsigned long *clear); + + const char * + archive_entry_fflags_text(struct archive_entry *); + + void + archive_entry_free(struct archive_entry *); + + const char * + archive_entry_gname(struct archive_entry *); + + const char * + archive_entry_hardlink(struct archive_entry *); + + ino_t + archive_entry_ino(struct archive_entry *); + + mode_t + archive_entry_mode(struct archive_entry *); + + time_t + archive_entry_mtime(struct archive_entry *); + + long + archive_entry_mtime_nsec(struct archive_entry *); + + unsigned int + archive_entry_nlink(struct archive_entry *); + + struct archive_entry * + archive_entry_new(void); + + const char * + archive_entry_pathname(struct archive_entry *); + + const wchar_t * + archive_entry_pathname_w(struct archive_entry *); + + dev_t + archive_entry_rdev(struct archive_entry *); + + dev_t + archive_entry_rdevmajor(struct archive_entry *); + + dev_t + archive_entry_rdevminor(struct archive_entry *); + + void + archive_entry_set_dev(struct archive_entry *, dev_t); + + void + archive_entry_set_devmajor(struct archive_entry *, dev_t); + + void + archive_entry_set_devminor(struct archive_entry *, dev_t); + + void + archive_entry_set_filetype(struct archive_entry *, unsigned int); + + void + archive_entry_set_fflags(struct archive_entry *, unsigned long set, + unsigned long clear); + + void + archive_entry_set_gid(struct archive_entry *, gid_t); + + void + archive_entry_set_gname(struct archive_entry *, const char *); + + void + archive_entry_set_hardlink(struct archive_entry *, const char *); + + void + archive_entry_set_ino(struct archive_entry *, unsigned long); + + void + archive_entry_set_link(struct archive_entry *, const char *); + + void + archive_entry_set_mode(struct archive_entry *, mode_t); + + void + archive_entry_set_mtime(struct archive_entry *, time_t, long nanos); + + void + archive_entry_set_nlink(struct archive_entry *, unsigned int); + + void + archive_entry_set_pathname(struct archive_entry *, const char *); + + void + archive_entry_set_rdev(struct archive_entry *, dev_t); + + void + archive_entry_set_rdevmajor(struct archive_entry *, dev_t); + + void + archive_entry_set_rdevminor(struct archive_entry *, dev_t); + + void + archive_entry_set_size(struct archive_entry *, int64_t); + + void + archive_entry_set_symlink(struct archive_entry *, const char *); + + void + archive_entry_set_uid(struct archive_entry *, uid_t); + + void + archive_entry_set_uname(struct archive_entry *, const char *); + + int64_t + archive_entry_size(struct archive_entry *); + + const struct stat * + archive_entry_stat(struct archive_entry *); + + const char * + archive_entry_symlink(struct archive_entry *); + + const char * + archive_entry_uname(struct archive_entry *); + +DESCRIPTION + These functions create and manipulate data objects that represent entries + within an archive. You can think of a struct archive_entry as a heavy- + duty version of struct stat: it includes everything from struct stat plus + associated pathname, textual group and user names, etc. These objects + are used by libarchive(3) to represent the metadata associated with a + particular entry in an archive. + + Create and Destroy + There are functions to allocate, destroy, clear, and copy archive_entry + objects: + archive_entry_clear() + 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. + archive_entry_clone() + A deep copy operation; all text fields are duplicated. + archive_entry_free() + Releases the struct archive_entry object. + archive_entry_new() + Allocate and return a blank struct archive_entry object. + + Set and Get Functions + Most of the functions here set or read entries in an object. Such func- + tions have one of the following forms: + archive_entry_set_XXXX() + Stores the provided data in the object. In particular, for + strings, the pointer is stored, not the referenced string. + archive_entry_copy_XXXX() + As above, except that the referenced data is copied into the + object. + archive_entry_XXXX() + 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 + char strings. The functions that use wide character strings are suffixed + with _w. 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 dis- + carded in favor of the new data. + + There are a few set/get functions that merit additional description: + archive_entry_set_link() + This function sets the symlink field if it is already set. Oth- + erwise, it sets the hardlink field. + + 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 recon- + structed 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 fflagstostr(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 + archive_entry_copy_fflags_text_w() function parses 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 evalu- + ated, and the bitmaps will be set to reflect every name that is recog- + nized. (In particular, this differs from strtofflags(3), which stops + parsing at the first unrecognized name.) + + 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 pro- + vided 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 + +SEE ALSO + archive(3) + +HISTORY + The libarchive library first appeared in FreeBSD 5.3. + +AUTHORS + The libarchive library was written by Tim Kientzle . + +FreeBSD 6.0 December 15, 2003 FreeBSD 6.0 diff --git a/libarchive/libarchive-2.4.17/doc/text/archive_read.3 b/libarchive/libarchive-2.4.17/doc/text/archive_read.3 new file mode 100644 index 0000000..95b8686 --- /dev/null +++ b/libarchive/libarchive-2.4.17/doc/text/archive_read.3 @@ -0,0 +1,395 @@ +archive_read(3) FreeBSD Library Functions Manual archive_read(3) + +NAME + archive_read_new, archive_read_support_compression_all, + archive_read_support_compression_bzip2, + archive_read_support_compression_compress, + archive_read_support_compression_gzip, + archive_read_support_compression_none, + archive_read_support_compression_program, + archive_read_support_format_all, archive_read_support_format_cpio, + archive_read_support_format_empty, archive_read_support_format_iso9660, + archive_read_support_format_tar, archive_read_support_format_zip, + archive_read_open, archive_read_open2, archive_read_open_fd, + archive_read_open_FILE, archive_read_open_filename, + archive_read_open_memory, archive_read_next_header, archive_read_data, + archive_read_data_block, archive_read_data_skip, + archive_read_data_into_buffer, archive_read_data_into_fd, + archive_read_extract, archive_read_extract_set_progress_callback, + archive_read_close, archive_read_finish -- functions for reading stream- + ing archives + +SYNOPSIS + #include + + struct archive * + archive_read_new(void); + + int + archive_read_support_compression_all(struct archive *); + + int + archive_read_support_compression_bzip2(struct archive *); + + int + archive_read_support_compression_compress(struct archive *); + + int + archive_read_support_compression_gzip(struct archive *); + + int + archive_read_support_compression_none(struct archive *); + + int + archive_read_support_compression_program(struct archive *, + const char *cmd); + + int + archive_read_support_format_all(struct archive *); + + int + archive_read_support_format_cpio(struct archive *); + + int + archive_read_support_format_empty(struct archive *); + + int + archive_read_support_format_iso9660(struct archive *); + + int + archive_read_support_format_tar(struct archive *); + + int + archive_read_support_format_zip(struct archive *); + + int + archive_read_open(struct archive *, void *client_data, + archive_open_callback *, archive_read_callback *, + archive_close_callback *); + + int + archive_read_open2(struct archive *, void *client_data, + archive_open_callback *, archive_read_callback *, + archive_skip_callback *, archive_close_callback *); + + int + archive_read_open_FILE(struct archive *, FILE *file); + + int + archive_read_open_fd(struct archive *, int fd, size_t block_size); + + int + archive_read_open_filename(struct archive *, const char *filename, + size_t block_size); + + int + archive_read_open_memory(struct archive *, void *buff, size_t size); + + int + archive_read_next_header(struct archive *, struct archive_entry **); + + ssize_t + archive_read_data(struct archive *, void *buff, size_t len); + + int + archive_read_data_block(struct archive *, const void **buff, size_t *len, + off_t *offset); + + int + archive_read_data_skip(struct archive *); + + int + archive_read_data_into_buffer(struct archive *, void *, ssize_t len); + + int + archive_read_data_into_fd(struct archive *, int fd); + + int + archive_read_extract(struct archive *, struct archive_entry *, + int flags); + + void + archive_read_extract_set_progress_callback(struct archive *, + void (*func)(void *), void *user_data); + + int + archive_read_close(struct archive *); + + int + archive_read_finish(struct archive *); + +DESCRIPTION + These functions provide a complete API for reading streaming archives. + The general process is to first create the 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: + archive_read_new() + Allocates and initializes a struct archive object suitable for + reading from an archive. + archive_read_support_compression_all(), + archive_read_support_compression_bzip2(), + archive_read_support_compression_compress(), + archive_read_support_compression_gzip(), + archive_read_support_compression_none() + Enables auto-detection code and decompression support for the + specified compression. Note that ``none'' is always enabled by + default. For convenience, archive_read_support_compression_all() + enables all available decompression code. + archive_read_support_compression_program() + 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 con- + junction with any other decompression option. + archive_read_support_format_all(), archive_read_support_format_cpio(), + archive_read_support_format_empty(), + archive_read_support_format_iso9660(), + archive_read_support_format_tar,() + archive_read_support_format_zip() + Enables support---including auto-detection code---for the speci- + fied archive format. For example, + archive_read_support_format_tar() enables support for a variety + of standard tar formats, old-style tar, ustar, pax interchange + format, and many common variants. For convenience, + archive_read_support_format_all() enables support for all avail- + able formats. Only empty archives are supported by default. + archive_read_open() + The same as archive_read_open2(), except that the skip callback + is assumed to be NULL. + archive_read_open2() + 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 + archive_read_open_filename(), archive_read_open_FILE(), + archive_read_open_fd(), or archive_read_open_memory() instead. + The library invokes the client-provided functions to obtain raw + bytes from the archive. + archive_read_open_FILE() + Like archive_read_open(), except that it accepts a FILE * + pointer. This function should not be used with tape drives or + other devices that require strict I/O blocking. + archive_read_open_fd() + Like archive_read_open(), except that it accepts a file descrip- + tor 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. + archive_read_open_file() + This is a deprecated synonym for archive_read_open_filename(). + archive_read_open_filename() + Like archive_read_open(), except that it accepts a simple file- + name and a block size. A NULL filename represents standard + input. This function is safe for use with tape drives or other + blocked devices. + archive_read_open_memory() + Like archive_read_open(), except that it accepts a pointer and + size of a block of memory containing the archive data. + archive_read_next_header() + Read the header for the next entry and return a pointer to a + struct archive_entry. + archive_read_data() + Read data associated with the header just read. Internally, this + is a convenience function that calls archive_read_data_block() + and fills any gaps with nulls so that callers see a single con- + tinuous stream of data. + archive_read_data_block() + Return the next available block of data for this entry. Unlike + archive_read_data(), the archive_read_data_block() function + avoids copying data and allows you to correctly handle sparse + files, as supported by some archive formats. The library guaran- + tees 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. + archive_read_data_skip() + A convenience function that repeatedly calls + archive_read_data_block() to skip all of the data for this ar- + chive entry. + archive_read_data_into_buffer() + This function is deprecated and will be removed. Use + archive_read_data() instead. + archive_read_data_into_fd() + A convenience function that repeatedly calls + archive_read_data_block() to copy the entire entry to the pro- + vided file descriptor. + archive_read_extract(), archive_read_extract_set_skip_file() + A convenience function that wraps the corresponding + archive_write_disk(3) interfaces. The first call to + archive_read_extract() creates a restore object using + archive_write_disk_new(3) and + archive_write_disk_set_standard_lookup(3), then transparently + invokes archive_write_disk_set_options(3), + archive_write_header(3), archive_write_data(3), and + archive_write_finish_entry(3) to create the entry on disk and + copy data into it. The flags argument is passed unmodified to + archive_write_disk_set_options(3). + archive_read_extract_set_progress_callback() + Sets a pointer to a user-defined callback that can be used for + updating progress displays during extraction. The progress func- + tion 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. + archive_read_close() + Complete the archive and invoke the close callback. + archive_read_finish() + Invokes archive_read_close() if it was not invoked manually, then + release all resources. Note: In libarchive 1.x, this function + was declared to return void, which made it impossible to detect + certain errors when archive_read_close() 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 + gzip(1) or bzip2(1) compression and transparently performs the appropri- + ate decompression. It also automatically detects the archive format. + + A complete description of the struct archive and struct archive_entry + objects can be found in the overview manual page for libarchive(3). + +CLIENT CALLBACKS + The callback functions must match the following prototypes: + + typedef ssize_t archive_read_callback(struct archive *, void + *client_data, const void **buffer) + + typedef int archive_skip_callback(struct archive *, void + *client_data, size_t request) + + typedef int archive_open_callback(struct archive *, void + *client_data) + + typedef int archive_close_callback(struct archive *, void + *client_data) + + The open callback is invoked by archive_open(). It should return + ARCHIVE_OK if the underlying file or data source is successfully opened. + If the open fails, it should call archive_set_error() to register an + error code and message and return ARCHIVE_FATAL. + + 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 + const void **buffer 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 archive_set_error() 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 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 process- + ing is complete. The callback should return ARCHIVE_OK on success. On + failure, the callback should invoke archive_set_error() to register an + error code and message and return ARCHIVE_FATAL. + +EXAMPLE + The following illustrates basic usage of the library. In this example, + the callback functions are simply wrappers around the standard open(2), + read(2), and close(2) system calls. + + 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); + } + +RETURN VALUES + Most functions return zero on success, non-zero on error. The possible + return codes include: ARCHIVE_OK (the operation succeeded), ARCHIVE_WARN + (the operation succeeded but a non-critical error was encountered), + ARCHIVE_EOF (end-of-archive was encountered), ARCHIVE_RETRY (the opera- + tion failed but can be retried), and ARCHIVE_FATAL (there was a fatal + error; the archive should be closed immediately). Detailed error codes + and textual descriptions are available from the archive_errno() and + archive_error_string() functions. + + archive_read_new() returns a pointer to a freshly allocated struct + archive object. It returns NULL on error. + + archive_read_data() returns a count of bytes actually read or zero at the + end of the entry. On error, a value of ARCHIVE_FATAL, ARCHIVE_WARN, or + ARCHIVE_RETRY is returned and an error code and textual description can + be retrieved from the archive_errno() and archive_error_string() func- + tions. + + The library expects the client callbacks to behave similarly. If there + is an error, you can use archive_set_error() 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 even- + tually cause ARCHIVE_FATAL to be returned.) + +SEE ALSO + tar(1), archive(3), archive_util(3), tar(5) + +HISTORY + The libarchive library first appeared in FreeBSD 5.3. + +AUTHORS + The libarchive library was written by Tim Kientzle . + +BUGS + Many traditional archiver programs treat empty files as valid empty ar- + chives. For example, many implementations of tar(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. + +FreeBSD 6.0 August 19, 2006 FreeBSD 6.0 diff --git a/libarchive/libarchive-2.4.17/doc/text/archive_util.3 b/libarchive/libarchive-2.4.17/doc/text/archive_util.3 new file mode 100644 index 0000000..28b6883 --- /dev/null +++ b/libarchive/libarchive-2.4.17/doc/text/archive_util.3 @@ -0,0 +1,91 @@ +archive_util(3) FreeBSD Library Functions Manual archive_util(3) + +NAME + archive_clear_error, archive_compression, archive_compression_name, + archive_copy_error, archive_errno, archive_error_string, archive_format, + archive_format_name, archive_set_error -- libarchive utility functions + +SYNOPSIS + #include + + void + archive_clear_error(struct archive *); + + int + archive_compression(struct archive *); + + const char * + archive_compression_name(struct archive *); + + void + archive_copy_error(struct archive *, struct archive *); + + int + archive_errno(struct archive *); + + const char * + archive_error_string(struct archive *); + + int + archive_format(struct archive *); + + const char * + archive_format_name(struct archive *); + + void + archive_set_error(struct archive *, int error_code, const char *fmt, + ...); + +DESCRIPTION + These functions provide access to various information about the struct + archive object used in the libarchive(3) library. + archive_clear_error() + Clears any error information left over from a previous call. Not + generally used in client code. + archive_compression() + Returns a numeric code indicating the current compression. This + value is set by archive_read_open(). + archive_compression_name() + Returns a text description of the current compression suitable + for display. + archive_copy_error() + Copies error information from one archive to another. + archive_errno() + Returns a numeric error code (see errno(2)) indicating the reason + for the most recent error return. + archive_error_string() + Returns a textual error message suitable for display. The error + message here is usually more specific than that obtained from + passing the result of archive_errno() to strerror(3). + archive_format() + Returns a numeric code indicating the format of the current ar- + chive entry. This value is set by a successful call to + archive_read_next_header(). 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. + archive_format_name() + A textual description of the format of the current entry. + archive_set_error() + Sets the numeric error code and error description that will be + returned by archive_errno() and archive_error_string(). This + function should be used within I/O callbacks to set system-spe- + cific 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. + +SEE ALSO + archive_read(3), archive_write(3), libarchive(3), printf(3) + +HISTORY + The libarchive library first appeared in FreeBSD 5.3. + +AUTHORS + The libarchive library was written by Tim Kientzle . + +FreeBSD 6.0 January 8, 2005 FreeBSD 6.0 diff --git a/libarchive/libarchive-2.4.17/doc/text/archive_write.3 b/libarchive/libarchive-2.4.17/doc/text/archive_write.3 new file mode 100644 index 0000000..a16d364 --- /dev/null +++ b/libarchive/libarchive-2.4.17/doc/text/archive_write.3 @@ -0,0 +1,420 @@ +archive_write(3) FreeBSD Library Functions Manual archive_write(3) + +NAME + archive_write_new, archive_write_set_format_cpio, + archive_write_set_format_pax, archive_write_set_format_pax_restricted, + archive_write_set_format_shar, archive_write_set_format_shar_binary, + archive_write_set_format_ustar, archive_write_get_bytes_per_block, + archive_write_set_bytes_per_block, archive_write_set_bytes_in_last_block, + archive_write_set_compression_bzip2, archive_write_set_compression_gzip, + archive_write_set_compression_none, + archive_write_set_compression_program, archive_write_open, + archive_write_open_fd, archive_write_open_FILE, + archive_write_open_filename, archive_write_open_memory, + archive_write_header, archive_write_data, archive_write_finish_entry, + archive_write_close, archive_write_finish -- functions for creating ar- + chives + +SYNOPSIS + #include + + struct archive * + archive_write_new(void); + + int + archive_write_get_bytes_per_block(struct archive *); + + int + archive_write_set_bytes_per_block(struct archive *, int bytes_per_block); + + int + archive_write_set_bytes_in_last_block(struct archive *, int); + + int + archive_write_set_compression_bzip2(struct archive *); + + int + archive_write_set_compression_gzip(struct archive *); + + int + archive_write_set_compression_none(struct archive *); + + int + archive_write_set_compression_program(struct archive *, + const char * cmd); + + int + archive_write_set_format_cpio(struct archive *); + + int + archive_write_set_format_pax(struct archive *); + + int + archive_write_set_format_pax_restricted(struct archive *); + + int + archive_write_set_format_shar(struct archive *); + + int + archive_write_set_format_shar_binary(struct archive *); + + int + archive_write_set_format_ustar(struct archive *); + + int + archive_write_open(struct archive *, void *client_data, + archive_open_callback *, archive_write_callback *, + archive_close_callback *); + + int + archive_write_open_fd(struct archive *, int fd); + + int + archive_write_open_FILE(struct archive *, FILE *file); + + int + archive_write_open_filename(struct archive *, const char *filename); + + int + archive_write_open_memory(struct archive *, void *buffer, + size_t bufferSize, size_t *outUsed); + + int + archive_write_header(struct archive *, struct archive_entry *); + + ssize_t + archive_write_data(struct archive *, const void *, size_t); + + int + archive_write_finish_entry(struct archive *); + + int + archive_write_close(struct archive *); + + int + archive_write_finish(struct archive *); + +DESCRIPTION + These functions provide a complete API for creating streaming archive + files. The general process is to first create the 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: + + archive_write_new() + Allocates and initializes a struct archive object suitable for + writing a tar archive. + + archive_write_set_bytes_per_block() + 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. + + archive_write_get_bytes_per_block() + 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. + + archive_write_set_bytes_in_last_block() + 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 com- + pression. The uncompressed data is always unpadded. The default + is to pad the last block to the full block size (note that + archive_write_open_filename() will set this based on the file + type). Unlike the other ``set'' functions, this function can be + called after the archive is opened. + + archive_write_get_bytes_in_last_block() + Retrieve the currently-set value for last block size. A value of + -1 here indicates that the library should use default values. + + archive_write_set_format_cpio(), archive_write_set_format_pax(), + archive_write_set_format_pax_restricted(), + archive_write_set_format_shar(), + archive_write_set_format_shar_binary(), + archive_write_set_format_ustar() + Sets the format that will be used for the archive. The library + can write POSIX octet-oriented cpio format archives, POSIX-stan- + dard ``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. + + archive_write_set_compression_bzip2(), + archive_write_set_compression_gzip(), + archive_write_set_compression_none() + The resulting archive will be compressed as specified. Note that + the compressed output is always properly blocked. + + archive_write_set_compression_program() + The archive will be fed into the specified compression program. + The output of that program is blocked and written to the client + write callbacks. + + archive_write_open() + 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 ar- + chive. + + archive_write_open_fd() + A convenience form of archive_write_open() that accepts a file + descriptor. The archive_write_open_fd() function is safe for use + with tape drives or other block-oriented devices. + + archive_write_open_FILE() + A convenience form of archive_write_open() that accepts a FILE * + pointer. Note that archive_write_open_FILE() is not safe for + writing to tape drives or other devices that require correct + blocking. + + archive_write_open_file() + A deprecated synonym for archive_write_open_filename(). + + archive_write_open_filename() + A convenience form of archive_write_open() that accepts a file- + name. A NULL argument indicates that the output should be writ- + ten to standard output; an argument of ``-'' will open a file + with that name. If you have not invoked + archive_write_set_bytes_in_last_block(), then + archive_write_open_filename() 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 archive_write_set_bytes_in_last_block() before calling + archive_write_open(). The archive_write_open_filename() function + is safe for use with tape drives or other block-oriented devices. + + archive_write_open_memory() + A convenience form of archive_write_open() that accepts a pointer + to a block of memory that will receive the archive. The final + size_t * 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 allo- + cated until after the archive is closed. + + archive_write_header() + Build and write a header using the data in the provided struct + archive_entry structure. See archive_entry(3) for information on + creating and populating struct archive_entry objects. + + archive_write_data() + Write data corresponding to the header just written. Returns + number of bytes written or -1 on error. + + archive_write_finish_entry() + 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 + archive_write_next_header() and archive_write_close() as needed. + + archive_write_close() + Complete the archive and invoke the close callback. + + archive_write_finish() + Invokes archive_write_close() if it was not invoked manually, + then releases all resources. Note that this function was + declared to return void in libarchive 1.x, which made it impossi- + ble to detect errors when archive_write_close() was invoked + implicitly from this function. This is corrected beginning with + libarchive 2.0. + More information about the struct archive object and the overall design + of the library can be found in the libarchive(3) overview. + +IMPLEMENTATION + Compression support is built-in to libarchive, which uses zlib and bzlib + to handle gzip and bzip2 compression, respectively. + +CLIENT CALLBACKS + To use this library, you will need to define and register callback func- + tions that will be invoked to write data to the resulting archive. These + functions are registered by calling archive_write_open(): + + typedef int archive_open_callback(struct archive *, void + *client_data) + + The open callback is invoked by archive_write_open(). It should return + ARCHIVE_OK if the underlying file or data source is successfully opened. + If the open fails, it should call archive_set_error() to register an + error code and message and return ARCHIVE_FATAL. + + typedef ssize_t archive_write_callback(struct archive *, void + *client_data, void *buffer, size_t length) + + The write callback is invoked whenever the library needs to write raw + bytes to the archive. For correct blocking, each call to the write call- + back function should translate into a single write(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 archive_set_error() to register an + error code and message and return -1. + + typedef int archive_close_callback(struct archive *, void + *client_data) + + The close callback is invoked by archive_close when the archive process- + ing is complete. The callback should return ARCHIVE_OK on success. On + failure, the callback should invoke archive_set_error() to register an + error code and message and return ARCHIVE_FATAL. + +EXAMPLE + The following sketch illustrates basic usage of the library. In this + example, the callback functions are simply wrappers around the standard + open(2), write(2), and close(2) system calls. + + #include + #include + #include + #include + #include + #include + + 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; + } + +RETURN VALUES + Most functions return ARCHIVE_OK (zero) on success, or one of several + non-zero error codes for errors. Specific error codes include: + ARCHIVE_RETRY for operations that might succeed if retried, ARCHIVE_WARN + for unusual conditions that do not prevent further operations, and + ARCHIVE_FATAL for serious errors that make remaining operations impossi- + ble. The archive_errno() and archive_error_string() functions can be + used to retrieve an appropriate error code and a textual error message. + + archive_write_new() returns a pointer to a newly-allocated struct archive + object. + + archive_write_data() returns a count of the number of bytes actually + written. On error, -1 is returned and the archive_errno() and + archive_error_string() functions will return appropriate values. 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 + archive_write_header(), archive_write_data(), archive_write_close(), or + archive_write_finish(). The client callback can call archive_set_error() + to provide values that can then be retrieved by archive_errno() and + archive_error_string(). + +SEE ALSO + tar(1), libarchive(3), tar(5) + +HISTORY + The libarchive library first appeared in FreeBSD 5.3. + +AUTHORS + The libarchive library was written by Tim Kientzle . + +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 ven- + dor-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 star 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. + +FreeBSD 6.0 August 19, 2006 FreeBSD 6.0 diff --git a/libarchive/libarchive-2.4.17/doc/text/archive_write_disk.3 b/libarchive/libarchive-2.4.17/doc/text/archive_write_disk.3 new file mode 100644 index 0000000..18e4e50 --- /dev/null +++ b/libarchive/libarchive-2.4.17/doc/text/archive_write_disk.3 @@ -0,0 +1,253 @@ +archive_write_disk(3) FreeBSD Library Functions Manual archive_write_disk(3) + +NAME + archive_write_disk_new, archive_write_disk_set_options, + archive_write_disk_set_skip_file, archive_write_disk_set_group_lookup, + archive_write_disk_set_standard_lookup, + archive_write_disk_set_user_lookup, archive_write_header, + archive_write_data, archive_write_finish_entry, archive_write_close, + archive_write_finish -- functions for creating objects on disk + +SYNOPSIS + #include + + struct archive * + archive_write_disk_new(void); + + int + archive_write_disk_set_options(struct archive *, int flags); + + int + archive_write_disk_set_skip_file(struct archive *, dev_t, ino_t); + + int + archive_write_disk_set_group_lookup(struct archive *, void *, + gid_t (*)(void *, const char *gname, gid_t gid), + void (*cleanup)(void *)); + + int + archive_write_disk_set_standard_lookup(struct archive *); + + int + archive_write_disk_set_user_lookup(struct archive *, void *, + uid_t (*)(void *, const char *uname, uid_t uid), + void (*cleanup)(void *)); + + int + archive_write_header(struct archive *, struct archive_entry *); + + ssize_t + archive_write_data(struct archive *, const void *, size_t); + + int + archive_write_finish_entry(struct archive *); + + int + archive_write_close(struct archive *); + + int + archive_write_finish(struct archive *); + +DESCRIPTION + These functions provide a complete API for creating objects on disk from + struct archive_entry descriptions. They are most naturally used when + extracting objects from an archive using the archive_read() interface. + The general process is to read struct archive_entry objects from an ar- + chive, then write those objects to a struct archive object created using + the archive_write_disk() family functions. This interface is deliber- + ately very similar to the archive_write() interface used to write objects + to a streaming archive. + + archive_write_disk_new() + Allocates and initializes a struct archive object suitable for + writing objects to disk. + + archive_write_disk_set_skip_file() + 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. + + archive_write_disk_set_options() + The options field consists of a bitwise OR of one or more of the + following values: + ARCHIVE_EXTRACT_OWNER + The user and group IDs should be set on the restored + file. By default, the user and group IDs are not + restored. + ARCHIVE_EXTRACT_PERM + Full permissions (including SGID, SUID, and sticky bits) + should be restored exactly as specified, without obeying + the current umask. Note that SUID and SGID bits can only + be restored if the user and group ID of the object on + disk are correct. If ARCHIVE_EXTRACT_OWNER is not speci- + fied, 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. + ARCHIVE_EXTRACT_TIME + The timestamps (mtime, ctime, and atime) should be + restored. By default, they are ignored. Note that + restoring of atime is not currently supported. + ARCHIVE_EXTRACT_NO_OVERWRITE + Existing files on disk will not be overwritten. By + default, existing regular files are truncated and over- + written; existing directories will have their permissions + updated; other pre-existing objects are unlinked and + recreated from scratch. + ARCHIVE_EXTRACT_UNLINK + 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. + ARCHIVE_EXTRACT_ACL + Attempt to restore ACLs. By default, extended ACLs are + ignored. + ARCHIVE_EXTRACT_FFLAGS + Attempt to restore extended file flags. By default, file + flags are ignored. + ARCHIVE_EXTRACT_XATTR + Attempt to restore POSIX.1e extended attributes. By + default, they are ignored. + ARCHIVE_EXTRACT_SECURE_SYMLINKS + 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 ar- + chives that (deliberately or otherwise) extract files + outside of the current directory. The default is not to + perform this check. If ARCHIVE_EXTRACT_UNLINK is speci- + fied 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. + ARCHIVE_EXTRACT_SECURE_NODOTDOT + Refuse to extract a path that contains a .. element any- + where within it. The default is to not refuse such + paths. Note that paths ending in .. always cause an + error, regardless of this flag. + + archive_write_disk_set_group_lookup(), + archive_write_disk_set_user_lookup() + The struct archive_entry objects contain both names and ids that + can be used to identify users and groups. These names and ids + describe the ownership of the file itself and also appear in ACL + lists. By default, the library uses the ids and ignores the + names, but this can be overridden by registering user and group + lookup functions. To register, you must provide a lookup func- + tion which accepts both a name and id and returns a suitable id. + You may also provide a void * pointer to a private data structure + and a cleanup function for that data. The cleanup function will + be invoked when the struct archive object is destroyed. + + archive_write_disk_set_standard_lookup() + This convenience function installs a standard set of user and + group lookup functions. These functions use getpwnam(3) and + getgrnam(3) to convert names to ids, defaulting to the ids if the + names cannot be looked up. These functions also implement a sim- + ple memory cache to reduce the number of calls to getpwnam(3) and + getgrnam(3). + + archive_write_header() + Build and write a header using the data in the provided struct + archive_entry structure. See archive_entry(3) for information on + creating and populating struct archive_entry objects. + + archive_write_data() + Write data corresponding to the header just written. Returns + number of bytes written or -1 on error. + + archive_write_finish_entry() + Close out the entry just written. Ordinarily, clients never need + to call this, as it is called automatically by + archive_write_next_header() and archive_write_close() as needed. + + archive_write_close() + Set any attributes that could not be set during the initial + restore. For example, directory timestamps are not restored ini- + tially because restoring a subsequent file would alter that time- + stamp. Similarly, non-writable directories are initially created + with write permissions (so that their contents can be restored). + The archive_write_disk_new library maintains a list of all such + deferred attributes and sets them when this function is invoked. + + archive_write_finish() + Invokes archive_write_close() if it was not invoked manually, + then releases all resources. + More information about the struct archive object and the overall design + of the library can be found in the libarchive(3) overview. Many of these + functions are also documented under archive_write(3). + +RETURN VALUES + Most functions return ARCHIVE_OK (zero) on success, or one of several + non-zero error codes for errors. Specific error codes include: + ARCHIVE_RETRY for operations that might succeed if retried, ARCHIVE_WARN + for unusual conditions that do not prevent further operations, and + ARCHIVE_FATAL for serious errors that make remaining operations impossi- + ble. The archive_errno() and archive_error_string() functions can be + used to retrieve an appropriate error code and a textual error message. + + archive_write_disk_new() returns a pointer to a newly-allocated struct + archive object. + + archive_write_data() returns a count of the number of bytes actually + written. On error, -1 is returned and the archive_errno() and + archive_error_string() functions will return appropriate values. + +SEE ALSO + archive_read(3), archive_write(3), tar(1), libarchive(3) + +HISTORY + The libarchive library first appeared in FreeBSD 5.3. The + archive_write_disk interface was added to libarchive 2.0 and first + appeared in FreeBSD 6.3. + +AUTHORS + The libarchive library was written by Tim Kientzle . + +BUGS + Directories are actually extracted in two distinct phases. Directories + are created during archive_write_header(), but final permissions are not + set until archive_write_close(). This separation is necessary to cor- + rectly handle borderline cases such as a non-writable directory contain- + ing files, but can cause unexpected results. In particular, directory + permissions are not fully restored until the archive is closed. If you + use chdir(2) to change the current directory between calls to + archive_read_extract() or before calling archive_read_close(), you may + confuse the permission-setting logic with the result that directory per- + missions are restored incorrectly. + + The library attempts to create objects with filenames longer than + PATH_MAX by creating prefixes of the full path and changing the current + directory. Currently, this logic is limited in scope; the fixup pass + does not work correctly for such objects and the symlink security check + option disables the support for very long pathnames. + + Restoring the path aa/../bb does create each intermediate directory. In + particular, the directory aa is created as well as the final object bb. + In theory, this can be exploited to create an entire directory heirarchy + with a single request. Of course, this does not work if the + ARCHIVE_EXTRACT_NODOTDOT option is specified. + + Implicit directories are always created obeying the current umask. + Explicit objects are created obeying the current umask unless + ARCHIVE_EXTRACT_PERM is specified, in which case they current umask is + ignored. + + SGID and SUID bits are restored only if the correct user and group could + be set. If ARCHIVE_EXTRACT_OWNER is not specified, then no attempt is + made to set the ownership. In this case, SGID and SUID bits are restored + only if the user and group of the final object happen to match those + specified in the entry. + + The ``standard'' user-id and group-id lookup functions are not the + defaults because getgrnam(3) and getpwnam(3) are sometimes too large for + particular applications. The current design allows the application + author to use a more compact implementation when appropriate. + + There should be a corresponding archive_read_disk interface that walks a + directory heirarchy and returns archive entry objects. + +FreeBSD 6.0 March 2, 2007 FreeBSD 6.0 diff --git a/libarchive/libarchive-2.4.17/doc/text/bsdcpio.1 b/libarchive/libarchive-2.4.17/doc/text/bsdcpio.1 new file mode 100644 index 0000000..d8f7102 --- /dev/null +++ b/libarchive/libarchive-2.4.17/doc/text/bsdcpio.1 @@ -0,0 +1,187 @@ +BSDCPIO(1) FreeBSD General Commands Manual BSDCPIO(1) + +NAME + cpio -- copy files to and from archives + +SYNOPSIS + cpio {-i} [options] [pattern ...] [< archive] + cpio {-o} [options] < name-list [> archive] + cpio {-p} [options] dest-dir < name-list + +DESCRIPTION + cpio 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 cpio is a mode indicator from the following list: + -i Input. Read an archive from standard input and extract the con- + tents to disk or (if the -t option is specified) list the con- + tents to standard output. If one or more file patterns are spec- + ified, only files matching one of the patterns will be extracted. + -o Output. Read a list of filenames from standard input and produce + a new archive on standard output containing the specified items. + -p Pass-through. Read a list of filenames from standard input and + copy the files to the specified directory. + +OPTIONS + Unless specifically stated otherwise, options are applicable in all oper- + ating modes. + + -a (o and p modes) Reset access times on files after they are read. + + -B (o mode only) Block output to records of 5120 bytes. + + -c (o mode only) Use the old POSIX portable character format. + Equivalent to --format odc. + + -d (i and p modes) Create directories as necessary. + + -f pattern + (i mode only) Ignore files that match pattern. + + --format format + (o mode only) Produce the output archive in the specified format. + Supported formats include: + + cpio Synonym for odc. + newc The SVR4 portable cpio format. + odc The old POSIX.1 portable octet-oriented cpio format. + pax The POSIX.1 pax format, an extension of the ustar for- + mat. + ustar The POSIX.1 tar format. + + The default format is odc. See libarchive_formats(5) for more + complete information about the formats currently supported by the + underlying libarchive(3) library. + + -i Input mode. See above for description. + + -L (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. + + -l (p mode only) Create links from the target directory to the orig- + inal files, instead of copying. + + -m (i and p modes) Set file modification time on created files to + match those in the source. + + -o Output mode. See above for description. + + -p Pass-through mode. See above for description. + + --quiet + Suppress unnecessary messages. + + -R [user][:][group] + Set the owner and/or group on files in the output. If group is + specified with no user (for example, -R :wheel) then the group + will be set but not the user. If the user is specified with a + trailing colon and no group (for example, -R root:) 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 -i and -p modes, this option can only be used + by the super-user. (For compatibility, a period can be used in + place of the colon.) + + -r (All modes.) Rename files interactively. For each file, a + prompt is written to /dev/tty containing the name of the file and + a line is read from /dev/tty. 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. + + -t (i mode only) List the contents of the archive to stdout; do not + restore the contents to disk. + + -u (i and p modes) Unconditionally overwrite existing files. Ordi- + narily, an older file will not overwrite a newer file on disk. + + -v Print the name of each file to stderr as it is processed. With + -t, provide a detailed listing of each file. + + --version + Print the program version information and exit. + + -y (o mode only) Compress the archive with bzip2-compatible compres- + sion before writing to stdout. In input mode, this option is + ignored; bzip2 compression is recognized automatically on input. + + -z (o mode only) Compress the archive with gzip-compatible compres- + sion before writing it to stdout. In input mode, this option is + ignored; gzip compression is recognized automatically on input. + +ENVIRONMENT + The following environment variables affect the execution of cpio: + + LANG The locale to use. See environ(7) for more information. + + TZ The timezone to use when displaying dates. See environ(7) for + more information. + +EXIT STATUS + The cpio utility exits 0 on success, and >0 if an error occurs. + +EXAMPLES + The cpio command is traditionally used to copy file heirarchies in con- + junction with the find(1) command. The first example here simply copies + all files from src to dest: + find src | cpio -pmud dest + + By carefully selecting options to the find(1) command and combining it + with other standard utilities, it is possible to exercise very fine con- + trol over which files are copied. This next example copies files from + src to dest that are more than 2 days old and whose names match a partic- + ular pattern: + find src -mtime +2 | grep foo[bar] | cpio -pdmu dest + + This example copies files from src to dest that are more than 2 days old + and which contain the word ``foobar'': + find src -mtime +2 | xargs grep -l foobar | cpio -pdmu dest + +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 -i, -o, and -p were inter- + preted as command-line options. Each took a single argument of a list of + modifier characters. For example, the standard syntax allows -imu but + does not support -miu or -i -m -u, since m and u are only modifiers to + -i, they are not command-line options in their own right. The syntax + supported by this implementation is backwards-compatible with the stan- + dard. For best compatibility, scripts should limit themselves to the + standard syntax. + +SEE ALSO + bzip2(1), tar(1), gzip(1), mt(1), pax(1), libarchive(3), cpio(5), + libarchive-formats(5), tar(5) + +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. + +HISTORY + The original cpio and find 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, cpio actually predates tar, even though + it was not well-known outside of AT&T until some time later. + + This is a complete re-implementation based on the libarchive(3) library. + +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 for- + mats cannot support files over 4 gigabytes, except for the ``odc'' vari- + ant, which can support files up to 8 gigabytes. + +FreeBSD 6.0 December 21, 2007 FreeBSD 6.0 diff --git a/libarchive/libarchive-2.4.17/doc/text/bsdtar.1 b/libarchive/libarchive-2.4.17/doc/text/bsdtar.1 new file mode 100644 index 0000000..9a62753 --- /dev/null +++ b/libarchive/libarchive-2.4.17/doc/text/bsdtar.1 @@ -0,0 +1,441 @@ +BSDTAR(1) FreeBSD General Commands Manual BSDTAR(1) + +NAME + tar -- manipulate tape archives + +SYNOPSIS + tar [bundled-flags ] [ | ...] + tar {-c} [options] [files | directories] + tar {-r | -u} -f archive-file [options] [files | directories] + tar {-t | -x} [options] [patterns] + +DESCRIPTION + tar 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 COMPATI- + BILITY below for details. + + The other synopsis forms show the preferred usage. The first option to + tar is a mode indicator from the following list: + -c Create a new archive containing the specified items. + -r Like -c, but new entries are appended to the archive. Note that + this only works on uncompressed archives stored in regular files. + The -f option is required. + -t List archive contents to stdout. + -u Like -r, but new entries are added only if they have a modifica- + tion date newer than the corresponding entry in the archive. + Note that this only works on uncompressed archives stored in reg- + ular files. The -f option is required. + -x 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 -c, -r, or -u mode, each specified file or directory is added to the + archive in the order specified on the command line. By default, the con- + tents 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 tcsh(1). + +OPTIONS + Unless specifically stated otherwise, options are applicable in all oper- + ating modes. + + @archive + (c and r mode only) The specified archive is opened and the + entries in it will be appended to the current archive. As a sim- + ple example, + tar -c -f - newfile @original.tar + writes a new archive to standard output containing a file newfile + and all of the entries from original.tar. In contrast, + tar -c -f - newfile original.tar + creates a new archive with only two entries. Similarly, + tar -czf - --format pax @- + reads an archive from standard input (whose format will be deter- + mined automatically) and converts it into a gzip-compressed pax- + format archive on stdout. In this way, tar can be used to con- + vert archives from one format to another. + + -b blocksize + 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. + + -C directory + 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. + + --check-links (-W check-links) + (c and r modes only) Issue a warning message unless all links to + each file are archived. + + --exclude pattern (-W exclude=pattern) + Do not process files or directories that match the specified pat- + tern. Note that exclusions take precedence over patterns or + filenames specified on the command line. + + --format format (-W format=format) + (c 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 + libarchive-formats(5) for more information about currently-sup- + ported formats. + + -f file + Read the archive from or write the archive to the specified file. + The filename can be - for standard input or standard output. If + not specified, the default tape device will be used. (On + FreeBSD, the default tape device is /dev/sa0.) + + --fast-read (-W fast-read) + (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. + + -H (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. + + -h (c and r mode only) Synonym for -L. + + -I Synonym for -T. + + --include pattern (-W include=pattern) + Process only files or directories that match the specified pat- + tern. Note that exclusions specified with --exclude take prece- + dence over inclusions. If no inclusions are explicitly speci- + fied, all entries are processed by default. The --include option + is especially useful when filtering archives. For example, the + command + tar -c -f new.tar --include='*foo*' @old.tgz + creates a new archive new.tar containing only the entries from + old.tgz containing the string `foo'. + + -j (c mode only) Compress the resulting archive with bzip2(1). In + extract or list modes, this option is ignored. Note that, unlike + other tar implementations, this implementation recognizes bzip2 + compression automatically when reading archives. + + -k (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. + + -L (c and r mode only) All symbolic links will be followed. Nor- + mally, symbolic links are archived as such. With this option, + the target of the link will be archived instead. + + -l This is a synonym for the --check-links option. + + -m (x mode only) Do not extract modification time. By default, the + modification time is set to the time stored in the archive. + + -n (c, r, u modes only) Do not recursively archive the contents of + directories. + + --newer date (-W newer=date) + (c, r, u modes only) Only include files and directories newer + than the specified date. This compares ctime entries. + + --newer-mtime date (-W newer-mtime=date) + (c, r, u modes only) Like --newer, except it compares mtime + entries instead of ctime entries. + + --newer-than file (-W newer-than=file) + (c, r, u modes only) Only include files and directories newer + than the specified file. This compares ctime entries. + + --newer-mtime-than file (-W newer-mtime-than=file) + (c, r, u modes only) Like --newer-than, except it compares mtime + entries instead of ctime entries. + + --nodump (-W nodump) + (c and r modes only) Honor the nodump file flag by skipping this + file. + + --null (-W null) + (use with -I, -T, or -X) Filenames or patterns are separated by + null characters, not by newlines. This is often used to read + filenames output by the -print0 option to find(1). + + -O (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. + + -o (x mode only) Use the user and group of the user running the pro- + gram rather than those specified in the archive. Note that this + has no significance unless -p 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 infor- + mation in the archive will be discarded. + + --one-file-system (-W one-file-system) + (c, r, and u modes) Do not cross mount points. + + -P 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, tar will + refuse to extract archive entries whose pathnames contain .. or + whose target directory would be altered by a symlink. This + option suppresses these behaviors. + + -p (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 tar, + the file mode is restored for newly-created regular files, and + all other types of entries receive default permissions. If tar + is being run by root, the default is to restore the owner unless + the -o option is also specified. + + --strip-components count (-W strip-components=count) + (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 inclu- + sion/exclusion patterns but before security checks. + + -T filename + In x or t mode, tar will read the list of names to be extracted + from filename. In c mode, tar will read names to be archived + from filename. The special name ``-C'' on a line by itself will + cause the current directory to be changed to the directory speci- + fied on the following line. Names are terminated by newlines + unless --null is specified. Note that --null also disables the + special handling of lines containing ``-C''. + + -U (x mode only) Unlink files before creating them. Without this + option, tar 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. + + --use-compress-program program + Pipe the input (in x or t mode) or the output (in c mode) through + program instead of using the builtin compression support. + + -v Produce verbose output. In create and extract modes, tar will + list each file name as it is read from or written to the archive. + In list mode, tar will produce output similar to that of ls(1). + Additional -v options will provide additional detail. + + -W longopt=value + Long options (preceded by --) are only supported directly on sys- + tems that have the getopt_long(3) function. The -W option can be + used to access long options on systems that do not support this + function. + + -w Ask for confirmation for every action. + + -X filename + Read a list of exclusion patterns from the specified file. See + --exclude for more information about the handling of exclusions. + + -y (c mode only) Compress the resulting archive with bzip2(1). In + extract or list modes, this option is ignored. Note that, unlike + other tar implementations, this implementation recognizes bzip2 + compression automatically when reading archives. + + -z (c mode only) Compress the resulting archive with gzip(1). In + extract or list modes, this option is ignored. Note that, unlike + other tar implementations, this implementation recognizes gzip + compression automatically when reading archives. + +ENVIRONMENT + The following environment variables affect the execution of tar: + + LANG The locale to use. See environ(7) for more information. + + TAPE The default tape device. The -f option overrides this. + + TZ The timezone to use when displaying dates. See environ(7) for + more information. + +FILES + /dev/sa0 The default tape device, if not overridden by the TAPE envi- + ronment variable or the -f option. + +EXIT STATUS + The tar utility exits 0 on success, and >0 if an error occurs. + +EXAMPLES + The following creates a new archive called file.tar.gz that contains two + files source.c and source.h: + tar -czf file.tar.gz source.c source.h + + To view a detailed table of contents for this archive: + tar -tvf file.tar.gz + + To extract all entries from the archive on the default tape drive: + tar -x + + To examine the contents of an ISO 9660 cdrom image: + tar -tf image.iso + + To move file hierarchies, invoke tar as + tar -cf - -C srcdir . | tar -xpf - -C destdir + or more traditionally + cd srcdir ; tar -cf - . | (cd destdir ; tar -xpf -) + + In create mode, the list of files and directories to be archived can also + include directory change instructions of the form -Cfoo/baz and archive + inclusions of the form @archive-file. For example, the command line + tar -c -f new.tar foo1 @old.tgz -C/tmp foo2 + will create a new archive new.tar. tar will read the file foo1 from the + current directory and add it to the output archive. It will then read + each entry from old.tgz and add those entries to the output archive. + Finally, it will switch to the /tmp directory and add foo2 to the output + archive. + + The --newer and --newer-mtime 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''. + +COMPATIBILITY + The bundled-arguments format is supported for compatibility with historic + implementations. It consists of an initial word (with no leading - char- + acter) 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, + tar tbf 32 file.tar + specifies three flags t, b, and f. The b and f flags both require argu- + ments, so there must be two additional items on the command line. The 32 + is the argument to the b flag, and file.tar is the argument to the f + 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 tar should use the bundled- + argument format above, should limit themselves to the c, t, and x modes, + and the b, f, m, v, and w options. + + On systems that support getopt_long(), additional long options are avail- + able to improve compatibility with other tar implementations. + +SECURITY + Certain security issues are common to many archiving programs, including + tar. In particular, carefully-crafted archives can request that tar + 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 supe- + ruser, any file on the system can potentially be overwritten. There are + three ways this can happen. Although tar has mechanisms to protect + against each one, savvy users should be aware of the implications: + + o Archive entries can have absolute pathnames. By default, tar + removes the leading / character from filenames before restoring + them to guard against this problem. + + o Archive entries can have pathnames that include .. components. + By default, tar will not extract files containing .. components + in their pathname. + + o 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, tar 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 -U is specified, + any intermediate symlink will also be unconditionally removed. + If neither -U nor -P is specified, tar 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 + tar -tf filename + before extraction. You should use the -k option to ensure that tar will + not overwrite any existing files or the -U option to remove any pre- + existing files. You should generally not extract archives while running + with super-user privileges. Note that the -P option to tar disables the + security checks above and allows you to extract an archive while preserv- + ing any absolute pathnames, .. components, or symlinks to other directo- + ries. + +SEE ALSO + bzip2(1), cpio(1), gzip(1), mt(1), pax(1), shar(1), libarchive(3), + libarchive-formats(5), tar(5) + +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 specifica- + tion for pax. + + The ustar and pax interchange file formats are defined by IEEE Std + 1003.1-2001 (``POSIX.1'') for the pax command. + +HISTORY + A tar 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 pdtar 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 libarchive(3) library. + +BUGS + This program follows ISO/IEC 9945-1:1996 (``POSIX.1'') for the definition + of the -l option. Note that GNU tar prior to version 1.15 treated -l as + a synonym for the --one-file-system option. + + The -C dir option may differ from historic implementations. + + All archive output is written in correctly-sized blocks, even if the out- + put 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 com- + pressors, including gzip(1) and bzip2(1), complain about the null padding + when decompressing an archive created by tar, 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 + tar -czf - file + and that generated by + tar -cf - file | gzip + + The default should be to read and write archives to the standard I/O + paths, but tradition (and POSIX) dictates otherwise. + + The r and u modes require that the archive be uncompressed and located in + a regular file on disk. Other archives can be modified using c mode with + the @archive-file extension. + + To archive a file called @foo or -foo you must specify it as ./@foo or + ./-foo, respectively. + + In create mode, a leading ./ is always removed. A leading / is stripped + unless the -P 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 @- 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. + +FreeBSD 6.0 April 13, 2004 FreeBSD 6.0 diff --git a/libarchive/libarchive-2.4.17/doc/text/cpio.5 b/libarchive/libarchive-2.4.17/doc/text/cpio.5 new file mode 100644 index 0000000..db5da1e --- /dev/null +++ b/libarchive/libarchive-2.4.17/doc/text/cpio.5 @@ -0,0 +1,235 @@ +CPIO(5) FreeBSD File Formats Manual CPIO(5) + +NAME + cpio -- format of cpio archive files + +DESCRIPTION + The cpio archive format collects any number of files, directories, and + other file system objects (symbolic links, device nodes, etc.) into a + single stream of bytes. + + General Format + Each file system object in a cpio 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 gen- + erally follow the fields in struct stat. (See stat(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!!!''. + + PWB format + XXX Any documentation of the original PWB/UNIX 1.0 format? XXX + + Old Binary Format + The old binary cpio format stores numbers as 2-byte and 4-byte binary + values. Each entry begins with a header in the following format: + + 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]; + }; + + The unsigned short fields here are 16-bit integer values; the unsigned + int fields are 32-bit integer values. The fields are as follows + + magic The integer value octal 070707. This value can be used to deter- + mine whether this archive is written with little-endian or big- + endian integers. + + dev, ino + The device and inode numbers from the disk. These are used by + programs that read cpio archives to determine when two entries + refer to the same file. Programs that synthesize cpio archives + should be careful to set these to distinct values for each entry. + + mode The mode specifies both the regular permissions and the file + type. It consists of several bit fields as follows: + 0170000 This masks the file type bits. + 0140000 File type value for sockets. + 0120000 File type value for symbolic links. For symbolic links, + the link body is stored as file data. + 0100000 File type value for regular files. + 0060000 File type value for block special devices. + 0040000 File type value for directories. + 0020000 File type value for character special devices. + 0010000 File type value for named pipes or FIFOs. + 0004000 SUID bit. + 0002000 SGID bit. + 0001000 Sticky bit. On some systems, this modifies the behavior + of executables and/or directories. + 0000777 The lower 9 bits specify read/write/execute permissions + for world, group, and user following standard POSIX con- + ventions. + + uid, gid + The numeric user id and group id of the owner. + + nlink 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. + + rdev For block special and character special entries, this field con- + tains the associated device number. For all other entry types, + it should be set to zero by writers and ignored by readers. + + mtime 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. + + namesize + The number of bytes in the pathname that follows the header. + This count includes the trailing NULL byte. + + filesize + The size of the file. Note that this archive format is limited + to four gigabyte file sizes. See mtime above for a description + of the storage of four-byte integers. + + The pathname immediately follows the fixed header. If the namesize is + odd, an additional NULL byte is added after the pathname. The file data + is then appended, padded with NULL bytes to an even length. + + Hardlinked files are not given special treatment; the full file contents + are included with each copy of the file. + + 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. + + 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]; + }; + + 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 NULL byte that terminates + the name field. + + 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 num- + bers. + + 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]; + }; + + Except as specified below, the fields here match those specified for the + old binary format above. + + magic The string ``070701''. + + check This field is always set to zero by writers and ignored by read- + ers. See the next section for more details. + + The pathname is followed by NULL 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 sup- + ports only 4 gigabyte files (unlike the older ASCII format, which sup- + ports 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. + + New CRC Format + The CRC format is identical to the new ASCII format described in the pre- + vious section except that the magic field is set to ``070702'' and the + check 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 arith- + metic. Only the least-significant 32 bits of the sum are stored. + + HP variants + The cpio implementation distributed with HPUX used XXXX but stored device + numbers differently XXX. + + 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 ar- + chives. + + XXX Others? XXX + +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 number- + ing. + + 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. + +SEE ALSO + cpio(1), tar(5) + +STANDARDS + The cpio utility is no longer a part of POSIX or the Single Unix Stan- + dard. It last appeared in Version 2 of the Single UNIX Specification + (``SUSv2''). It has been supplanted in subsequent standards by pax(1). + The portable ASCII format is currently part of the specification for the + pax(1) utility. + +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 Version 6 AT&T UNIX 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 + +FreeBSD 6.0 October 5, 2007 FreeBSD 6.0 diff --git a/libarchive/libarchive-2.4.17/doc/text/libarchive-formats.5 b/libarchive/libarchive-2.4.17/doc/text/libarchive-formats.5 new file mode 100644 index 0000000..35eb278 --- /dev/null +++ b/libarchive/libarchive-2.4.17/doc/text/libarchive-formats.5 @@ -0,0 +1,180 @@ +libarchive-formats(3) FreeBSD Library Functions Manual libarchive-formats(3) + +NAME + libarchive-formats -- archive formats supported by the libarchive library + +DESCRIPTION + The libarchive(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 limita- + tions 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. + + Tar Formats + The libarchive(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. + + gnutar The libarchive(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. + + pax The libarchive(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 pres- + ence 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 Uni- + code strings. Keywords defined in the standard are in all lower- + case; vendors are allowed to define custom keys by preceding them + with the vendor name in all uppercase. When writing pax ar- + chives, 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. + + restricted pax + The libarchive library can also write pax archives in which it + attempts to suppress the extended attributes entry whenever pos- + sible. 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-com- + pliant pax interchange format archives. Programs that correctly + read ustar format (see below) will also be able to read this for- + mat; any extended attributes will be extracted as separate files + stored in PaxHeader directories. + + ustar The libarchive library can both read and write this format. This + format has the following limitations: + o Device major and minor numbers are limited to 21 bits. Nodes + with larger numbers will not be added to the archive. + o Path names in the archive are limited to 255 bytes. (Shorter + if there is no / character in exactly the right place.) + o Symbolic links and hard links are stored in the archive with + the name of the referenced file. This name is limited to 100 + bytes. + o Extended attributes, file flags, and other extended security + information cannot be stored. + o Archive entries are limited to 2 gigabytes in size. + Note that the pax interchange format has none of these restric- + tions. + + The libarchive library can also read a variety of commonly-used exten- + sions to the basic tar format. In particular, it supports base-256 val- + ues 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. + + 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. + + binary 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. + + odc The libarchive library can both read and write this POSIX-stan- + dard 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. + + SVR4 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 find and cpio utilities provided very precise + control over file selection. Unfortunately, the format has many limita- + tions 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 dissim- + ilar user numbering. + + Shar Formats + A ``shell archive'' is a shell script that, when executed on a POSIX-com- + pliant system, will recreate a collection of file system objects. The + libarchive library can write two different kinds of shar archives: + + shar The traditional shar format uses a limited set of POSIX commands, + including echo(1), mkdir(1), and sed(1). It is suitable for + portably archiving small collections of plain text files. How- + ever, it is not generally well-suited for large archives (many + implementations of sh(1) have limits on the size of a script) nor + should it be used with non-text files. + + shardump + This format is similar to shar but encodes files using + uuencode(1) so that the result will be a plain text file regard- + less 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 com- + mands used to restore file attributes make shardump archives less + portable than plain shar archives. + + 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. + + 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. + + Archive (library) file format + The Unix archive format (commonly created by the ar(1) archiver) is a + general-purpose format which is used almost exclusively for object files + to be read by the link editor ld(1). The ar format has never been stan- + dardised. 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. + +SEE ALSO + ar(1), cpio(1), mkisofs(1), shar(1), tar(1), zip(1), zlib(3), cpio(5), + mtree(5), tar(5) + +FreeBSD 6.0 April 27, 2004 FreeBSD 6.0 diff --git a/libarchive/libarchive-2.4.17/doc/text/libarchive.3 b/libarchive/libarchive-2.4.17/doc/text/libarchive.3 new file mode 100644 index 0000000..f4925f0 --- /dev/null +++ b/libarchive/libarchive-2.4.17/doc/text/libarchive.3 @@ -0,0 +1,185 @@ +LIBARCHIVE(3) FreeBSD Library Functions Manual LIBARCHIVE(3) + +NAME + libarchive -- functions for reading and writing streaming archives + +LIBRARY + Streaming Archive Library (libarchive, -larchive) + +OVERVIEW + The libarchive 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 modifica- + tion. + + When reading an archive, the library automatically detects the format and + the compression. The library currently has read support for: + o old-style tar archives, + o most variants of the POSIX ``ustar'' format, + o the POSIX ``pax interchange'' format, + o GNU-format tar archives, + o most common cpio archive formats, + o ISO9660 CD images (with or without RockRidge extensions), + o Zip archives. + The library automatically detects archives compressed with gzip(1), + bzip2(1), or compress(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 + o POSIX-standard ``ustar'' archives, + o POSIX ``pax interchange format'' archives, + o POSIX octet-oriented cpio archives, + o 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 pax(1) implemen- + tations on many systems as well as several newer implementations of + tar(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 archive_read_XXX() func- + tions and the archive_write_XXX() functions, respectively, and either can + be used independently of the other. + + The rest of this manual page provides an overview of the library opera- + tion. More detailed information can be found in the individual manual + pages for each API or utility function. + +READING AN ARCHIVE + To read an archive, you must first obtain an initialized struct archive + object from archive_read_new(). You can then modify this object for the + desired operations with the various archive_read_set_XXX() and + archive_read_support_XXX() functions. In particular, you will need to + invoke appropriate archive_read_support_XXX() 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 corre- + sponding auto-detect code. Unless you have specific constraints, you + will generally want to invoke archive_read_support_compression_all() and + archive_read_support_format_all() to enable auto-detect for all formats + and compression types currently supported by the library. + + Once you have prepared the struct archive object, you call + archive_read_open() to actually open the archive and prepare it for read- + ing. 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, FILE * 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 archive_read_next_header(), + which returns a pointer to an struct archive_entry structure with infor- + mation 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 + archive_read_data() (which works much like the read(2) system call) to + read this data from the archive. You may prefer to use the higher-level + archive_read_data_skip(), which reads and discards the data for this + entry, archive_read_data_to_buffer(), which reads the data into an in- + memory buffer, archive_read_data_to_file(), which copies the data to the + provided file descriptor, or archive_read_extract(), which recreates the + specified entry on disk and copies data from the archive. In particular, + note that archive_read_extract() uses the 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 + archive_read_close() to close the archive, then call + archive_read_finish() to release all resources, including all memory + allocated by the library. + + The archive_read(3) manual page provides more detailed calling informa- + tion for this API. + +WRITING AN ARCHIVE + You use a similar process to write an archive. The archive_write_new() + function creates an archive object useful for writing, the various + archive_write_set_XXX() functions are used to set parameters for writing + the archive, and archive_write_open() completes the setup and opens the + archive for writing. + + Individual archive entries are written in a three-step process: You first + initialize a struct archive_entry structure with information about the + new entry. At a minimum, you should set the pathname of the entry and + provide a struct stat with a valid st_mode field, which specifies the + type of object and st_size field, which specifies the size of the data + portion of the object. The archive_write_header() function actually + writes the header data to the archive. You can then use + archive_write_data() to write the actual data. + + After all entries have been written, use the archive_write_finish() func- + tion to release all resources. + + The archive_write(3) manual page provides more detailed calling informa- + tion for this API. + +DESCRIPTION + Detailed descriptions of each function are provided by the corresponding + manual pages. + + All of the functions utilize an opaque struct archive datatype that pro- + vides access to the archive contents. + + The struct archive_entry structure contains a complete description of a + single archive entry. It uses an opaque interface that is fully docu- + mented in archive_entry(3). + + Users familiar with historic formats should be aware that the newer vari- + ants 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 + PATH_MAX. + +RETURN VALUES + Most functions return zero on success, non-zero on error. The return + value indicates the general severity of the error, ranging from + ARCHIVE_WARN, which indicates a minor problem that should probably be + reported to the user, to ARCHIVE_FATAL, which indicates a serious problem + that will prevent any further operations on this archive. On error, the + archive_errno() function can be used to retrieve a numeric error code + (see errno(2)). The archive_error_string() returns a textual error mes- + sage suitable for display. + + archive_read_new() and archive_write_new() return pointers to an allo- + cated and initialized struct archive object. + + archive_read_data() and archive_write_data() 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 archive_errno() and archive_error_string() functions can be used + to obtain more information. + +ENVIRONMENT + There are character set conversions within the archive_entry(3) functions + that are impacted by the currently-selected locale. + +SEE ALSO + tar(1), archive_entry(3), archive_read(3), archive_util(3), + archive_write(3), tar(5) + +HISTORY + The libarchive library first appeared in FreeBSD 5.3. + +AUTHORS + The libarchive library was written by Tim Kientzle . + +BUGS + Some archive formats support information that is not supported by 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 struct archive_entry is supported by all formats. For example, cpio + formats do not support nanosecond timestamps; old tar formats do not sup- + port large device numbers. + +FreeBSD 6.0 August 19, 2006 FreeBSD 6.0 diff --git a/libarchive/libarchive-2.4.17/doc/text/libarchive_internals.3 b/libarchive/libarchive-2.4.17/doc/text/libarchive_internals.3 new file mode 100644 index 0000000..4e398a1 --- /dev/null +++ b/libarchive/libarchive-2.4.17/doc/text/libarchive_internals.3 @@ -0,0 +1,248 @@ +LIBARCHIVE(3) FreeBSD Library Functions Manual LIBARCHIVE(3) + +NAME + libarchive_internals -- description of libarchive internal interfaces + +OVERVIEW + The libarchive 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 ar- + chive and compression formats. + +GENERAL ARCHITECTURE + Externally, libarchive exposes most operations through an opaque, object- + style interface. The archive_entry(1) objects store information about a + single filesystem object. The rest of the library provides facilities to + write archive_entry(1) objects to archive files, read them from archive + files, and write them to disk. (There are plans to add a facility to + read archive_entry(1) objects from disk as well.) + + The read and write APIs each have four layers: a public API layer, a for- + mat 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. + +READ ARCHITECTURE + From the outside, clients use the archive_read(3) API to manipulate an + archive object to read entries and bodies from an archive stream. Inter- + nally, the archive object is cast to an archive_read 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 + archive_read_open_memory(3), and archive_read_open_fd(3). The compres- + sion 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 archive_entry 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 ar- + chive, 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 bid- + ders were invoked for each entry, but this design hindered error recov- + ery.) + + 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 call- + back 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 mmap(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. + + 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 decom- + pression 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 avail- + able, 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 consume() function advances the read pointer. + Note that data returned from a read_ahead() call is guaranteed to remain + in place until the next call to read_ahead(). Intervening calls to + consume() 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: + Registration/Configuration + When the client invokes the public support function, the decom- + pression handler invokes the internal + __archive_read_register_compression() function to provide bid and + initialization functions. This function returns NULL on error or + else a pointer to a struct decompressor_t. This structure con- + tains a void * config slot that can be used for storing any cus- + tomization information. + 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 + decompressor element of the archive_read object. The bid func- + tion 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.) + Initialize + The winning bidder will have its init function called. This + function should initialize the remaining slots of the struct + decompressor_t object pointed to by the decompressor element of + the archive_read object. In particular, it should allocate any + working data it needs in the data 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. + Satisfy I/O requests + The format handler will invoke the read_ahead, consume, and skip + functions as needed. + Finish The finish method is called only once when the archive is closed. + It should release anything stored in the data and config slots of + the decompressor object. It should not invoke the client close + callback. + + Format Layer + The read formats have a similar lifecycle to the decompression handlers: + Registration + Allocate your private data and initialize your pointers. + Bid Formats bid by invoking the read_ahead() decompression method but + not calling the consume() 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.) + 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. + 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. Remem- + ber 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. + 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 data_skip() function. + Cleanup + On cleanup, the format should release all of its allocated mem- + ory. + + API Layer + XXX to do XXX + +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 regis- + tered at a time. + + I/O Layer and Client Callbacks + XXX To be written XXX + + Compression Layer + XXX To be written XXX + + Format Layer + XXX To be written XXX + + API Layer + XXX To be written XXX + +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. + +GENERAL SERVICES + The archive_read, archive_write, and archive_write_disk objects all con- + tain an initial archive 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 archive 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. + +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. Direc- + tories are parsed when they are encountered and new items are added to + the list. This design relies heavily on the ISO9660 image being opti- + mized 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. + +SEE ALSO + archive(3), archive_entry(3), archive_read(3), archive_write(3), + archive_write_disk(3) + +HISTORY + The libarchive library first appeared in FreeBSD 5.3. + +AUTHORS + The libarchive library was written by Tim Kientzle . + +BUGS +FreeBSD 6.0 April 16, 2007 FreeBSD 6.0 diff --git a/libarchive/libarchive-2.4.17/doc/text/mtree.5 b/libarchive/libarchive-2.4.17/doc/text/mtree.5 new file mode 100644 index 0000000..1e5eb4f --- /dev/null +++ b/libarchive/libarchive-2.4.17/doc/text/mtree.5 @@ -0,0 +1,158 @@ +MTREE(5) FreeBSD File Formats Manual MTREE(5) + +NAME + mtree -- format of mtree dir heirarchy files + +DESCRIPTION + The mtree format is a textual format that describes a collection of + filesystem objects. Such files are typically used to create or verify + directory heirarchies. + + General Format + An mtree 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 back- + slash followed by three octal digits. When reading mtree files, any + appearance of a backslash followed by three octal digits should be con- + verted into the corresponding character. + + Each line is interpreted independently as one of the following types: + + 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''. + + Blank Blank lines are ignored. + + Comment Lines beginning with # are ignored. + + Special Lines beginning with / are special commands that influence + the interpretation of later lines. + + Relative If the first whitespace-delimited word has no / characters, + it is the name of a file in the current directory. Any rela- + tive entry that describes a directory changes the current + directory. + + dot-dot As a special case, a relative entry with the filename .. + changes the current directory to the parent directory. + Options on dot-dot entries are always ignored. + + Full If the first whitespace-delimited word has a / character + after the first character, it is the pathname of a file rela- + tive to the starting directory. There can be multiple full + entries describing the same file. + + Some tools that process mtree 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 spec- + ification. + + Special commands + Two special commands are currently defined: + + /set 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 key- + word. + + /unset This command removes any default value set by a previous /set + command. It is followed on the same line by one or more key- + words separated by whitespace. + + Keywords + After the filename, a full or relative entry consists of zero or more + whitespace-separated keyword definitions. Each such definitions consists + of a key from the following list immediately followed by an '=' sign and + a value. Software programs reading mtree files should warn about unrec- + ognized keywords. + + Currently supported keywords are as follows: + + cksum The checksum of the file using the default algorithm speci- + fied by the cksum(1) utility. + + contents The full pathname of a file whose contents should be compared + to the contents of this file. + + flags The file flags as a symbolic name. See chflags(1) for infor- + mation on these names. If no flags are to be set the string + ``none'' may be used to override the current default. + + ignore Ignore any file hierarchy below this file. + + gid The file group as a numeric value. + + gname The file group as a symbolic name. + + md5 The MD5 message digest of the file. + + md5digest A synonym for md5. + + sha1 The FIPS 160-1 (``SHA-1'') message digest of the file. + + sha1digest A synonym for sha1. + + sha256 The FIPS 180-2 (``SHA-256'') message digest of the file. + + sha256digest + A synonym for sha256. + + ripemd160digest + The RIPEMD160 message digest of the file. + + rmd160 A synonym for ripemd160digest. + + rmd160digest + A synonym for ripemd160digest. + + mode The current file's permissions as a numeric (octal) or sym- + bolic value. + + nlink The number of hard links the file is expected to have. + + nochange Make sure this file or directory exists but otherwise ignore + all attributes. + + uid The file owner as a numeric value. + + uname The file owner as a symbolic name. + + size The size, in bytes, of the file. + + link The file the symbolic link is expected to reference. + + time The last modification time of the file. + + type The type of the file; may be set to any one of the following: + + block block special device + char character special device + dir directory + fifo fifo + file regular file + link symbolic link + socket socket + +SEE ALSO + cksum(1), find(1), mtree(8) + +BUGS + The FreeBSD implementation of mtree does not currently support the mtree + 2.0 format. The requirement for a ``#mtree'' signature line is new and + not yet widely implemented. + +HISTORY + The mtree utility appeared in 4.3BSD-Reno. The MD5 digest capability was + added in FreeBSD 2.1, in response to the widespread use of programs which + can spoof cksum(1). The SHA-1 and RIPEMD160 digests were added in + FreeBSD 4.0, as new attacks have demonstrated weaknesses in MD5. The + 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. + +FreeBSD 6.0 August 20, 2007 FreeBSD 6.0 diff --git a/libarchive/libarchive-2.4.17/doc/text/tar.5 b/libarchive/libarchive-2.4.17/doc/text/tar.5 new file mode 100644 index 0000000..24b77e1 --- /dev/null +++ b/libarchive/libarchive-2.4.17/doc/text/tar.5 @@ -0,0 +1,534 @@ +TAR(5) FreeBSD File Formats Manual TAR(5) + +NAME + tar -- format of tape archive files + +DESCRIPTION + The tar 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. + + General Format + A tar 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--and the maximum sup- + ported by historic implementations--is 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 document- + ing pdtar.) + + 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 + Version 7 AT&T UNIX, which is one of the earliest widely-used versions of + the tar program. + + The header record for an old-style tar archive consists of the following: + + 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]; + }; + All unused bytes in the header record are filled with nulls. + + name Pathname, stored as a null-terminated string. Early tar imple- + mentations only stored regular files (including hardlinks to + those files). One common early convention used a trailing "/" + character to indicate a directory name, allowing directory per- + missions and owner information to be archived and restored. + + mode File mode, stored as an octal number in ASCII. + + uid, gid + User id and group id of owner, as octal numbers in ASCII. + + size 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. + + mtime 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. + + checksum + 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 inter- + operability problems when transferring archives between systems. + Modern robust readers compute the checksum both ways and accept + the header if either computation matches. + + linkflag, linkname + 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 linkflag is + set to an ASCII `1' and the linkname field holds the first name + under which this file appears. (Note that regular files have a + null value in the linkflag field.) + + Early tar implementations varied in how they terminated these fields. + The tar command in Version 7 AT&T UNIX 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 prac- + tice 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. + + Pre-POSIX Archives + An early draft of IEEE Std 1003.1-1988 (``POSIX.1'') served as the basis + for John Gilmore's pdtar 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: + o The magic value is ``ustar '' (note the following space). The + version field contains a space character followed by a null. + o The numeric fields are generally filled with leading spaces (not + leading zeros as recommended in the final standard). + o The prefix field is often not used, limiting pathnames to the 100 + characters of old-style archives. + + 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 tar(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: + + 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]; + }; + + typeflag + Type of entry. POSIX extended the earlier linkflag field with + several new type values: + ``0'' Regular file. NULL should be treated as a synonym, for + compatibility purposes. + ``1'' Hard link. + ``2'' Symbolic link. + ``3'' Character device node. + ``4'' Block device node. + ``5'' Directory. + ``6'' FIFO node. + ``7'' Reserved. + Other A POSIX-compliant implementation must treat any unrecog- + nized typeflag value as a regular file. In particular, + writers should ensure that all entries have a valid file- + name 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 size field, in particular, has dif- + ferent 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. + + magic Contains the magic value ``ustar'' followed by a NULL byte to + indicate that this is a POSIX standard archive. Full compliance + requires the uname and gname fields be properly set. + + version + Version. This should be ``00'' (two copies of the ASCII digit + zero) for POSIX standard archives. + + uname, gname + 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. + + devmajor, devminor + Major and minor numbers for character device or block device + entry. + + prefix 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 / character with the first portion going here. If the prefix + field is not empty, the reader will prepend the prefix value and + a / character to the regular name field to obtain the full path- + name. + + Note that all unused bytes must be set to NULL. + + Field termination is specified slightly differently by POSIX than by pre- + vious implementations. The magic, uname, and gname fields must have a + trailing NULL. The pathname, linkname, and prefix fields must have a + trailing NULL unless they fill the entire field. (In particular, it is + possible to store a 256-character pathname if it happens to have a / 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 NULL + characters. + + Currently, most tar implementations comply with the ustar format, occa- + sionally extending it by adding new fields to the blank area at the end + of the header record. + + 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 meta- + data that applies to following entries. Note that a pax interchange for- + mat 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 meta- + data can be examined as necessary. + + An entry in a pax interchange format archive consists of one or two stan- + dard 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 indi- + cates 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: + 25 ctime=1084839148.1212\n + 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 deci- + mal, not octal. A description of some common keys follows: + + atime, ctime, mtime + File access, inode change, and modification times. These fields + can be negative or include a decimal point and a fractional + value. + + uname, uid, gname, gid + 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. + + linkpath + The full path of the linked-to file. Note that this is encoded + in UTF8 and can thus include non-ASCII characters. + + path The full pathname of the entry. Note that this is encoded in + UTF8 and can thus include non-ASCII characters. + + realtime.*, security.* + These keys are reserved and may be used for future standardiza- + tion. + + size 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. + + SCHILY.* + Vendor-specific attributes used by Joerg Schilling's star imple- + mentation. + + SCHILY.acl.access, SCHILY.acl.default + 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). + + SCHILY.devminor, SCHILY.devmajor + The full minor and major numbers for device nodes. + + SCHILY.dev, SCHILY.ino, SCHILY.nlinks + The device number, inode number, and link count for the entry. + In particular, note that a pax interchange format archive using + Joerg Schilling's SCHILY.* extensions can store all of the data + from struct stat. + + LIBARCHIVE.xattr.namespace.key + Libarchive stores POSIX.1e-style extended attributes using keys + of this form. The key value is URL-encoded: All non-ASCII char- + acters 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 + + VENDOR.* + 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 arbitrar- + ily 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 x entry described above, the pax interchange format + also supports a g entry. The g entry is identical in format, but speci- + fies attributes that serve as defaults for all subsequent archive + entries. The g entry is not widely used. + + Besides the new x and g 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. + + 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 mod- + ify following entries (similar in principle to the x entry described + above, but each GNU special entry is single-purpose, unlike the general- + purpose x entry). As a result, GNU tar archives are not POSIX compati- + ble, although more lenient POSIX-compliant readers can successfully + extract most GNU tar archives. + + 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]; + }; + + typeflag + GNU tar uses the following special entry types, in addition to + those defined by POSIX: + + 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. + + D This indicates a directory entry. Unlike the POSIX-stan- + dard "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 ar- + chive 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. + + K The data for this entry is a long linkname for the fol- + lowing regular entry. + + L The data for this entry is a long pathname for the fol- + lowing regular entry. + + 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 vol- + ume. The "M" typeflag indicates that this entry contin- + ues 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 size field spec- + ifies the size of this entry. The offset field at bytes + 369-380 specifies the offset where this file fragment + begins. The realsize field specifies the total size of + the file (which must equal size plus offset). 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. + + 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\n'' or ``Symlink %s to %s\n''; in + either case, both filenames are escaped using K&R C syn- + tax. + + 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 nec- + essary with ``extra'' header extensions (an older format + that is no longer used), or ``sparse'' extensions. + + V The name field should be interpreted as a tape/volume + header name. This entry should generally be ignored on + extraction. + + magic The magic field holds the five characters ``ustar'' followed by a + space. Note that POSIX ustar archives have a trailing null. + + version + The version field holds a space character followed by a null. + Note that POSIX ustar archives use two copies of the ASCII digit + ``0''. + + atime, ctime + The time the file was last accessed and the time of last change + of file information, stored in octal as with mtime. + + longnames + This field is apparently no longer used. + + Sparse offset / numbytes + 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. + + isextended + If this is set to non-zero, the header will be followed by addi- + tional ``sparse header'' records. Each such record contains + information about as many as 21 additional sparse blocks as shown + here: + + struct gnu_sparse_header { + struct { + char offset[12]; + char numbytes[12]; + } sparse[21]; + char isextended[1]; + char padding[7]; + }; + + realsize + A binary representation of the file's complete size, with a much + larger range than the POSIX file size. In particular, with M + 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 realsize field will indicate the total size of the + file. + + 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 for- + mat, with the following differences: + o Extended attributes are stored in an entry whose type is X, not + x, as used by pax interchange format. The detailed format of + this entry appears to be the same as detailed above for the x + entry. + o An additional A 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. + + Other Extensions + One common extension, utilized by GNU tar, star, and other newer tar + 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. + +SEE ALSO + ar(1), pax(1), tar(1) + +STANDARDS + The tar 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 pax(1). + The ustar format is currently part of the specification for the pax(1) + utility. The pax interchange file format is new with IEEE Std + 1003.1-2001 (``POSIX.1''). + +HISTORY + A tar command appeared in Seventh Edition Unix, which was released in + January, 1979. It replaced the tp program from Fourth Edition Unix which + in turn replaced the tap program from First Edition Unix. John Gilmore's + pdtar public-domain implementation (circa 1987) was highly influential + and formed the basis of GNU tar. Joerg Shilling's star archiver is + another open-source (GPL) archiver (originally developed circa 1985) + which features complete support for pax interchange format. + +FreeBSD 6.0 May 20, 2004 FreeBSD 6.0 diff --git a/libarchive/libarchive-2.4.17/doc/update.sh b/libarchive/libarchive-2.4.17/doc/update.sh new file mode 100755 index 0000000..644b90a --- /dev/null +++ b/libarchive/libarchive-2.4.17/doc/update.sh @@ -0,0 +1,47 @@ +#!/bin/sh + +# +# Simple script to repopulate the 'doc' tree from +# the mdoc man pages stored in each project. +# + +# Remove existing manpages from the doc tree +chmod -R +w man text +rm -f man/*.[135] +rm -f text/*.[135] + +# Build Makefile in 'man' directory +cd man +echo > Makefile +echo "default: all" >>Makefile +echo >>Makefile +all="all:" +for d in libarchive tar cpio; do + for f in ../../$d/*.[135]; do + echo >> Makefile + echo `basename $f`: ../mdoc2man.awk $f >> Makefile + echo " awk -f ../mdoc2man.awk < $f > `basename $f`" >> Makefile + all="$all `basename $f`" + done +done +echo $all >>Makefile +cd .. + +# Rebuild Makefile in 'text' directory +cd text +echo > Makefile +echo "$all" >>Makefile +echo >>Makefile +for d in libarchive tar cpio; do + for f in ../../$d/*.[135]; do + echo >> Makefile + echo `basename $f`: $f >> Makefile + echo " nroff -mdoc $f | col -b > `basename $f`" >> Makefile + done +done +cd .. + +# Convert all of the manpages to -man format. +(cd man && make) +# Format all of the manpages to text +(cd text && make) -- cgit v1.2.3