diff options
Diffstat (limited to 'libarchive/libarchive-2.8.0/doc')
78 files changed, 0 insertions, 26645 deletions
diff --git a/libarchive/libarchive-2.8.0/doc/html/Makefile b/libarchive/libarchive-2.8.0/doc/html/Makefile deleted file mode 100644 index dcab40e..0000000 --- a/libarchive/libarchive-2.8.0/doc/html/Makefile +++ /dev/null @@ -1,46 +0,0 @@ - -default: all - - -archive_entry.3.html: ../mdoc2man.awk ../../libarchive/archive_entry.3 - groff -mdoc -T html ../../libarchive/archive_entry.3 > archive_entry.3.html - -archive_read.3.html: ../mdoc2man.awk ../../libarchive/archive_read.3 - groff -mdoc -T html ../../libarchive/archive_read.3 > archive_read.3.html - -archive_read_disk.3.html: ../mdoc2man.awk ../../libarchive/archive_read_disk.3 - groff -mdoc -T html ../../libarchive/archive_read_disk.3 > archive_read_disk.3.html - -archive_util.3.html: ../mdoc2man.awk ../../libarchive/archive_util.3 - groff -mdoc -T html ../../libarchive/archive_util.3 > archive_util.3.html - -archive_write.3.html: ../mdoc2man.awk ../../libarchive/archive_write.3 - groff -mdoc -T html ../../libarchive/archive_write.3 > archive_write.3.html - -archive_write_disk.3.html: ../mdoc2man.awk ../../libarchive/archive_write_disk.3 - groff -mdoc -T html ../../libarchive/archive_write_disk.3 > archive_write_disk.3.html - -cpio.5.html: ../mdoc2man.awk ../../libarchive/cpio.5 - groff -mdoc -T html ../../libarchive/cpio.5 > cpio.5.html - -libarchive-formats.5.html: ../mdoc2man.awk ../../libarchive/libarchive-formats.5 - groff -mdoc -T html ../../libarchive/libarchive-formats.5 > libarchive-formats.5.html - -libarchive.3.html: ../mdoc2man.awk ../../libarchive/libarchive.3 - groff -mdoc -T html ../../libarchive/libarchive.3 > libarchive.3.html - -libarchive_internals.3.html: ../mdoc2man.awk ../../libarchive/libarchive_internals.3 - groff -mdoc -T html ../../libarchive/libarchive_internals.3 > libarchive_internals.3.html - -mtree.5.html: ../mdoc2man.awk ../../libarchive/mtree.5 - groff -mdoc -T html ../../libarchive/mtree.5 > mtree.5.html - -tar.5.html: ../mdoc2man.awk ../../libarchive/tar.5 - groff -mdoc -T html ../../libarchive/tar.5 > tar.5.html - -bsdtar.1.html: ../mdoc2man.awk ../../tar/bsdtar.1 - groff -mdoc -T html ../../tar/bsdtar.1 > bsdtar.1.html - -bsdcpio.1.html: ../mdoc2man.awk ../../cpio/bsdcpio.1 - groff -mdoc -T html ../../cpio/bsdcpio.1 > bsdcpio.1.html -all: archive_entry.3.html archive_read.3.html archive_read_disk.3.html archive_util.3.html archive_write.3.html archive_write_disk.3.html cpio.5.html libarchive-formats.5.html libarchive.3.html libarchive_internals.3.html mtree.5.html tar.5.html bsdtar.1.html bsdcpio.1.html diff --git a/libarchive/libarchive-2.8.0/doc/html/archive_entry.3.html b/libarchive/libarchive-2.8.0/doc/html/archive_entry.3.html deleted file mode 100644 index 7b30d72..0000000 --- a/libarchive/libarchive-2.8.0/doc/html/archive_entry.3.html +++ /dev/null @@ -1,694 +0,0 @@ -<!-- Creator : groff version 1.19.2 --> -<!-- CreationDate: Thu Feb 4 20:36:29 2010 --> -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" -"http://www.w3.org/TR/html4/loose.dtd"> -<html> -<head> -<meta name="generator" content="groff -Thtml, see www.gnu.org"> -<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> -<meta name="Content-Style" content="text/css"> -<style type="text/css"> - p { margin-top: 0; margin-bottom: 0; } - pre { margin-top: 0; margin-bottom: 0; } - table { margin-top: 0; margin-bottom: 0; } -</style> -<title></title> -</head> -<body> - -<hr> - - -<p valign="top">archive_entry(3) FreeBSD Library Functions -Manual archive_entry(3)</p> - -<p style="margin-top: 1em" valign="top"><b>NAME</b></p> - - -<p style="margin-left:8%;"><b>archive_entry_acl_add_entry</b>, -<b>archive_entry_acl_add_entry_w</b>, -<b>archive_entry_acl_clear</b>, -<b>archive_entry_acl_count</b>, -<b>archive_entry_acl_next</b>, -<b>archive_entry_acl_next_w</b>, -<b>archive_entry_acl_reset</b>, -<b>archive_entry_acl_text_w</b>, <b>archive_entry_atime</b>, -<b>archive_entry_atime_nsec</b>, <b>archive_entry_clear</b>, -<b>archive_entry_clone</b>, -<b>archive_entry_copy_fflags_text</b>, -<b>archive_entry_copy_fflags_text_w</b>, -<b>archive_entry_copy_gname</b>, -<b>archive_entry_copy_gname_w</b>, -<b>archive_entry_copy_hardlink</b>, -<b>archive_entry_copy_hardlink_w</b>, -<b>archive_entry_copy_link</b>, -<b>archive_entry_copy_link_w</b>, -<b>archive_entry_copy_pathname_w</b>, -<b>archive_entry_copy_sourcepath</b>, -<b>archive_entry_copy_stat</b>, -<b>archive_entry_copy_symlink</b>, -<b>archive_entry_copy_symlink_w</b>, -<b>archive_entry_copy_uname</b>, -<b>archive_entry_copy_uname_w</b>, <b>archive_entry_dev</b>, -<b>archive_entry_devmajor</b>, -<b>archive_entry_devminor</b>, -<b>archive_entry_filetype</b>, <b>archive_entry_fflags</b>, -<b>archive_entry_fflags_text</b>, <b>archive_entry_free</b>, -<b>archive_entry_gid</b>, <b>archive_entry_gname</b>, -<b>archive_entry_hardlink</b>, <b>archive_entry_ino</b>, -<b>archive_entry_mode</b>, <b>archive_entry_mtime</b>, -<b>archive_entry_mtime_nsec</b>, <b>archive_entry_nlink</b>, -<b>archive_entry_new</b>, <b>archive_entry_pathname</b>, -<b>archive_entry_pathname_w</b>, <b>archive_entry_rdev</b>, -<b>archive_entry_rdevmajor</b>, -<b>archive_entry_rdevminor</b>, -<b>archive_entry_set_atime</b>, -<b>archive_entry_set_ctime</b>, -<b>archive_entry_set_dev</b>, -<b>archive_entry_set_devmajor</b>, -<b>archive_entry_set_devminor</b>, -<b>archive_entry_set_filetype</b>, -<b>archive_entry_set_fflags</b>, -<b>archive_entry_set_gid</b>, -<b>archive_entry_set_gname</b>, -<b>archive_entry_set_hardlink</b>, -<b>archive_entry_set_link</b>, -<b>archive_entry_set_mode</b>, -<b>archive_entry_set_mtime</b>, -<b>archive_entry_set_pathname</b>, -<b>archive_entry_set_rdevmajor</b>, -<b>archive_entry_set_rdevminor</b>, -<b>archive_entry_set_size</b>, -<b>archive_entry_set_symlink</b>, -<b>archive_entry_set_uid</b>, -<b>archive_entry_set_uname</b>, <b>archive_entry_size</b>, -<b>archive_entry_sourcepath</b>, <b>archive_entry_stat</b>, -<b>archive_entry_symlink</b>, <b>archive_entry_uid</b>, -<b>archive_entry_uname</b> — functions for -manipulating archive entry descriptions</p> - - -<p style="margin-top: 1em" valign="top"><b>SYNOPSIS</b></p> - -<p style="margin-left:8%;"><b>#include -<archive_entry.h></b></p> - -<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> - - -<p valign="top"><b>archive_entry_acl_add_entry</b>(<i>struct archive_entry *</i>, -<i>int type</i>, <i>int permset</i>, -<i>int tag</i>, <i>int qual</i>, -<i>const char *name</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> - - -<p valign="top"><b>archive_entry_acl_add_entry_w</b>(<i>struct archive_entry *</i>, -<i>int type</i>, <i>int permset</i>, -<i>int tag</i>, <i>int qual</i>, -<i>const wchar_t *name</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_acl_clear</b>(<i>struct archive_entry *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_acl_count</b>(<i>struct archive_entry *</i>, -<i>int type</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p valign="top"><b>archive_entry_acl_next</b>(<i>struct archive_entry *</i>, -<i>int want_type</i>, <i>int *type</i>, -<i>int *permset</i>, <i>int *tag</i>, -<i>int *qual</i>, -<i>const char **name</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p valign="top"><b>archive_entry_acl_next_w</b>(<i>struct archive_entry *</i>, -<i>int want_type</i>, <i>int *type</i>, -<i>int *permset</i>, <i>int *tag</i>, -<i>int *qual</i>, -<i>const wchar_t **name</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_acl_reset</b>(<i>struct archive_entry *</i>, -<i>int want_type</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>const wchar_t -*</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_acl_text_w</b>(<i>struct archive_entry *</i>, -<i>int flags</i>);</p> - - -<p style="margin-left:8%; margin-top: 1em"><i>time_t</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_atime</b>(<i>struct archive_entry *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>long</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_atime_nsec</b>(<i>struct archive_entry *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>struct -archive_entry *</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_clear</b>(<i>struct archive_entry *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>struct -archive_entry *</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_clone</b>(<i>struct archive_entry *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>const char * -*</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_copy_fflags_text_w</b>(<i>struct archive_entry *</i>, -<i>const char *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>const wchar_t -*</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_copy_fflags_text_w</b>(<i>struct archive_entry *</i>, -<i>const wchar_t *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_copy_gname</b>(<i>struct archive_entry *</i>, -<i>const char *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_copy_gname_w</b>(<i>struct archive_entry *</i>, -<i>const wchar_t *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_copy_hardlink</b>(<i>struct archive_entry *</i>, -<i>const char *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_copy_hardlink_w</b>(<i>struct archive_entry *</i>, -<i>const wchar_t *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_copy_sourcepath</b>(<i>struct archive_entry *</i>, -<i>const char *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_copy_pathname_w</b>(<i>struct archive_entry *</i>, -<i>const wchar_t *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_copy_stat</b>(<i>struct archive_entry *</i>, -<i>const struct stat *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_copy_symlink</b>(<i>struct archive_entry *</i>, -<i>const char *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_copy_symlink_w</b>(<i>struct archive_entry *</i>, -<i>const wchar_t *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_copy_uname</b>(<i>struct archive_entry *</i>, -<i>const char *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_copy_uname_w</b>(<i>struct archive_entry *</i>, -<i>const wchar_t *</i>);</p> - - -<p style="margin-left:8%; margin-top: 1em"><i>dev_t</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_dev</b>(<i>struct archive_entry *</i>);</p> - - -<p style="margin-left:8%; margin-top: 1em"><i>dev_t</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_devmajor</b>(<i>struct archive_entry *</i>);</p> - - -<p style="margin-left:8%; margin-top: 1em"><i>dev_t</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_devminor</b>(<i>struct archive_entry *</i>);</p> - - -<p style="margin-left:8%; margin-top: 1em"><i>mode_t</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_filetype</b>(<i>struct archive_entry *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> - - -<p valign="top"><b>archive_entry_fflags</b>(<i>struct archive_entry *</i>, -<i>unsigned long *set</i>, -<i>unsigned long *clear</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>const char -*</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_fflags_text</b>(<i>struct archive_entry *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_free</b>(<i>struct archive_entry *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>const char -*</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_gname</b>(<i>struct archive_entry *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>const char -*</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_hardlink</b>(<i>struct archive_entry *</i>);</p> - - -<p style="margin-left:8%; margin-top: 1em"><i>ino_t</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_ino</b>(<i>struct archive_entry *</i>);</p> - - -<p style="margin-left:8%; margin-top: 1em"><i>mode_t</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_mode</b>(<i>struct archive_entry *</i>);</p> - - -<p style="margin-left:8%; margin-top: 1em"><i>time_t</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_mtime</b>(<i>struct archive_entry *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>long</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_mtime_nsec</b>(<i>struct archive_entry *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>unsigned -int</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_nlink</b>(<i>struct archive_entry *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>struct -archive_entry *</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_new</b>(<i>void</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>const char -*</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_pathname</b>(<i>struct archive_entry *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>const wchar_t -*</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_pathname_w</b>(<i>struct archive_entry *</i>);</p> - - -<p style="margin-left:8%; margin-top: 1em"><i>dev_t</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_rdev</b>(<i>struct archive_entry *</i>);</p> - - -<p style="margin-left:8%; margin-top: 1em"><i>dev_t</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_rdevmajor</b>(<i>struct archive_entry *</i>);</p> - - -<p style="margin-left:8%; margin-top: 1em"><i>dev_t</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_rdevminor</b>(<i>struct archive_entry *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_set_dev</b>(<i>struct archive_entry *</i>, -<i>dev_t</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_set_devmajor</b>(<i>struct archive_entry *</i>, -<i>dev_t</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_set_devminor</b>(<i>struct archive_entry *</i>, -<i>dev_t</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_set_filetype</b>(<i>struct archive_entry *</i>, -<i>unsigned int</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> - - -<p valign="top"><b>archive_entry_set_fflags</b>(<i>struct archive_entry *</i>, -<i>unsigned long set</i>, -<i>unsigned long clear</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_set_gid</b>(<i>struct archive_entry *</i>, -<i>gid_t</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_set_gname</b>(<i>struct archive_entry *</i>, -<i>const char *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_set_hardlink</b>(<i>struct archive_entry *</i>, -<i>const char *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_set_ino</b>(<i>struct archive_entry *</i>, -<i>unsigned long</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_set_link</b>(<i>struct archive_entry *</i>, -<i>const char *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_set_mode</b>(<i>struct archive_entry *</i>, -<i>mode_t</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_set_mtime</b>(<i>struct archive_entry *</i>, -<i>time_t</i>, <i>long nanos</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_set_nlink</b>(<i>struct archive_entry *</i>, -<i>unsigned int</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_set_pathname</b>(<i>struct archive_entry *</i>, -<i>const char *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_set_rdev</b>(<i>struct archive_entry *</i>, -<i>dev_t</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_set_rdevmajor</b>(<i>struct archive_entry *</i>, -<i>dev_t</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_set_rdevminor</b>(<i>struct archive_entry *</i>, -<i>dev_t</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_set_size</b>(<i>struct archive_entry *</i>, -<i>int64_t</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_set_symlink</b>(<i>struct archive_entry *</i>, -<i>const char *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_set_uid</b>(<i>struct archive_entry *</i>, -<i>uid_t</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_set_uname</b>(<i>struct archive_entry *</i>, -<i>const char *</i>);</p> - - -<p style="margin-left:8%; margin-top: 1em"><i>int64_t</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_size</b>(<i>struct archive_entry *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>const char -*</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_sourcepath</b>(<i>struct archive_entry *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>const struct -stat *</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_stat</b>(<i>struct archive_entry *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>const char -*</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_symlink</b>(<i>struct archive_entry *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>const char -*</i></p> - - -<p style="margin-left:14%;"><b>archive_entry_uname</b>(<i>struct archive_entry *</i>);</p> - - -<p style="margin-top: 1em" valign="top"><b>DESCRIPTION</b></p> - -<p style="margin-left:8%;">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.</p> - -<p style="margin-left:8%; margin-top: 1em"><b>Create and -Destroy</b> <br> -There are functions to allocate, destroy, clear, and copy -<i>archive_entry</i> objects:</p> - -<p valign="top"><b>archive_entry_clear</b>()</p> - -<p style="margin-left:20%;">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.</p> - -<p valign="top"><b>archive_entry_clone</b>()</p> - -<p style="margin-left:20%;">A deep copy operation; all text -fields are duplicated.</p> - -<p valign="top"><b>archive_entry_free</b>()</p> - -<p style="margin-left:20%;">Releases the struct -archive_entry object.</p> - -<p valign="top"><b>archive_entry_new</b>()</p> - -<p style="margin-left:20%;">Allocate and return a blank -struct archive_entry object.</p> - -<p style="margin-left:8%; margin-top: 1em"><b>Set and Get -Functions</b> <br> -Most of the functions here set or read entries in an object. -Such functions have one of the following forms:</p> - -<p valign="top"><b>archive_entry_set_XXXX</b>()</p> - -<p style="margin-left:20%;">Stores the provided data in the -object. In particular, for strings, the pointer is stored, -not the referenced string.</p> - -<p valign="top"><b>archive_entry_copy_XXXX</b>()</p> - -<p style="margin-left:20%;">As above, except that the -referenced data is copied into the object.</p> - -<p valign="top"><b>archive_entry_XXXX</b>()</p> - -<p style="margin-left:20%;">Returns the specified data. In -the case of strings, a const-qualified pointer to the string -is returned.</p> - -<p style="margin-left:8%;">String data can be set or -accessed as wide character strings or normal <i>char</i> -strings. The functions that use wide character strings are -suffixed with <b>_w</b>. 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.</p> - -<p style="margin-left:8%; margin-top: 1em">There are a few -set/get functions that merit additional description:</p> - -<p valign="top"><b>archive_entry_set_link</b>()</p> - -<p style="margin-left:20%;">This function sets the symlink -field if it is already set. Otherwise, it sets the hardlink -field.</p> - -<p style="margin-left:8%; margin-top: 1em"><b>File -Flags</b> <br> -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.</p> - -<p style="margin-left:8%; margin-top: 1em">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.</p> - -<p style="margin-left:8%; margin-top: 1em">The canonical -text format is a comma-separated list of flag names. The -<b>archive_entry_copy_fflags_text</b>() and -<b>archive_entry_copy_fflags_text_w</b>() functions parse -the provided text and sets the internal bitmap values. This -is a platform-specific operation; names that are not -meaningful on the current platform will be ignored. The -function returns a pointer to the start of the first name -that was not recognized, or NULL if every name was -recognized. Note that every name--including names that -follow an unrecognized name--will be evaluated, and the -bitmaps will be set to reflect every name that is -recognized. (In particular, this differs from -strtofflags(3), which stops parsing at the first -unrecognized name.)</p> - -<p style="margin-left:8%; margin-top: 1em"><b>ACL -Handling</b> <br> -XXX This needs serious help. XXX</p> - -<p style="margin-left:8%; margin-top: 1em">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.</p> - -<p style="margin-left:8%; margin-top: 1em">XXX explain ACL -stuff XXX</p> - -<p style="margin-top: 1em" valign="top"><b>SEE ALSO</b></p> - -<p style="margin-left:8%;">archive(3)</p> - -<p style="margin-top: 1em" valign="top"><b>HISTORY</b></p> - -<p style="margin-left:8%;">The <b>libarchive</b> library -first appeared in FreeBSD 5.3.</p> - -<p style="margin-top: 1em" valign="top"><b>AUTHORS</b></p> - -<p style="margin-left:8%;">The <b>libarchive</b> library -was written by Tim Kientzle -⟨kientzle@acm.org⟩.</p> - - -<p style="margin-left:8%; margin-top: 1em">FreeBSD 8.0 -May 12, 2008 FreeBSD 8.0</p> -<hr> -</body> -</html> diff --git a/libarchive/libarchive-2.8.0/doc/html/archive_read.3.html b/libarchive/libarchive-2.8.0/doc/html/archive_read.3.html deleted file mode 100644 index c37fcac..0000000 --- a/libarchive/libarchive-2.8.0/doc/html/archive_read.3.html +++ /dev/null @@ -1,820 +0,0 @@ -<!-- Creator : groff version 1.19.2 --> -<!-- CreationDate: Thu Feb 4 20:36:31 2010 --> -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" -"http://www.w3.org/TR/html4/loose.dtd"> -<html> -<head> -<meta name="generator" content="groff -Thtml, see www.gnu.org"> -<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> -<meta name="Content-Style" content="text/css"> -<style type="text/css"> - p { margin-top: 0; margin-bottom: 0; } - pre { margin-top: 0; margin-bottom: 0; } - table { margin-top: 0; margin-bottom: 0; } -</style> -<title></title> -</head> -<body> - -<hr> - - -<p valign="top">archive_read(3) FreeBSD Library Functions -Manual archive_read(3)</p> - -<p style="margin-top: 1em" valign="top"><b>NAME</b></p> - -<p style="margin-left:8%;"><b>archive_read_new</b>, -<b>archive_read_set_filter_options</b>, -<b>archive_read_set_format_options</b>, -<b>archive_read_set_options</b>, -<b>archive_read_support_compression_all</b>, -<b>archive_read_support_compression_bzip2</b>, -<b>archive_read_support_compression_compress</b>, -<b>archive_read_support_compression_gzip</b>, -<b>archive_read_support_compression_lzma</b>, -<b>archive_read_support_compression_none</b>, -<b>archive_read_support_compression_xz</b>, -<b>archive_read_support_compression_program</b>, -<b>archive_read_support_compression_program_signature</b>, -<b>archive_read_support_format_all</b>, -<b>archive_read_support_format_ar</b>, -<b>archive_read_support_format_cpio</b>, -<b>archive_read_support_format_empty</b>, -<b>archive_read_support_format_iso9660</b>, -<b>archive_read_support_format_mtree, -archive_read_support_format_raw, -archive_read_support_format_tar</b>, -<b>archive_read_support_format_zip</b>, -<b>archive_read_open</b>, <b>archive_read_open2</b>, -<b>archive_read_open_fd</b>, <b>archive_read_open_FILE</b>, -<b>archive_read_open_filename</b>, -<b>archive_read_open_memory</b>, -<b>archive_read_next_header</b>, -<b>archive_read_next_header2</b>, <b>archive_read_data</b>, -<b>archive_read_data_block</b>, -<b>archive_read_data_skip</b>, -<b>archive_read_data_into_buffer</b>, -<b>archive_read_data_into_fd</b>, -<b>archive_read_extract</b>, <b>archive_read_extract2</b>, -<b>archive_read_extract_set_progress_callback</b>, -<b>archive_read_close</b>, <b>archive_read_finish</b> -— functions for reading streaming archives</p> - - -<p style="margin-top: 1em" valign="top"><b>SYNOPSIS</b></p> - -<p style="margin-left:8%;"><b>#include -<archive.h></b></p> - -<p style="margin-left:8%; margin-top: 1em"><i>struct -archive *</i></p> - - -<p style="margin-left:14%;"><b>archive_read_new</b>(<i>void</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_support_compression_all</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_support_compression_bzip2</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_support_compression_compress</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_support_compression_gzip</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_support_compression_lzma</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_support_compression_none</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_support_compression_xz</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p valign="top"><b>archive_read_support_compression_program</b>(<i>struct archive *</i>, -<i>const char *cmd</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p valign="top"><b>archive_read_support_compression_program_signature</b>(<i>struct archive *</i>, -<i>const char *cmd</i>, -<i>const void *signature</i>, -<i>size_t signature_length</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_support_format_all</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_support_format_ar</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_support_format_cpio</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_support_format_empty</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_support_format_iso9660</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_support_format_mtree</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_support_format_raw</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_support_format_tar</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_support_format_zip</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_set_filter_options</b>(<i>struct archive *</i>, -<i>const char *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_set_format_options</b>(<i>struct archive *</i>, -<i>const char *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_set_options</b>(<i>struct archive *</i>, -<i>const char *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p valign="top"><b>archive_read_open</b>(<i>struct archive *</i>, -<i>void *client_data</i>, -<i>archive_open_callback *</i>, -<i>archive_read_callback *</i>, -<i>archive_close_callback *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p valign="top"><b>archive_read_open2</b>(<i>struct archive *</i>, -<i>void *client_data</i>, -<i>archive_open_callback *</i>, -<i>archive_read_callback *</i>, -<i>archive_skip_callback *</i>, -<i>archive_close_callback *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_open_FILE</b>(<i>struct archive *</i>, -<i>FILE *file</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_open_fd</b>(<i>struct archive *</i>, -<i>int fd</i>, <i>size_t block_size</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p valign="top"><b>archive_read_open_filename</b>(<i>struct archive *</i>, -<i>const char *filename</i>, -<i>size_t block_size</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_open_memory</b>(<i>struct archive *</i>, -<i>void *buff</i>, <i>size_t size</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_next_header</b>(<i>struct archive *</i>, -<i>struct archive_entry **</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_next_header2</b>(<i>struct archive *</i>, -<i>struct archive_entry *</i>);</p> - - -<p style="margin-left:8%; margin-top: 1em"><i>ssize_t</i></p> - - -<p style="margin-left:14%;"><b>archive_read_data</b>(<i>struct archive *</i>, -<i>void *buff</i>, <i>size_t len</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p valign="top"><b>archive_read_data_block</b>(<i>struct archive *</i>, -<i>const void **buff</i>, <i>size_t *len</i>, -<i>off_t *offset</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_data_skip</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_data_into_buffer</b>(<i>struct archive *</i>, -<i>void *</i>, <i>ssize_t len</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_data_into_fd</b>(<i>struct archive *</i>, -<i>int fd</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p valign="top"><b>archive_read_extract</b>(<i>struct archive *</i>, -<i>struct archive_entry *</i>, -<i>int flags</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p valign="top"><b>archive_read_extract2</b>(<i>struct archive *src</i>, -<i>struct archive_entry *</i>, -<i>struct archive *dest</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> - - -<p valign="top"><b>archive_read_extract_set_progress_callback</b>(<i>struct archive *</i>, -<i>void (*func)(void *)</i>, -<i>void *user_data</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_close</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_finish</b>(<i>struct archive *</i>);</p> - - -<p style="margin-top: 1em" valign="top"><b>DESCRIPTION</b></p> - -<p style="margin-left:8%;">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:</p> - -<p valign="top"><b>archive_read_new</b>()</p> - -<p style="margin-left:20%;">Allocates and initializes a -struct archive object suitable for reading from an -archive.</p> - - -<p valign="top"><b>archive_read_support_compression_bzip2</b>(), -<b>archive_read_support_compression_compress</b>(), -<b>archive_read_support_compression_gzip</b>(), -<b>archive_read_support_compression_lzma</b>(), -<b>archive_read_support_compression_none</b>(), -<b>archive_read_support_compression_xz</b>()</p> - -<p style="margin-left:20%;">Enables auto-detection code and -decompression support for the specified compression. Returns -<b>ARCHIVE_OK</b> if the compression is fully supported, or -<b>ARCHIVE_WARN</b> if the compression is supported only -through an external program. Note that decompression using -an external program is usually slower than decompression -through built-in libraries. Note that -‘‘none’’ is always enabled by -default.</p> - - -<p valign="top"><b>archive_read_support_compression_all</b>()</p> - -<p style="margin-left:20%;">Enables all available -decompression filters.</p> - - -<p valign="top"><b>archive_read_support_compression_program</b>()</p> - -<p style="margin-left:20%;">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.</p> - - -<p valign="top"><b>archive_read_support_compression_program_signature</b>()</p> - -<p style="margin-left:20%;">This feeds data through the -specified external program but only if the initial bytes of -the data match the specified signature value.</p> - -<p valign="top"><b>archive_read_support_format_all</b>(), -<b>archive_read_support_format_ar</b>(), -<b>archive_read_support_format_cpio</b>(), -<b>archive_read_support_format_empty</b>(), -<b>archive_read_support_format_iso9660</b>(), -<b>archive_read_support_format_mtree</b>(), -<b>archive_read_support_format_tar</b>(), -<b>archive_read_support_format_zip</b>()</p> - -<p style="margin-left:20%;">Enables support---including -auto-detection code---for the specified archive format. For -example, <b>archive_read_support_format_tar</b>() enables -support for a variety of standard tar formats, old-style -tar, ustar, pax interchange format, and many common -variants. For convenience, -<b>archive_read_support_format_all</b>() enables support for -all available formats. Only empty archives are supported by -default.</p> - - -<p valign="top"><b>archive_read_support_format_raw</b>()</p> - -<p style="margin-left:20%;">The -‘‘raw’’ format handler allows -libarchive to be used to read arbitrary data. It treats any -data stream as an archive with a single entry. The pathname -of this entry is ‘‘data’’; all other -entry fields are unset. This is not enabled by -<b>archive_read_support_format_all</b>() in order to avoid -erroneous handling of damaged archives.</p> - -<p valign="top"><b>archive_read_set_filter_options</b>(), -<b>archive_read_set_format_options</b>(), -<b>archive_read_set_options</b>()</p> - -<p style="margin-left:20%;">Specifies options that will be -passed to currently-registered filters (including -decompression filters) and/or format readers. The argument -is a comma-separated list of individual options. Individual -options have one of the following forms:</p> - -<p valign="top"><i>option=value</i></p> - -<p style="margin-left:32%;">The option/value pair will be -provided to every module. Modules that do not accept an -option with this name will ignore it.</p> - -<p valign="top"><i>option</i></p> - -<p style="margin-left:32%; margin-top: 1em">The option will -be provided to every module with a value of -‘‘1’’.</p> - -<p valign="top"><i>!option</i></p> - -<p style="margin-left:32%;">The option will be provided to -every module with a NULL value.</p> - -<p valign="top"><i>module:option=value</i>, -<i>module:option</i>, <i>module:!option</i></p> - -<p style="margin-left:32%;">As above, but the corresponding -option and value will be provided only to modules whose name -matches <i>module</i>.</p> - -<p style="margin-left:20%;">The return value will be -<b>ARCHIVE_OK</b> if any module accepts the option, or -<b>ARCHIVE_WARN</b> if no module accepted the option, or -<b>ARCHIVE_FATAL</b> if there was a fatal error while -attempting to process the option.</p> - -<p style="margin-left:20%; margin-top: 1em">The currently -supported options are:</p> - -<p valign="top">Format iso9660 <b><br> -joliet</b></p> - -<p style="margin-left:45%; margin-top: 1em">Support Joliet -extensions. Defaults to enabled, use <b>!joliet</b> to -disable.</p> - -<p valign="top"><b>archive_read_open</b>()</p> - -<p style="margin-left:20%;">The same as -<b>archive_read_open2</b>(), except that the skip callback -is assumed to be NULL.</p> - -<p valign="top"><b>archive_read_open2</b>()</p> - -<p style="margin-left:20%;">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 -<b>archive_read_open_filename</b>(), -<b>archive_read_open_FILE</b>(), -<b>archive_read_open_fd</b>(), or -<b>archive_read_open_memory</b>() instead. The library -invokes the client-provided functions to obtain raw bytes -from the archive.</p> - -<p valign="top"><b>archive_read_open_FILE</b>()</p> - -<p style="margin-left:20%;">Like -<b>archive_read_open</b>(), except that it accepts a <i>FILE -*</i> pointer. This function should not be used with tape -drives or other devices that require strict I/O -blocking.</p> - -<p valign="top"><b>archive_read_open_fd</b>()</p> - -<p style="margin-left:20%;">Like -<b>archive_read_open</b>(), 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.</p> - -<p valign="top"><b>archive_read_open_file</b>()</p> - -<p style="margin-left:20%;">This is a deprecated synonym -for <b>archive_read_open_filename</b>().</p> - -<p valign="top"><b>archive_read_open_filename</b>()</p> - -<p style="margin-left:20%;">Like -<b>archive_read_open</b>(), 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.</p> - -<p valign="top"><b>archive_read_open_memory</b>()</p> - -<p style="margin-left:20%;">Like -<b>archive_read_open</b>(), except that it accepts a pointer -and size of a block of memory containing the archive -data.</p> - -<p valign="top"><b>archive_read_next_header</b>()</p> - -<p style="margin-left:20%;">Read the header for the next -entry and return a pointer to a struct archive_entry. This -is a convenience wrapper around -<b>archive_read_next_header2</b>() that reuses an internal -struct archive_entry object for each request.</p> - -<p valign="top"><b>archive_read_next_header2</b>()</p> - -<p style="margin-left:20%;">Read the header for the next -entry and populate the provided struct archive_entry.</p> - -<p valign="top"><b>archive_read_data</b>()</p> - -<p style="margin-left:20%;">Read data associated with the -header just read. Internally, this is a convenience function -that calls <b>archive_read_data_block</b>() and fills any -gaps with nulls so that callers see a single continuous -stream of data.</p> - -<p valign="top"><b>archive_read_data_block</b>()</p> - -<p style="margin-left:20%;">Return the next available block -of data for this entry. Unlike <b>archive_read_data</b>(), -the <b>archive_read_data_block</b>() 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.</p> - -<p valign="top"><b>archive_read_data_skip</b>()</p> - -<p style="margin-left:20%;">A convenience function that -repeatedly calls <b>archive_read_data_block</b>() to skip -all of the data for this archive entry.</p> - -<p valign="top"><b>archive_read_data_into_buffer</b>()</p> - -<p style="margin-left:20%;">This function is deprecated and -will be removed. Use <b>archive_read_data</b>() instead.</p> - -<p valign="top"><b>archive_read_data_into_fd</b>()</p> - -<p style="margin-left:20%;">A convenience function that -repeatedly calls <b>archive_read_data_block</b>() to copy -the entire entry to the provided file descriptor.</p> - -<p valign="top"><b>archive_read_extract</b>(), -<b>archive_read_extract_set_skip_file</b>()</p> - -<p style="margin-left:20%;">A convenience function that -wraps the corresponding archive_write_disk(3) interfaces. -The first call to <b>archive_read_extract</b>() 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 <i>flags</i> argument is passed -unmodified to archive_write_disk_set_options(3).</p> - -<p valign="top"><b>archive_read_extract2</b>()</p> - -<p style="margin-left:20%;">This is another version of -<b>archive_read_extract</b>() that allows you to provide -your own restore object. In particular, this allows you to -override the standard lookup functions using -archive_write_disk_set_group_lookup(3), and -archive_write_disk_set_user_lookup(3). Note that -<b>archive_read_extract2</b>() does not accept a -<i>flags</i> argument; you should use -<b>archive_write_disk_set_options</b>() to set the restore -options yourself.</p> - - -<p valign="top"><b>archive_read_extract_set_progress_callback</b>()</p> - -<p style="margin-left:20%;">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.</p> - -<p valign="top"><b>archive_read_close</b>()</p> - -<p style="margin-left:20%;">Complete the archive and invoke -the close callback.</p> - -<p valign="top"><b>archive_read_finish</b>()</p> - -<p style="margin-left:20%;">Invokes -<b>archive_read_close</b>() if it was not invoked manually, -then release all resources. Note: In libarchive 1.x, this -function was declared to return <i>void</i>, which made it -impossible to detect certain errors when -<b>archive_read_close</b>() was invoked implicitly from this -function. The declaration is corrected beginning with -libarchive 2.0.</p> - -<p style="margin-left:8%; margin-top: 1em">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 appropriate decompression. It also -automatically detects the archive format.</p> - -<p style="margin-left:8%; margin-top: 1em">A complete -description of the struct archive and struct archive_entry -objects can be found in the overview manual page for -libarchive(3).</p> - -<p style="margin-top: 1em" valign="top"><b>CLIENT -CALLBACKS</b></p> - -<p style="margin-left:8%;">The callback functions must -match the following prototypes:</p> - -<p style="margin-left:17%; margin-top: 1em"><i>typedef -ssize_t</i></p> - - -<p valign="top"><b>archive_read_callback</b>(<i>struct archive *</i>, -<i>void *client_data</i>, -<i>const void **buffer</i>)</p> - -<p style="margin-left:17%; margin-top: 1em"><i>typedef -int</i></p> - - -<p valign="top"><b>archive_skip_callback</b>(<i>struct archive *</i>, -<i>void *client_data</i>, -<i>size_t request</i>)</p> - -<p style="margin-left:17%; margin-top: 1em"><i>typedef -int</i> <b>archive_open_callback</b>(<i>struct archive -*</i>, <i>void *client_data</i>)</p> - -<p style="margin-left:17%; margin-top: 1em"><i>typedef -int</i> <b>archive_close_callback</b>(<i>struct archive -*</i>, <i>void *client_data</i>)</p> - -<p style="margin-left:8%; margin-top: 1em">The open -callback is invoked by <b>archive_open</b>(). It should -return <b>ARCHIVE_OK</b> if the underlying file or data -source is successfully opened. If the open fails, it should -call <b>archive_set_error</b>() to register an error code -and message and return <b>ARCHIVE_FATAL</b>.</p> - -<p style="margin-left:8%; margin-top: 1em">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 <b>archive_set_error</b>() -to register an error code and message and return -1.</p> - -<p style="margin-left:8%; margin-top: 1em">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.</p> - -<p style="margin-left:8%; margin-top: 1em">The close -callback is invoked by archive_close when the archive -processing is complete. The callback should return -<b>ARCHIVE_OK</b> on success. On failure, the callback -should invoke <b>archive_set_error</b>() to register an -error code and message and return <b>ARCHIVE_FATAL.</b></p> - -<p style="margin-top: 1em" valign="top"><b>EXAMPLE</b></p> - -<p style="margin-left:8%;">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.</p> - -<p style="margin-left:17%; margin-top: 1em">void <br> -list_archive(const char *name) <br> -{ <br> -struct mydata *mydata; <br> -struct archive *a; <br> -struct archive_entry *entry;</p> - -<p style="margin-left:17%; margin-top: 1em">mydata = -malloc(sizeof(struct mydata)); <br> -a = archive_read_new(); <br> -mydata->name = name; <br> -archive_read_support_compression_all(a); <br> -archive_read_support_format_all(a); <br> -archive_read_open(a, mydata, myopen, myread, myclose); <br> -while (archive_read_next_header(a, &entry) == -ARCHIVE_OK) { <br> -printf("%s\n",archive_entry_pathname(entry)); <br> -archive_read_data_skip(a); <br> -} <br> -archive_read_finish(a); <br> -free(mydata); <br> -}</p> - -<p style="margin-left:17%; margin-top: 1em">ssize_t <br> -myread(struct archive *a, void *client_data, const void -**buff) <br> -{ <br> -struct mydata *mydata = client_data;</p> - -<p style="margin-left:17%; margin-top: 1em">*buff = -mydata->buff; <br> -return (read(mydata->fd, mydata->buff, 10240)); <br> -}</p> - -<p style="margin-left:17%; margin-top: 1em">int <br> -myopen(struct archive *a, void *client_data) <br> -{ <br> -struct mydata *mydata = client_data;</p> - -<p style="margin-left:17%; margin-top: 1em">mydata->fd = -open(mydata->name, O_RDONLY); <br> -return (mydata->fd >= 0 ? ARCHIVE_OK : ARCHIVE_FATAL); -<br> -}</p> - -<p style="margin-left:17%; margin-top: 1em">int <br> -myclose(struct archive *a, void *client_data) <br> -{ <br> -struct mydata *mydata = client_data;</p> - -<p style="margin-left:17%; margin-top: 1em">if -(mydata->fd > 0) <br> -close(mydata->fd); <br> -return (ARCHIVE_OK); <br> -}</p> - -<p style="margin-top: 1em" valign="top"><b>RETURN -VALUES</b></p> - -<p style="margin-left:8%;">Most functions return zero on -success, non-zero on error. The possible return codes -include: <b>ARCHIVE_OK</b> (the operation succeeded), -<b>ARCHIVE_WARN</b> (the operation succeeded but a -non-critical error was encountered), <b>ARCHIVE_EOF</b> -(end-of-archive was encountered), <b>ARCHIVE_RETRY</b> (the -operation failed but can be retried), and -<b>ARCHIVE_FATAL</b> (there was a fatal error; the archive -should be closed immediately). Detailed error codes and -textual descriptions are available from the -<b>archive_errno</b>() and <b>archive_error_string</b>() -functions.</p> - - -<p style="margin-left:8%; margin-top: 1em"><b>archive_read_new</b>() -returns a pointer to a freshly allocated struct archive -object. It returns NULL on error.</p> - - -<p style="margin-left:8%; margin-top: 1em"><b>archive_read_data</b>() -returns a count of bytes actually read or zero at the end of -the entry. On error, a value of <b>ARCHIVE_FATAL</b>, -<b>ARCHIVE_WARN</b>, or <b>ARCHIVE_RETRY</b> is returned and -an error code and textual description can be retrieved from -the <b>archive_errno</b>() and <b>archive_error_string</b>() -functions.</p> - -<p style="margin-left:8%; margin-top: 1em">The library -expects the client callbacks to behave similarly. If there -is an error, you can use <b>archive_set_error</b>() 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 <b>ARCHIVE_FATAL</b> to be -returned.)</p> - -<p style="margin-top: 1em" valign="top"><b>SEE ALSO</b></p> - -<p style="margin-left:8%;">tar(1), archive(3), -archive_util(3), tar(5)</p> - -<p style="margin-top: 1em" valign="top"><b>HISTORY</b></p> - -<p style="margin-left:8%;">The <b>libarchive</b> library -first appeared in FreeBSD 5.3.</p> - -<p style="margin-top: 1em" valign="top"><b>AUTHORS</b></p> - -<p style="margin-left:8%;">The <b>libarchive</b> library -was written by Tim Kientzle -⟨kientzle@acm.org⟩.</p> - -<p style="margin-top: 1em" valign="top"><b>BUGS</b></p> - -<p style="margin-left:8%;">Many traditional archiver -programs treat empty files as valid empty archives. 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.</p> - - -<p style="margin-left:8%; margin-top: 1em">FreeBSD 8.0 -April 13, 2009 FreeBSD 8.0</p> -<hr> -</body> -</html> diff --git a/libarchive/libarchive-2.8.0/doc/html/archive_read_disk.3.html b/libarchive/libarchive-2.8.0/doc/html/archive_read_disk.3.html deleted file mode 100644 index 2257ffe..0000000 --- a/libarchive/libarchive-2.8.0/doc/html/archive_read_disk.3.html +++ /dev/null @@ -1,341 +0,0 @@ -<!-- Creator : groff version 1.19.2 --> -<!-- CreationDate: Thu Feb 4 20:36:31 2010 --> -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" -"http://www.w3.org/TR/html4/loose.dtd"> -<html> -<head> -<meta name="generator" content="groff -Thtml, see www.gnu.org"> -<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> -<meta name="Content-Style" content="text/css"> -<style type="text/css"> - p { margin-top: 0; margin-bottom: 0; } - pre { margin-top: 0; margin-bottom: 0; } - table { margin-top: 0; margin-bottom: 0; } -</style> -<title></title> -</head> -<body> - -<hr> - - -<p valign="top">archive_read_disk(3) FreeBSD Library -Functions Manual archive_read_disk(3)</p> - -<p style="margin-top: 1em" valign="top"><b>NAME</b></p> - -<p style="margin-left:8%;"><b>archive_read_disk_new</b>, -<b>archive_read_disk_set_symlink_logical</b>, -<b>archive_read_disk_set_symlink_physical</b>, -<b>archive_read_disk_set_symlink_hybrid</b>, -<b>archive_read_disk_entry_from_file</b>, -<b>archive_read_disk_gname</b>, -<b>archive_read_disk_uname</b>, -<b>archive_read_disk_set_uname_lookup</b>, -<b>archive_read_disk_set_gname_lookup</b>, -<b>archive_read_disk_set_standard_lookup</b>, -<b>archive_read_close</b>, <b>archive_read_finish</b> -— functions for reading objects from disk</p> - - -<p style="margin-top: 1em" valign="top"><b>SYNOPSIS</b></p> - -<p style="margin-left:8%;"><b>#include -<archive.h></b></p> - -<p style="margin-left:8%; margin-top: 1em"><i>struct -archive *</i></p> - - -<p style="margin-left:14%;"><b>archive_read_disk_new</b>(<i>void</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_disk_set_symlink_logical</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_disk_set_symlink_physical</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_disk_set_symlink_hybrid</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_disk_gname</b>(<i>struct archive *</i>, -<i>gid_t</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_disk_uname</b>(<i>struct archive *</i>, -<i>uid_t</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p valign="top"><b>archive_read_disk_set_gname_lookup</b>(<i>struct archive *</i>, -<i>void *</i>, -<i>const char *(*lookup)(void *, gid_t)</i>, -<i>void (*cleanup)(void *)</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p valign="top"><b>archive_read_disk_set_uname_lookup</b>(<i>struct archive *</i>, -<i>void *</i>, -<i>const char *(*lookup)(void *, uid_t)</i>, -<i>void (*cleanup)(void *)</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_disk_set_standard_lookup</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p valign="top"><b>archive_read_disk_entry_from_file</b>(<i>struct archive *</i>, -<i>struct archive_entry *</i>, <i>int fd</i>, -<i>const struct stat *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_close</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_read_finish</b>(<i>struct archive *</i>);</p> - - -<p style="margin-top: 1em" valign="top"><b>DESCRIPTION</b></p> - -<p style="margin-left:8%;">These functions provide an API -for reading information about objects on disk. In -particular, they provide an interface for populating struct -archive_entry objects.</p> - - -<p style="margin-top: 1em" valign="top"><b>archive_read_disk_new</b>()</p> - -<p style="margin-left:20%;">Allocates and initializes a -struct archive object suitable for reading object -information from disk.</p> - - -<p style="margin-top: 1em" valign="top"><b>archive_read_disk_set_symlink_logical</b>(), -<b>archive_read_disk_set_symlink_physical</b>(), -<b>archive_read_disk_set_symlink_hybrid</b>()</p> - -<p style="margin-left:20%;">This sets the mode used for -handling symbolic links. The -‘‘logical’’ mode follows all -symbolic links. The ‘‘physical’’ -mode does not follow any symbolic links. The -‘‘hybrid’’ mode currently behaves -identically to the ‘‘logical’’ -mode.</p> - - -<p style="margin-top: 1em" valign="top"><b>archive_read_disk_gname</b>(), -<b>archive_read_disk_uname</b>()</p> - -<p style="margin-left:20%;">Returns a user or group name -given a gid or uid value. By default, these always return a -NULL string.</p> - - -<p style="margin-top: 1em" valign="top"><b>archive_read_disk_set_gname_lookup</b>(), -<b>archive_read_disk_set_uname_lookup</b>()</p> - -<p style="margin-left:20%;">These allow you to override the -functions used for user and group name lookups. 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 or when -new lookup functions are registered.</p> - - -<p style="margin-top: 1em" valign="top"><b>archive_read_disk_set_standard_lookup</b>()</p> - -<p style="margin-left:20%;">This convenience function -installs a standard set of user and group name lookup -functions. These functions use getpwid(3) and getgrid(3) to -convert ids to names, defaulting to NULL if the names cannot -be looked up. These functions also implement a simple memory -cache to reduce the number of calls to getpwid(3) and -getgrid(3).</p> - - -<p style="margin-top: 1em" valign="top"><b>archive_read_disk_entry_from_file</b>()</p> - -<p style="margin-left:20%;">Populates a struct -archive_entry object with information about a particular -file. The archive_entry object must have already been -created with archive_entry_new(3) and at least one of the -source path or path fields must already be set. (If both are -set, the source path will be used.)</p> - -<p style="margin-left:20%; margin-top: 1em">Information is -read from disk using the path name from the struct -archive_entry object. If a file descriptor is provided, some -information will be obtained using that file descriptor, on -platforms that support the appropriate system calls.</p> - -<p style="margin-left:20%; margin-top: 1em">If a pointer to -a struct stat is provided, information from that structure -will be used instead of reading from the disk where -appropriate. This can provide performance benefits in -scenarios where struct stat information has already been -read from the disk as a side effect of some other operation. -(For example, directory traversal libraries often provide -this information.)</p> - -<p style="margin-left:20%; margin-top: 1em">Where -necessary, user and group ids are converted to user and -group names using the currently registered lookup functions -above. This affects the file ownership fields and ACL values -in the struct archive_entry object.</p> - - -<p style="margin-top: 1em" valign="top"><b>archive_read_close</b>()</p> - -<p style="margin-left:20%;">This currently does -nothing.</p> - - -<p style="margin-top: 1em" valign="top"><b>archive_write_finish</b>()</p> - -<p style="margin-left:20%;">Invokes -<b>archive_write_close</b>() if it was not invoked manually, -then releases all resources.</p> - -<p style="margin-left:8%;">More information about the -<i>struct archive</i> object and the overall design of the -library can be found in the libarchive(3) overview.</p> - -<p style="margin-top: 1em" valign="top"><b>EXAMPLE</b></p> - -<p style="margin-left:8%;">The following illustrates basic -usage of the library by showing how to use it to copy an -item on disk into an archive.</p> - -<p style="margin-left:17%; margin-top: 1em">void <br> -file_to_archive(struct archive *a, const char *name) <br> -{ <br> -char buff[8192]; <br> -size_t bytes_read; <br> -struct archive *ard; <br> -struct archive_entry *entry; <br> -int fd;</p> - -<p style="margin-left:17%; margin-top: 1em">ard = -archive_read_disk_new(); <br> -archive_read_disk_set_standard_lookup(ard); <br> -entry = archive_entry_new(); <br> -fd = open(name, O_RDONLY); <br> -if (fd < 0) <br> -return; <br> -archive_entry_copy_sourcepath(entry, name); <br> -archive_read_disk_entry_from_file(ard, entry, fd, NULL); -<br> -archive_write_header(a, entry); <br> -while ((bytes_read = read(fd, buff, sizeof(buff))) > 0) -<br> -archive_write_data(a, buff, bytes_read); <br> -archive_write_finish_entry(a); <br> -archive_read_finish(ard); <br> -archive_entry_free(entry); <br> -}</p> - -<p style="margin-top: 1em" valign="top"><b>RETURN -VALUES</b></p> - -<p style="margin-left:8%;">Most functions return -<b>ARCHIVE_OK</b> (zero) on success, or one of several -negative error codes for errors. Specific error codes -include: <b>ARCHIVE_RETRY</b> for operations that might -succeed if retried, <b>ARCHIVE_WARN</b> for unusual -conditions that do not prevent further operations, and -<b>ARCHIVE_FATAL</b> for serious errors that make remaining -operations impossible. The archive_errno(3) and -archive_error_string(3) functions can be used to retrieve an -appropriate error code and a textual error message. (See -archive_util(3) for details.)</p> - - -<p style="margin-left:8%; margin-top: 1em"><b>archive_read_disk_new</b>() -returns a pointer to a newly-allocated struct archive object -or NULL if the allocation failed for any reason.</p> - - -<p style="margin-left:8%; margin-top: 1em"><b>archive_read_disk_gname</b>() -and <b>archive_read_disk_uname</b>() return const char * -pointers to the textual name or NULL if the lookup failed -for any reason. The returned pointer points to internal -storage that may be reused on the next call to either of -these functions; callers should copy the string if they need -to continue accessing it.</p> - -<p style="margin-top: 1em" valign="top"><b>SEE ALSO</b></p> - -<p style="margin-left:8%;">archive_read(3), -archive_write(3), archive_write_disk(3), tar(1), -libarchive(3)</p> - -<p style="margin-top: 1em" valign="top"><b>HISTORY</b></p> - -<p style="margin-left:8%;">The <b>libarchive</b> library -first appeared in FreeBSD 5.3. The -<b>archive_read_disk</b> interface was added to -<b>libarchive 2.6</b> and first appeared in -FreeBSD 8.0.</p> - -<p style="margin-top: 1em" valign="top"><b>AUTHORS</b></p> - -<p style="margin-left:8%;">The <b>libarchive</b> library -was written by Tim Kientzle -⟨kientzle@freebsd.org⟩.</p> - -<p style="margin-top: 1em" valign="top"><b>BUGS</b></p> - -<p style="margin-left:8%;">The -‘‘standard’’ user name and group -name lookup functions are not the defaults because -getgrid(3) and getpwid(3) are sometimes too large for -particular applications. The current design allows the -application author to use a more compact implementation when -appropriate.</p> - -<p style="margin-left:8%; margin-top: 1em">The full list of -metadata read from disk by -<b>archive_read_disk_entry_from_file</b>() is necessarily -system-dependent.</p> - -<p style="margin-left:8%; margin-top: 1em">The -<b>archive_read_disk_entry_from_file</b>() function reads as -much information as it can from disk. Some method should be -provided to limit this so that clients who do not need ACLs, -for instance, can avoid the extra work needed to look up -such information.</p> - -<p style="margin-left:8%; margin-top: 1em">This API should -provide a set of methods for walking a directory tree. That -would make it a direct parallel of the archive_read(3) API. -When such methods are implemented, the -‘‘hybrid’’ symbolic link mode will -make sense.</p> - - -<p style="margin-left:8%; margin-top: 1em">FreeBSD 8.0 -March 10, 2009 FreeBSD 8.0</p> -<hr> -</body> -</html> diff --git a/libarchive/libarchive-2.8.0/doc/html/archive_util.3.html b/libarchive/libarchive-2.8.0/doc/html/archive_util.3.html deleted file mode 100644 index c4dd32c..0000000 --- a/libarchive/libarchive-2.8.0/doc/html/archive_util.3.html +++ /dev/null @@ -1,210 +0,0 @@ -<!-- Creator : groff version 1.19.2 --> -<!-- CreationDate: Thu Feb 4 20:36:32 2010 --> -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" -"http://www.w3.org/TR/html4/loose.dtd"> -<html> -<head> -<meta name="generator" content="groff -Thtml, see www.gnu.org"> -<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> -<meta name="Content-Style" content="text/css"> -<style type="text/css"> - p { margin-top: 0; margin-bottom: 0; } - pre { margin-top: 0; margin-bottom: 0; } - table { margin-top: 0; margin-bottom: 0; } -</style> -<title></title> -</head> -<body> - -<hr> - - -<p valign="top">archive_util(3) FreeBSD Library Functions -Manual archive_util(3)</p> - -<p style="margin-top: 1em" valign="top"><b>NAME</b></p> - -<p style="margin-left:8%;"><b>archive_clear_error</b>, -<b>archive_compression</b>, <b>archive_compression_name</b>, -<b>archive_copy_error</b>, <b>archive_errno</b>, -<b>archive_error_string</b>, <b>archive_file_count</b>, -<b>archive_format</b>, <b>archive_format_name</b>, -<b>archive_set_error</b> — libarchive utility -functions</p> - - -<p style="margin-top: 1em" valign="top"><b>SYNOPSIS</b></p> - -<p style="margin-left:8%;"><b>#include -<archive.h></b></p> - -<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> - - -<p style="margin-left:14%;"><b>archive_clear_error</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_compression</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>const char -*</i></p> - - -<p style="margin-left:14%;"><b>archive_compression_name</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> - - -<p style="margin-left:14%;"><b>archive_copy_error</b>(<i>struct archive *</i>, -<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_errno</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>const char -*</i></p> - - -<p style="margin-left:14%;"><b>archive_error_string</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_file_count</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_format</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>const char -*</i></p> - - -<p style="margin-left:14%;"><b>archive_format_name</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> - - -<p valign="top"><b>archive_set_error</b>(<i>struct archive *</i>, -<i>int error_code</i>, -<i>const char *fmt</i>, <i>...</i>);</p> - - -<p style="margin-top: 1em" valign="top"><b>DESCRIPTION</b></p> - -<p style="margin-left:8%;">These functions provide access -to various information about the struct archive object used -in the libarchive(3) library.</p> - -<p valign="top"><b>archive_clear_error</b>()</p> - -<p style="margin-left:20%;">Clears any error information -left over from a previous call. Not generally used in client -code.</p> - -<p valign="top"><b>archive_compression</b>()</p> - -<p style="margin-left:20%;">Returns a numeric code -indicating the current compression. This value is set by -<b>archive_read_open</b>().</p> - -<p valign="top"><b>archive_compression_name</b>()</p> - -<p style="margin-left:20%;">Returns a text description of -the current compression suitable for display.</p> - -<p valign="top"><b>archive_copy_error</b>()</p> - -<p style="margin-left:20%;">Copies error information from -one archive to another.</p> - -<p valign="top"><b>archive_errno</b>()</p> - -<p style="margin-left:20%;">Returns a numeric error code -(see errno(2)) indicating the reason for the most recent -error return.</p> - -<p valign="top"><b>archive_error_string</b>()</p> - -<p style="margin-left:20%;">Returns a textual error message -suitable for display. The error message here is usually more -specific than that obtained from passing the result of -<b>archive_errno</b>() to strerror(3).</p> - -<p valign="top"><b>archive_file_count</b>()</p> - -<p style="margin-left:20%;">Returns a count of the number -of files processed by this archive object. The count is -incremented by calls to archive_write_header or -archive_read_next_header.</p> - -<p valign="top"><b>archive_format</b>()</p> - -<p style="margin-left:20%;">Returns a numeric code -indicating the format of the current archive entry. This -value is set by a successful call to -<b>archive_read_next_header</b>(). 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.</p> - -<p valign="top"><b>archive_format_name</b>()</p> - -<p style="margin-left:20%;">A textual description of the -format of the current entry.</p> - -<p valign="top"><b>archive_set_error</b>()</p> - -<p style="margin-left:20%;">Sets the numeric error code and -error description that will be returned by -<b>archive_errno</b>() and <b>archive_error_string</b>(). -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.</p> - -<p style="margin-top: 1em" valign="top"><b>SEE ALSO</b></p> - -<p style="margin-left:8%;">archive_read(3), -archive_write(3), libarchive(3), printf(3)</p> - -<p style="margin-top: 1em" valign="top"><b>HISTORY</b></p> - -<p style="margin-left:8%;">The <b>libarchive</b> library -first appeared in FreeBSD 5.3.</p> - -<p style="margin-top: 1em" valign="top"><b>AUTHORS</b></p> - -<p style="margin-left:8%;">The <b>libarchive</b> library -was written by Tim Kientzle -⟨kientzle@acm.org⟩.</p> - - -<p style="margin-left:8%; margin-top: 1em">FreeBSD 8.0 -January 8, 2005 FreeBSD 8.0</p> -<hr> -</body> -</html> diff --git a/libarchive/libarchive-2.8.0/doc/html/archive_write.3.html b/libarchive/libarchive-2.8.0/doc/html/archive_write.3.html deleted file mode 100644 index e72c5d5..0000000 --- a/libarchive/libarchive-2.8.0/doc/html/archive_write.3.html +++ /dev/null @@ -1,845 +0,0 @@ -<!-- Creator : groff version 1.19.2 --> -<!-- CreationDate: Thu Feb 4 20:36:33 2010 --> -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" -"http://www.w3.org/TR/html4/loose.dtd"> -<html> -<head> -<meta name="generator" content="groff -Thtml, see www.gnu.org"> -<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> -<meta name="Content-Style" content="text/css"> -<style type="text/css"> - p { margin-top: 0; margin-bottom: 0; } - pre { margin-top: 0; margin-bottom: 0; } - table { margin-top: 0; margin-bottom: 0; } -</style> -<title></title> -</head> -<body> - -<hr> - - -<p valign="top">archive_write(3) FreeBSD Library Functions -Manual archive_write(3)</p> - -<p style="margin-top: 1em" valign="top"><b>NAME</b></p> - -<p style="margin-left:8%;"><b>archive_write_new</b>, -<b>archive_write_set_format_cpio</b>, -<b>archive_write_set_format_pax</b>, -<b>archive_write_set_format_pax_restricted</b>, -<b>archive_write_set_format_shar</b>, -<b>archive_write_set_format_shar_binary</b>, -<b>archive_write_set_format_ustar</b>, -<b>archive_write_get_bytes_per_block</b>, -<b>archive_write_set_bytes_per_block</b>, -<b>archive_write_set_bytes_in_last_block</b>, -<b>archive_write_set_compression_bzip2</b>, -<b>archive_write_set_compression_compress</b>, -<b>archive_write_set_compression_gzip</b>, -<b>archive_write_set_compression_none</b>, -<b>archive_write_set_compression_program</b>, -<b>archive_write_set_compressor_options</b>, -<b>archive_write_set_format_options</b>, -<b>archive_write_set_options</b>, <b>archive_write_open</b>, -<b>archive_write_open_fd</b>, -<b>archive_write_open_FILE</b>, -<b>archive_write_open_filename</b>, -<b>archive_write_open_memory</b>, -<b>archive_write_header</b>, <b>archive_write_data</b>, -<b>archive_write_finish_entry</b>, -<b>archive_write_close</b>, <b>archive_write_finish</b> -— functions for creating archives</p> - - -<p style="margin-top: 1em" valign="top"><b>SYNOPSIS</b></p> - -<p style="margin-left:8%;"><b>#include -<archive.h></b></p> - -<p style="margin-left:8%; margin-top: 1em"><i>struct -archive *</i></p> - - -<p style="margin-left:14%;"><b>archive_write_new</b>(<i>void</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_write_get_bytes_per_block</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_write_set_bytes_per_block</b>(<i>struct archive *</i>, -<i>int bytes_per_block</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_write_set_bytes_in_last_block</b>(<i>struct archive *</i>, -<i>int</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_write_set_compression_bzip2</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_write_set_compression_compress</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_write_set_compression_gzip</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_write_set_compression_none</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_write_set_compression_program</b>(<i>struct archive *</i>, -<i>const char * cmd</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_write_set_format_cpio</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_write_set_format_pax</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_write_set_format_pax_restricted</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_write_set_format_shar</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_write_set_format_shar_binary</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_write_set_format_ustar</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_write_set_format_options</b>(<i>struct archive *</i>, -<i>const char *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_write_set_compressor_options</b>(<i>struct archive *</i>, -<i>const char *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_write_set_options</b>(<i>struct archive *</i>, -<i>const char *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p valign="top"><b>archive_write_open</b>(<i>struct archive *</i>, -<i>void *client_data</i>, -<i>archive_open_callback *</i>, -<i>archive_write_callback *</i>, -<i>archive_close_callback *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_write_open_fd</b>(<i>struct archive *</i>, -<i>int fd</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_write_open_FILE</b>(<i>struct archive *</i>, -<i>FILE *file</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_write_open_filename</b>(<i>struct archive *</i>, -<i>const char *filename</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p valign="top"><b>archive_write_open_memory</b>(<i>struct archive *</i>, -<i>void *buffer</i>, <i>size_t bufferSize</i>, -<i>size_t *outUsed</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_write_header</b>(<i>struct archive *</i>, -<i>struct archive_entry *</i>);</p> - - -<p style="margin-left:8%; margin-top: 1em"><i>ssize_t</i></p> - - -<p style="margin-left:14%;"><b>archive_write_data</b>(<i>struct archive *</i>, -<i>const void *</i>, <i>size_t</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_write_finish_entry</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_write_close</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_write_finish</b>(<i>struct archive *</i>);</p> - - -<p style="margin-top: 1em" valign="top"><b>DESCRIPTION</b></p> - -<p style="margin-left:8%;">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:</p> - - -<p style="margin-top: 1em" valign="top"><b>archive_write_new</b>()</p> - -<p style="margin-left:20%;">Allocates and initializes a -struct archive object suitable for writing a tar -archive.</p> - - -<p style="margin-top: 1em" valign="top"><b>archive_write_set_bytes_per_block</b>()</p> - -<p style="margin-left:20%;">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.</p> - - -<p style="margin-top: 1em" valign="top"><b>archive_write_get_bytes_per_block</b>()</p> - -<p style="margin-left:20%;">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.</p> - - -<p style="margin-top: 1em" valign="top"><b>archive_write_set_bytes_in_last_block</b>()</p> - -<p style="margin-left:20%;">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 <b>archive_write_open_filename</b>() will set -this based on the file type). Unlike the other -‘‘set’’ functions, this function can -be called after the archive is opened.</p> - - -<p style="margin-top: 1em" valign="top"><b>archive_write_get_bytes_in_last_block</b>()</p> - -<p style="margin-left:20%;">Retrieve the currently-set -value for last block size. A value of -1 here indicates that -the library should use default values.</p> - - -<p style="margin-top: 1em" valign="top"><b>archive_write_set_format_cpio</b>(), -<b>archive_write_set_format_pax</b>(), -<b>archive_write_set_format_pax_restricted</b>(), -<b>archive_write_set_format_shar</b>(), -<b>archive_write_set_format_shar_binary</b>(), -<b>archive_write_set_format_ustar</b>()</p> - -<p style="margin-left:20%;">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.</p> - - -<p style="margin-top: 1em" valign="top"><b>archive_write_set_compression_bzip2</b>(), -<b>archive_write_set_compression_compress</b>(), -<b>archive_write_set_compression_gzip</b>(), -<b>archive_write_set_compression_none</b>()</p> - -<p style="margin-left:20%;">The resulting archive will be -compressed as specified. Note that the compressed output is -always properly blocked.</p> - - -<p style="margin-top: 1em" valign="top"><b>archive_write_set_compression_program</b>()</p> - -<p style="margin-left:20%;">The archive will be fed into -the specified compression program. The output of that -program is blocked and written to the client write -callbacks.</p> - - -<p style="margin-top: 1em" valign="top"><b>archive_write_set_compressor_options</b>(), -<b>archive_write_set_format_options</b>(), -<b>archive_write_set_options</b>()</p> - -<p style="margin-left:20%;">Specifies options that will be -passed to the currently-enabled compressor and/or format -writer. The argument is a comma-separated list of individual -options. Individual options have one of the following -forms:</p> - -<p valign="top"><i>option=value</i></p> - -<p style="margin-left:32%;">The option/value pair will be -provided to every module. Modules that do not accept an -option with this name will ignore it.</p> - -<p valign="top"><i>option</i></p> - -<p style="margin-left:32%; margin-top: 1em">The option will -be provided to every module with a value of -‘‘1’’.</p> - -<p valign="top"><i>!option</i></p> - -<p style="margin-left:32%;">The option will be provided to -every module with a NULL value.</p> - -<p valign="top"><i>module:option=value</i>, -<i>module:option</i>, <i>module:!option</i></p> - -<p style="margin-left:32%;">As above, but the corresponding -option and value will be provided only to modules whose name -matches <i>module</i>.</p> - -<p style="margin-left:20%;">The return value will be -<b>ARCHIVE_OK</b> if any module accepts the option, or -<b>ARCHIVE_WARN</b> if no module accepted the option, or -<b>ARCHIVE_FATAL</b> if there was a fatal error while -attempting to process the option.</p> - -<p style="margin-left:20%; margin-top: 1em">The currently -supported options are:</p> - -<p valign="top">Compressor gzip <b><br> -compression-level</b></p> - -<p style="margin-left:45%;">The value is interpreted as a -decimal integer specifying the gzip compression level.</p> - -<p valign="top">Compressor xz <b><br> -compression-level</b></p> - -<p style="margin-left:45%;">The value is interpreted as a -decimal integer specifying the compression level.</p> - -<p valign="top">Format mtree <b><br> -cksum</b>, <b>device</b>, <b>flags</b>, <b>gid</b>, -<b>gname</b>, <b>indent</b>, <b>link</b>, <b>md5</b>, -<b>mode</b>, <b>nlink</b>, <b>rmd160</b>, <b>sha1</b>, -<b>sha256</b>, <b>sha384</b>, <b>sha512</b>, <b>size</b>, -<b>time</b>, <b>uid</b>, <b>uname</b></p> - -<p style="margin-left:45%;">Enable a particular keyword in -the mtree output. Prefix with an exclamation mark to disable -the corresponding keyword. The default is equivalent to -‘‘device, flags, gid, gname, link, mode, nlink, -size, time, type, uid, uname’’.</p> - -<p valign="top"><b>all</b></p> - -<p style="margin-left:45%; margin-top: 1em">Enables all of -the above keywords.</p> - -<p valign="top"><b>use-set</b></p> - -<p style="margin-left:45%;">Enables generation of -<b>/set</b> lines that specify default values for the -following files and/or directories.</p> - -<p valign="top"><b>indent</b></p> - -<p style="margin-left:45%; margin-top: 1em">XXX needs -explanation XXX</p> - - -<p style="margin-top: 1em" valign="top"><b>archive_write_open</b>()</p> - -<p style="margin-left:20%;">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.</p> - - -<p style="margin-top: 1em" valign="top"><b>archive_write_open_fd</b>()</p> - -<p style="margin-left:20%;">A convenience form of -<b>archive_write_open</b>() that accepts a file descriptor. -The <b>archive_write_open_fd</b>() function is safe for use -with tape drives or other block-oriented devices.</p> - - -<p style="margin-top: 1em" valign="top"><b>archive_write_open_FILE</b>()</p> - -<p style="margin-left:20%;">A convenience form of -<b>archive_write_open</b>() that accepts a <i>FILE *</i> -pointer. Note that <b>archive_write_open_FILE</b>() is not -safe for writing to tape drives or other devices that -require correct blocking.</p> - - -<p style="margin-top: 1em" valign="top"><b>archive_write_open_file</b>()</p> - -<p style="margin-left:20%;">A deprecated synonym for -<b>archive_write_open_filename</b>().</p> - - -<p style="margin-top: 1em" valign="top"><b>archive_write_open_filename</b>()</p> - -<p style="margin-left:20%;">A convenience form of -<b>archive_write_open</b>() 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 -<b>archive_write_set_bytes_in_last_block</b>(), then -<b>archive_write_open_filename</b>() 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 -<b>archive_write_set_bytes_in_last_block</b>() before -calling <b>archive_write_open</b>(). The -<b>archive_write_open_filename</b>() function is safe for -use with tape drives or other block-oriented devices.</p> - - -<p style="margin-top: 1em" valign="top"><b>archive_write_open_memory</b>()</p> - -<p style="margin-left:20%;">A convenience form of -<b>archive_write_open</b>() that accepts a pointer to a -block of memory that will receive the archive. The final -<i>size_t *</i> 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.</p> - - -<p style="margin-top: 1em" valign="top"><b>archive_write_header</b>()</p> - -<p style="margin-left:20%;">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.</p> - - -<p style="margin-top: 1em" valign="top"><b>archive_write_data</b>()</p> - -<p style="margin-left:20%;">Write data corresponding to the -header just written. Returns number of bytes written or -1 -on error.</p> - - -<p style="margin-top: 1em" valign="top"><b>archive_write_finish_entry</b>()</p> - -<p style="margin-left:20%;">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 -<b>archive_write_next_header</b>() and -<b>archive_write_close</b>() as needed.</p> - - -<p style="margin-top: 1em" valign="top"><b>archive_write_close</b>()</p> - -<p style="margin-left:20%;">Complete the archive and invoke -the close callback.</p> - - -<p style="margin-top: 1em" valign="top"><b>archive_write_finish</b>()</p> - -<p style="margin-left:20%;">Invokes -<b>archive_write_close</b>() if it was not invoked manually, -then releases all resources. Note that this function was -declared to return <i>void</i> in libarchive 1.x, which made -it impossible to detect errors when -<b>archive_write_close</b>() was invoked implicitly from -this function. This is corrected beginning with libarchive -2.0.</p> - -<p style="margin-left:8%;">More information about the -<i>struct archive</i> object and the overall design of the -library can be found in the libarchive(3) overview.</p> - - -<p style="margin-top: 1em" valign="top"><b>IMPLEMENTATION</b></p> - -<p style="margin-left:8%;">Compression support is built-in -to libarchive, which uses zlib and bzlib to handle gzip and -bzip2 compression, respectively.</p> - -<p style="margin-top: 1em" valign="top"><b>CLIENT -CALLBACKS</b></p> - -<p style="margin-left:8%;">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 -<b>archive_write_open</b>():</p> - -<p style="margin-left:17%; margin-top: 1em"><i>typedef -int</i> <b>archive_open_callback</b>(<i>struct archive -*</i>, <i>void *client_data</i>)</p> - -<p style="margin-left:8%; margin-top: 1em">The open -callback is invoked by <b>archive_write_open</b>(). It -should return <b>ARCHIVE_OK</b> if the underlying file or -data source is successfully opened. If the open fails, it -should call <b>archive_set_error</b>() to register an error -code and message and return <b>ARCHIVE_FATAL</b>.</p> - -<p style="margin-left:17%; margin-top: 1em"><i>typedef -ssize_t</i></p> - - -<p valign="top"><b>archive_write_callback</b>(<i>struct archive *</i>, -<i>void *client_data</i>, -<i>const void *buffer</i>, -<i>size_t length</i>)</p> - -<p style="margin-left:8%; margin-top: 1em">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 -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 -<b>archive_set_error</b>() to register an error code and -message and return -1.</p> - -<p style="margin-left:17%; margin-top: 1em"><i>typedef -int</i> <b>archive_close_callback</b>(<i>struct archive -*</i>, <i>void *client_data</i>)</p> - -<p style="margin-left:8%; margin-top: 1em">The close -callback is invoked by archive_close when the archive -processing is complete. The callback should return -<b>ARCHIVE_OK</b> on success. On failure, the callback -should invoke <b>archive_set_error</b>() to register an -error code and message and return <b>ARCHIVE_FATAL.</b></p> - -<p style="margin-top: 1em" valign="top"><b>EXAMPLE</b></p> - -<p style="margin-left:8%;">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.</p> - -<p style="margin-left:17%; margin-top: 1em">#ifdef -__linux__</p> - -<table width="100%" border=0 rules="none" frame="void" - cellspacing="0" cellpadding="0"> -<tr valign="top" align="left"> -<td width="17%"></td> -<td width="12%"> - - -<p valign="top">#define</p></td> -<td width="13%"> - - -<p valign="top">_FILE_OFFSET_BITS 64</p></td> -<td width="58%"> -</td> -</table> - -<p style="margin-left:17%;">#endif <br> -#include <sys/stat.h> <br> -#include <archive.h> <br> -#include <archive_entry.h> <br> -#include <fcntl.h> <br> -#include <stdlib.h> <br> -#include <unistd.h></p> - -<p style="margin-left:17%; margin-top: 1em">struct mydata -{</p> - -<table width="100%" border=0 rules="none" frame="void" - cellspacing="0" cellpadding="0"> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="71%"> - - -<p valign="top">const char *name;</p></td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="71%"> - - -<p valign="top">int fd;</p></td> -</table> - -<p style="margin-left:17%;">};</p> - -<p style="margin-left:17%; margin-top: 1em">int <br> -myopen(struct archive *a, void *client_data) <br> -{ <br> -struct mydata *mydata = client_data;</p> - -<p style="margin-left:17%; margin-top: 1em">mydata->fd = -open(mydata->name, O_WRONLY | O_CREAT, 0644); <br> -if (mydata->fd >= 0) <br> -return (ARCHIVE_OK); <br> -else <br> -return (ARCHIVE_FATAL); <br> -}</p> - -<p style="margin-left:17%; margin-top: 1em">ssize_t <br> -mywrite(struct archive *a, void *client_data, const void -*buff, size_t n) <br> -{ <br> -struct mydata *mydata = client_data;</p> - -<p style="margin-left:17%; margin-top: 1em">return -(write(mydata->fd, buff, n)); <br> -}</p> - -<p style="margin-left:17%; margin-top: 1em">int <br> -myclose(struct archive *a, void *client_data) <br> -{ <br> -struct mydata *mydata = client_data;</p> - -<p style="margin-left:17%; margin-top: 1em">if -(mydata->fd > 0) <br> -close(mydata->fd); <br> -return (0); <br> -}</p> - -<p style="margin-left:17%; margin-top: 1em">void <br> -write_archive(const char *outname, const char **filename) -<br> -{ <br> -struct mydata *mydata = malloc(sizeof(struct mydata)); <br> -struct archive *a; <br> -struct archive_entry *entry; <br> -struct stat st; <br> -char buff[8192]; <br> -int len; <br> -int fd;</p> - -<p style="margin-left:17%; margin-top: 1em">a = -archive_write_new(); <br> -mydata->name = outname; <br> -archive_write_set_compression_gzip(a); <br> -archive_write_set_format_ustar(a); <br> -archive_write_open(a, mydata, myopen, mywrite, myclose); -<br> -while (*filename) { <br> -stat(*filename, &st); <br> -entry = archive_entry_new(); <br> -archive_entry_copy_stat(entry, &st); <br> -archive_entry_set_pathname(entry, *filename); <br> -archive_write_header(a, entry); <br> -fd = open(*filename, O_RDONLY); <br> -len = read(fd, buff, sizeof(buff)); <br> -while ( len > 0 ) {</p> - -<table width="100%" border=0 rules="none" frame="void" - cellspacing="0" cellpadding="0"> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="71%"> - - -<p valign="top">archive_write_data(a, buff, len);</p></td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="71%"> - - -<p valign="top">len = read(fd, buff, sizeof(buff));</p></td> -</table> - -<p style="margin-left:17%;">} <br> -archive_entry_free(entry); <br> -filename++; <br> -} <br> -archive_write_finish(a); <br> -}</p> - -<p style="margin-left:17%; margin-top: 1em">int main(int -argc, const char **argv) <br> -{</p> - -<table width="100%" border=0 rules="none" frame="void" - cellspacing="0" cellpadding="0"> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="71%"> - - -<p valign="top">const char *outname;</p></td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="71%"> - - -<p valign="top">argv++;</p></td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="71%"> - - -<p valign="top">outname = argv++;</p></td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="71%"> - - -<p valign="top">write_archive(outname, argv);</p></td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="71%"> - - -<p valign="top">return 0;</p></td> -</table> - -<p style="margin-left:17%;">}</p> - -<p style="margin-top: 1em" valign="top"><b>RETURN -VALUES</b></p> - -<p style="margin-left:8%;">Most functions return -<b>ARCHIVE_OK</b> (zero) on success, or one of several -non-zero error codes for errors. Specific error codes -include: <b>ARCHIVE_RETRY</b> for operations that might -succeed if retried, <b>ARCHIVE_WARN</b> for unusual -conditions that do not prevent further operations, and -<b>ARCHIVE_FATAL</b> for serious errors that make remaining -operations impossible. The <b>archive_errno</b>() and -<b>archive_error_string</b>() functions can be used to -retrieve an appropriate error code and a textual error -message.</p> - - -<p style="margin-left:8%; margin-top: 1em"><b>archive_write_new</b>() -returns a pointer to a newly-allocated struct archive -object.</p> - - -<p style="margin-left:8%; margin-top: 1em"><b>archive_write_data</b>() -returns a count of the number of bytes actually written. On -error, -1 is returned and the <b>archive_errno</b>() and -<b>archive_error_string</b>() 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 -<b>archive_write_header</b>(), <b>archive_write_data</b>(), -<b>archive_write_close</b>(), or -<b>archive_write_finish</b>(). The client callback can call -<b>archive_set_error</b>() to provide values that can then -be retrieved by <b>archive_errno</b>() and -<b>archive_error_string</b>().</p> - -<p style="margin-top: 1em" valign="top"><b>SEE ALSO</b></p> - -<p style="margin-left:8%;">tar(1), libarchive(3), -tar(5)</p> - -<p style="margin-top: 1em" valign="top"><b>HISTORY</b></p> - -<p style="margin-left:8%;">The <b>libarchive</b> library -first appeared in FreeBSD 5.3.</p> - -<p style="margin-top: 1em" valign="top"><b>AUTHORS</b></p> - -<p style="margin-left:8%;">The <b>libarchive</b> library -was written by Tim Kientzle -⟨kientzle@acm.org⟩.</p> - -<p style="margin-top: 1em" valign="top"><b>BUGS</b></p> - -<p style="margin-left:8%;">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.</p> - -<p style="margin-left:8%; margin-top: 1em">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 <b>star</b> 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.</p> - - -<p style="margin-left:8%; margin-top: 1em">FreeBSD 8.0 -May 11, 2008 FreeBSD 8.0</p> -<hr> -</body> -</html> diff --git a/libarchive/libarchive-2.8.0/doc/html/archive_write_disk.3.html b/libarchive/libarchive-2.8.0/doc/html/archive_write_disk.3.html deleted file mode 100644 index 3d7ef63..0000000 --- a/libarchive/libarchive-2.8.0/doc/html/archive_write_disk.3.html +++ /dev/null @@ -1,421 +0,0 @@ -<!-- Creator : groff version 1.19.2 --> -<!-- CreationDate: Thu Feb 4 20:36:34 2010 --> -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" -"http://www.w3.org/TR/html4/loose.dtd"> -<html> -<head> -<meta name="generator" content="groff -Thtml, see www.gnu.org"> -<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> -<meta name="Content-Style" content="text/css"> -<style type="text/css"> - p { margin-top: 0; margin-bottom: 0; } - pre { margin-top: 0; margin-bottom: 0; } - table { margin-top: 0; margin-bottom: 0; } -</style> -<title></title> -</head> -<body> - -<hr> - - -<p valign="top">archive_write_disk(3) FreeBSD Library -Functions Manual archive_write_disk(3)</p> - -<p style="margin-top: 1em" valign="top"><b>NAME</b></p> - -<p style="margin-left:8%;"><b>archive_write_disk_new</b>, -<b>archive_write_disk_set_options</b>, -<b>archive_write_disk_set_skip_file</b>, -<b>archive_write_disk_set_group_lookup</b>, -<b>archive_write_disk_set_standard_lookup</b>, -<b>archive_write_disk_set_user_lookup</b>, -<b>archive_write_header</b>, <b>archive_write_data</b>, -<b>archive_write_finish_entry</b>, -<b>archive_write_close</b>, <b>archive_write_finish</b> -— functions for creating objects on disk</p> - - -<p style="margin-top: 1em" valign="top"><b>SYNOPSIS</b></p> - -<p style="margin-left:8%;"><b>#include -<archive.h></b></p> - -<p style="margin-left:8%; margin-top: 1em"><i>struct -archive *</i></p> - - -<p style="margin-left:14%;"><b>archive_write_disk_new</b>(<i>void</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_write_disk_set_options</b>(<i>struct archive *</i>, -<i>int flags</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_write_disk_set_skip_file</b>(<i>struct archive *</i>, -<i>dev_t</i>, <i>ino_t</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p valign="top"><b>archive_write_disk_set_group_lookup</b>(<i>struct archive *</i>, -<i>void *</i>, -<i>gid_t (*)(void *, const char *gname, gid_t gid)</i>, -<i>void (*cleanup)(void *)</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_write_disk_set_standard_lookup</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p valign="top"><b>archive_write_disk_set_user_lookup</b>(<i>struct archive *</i>, -<i>void *</i>, -<i>uid_t (*)(void *, const char *uname, uid_t uid)</i>, -<i>void (*cleanup)(void *)</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_write_header</b>(<i>struct archive *</i>, -<i>struct archive_entry *</i>);</p> - - -<p style="margin-left:8%; margin-top: 1em"><i>ssize_t</i></p> - - -<p style="margin-left:14%;"><b>archive_write_data</b>(<i>struct archive *</i>, -<i>const void *</i>, <i>size_t</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_write_finish_entry</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_write_close</b>(<i>struct archive *</i>);</p> - -<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> - - -<p style="margin-left:14%;"><b>archive_write_finish</b>(<i>struct archive *</i>);</p> - - -<p style="margin-top: 1em" valign="top"><b>DESCRIPTION</b></p> - -<p style="margin-left:8%;">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 -<b>archive_read</b>() interface. The general process is to -read struct archive_entry objects from an archive, then -write those objects to a struct archive object created using -the <b>archive_write_disk</b>() family functions. This -interface is deliberately very similar to the -<b>archive_write</b>() interface used to write objects to a -streaming archive.</p> - - -<p style="margin-top: 1em" valign="top"><b>archive_write_disk_new</b>()</p> - -<p style="margin-left:20%;">Allocates and initializes a -struct archive object suitable for writing objects to -disk.</p> - - -<p style="margin-top: 1em" valign="top"><b>archive_write_disk_set_skip_file</b>()</p> - -<p style="margin-left:20%;">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.</p> - - -<p style="margin-top: 1em" valign="top"><b>archive_write_disk_set_options</b>()</p> - -<p style="margin-left:20%;">The options field consists of a -bitwise OR of one or more of the following values:</p> - -<p valign="top"><b>ARCHIVE_EXTRACT_OWNER</b></p> - -<p style="margin-left:32%;">The user and group IDs should -be set on the restored file. By default, the user and group -IDs are not restored.</p> - -<p valign="top"><b>ARCHIVE_EXTRACT_PERM</b></p> - -<p style="margin-left:32%;">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 -<b>ARCHIVE_EXTRACT_OWNER</b> 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.</p> - -<p valign="top"><b>ARCHIVE_EXTRACT_TIME</b></p> - -<p style="margin-left:32%;">The timestamps (mtime, ctime, -and atime) should be restored. By default, they are ignored. -Note that restoring of atime is not currently supported.</p> - -<p valign="top"><b>ARCHIVE_EXTRACT_NO_OVERWRITE</b></p> - -<p style="margin-left:32%;">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.</p> - -<p valign="top"><b>ARCHIVE_EXTRACT_UNLINK</b></p> - -<p style="margin-left:32%;">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.</p> - -<p valign="top"><b>ARCHIVE_EXTRACT_ACL</b></p> - -<p style="margin-left:32%;">Attempt to restore ACLs. By -default, extended ACLs are ignored.</p> - -<p valign="top"><b>ARCHIVE_EXTRACT_FFLAGS</b></p> - -<p style="margin-left:32%;">Attempt to restore extended -file flags. By default, file flags are ignored.</p> - -<p valign="top"><b>ARCHIVE_EXTRACT_XATTR</b></p> - -<p style="margin-left:32%;">Attempt to restore POSIX.1e -extended attributes. By default, they are ignored.</p> - -<p valign="top"><b>ARCHIVE_EXTRACT_SECURE_SYMLINKS</b></p> - -<p style="margin-left:32%;">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 <b>ARCHIVE_EXTRACT_UNLINK</b> 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.</p> - -<p valign="top"><b>ARCHIVE_EXTRACT_SECURE_NODOTDOT</b></p> - -<p style="margin-left:32%;">Refuse to extract a path that -contains a <i>..</i> element anywhere within it. The default -is to not refuse such paths. Note that paths ending in -<i>..</i> always cause an error, regardless of this -flag.</p> - -<p valign="top"><b>ARCHIVE_EXTRACT_SPARSE</b></p> - -<p style="margin-left:32%;">Scan data for blocks of NUL -bytes and try to recreate them with holes. This results in -sparse files, independent of whether the archive format -supports or uses them.</p> - - -<p style="margin-top: 1em" valign="top"><b>archive_write_disk_set_group_lookup</b>(), -<b>archive_write_disk_set_user_lookup</b>()</p> - -<p style="margin-left:20%;">The struct archive_entry -objects contain both names and ids that can be used to -identify users and groups. These names and ids describe the -ownership of the file itself and also appear in ACL lists. -By default, the library uses the ids and ignores the names, -but this can be overridden by registering user and group -lookup functions. To register, you must provide a lookup -function which accepts both a name and id and returns a -suitable id. You may also provide a void * pointer to a -private data structure and a cleanup function for that data. -The cleanup function will be invoked when the struct archive -object is destroyed.</p> - - -<p style="margin-top: 1em" valign="top"><b>archive_write_disk_set_standard_lookup</b>()</p> - -<p style="margin-left:20%;">This convenience function -installs a standard set of user and group lookup functions. -These functions use getpwnam(3) and getgrnam(3) to convert -names to ids, defaulting to the ids if the names cannot be -looked up. These functions also implement a simple memory -cache to reduce the number of calls to getpwnam(3) and -getgrnam(3).</p> - - -<p style="margin-top: 1em" valign="top"><b>archive_write_header</b>()</p> - -<p style="margin-left:20%;">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.</p> - - -<p style="margin-top: 1em" valign="top"><b>archive_write_data</b>()</p> - -<p style="margin-left:20%;">Write data corresponding to the -header just written. Returns number of bytes written or -1 -on error.</p> - - -<p style="margin-top: 1em" valign="top"><b>archive_write_finish_entry</b>()</p> - -<p style="margin-left:20%;">Close out the entry just -written. Ordinarily, clients never need to call this, as it -is called automatically by -<b>archive_write_next_header</b>() and -<b>archive_write_close</b>() as needed.</p> - - -<p style="margin-top: 1em" valign="top"><b>archive_write_close</b>()</p> - -<p style="margin-left:20%;">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 <b>archive_write_disk_new</b> library -maintains a list of all such deferred attributes and sets -them when this function is invoked.</p> - - -<p style="margin-top: 1em" valign="top"><b>archive_write_finish</b>()</p> - -<p style="margin-left:20%;">Invokes -<b>archive_write_close</b>() if it was not invoked manually, -then releases all resources.</p> - -<p style="margin-left:8%;">More information about the -<i>struct archive</i> 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).</p> - -<p style="margin-top: 1em" valign="top"><b>RETURN -VALUES</b></p> - -<p style="margin-left:8%;">Most functions return -<b>ARCHIVE_OK</b> (zero) on success, or one of several -non-zero error codes for errors. Specific error codes -include: <b>ARCHIVE_RETRY</b> for operations that might -succeed if retried, <b>ARCHIVE_WARN</b> for unusual -conditions that do not prevent further operations, and -<b>ARCHIVE_FATAL</b> for serious errors that make remaining -operations impossible. The <b>archive_errno</b>() and -<b>archive_error_string</b>() functions can be used to -retrieve an appropriate error code and a textual error -message.</p> - - -<p style="margin-left:8%; margin-top: 1em"><b>archive_write_disk_new</b>() -returns a pointer to a newly-allocated struct archive -object.</p> - - -<p style="margin-left:8%; margin-top: 1em"><b>archive_write_data</b>() -returns a count of the number of bytes actually written. On -error, -1 is returned and the <b>archive_errno</b>() and -<b>archive_error_string</b>() functions will return -appropriate values.</p> - -<p style="margin-top: 1em" valign="top"><b>SEE ALSO</b></p> - -<p style="margin-left:8%;">archive_read(3), -archive_write(3), tar(1), libarchive(3)</p> - -<p style="margin-top: 1em" valign="top"><b>HISTORY</b></p> - -<p style="margin-left:8%;">The <b>libarchive</b> library -first appeared in FreeBSD 5.3. The -<b>archive_write_disk</b> interface was added to -<b>libarchive 2.0</b> and first appeared in -FreeBSD 6.3.</p> - -<p style="margin-top: 1em" valign="top"><b>AUTHORS</b></p> - -<p style="margin-left:8%;">The <b>libarchive</b> library -was written by Tim Kientzle -⟨kientzle@acm.org⟩.</p> - -<p style="margin-top: 1em" valign="top"><b>BUGS</b></p> - -<p style="margin-left:8%;">Directories are actually -extracted in two distinct phases. Directories are created -during <b>archive_write_header</b>(), but final permissions -are not set until <b>archive_write_close</b>(). This -separation is necessary to correctly handle borderline cases -such as a non-writable directory containing files, but can -cause unexpected results. In particular, directory -permissions are not fully restored until the archive is -closed. If you use chdir(2) to change the current directory -between calls to <b>archive_read_extract</b>() or before -calling <b>archive_read_close</b>(), you may confuse the -permission-setting logic with the result that directory -permissions are restored incorrectly.</p> - -<p style="margin-left:8%; margin-top: 1em">The library -attempts to create objects with filenames longer than -<b>PATH_MAX</b> 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.</p> - -<p style="margin-left:8%; margin-top: 1em">Restoring the -path <i>aa/../bb</i> does create each intermediate -directory. In particular, the directory <i>aa</i> is created -as well as the final object <i>bb</i>. In theory, this can -be exploited to create an entire directory heirarchy with a -single request. Of course, this does not work if the -<b>ARCHIVE_EXTRACT_NODOTDOT</b> option is specified.</p> - -<p style="margin-left:8%; margin-top: 1em">Implicit -directories are always created obeying the current umask. -Explicit objects are created obeying the current umask -unless <b>ARCHIVE_EXTRACT_PERM</b> is specified, in which -case they current umask is ignored.</p> - -<p style="margin-left:8%; margin-top: 1em">SGID and SUID -bits are restored only if the correct user and group could -be set. If <b>ARCHIVE_EXTRACT_OWNER</b> 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.</p> - -<p style="margin-left:8%; margin-top: 1em">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.</p> - -<p style="margin-left:8%; margin-top: 1em">There should be -a corresponding <b>archive_read_disk</b> interface that -walks a directory heirarchy and returns archive entry -objects.</p> - - -<p style="margin-left:8%; margin-top: 1em">FreeBSD 8.0 -August 5, 2008 FreeBSD 8.0</p> -<hr> -</body> -</html> diff --git a/libarchive/libarchive-2.8.0/doc/html/bsdcpio.1.html b/libarchive/libarchive-2.8.0/doc/html/bsdcpio.1.html deleted file mode 100644 index 951f0e2..0000000 --- a/libarchive/libarchive-2.8.0/doc/html/bsdcpio.1.html +++ /dev/null @@ -1,519 +0,0 @@ -<!-- Creator : groff version 1.19.2 --> -<!-- CreationDate: Thu Feb 4 20:36:41 2010 --> -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" -"http://www.w3.org/TR/html4/loose.dtd"> -<html> -<head> -<meta name="generator" content="groff -Thtml, see www.gnu.org"> -<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> -<meta name="Content-Style" content="text/css"> -<style type="text/css"> - p { margin-top: 0; margin-bottom: 0; } - pre { margin-top: 0; margin-bottom: 0; } - table { margin-top: 0; margin-bottom: 0; } -</style> -<title></title> -</head> -<body> - -<hr> - - -<p valign="top">BSDCPIO(1) FreeBSD General Commands Manual -BSDCPIO(1)</p> - -<p style="margin-top: 1em" valign="top"><b>NAME</b></p> - -<p style="margin-left:8%;"><b>cpio</b> — copy files -to and from archives</p> - - -<p style="margin-top: 1em" valign="top"><b>SYNOPSIS</b></p> - -<p style="margin-left:15%;"><b>cpio</b> {<b>−i</b>} -[<i>options</i>] [<i>pattern ...</i>] -[<i>< archive</i>] <b><br> -cpio</b> {<b>−o</b>} [<i>options</i>] <i>< -name-list</i> [<i>> archive</i>] <b><br> -cpio</b> {<b>−p</b>} [<i>options</i>] <i>dest-dir < -name-list</i></p> - - -<p style="margin-top: 1em" valign="top"><b>DESCRIPTION</b></p> - -<p style="margin-left:8%;"><b>cpio</b> 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.</p> - -<p style="margin-left:8%; margin-top: 1em">The first option -to <b>cpio</b> is a mode indicator from the following -list:</p> - -<p valign="top"><b>−i</b></p> - -<p style="margin-left:20%; margin-top: 1em">Input. Read an -archive from standard input (unless overriden) and extract -the contents to disk or (if the <b>−t</b> 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.</p> - -<p valign="top"><b>−o</b></p> - -<p style="margin-left:20%; margin-top: 1em">Output. Read a -list of filenames from standard input and produce a new -archive on standard output (unless overriden) containing the -specified items.</p> - -<p valign="top"><b>−p</b></p> - -<p style="margin-left:20%; margin-top: 1em">Pass-through. -Read a list of filenames from standard input and copy the -files to the specified directory.</p> - -<p style="margin-top: 1em" valign="top"><b>OPTIONS</b></p> - -<p style="margin-left:8%;">Unless specifically stated -otherwise, options are applicable in all operating -modes.</p> - - -<p style="margin-top: 1em" valign="top"><b>−0</b></p> - -<p style="margin-left:20%; margin-top: 1em">Read filenames -separated by NUL characters instead of newlines. This is -necessary if any of the filenames being read might contain -newlines.</p> - - -<p style="margin-top: 1em" valign="top"><b>−A</b></p> - -<p style="margin-left:20%; margin-top: 1em">(o mode only) -Append to the specified archive. (Not yet implemented.)</p> - - -<p style="margin-top: 1em" valign="top"><b>−a</b></p> - -<p style="margin-left:20%; margin-top: 1em">(o and p modes) -Reset access times on files after they are read.</p> - - -<p style="margin-top: 1em" valign="top"><b>−B</b></p> - -<p style="margin-left:20%; margin-top: 1em">(o mode only) -Block output to records of 5120 bytes.</p> - -<p style="margin-top: 1em" valign="top"><b>−C</b> -<i>size</i></p> - -<p style="margin-left:20%;">(o mode only) Block output to -records of <i>size</i> bytes.</p> - - -<p style="margin-top: 1em" valign="top"><b>−c</b></p> - -<p style="margin-left:20%; margin-top: 1em">(o mode only) -Use the old POSIX portable character format. Equivalent to -<b>−-format</b> <i>odc</i>.</p> - - -<p style="margin-top: 1em" valign="top"><b>−d</b></p> - -<p style="margin-left:20%; margin-top: 1em">(i and p modes) -Create directories as necessary.</p> - -<p style="margin-top: 1em" valign="top"><b>−E</b> -<i>file</i></p> - -<p style="margin-left:20%;">(i mode only) Read list of file -name patterns from <i>file</i> to list and extract.</p> - -<p style="margin-top: 1em" valign="top"><b>−F</b> -<i>file</i></p> - -<p style="margin-left:20%;">Read archive from or write -archive to <i>file</i>.</p> - -<p style="margin-top: 1em" valign="top"><b>−f</b> -<i>pattern</i></p> - -<p style="margin-left:20%;">(i mode only) Ignore files that -match <i>pattern</i>.</p> - - -<p style="margin-top: 1em" valign="top"><b>−-format</b> -<i>format</i></p> - -<p style="margin-left:20%;">(o mode only) Produce the -output archive in the specified format. Supported formats -include:</p> - -<p style="margin-top: 1em" valign="top"><i>cpio</i></p> - -<p style="margin-left:34%; margin-top: 1em">Synonym for -<i>odc</i>.</p> - -<p valign="top"><i>newc</i></p> - -<p style="margin-left:34%; margin-top: 1em">The SVR4 -portable cpio format.</p> - -<p valign="top"><i>odc</i></p> - -<p style="margin-left:34%; margin-top: 1em">The old POSIX.1 -portable octet-oriented cpio format.</p> - -<p valign="top"><i>pax</i></p> - -<p style="margin-left:34%; margin-top: 1em">The POSIX.1 pax -format, an extension of the ustar format.</p> - -<p valign="top"><i>ustar</i></p> - -<p style="margin-left:34%; margin-top: 1em">The POSIX.1 tar -format.</p> - -<p style="margin-left:20%; margin-top: 1em">The default -format is <i>odc</i>. See libarchive_formats(5) for more -complete information about the formats currently supported -by the underlying libarchive(3) library.</p> - -<p style="margin-top: 1em" valign="top"><b>−H</b> -<i>format</i></p> - -<p style="margin-left:20%;">Synonym for -<b>−-format</b>.</p> - -<p style="margin-top: 1em" valign="top"><b>−h</b>, -<b>−-help</b></p> - -<p style="margin-left:20%;">Print usage information.</p> - -<p style="margin-top: 1em" valign="top"><b>−I</b> -<i>file</i></p> - -<p style="margin-left:20%;">Read archive from -<i>file</i>.</p> - - -<p style="margin-top: 1em" valign="top"><b>−i</b></p> - -<p style="margin-left:20%; margin-top: 1em">Input mode. See -above for description.</p> - - -<p style="margin-top: 1em" valign="top"><b>−-insecure</b></p> - -<p style="margin-left:20%;">(i and p mode only) Disable -security checks during extraction or copying. This allows -extraction via symbolic links and path names containing -‘..’ in the name.</p> - - -<p style="margin-top: 1em" valign="top"><b>−J</b></p> - -<p style="margin-left:20%; margin-top: 1em">(o mode only) -Compress the file with xz-compatible compression before -writing it. In input mode, this option is ignored; xz -compression is recognized automatically on input.</p> - - -<p style="margin-top: 1em" valign="top"><b>−j</b></p> - -<p style="margin-left:20%; margin-top: 1em">Synonym for -<b>−y</b>.</p> - - -<p style="margin-top: 1em" valign="top"><b>−L</b></p> - -<p style="margin-left:20%; margin-top: 1em">(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.</p> - - -<p style="margin-top: 1em" valign="top"><b>−l</b></p> - -<p style="margin-left:20%; margin-top: 1em">(p mode only) -Create links from the target directory to the original -files, instead of copying.</p> - - -<p style="margin-top: 1em" valign="top"><b>−lzma</b></p> - -<p style="margin-left:20%; margin-top: 1em">(o mode only) -Compress the file with lzma-compatible compression before -writing it. In input mode, this option is ignored; lzma -compression is recognized automatically on input.</p> - - -<p style="margin-top: 1em" valign="top"><b>−m</b></p> - -<p style="margin-left:20%; margin-top: 1em">(i and p modes) -Set file modification time on created files to match those -in the source.</p> - - -<p style="margin-top: 1em" valign="top"><b>−n</b></p> - -<p style="margin-left:20%; margin-top: 1em">(i mode, only -with <b>−t</b>) Display numeric uid and gid. By -default, <b>cpio</b> displays the user and group names when -they are provided in the archive, or looks up the user and -group names in the system password database.</p> - - -<p style="margin-top: 1em" valign="top"><b>−no-preserve-owner</b></p> - -<p style="margin-left:20%;">(i mode only) Do not attempt to -restore file ownership. This is the default when run by -non-root users.</p> - -<p style="margin-top: 1em" valign="top"><b>−O</b> -<i>file</i></p> - -<p style="margin-left:20%;">Write archive to -<i>file</i>.</p> - - -<p style="margin-top: 1em" valign="top"><b>−o</b></p> - -<p style="margin-left:20%; margin-top: 1em">Output mode. -See above for description.</p> - - -<p style="margin-top: 1em" valign="top"><b>−p</b></p> - -<p style="margin-left:20%; margin-top: 1em">Pass-through -mode. See above for description.</p> - - -<p style="margin-top: 1em" valign="top"><b>−preserve-owner</b></p> - -<p style="margin-left:20%;">(i mode only) Restore file -ownership. This is the default when run by the root -user.</p> - - -<p style="margin-top: 1em" valign="top"><b>−-quiet</b></p> - -<p style="margin-left:20%;">Suppress unnecessary -messages.</p> - -<p style="margin-top: 1em" valign="top"><b>−R</b> [ -<br> -user][ <br> -:][ <br> -group]</p> - -<p style="margin-left:20%;">Set the owner and/or group on -files in the output. If group is specified with no user (for -example, <b>−R</b> <i>:wheel</i>) then the group will -be set but not the user. If the user is specified with a -trailing colon and no group (for example, <b>−R</b> -<i>root:</i>) 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 -<b>−i</b> and <b>−p</b> modes, this option can -only be used by the super-user. (For compatibility, a period -can be used in place of the colon.)</p> - - -<p style="margin-top: 1em" valign="top"><b>−r</b></p> - -<p style="margin-left:20%; margin-top: 1em">(All modes.) -Rename files interactively. For each file, a prompt is -written to <i>/dev/tty</i> containing the name of the file -and a line is read from <i>/dev/tty</i>. 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.</p> - - -<p style="margin-top: 1em" valign="top"><b>−t</b></p> - -<p style="margin-left:20%; margin-top: 1em">(i mode only) -List the contents of the archive to stdout; do not restore -the contents to disk.</p> - - -<p style="margin-top: 1em" valign="top"><b>−u</b></p> - -<p style="margin-left:20%; margin-top: 1em">(i and p modes) -Unconditionally overwrite existing files. Ordinarily, an -older file will not overwrite a newer file on disk.</p> - - -<p style="margin-top: 1em" valign="top"><b>−v</b></p> - -<p style="margin-left:20%; margin-top: 1em">Print the name -of each file to stderr as it is processed. With -<b>−t</b>, provide a detailed listing of each -file.</p> - - -<p style="margin-top: 1em" valign="top"><b>−-version</b></p> - -<p style="margin-left:20%;">Print the program version -information and exit.</p> - - -<p style="margin-top: 1em" valign="top"><b>−y</b></p> - -<p style="margin-left:20%; margin-top: 1em">(o mode only) -Compress the archive with bzip2-compatible compression -before writing it. In input mode, this option is ignored; -bzip2 compression is recognized automatically on input.</p> - - -<p style="margin-top: 1em" valign="top"><b>−Z</b></p> - -<p style="margin-left:20%; margin-top: 1em">(o mode only) -Compress the archive with compress-compatible compression -before writing it. In input mode, this option is ignored; -compression is recognized automatically on input.</p> - - -<p style="margin-top: 1em" valign="top"><b>−z</b></p> - -<p style="margin-left:20%; margin-top: 1em">(o mode only) -Compress the archive with gzip-compatible compression before -writing it. In input mode, this option is ignored; gzip -compression is recognized automatically on input.</p> - - -<p style="margin-top: 1em" valign="top"><b>ENVIRONMENT</b></p> - -<p style="margin-left:8%;">The following environment -variables affect the execution of <b>cpio</b>:</p> - -<p style="margin-top: 1em" valign="top">LANG</p> - -<p style="margin-left:25%; margin-top: 1em">The locale to -use. See environ(7) for more information.</p> - -<p style="margin-top: 1em" valign="top">TZ</p> - -<p style="margin-left:25%; margin-top: 1em">The timezone to -use when displaying dates. See environ(7) for more -information.</p> - -<p style="margin-top: 1em" valign="top"><b>EXIT -STATUS</b></p> - -<p style="margin-left:8%;">The <b>cpio</b> utility -exits 0 on success, and >0 if an error -occurs.</p> - - -<p style="margin-top: 1em" valign="top"><b>EXAMPLES</b></p> - -<p style="margin-left:8%;">The <b>cpio</b> command is -traditionally used to copy file heirarchies in conjunction -with the find(1) command. The first example here simply -copies all files from <i>src</i> to <i>dest</i>:</p> - -<p style="margin-left:17%;"><b>find</b> <i>src</i> | -<b>cpio −pmud</b> <i>dest</i></p> - -<p style="margin-left:8%; margin-top: 1em">By carefully -selecting options to the find(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 <i>src</i> to <i>dest</i> that are -more than 2 days old and whose names match a particular -pattern:</p> - -<p style="margin-left:17%;"><b>find</b> <i>src</i> -<b>−mtime</b> <i>+2</i> | <b>grep foo[bar]</b> | -<b>cpio −pdmu</b> <i>dest</i></p> - -<p style="margin-left:8%; margin-top: 1em">This example -copies files from <i>src</i> to <i>dest</i> that are more -than 2 days old and which contain the word -‘‘</p> - -<p valign="top">foobar ’’:</p> - -<p style="margin-left:17%;"><b>find</b> <i>src</i> -<b>−mtime</b> <i>+2</i> | <b>xargs grep -l foobar</b> -| <b>cpio −pdmu</b> <i>dest</i></p> - - -<p style="margin-top: 1em" valign="top"><b>COMPATIBILITY</b></p> - -<p style="margin-left:8%;">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.</p> - -<p style="margin-left:8%; margin-top: 1em">The old POSIX.1 -standard specified that only <b>−i</b>, -<b>−o</b>, and <b>−p</b> were interpreted as -command-line options. Each took a single argument of a list -of modifier characters. For example, the standard syntax -allows <b>−imu</b> but does not support -<b>−miu</b> or <b>−i −m −u</b>, -since <i>m</i> and <i>u</i> are only modifiers to -<b>−i</b>, 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.</p> - -<p style="margin-top: 1em" valign="top"><b>SEE ALSO</b></p> - -<p style="margin-left:8%;">bzip2(1), tar(1), gzip(1), -mt(1), pax(1), libarchive(3), cpio(5), -libarchive-formats(5), tar(5)</p> - - -<p style="margin-top: 1em" valign="top"><b>STANDARDS</b></p> - -<p style="margin-left:8%;">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’’).</p> - -<p style="margin-left:8%; margin-top: 1em">The cpio, ustar, -and pax interchange file formats are defined by IEEE Std -1003.1-2001 (‘‘POSIX.1’’) for the -pax command.</p> - -<p style="margin-top: 1em" valign="top"><b>HISTORY</b></p> - -<p style="margin-left:8%;">The original <b>cpio</b> and -<b>find</b> 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, <b>cpio</b> actually predates <b>tar</b>, -even though it was not well-known outside of AT&T until -some time later.</p> - -<p style="margin-left:8%; margin-top: 1em">This is a -complete re-implementation based on the libarchive(3) -library.</p> - -<p style="margin-top: 1em" valign="top"><b>BUGS</b></p> - -<p style="margin-left:8%;">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.</p> - - -<p style="margin-left:8%; margin-top: 1em">FreeBSD 8.0 -December 21, 2007 FreeBSD 8.0</p> -<hr> -</body> -</html> diff --git a/libarchive/libarchive-2.8.0/doc/html/bsdtar.1.html b/libarchive/libarchive-2.8.0/doc/html/bsdtar.1.html deleted file mode 100644 index 3b84d21..0000000 --- a/libarchive/libarchive-2.8.0/doc/html/bsdtar.1.html +++ /dev/null @@ -1,1014 +0,0 @@ -<!-- Creator : groff version 1.19.2 --> -<!-- CreationDate: Thu Feb 4 20:36:40 2010 --> -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" -"http://www.w3.org/TR/html4/loose.dtd"> -<html> -<head> -<meta name="generator" content="groff -Thtml, see www.gnu.org"> -<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> -<meta name="Content-Style" content="text/css"> -<style type="text/css"> - p { margin-top: 0; margin-bottom: 0; } - pre { margin-top: 0; margin-bottom: 0; } - table { margin-top: 0; margin-bottom: 0; } -</style> -<title></title> -</head> -<body> - -<hr> - - -<p valign="top">BSDTAR(1) FreeBSD General Commands Manual -BSDTAR(1)</p> - -<p style="margin-top: 1em" valign="top"><b>NAME</b></p> - -<p style="margin-left:8%;"><b>tar</b> — manipulate -tape archives</p> - - -<p style="margin-top: 1em" valign="top"><b>SYNOPSIS</b></p> - -<p style="margin-left:14%;"><b>tar</b> -[<i>bundled-flags </i>⟨</p> - -<p valign="top">args ⟩] [⟨ <i><br> -file</i> ⟩ | ⟨ <i><br> -pattern</i> ⟩ ...]</p> - -<p style="margin-left:14%;"><b>tar</b> {<b>−c</b>} -[<i>options</i>] -[<i>files </i>| <i>directories</i>] <b><br> -tar</b> {<b>−r </b>| <b>−u</b>} -<b>−f</b> <i>archive-file</i> [<i>options</i>] -[<i>files </i>| <i>directories</i>] <b><br> -tar</b> {<b>−t </b>| <b>−x</b>} -[<i>options</i>] [<i>patterns</i>]</p> - - -<p style="margin-top: 1em" valign="top"><b>DESCRIPTION</b></p> - -<p style="margin-left:8%;"><b>tar</b> 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.</p> - -<p style="margin-left:8%; margin-top: 1em">The first -synopsis form shows a ‘‘bundled’’ -option word. This usage is provided for compatibility with -historical implementations. See COMPATIBILITY below for -details.</p> - -<p style="margin-left:8%; margin-top: 1em">The other -synopsis forms show the preferred usage. The first option to -<b>tar</b> is a mode indicator from the following list:</p> - -<p valign="top"><b>−c</b></p> - -<p style="margin-left:20%; margin-top: 1em">Create a new -archive containing the specified items.</p> - -<p valign="top"><b>−r</b></p> - -<p style="margin-left:20%; margin-top: 1em">Like -<b>−c</b>, but new entries are appended to the -archive. Note that this only works on uncompressed archives -stored in regular files. The <b>−f</b> option is -required.</p> - -<p valign="top"><b>−t</b></p> - -<p style="margin-left:20%; margin-top: 1em">List archive -contents to stdout.</p> - -<p valign="top"><b>−u</b></p> - -<p style="margin-left:20%; margin-top: 1em">Like -<b>−r</b>, 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 <b>−f</b> option -is required.</p> - -<p valign="top"><b>−x</b></p> - -<p style="margin-left:20%; margin-top: 1em">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.</p> - -<p style="margin-left:8%; margin-top: 1em">In -<b>−c</b>, <b>−r</b>, or <b>−u</b> 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.</p> - -<p style="margin-left:8%; margin-top: 1em">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).</p> - -<p style="margin-top: 1em" valign="top"><b>OPTIONS</b></p> - -<p style="margin-left:8%;">Unless specifically stated -otherwise, options are applicable in all operating -modes.</p> - - -<p style="margin-top: 1em" valign="top"><b>@</b><i>archive</i></p> - -<p style="margin-left:20%;">(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,</p> - -<p style="margin-left:29%;"><b>tar −c −f</b> -<i>- newfile</i> <b>@</b><i>original.tar</i></p> - -<p style="margin-left:20%;">writes a new archive to -standard output containing a file <i>newfile</i> and all of -the entries from <i>original.tar</i>. In contrast,</p> - -<p style="margin-left:29%;"><b>tar −c −f</b> -<i>- newfile original.tar</i></p> - -<p style="margin-left:20%;">creates a new archive with only -two entries. Similarly,</p> - -<p style="margin-left:29%;"><b>tar −czf</b> <i>-</i> -<b>−-format pax @</b><i>-</i></p> - -<p style="margin-left:20%;">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, <b>tar</b> can be used to convert -archives from one format to another.</p> - -<p style="margin-top: 1em" valign="top"><b>−b</b> -<i>blocksize</i></p> - -<p style="margin-left:20%;">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.</p> - -<p style="margin-top: 1em" valign="top"><b>−C</b> -<i>directory</i></p> - -<p style="margin-left:20%;">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.</p> - - -<p style="margin-top: 1em" valign="top"><b>−-check-links</b></p> - -<p style="margin-left:20%;">(c and r modes only) Issue a -warning message unless all links to each file are -archived.</p> - - -<p style="margin-top: 1em" valign="top"><b>−-chroot</b></p> - -<p style="margin-left:20%;">(x mode only) <b>chroot</b>() -to the current directory after processing any -<b>−C</b> options and before extracting any files.</p> - - -<p style="margin-top: 1em" valign="top"><b>−-exclude</b> -<i>pattern</i></p> - -<p style="margin-left:20%;">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.</p> - - -<p style="margin-top: 1em" valign="top"><b>−-format</b> -<i>format</i></p> - -<p style="margin-left:20%;">(c, r, u mode only) Use the -specified format for the created archive. Supported formats -include ‘‘cpio’’, -‘‘pax’’, -‘‘shar’’, and -‘‘ustar’’. Other formats may also be -supported; see libarchive-formats(5) for more information -about currently-supported formats. In r and u modes, when -extending an existing archive, the format specified here -must be compatible with the format of the existing archive -on disk.</p> - -<p style="margin-top: 1em" valign="top"><b>−f</b> -<i>file</i></p> - -<p style="margin-left:20%;">Read the archive from or write -the archive to the specified file. The filename can be -<i>-</i> for standard input or standard output. If not -specified, the default tape device will be used. (On -FreeBSD, the default tape device is <i>/dev/sa0</i>.)</p> - - -<p style="margin-top: 1em" valign="top"><b>−H</b></p> - -<p style="margin-left:20%; margin-top: 1em">(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.</p> - - -<p style="margin-top: 1em" valign="top"><b>−h</b></p> - -<p style="margin-left:20%; margin-top: 1em">(c and r mode -only) Synonym for <b>−L</b>.</p> - - -<p style="margin-top: 1em" valign="top"><b>−I</b></p> - -<p style="margin-left:20%; margin-top: 1em">Synonym for -<b>−T</b>.</p> - - -<p style="margin-top: 1em" valign="top"><b>−-include</b> -<i>pattern</i></p> - -<p style="margin-left:20%;">Process only files or -directories that match the specified pattern. Note that -exclusions specified with <b>−-exclude</b> take -precedence over inclusions. If no inclusions are explicitly -specified, all entries are processed by default. The -<b>−-include</b> option is especially useful when -filtering archives. For example, the command</p> - -<p style="margin-left:29%;"><b>tar −c −f</b> -<i>new.tar</i> <b>−-include=’*foo*’ -@</b><i>old.tgz</i></p> - -<p style="margin-left:20%;">creates a new archive -<i>new.tar</i> containing only the entries from -<i>old.tgz</i> containing the string ‘foo’.</p> - - -<p style="margin-top: 1em" valign="top"><b>−j</b></p> - -<p style="margin-left:20%; margin-top: 1em">(c mode only) -Compress the resulting archive with bzip2(1). In extract or -list modes, this option is ignored. Note that, unlike other -<b>tar</b> implementations, this implementation recognizes -bzip2 compression automatically when reading archives.</p> - - -<p style="margin-top: 1em" valign="top"><b>−k</b></p> - -<p style="margin-left:20%; margin-top: 1em">(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.</p> - - -<p style="margin-top: 1em" valign="top"><b>−-keep-newer-files</b></p> - -<p style="margin-left:20%;">(x mode only) Do not overwrite -existing files that are newer than the versions appearing in -the archive being extracted.</p> - - -<p style="margin-top: 1em" valign="top"><b>−L</b></p> - -<p style="margin-left:20%; margin-top: 1em">(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.</p> - - -<p style="margin-top: 1em" valign="top"><b>−l</b></p> - -<p style="margin-left:20%; margin-top: 1em">This is a -synonym for the <b>−-check-links</b> option.</p> - - -<p style="margin-top: 1em" valign="top"><b>−m</b></p> - -<p style="margin-left:20%; margin-top: 1em">(x mode only) -Do not extract modification time. By default, the -modification time is set to the time stored in the -archive.</p> - - -<p style="margin-top: 1em" valign="top"><b>−n</b></p> - -<p style="margin-left:20%; margin-top: 1em">(c, r, u modes -only) Do not recursively archive the contents of -directories.</p> - - -<p style="margin-top: 1em" valign="top"><b>−-newer</b> -<i>date</i></p> - -<p style="margin-left:20%;">(c, r, u modes only) Only -include files and directories newer than the specified date. -This compares ctime entries.</p> - - -<p style="margin-top: 1em" valign="top"><b>−-newer-mtime</b> -<i>date</i></p> - -<p style="margin-left:20%;">(c, r, u modes only) Like -<b>−-newer</b>, except it compares mtime entries -instead of ctime entries.</p> - - -<p style="margin-top: 1em" valign="top"><b>−-newer-than</b> -<i>file</i></p> - -<p style="margin-left:20%;">(c, r, u modes only) Only -include files and directories newer than the specified file. -This compares ctime entries.</p> - - -<p style="margin-top: 1em" valign="top"><b>−-newer-mtime-than</b> -<i>file</i></p> - -<p style="margin-left:20%;">(c, r, u modes only) Like -<b>−-newer-than</b>, except it compares mtime entries -instead of ctime entries.</p> - - -<p style="margin-top: 1em" valign="top"><b>−-nodump</b></p> - -<p style="margin-left:20%;">(c and r modes only) Honor the -nodump file flag by skipping this file.</p> - - -<p style="margin-top: 1em" valign="top"><b>−-null</b></p> - -<p style="margin-left:20%; margin-top: 1em">(use with -<b>−I</b>, <b>−T</b>, or <b>−X</b>) -Filenames or patterns are separated by null characters, not -by newlines. This is often used to read filenames output by -the <b>−print0</b> option to find(1).</p> - - -<p style="margin-top: 1em" valign="top"><b>−-numeric-owner</b></p> - -<p style="margin-left:20%;">(x mode only) Ignore symbolic -user and group names when restoring archives to disk, only -numeric uid and gid values will be obeyed.</p> - - -<p style="margin-top: 1em" valign="top"><b>−O</b></p> - -<p style="margin-left:20%; margin-top: 1em">(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.</p> - - -<p style="margin-top: 1em" valign="top"><b>−o</b></p> - -<p style="margin-left:20%; margin-top: 1em">(x mode) Use -the user and group of the user running the program rather -than those specified in the archive. Note that this has no -significance unless <b>−p</b> 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.</p> - - -<p style="margin-top: 1em" valign="top"><b>−o</b></p> - -<p style="margin-left:20%; margin-top: 1em">(c, r, u mode) -A synonym for <b>−-format</b> <i>ustar</i></p> - - -<p style="margin-top: 1em" valign="top"><b>−-one-file-system</b></p> - -<p style="margin-left:20%;">(c, r, and u modes) Do not -cross mount points.</p> - - -<p style="margin-top: 1em" valign="top"><b>−-options</b> -<i>options</i></p> - -<p style="margin-left:20%;">Select optional behaviors for -particular modules. The argument is a text string containing -comma-separated keywords and values. These are passed to the -modules that handle particular formats to control how those -formats will behave. Each option has one of the following -forms:</p> - -<p valign="top"><i>key=value</i></p> - -<p style="margin-left:32%;">The key will be set to the -specified value in every module that supports it. Modules -that do not support this key will ignore it.</p> - -<p valign="top"><i>key</i></p> - -<p style="margin-left:32%; margin-top: 1em">The key will be -enabled in every module that supports it. This is equivalent -to <i>key</i><b>=1</b>.</p> - -<p valign="top"><i>!key</i></p> - -<p style="margin-left:32%; margin-top: 1em">The key will be -disabled in every module that supports it.</p> - -<p valign="top"><i>module:key=value</i>, <i>module:key</i>, -<i>module:!key</i></p> - -<p style="margin-left:32%;">As above, but the corresponding -key and value will be provided only to modules whose name -matches <i>module</i>.</p> - -<p style="margin-left:20%;">The currently supported modules -and keys are:</p> - -<p valign="top"><b>iso9660:joliet</b></p> - -<p style="margin-left:32%;">Support Joliet extensions. This -is enabled by default, use <b>!joliet</b> or -<b>iso9660:!joliet</b> to disable.</p> - -<p valign="top"><b>iso9660:rockridge</b></p> - -<p style="margin-left:32%;">Support Rock Ridge extensions. -This is enabled by default, use <b>!rockridge</b> or -<b>iso9660:!rockridge</b> to disable.</p> - -<p valign="top"><b>gzip:compression-level</b></p> - -<p style="margin-left:32%;">A decimal integer from 0 to 9 -specifying the gzip compression level.</p> - -<p valign="top"><b>xz:compression-level</b></p> - -<p style="margin-left:32%;">A decimal integer from 0 to 9 -specifying the xz compression level.</p> - -<p valign="top"><b>mtree:</b><i>keyword</i></p> - -<p style="margin-left:32%;">The mtree writer module allows -you to specify which mtree keywords will be included in the -output. Supported keywords include: <b>cksum</b>, -<b>device</b>, <b>flags</b>, <b>gid</b>, <b>gname</b>, -<b>indent</b>, <b>link</b>, <b>md5</b>, <b>mode</b>, -<b>nlink</b>, <b>rmd160</b>, <b>sha1</b>, <b>sha256</b>, -<b>sha384</b>, <b>sha512</b>, <b>size</b>, <b>time</b>, -<b>uid</b>, <b>uname</b>. The default is equivalent to: -‘‘device, flags, gid, gname, link, mode, nlink, -size, time, type, uid, uname’’.</p> - -<p valign="top"><b>mtree:all</b></p> - -<p style="margin-left:32%;">Enables all of the above -keywords. You can also use <b>mtree:!all</b> to disable all -keywords.</p> - -<p valign="top"><b>mtree:use-set</b></p> - -<p style="margin-left:32%;">Enable generation of -<b>/set</b> lines in the output.</p> - -<p valign="top"><b>mtree:indent</b></p> - -<p style="margin-left:32%;">Produce human-readable output -by indenting options and splitting lines to fit into 80 -columns.</p> - -<p valign="top"><b>zip:compression</b>=<i>type</i></p> - -<p style="margin-left:32%;">Use <i>type</i> as compression -method. Supported values are store (uncompressed) and -deflate (gzip algorithm).</p> - -<p style="margin-left:20%;">If a provided option is not -supported by any module, that is a fatal error.</p> - - -<p style="margin-top: 1em" valign="top"><b>−P</b></p> - -<p style="margin-left:20%; margin-top: 1em">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, <b>tar</b> -will refuse to extract archive entries whose pathnames -contain <i>..</i> or whose target directory would be altered -by a symlink. This option suppresses these behaviors.</p> - - -<p style="margin-top: 1em" valign="top"><b>−p</b></p> - -<p style="margin-left:20%; margin-top: 1em">(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 <b>tar</b>, the file mode is restored for -newly-created regular files, and all other types of entries -receive default permissions. If <b>tar</b> is being run by -root, the default is to restore the owner unless the -<b>−o</b> option is also specified.</p> - -<p style="margin-top: 1em" valign="top"><b>−q</b> -(<b>−-fast-read</b>)</p> - -<p style="margin-left:20%;">(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.</p> - - -<p style="margin-top: 1em" valign="top"><b>−S</b></p> - -<p style="margin-left:20%; margin-top: 1em">(x mode only) -Extract files as sparse files. For every block on disk, -check first if it contains only NULL bytes and seek over it -otherwise. This works similiar to the conv=sparse option of -dd.</p> - - -<p style="margin-top: 1em" valign="top"><b>−-strip-components</b> -<i>count</i></p> - -<p style="margin-left:20%;">(x mode only) Remove the -specified number of leading path elements. Pathnames with -fewer elements will be silently skipped. Note that the -pathname is edited after checking inclusion/exclusion -patterns but before security checks.</p> - -<p style="margin-top: 1em" valign="top"><b>−s</b> -<i>pattern</i></p> - -<p style="margin-left:20%;">Modify file or archive member -names according to <i>pattern</i>. The pattern has the -format <i>/old/new/</i>[gps] where <i>old</i> is a basic -regular expression, <i>new</i> is the replacement string of -the matched part, and the optional trailing letters modify -how the replacement is handled. If <i>old</i> is not -matched, the pattern is skipped. Within <i>new</i>, ~ is -substituted with the match, 1 to 9 with the content of the -corresponding captured group. The optional trailing g -specifies that matching should continue after the matched -part and stopped on the first unmatched pattern. The -optional trailing s specifies that the pattern applies to -the value of symbolic links. The optional trailing p -specifies that after a successful substitution the original -path name and the new path name should be printed to -standard error.</p> - -<p style="margin-top: 1em" valign="top"><b>−T</b> -<i>filename</i></p> - -<p style="margin-left:20%;">In x or t mode, <b>tar</b> will -read the list of names to be extracted from <i>filename</i>. -In c mode, <b>tar</b> will read names to be archived from -<i>filename</i>. 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 <b>−-null</b> is specified. Note that -<b>−-null</b> also disables the special handling of -lines containing ‘‘-C’’.</p> - - -<p style="margin-top: 1em" valign="top"><b>−U</b></p> - -<p style="margin-left:20%; margin-top: 1em">(x mode only) -Unlink files before creating them. Without this option, -<b>tar</b> 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.</p> - - -<p style="margin-top: 1em" valign="top"><b>−-use-compress-program</b> -<i>program</i></p> - -<p style="margin-left:20%;">Pipe the input (in x or t mode) -or the output (in c mode) through <i>program</i> instead of -using the builtin compression support.</p> - - -<p style="margin-top: 1em" valign="top"><b>−v</b></p> - -<p style="margin-left:20%; margin-top: 1em">Produce verbose -output. In create and extract modes, <b>tar</b> will list -each file name as it is read from or written to the archive. -In list mode, <b>tar</b> will produce output similar to that -of ls(1). Additional <b>−v</b> options will provide -additional detail.</p> - - -<p style="margin-top: 1em" valign="top"><b>−-version</b></p> - -<p style="margin-left:20%;">Print version of <b>tar</b> and -<b>libarchive</b>, and exit.</p> - - -<p style="margin-top: 1em" valign="top"><b>−w</b></p> - -<p style="margin-left:20%; margin-top: 1em">Ask for -confirmation for every action.</p> - -<p style="margin-top: 1em" valign="top"><b>−X</b> -<i>filename</i></p> - -<p style="margin-left:20%;">Read a list of exclusion -patterns from the specified file. See <b>−-exclude</b> -for more information about the handling of exclusions.</p> - - -<p style="margin-top: 1em" valign="top"><b>−y</b></p> - -<p style="margin-left:20%; margin-top: 1em">(c mode only) -Compress the resulting archive with bzip2(1). In extract or -list modes, this option is ignored. Note that, unlike other -<b>tar</b> implementations, this implementation recognizes -bzip2 compression automatically when reading archives.</p> - - -<p style="margin-top: 1em" valign="top"><b>−z</b></p> - -<p style="margin-left:20%; margin-top: 1em">(c mode only) -Compress the resulting archive with gzip(1). In extract or -list modes, this option is ignored. Note that, unlike other -<b>tar</b> implementations, this implementation recognizes -gzip compression automatically when reading archives.</p> - - -<p style="margin-top: 1em" valign="top"><b>−Z</b></p> - -<p style="margin-left:20%; margin-top: 1em">(c mode only) -Compress the resulting archive with compress(1). In extract -or list modes, this option is ignored. Note that, unlike -other <b>tar</b> implementations, this implementation -recognizes compress compression automatically when reading -archives.</p> - - -<p style="margin-top: 1em" valign="top"><b>ENVIRONMENT</b></p> - -<p style="margin-left:8%;">The following environment -variables affect the execution of <b>tar</b>:</p> - -<p style="margin-top: 1em" valign="top">LANG</p> - -<p style="margin-left:25%; margin-top: 1em">The locale to -use. See environ(7) for more information.</p> - -<p style="margin-top: 1em" valign="top">TAPE</p> - -<p style="margin-left:25%; margin-top: 1em">The default -tape device. The <b>−f</b> option overrides this.</p> - -<p style="margin-top: 1em" valign="top">TZ</p> - -<p style="margin-left:25%; margin-top: 1em">The timezone to -use when displaying dates. See environ(7) for more -information.</p> - -<p style="margin-top: 1em" valign="top"><b>FILES</b> <br> -/dev/sa0</p> - -<p style="margin-left:25%; margin-top: 1em">The default -tape device, if not overridden by the TAPE environment -variable or the <b>−f</b> option.</p> - -<p style="margin-top: 1em" valign="top"><b>EXIT -STATUS</b></p> - -<p style="margin-left:8%;">The <b>tar</b> utility -exits 0 on success, and >0 if an error -occurs.</p> - - -<p style="margin-top: 1em" valign="top"><b>EXAMPLES</b></p> - -<p style="margin-left:8%;">The following creates a new -archive called <i>file.tar.gz</i> that contains two files -<i>source.c</i> and <i>source.h</i>:</p> - -<p style="margin-left:17%;"><b>tar −czf</b> -<i>file.tar.gz source.c source.h</i></p> - -<p style="margin-left:8%; margin-top: 1em">To view a -detailed table of contents for this archive:</p> - -<p style="margin-left:17%;"><b>tar −tvf</b> -<i>file.tar.gz</i></p> - -<p style="margin-left:8%; margin-top: 1em">To extract all -entries from the archive on the default tape drive:</p> - -<p style="margin-left:17%;"><b>tar −x</b></p> - -<p style="margin-left:8%; margin-top: 1em">To examine the -contents of an ISO 9660 cdrom image:</p> - -<p style="margin-left:17%;"><b>tar −tf</b> -<i>image.iso</i></p> - -<p style="margin-left:8%; margin-top: 1em">To move file -hierarchies, invoke <b>tar</b> as</p> - -<p style="margin-left:17%;"><b>tar −cf</b> <i>-</i> -<b>−C</b> <i>srcdir .</i> | <b>tar −xpf</b> -<i>-</i> <b>−C</b> <i>destdir</i></p> - -<p style="margin-left:8%;">or more traditionally</p> - -<p style="margin-left:17%;">cd srcdir ; <b>tar -−cf</b> <i>- .</i> | (<i>cd destdir ;</i> <b>tar -−xpf</b> <i>-</i>)</p> - -<p style="margin-left:8%; margin-top: 1em">In create mode, -the list of files and directories to be archived can also -include directory change instructions of the form -<b>-C</b><i>foo/baz</i> and archive inclusions of the form -<b>@</b><i>archive-file</i>. For example, the command -line</p> - -<p style="margin-left:17%;"><b>tar −c −f</b> -<i>new.tar foo1</i> <b>@</b><i>old.tgz</i> <b>-C</b><i>/tmp -foo2</i></p> - -<p style="margin-left:8%;">will create a new archive -<i>new.tar</i>. <b>tar</b> will read the file <i>foo1</i> -from the current directory and add it to the output archive. -It will then read each entry from <i>old.tgz</i> and add -those entries to the output archive. Finally, it will switch -to the <i>/tmp</i> directory and add <i>foo2</i> to the -output archive.</p> - -<p style="margin-left:8%; margin-top: 1em">An input file in -mtree(5) format can be used to create an output archive with -arbitrary ownership, permissions, or names that differ from -existing data on disk:</p> - -<p style="margin-left:17%; margin-top: 1em">$ cat -input.mtree <br> -#mtree <br> -usr/bin uid=0 gid=0 mode=0755 type=dir <br> -usr/bin/ls uid=0 gid=0 mode=0755 type=file content=myls <br> -$ tar -cvf output.tar @input.mtree</p> - -<p style="margin-left:8%; margin-top: 1em">The -<b>−-newer</b> and <b>−-newer-mtime</b> 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’’.</p> - -<p style="margin-left:8%; margin-top: 1em">The -<b>−-options</b> argument can be used to control -various details of archive generation or reading. For -example, you can generate mtree output which only contains -<b>type</b>, <b>time</b>, and <b>uid</b> keywords:</p> - -<p style="margin-left:17%;"><b>tar −cf</b> -<i>file.tar</i> <b>−-format=mtree -−-options=’!all,type,time,uid’</b> -<i>dir</i></p> - -<p style="margin-left:8%;">or you can set the compression -level used by gzip or xz compression:</p> - -<p style="margin-left:17%;"><b>tar −czf</b> -<i>file.tar</i> -<b>−-options=’compression-level=9’</b>.</p> - -<p style="margin-left:8%;">For more details, see the -explanation of the <b>archive_read_set_options</b>() and -<b>archive_write_set_options</b>() API calls that are -described in archive_read(3) and archive_write(3).</p> - - -<p style="margin-top: 1em" valign="top"><b>COMPATIBILITY</b></p> - -<p style="margin-left:8%;">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,</p> - -<p style="margin-left:17%;"><b>tar tbf 32</b> -<i>file.tar</i></p> - -<p style="margin-left:8%;">specifies three flags <b>t</b>, -<b>b</b>, and <b>f</b>. The <b>b</b> and <b>f</b> flags both -require arguments, so there must be two additional items on -the command line. The <i>32</i> is the argument to the -<b>b</b> flag, and <i>file.tar</i> is the argument to the -<b>f</b> flag.</p> - -<p style="margin-left:8%; margin-top: 1em">The mode options -c, r, t, u, and x and the options b, f, l, m, o, v, and w -comply with SUSv2.</p> - -<p style="margin-left:8%; margin-top: 1em">For maximum -portability, scripts that invoke <b>tar</b> should use the -bundled-argument format above, should limit themselves to -the <b>c</b>, <b>t</b>, and <b>x</b> modes, and the -<b>b</b>, <b>f</b>, <b>m</b>, <b>v</b>, and <b>w</b> -options.</p> - -<p style="margin-left:8%; margin-top: 1em">Additional long -options are provided to improve compatibility with other tar -implementations.</p> - - -<p style="margin-top: 1em" valign="top"><b>SECURITY</b></p> - -<p style="margin-left:8%;">Certain security issues are -common to many archiving programs, including <b>tar</b>. In -particular, carefully-crafted archives can request that -<b>tar</b> 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 <b>tar</b> has -mechanisms to protect against each one, savvy users should -be aware of the implications:</p> - -<p style="margin-top: 1em" valign="top"><b>•</b></p> - -<p style="margin-left:20%;">Archive entries can have -absolute pathnames. By default, <b>tar</b> removes the -leading <i>/</i> character from filenames before restoring -them to guard against this problem.</p> - -<p style="margin-top: 1em" valign="top"><b>•</b></p> - -<p style="margin-left:20%;">Archive entries can have -pathnames that include <i>..</i> components. By default, -<b>tar</b> will not extract files containing <i>..</i> -components in their pathname.</p> - -<p style="margin-top: 1em" valign="top"><b>•</b></p> - -<p style="margin-left:20%;">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, <b>tar</b> 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 -<b>−U</b> is specified, any intermediate symlink will -also be unconditionally removed. If neither <b>−U</b> -nor <b>−P</b> is specified, <b>tar</b> will refuse to -extract the entry.</p> - -<p style="margin-left:8%;">To protect yourself, you should -be wary of any archives that come from untrusted sources. -You should examine the contents of an archive with</p> - -<p style="margin-left:17%;"><b>tar −tf</b> -<i>filename</i></p> - -<p style="margin-left:8%;">before extraction. You should -use the <b>−k</b> option to ensure that <b>tar</b> -will not overwrite any existing files or the <b>−U</b> -option to remove any pre-existing files. You should -generally not extract archives while running with super-user -privileges. Note that the <b>−P</b> option to -<b>tar</b> disables the security checks above and allows you -to extract an archive while preserving any absolute -pathnames, <i>..</i> components, or symlinks to other -directories.</p> - -<p style="margin-top: 1em" valign="top"><b>SEE ALSO</b></p> - -<p style="margin-left:8%;">bzip2(1), compress(1), cpio(1), -gzip(1), mt(1), pax(1), shar(1), libarchive(3), -libarchive-formats(5), tar(5)</p> - - -<p style="margin-top: 1em" valign="top"><b>STANDARDS</b></p> - -<p style="margin-left:8%;">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.</p> - -<p style="margin-left:8%; margin-top: 1em">The ustar and -pax interchange file formats are defined by IEEE Std -1003.1-2001 (‘‘POSIX.1’’) for the -pax command.</p> - -<p style="margin-top: 1em" valign="top"><b>HISTORY</b></p> - -<p style="margin-left:8%;">A <b>tar</b> 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 -<b>pdtar</b> 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.</p> - -<p style="margin-left:8%; margin-top: 1em">This is a -complete re-implementation based on the libarchive(3) -library.</p> - -<p style="margin-top: 1em" valign="top"><b>BUGS</b></p> - -<p style="margin-left:8%;">This program follows ISO/IEC -9945-1:1996 (‘‘POSIX.1’’) for the -definition of the <b>−l</b> option. Note that GNU tar -prior to version 1.15 treated <b>−l</b> as a synonym -for the <b>−-one-file-system</b> option.</p> - -<p style="margin-left:8%; margin-top: 1em">The -<b>−C</b> <i>dir</i> option may differ from historic -implementations.</p> - -<p style="margin-left:8%; margin-top: 1em">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 gzip(1) and bzip2(1), -complain about the null padding when decompressing an -archive created by <b>tar</b>, although they still extract -it correctly.</p> - -<p style="margin-left:8%; margin-top: 1em">The compression -and decompression is implemented internally, so there may be -insignificant differences between the compressed output -generated by</p> - -<p style="margin-left:17%;"><b>tar −czf</b> <i>- -file</i></p> - -<p style="margin-left:8%;">and that generated by</p> - -<p style="margin-left:17%;"><b>tar −cf</b> <i>- -file</i> | <b>gzip</b></p> - -<p style="margin-left:8%; margin-top: 1em">The default -should be to read and write archives to the standard I/O -paths, but tradition (and POSIX) dictates otherwise.</p> - -<p style="margin-left:8%; margin-top: 1em">The <b>r</b> and -<b>u</b> modes require that the archive be uncompressed and -located in a regular file on disk. Other archives can be -modified using <b>c</b> mode with the <i>@archive-file</i> -extension.</p> - -<p style="margin-left:8%; margin-top: 1em">To archive a -file called <i>@foo</i> or <i>-foo</i> you must specify it -as <i>./@foo</i> or <i>./-foo</i>, respectively.</p> - -<p style="margin-left:8%; margin-top: 1em">In create mode, -a leading <i>./</i> is always removed. A leading <i>/</i> is -stripped unless the <b>−P</b> option is specified.</p> - -<p style="margin-left:8%; margin-top: 1em">There needs to -be better support for file selection on both create and -extract.</p> - -<p style="margin-left:8%; margin-top: 1em">There is not yet -any support for multi-volume archives or for archiving -sparse files.</p> - -<p style="margin-left:8%; margin-top: 1em">Converting -between dissimilar archive formats (such as tar and cpio) -using the <b>@</b><i>-</i> convention can cause hard link -information to be lost. (This is a consequence of the -incompatible ways that different archive formats store -hardlink information.)</p> - -<p style="margin-left:8%; margin-top: 1em">There are -alternative long options for many of the short options that -are deliberately not documented.</p> - - -<p style="margin-left:8%; margin-top: 1em">FreeBSD 8.0 -Oct 12, 2009 FreeBSD 8.0</p> -<hr> -</body> -</html> diff --git a/libarchive/libarchive-2.8.0/doc/html/cpio.5.html b/libarchive/libarchive-2.8.0/doc/html/cpio.5.html deleted file mode 100644 index 8d4768d..0000000 --- a/libarchive/libarchive-2.8.0/doc/html/cpio.5.html +++ /dev/null @@ -1,422 +0,0 @@ -<!-- Creator : groff version 1.19.2 --> -<!-- CreationDate: Thu Feb 4 20:36:34 2010 --> -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" -"http://www.w3.org/TR/html4/loose.dtd"> -<html> -<head> -<meta name="generator" content="groff -Thtml, see www.gnu.org"> -<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> -<meta name="Content-Style" content="text/css"> -<style type="text/css"> - p { margin-top: 0; margin-bottom: 0; } - pre { margin-top: 0; margin-bottom: 0; } - table { margin-top: 0; margin-bottom: 0; } -</style> -<title></title> -</head> -<body> - -<hr> - - -<p valign="top">CPIO(5) FreeBSD File Formats Manual -CPIO(5)</p> - -<p style="margin-top: 1em" valign="top"><b>NAME</b></p> - -<p style="margin-left:8%;"><b>cpio</b> — format of -cpio archive files</p> - - -<p style="margin-top: 1em" valign="top"><b>DESCRIPTION</b></p> - -<p style="margin-left:8%;">The <b>cpio</b> archive format -collects any number of files, directories, and other file -system objects (symbolic links, device nodes, etc.) into a -single stream of bytes.</p> - -<p style="margin-left:8%; margin-top: 1em"><b>General -Format</b> <br> -Each file system object in a <b>cpio</b> 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 <i>struct stat</i>. (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!!!’’.</p> - -<p style="margin-left:8%; margin-top: 1em"><b>PWB -format</b> <br> -XXX Any documentation of the original PWB/UNIX 1.0 format? -XXX</p> - -<p style="margin-left:8%; margin-top: 1em"><b>Old Binary -Format</b> <br> -The old binary <b>cpio</b> format stores numbers as 2-byte -and 4-byte binary values. Each entry begins with a header in -the following format:</p> - -<p style="margin-left:17%; margin-top: 1em">struct -header_old_cpio { <br> -unsigned short c_magic; <br> -unsigned short c_dev; <br> -unsigned short c_ino; <br> -unsigned short c_mode; <br> -unsigned short c_uid; <br> -unsigned short c_gid; <br> -unsigned short c_nlink; <br> -unsigned short c_rdev;</p> - -<table width="100%" border=0 rules="none" frame="void" - cellspacing="0" cellpadding="0"> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">unsigned short c_mtime[2];</p></td> -<td width="58%"> -</td> -</table> - -<p style="margin-left:17%;">unsigned short c_namesize;</p> - -<table width="100%" border=0 rules="none" frame="void" - cellspacing="0" cellpadding="0"> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="71%"> - - -<p valign="top">unsigned short c_filesize[2];</p></td> -</table> - -<p style="margin-left:17%;">};</p> - -<p style="margin-left:8%; margin-top: 1em">The <i>unsigned -short</i> fields here are 16-bit integer values; the -<i>unsigned int</i> fields are 32-bit integer values. The -fields are as follows</p> - -<p style="margin-top: 1em" valign="top"><i>magic</i></p> - -<p style="margin-left:20%; margin-top: 1em">The integer -value octal 070707. This value can be used to determine -whether this archive is written with little-endian or -big-endian integers.</p> - -<p style="margin-top: 1em" valign="top"><i>dev</i>, -<i>ino</i></p> - -<p style="margin-left:20%;">The device and inode numbers -from the disk. These are used by programs that read -<b>cpio</b> archives to determine when two entries refer to -the same file. Programs that synthesize <b>cpio</b> archives -should be careful to set these to distinct values for each -entry.</p> - -<p style="margin-top: 1em" valign="top"><i>mode</i></p> - -<p style="margin-left:20%; margin-top: 1em">The mode -specifies both the regular permissions and the file type. It -consists of several bit fields as follows:</p> - -<p valign="top">0170000</p> - -<p style="margin-left:34%; margin-top: 1em">This masks the -file type bits.</p> - -<p valign="top">0140000</p> - -<p style="margin-left:34%; margin-top: 1em">File type value -for sockets.</p> - -<p valign="top">0120000</p> - -<p style="margin-left:34%; margin-top: 1em">File type value -for symbolic links. For symbolic links, the link body is -stored as file data.</p> - -<p valign="top">0100000</p> - -<p style="margin-left:34%; margin-top: 1em">File type value -for regular files.</p> - -<p valign="top">0060000</p> - -<p style="margin-left:34%; margin-top: 1em">File type value -for block special devices.</p> - -<p valign="top">0040000</p> - -<p style="margin-left:34%; margin-top: 1em">File type value -for directories.</p> - -<p valign="top">0020000</p> - -<p style="margin-left:34%; margin-top: 1em">File type value -for character special devices.</p> - -<p valign="top">0010000</p> - -<p style="margin-left:34%; margin-top: 1em">File type value -for named pipes or FIFOs.</p> - -<p valign="top">0004000</p> - -<p style="margin-left:34%; margin-top: 1em">SUID bit.</p> - -<p valign="top">0002000</p> - -<p style="margin-left:34%; margin-top: 1em">SGID bit.</p> - -<p valign="top">0001000</p> - -<p style="margin-left:34%; margin-top: 1em">Sticky bit. On -some systems, this modifies the behavior of executables -and/or directories.</p> - -<p valign="top">0000777</p> - -<p style="margin-left:34%; margin-top: 1em">The lower 9 -bits specify read/write/execute permissions for world, -group, and user following standard POSIX conventions.</p> - -<p style="margin-top: 1em" valign="top"><i>uid</i>, -<i>gid</i></p> - -<p style="margin-left:20%;">The numeric user id and group -id of the owner.</p> - -<p style="margin-top: 1em" valign="top"><i>nlink</i></p> - -<p style="margin-left:20%; margin-top: 1em">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.</p> - -<p style="margin-top: 1em" valign="top"><i>rdev</i></p> - -<p style="margin-left:20%; margin-top: 1em">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.</p> - -<p style="margin-top: 1em" valign="top"><i>mtime</i></p> - -<p style="margin-left:20%; margin-top: 1em">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.</p> - - -<p style="margin-top: 1em" valign="top"><i>namesize</i></p> - -<p style="margin-left:20%;">The number of bytes in the -pathname that follows the header. This count includes the -trailing NUL byte.</p> - - -<p style="margin-top: 1em" valign="top"><i>filesize</i></p> - -<p style="margin-left:20%;">The size of the file. Note that -this archive format is limited to four gigabyte file sizes. -See <i>mtime</i> above for a description of the storage of -four-byte integers.</p> - -<p style="margin-left:8%; margin-top: 1em">The pathname -immediately follows the fixed header. If the <b>namesize</b> -is odd, an additional NUL byte is added after the pathname. -The file data is then appended, padded with NUL bytes to an -even length.</p> - -<p style="margin-left:8%; margin-top: 1em">Hardlinked files -are not given special treatment; the full file contents are -included with each copy of the file.</p> - -<p style="margin-left:8%; margin-top: 1em"><b>Portable -ASCII Format</b> <br> -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.</p> - -<p style="margin-left:17%; margin-top: 1em">struct -cpio_odc_header { <br> -char c_magic[6]; <br> -char c_dev[6]; <br> -char c_ino[6]; <br> -char c_mode[6]; <br> -char c_uid[6]; <br> -char c_gid[6]; <br> -char c_nlink[6]; <br> -char c_rdev[6]; <br> -char c_mtime[11]; <br> -char c_namesize[6]; <br> -char c_filesize[11]; <br> -};</p> - -<p style="margin-left:8%; margin-top: 1em">The fields are -identical to those in the old binary format. The name and -file body follow the fixed header. Unlike the old binary -format, there is no additional padding after the pathname or -file contents. If the files being archived are themselves -entirely ASCII, then the resulting archive will be entirely -ASCII, except for the NUL byte that terminates the name -field.</p> - -<p style="margin-left:8%; margin-top: 1em"><b>New ASCII -Format</b> <br> -The "new" ASCII format uses 8-byte hexadecimal -fields for all numbers and separates device numbers into -separate fields for major and minor numbers.</p> - -<p style="margin-left:17%; margin-top: 1em">struct -cpio_newc_header { <br> -char c_magic[6]; <br> -char c_ino[8]; <br> -char c_mode[8]; <br> -char c_uid[8]; <br> -char c_gid[8]; <br> -char c_nlink[8]; <br> -char c_mtime[8]; <br> -char c_filesize[8]; <br> -char c_devmajor[8]; <br> -char c_devminor[8]; <br> -char c_rdevmajor[8]; <br> -char c_rdevminor[8]; <br> -char c_namesize[8]; <br> -char c_check[8]; <br> -};</p> - -<p style="margin-left:8%; margin-top: 1em">Except as -specified below, the fields here match those specified for -the old binary format above.</p> - -<p style="margin-top: 1em" valign="top"><i>magic</i></p> - -<p style="margin-left:20%; margin-top: 1em">The string -‘‘070701’’.</p> - -<p style="margin-top: 1em" valign="top"><i>check</i></p> - -<p style="margin-left:20%; margin-top: 1em">This field is -always set to zero by writers and ignored by readers. See -the next section for more details.</p> - -<p style="margin-left:8%; margin-top: 1em">The pathname is -followed by NUL bytes so that the total size of the fixed -header plus pathname is a multiple of four. Likewise, the -file data is padded to a multiple of four bytes. Note that -this format supports only 4 gigabyte files (unlike the older -ASCII format, which supports 8 gigabyte files).</p> - -<p style="margin-left:8%; margin-top: 1em">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.</p> - -<p style="margin-left:8%; margin-top: 1em"><b>New CRC -Format</b> <br> -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 -<i>check</i> 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.</p> - -<p style="margin-left:8%; margin-top: 1em"><b>HP -variants</b> <br> -The <b>cpio</b> implementation distributed with HPUX used -XXXX but stored device numbers differently XXX.</p> - -<p style="margin-left:8%; margin-top: 1em"><b>Other -Extensions and Variants</b> <br> -Sun Solaris uses additional file types to store extended -file data, including ACLs and extended attributes, as -special entries in cpio archives.</p> - -<p style="margin-left:8%; margin-top: 1em">XXX Others? -XXX</p> - -<p style="margin-top: 1em" valign="top"><b>BUGS</b></p> - -<p style="margin-left:8%;">The -‘‘CRC’’ format is mis-named, as it -uses a simple checksum and not a cyclic redundancy -check.</p> - -<p style="margin-left:8%; margin-top: 1em">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.</p> - -<p style="margin-left:8%; margin-top: 1em">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.</p> - -<p style="margin-left:8%; margin-top: 1em">The new ASCII -format is limited to 4 gigabyte file sizes.</p> - -<p style="margin-left:8%; margin-top: 1em">None of the cpio -formats store user or group names, which are essential when -moving files between systems with dissimilar user or group -numbering.</p> - -<p style="margin-left:8%; margin-top: 1em">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.</p> - -<p style="margin-top: 1em" valign="top"><b>SEE ALSO</b></p> - -<p style="margin-left:8%;">cpio(1), tar(5)</p> - - -<p style="margin-top: 1em" valign="top"><b>STANDARDS</b></p> - -<p style="margin-left:8%;">The <b>cpio</b> 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 portable ASCII format -is currently part of the specification for the pax(1) -utility.</p> - -<p style="margin-top: 1em" valign="top"><b>HISTORY</b></p> - -<p style="margin-left:8%;">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</p> - - -<p style="margin-left:8%; margin-top: 1em">FreeBSD 8.0 -October 5, 2007 FreeBSD 8.0</p> -<hr> -</body> -</html> diff --git a/libarchive/libarchive-2.8.0/doc/html/libarchive-formats.5.html b/libarchive/libarchive-2.8.0/doc/html/libarchive-formats.5.html deleted file mode 100644 index db26b1e..0000000 --- a/libarchive/libarchive-2.8.0/doc/html/libarchive-formats.5.html +++ /dev/null @@ -1,375 +0,0 @@ -<!-- Creator : groff version 1.19.2 --> -<!-- CreationDate: Thu Feb 4 20:36:35 2010 --> -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" -"http://www.w3.org/TR/html4/loose.dtd"> -<html> -<head> -<meta name="generator" content="groff -Thtml, see www.gnu.org"> -<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> -<meta name="Content-Style" content="text/css"> -<style type="text/css"> - p { margin-top: 0; margin-bottom: 0; } - pre { margin-top: 0; margin-bottom: 0; } - table { margin-top: 0; margin-bottom: 0; } -</style> -<title></title> -</head> -<body> - -<hr> - - -<p valign="top">libarchive-formats(5) FreeBSD File Formats -Manual libarchive-formats(5)</p> - -<p style="margin-top: 1em" valign="top"><b>NAME</b></p> - -<p style="margin-left:8%;"><b>libarchive-formats</b> -— archive formats supported by the libarchive -library</p> - - -<p style="margin-top: 1em" valign="top"><b>DESCRIPTION</b></p> - -<p style="margin-left:8%;">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.</p> - -<p style="margin-left:8%; margin-top: 1em">The following -provides a brief description of each format supported by -libarchive, with some information about recognized -extensions or limitations of the current library support. -Note that just because a format is supported by libarchive -does not imply that a program that uses libarchive will -support that format. Applications that use libarchive -specify which formats they wish to support, though many -programs do use libarchive convenience functions to enable -all supported formats.</p> - -<p style="margin-left:8%; margin-top: 1em"><b>Tar -Formats</b> <br> -The libarchive(3) library can read most tar archives. -However, it only writes POSIX-standard -‘‘ustar’’ and ‘‘pax -interchange’’ formats.</p> - -<p style="margin-left:8%; margin-top: 1em">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.</p> - -<p style="margin-top: 1em" valign="top"><b>gnutar</b></p> - -<p style="margin-left:20%; margin-top: 1em">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.</p> - -<p style="margin-top: 1em" valign="top"><b>pax</b></p> - -<p style="margin-left:20%; margin-top: 1em">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 immediately before each regular entry. The -presence of these additional entries is the only difference -between pax interchange format and the older ustar format. -The extended attributes are of unlimited length and are -stored as UTF-8 Unicode strings. Keywords defined in the -standard are in all lowercase; vendors are allowed to define -custom keys by preceding them with the vendor name in all -uppercase. When writing pax archives, libarchive uses many -of the SCHILY keys defined by Joerg Schilling’s -‘‘star’’ archiver and a few -LIBARCHIVE keys. The libarchive library can read most of the -SCHILY keys and most of the GNU keys introduced by GNU tar. -It silently ignores any keywords that it does not -understand.</p> - -<p style="margin-top: 1em" valign="top"><b>restricted -pax</b></p> - -<p style="margin-left:20%;">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 -<i>PaxHeader</i> directories.</p> - -<p style="margin-top: 1em" valign="top"><b>ustar</b></p> - -<p style="margin-left:20%; margin-top: 1em">The libarchive -library can both read and write this format. This format has -the following limitations:</p> - -<p valign="top"><b>•</b></p> - -<p style="margin-left:26%;">Device major and minor numbers -are limited to 21 bits. Nodes with larger numbers will not -be added to the archive.</p> - -<p valign="top"><b>•</b></p> - -<p style="margin-left:26%;">Path names in the archive are -limited to 255 bytes. (Shorter if there is no / character in -exactly the right place.)</p> - -<p valign="top"><b>•</b></p> - -<p style="margin-left:26%;">Symbolic links and hard links -are stored in the archive with the name of the referenced -file. This name is limited to 100 bytes.</p> - -<p valign="top"><b>•</b></p> - -<p style="margin-left:26%;">Extended attributes, file -flags, and other extended security information cannot be -stored.</p> - -<p valign="top"><b>•</b></p> - -<p style="margin-left:26%;">Archive entries are limited to -8 gigabytes in size.</p> - -<p style="margin-left:20%;">Note that the pax interchange -format has none of these restrictions.</p> - -<p style="margin-left:8%; margin-top: 1em">The libarchive -library also reads a variety of commonly-used extensions to -the basic tar format. These extensions are recognized -automatically whenever they appear.</p> - -<p style="margin-top: 1em" valign="top">Numeric -extensions.</p> - -<p style="margin-left:20%;">The POSIX standards require -fixed-length numeric fields to be written with some -character position reserved for terminators. Libarchive -allows these fields to be written without terminator -characters. This extends the allowable range; in particular, -ustar archives with this extension can support entries up to -64 gigabytes in size. Libarchive also recognizes base-256 -values in most numeric fields. This essentially removes all -limitations on file size, modification time, and device -numbers.</p> - -<p style="margin-top: 1em" valign="top">Solaris -extensions</p> - -<p style="margin-left:20%;">Libarchive recognizes ACL and -extended attribute records written by Solaris tar. -Currently, libarchive only has support for old-style ACLs; -the newer NFSv4 ACLs are recognized but discarded.</p> - -<p style="margin-left:8%; margin-top: 1em">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.</p> - -<p style="margin-left:8%; margin-top: 1em"><b>Cpio -Formats</b> <br> -The libarchive library can read a number of common cpio -variants and can write ‘‘odc’’ and -‘‘newc’’ format archives. A cpio -archive stores each entry as a fixed-size header followed by -a variable-length filename and variable-length data. Unlike -the tar format, the cpio format does only minimal padding of -the header or file data. There are several cpio variants, -which differ primarily in how they store the initial header: -some store the values as octal or hexadecimal numbers in -ASCII, others as binary values of varying byte order and -length.</p> - -<p style="margin-top: 1em" valign="top"><b>binary</b></p> - -<p style="margin-left:20%; margin-top: 1em">The libarchive -library transparently reads both big-endian and -little-endian variants of the original binary cpio format. -This format used 32-bit binary values for file size and -mtime, and 16-bit binary values for the other fields.</p> - -<p style="margin-top: 1em" valign="top"><b>odc</b></p> - -<p style="margin-left:20%; margin-top: 1em">The libarchive -library can both read and write this POSIX-standard format, -which is officially known as the ‘‘cpio -interchange format’’ or the -‘‘octet-oriented cpio archive -format’’ and sometimes unofficially referred to -as the ‘‘old character format’’. -This format stores the header contents as octal values in -ASCII. It is standard, portable, and immune from byte-order -confusion. File sizes and mtime are limited to 33 bits (8GB -file size), other fields are limited to 18 bits.</p> - -<p style="margin-top: 1em" valign="top"><b>SVR4</b></p> - -<p style="margin-left:20%; margin-top: 1em">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.</p> - -<p style="margin-left:8%; margin-top: 1em">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 <b>find</b> and -<b>cpio</b> 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.</p> - -<p style="margin-left:8%; margin-top: 1em"><b>Shar -Formats</b> <br> -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:</p> - -<p style="margin-top: 1em" valign="top"><b>shar</b></p> - -<p style="margin-left:20%; margin-top: 1em">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. However, 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.</p> - - -<p style="margin-top: 1em" valign="top"><b>shardump</b></p> - -<p style="margin-left:20%;">This format is similar to shar -but encodes files using uuencode(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.</p> - -<p style="margin-left:8%; margin-top: 1em"><b>ISO9660 -format</b> <br> -Libarchive can read and extract from files containing -ISO9660-compliant CDROM images. In many cases, this can -remove the need to burn a physical CDROM just in order to -read the files contained in an ISO9660 image. It also avoids -security and complexity issues that come with virtual mounts -and loopback devices. Libarchive supports the most common -Rockridge extensions and has partial support for Joliet -extensions. If both extensions are present, the Joliet -extensions will be used and the Rockridge extensions will be -ignored. In particular, this can create problems with -hardlinks and symlinks, which are supported by Rockridge but -not by Joliet.</p> - -<p style="margin-left:8%; margin-top: 1em"><b>Zip -format</b> <br> -Libarchive can read and write zip format archives that have -uncompressed entries and entries compressed with the -‘‘deflate’’ algorithm. Older zip -compression algorithms are not supported. It can extract jar -archives, archives that use Zip64 extensions and many -self-extracting zip archives. Libarchive reads Zip archives -as they are being streamed, which allows it to read archives -of arbitrary size. It currently does not use the central -directory; this limits libarchive’s ability to support -some self-extracting archives and ones that have been -modified in certain ways.</p> - -<p style="margin-left:8%; margin-top: 1em"><b>Archive -(library) file format</b> <br> -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 standardised. There are -two common variants: the GNU format derived from SVR4, and -the BSD format, which first appeared in 4.4BSD. The two -differ primarily in their handling of filenames longer than -15 characters: the GNU/SVR4 variant writes a filename table -at the beginning of the archive; the BSD format stores each -long filename in an extension area adjacent to the entry. -Libarchive can read both extensions, including archives that -may include both types of long filenames. Programs using -libarchive can write GNU/SVR4 format if they provide a -filename table to be written into the archive before any of -the entries. Any entries whose names are not in the filename -table will be written using BSD-style long filenames. This -can cause problems for programs such as GNU ld that do not -support the BSD-style long filenames.</p> - -<p style="margin-left:8%; margin-top: 1em"><b>mtree</b> -<br> -Libarchive can read and write files in mtree(5) format. This -format is not a true archive format, but rather a textual -description of a file hierarchy in which each line specifies -the name of a file and provides specific metadata about that -file. Libarchive can read all of the keywords supported by -both the NetBSD and FreeBSD versions of mtree(1), although -many of the keywords cannot currently be stored in an -archive_entry object. When writing, libarchive supports use -of the archive_write_set_options(3) interface to specify -which keywords should be included in the output. If -libarchive was compiled with access to suitable -cryptographic libraries (such as the OpenSSL libraries), it -can compute hash entries such as <b>sha512</b> or <b>md5</b> -from file data being written to the mtree writer.</p> - -<p style="margin-left:8%; margin-top: 1em">When reading an -mtree file, libarchive will locate the corresponding files -on disk using the <b>contents</b> keyword if present or the -regular filename. If it can locate and open the file on -disk, it will use that to fill in any metadata that is -missing from the mtree file and will read the file contents -and return those to the program using libarchive. If it -cannot locate and open the file on disk, libarchive will -return an error for any attempt to read the entry body.</p> - -<p style="margin-top: 1em" valign="top"><b>SEE ALSO</b></p> - -<p style="margin-left:8%;">ar(1), cpio(1), mkisofs(1), -shar(1), tar(1), zip(1), zlib(3), cpio(5), mtree(5), -tar(5)</p> - - -<p style="margin-left:8%; margin-top: 1em">FreeBSD 8.0 -December 27, 2009 FreeBSD 8.0</p> -<hr> -</body> -</html> diff --git a/libarchive/libarchive-2.8.0/doc/html/libarchive.3.html b/libarchive/libarchive-2.8.0/doc/html/libarchive.3.html deleted file mode 100644 index f02d7cb..0000000 --- a/libarchive/libarchive-2.8.0/doc/html/libarchive.3.html +++ /dev/null @@ -1,329 +0,0 @@ -<!-- Creator : groff version 1.19.2 --> -<!-- CreationDate: Thu Feb 4 20:36:35 2010 --> -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" -"http://www.w3.org/TR/html4/loose.dtd"> -<html> -<head> -<meta name="generator" content="groff -Thtml, see www.gnu.org"> -<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> -<meta name="Content-Style" content="text/css"> -<style type="text/css"> - p { margin-top: 0; margin-bottom: 0; } - pre { margin-top: 0; margin-bottom: 0; } - table { margin-top: 0; margin-bottom: 0; } -</style> -<title></title> -</head> -<body> - -<hr> - - -<p valign="top">LIBARCHIVE(3) FreeBSD Library Functions -Manual LIBARCHIVE(3)</p> - -<p style="margin-top: 1em" valign="top"><b>NAME</b></p> - -<p style="margin-left:8%;"><b>libarchive</b> — -functions for reading and writing streaming archives</p> - -<p style="margin-top: 1em" valign="top"><b>LIBRARY</b></p> - -<p style="margin-left:8%;">Streaming Archive Library -(libarchive, −larchive)</p> - - -<p style="margin-top: 1em" valign="top"><b>OVERVIEW</b></p> - -<p style="margin-left:8%;">The <b>libarchive</b> 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.</p> - -<p style="margin-left:8%; margin-top: 1em">When reading an -archive, the library automatically detects the format and -the compression. The library currently has read support -for:</p> - -<p valign="top"><b>•</b></p> - -<p style="margin-left:14%;">old-style tar archives,</p> - -<p valign="top"><b>•</b></p> - -<p style="margin-left:14%;">most variants of the POSIX -‘‘ustar’’ format,</p> - -<p valign="top"><b>•</b></p> - -<p style="margin-left:14%;">the POSIX ‘‘pax -interchange’’ format,</p> - -<p valign="top"><b>•</b></p> - -<p style="margin-left:14%;">GNU-format tar archives,</p> - -<p valign="top"><b>•</b></p> - -<p style="margin-left:14%;">most common cpio archive -formats,</p> - -<p valign="top"><b>•</b></p> - -<p style="margin-left:14%;">ISO9660 CD images (with or -without RockRidge extensions),</p> - -<p valign="top"><b>•</b></p> - -<p style="margin-left:14%;">Zip archives.</p> - -<p style="margin-left:8%;">The library automatically -detects archives compressed with gzip(1), bzip2(1), or -compress(1) and decompresses them transparently.</p> - -<p style="margin-left:8%; margin-top: 1em">When writing an -archive, you can specify the compression to be used and the -format to use. The library can write</p> - -<p valign="top"><b>•</b></p> - -<p style="margin-left:14%;">POSIX-standard -‘‘ustar’’ archives,</p> - -<p valign="top"><b>•</b></p> - -<p style="margin-left:14%;">POSIX ‘‘pax -interchange format’’ archives,</p> - -<p valign="top"><b>•</b></p> - -<p style="margin-left:14%;">POSIX octet-oriented cpio -archives,</p> - -<p valign="top"><b>•</b></p> - -<p style="margin-left:14%;">two different variants of shar -archives.</p> - -<p style="margin-left:8%;">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) implementations 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.</p> - -<p style="margin-left:8%; margin-top: 1em">The read and -write APIs are accessed through the -<b>archive_read_XXX</b>() functions and the -<b>archive_write_XXX</b>() functions, respectively, and -either can be used independently of the other.</p> - -<p style="margin-left:8%; margin-top: 1em">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.</p> - -<p style="margin-top: 1em" valign="top"><b>READING AN -ARCHIVE</b></p> - -<p style="margin-left:8%;">To read an archive, you must -first obtain an initialized struct archive object from -<b>archive_read_new</b>(). You can then modify this object -for the desired operations with the various -<b>archive_read_set_XXX</b>() and -<b>archive_read_support_XXX</b>() functions. In particular, -you will need to invoke appropriate -<b>archive_read_support_XXX</b>() 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 <b>archive_read_support_compression_all</b>() -and <b>archive_read_support_format_all</b>() to enable -auto-detect for all formats and compression types currently -supported by the library.</p> - -<p style="margin-left:8%; margin-top: 1em">Once you have -prepared the struct archive object, you call -<b>archive_read_open</b>() 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, <i>FILE *</i> 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.</p> - -<p style="margin-left:8%; margin-top: 1em">Each archive -entry consists of a header followed by a certain amount of -data. You can obtain the next header with -<b>archive_read_next_header</b>(), which returns a pointer -to an 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 <b>archive_read_data</b>() (which works much like the -read(2) system call) to read this data from the archive. You -may prefer to use the higher-level -<b>archive_read_data_skip</b>(), which reads and discards -the data for this entry, -<b>archive_read_data_to_buffer</b>(), which reads the data -into an in-memory buffer, -<b>archive_read_data_to_file</b>(), which copies the data to -the provided file descriptor, or -<b>archive_read_extract</b>(), which recreates the specified -entry on disk and copies data from the archive. In -particular, note that <b>archive_read_extract</b>() 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.</p> - -<p style="margin-left:8%; margin-top: 1em">Once you have -finished reading data from the archive, you should call -<b>archive_read_close</b>() to close the archive, then call -<b>archive_read_finish</b>() to release all resources, -including all memory allocated by the library.</p> - -<p style="margin-left:8%; margin-top: 1em">The -archive_read(3) manual page provides more detailed calling -information for this API.</p> - -<p style="margin-top: 1em" valign="top"><b>WRITING AN -ARCHIVE</b></p> - -<p style="margin-left:8%;">You use a similar process to -write an archive. The <b>archive_write_new</b>() function -creates an archive object useful for writing, the various -<b>archive_write_set_XXX</b>() functions are used to set -parameters for writing the archive, and -<b>archive_write_open</b>() completes the setup and opens -the archive for writing.</p> - -<p style="margin-left:8%; margin-top: 1em">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 <i>struct -stat</i> with a valid <i>st_mode</i> field, which specifies -the type of object and <i>st_size</i> field, which specifies -the size of the data portion of the object. The -<b>archive_write_header</b>() function actually writes the -header data to the archive. You can then use -<b>archive_write_data</b>() to write the actual data.</p> - -<p style="margin-left:8%; margin-top: 1em">After all -entries have been written, use the -<b>archive_write_finish</b>() function to release all -resources.</p> - -<p style="margin-left:8%; margin-top: 1em">The -archive_write(3) manual page provides more detailed calling -information for this API.</p> - - -<p style="margin-top: 1em" valign="top"><b>DESCRIPTION</b></p> - -<p style="margin-left:8%;">Detailed descriptions of each -function are provided by the corresponding manual pages.</p> - -<p style="margin-left:8%; margin-top: 1em">All of the -functions utilize an opaque struct archive datatype that -provides access to the archive contents.</p> - -<p style="margin-left:8%; margin-top: 1em">The struct -archive_entry structure contains a complete description of a -single archive entry. It uses an opaque interface that is -fully documented in archive_entry(3).</p> - -<p style="margin-left:8%; margin-top: 1em">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 <i>PATH_MAX</i>.</p> - -<p style="margin-top: 1em" valign="top"><b>RETURN -VALUES</b></p> - -<p style="margin-left:8%;">Most functions return zero on -success, non-zero on error. The return value indicates the -general severity of the error, ranging from -<b>ARCHIVE_WARN</b>, which indicates a minor problem that -should probably be reported to the user, to -<b>ARCHIVE_FATAL</b>, which indicates a serious problem that -will prevent any further operations on this archive. On -error, the <b>archive_errno</b>() function can be used to -retrieve a numeric error code (see errno(2)). The -<b>archive_error_string</b>() returns a textual error -message suitable for display.</p> - - -<p style="margin-left:8%; margin-top: 1em"><b>archive_read_new</b>() -and <b>archive_write_new</b>() return pointers to an -allocated and initialized struct archive object.</p> - - -<p style="margin-left:8%; margin-top: 1em"><b>archive_read_data</b>() -and <b>archive_write_data</b>() 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 <b>archive_errno</b>() -and <b>archive_error_string</b>() functions can be used to -obtain more information.</p> - - -<p style="margin-top: 1em" valign="top"><b>ENVIRONMENT</b></p> - -<p style="margin-left:8%;">There are character set -conversions within the archive_entry(3) functions that are -impacted by the currently-selected locale.</p> - -<p style="margin-top: 1em" valign="top"><b>SEE ALSO</b></p> - -<p style="margin-left:8%;">tar(1), archive_entry(3), -archive_read(3), archive_util(3), archive_write(3), -tar(5)</p> - -<p style="margin-top: 1em" valign="top"><b>HISTORY</b></p> - -<p style="margin-left:8%;">The <b>libarchive</b> library -first appeared in FreeBSD 5.3.</p> - -<p style="margin-top: 1em" valign="top"><b>AUTHORS</b></p> - -<p style="margin-left:8%;">The <b>libarchive</b> library -was written by Tim Kientzle -⟨kientzle@acm.org⟩.</p> - -<p style="margin-top: 1em" valign="top"><b>BUGS</b></p> - -<p style="margin-left:8%;">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.</p> - -<p style="margin-left:8%; margin-top: 1em">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 support large device numbers.</p> - - -<p style="margin-left:8%; margin-top: 1em">FreeBSD 8.0 -August 19, 2006 FreeBSD 8.0</p> -<hr> -</body> -</html> diff --git a/libarchive/libarchive-2.8.0/doc/html/libarchive_internals.3.html b/libarchive/libarchive-2.8.0/doc/html/libarchive_internals.3.html deleted file mode 100644 index 31c716a..0000000 --- a/libarchive/libarchive-2.8.0/doc/html/libarchive_internals.3.html +++ /dev/null @@ -1,381 +0,0 @@ -<!-- Creator : groff version 1.19.2 --> -<!-- CreationDate: Thu Feb 4 20:36:36 2010 --> -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" -"http://www.w3.org/TR/html4/loose.dtd"> -<html> -<head> -<meta name="generator" content="groff -Thtml, see www.gnu.org"> -<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> -<meta name="Content-Style" content="text/css"> -<style type="text/css"> - p { margin-top: 0; margin-bottom: 0; } - pre { margin-top: 0; margin-bottom: 0; } - table { margin-top: 0; margin-bottom: 0; } -</style> -<title></title> -</head> -<body> - -<hr> - - -<p valign="top">LIBARCHIVE(3) FreeBSD Library Functions -Manual LIBARCHIVE(3)</p> - -<p style="margin-top: 1em" valign="top"><b>NAME</b></p> - -<p style="margin-left:8%;"><b>libarchive_internals</b> -— description of libarchive internal interfaces</p> - - -<p style="margin-top: 1em" valign="top"><b>OVERVIEW</b></p> - -<p style="margin-left:8%;">The <b>libarchive</b> 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.</p> - -<p style="margin-top: 1em" valign="top"><b>GENERAL -ARCHITECTURE</b></p> - -<p style="margin-left:8%;">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.)</p> - -<p style="margin-left:8%; margin-top: 1em">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.</p> - -<p style="margin-left:8%; margin-top: 1em">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.</p> - -<p style="margin-top: 1em" valign="top"><b>READ -ARCHITECTURE</b></p> - -<p style="margin-left:8%;">From the outside, clients use -the archive_read(3) API to manipulate an <b>archive</b> -object to read entries and bodies from an archive stream. -Internally, the <b>archive</b> object is cast to an -<b>archive_read</b> 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 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 <b>archive_entry</b> 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.)</p> - -<p style="margin-left:8%; margin-top: 1em"><b>I/O Layer and -Client Callbacks</b> <br> -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.</p> - -<p style="margin-left:8%; margin-top: 1em">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.</p> - -<p style="margin-left:8%; margin-top: 1em">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.</p> - -<p style="margin-left:8%; margin-top: 1em">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.</p> - - -<p style="margin-left:8%; margin-top: 1em"><b>Decompresssion -Layer</b> <br> -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.</p> - -<p style="margin-left:8%; margin-top: 1em">A subsequent -call to the <b>consume</b>() function advances the read -pointer. Note that data returned from a <b>read_ahead</b>() -call is guaranteed to remain in place until the next call to -<b>read_ahead</b>(). Intervening calls to <b>consume</b>() -should not cause the data to move.</p> - -<p style="margin-left:8%; margin-top: 1em">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.</p> - -<p style="margin-left:8%; margin-top: 1em">A decompression -handler has a specific lifecycle:</p> - -<p valign="top">Registration/Configuration</p> - -<p style="margin-left:20%;">When the client invokes the -public support function, the decompression handler invokes -the internal <b>__archive_read_register_compression</b>() -function to provide bid and initialization functions. This -function returns <b>NULL</b> on error or else a pointer to a -<b>struct decompressor_t</b>. This structure contains a -<i>void * config</i> slot that can be used for storing any -customization information.</p> - -<p valign="top">Bid</p> - -<p style="margin-left:20%; margin-top: 1em">The bid -function is invoked with a pointer and size of a block of -data. The decompressor can access its config data through -the <i>decompressor</i> element of the <b>archive_read</b> -object. The bid function is otherwise stateless. In -particular, it must not perform any I/O operations.</p> - -<p style="margin-left:20%; margin-top: 1em">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.)</p> - -<p valign="top">Initialize</p> - -<p style="margin-left:20%;">The winning bidder will have -its init function called. This function should initialize -the remaining slots of the <i>struct decompressor_t</i> -object pointed to by the <i>decompressor</i> element of the -<i>archive_read</i> object. In particular, it should -allocate any working data it needs in the <i>data</i> 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.</p> - -<p valign="top">Satisfy I/O requests</p> - -<p style="margin-left:20%;">The format handler will invoke -the <i>read_ahead</i>, <i>consume</i>, and <i>skip</i> -functions as needed.</p> - -<p valign="top">Finish</p> - -<p style="margin-left:20%; margin-top: 1em">The finish -method is called only once when the archive is closed. It -should release anything stored in the <i>data</i> and -<i>config</i> slots of the <i>decompressor</i> object. It -should not invoke the client close callback.</p> - -<p style="margin-left:8%; margin-top: 1em"><b>Format -Layer</b> <br> -The read formats have a similar lifecycle to the -decompression handlers:</p> - -<p valign="top">Registration</p> - -<p style="margin-left:20%;">Allocate your private data and -initialize your pointers.</p> - -<p valign="top">Bid</p> - -<p style="margin-left:20%; margin-top: 1em">Formats bid by -invoking the <b>read_ahead</b>() decompression method but -not calling the <b>consume</b>() 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.)</p> - -<p valign="top">Read header</p> - -<p style="margin-left:20%;">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.</p> - -<p valign="top">Read Data</p> - -<p style="margin-left:20%;">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.</p> - -<p valign="top">Skip All Data</p> - -<p style="margin-left:20%;">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 <b>data_skip</b>() function.</p> - -<p valign="top">Cleanup</p> - -<p style="margin-left:20%;">On cleanup, the format should -release all of its allocated memory.</p> - -<p style="margin-left:8%; margin-top: 1em"><b>API Layer</b> -<br> -XXX to do XXX</p> - -<p style="margin-top: 1em" valign="top"><b>WRITE -ARCHITECTURE</b></p> - -<p style="margin-left:8%;">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.</p> - -<p style="margin-left:8%; margin-top: 1em"><b>I/O Layer and -Client Callbacks</b> <br> -XXX To be written XXX</p> - -<p style="margin-left:8%; margin-top: 1em"><b>Compression -Layer</b> <br> -XXX To be written XXX</p> - -<p style="margin-left:8%; margin-top: 1em"><b>Format -Layer</b> <br> -XXX To be written XXX</p> - -<p style="margin-left:8%; margin-top: 1em"><b>API Layer</b> -<br> -XXX To be written XXX</p> - -<p style="margin-top: 1em" valign="top"><b>WRITE_DISK -ARCHITECTURE</b></p> - -<p style="margin-left:8%;">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.</p> - -<p style="margin-top: 1em" valign="top"><b>GENERAL -SERVICES</b></p> - -<p style="margin-left:8%;">The <b>archive_read</b>, -<b>archive_write</b>, and <b>archive_write_disk</b> objects -all contain an initial <b>archive</b> 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 <b>archive</b> 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.</p> - -<p style="margin-top: 1em" valign="top"><b>MISCELLANEOUS -NOTES</b></p> - -<p style="margin-left:8%;">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.</p> - -<p style="margin-left:8%; margin-top: 1em">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.</p> - -<p style="margin-left:8%; margin-top: 1em">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.</p> - -<p style="margin-top: 1em" valign="top"><b>SEE ALSO</b></p> - -<p style="margin-left:8%;">archive(3), archive_entry(3), -archive_read(3), archive_write(3), archive_write_disk(3)</p> - -<p style="margin-top: 1em" valign="top"><b>HISTORY</b></p> - -<p style="margin-left:8%;">The <b>libarchive</b> library -first appeared in FreeBSD 5.3.</p> - -<p style="margin-top: 1em" valign="top"><b>AUTHORS</b></p> - -<p style="margin-left:8%;">The <b>libarchive</b> library -was written by Tim Kientzle -⟨kientzle@acm.org⟩.</p> - -<p style="margin-top: 1em" valign="top"><b>BUGS</b></p> - -<p style="margin-left:8%;">FreeBSD 8.0 April 16, -2007 FreeBSD 8.0</p> -<hr> -</body> -</html> diff --git a/libarchive/libarchive-2.8.0/doc/html/mtree.5.html b/libarchive/libarchive-2.8.0/doc/html/mtree.5.html deleted file mode 100644 index 674edef..0000000 --- a/libarchive/libarchive-2.8.0/doc/html/mtree.5.html +++ /dev/null @@ -1,339 +0,0 @@ -<!-- Creator : groff version 1.19.2 --> -<!-- CreationDate: Thu Feb 4 20:36:37 2010 --> -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" -"http://www.w3.org/TR/html4/loose.dtd"> -<html> -<head> -<meta name="generator" content="groff -Thtml, see www.gnu.org"> -<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> -<meta name="Content-Style" content="text/css"> -<style type="text/css"> - p { margin-top: 0; margin-bottom: 0; } - pre { margin-top: 0; margin-bottom: 0; } - table { margin-top: 0; margin-bottom: 0; } -</style> -<title></title> -</head> -<body> - -<hr> - - -<p valign="top">MTREE(5) FreeBSD File Formats Manual -MTREE(5)</p> - -<p style="margin-top: 1em" valign="top"><b>NAME</b></p> - -<p style="margin-left:8%;"><b>mtree</b> — format of -mtree dir hierarchy files</p> - - -<p style="margin-top: 1em" valign="top"><b>DESCRIPTION</b></p> - -<p style="margin-left:8%;">The <b>mtree</b> format is a -textual format that describes a collection of filesystem -objects. Such files are typically used to create or verify -directory hierarchies.</p> - -<p style="margin-left:8%; margin-top: 1em"><b>General -Format</b> <br> -An <b>mtree</b> file consists of a series of lines, each -providing information about a single filesystem object. -Leading whitespace is always ignored.</p> - -<p style="margin-left:8%; margin-top: 1em">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.</p> - -<p style="margin-left:8%; margin-top: 1em">Each line is -interpreted independently as one of the following types:</p> - -<p style="margin-top: 1em" valign="top">Signature</p> - -<p style="margin-left:26%; margin-top: 1em">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’’.</p> - -<p style="margin-top: 1em" valign="top">Blank</p> - -<p style="margin-left:26%; margin-top: 1em">Blank lines are -ignored.</p> - -<p style="margin-top: 1em" valign="top">Comment</p> - -<p style="margin-left:26%; margin-top: 1em">Lines beginning -with <b>#</b> are ignored.</p> - -<p style="margin-top: 1em" valign="top">Special</p> - -<p style="margin-left:26%; margin-top: 1em">Lines beginning -with <b>/</b> are special commands that influence the -interpretation of later lines.</p> - -<p style="margin-top: 1em" valign="top">Relative</p> - -<p style="margin-left:26%; margin-top: 1em">If the first -whitespace-delimited word has no <b>/</b> characters, it is -the name of a file in the current directory. Any relative -entry that describes a directory changes the current -directory.</p> - -<p style="margin-top: 1em" valign="top">dot-dot</p> - -<p style="margin-left:26%; margin-top: 1em">As a special -case, a relative entry with the filename <i>..</i> changes -the current directory to the parent directory. Options on -dot-dot entries are always ignored.</p> - -<p style="margin-top: 1em" valign="top">Full</p> - -<p style="margin-left:26%; margin-top: 1em">If the first -whitespace-delimited word has a <b>/</b> 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.</p> - -<p style="margin-left:8%; margin-top: 1em">Some tools that -process <b>mtree</b> 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.</p> - -<p style="margin-left:8%; margin-top: 1em"><b>Special -commands</b> <br> -Two special commands are currently defined:</p> - -<p style="margin-top: 1em" valign="top"><b>/set</b></p> - -<p style="margin-left:26%; margin-top: 1em">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.</p> - -<p style="margin-top: 1em" valign="top"><b>/unset</b></p> - -<p style="margin-left:26%; margin-top: 1em">This command -removes any default value set by a previous <b>/set</b> -command. It is followed on the same line by one or more -keywords separated by whitespace.</p> - -<p style="margin-left:8%; margin-top: 1em"><b>Keywords</b> -<br> -After the filename, a full or relative entry consists of -zero or more whitespace-separated keyword definitions. Each -such definition consists of a key from the following list -immediately followed by an ’=’ sign and a value. -Software programs reading mtree files should warn about -unrecognized keywords.</p> - -<p style="margin-left:8%; margin-top: 1em">Currently -supported keywords are as follows:</p> - -<p style="margin-top: 1em" valign="top"><b>cksum</b></p> - -<p style="margin-left:26%; margin-top: 1em">The checksum of -the file using the default algorithm specified by the -cksum(1) utility.</p> - - -<p style="margin-top: 1em" valign="top"><b>contents</b></p> - -<p style="margin-left:26%; margin-top: 1em">The full -pathname of a file that holds the contents of this file.</p> - -<p style="margin-top: 1em" valign="top"><b>flags</b></p> - -<p style="margin-left:26%; margin-top: 1em">The file flags -as a symbolic name. See chflags(1) for information on these -names. If no flags are to be set the string -‘‘none’’ may be used to override the -current default.</p> - -<p style="margin-top: 1em" valign="top"><b>gid</b></p> - -<p style="margin-left:26%; margin-top: 1em">The file group -as a numeric value.</p> - -<p style="margin-top: 1em" valign="top"><b>gname</b></p> - -<p style="margin-left:26%; margin-top: 1em">The file group -as a symbolic name.</p> - -<p style="margin-top: 1em" valign="top"><b>ignore</b></p> - -<p style="margin-left:26%; margin-top: 1em">Ignore any file -hierarchy below this file.</p> - -<p style="margin-top: 1em" valign="top"><b>link</b></p> - -<p style="margin-left:26%; margin-top: 1em">The target of -the symbolic link when type=link.</p> - -<p style="margin-top: 1em" valign="top"><b>md5</b></p> - -<p style="margin-left:26%; margin-top: 1em">The MD5 message -digest of the file.</p> - - -<p style="margin-top: 1em" valign="top"><b>md5digest</b></p> - -<p style="margin-left:26%; margin-top: 1em">A synonym for -<b>md5</b>.</p> - -<p style="margin-top: 1em" valign="top"><b>mode</b></p> - -<p style="margin-left:26%; margin-top: 1em">The current -file’s permissions as a numeric (octal) or symbolic -value.</p> - -<p style="margin-top: 1em" valign="top"><b>nlink</b></p> - -<p style="margin-left:26%; margin-top: 1em">The number of -hard links the file is expected to have.</p> - - -<p style="margin-top: 1em" valign="top"><b>nochange</b></p> - -<p style="margin-left:26%; margin-top: 1em">Make sure this -file or directory exists but otherwise ignore all -attributes.</p> - - -<p style="margin-top: 1em" valign="top"><b>ripemd160digest</b></p> - -<p style="margin-left:26%;">The RIPEMD160 message digest of -the file.</p> - -<p style="margin-top: 1em" valign="top"><b>rmd160</b></p> - -<p style="margin-left:26%; margin-top: 1em">A synonym for -<b>ripemd160digest</b>.</p> - - -<p style="margin-top: 1em" valign="top"><b>rmd160digest</b></p> - -<p style="margin-left:26%;">A synonym for -<b>ripemd160digest</b>.</p> - -<p style="margin-top: 1em" valign="top"><b>sha1</b></p> - -<p style="margin-left:26%; margin-top: 1em">The FIPS 160-1 -(‘‘SHA-1’’) message digest of the -file.</p> - - -<p style="margin-top: 1em" valign="top"><b>sha1digest</b></p> - -<p style="margin-left:26%; margin-top: 1em">A synonym for -<b>sha1</b>.</p> - -<p style="margin-top: 1em" valign="top"><b>sha256</b></p> - -<p style="margin-left:26%; margin-top: 1em">The FIPS 180-2 -(‘‘SHA-256’’) message digest of the -file.</p> - - -<p style="margin-top: 1em" valign="top"><b>sha256digest</b></p> - -<p style="margin-left:26%;">A synonym for -<b>sha256</b>.</p> - -<p style="margin-top: 1em" valign="top"><b>size</b></p> - -<p style="margin-left:26%; margin-top: 1em">The size, in -bytes, of the file.</p> - -<p style="margin-top: 1em" valign="top"><b>time</b></p> - -<p style="margin-left:26%; margin-top: 1em">The last -modification time of the file.</p> - -<p style="margin-top: 1em" valign="top"><b>type</b></p> - -<p style="margin-left:26%; margin-top: 1em">The type of the -file; may be set to any one of the following:</p> - -<p style="margin-top: 1em" valign="top"><b>block</b></p> - -<p style="margin-left:45%; margin-top: 1em">block special -device</p> - -<p valign="top"><b>char</b></p> - -<p style="margin-left:45%; margin-top: 1em">character -special device</p> - -<p valign="top"><b>dir</b></p> - -<p style="margin-left:45%; margin-top: 1em">directory</p> - -<p valign="top"><b>fifo</b></p> - -<p style="margin-left:45%; margin-top: 1em">fifo</p> - -<p valign="top"><b>file</b></p> - -<p style="margin-left:45%; margin-top: 1em">regular -file</p> - -<p valign="top"><b>link</b></p> - -<p style="margin-left:45%; margin-top: 1em">symbolic -link</p> - -<p valign="top"><b>socket</b></p> - -<p style="margin-left:45%; margin-top: 1em">socket</p> - -<p style="margin-top: 1em" valign="top"><b>uid</b></p> - -<p style="margin-left:26%; margin-top: 1em">The file owner -as a numeric value.</p> - -<p style="margin-top: 1em" valign="top"><b>uname</b></p> - -<p style="margin-left:26%; margin-top: 1em">The file owner -as a symbolic name.</p> - -<p style="margin-top: 1em" valign="top"><b>SEE ALSO</b></p> - -<p style="margin-left:8%;">cksum(1), find(1), mtree(8)</p> - -<p style="margin-top: 1em" valign="top"><b>BUGS</b></p> - -<p style="margin-left:8%;">The FreeBSD implementation of -mtree does not currently support the <b>mtree</b> 2.0 -format. The requirement for a -‘‘#mtree’’ signature line is new and -not yet widely implemented.</p> - -<p style="margin-top: 1em" valign="top"><b>HISTORY</b></p> - -<p style="margin-left:8%;">The <b>mtree</b> 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.</p> - - -<p style="margin-left:8%; margin-top: 1em">FreeBSD 8.0 -August 20, 2007 FreeBSD 8.0</p> -<hr> -</body> -</html> diff --git a/libarchive/libarchive-2.8.0/doc/html/tar.5.html b/libarchive/libarchive-2.8.0/doc/html/tar.5.html deleted file mode 100644 index 1d87324..0000000 --- a/libarchive/libarchive-2.8.0/doc/html/tar.5.html +++ /dev/null @@ -1,1400 +0,0 @@ -<!-- Creator : groff version 1.19.2 --> -<!-- CreationDate: Thu Feb 4 20:36:38 2010 --> -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" -"http://www.w3.org/TR/html4/loose.dtd"> -<html> -<head> -<meta name="generator" content="groff -Thtml, see www.gnu.org"> -<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> -<meta name="Content-Style" content="text/css"> -<style type="text/css"> - p { margin-top: 0; margin-bottom: 0; } - pre { margin-top: 0; margin-bottom: 0; } - table { margin-top: 0; margin-bottom: 0; } -</style> -<title></title> -</head> -<body> - -<hr> - - -<p valign="top">tar(5) FreeBSD File Formats Manual -tar(5)</p> - -<p style="margin-top: 1em" valign="top"><b>NAME</b></p> - -<p style="margin-left:8%;"><b>tar</b> — format of -tape archive files</p> - - -<p style="margin-top: 1em" valign="top"><b>DESCRIPTION</b></p> - -<p style="margin-left:8%;">The <b>tar</b> 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.</p> - -<p style="margin-left:8%; margin-top: 1em"><b>General -Format</b> <br> -A <b>tar</b> 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.</p> - -<p style="margin-left:8%; margin-top: 1em">For -compatibility with tape drives that use fixed block sizes, -programs that read or write tar files always read or write a -fixed number of records with each I/O operation. These -‘‘blocks’’ are always a multiple of -the record size. The maximum block size supported by early -implementations was 10240 bytes or 20 records. This is still -the default for most implementations although block sizes of -1MiB (2048 records) or larger are commonly used with modern -high-speed tape drives. (Note: the terms -‘‘block’’ and -‘‘record’’ here are not entirely -standard; this document follows the convention established -by John Gilmore in documenting <b>pdtar</b>.)</p> - -<p style="margin-left:8%; margin-top: 1em"><b>Old-Style -Archive Format</b> <br> -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 seems to be the earliest widely-used -version of the tar program.</p> - -<p style="margin-left:8%; margin-top: 1em">The header -record for an old-style <b>tar</b> archive consists of the -following:</p> - -<p style="margin-left:17%; margin-top: 1em">struct -header_old_tar {</p> - -<table width="100%" border=0 rules="none" frame="void" - cellspacing="0" cellpadding="0"> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">char name[100];</p></td> -<td width="58%"> -</td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">char mode[8];</p></td> -<td width="58%"> -</td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">char uid[8];</p></td> -<td width="58%"> -</td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">char gid[8];</p></td> -<td width="58%"> -</td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">char size[12];</p></td> -<td width="58%"> -</td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">char mtime[12];</p></td> -<td width="58%"> -</td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">char checksum[8];</p></td> -<td width="58%"> -</td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">char linkflag[1];</p></td> -<td width="58%"> -</td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">char linkname[100];</p></td> -<td width="58%"> -</td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">char pad[255];</p></td> -<td width="58%"> -</td> -</table> - -<p style="margin-left:17%;">};</p> - -<p style="margin-left:8%;">All unused bytes in the header -record are filled with nulls.</p> - -<p style="margin-top: 1em" valign="top"><i>name</i></p> - -<p style="margin-left:20%; margin-top: 1em">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.</p> - -<p style="margin-top: 1em" valign="top"><i>mode</i></p> - -<p style="margin-left:20%; margin-top: 1em">File mode, -stored as an octal number in ASCII.</p> - -<p style="margin-top: 1em" valign="top"><i>uid</i>, -<i>gid</i></p> - -<p style="margin-left:20%;">User id and group id of owner, -as octal numbers in ASCII.</p> - -<p style="margin-top: 1em" valign="top"><i>size</i></p> - -<p style="margin-left:20%; margin-top: 1em">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.</p> - -<p style="margin-top: 1em" valign="top"><i>mtime</i></p> - -<p style="margin-left:20%; margin-top: 1em">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.</p> - - -<p style="margin-top: 1em" valign="top"><i>checksum</i></p> - -<p style="margin-left:20%;">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.</p> - -<p style="margin-top: 1em" valign="top"><i>linkflag</i>, -<i>linkname</i></p> - -<p style="margin-left:20%;">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 <i>linkflag</i> is set to -an ASCII ‘1’ and the <i>linkname</i> field holds -the first name under which this file appears. (Note that -regular files have a null value in the <i>linkflag</i> -field.)</p> - -<p style="margin-left:8%; margin-top: 1em">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 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.</p> - -<p style="margin-left:8%; margin-top: 1em"><b>Pre-POSIX -Archives</b> <br> -An early draft of IEEE Std 1003.1-1988 -(‘‘POSIX.1’’) served as the basis -for John Gilmore’s <b>pdtar</b> 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:</p> - -<p valign="top"><b>•</b></p> - -<p style="margin-left:20%;">The magic value is -‘‘ustar ’’ (note the following -space). The version field contains a space character -followed by a null.</p> - -<p valign="top"><b>•</b></p> - -<p style="margin-left:20%;">The numeric fields are -generally filled with leading spaces (not leading zeros as -recommended in the final standard).</p> - -<p valign="top"><b>•</b></p> - -<p style="margin-left:20%;">The prefix field is often not -used, limiting pathnames to the 100 characters of old-style -archives.</p> - -<p style="margin-left:8%; margin-top: 1em"><b>POSIX ustar -Archives</b> <br> -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:</p> - -<p style="margin-left:17%; margin-top: 1em">struct -header_posix_ustar {</p> - -<table width="100%" border=0 rules="none" frame="void" - cellspacing="0" cellpadding="0"> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">char name[100];</p></td> -<td width="58%"> -</td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">char mode[8];</p></td> -<td width="58%"> -</td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">char uid[8];</p></td> -<td width="58%"> -</td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">char gid[8];</p></td> -<td width="58%"> -</td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">char size[12];</p></td> -<td width="58%"> -</td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">char mtime[12];</p></td> -<td width="58%"> -</td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">char checksum[8];</p></td> -<td width="58%"> -</td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">char typeflag[1];</p></td> -<td width="58%"> -</td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">char linkname[100];</p></td> -<td width="58%"> -</td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">char magic[6];</p></td> -<td width="58%"> -</td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">char version[2];</p></td> -<td width="58%"> -</td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">char uname[32];</p></td> -<td width="58%"> -</td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">char gname[32];</p></td> -<td width="58%"> -</td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">char devmajor[8];</p></td> -<td width="58%"> -</td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">char devminor[8];</p></td> -<td width="58%"> -</td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">char prefix[155];</p></td> -<td width="58%"> -</td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">char pad[12];</p></td> -<td width="58%"> -</td> -</table> - -<p style="margin-left:17%;">};</p> - - -<p style="margin-top: 1em" valign="top"><i>typeflag</i></p> - -<p style="margin-left:20%;">Type of entry. POSIX extended -the earlier <i>linkflag</i> field with several new type -values:</p> - -<p valign="top">‘‘0’’</p> - -<p style="margin-left:32%; margin-top: 1em">Regular file. -NUL should be treated as a synonym, for compatibility -purposes.</p> - -<p valign="top">‘‘1’’</p> - -<p style="margin-left:32%; margin-top: 1em">Hard link.</p> - -<p valign="top">‘‘2’’</p> - -<p style="margin-left:32%; margin-top: 1em">Symbolic -link.</p> - -<p valign="top">‘‘3’’</p> - -<p style="margin-left:32%; margin-top: 1em">Character -device node.</p> - -<p valign="top">‘‘4’’</p> - -<p style="margin-left:32%; margin-top: 1em">Block device -node.</p> - -<p valign="top">‘‘5’’</p> - -<p style="margin-left:32%; margin-top: 1em">Directory.</p> - -<p valign="top">‘‘6’’</p> - -<p style="margin-left:32%; margin-top: 1em">FIFO node.</p> - -<p valign="top">‘‘7’’</p> - -<p style="margin-left:32%; margin-top: 1em">Reserved.</p> - -<p valign="top">Other</p> - -<p style="margin-left:32%; margin-top: 1em">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.</p> - -<p style="margin-left:20%;">It is worth noting that the -<i>size</i> 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.</p> - -<p style="margin-top: 1em" valign="top"><i>magic</i></p> - -<p style="margin-left:20%; margin-top: 1em">Contains the -magic value ‘‘ustar’’ followed by a -NUL byte to indicate that this is a POSIX standard archive. -Full compliance requires the uname and gname fields be -properly set.</p> - -<p style="margin-top: 1em" valign="top"><i>version</i></p> - -<p style="margin-left:20%;">Version. This should be -‘‘00’’ (two copies of the ASCII -digit zero) for POSIX standard archives.</p> - -<p style="margin-top: 1em" valign="top"><i>uname</i>, -<i>gname</i></p> - -<p style="margin-left:20%;">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.</p> - -<p style="margin-top: 1em" valign="top"><i>devmajor</i>, -<i>devminor</i></p> - -<p style="margin-left:20%;">Major and minor numbers for -character device or block device entry.</p> - -<p style="margin-top: 1em" valign="top"><i>name</i>, -<i>prefix</i></p> - -<p style="margin-left:20%;">If the pathname is too long to -fit in the 100 bytes provided by the standard format, it can -be split at any <i>/</i> character with the first portion -going into the prefix field. If the prefix field is not -empty, the reader will prepend the prefix value and a -<i>/</i> character to the regular name field to obtain the -full pathname. The standard does not require a trailing -<i>/</i> character on directory names, though most -implementations still include this for compatibility -reasons.</p> - -<p style="margin-left:8%; margin-top: 1em">Note that all -unused bytes must be set to NUL.</p> - -<p style="margin-left:8%; margin-top: 1em">Field -termination is specified slightly differently by POSIX than -by previous implementations. The <i>magic</i>, <i>uname</i>, -and <i>gname</i> fields must have a trailing NUL. The -<i>pathname</i>, <i>linkname</i>, and <i>prefix</i> fields -must have a trailing NUL unless they fill the entire field. -(In particular, it is possible to store a 256-character -pathname if it happens to have a <i>/</i> as the 156th -character.) POSIX requires numeric fields to be zero-padded -in the front, and requires them to be terminated with either -space or NUL characters.</p> - -<p style="margin-left:8%; margin-top: 1em">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.</p> - -<p style="margin-left:8%; margin-top: 1em"><b>Pax -Interchange Format</b> <br> -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.</p> - -<p style="margin-left:8%; margin-top: 1em">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:</p> - -<p style="margin-left:17%;">25 ctime=1084839148.1212\n</p> - -<p style="margin-left:8%;">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:</p> - -<p style="margin-top: 1em" valign="top"><b>atime</b>, -<b>ctime</b>, <b>mtime</b></p> - -<p style="margin-left:20%;">File access, inode change, and -modification times. These fields can be negative or include -a decimal point and a fractional value.</p> - -<p style="margin-top: 1em" valign="top"><b>uname</b>, -<b>uid</b>, <b>gname</b>, <b>gid</b></p> - -<p style="margin-left:20%;">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.</p> - - -<p style="margin-top: 1em" valign="top"><b>linkpath</b></p> - -<p style="margin-left:20%;">The full path of the linked-to -file. Note that this is encoded in UTF8 and can thus include -non-ASCII characters.</p> - -<p style="margin-top: 1em" valign="top"><b>path</b></p> - -<p style="margin-left:20%; margin-top: 1em">The full -pathname of the entry. Note that this is encoded in UTF8 and -can thus include non-ASCII characters.</p> - -<p style="margin-top: 1em" valign="top"><b>realtime.*</b>, -<b>security.*</b></p> - -<p style="margin-left:20%;">These keys are reserved and may -be used for future standardization.</p> - -<p style="margin-top: 1em" valign="top"><b>size</b></p> - -<p style="margin-left:20%; margin-top: 1em">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.</p> - - -<p style="margin-top: 1em" valign="top"><b>SCHILY.*</b></p> - -<p style="margin-left:20%;">Vendor-specific attributes used -by Joerg Schilling’s <b>star</b> implementation.</p> - - -<p style="margin-top: 1em" valign="top"><b>SCHILY.acl.access</b>, -<b>SCHILY.acl.default</b></p> - -<p style="margin-left:20%;">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).</p> - - -<p style="margin-top: 1em" valign="top"><b>SCHILY.devminor</b>, -<b>SCHILY.devmajor</b></p> - -<p style="margin-left:20%;">The full minor and major -numbers for device nodes.</p> - - -<p style="margin-top: 1em" valign="top"><b>SCHILY.fflags</b></p> - -<p style="margin-left:20%;">The file flags.</p> - - -<p style="margin-top: 1em" valign="top"><b>SCHILY.realsize</b></p> - -<p style="margin-left:20%;">The full size of the file on -disk. XXX explain? XXX</p> - -<p style="margin-top: 1em" valign="top"><b>SCHILY.dev, -SCHILY.ino</b>, <b>SCHILY.nlinks</b></p> - -<p style="margin-left:20%;">The device number, inode -number, and link count for the entry. In particular, note -that a pax interchange format archive using Joerg -Schilling’s <b>SCHILY.*</b> extensions can store all -of the data from <i>struct stat</i>.</p> - - -<p style="margin-top: 1em" valign="top"><b>LIBARCHIVE.xattr.</b><i>namespace</i>.<i>key</i></p> - -<p style="margin-left:20%;">Libarchive stores -POSIX.1e-style extended attributes using keys of this form. -The <i>key</i> 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</p> - - -<p style="margin-top: 1em" valign="top"><b>VENDOR.*</b></p> - -<p style="margin-left:20%;">XXX document other -vendor-specific extensions XXX</p> - -<p style="margin-left:8%; margin-top: 1em">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.</p> - -<p style="margin-left:8%; margin-top: 1em">In addition to -the <b>x</b> entry described above, the pax interchange -format also supports a <b>g</b> entry. The <b>g</b> entry is -identical in format, but specifies attributes that serve as -defaults for all subsequent archive entries. The <b>g</b> -entry is not widely used.</p> - -<p style="margin-left:8%; margin-top: 1em">Besides the new -<b>x</b> and <b>g</b> 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.</p> - -<p style="margin-left:8%; margin-top: 1em"><b>GNU Tar -Archives</b> <br> -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 -<b>x</b> entry described above, but each GNU special entry -is single-purpose, unlike the general-purpose <b>x</b> -entry). As a result, GNU tar archives are not POSIX -compatible, although more lenient POSIX-compliant readers -can successfully extract most GNU tar archives.</p> - -<p style="margin-left:17%; margin-top: 1em">struct -header_gnu_tar {</p> - -<table width="100%" border=0 rules="none" frame="void" - cellspacing="0" cellpadding="0"> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">char name[100];</p></td> -<td width="12%"></td> -<td width="46%"> -</td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">char mode[8];</p></td> -<td width="12%"></td> -<td width="46%"> -</td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">char uid[8];</p></td> -<td width="12%"></td> -<td width="46%"> -</td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">char gid[8];</p></td> -<td width="12%"></td> -<td width="46%"> -</td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">char size[12];</p></td> -<td width="12%"></td> -<td width="46%"> -</td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">char mtime[12];</p></td> -<td width="12%"></td> -<td width="46%"> -</td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">char checksum[8];</p></td> -<td width="12%"></td> -<td width="46%"> -</td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">char typeflag[1];</p></td> -<td width="12%"></td> -<td width="46%"> -</td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">char linkname[100];</p></td> -<td width="12%"></td> -<td width="46%"> -</td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">char magic[6];</p></td> -<td width="12%"></td> -<td width="46%"> -</td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">char version[2];</p></td> -<td width="12%"></td> -<td width="46%"> -</td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">char uname[32];</p></td> -<td width="12%"></td> -<td width="46%"> -</td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">char gname[32];</p></td> -<td width="12%"></td> -<td width="46%"> -</td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">char devmajor[8];</p></td> -<td width="12%"></td> -<td width="46%"> -</td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">char devminor[8];</p></td> -<td width="12%"></td> -<td width="46%"> -</td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">char atime[12];</p></td> -<td width="12%"></td> -<td width="46%"> -</td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">char ctime[12];</p></td> -<td width="12%"></td> -<td width="46%"> -</td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">char offset[12];</p></td> -<td width="12%"></td> -<td width="46%"> -</td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">char longnames[4];</p></td> -<td width="12%"></td> -<td width="46%"> -</td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">char unused[1];</p></td> -<td width="12%"></td> -<td width="46%"> -</td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">struct {</p></td> -<td width="12%"></td> -<td width="46%"> -</td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> -</td> -<td width="12%"> - - -<p valign="top">char offset[12];</p></td> -<td width="46%"> -</td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> -</td> -<td width="12%"> - - -<p valign="top">char numbytes[12];</p></td> -<td width="46%"> -</td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">} sparse[4];</p></td> -<td width="12%"></td> -<td width="46%"> -</td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">char isextended[1];</p></td> -<td width="12%"></td> -<td width="46%"> -</td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">char realsize[12];</p></td> -<td width="12%"></td> -<td width="46%"> -</td> -<tr valign="top" align="left"> -<td width="29%"></td> -<td width="13%"> - - -<p valign="top">char pad[17];</p></td> -<td width="12%"></td> -<td width="46%"> -</td> -</table> - -<p style="margin-left:17%;">};</p> - - -<p style="margin-top: 1em" valign="top"><i>typeflag</i></p> - -<p style="margin-left:20%;">GNU tar uses the following -special entry types, in addition to those defined by -POSIX:</p> - -<p style="margin-top: 1em" valign="top">7</p> - -<p style="margin-left:32%; margin-top: 1em">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.</p> - -<p style="margin-top: 1em" valign="top">D</p> - -<p style="margin-left:32%; margin-top: 1em">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.</p> - -<p style="margin-left:32%; margin-top: 1em">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.</p> - -<p style="margin-top: 1em" valign="top">K</p> - -<p style="margin-left:32%; margin-top: 1em">The data for -this entry is a long linkname for the following regular -entry.</p> - -<p style="margin-top: 1em" valign="top">L</p> - -<p style="margin-left:32%; margin-top: 1em">The data for -this entry is a long pathname for the following regular -entry.</p> - -<p style="margin-top: 1em" valign="top">M</p> - -<p style="margin-left:32%; margin-top: 1em">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 <i>size</i> field specifies the size of -this entry. The <i>offset</i> field at bytes 369-380 -specifies the offset where this file fragment begins. The -<i>realsize</i> field specifies the total size of the file -(which must equal <i>size</i> plus <i>offset</i>). 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.</p> - -<p style="margin-top: 1em" valign="top">N</p> - -<p style="margin-left:32%; margin-top: 1em">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 syntax. Due to security concerns, -"N" records are now generally ignored when reading -archives.</p> - -<p style="margin-top: 1em" valign="top">S</p> - -<p style="margin-left:32%; margin-top: 1em">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.</p> - -<p style="margin-top: 1em" valign="top">V</p> - -<p style="margin-left:32%; margin-top: 1em">The <i>name</i> -field should be interpreted as a tape/volume header name. -This entry should generally be ignored on extraction.</p> - -<p style="margin-top: 1em" valign="top"><i>magic</i></p> - -<p style="margin-left:20%; margin-top: 1em">The magic field -holds the five characters ‘‘ustar’’ -followed by a space. Note that POSIX ustar archives have a -trailing null.</p> - -<p style="margin-top: 1em" valign="top"><i>version</i></p> - -<p style="margin-left:20%;">The version field holds a space -character followed by a null. Note that POSIX ustar archives -use two copies of the ASCII digit -‘‘0’’.</p> - -<p style="margin-top: 1em" valign="top"><i>atime</i>, -<i>ctime</i></p> - -<p style="margin-left:20%;">The time the file was last -accessed and the time of last change of file information, -stored in octal as with <i>mtime</i>.</p> - - -<p style="margin-top: 1em" valign="top"><i>longnames</i></p> - -<p style="margin-left:20%;">This field is apparently no -longer used.</p> - -<p style="margin-top: 1em" valign="top">Sparse <i>offset / -numbytes</i></p> - -<p style="margin-left:20%;">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.</p> - - -<p style="margin-top: 1em" valign="top"><i>isextended</i></p> - -<p style="margin-left:20%;">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:</p> - -<p style="margin-left:29%; margin-top: 1em">struct -gnu_sparse_header {</p> - -<table width="100%" border=0 rules="none" frame="void" - cellspacing="0" cellpadding="0"> -<tr valign="top" align="left"> -<td width="42%"></td> -<td width="12%"> - - -<p valign="top">struct {</p></td> -<td width="12%"></td> -<td width="34%"> -</td> -<tr valign="top" align="left"> -<td width="42%"></td> -<td width="12%"> -</td> -<td width="12%"> - - -<p valign="top">char offset[12];</p></td> -<td width="34%"> -</td> -<tr valign="top" align="left"> -<td width="42%"></td> -<td width="12%"> -</td> -<td width="12%"> - - -<p valign="top">char numbytes[12];</p></td> -<td width="34%"> -</td> -<tr valign="top" align="left"> -<td width="42%"></td> -<td width="12%"> - - -<p valign="top">} sparse[21];</p></td> -<td width="12%"></td> -<td width="34%"> -</td> -<tr valign="top" align="left"> -<td width="42%"></td> -<td width="12%"> - - -<p valign="top">char isextended[1];</p></td> -<td width="12%"></td> -<td width="34%"> -</td> -<tr valign="top" align="left"> -<td width="42%"></td> -<td width="12%"> - - -<p valign="top">char padding[7];</p></td> -<td width="12%"></td> -<td width="34%"> -</td> -</table> - -<p style="margin-left:29%;">};</p> - - -<p style="margin-top: 1em" valign="top"><i>realsize</i></p> - -<p style="margin-left:20%;">A binary representation of the -file’s complete size, with a much larger range than -the POSIX file size. In particular, with <b>M</b> 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 <i>realsize</i> field will indicate the -total size of the file.</p> - -<p style="margin-left:8%; margin-top: 1em"><b>GNU tar pax -archives</b> <br> -GNU tar 1.14 (XXX check this XXX) and later will write pax -interchange format archives when you specify the -<b>−-posix</b> flag. This format uses custom keywords -to store sparse file information. There have been three -iterations of this support, referred to as -‘‘0.0’’, -‘‘0.1’’, and -‘‘1.0’’.</p> - - -<p style="margin-top: 1em" valign="top"><b>GNU.sparse.numblocks</b>, -<b>GNU.sparse.offset</b>, <b>GNU.sparse.numbytes</b>, -<b>GNU.sparse.size</b></p> - -<p style="margin-left:20%;">The -‘‘0.0’’ format used an initial -<b>GNU.sparse.numblocks</b> attribute to indicate the number -of blocks in the file, a pair of <b>GNU.sparse.offset</b> -and <b>GNU.sparse.numbytes</b> to indicate the offset and -size of each block, and a single <b>GNU.sparse.size</b> to -indicate the full size of the file. This is not the same as -the size in the tar header because the latter value does not -include the size of any holes. This format required that the -order of attributes be preserved and relied on readers -accepting multiple appearances of the same attribute names, -which is not officially permitted by the standards.</p> - - -<p style="margin-top: 1em" valign="top"><b>GNU.sparse.map</b></p> - -<p style="margin-left:20%;">The -‘‘0.1’’ format used a single -attribute that stored a comma-separated list of decimal -numbers. Each pair of numbers indicated the offset and size, -respectively, of a block of data. This does not work well if -the archive is extracted by an archiver that does not -recognize this extension, since many pax implementations -simply discard unrecognized attributes.</p> - - -<p style="margin-top: 1em" valign="top"><b>GNU.sparse.major</b>, -<b>GNU.sparse.minor</b>, <b>GNU.sparse.name</b>, -<b>GNU.sparse.realsize</b></p> - -<p style="margin-left:20%;">The -‘‘1.0’’ format stores the sparse -block map in one or more 512-byte blocks prepended to the -file data in the entry body. The pax attributes indicate the -existence of this map (via the <b>GNU.sparse.major</b> and -<b>GNU.sparse.minor</b> fields) and the full size of the -file. The <b>GNU.sparse.name</b> holds the true name of the -file. To avoid confusion, the name stored in the regular tar -header is a modified name so that extraction errors will be -apparent to users.</p> - -<p style="margin-left:8%; margin-top: 1em"><b>Solaris -Tar</b> <br> -XXX More Details Needed XXX</p> - -<p style="margin-left:8%; margin-top: 1em">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:</p> - -<p valign="top"><b>•</b></p> - -<p style="margin-left:20%;">Extended attributes are stored -in an entry whose type is <b>X</b>, not <b>x</b>, as used by -pax interchange format. The detailed format of this entry -appears to be the same as detailed above for the <b>x</b> -entry.</p> - -<p valign="top"><b>•</b></p> - -<p style="margin-left:20%;">An additional <b>A</b> entry is -used to store an ACL for the following regular entry. The -body of this entry contains a seven-digit octal number -followed by a zero byte, followed by the textual ACL -description. The octal value is the number of ACL entries -plus a constant that indicates the ACL type: 01000000 for -POSIX.1e ACLs and 03000000 for NFSv4 ACLs.</p> - -<p style="margin-left:8%; margin-top: 1em"><b>AIX Tar</b> -<br> -XXX More details needed XXX</p> - -<p style="margin-left:8%; margin-top: 1em"><b>Mac OS X -Tar</b> <br> -The tar distributed with Apple’s Mac OS X stores most -regular files as two separate entries in the tar archive. -The two entries have the same name except that the first one -has ‘‘._’’ added to the beginning of -the name. This first entry stores the ‘‘resource -fork’’ with additional attributes for the file. -The Mac OS X <b>CopyFile</b>() API is used to separate a -file on disk into separate resource and data streams and to -reassemble those separate streams when the file is restored -to disk.</p> - -<p style="margin-left:8%; margin-top: 1em"><b>Other -Extensions</b> <br> -One obvious extension to increase the size of files is to -eliminate the terminating characters from the various -numeric fields. For example, the standard only allows the -size field to contain 11 octal digits, reserving the twelfth -byte for a trailing NUL character. Allowing 12 octal digits -allows file sizes up to 64 GB.</p> - -<p style="margin-left:8%; margin-top: 1em">Another -extension, utilized by GNU tar, star, and other newer -<b>tar</b> implementations, permits binary numbers in the -standard numeric fields. This is flagged by setting the high -bit of the first byte. This permits 95-bit values for the -length and time fields and 63-bit values for the uid, gid, -and device numbers. GNU tar supports this extension for the -length, mtime, ctime, and atime fields. Joerg -Schilling’s star program supports this extension for -all numeric fields. Note that this extension is largely -obsoleted by the extended attribute record provided by the -pax interchange format.</p> - -<p style="margin-left:8%; margin-top: 1em">Another early -GNU extension allowed base-64 values rather than octal. This -extension was short-lived and is no longer supported by any -implementation.</p> - -<p style="margin-top: 1em" valign="top"><b>SEE ALSO</b></p> - -<p style="margin-left:8%;">ar(1), pax(1), tar(1)</p> - - -<p style="margin-top: 1em" valign="top"><b>STANDARDS</b></p> - -<p style="margin-left:8%;">The <b>tar</b> 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’’).</p> - -<p style="margin-top: 1em" valign="top"><b>HISTORY</b></p> - -<p style="margin-left:8%;">A <b>tar</b> command appeared in -Seventh Edition Unix, which was released in January, 1979. -It replaced the <b>tp</b> program from Fourth Edition Unix -which in turn replaced the <b>tap</b> program from First -Edition Unix. John Gilmore’s <b>pdtar</b> -public-domain implementation (circa 1987) was highly -influential and formed the basis of <b>GNU tar</b> (circa -1988). Joerg Shilling’s <b>star</b> archiver is -another open-source (GPL) archiver (originally developed -circa 1985) which features complete support for pax -interchange format.</p> - -<p style="margin-left:8%; margin-top: 1em">This -documentation was written as part of the <b>libarchive</b> -and <b>bsdtar</b> project by Tim Kientzle -⟨kientzle@FreeBSD.org⟩.</p> - - -<p style="margin-left:8%; margin-top: 1em">FreeBSD 8.0 -December 27, 2009 FreeBSD 8.0</p> -<hr> -</body> -</html> diff --git a/libarchive/libarchive-2.8.0/doc/man/Makefile b/libarchive/libarchive-2.8.0/doc/man/Makefile deleted file mode 100644 index d3a9019..0000000 --- a/libarchive/libarchive-2.8.0/doc/man/Makefile +++ /dev/null @@ -1,46 +0,0 @@ - -default: all - - -archive_entry.3: ../mdoc2man.awk ../../libarchive/archive_entry.3 - awk -f ../mdoc2man.awk < ../../libarchive/archive_entry.3 > archive_entry.3 - -archive_read.3: ../mdoc2man.awk ../../libarchive/archive_read.3 - awk -f ../mdoc2man.awk < ../../libarchive/archive_read.3 > archive_read.3 - -archive_read_disk.3: ../mdoc2man.awk ../../libarchive/archive_read_disk.3 - awk -f ../mdoc2man.awk < ../../libarchive/archive_read_disk.3 > archive_read_disk.3 - -archive_util.3: ../mdoc2man.awk ../../libarchive/archive_util.3 - awk -f ../mdoc2man.awk < ../../libarchive/archive_util.3 > archive_util.3 - -archive_write.3: ../mdoc2man.awk ../../libarchive/archive_write.3 - awk -f ../mdoc2man.awk < ../../libarchive/archive_write.3 > archive_write.3 - -archive_write_disk.3: ../mdoc2man.awk ../../libarchive/archive_write_disk.3 - awk -f ../mdoc2man.awk < ../../libarchive/archive_write_disk.3 > archive_write_disk.3 - -cpio.5: ../mdoc2man.awk ../../libarchive/cpio.5 - awk -f ../mdoc2man.awk < ../../libarchive/cpio.5 > cpio.5 - -libarchive-formats.5: ../mdoc2man.awk ../../libarchive/libarchive-formats.5 - awk -f ../mdoc2man.awk < ../../libarchive/libarchive-formats.5 > libarchive-formats.5 - -libarchive.3: ../mdoc2man.awk ../../libarchive/libarchive.3 - awk -f ../mdoc2man.awk < ../../libarchive/libarchive.3 > libarchive.3 - -libarchive_internals.3: ../mdoc2man.awk ../../libarchive/libarchive_internals.3 - awk -f ../mdoc2man.awk < ../../libarchive/libarchive_internals.3 > libarchive_internals.3 - -mtree.5: ../mdoc2man.awk ../../libarchive/mtree.5 - awk -f ../mdoc2man.awk < ../../libarchive/mtree.5 > mtree.5 - -tar.5: ../mdoc2man.awk ../../libarchive/tar.5 - awk -f ../mdoc2man.awk < ../../libarchive/tar.5 > tar.5 - -bsdtar.1: ../mdoc2man.awk ../../tar/bsdtar.1 - awk -f ../mdoc2man.awk < ../../tar/bsdtar.1 > bsdtar.1 - -bsdcpio.1: ../mdoc2man.awk ../../cpio/bsdcpio.1 - awk -f ../mdoc2man.awk < ../../cpio/bsdcpio.1 > bsdcpio.1 -all: archive_entry.3 archive_read.3 archive_read_disk.3 archive_util.3 archive_write.3 archive_write_disk.3 cpio.5 libarchive-formats.5 libarchive.3 libarchive_internals.3 mtree.5 tar.5 bsdtar.1 bsdcpio.1 diff --git a/libarchive/libarchive-2.8.0/doc/man/archive_entry.3 b/libarchive/libarchive-2.8.0/doc/man/archive_entry.3 deleted file mode 100644 index d459f00..0000000 --- a/libarchive/libarchive-2.8.0/doc/man/archive_entry.3 +++ /dev/null @@ -1,519 +0,0 @@ -.TH archive_entry 3 "May 12, 2008" "" -.SH NAME -.ad l -\fB\%archive_entry_acl_add_entry\fP, -\fB\%archive_entry_acl_add_entry_w\fP, -\fB\%archive_entry_acl_clear\fP, -\fB\%archive_entry_acl_count\fP, -\fB\%archive_entry_acl_next\fP, -\fB\%archive_entry_acl_next_w\fP, -\fB\%archive_entry_acl_reset\fP, -\fB\%archive_entry_acl_text_w\fP, -\fB\%archive_entry_atime\fP, -\fB\%archive_entry_atime_nsec\fP, -\fB\%archive_entry_clear\fP, -\fB\%archive_entry_clone\fP, -\fB\%archive_entry_copy_fflags_text\fP, -\fB\%archive_entry_copy_fflags_text_w\fP, -\fB\%archive_entry_copy_gname\fP, -\fB\%archive_entry_copy_gname_w\fP, -\fB\%archive_entry_copy_hardlink\fP, -\fB\%archive_entry_copy_hardlink_w\fP, -\fB\%archive_entry_copy_link\fP, -\fB\%archive_entry_copy_link_w\fP, -\fB\%archive_entry_copy_pathname_w\fP, -\fB\%archive_entry_copy_sourcepath\fP, -\fB\%archive_entry_copy_stat\fP, -\fB\%archive_entry_copy_symlink\fP, -\fB\%archive_entry_copy_symlink_w\fP, -\fB\%archive_entry_copy_uname\fP, -\fB\%archive_entry_copy_uname_w\fP, -\fB\%archive_entry_dev\fP, -\fB\%archive_entry_devmajor\fP, -\fB\%archive_entry_devminor\fP, -\fB\%archive_entry_filetype\fP, -\fB\%archive_entry_fflags\fP, -\fB\%archive_entry_fflags_text\fP, -\fB\%archive_entry_free\fP, -\fB\%archive_entry_gid\fP, -\fB\%archive_entry_gname\fP, -\fB\%archive_entry_hardlink\fP, -\fB\%archive_entry_ino\fP, -\fB\%archive_entry_mode\fP, -\fB\%archive_entry_mtime\fP, -\fB\%archive_entry_mtime_nsec\fP, -\fB\%archive_entry_nlink\fP, -\fB\%archive_entry_new\fP, -\fB\%archive_entry_pathname\fP, -\fB\%archive_entry_pathname_w\fP, -\fB\%archive_entry_rdev\fP, -\fB\%archive_entry_rdevmajor\fP, -\fB\%archive_entry_rdevminor\fP, -\fB\%archive_entry_set_atime\fP, -\fB\%archive_entry_set_ctime\fP, -\fB\%archive_entry_set_dev\fP, -\fB\%archive_entry_set_devmajor\fP, -\fB\%archive_entry_set_devminor\fP, -\fB\%archive_entry_set_filetype\fP, -\fB\%archive_entry_set_fflags\fP, -\fB\%archive_entry_set_gid\fP, -\fB\%archive_entry_set_gname\fP, -\fB\%archive_entry_set_hardlink\fP, -\fB\%archive_entry_set_link\fP, -\fB\%archive_entry_set_mode\fP, -\fB\%archive_entry_set_mtime\fP, -\fB\%archive_entry_set_pathname\fP, -\fB\%archive_entry_set_rdevmajor\fP, -\fB\%archive_entry_set_rdevminor\fP, -\fB\%archive_entry_set_size\fP, -\fB\%archive_entry_set_symlink\fP, -\fB\%archive_entry_set_uid\fP, -\fB\%archive_entry_set_uname\fP, -\fB\%archive_entry_size\fP, -\fB\%archive_entry_sourcepath\fP, -\fB\%archive_entry_stat\fP, -\fB\%archive_entry_symlink\fP, -\fB\%archive_entry_uid\fP, -\fB\%archive_entry_uname\fP -\- functions for manipulating archive entry descriptions -.SH SYNOPSIS -.ad l -\fB#include <archive_entry.h>\fP -.br -\fIvoid\fP -.br -\fB\%archive_entry_acl_add_entry\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%int\ type\fP, \fI\%int\ permset\fP, \fI\%int\ tag\fP, \fI\%int\ qual\fP, \fI\%const\ char\ *name\fP); -.br -\fIvoid\fP -.br -\fB\%archive_entry_acl_add_entry_w\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%int\ type\fP, \fI\%int\ permset\fP, \fI\%int\ tag\fP, \fI\%int\ qual\fP, \fI\%const\ wchar_t\ *name\fP); -.br -\fIvoid\fP -.br -\fB\%archive_entry_acl_clear\fP(\fI\%struct\ archive_entry\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_entry_acl_count\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%int\ type\fP); -.br -\fIint\fP -.br -\fB\%archive_entry_acl_next\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%int\ want_type\fP, \fI\%int\ *type\fP, \fI\%int\ *permset\fP, \fI\%int\ *tag\fP, \fI\%int\ *qual\fP, \fI\%const\ char\ **name\fP); -.br -\fIint\fP -.br -\fB\%archive_entry_acl_next_w\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%int\ want_type\fP, \fI\%int\ *type\fP, \fI\%int\ *permset\fP, \fI\%int\ *tag\fP, \fI\%int\ *qual\fP, \fI\%const\ wchar_t\ **name\fP); -.br -\fIint\fP -.br -\fB\%archive_entry_acl_reset\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%int\ want_type\fP); -.br -\fIconst wchar_t *\fP -.br -\fB\%archive_entry_acl_text_w\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%int\ flags\fP); -.br -\fItime_t\fP -.br -\fB\%archive_entry_atime\fP(\fI\%struct\ archive_entry\ *\fP); -.br -\fIlong\fP -.br -\fB\%archive_entry_atime_nsec\fP(\fI\%struct\ archive_entry\ *\fP); -.br -\fIstruct archive_entry *\fP -.br -\fB\%archive_entry_clear\fP(\fI\%struct\ archive_entry\ *\fP); -.br -\fIstruct archive_entry *\fP -.br -\fB\%archive_entry_clone\fP(\fI\%struct\ archive_entry\ *\fP); -.br -\fIconst char * *\fP -.br -\fB\%archive_entry_copy_fflags_text_w\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ char\ *\fP); -.br -\fIconst wchar_t *\fP -.br -\fB\%archive_entry_copy_fflags_text_w\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ wchar_t\ *\fP); -.br -\fIvoid\fP -.br -\fB\%archive_entry_copy_gname\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ char\ *\fP); -.br -\fIvoid\fP -.br -\fB\%archive_entry_copy_gname_w\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ wchar_t\ *\fP); -.br -\fIvoid\fP -.br -\fB\%archive_entry_copy_hardlink\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ char\ *\fP); -.br -\fIvoid\fP -.br -\fB\%archive_entry_copy_hardlink_w\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ wchar_t\ *\fP); -.br -\fIvoid\fP -.br -\fB\%archive_entry_copy_sourcepath\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ char\ *\fP); -.br -\fIvoid\fP -.br -\fB\%archive_entry_copy_pathname_w\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ wchar_t\ *\fP); -.br -\fIvoid\fP -.br -\fB\%archive_entry_copy_stat\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ struct\ stat\ *\fP); -.br -\fIvoid\fP -.br -\fB\%archive_entry_copy_symlink\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ char\ *\fP); -.br -\fIvoid\fP -.br -\fB\%archive_entry_copy_symlink_w\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ wchar_t\ *\fP); -.br -\fIvoid\fP -.br -\fB\%archive_entry_copy_uname\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ char\ *\fP); -.br -\fIvoid\fP -.br -\fB\%archive_entry_copy_uname_w\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ wchar_t\ *\fP); -.br -\fIdev_t\fP -.br -\fB\%archive_entry_dev\fP(\fI\%struct\ archive_entry\ *\fP); -.br -\fIdev_t\fP -.br -\fB\%archive_entry_devmajor\fP(\fI\%struct\ archive_entry\ *\fP); -.br -\fIdev_t\fP -.br -\fB\%archive_entry_devminor\fP(\fI\%struct\ archive_entry\ *\fP); -.br -\fImode_t\fP -.br -\fB\%archive_entry_filetype\fP(\fI\%struct\ archive_entry\ *\fP); -.br -\fIvoid\fP -.br -\fB\%archive_entry_fflags\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%unsigned\ long\ *set\fP, \fI\%unsigned\ long\ *clear\fP); -.br -\fIconst char *\fP -.br -\fB\%archive_entry_fflags_text\fP(\fI\%struct\ archive_entry\ *\fP); -.br -\fIvoid\fP -.br -\fB\%archive_entry_free\fP(\fI\%struct\ archive_entry\ *\fP); -.br -\fIconst char *\fP -.br -\fB\%archive_entry_gname\fP(\fI\%struct\ archive_entry\ *\fP); -.br -\fIconst char *\fP -.br -\fB\%archive_entry_hardlink\fP(\fI\%struct\ archive_entry\ *\fP); -.br -\fIino_t\fP -.br -\fB\%archive_entry_ino\fP(\fI\%struct\ archive_entry\ *\fP); -.br -\fImode_t\fP -.br -\fB\%archive_entry_mode\fP(\fI\%struct\ archive_entry\ *\fP); -.br -\fItime_t\fP -.br -\fB\%archive_entry_mtime\fP(\fI\%struct\ archive_entry\ *\fP); -.br -\fIlong\fP -.br -\fB\%archive_entry_mtime_nsec\fP(\fI\%struct\ archive_entry\ *\fP); -.br -\fIunsigned int\fP -.br -\fB\%archive_entry_nlink\fP(\fI\%struct\ archive_entry\ *\fP); -.br -\fIstruct archive_entry *\fP -.br -\fB\%archive_entry_new\fP(\fI\%void\fP); -.br -\fIconst char *\fP -.br -\fB\%archive_entry_pathname\fP(\fI\%struct\ archive_entry\ *\fP); -.br -\fIconst wchar_t *\fP -.br -\fB\%archive_entry_pathname_w\fP(\fI\%struct\ archive_entry\ *\fP); -.br -\fIdev_t\fP -.br -\fB\%archive_entry_rdev\fP(\fI\%struct\ archive_entry\ *\fP); -.br -\fIdev_t\fP -.br -\fB\%archive_entry_rdevmajor\fP(\fI\%struct\ archive_entry\ *\fP); -.br -\fIdev_t\fP -.br -\fB\%archive_entry_rdevminor\fP(\fI\%struct\ archive_entry\ *\fP); -.br -\fIvoid\fP -.br -\fB\%archive_entry_set_dev\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%dev_t\fP); -.br -\fIvoid\fP -.br -\fB\%archive_entry_set_devmajor\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%dev_t\fP); -.br -\fIvoid\fP -.br -\fB\%archive_entry_set_devminor\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%dev_t\fP); -.br -\fIvoid\fP -.br -\fB\%archive_entry_set_filetype\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%unsigned\ int\fP); -.br -\fIvoid\fP -.br -\fB\%archive_entry_set_fflags\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%unsigned\ long\ set\fP, \fI\%unsigned\ long\ clear\fP); -.br -\fIvoid\fP -.br -\fB\%archive_entry_set_gid\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%gid_t\fP); -.br -\fIvoid\fP -.br -\fB\%archive_entry_set_gname\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ char\ *\fP); -.br -\fIvoid\fP -.br -\fB\%archive_entry_set_hardlink\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ char\ *\fP); -.br -\fIvoid\fP -.br -\fB\%archive_entry_set_ino\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%unsigned\ long\fP); -.br -\fIvoid\fP -.br -\fB\%archive_entry_set_link\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ char\ *\fP); -.br -\fIvoid\fP -.br -\fB\%archive_entry_set_mode\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%mode_t\fP); -.br -\fIvoid\fP -.br -\fB\%archive_entry_set_mtime\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%time_t\fP, \fI\%long\ nanos\fP); -.br -\fIvoid\fP -.br -\fB\%archive_entry_set_nlink\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%unsigned\ int\fP); -.br -\fIvoid\fP -.br -\fB\%archive_entry_set_pathname\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ char\ *\fP); -.br -\fIvoid\fP -.br -\fB\%archive_entry_set_rdev\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%dev_t\fP); -.br -\fIvoid\fP -.br -\fB\%archive_entry_set_rdevmajor\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%dev_t\fP); -.br -\fIvoid\fP -.br -\fB\%archive_entry_set_rdevminor\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%dev_t\fP); -.br -\fIvoid\fP -.br -\fB\%archive_entry_set_size\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%int64_t\fP); -.br -\fIvoid\fP -.br -\fB\%archive_entry_set_symlink\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ char\ *\fP); -.br -\fIvoid\fP -.br -\fB\%archive_entry_set_uid\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%uid_t\fP); -.br -\fIvoid\fP -.br -\fB\%archive_entry_set_uname\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ char\ *\fP); -.br -\fIint64_t\fP -.br -\fB\%archive_entry_size\fP(\fI\%struct\ archive_entry\ *\fP); -.br -\fIconst char *\fP -.br -\fB\%archive_entry_sourcepath\fP(\fI\%struct\ archive_entry\ *\fP); -.br -\fIconst struct stat *\fP -.br -\fB\%archive_entry_stat\fP(\fI\%struct\ archive_entry\ *\fP); -.br -\fIconst char *\fP -.br -\fB\%archive_entry_symlink\fP(\fI\%struct\ archive_entry\ *\fP); -.br -\fIconst char *\fP -.br -\fB\%archive_entry_uname\fP(\fI\%struct\ archive_entry\ *\fP); -.SH DESCRIPTION -.ad l -These functions create and manipulate data objects that -represent entries within an archive. -You can think of a -Tn struct archive_entry -as a heavy-duty version of -Tn struct stat: -it includes everything from -Tn struct stat -plus associated pathname, textual group and user names, etc. -These objects are used by -\fBlibarchive\fP(3) -to represent the metadata associated with a particular -entry in an archive. -.SS Create and Destroy -There are functions to allocate, destroy, clear, and copy -\fIarchive_entry\fP -objects: -.RS 5 -.TP -\fB\%archive_entry_clear\fP() -Erases the object, resetting all internal fields to the -same state as a newly-created object. -This is provided to allow you to quickly recycle objects -without thrashing the heap. -.TP -\fB\%archive_entry_clone\fP() -A deep copy operation; all text fields are duplicated. -.TP -\fB\%archive_entry_free\fP() -Releases the -Tn struct archive_entry -object. -.TP -\fB\%archive_entry_new\fP() -Allocate and return a blank -Tn struct archive_entry -object. -.RE -.SS Set and Get Functions -Most of the functions here set or read entries in an object. -Such functions have one of the following forms: -.RS 5 -.TP -\fB\%archive_entry_set_XXXX\fP() -Stores the provided data in the object. -In particular, for strings, the pointer is stored, -not the referenced string. -.TP -\fB\%archive_entry_copy_XXXX\fP() -As above, except that the referenced data is copied -into the object. -.TP -\fB\%archive_entry_XXXX\fP() -Returns the specified data. -In the case of strings, a const-qualified pointer to -the string is returned. -.RE -String data can be set or accessed as wide character strings -or normal -\fIchar\fP -strings. -The functions that use wide character strings are suffixed with -\fB_w\fP. -Note that these are different representations of the same data: -For example, if you store a narrow string and read the corresponding -wide string, the object will transparently convert formats -using the current locale. -Similarly, if you store a wide string and then store a -narrow string for the same data, the previously-set wide string will -be discarded in favor of the new data. -.PP -There are a few set/get functions that merit additional description: -.RS 5 -.TP -\fB\%archive_entry_set_link\fP() -This function sets the symlink field if it is already set. -Otherwise, it sets the hardlink field. -.RE -.SS File Flags -File flags are transparently converted between a bitmap -representation and a textual format. -For example, if you set the bitmap and ask for text, the library -will build a canonical text format. -However, if you set a text format and request a text format, -you will get back the same text, even if it is ill-formed. -If you need to canonicalize a textual flags string, you should first set the -text form, then request the bitmap form, then use that to set the bitmap form. -Setting the bitmap format will clear the internal text representation -and force it to be reconstructed when you next request the text form. -.PP -The bitmap format consists of two integers, one containing bits -that should be set, the other specifying bits that should be -cleared. -Bits not mentioned in either bitmap will be ignored. -Usually, the bitmap of bits to be cleared will be set to zero. -In unusual circumstances, you can force a fully-specified set -of file flags by setting the bitmap of flags to clear to the complement -of the bitmap of flags to set. -(This differs from -\fBfflagstostr\fP(3), -which only includes names for set bits.) -Converting a bitmap to a textual string is a platform-specific -operation; bits that are not meaningful on the current platform -will be ignored. -.PP -The canonical text format is a comma-separated list of flag names. -The -\fB\%archive_entry_copy_fflags_text\fP() -and -\fB\%archive_entry_copy_fflags_text_w\fP() -functions parse the provided text and sets the internal bitmap values. -This is a platform-specific operation; names that are not meaningful -on the current platform will be ignored. -The function returns a pointer to the start of the first name that was not -recognized, or NULL if every name was recognized. -Note that every name--including names that follow an unrecognized name--will -be evaluated, and the bitmaps will be set to reflect every name that is -recognized. -(In particular, this differs from -\fBstrtofflags\fP(3), -which stops parsing at the first unrecognized name.) -.SS ACL Handling -XXX This needs serious help. -XXX -.PP -An -``Access Control List'' -(ACL) is a list of permissions that grant access to particular users or -groups beyond what would normally be provided by standard POSIX mode bits. -The ACL handling here addresses some deficiencies in the POSIX.1e draft 17 ACL -specification. -In particular, POSIX.1e draft 17 specifies several different formats, but -none of those formats include both textual user/group names and numeric -UIDs/GIDs. -.PP -XXX explain ACL stuff XXX -.SH SEE ALSO -.ad l -\fBarchive\fP(3) -.SH HISTORY -.ad l -The -\fB\%libarchive\fP -library first appeared in -FreeBSD 5.3. -.SH AUTHORS -.ad l --nosplit -The -\fB\%libarchive\fP -library was written by -Tim Kientzle \%<kientzle@acm.org.> diff --git a/libarchive/libarchive-2.8.0/doc/man/archive_read.3 b/libarchive/libarchive-2.8.0/doc/man/archive_read.3 deleted file mode 100644 index b1bd4f3..0000000 --- a/libarchive/libarchive-2.8.0/doc/man/archive_read.3 +++ /dev/null @@ -1,733 +0,0 @@ -.TH archive_read 3 "April 13, 2009" "" -.SH NAME -.ad l -\fB\%archive_read_new\fP, -\fB\%archive_read_set_filter_options\fP, -\fB\%archive_read_set_format_options\fP, -\fB\%archive_read_set_options\fP, -\fB\%archive_read_support_compression_all\fP, -\fB\%archive_read_support_compression_bzip2\fP, -\fB\%archive_read_support_compression_compress\fP, -\fB\%archive_read_support_compression_gzip\fP, -\fB\%archive_read_support_compression_lzma\fP, -\fB\%archive_read_support_compression_none\fP, -\fB\%archive_read_support_compression_xz\fP, -\fB\%archive_read_support_compression_program\fP, -\fB\%archive_read_support_compression_program_signature\fP, -\fB\%archive_read_support_format_all\fP, -\fB\%archive_read_support_format_ar\fP, -\fB\%archive_read_support_format_cpio\fP, -\fB\%archive_read_support_format_empty\fP, -\fB\%archive_read_support_format_iso9660\fP, -\fB\%archive_read_support_format_mtree,\fP -\fB\%archive_read_support_format_raw,\fP -\fB\%archive_read_support_format_tar\fP, -\fB\%archive_read_support_format_zip\fP, -\fB\%archive_read_open\fP, -\fB\%archive_read_open2\fP, -\fB\%archive_read_open_fd\fP, -\fB\%archive_read_open_FILE\fP, -\fB\%archive_read_open_filename\fP, -\fB\%archive_read_open_memory\fP, -\fB\%archive_read_next_header\fP, -\fB\%archive_read_next_header2\fP, -\fB\%archive_read_data\fP, -\fB\%archive_read_data_block\fP, -\fB\%archive_read_data_skip\fP, -\fB\%archive_read_data_into_buffer\fP, -\fB\%archive_read_data_into_fd\fP, -\fB\%archive_read_extract\fP, -\fB\%archive_read_extract2\fP, -\fB\%archive_read_extract_set_progress_callback\fP, -\fB\%archive_read_close\fP, -\fB\%archive_read_finish\fP -\- functions for reading streaming archives -.SH SYNOPSIS -.ad l -\fB#include <archive.h>\fP -.br -\fIstruct archive *\fP -.br -\fB\%archive_read_new\fP(\fI\%void\fP); -.br -\fIint\fP -.br -\fB\%archive_read_support_compression_all\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_read_support_compression_bzip2\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_read_support_compression_compress\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_read_support_compression_gzip\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_read_support_compression_lzma\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_read_support_compression_none\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_read_support_compression_xz\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_read_support_compression_program\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ char\ *cmd\fP); -.br -\fIint\fP -.br -\fB\%archive_read_support_compression_program_signature\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ char\ *cmd\fP, \fI\%const\ void\ *signature\fP, \fI\%size_t\ signature_length\fP); -.br -\fIint\fP -.br -\fB\%archive_read_support_format_all\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_read_support_format_ar\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_read_support_format_cpio\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_read_support_format_empty\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_read_support_format_iso9660\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_read_support_format_mtree\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_read_support_format_raw\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_read_support_format_tar\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_read_support_format_zip\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_read_set_filter_options\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ char\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_read_set_format_options\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ char\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_read_set_options\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ char\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_read_open\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *client_data\fP, \fI\%archive_open_callback\ *\fP, \fI\%archive_read_callback\ *\fP, \fI\%archive_close_callback\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_read_open2\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *client_data\fP, \fI\%archive_open_callback\ *\fP, \fI\%archive_read_callback\ *\fP, \fI\%archive_skip_callback\ *\fP, \fI\%archive_close_callback\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_read_open_FILE\fP(\fI\%struct\ archive\ *\fP, \fI\%FILE\ *file\fP); -.br -\fIint\fP -.br -\fB\%archive_read_open_fd\fP(\fI\%struct\ archive\ *\fP, \fI\%int\ fd\fP, \fI\%size_t\ block_size\fP); -.br -\fIint\fP -.br -\fB\%archive_read_open_filename\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ char\ *filename\fP, \fI\%size_t\ block_size\fP); -.br -\fIint\fP -.br -\fB\%archive_read_open_memory\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *buff\fP, \fI\%size_t\ size\fP); -.br -\fIint\fP -.br -\fB\%archive_read_next_header\fP(\fI\%struct\ archive\ *\fP, \fI\%struct\ archive_entry\ **\fP); -.br -\fIint\fP -.br -\fB\%archive_read_next_header2\fP(\fI\%struct\ archive\ *\fP, \fI\%struct\ archive_entry\ *\fP); -.br -\fIssize_t\fP -.br -\fB\%archive_read_data\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *buff\fP, \fI\%size_t\ len\fP); -.br -\fIint\fP -.br -\fB\%archive_read_data_block\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ void\ **buff\fP, \fI\%size_t\ *len\fP, \fI\%off_t\ *offset\fP); -.br -\fIint\fP -.br -\fB\%archive_read_data_skip\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_read_data_into_buffer\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *\fP, \fI\%ssize_t\ len\fP); -.br -\fIint\fP -.br -\fB\%archive_read_data_into_fd\fP(\fI\%struct\ archive\ *\fP, \fI\%int\ fd\fP); -.br -\fIint\fP -.br -\fB\%archive_read_extract\fP(\fI\%struct\ archive\ *\fP, \fI\%struct\ archive_entry\ *\fP, \fI\%int\ flags\fP); -.br -\fIint\fP -.br -\fB\%archive_read_extract2\fP(\fI\%struct\ archive\ *src\fP, \fI\%struct\ archive_entry\ *\fP, \fI\%struct\ archive\ *dest\fP); -.br -\fIvoid\fP -.br -\fB\%archive_read_extract_set_progress_callback\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ (*func)(void\ *)\fP, \fI\%void\ *user_data\fP); -.br -\fIint\fP -.br -\fB\%archive_read_close\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_read_finish\fP(\fI\%struct\ archive\ *\fP); -.SH DESCRIPTION -.ad l -These functions provide a complete API for reading streaming archives. -The general process is to first create the -Tn struct archive -object, set options, initialize the reader, iterate over the archive -headers and associated data, then close the archive and release all -resources. -The following summary describes the functions in approximately the -order they would be used: -.RS 5 -.TP -\fB\%archive_read_new\fP() -Allocates and initializes a -Tn struct archive -object suitable for reading from an archive. -.TP -\fB\%archive_read_support_compression_bzip2\fP(), -\fB\%archive_read_support_compression_compress\fP(), -\fB\%archive_read_support_compression_gzip\fP(), -\fB\%archive_read_support_compression_lzma\fP(), -\fB\%archive_read_support_compression_none\fP(), -\fB\%archive_read_support_compression_xz\fP() -Enables auto-detection code and decompression support for the -specified compression. -Returns -\fBARCHIVE_OK\fP -if the compression is fully supported, or -\fBARCHIVE_WARN\fP -if the compression is supported only through an external program. -Note that decompression using an external program is usually slower than -decompression through built-in libraries. -Note that -``none'' -is always enabled by default. -.TP -\fB\%archive_read_support_compression_all\fP() -Enables all available decompression filters. -.TP -\fB\%archive_read_support_compression_program\fP() -Data is fed through the specified external program before being dearchived. -Note that this disables automatic detection of the compression format, -so it makes no sense to specify this in conjunction with any other -decompression option. -.TP -\fB\%archive_read_support_compression_program_signature\fP() -This feeds data through the specified external program -but only if the initial bytes of the data match the specified -signature value. -.TP -\fB\%archive_read_support_format_all\fP(), -\fB\%archive_read_support_format_ar\fP(), -\fB\%archive_read_support_format_cpio\fP(), -\fB\%archive_read_support_format_empty\fP(), -\fB\%archive_read_support_format_iso9660\fP(), -\fB\%archive_read_support_format_mtree\fP(), -\fB\%archive_read_support_format_tar\fP(), -\fB\%archive_read_support_format_zip\fP() -Enables support---including auto-detection code---for the -specified archive format. -For example, -\fB\%archive_read_support_format_tar\fP() -enables support for a variety of standard tar formats, old-style tar, -ustar, pax interchange format, and many common variants. -For convenience, -\fB\%archive_read_support_format_all\fP() -enables support for all available formats. -Only empty archives are supported by default. -.TP -\fB\%archive_read_support_format_raw\fP() -The -``raw'' -format handler allows libarchive to be used to read arbitrary data. -It treats any data stream as an archive with a single entry. -The pathname of this entry is -``data ;'' -all other entry fields are unset. -This is not enabled by -\fB\%archive_read_support_format_all\fP() -in order to avoid erroneous handling of damaged archives. -.TP -\fB\%archive_read_set_filter_options\fP(), -\fB\%archive_read_set_format_options\fP(), -\fB\%archive_read_set_options\fP() -Specifies options that will be passed to currently-registered -filters (including decompression filters) and/or format readers. -The argument is a comma-separated list of individual options. -Individual options have one of the following forms: -.RS 5 -.TP -\fIoption=value\fP -The option/value pair will be provided to every module. -Modules that do not accept an option with this name will ignore it. -.TP -\fIoption\fP -The option will be provided to every module with a value of -``1''. -.TP -\fI!option\fP -The option will be provided to every module with a NULL value. -.TP -\fImodule:option=value\fP, \fImodule:option\fP, \fImodule:!option\fP -As above, but the corresponding option and value will be provided -only to modules whose name matches -\fImodule\fP. -.RE -The return value will be -\fBARCHIVE_OK\fP -if any module accepts the option, or -\fBARCHIVE_WARN\fP -if no module accepted the option, or -\fBARCHIVE_FATAL\fP -if there was a fatal error while attempting to process the option. -.PP -The currently supported options are: -.RS 5 -.TP -Format iso9660 -.RS 5 -.TP -\fBjoliet\fP -Support Joliet extensions. -Defaults to enabled, use -\fB!joliet\fP -to disable. -.RE -.RE -.TP -\fB\%archive_read_open\fP() -The same as -\fB\%archive_read_open2\fP(), -except that the skip callback is assumed to be -.BR NULL. -.TP -\fB\%archive_read_open2\fP() -Freeze the settings, open the archive, and prepare for reading entries. -This is the most generic version of this call, which accepts -four callback functions. -Most clients will want to use -\fB\%archive_read_open_filename\fP(), -\fB\%archive_read_open_FILE\fP(), -\fB\%archive_read_open_fd\fP(), -or -\fB\%archive_read_open_memory\fP() -instead. -The library invokes the client-provided functions to obtain -raw bytes from the archive. -.TP -\fB\%archive_read_open_FILE\fP() -Like -\fB\%archive_read_open\fP(), -except that it accepts a -\fIFILE *\fP -pointer. -This function should not be used with tape drives or other devices -that require strict I/O blocking. -.TP -\fB\%archive_read_open_fd\fP() -Like -\fB\%archive_read_open\fP(), -except that it accepts a file descriptor and block size rather than -a set of function pointers. -Note that the file descriptor will not be automatically closed at -end-of-archive. -This function is safe for use with tape drives or other blocked devices. -.TP -\fB\%archive_read_open_file\fP() -This is a deprecated synonym for -\fB\%archive_read_open_filename\fP(). -.TP -\fB\%archive_read_open_filename\fP() -Like -\fB\%archive_read_open\fP(), -except that it accepts a simple filename and a block size. -A NULL filename represents standard input. -This function is safe for use with tape drives or other blocked devices. -.TP -\fB\%archive_read_open_memory\fP() -Like -\fB\%archive_read_open\fP(), -except that it accepts a pointer and size of a block of -memory containing the archive data. -.TP -\fB\%archive_read_next_header\fP() -Read the header for the next entry and return a pointer to -a -Tn struct archive_entry. -This is a convenience wrapper around -\fB\%archive_read_next_header2\fP() -that reuses an internal -Tn struct archive_entry -object for each request. -.TP -\fB\%archive_read_next_header2\fP() -Read the header for the next entry and populate the provided -Tn struct archive_entry. -.TP -\fB\%archive_read_data\fP() -Read data associated with the header just read. -Internally, this is a convenience function that calls -\fB\%archive_read_data_block\fP() -and fills any gaps with nulls so that callers see a single -continuous stream of data. -.TP -\fB\%archive_read_data_block\fP() -Return the next available block of data for this entry. -Unlike -\fB\%archive_read_data\fP(), -the -\fB\%archive_read_data_block\fP() -function avoids copying data and allows you to correctly handle -sparse files, as supported by some archive formats. -The library guarantees that offsets will increase and that blocks -will not overlap. -Note that the blocks returned from this function can be much larger -than the block size read from disk, due to compression -and internal buffer optimizations. -.TP -\fB\%archive_read_data_skip\fP() -A convenience function that repeatedly calls -\fB\%archive_read_data_block\fP() -to skip all of the data for this archive entry. -.TP -\fB\%archive_read_data_into_buffer\fP() -This function is deprecated and will be removed. -Use -\fB\%archive_read_data\fP() -instead. -.TP -\fB\%archive_read_data_into_fd\fP() -A convenience function that repeatedly calls -\fB\%archive_read_data_block\fP() -to copy the entire entry to the provided file descriptor. -.TP -\fB\%archive_read_extract\fP(), \fB\%archive_read_extract_set_skip_file\fP() -A convenience function that wraps the corresponding -\fBarchive_write_disk\fP(3) -interfaces. -The first call to -\fB\%archive_read_extract\fP() -creates a restore object using -\fBarchive_write_disk_new\fP(3) -and -\fBarchive_write_disk_set_standard_lookup\fP(3), -then transparently invokes -\fBarchive_write_disk_set_options\fP(3), -\fBarchive_write_header\fP(3), -\fBarchive_write_data\fP(3), -and -\fBarchive_write_finish_entry\fP(3) -to create the entry on disk and copy data into it. -The -\fIflags\fP -argument is passed unmodified to -\fBarchive_write_disk_set_options\fP(3). -.TP -\fB\%archive_read_extract2\fP() -This is another version of -\fB\%archive_read_extract\fP() -that allows you to provide your own restore object. -In particular, this allows you to override the standard lookup functions -using -\fBarchive_write_disk_set_group_lookup\fP(3), -and -\fBarchive_write_disk_set_user_lookup\fP(3). -Note that -\fB\%archive_read_extract2\fP() -does not accept a -\fIflags\fP -argument; you should use -\fB\%archive_write_disk_set_options\fP() -to set the restore options yourself. -.TP -\fB\%archive_read_extract_set_progress_callback\fP() -Sets a pointer to a user-defined callback that can be used -for updating progress displays during extraction. -The progress function will be invoked during the extraction of large -regular files. -The progress function will be invoked with the pointer provided to this call. -Generally, the data pointed to should include a reference to the archive -object and the archive_entry object so that various statistics -can be retrieved for the progress display. -.TP -\fB\%archive_read_close\fP() -Complete the archive and invoke the close callback. -.TP -\fB\%archive_read_finish\fP() -Invokes -\fB\%archive_read_close\fP() -if it was not invoked manually, then release all resources. -Note: In libarchive 1.x, this function was declared to return -\fIvoid ,\fP -which made it impossible to detect certain errors when -\fB\%archive_read_close\fP() -was invoked implicitly from this function. -The declaration is corrected beginning with libarchive 2.0. -.RE -.PP -Note that the library determines most of the relevant information about -the archive by inspection. -In particular, it automatically detects -\fBgzip\fP(1) -or -\fBbzip2\fP(1) -compression and transparently performs the appropriate decompression. -It also automatically detects the archive format. -.PP -A complete description of the -Tn struct archive -and -Tn struct archive_entry -objects can be found in the overview manual page for -\fBlibarchive\fP(3). -.SH CLIENT CALLBACKS -.ad l -The callback functions must match the following prototypes: -.RS 5 -.IP -\fItypedef ssize_t\fP -\fB\%archive_read_callback\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *client_data\fP, \fI\%const\ void\ **buffer\fP) -.IP -\fItypedef int\fP -\fB\%archive_skip_callback\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *client_data\fP, \fI\%size_t\ request\fP) -.IP -\fItypedef int\fP -\fB\%archive_open_callback\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *client_data\fP) -.IP -\fItypedef int\fP -\fB\%archive_close_callback\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *client_data\fP) -.RE -.PP -The open callback is invoked by -\fB\%archive_open\fP(). -It should return -\fBARCHIVE_OK\fP -if the underlying file or data source is successfully -opened. -If the open fails, it should call -\fB\%archive_set_error\fP() -to register an error code and message and return -\fBARCHIVE_FATAL\fP. -.PP -The read callback is invoked whenever the library -requires raw bytes from the archive. -The read callback should read data into a buffer, -set the -.RS 4 -const void **buffer -.RE -argument to point to the available data, and -return a count of the number of bytes available. -The library will invoke the read callback again -only after it has consumed this data. -The library imposes no constraints on the size -of the data blocks returned. -On end-of-file, the read callback should -return zero. -On error, the read callback should invoke -\fB\%archive_set_error\fP() -to register an error code and message and -return -1. -.PP -The skip callback is invoked when the -library wants to ignore a block of data. -The return value is the number of bytes actually -skipped, which may differ from the request. -If the callback cannot skip data, it should return -zero. -If the skip callback is not provided (the -function pointer is -.BR NULL ), -the library will invoke the read function -instead and simply discard the result. -A skip callback can provide significant -performance gains when reading uncompressed -archives from slow disk drives or other media -that can skip quickly. -.PP -The close callback is invoked by archive_close when -the archive processing is complete. -The callback should return -\fBARCHIVE_OK\fP -on success. -On failure, the callback should invoke -\fB\%archive_set_error\fP() -to register an error code and message and -return -\fBARCHIVE_FATAL.\fP -.SH EXAMPLE -.ad l -The following illustrates basic usage of the library. -In this example, -the callback functions are simply wrappers around the standard -\fBopen\fP(2), -\fBread\fP(2), -and -\fBclose\fP(2) -system calls. -.RS 4 -.nf -void -list_archive(const char *name) -{ - struct mydata *mydata; - struct archive *a; - struct archive_entry *entry; - mydata = malloc(sizeof(struct mydata)); - a = archive_read_new(); - mydata->name = name; - archive_read_support_compression_all(a); - archive_read_support_format_all(a); - archive_read_open(a, mydata, myopen, myread, myclose); - while (archive_read_next_header(a, &entry) == ARCHIVE_OK) { - printf("%s\\n",archive_entry_pathname(entry)); - archive_read_data_skip(a); - } - archive_read_finish(a); - free(mydata); -} -ssize_t -myread(struct archive *a, void *client_data, const void **buff) -{ - struct mydata *mydata = client_data; - *buff = mydata->buff; - return (read(mydata->fd, mydata->buff, 10240)); -} -int -myopen(struct archive *a, void *client_data) -{ - struct mydata *mydata = client_data; - mydata->fd = open(mydata->name, O_RDONLY); - return (mydata->fd >= 0 ? ARCHIVE_OK : ARCHIVE_FATAL); -} -int -myclose(struct archive *a, void *client_data) -{ - struct mydata *mydata = client_data; - if (mydata->fd > 0) - close(mydata->fd); - return (ARCHIVE_OK); -} -.RE -.SH RETURN VALUES -.ad l -Most functions return zero on success, non-zero on error. -The possible return codes include: -\fBARCHIVE_OK\fP -(the operation succeeded), -\fBARCHIVE_WARN\fP -(the operation succeeded but a non-critical error was encountered), -\fBARCHIVE_EOF\fP -(end-of-archive was encountered), -\fBARCHIVE_RETRY\fP -(the operation failed but can be retried), -and -\fBARCHIVE_FATAL\fP -(there was a fatal error; the archive should be closed immediately). -Detailed error codes and textual descriptions are available from the -\fB\%archive_errno\fP() -and -\fB\%archive_error_string\fP() -functions. -.PP -\fB\%archive_read_new\fP() -returns a pointer to a freshly allocated -Tn struct archive -object. -It returns -.BR NULL -on error. -.PP -\fB\%archive_read_data\fP() -returns a count of bytes actually read or zero at the end of the entry. -On error, a value of -\fBARCHIVE_FATAL\fP, -\fBARCHIVE_WARN\fP, -or -\fBARCHIVE_RETRY\fP -is returned and an error code and textual description can be retrieved from the -\fB\%archive_errno\fP() -and -\fB\%archive_error_string\fP() -functions. -.PP -The library expects the client callbacks to behave similarly. -If there is an error, you can use -\fB\%archive_set_error\fP() -to set an appropriate error code and description, -then return one of the non-zero values above. -(Note that the value eventually returned to the client may -not be the same; many errors that are not critical at the level -of basic I/O can prevent the archive from being properly read, -thus most I/O errors eventually cause -\fBARCHIVE_FATAL\fP -to be returned.) -.SH SEE ALSO -.ad l -\fBtar\fP(1), -\fBarchive\fP(3), -\fBarchive_util\fP(3), -\fBtar\fP(5) -.SH HISTORY -.ad l -The -\fB\%libarchive\fP -library first appeared in -FreeBSD 5.3. -.SH AUTHORS -.ad l --nosplit -The -\fB\%libarchive\fP -library was written by -Tim Kientzle \%<kientzle@acm.org.> -.SH BUGS -.ad l -Many traditional archiver programs treat -empty files as valid empty archives. -For example, many implementations of -\fBtar\fP(1) -allow you to append entries to an empty file. -Of course, it is impossible to determine the format of an empty file -by inspecting the contents, so this library treats empty files as -having a special -``empty'' -format. diff --git a/libarchive/libarchive-2.8.0/doc/man/archive_read_disk.3 b/libarchive/libarchive-2.8.0/doc/man/archive_read_disk.3 deleted file mode 100644 index 6e10f4f..0000000 --- a/libarchive/libarchive-2.8.0/doc/man/archive_read_disk.3 +++ /dev/null @@ -1,300 +0,0 @@ -.TH archive_read_disk 3 "March 10, 2009" "" -.SH NAME -.ad l -\fB\%archive_read_disk_new\fP, -\fB\%archive_read_disk_set_symlink_logical\fP, -\fB\%archive_read_disk_set_symlink_physical\fP, -\fB\%archive_read_disk_set_symlink_hybrid\fP, -\fB\%archive_read_disk_entry_from_file\fP, -\fB\%archive_read_disk_gname\fP, -\fB\%archive_read_disk_uname\fP, -\fB\%archive_read_disk_set_uname_lookup\fP, -\fB\%archive_read_disk_set_gname_lookup\fP, -\fB\%archive_read_disk_set_standard_lookup\fP, -\fB\%archive_read_close\fP, -\fB\%archive_read_finish\fP -\- functions for reading objects from disk -.SH SYNOPSIS -.ad l -\fB#include <archive.h>\fP -.br -\fIstruct archive *\fP -.br -\fB\%archive_read_disk_new\fP(\fI\%void\fP); -.br -\fIint\fP -.br -\fB\%archive_read_disk_set_symlink_logical\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_read_disk_set_symlink_physical\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_read_disk_set_symlink_hybrid\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_read_disk_gname\fP(\fI\%struct\ archive\ *\fP, \fI\%gid_t\fP); -.br -\fIint\fP -.br -\fB\%archive_read_disk_uname\fP(\fI\%struct\ archive\ *\fP, \fI\%uid_t\fP); -.br -\fIint\fP -.br -\fB\%archive_read_disk_set_gname_lookup\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *\fP, \fI\%const\ char\ *(*lookup)(void\ *,\ gid_t)\fP, \fI\%void\ (*cleanup)(void\ *)\fP); -.br -\fIint\fP -.br -\fB\%archive_read_disk_set_uname_lookup\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *\fP, \fI\%const\ char\ *(*lookup)(void\ *,\ uid_t)\fP, \fI\%void\ (*cleanup)(void\ *)\fP); -.br -\fIint\fP -.br -\fB\%archive_read_disk_set_standard_lookup\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_read_disk_entry_from_file\fP(\fI\%struct\ archive\ *\fP, \fI\%struct\ archive_entry\ *\fP, \fI\%int\ fd\fP, \fI\%const\ struct\ stat\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_read_close\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_read_finish\fP(\fI\%struct\ archive\ *\fP); -.SH DESCRIPTION -.ad l -These functions provide an API for reading information about -objects on disk. -In particular, they provide an interface for populating -Tn struct archive_entry -objects. -.RS 5 -.TP -\fB\%archive_read_disk_new\fP() -Allocates and initializes a -Tn struct archive -object suitable for reading object information from disk. -.TP -\fB\%archive_read_disk_set_symlink_logical\fP(), -\fB\%archive_read_disk_set_symlink_physical\fP(), -\fB\%archive_read_disk_set_symlink_hybrid\fP() -This sets the mode used for handling symbolic links. -The -``logical'' -mode follows all symbolic links. -The -``physical'' -mode does not follow any symbolic links. -The -``hybrid'' -mode currently behaves identically to the -``logical'' -mode. -.TP -\fB\%archive_read_disk_gname\fP(), -\fB\%archive_read_disk_uname\fP() -Returns a user or group name given a gid or uid value. -By default, these always return a NULL string. -.TP -\fB\%archive_read_disk_set_gname_lookup\fP(), -\fB\%archive_read_disk_set_uname_lookup\fP() -These allow you to override the functions used for -user and group name lookups. -You may also provide a -Tn void * -pointer to a private data structure and a cleanup function for -that data. -The cleanup function will be invoked when the -Tn struct archive -object is destroyed or when new lookup functions are registered. -.TP -\fB\%archive_read_disk_set_standard_lookup\fP() -This convenience function installs a standard set of user -and group name lookup functions. -These functions use -\fBgetpwid\fP(3) -and -\fBgetgrid\fP(3) -to convert ids to names, defaulting to NULL if the names cannot -be looked up. -These functions also implement a simple memory cache to reduce -the number of calls to -\fBgetpwid\fP(3) -and -\fBgetgrid\fP(3). -.TP -\fB\%archive_read_disk_entry_from_file\fP() -Populates a -Tn struct archive_entry -object with information about a particular file. -The -Tn archive_entry -object must have already been created with -\fBarchive_entry_new\fP(3) -and at least one of the source path or path fields must already be set. -(If both are set, the source path will be used.) -.PP -Information is read from disk using the path name from the -Tn struct archive_entry -object. -If a file descriptor is provided, some information will be obtained using -that file descriptor, on platforms that support the appropriate -system calls. -.PP -If a pointer to a -Tn struct stat -is provided, information from that structure will be used instead -of reading from the disk where appropriate. -This can provide performance benefits in scenarios where -Tn struct stat -information has already been read from the disk as a side effect -of some other operation. -(For example, directory traversal libraries often provide this information.) -.PP -Where necessary, user and group ids are converted to user and group names -using the currently registered lookup functions above. -This affects the file ownership fields and ACL values in the -Tn struct archive_entry -object. -.TP -\fB\%archive_read_close\fP() -This currently does nothing. -.TP -\fB\%archive_write_finish\fP() -Invokes -\fB\%archive_write_close\fP() -if it was not invoked manually, then releases all resources. -.RE -More information about the -\fIstruct\fP archive -object and the overall design of the library can be found in the -\fBlibarchive\fP(3) -overview. -.SH EXAMPLE -.ad l -The following illustrates basic usage of the library by -showing how to use it to copy an item on disk into an archive. -.RS 4 -.nf -void -file_to_archive(struct archive *a, const char *name) -{ - char buff[8192]; - size_t bytes_read; - struct archive *ard; - struct archive_entry *entry; - int fd; - ard = archive_read_disk_new(); - archive_read_disk_set_standard_lookup(ard); - entry = archive_entry_new(); - fd = open(name, O_RDONLY); - if (fd < 0) - return; - archive_entry_copy_sourcepath(entry, name); - archive_read_disk_entry_from_file(ard, entry, fd, NULL); - archive_write_header(a, entry); - while ((bytes_read = read(fd, buff, sizeof(buff))) > 0) - archive_write_data(a, buff, bytes_read); - archive_write_finish_entry(a); - archive_read_finish(ard); - archive_entry_free(entry); -} -.RE -.SH RETURN VALUES -.ad l -Most functions return -\fBARCHIVE_OK\fP -(zero) on success, or one of several negative -error codes for errors. -Specific error codes include: -\fBARCHIVE_RETRY\fP -for operations that might succeed if retried, -\fBARCHIVE_WARN\fP -for unusual conditions that do not prevent further operations, and -\fBARCHIVE_FATAL\fP -for serious errors that make remaining operations impossible. -The -\fBarchive_errno\fP(3) -and -\fBarchive_error_string\fP(3) -functions can be used to retrieve an appropriate error code and a -textual error message. -(See -\fBarchive_util\fP(3) -for details.) -.PP -\fB\%archive_read_disk_new\fP() -returns a pointer to a newly-allocated -Tn struct archive -object or NULL if the allocation failed for any reason. -.PP -\fB\%archive_read_disk_gname\fP() -and -\fB\%archive_read_disk_uname\fP() -return -Tn const char * -pointers to the textual name or NULL if the lookup failed for any reason. -The returned pointer points to internal storage that -may be reused on the next call to either of these functions; -callers should copy the string if they need to continue accessing it. -.PP -.SH SEE ALSO -.ad l -\fBarchive_read\fP(3), -\fBarchive_write\fP(3), -\fBarchive_write_disk\fP(3), -\fBtar\fP(1), -\fBlibarchive\fP(3) -.SH HISTORY -.ad l -The -\fB\%libarchive\fP -library first appeared in -FreeBSD 5.3. -The -\fB\%archive_read_disk\fP -interface was added to -\fB\%libarchive\fP 2.6 -and first appeared in -FreeBSD 8.0. -.SH AUTHORS -.ad l --nosplit -The -\fB\%libarchive\fP -library was written by -Tim Kientzle \%<kientzle@freebsd.org.> -.SH BUGS -.ad l -The -``standard'' -user name and group name lookup functions are not the defaults because -\fBgetgrid\fP(3) -and -\fBgetpwid\fP(3) -are sometimes too large for particular applications. -The current design allows the application author to use a more -compact implementation when appropriate. -.PP -The full list of metadata read from disk by -\fB\%archive_read_disk_entry_from_file\fP() -is necessarily system-dependent. -.PP -The -\fB\%archive_read_disk_entry_from_file\fP() -function reads as much information as it can from disk. -Some method should be provided to limit this so that clients who -do not need ACLs, for instance, can avoid the extra work needed -to look up such information. -.PP -This API should provide a set of methods for walking a directory tree. -That would make it a direct parallel of the -\fBarchive_read\fP(3) -API. -When such methods are implemented, the -``hybrid'' -symbolic link mode will make sense. diff --git a/libarchive/libarchive-2.8.0/doc/man/archive_util.3 b/libarchive/libarchive-2.8.0/doc/man/archive_util.3 deleted file mode 100644 index 60375af..0000000 --- a/libarchive/libarchive-2.8.0/doc/man/archive_util.3 +++ /dev/null @@ -1,163 +0,0 @@ -.TH archive_util 3 "January 8, 2005" "" -.SH NAME -.ad l -\fB\%archive_clear_error\fP, -\fB\%archive_compression\fP, -\fB\%archive_compression_name\fP, -\fB\%archive_copy_error\fP, -\fB\%archive_errno\fP, -\fB\%archive_error_string\fP, -\fB\%archive_file_count\fP, -\fB\%archive_format\fP, -\fB\%archive_format_name\fP, -\fB\%archive_set_error\fP -\- libarchive utility functions -.SH SYNOPSIS -.ad l -\fB#include <archive.h>\fP -.br -\fIvoid\fP -.br -\fB\%archive_clear_error\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_compression\fP(\fI\%struct\ archive\ *\fP); -.br -\fIconst char *\fP -.br -\fB\%archive_compression_name\fP(\fI\%struct\ archive\ *\fP); -.br -\fIvoid\fP -.br -\fB\%archive_copy_error\fP(\fI\%struct\ archive\ *\fP, \fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_errno\fP(\fI\%struct\ archive\ *\fP); -.br -\fIconst char *\fP -.br -\fB\%archive_error_string\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_file_count\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_format\fP(\fI\%struct\ archive\ *\fP); -.br -\fIconst char *\fP -.br -\fB\%archive_format_name\fP(\fI\%struct\ archive\ *\fP); -.br -\fIvoid\fP -.br -\fB\%archive_set_error\fP(\fI\%struct\ archive\ *\fP, \fI\%int\ error_code\fP, \fI\%const\ char\ *fmt\fP, \fI\%...\fP); -.SH DESCRIPTION -.ad l -These functions provide access to various information about the -Tn struct archive -object used in the -\fBlibarchive\fP(3) -library. -.RS 5 -.TP -\fB\%archive_clear_error\fP() -Clears any error information left over from a previous call. -Not generally used in client code. -.TP -\fB\%archive_compression\fP() -Returns a numeric code indicating the current compression. -This value is set by -\fB\%archive_read_open\fP(). -.TP -\fB\%archive_compression_name\fP() -Returns a text description of the current compression suitable for display. -.TP -\fB\%archive_copy_error\fP() -Copies error information from one archive to another. -.TP -\fB\%archive_errno\fP() -Returns a numeric error code (see -\fBerrno\fP(2)) -indicating the reason for the most recent error return. -.TP -\fB\%archive_error_string\fP() -Returns a textual error message suitable for display. -The error message here is usually more specific than that -obtained from passing the result of -\fB\%archive_errno\fP() -to -\fBstrerror\fP(3). -.TP -\fB\%archive_file_count\fP() -Returns a count of the number of files processed by this archive object. -The count is incremented by calls to -\fBarchive_write_header\fP() -or -\fBarchive_read_next_header\fP(.) -.TP -\fB\%archive_format\fP() -Returns a numeric code indicating the format of the current -archive entry. -This value is set by a successful call to -\fB\%archive_read_next_header\fP(). -Note that it is common for this value to change from -entry to entry. -For example, a tar archive might have several entries that -utilize GNU tar extensions and several entries that do not. -These entries will have different format codes. -.TP -\fB\%archive_format_name\fP() -A textual description of the format of the current entry. -.TP -\fB\%archive_set_error\fP() -Sets the numeric error code and error description that will be returned -by -\fB\%archive_errno\fP() -and -\fB\%archive_error_string\fP(). -This function should be used within I/O callbacks to set system-specific -error codes and error descriptions. -This function accepts a printf-like format string and arguments. -However, you should be careful to use only the following printf -format specifiers: -``%c'', -``%d'', -``%jd'', -``%jo'', -``%ju'', -``%jx'', -``%ld'', -``%lo'', -``%lu'', -``%lx'', -``%o'', -``%u'', -``%s'', -``%x'', -``%%''. -Field-width specifiers and other printf features are -not uniformly supported and should not be used. -.RE -.SH SEE ALSO -.ad l -\fBarchive_read\fP(3), -\fBarchive_write\fP(3), -\fBlibarchive\fP(3), -\fBprintf\fP(3) -.SH HISTORY -.ad l -The -\fB\%libarchive\fP -library first appeared in -FreeBSD 5.3. -.SH AUTHORS -.ad l --nosplit -The -\fB\%libarchive\fP -library was written by -Tim Kientzle \%<kientzle@acm.org.> diff --git a/libarchive/libarchive-2.8.0/doc/man/archive_write.3 b/libarchive/libarchive-2.8.0/doc/man/archive_write.3 deleted file mode 100644 index b485dcf..0000000 --- a/libarchive/libarchive-2.8.0/doc/man/archive_write.3 +++ /dev/null @@ -1,670 +0,0 @@ -.TH archive_write 3 "May 11, 2008" "" -.SH NAME -.ad l -\fB\%archive_write_new\fP, -\fB\%archive_write_set_format_cpio\fP, -\fB\%archive_write_set_format_pax\fP, -\fB\%archive_write_set_format_pax_restricted\fP, -\fB\%archive_write_set_format_shar\fP, -\fB\%archive_write_set_format_shar_binary\fP, -\fB\%archive_write_set_format_ustar\fP, -\fB\%archive_write_get_bytes_per_block\fP, -\fB\%archive_write_set_bytes_per_block\fP, -\fB\%archive_write_set_bytes_in_last_block\fP, -\fB\%archive_write_set_compression_bzip2\fP, -\fB\%archive_write_set_compression_compress\fP, -\fB\%archive_write_set_compression_gzip\fP, -\fB\%archive_write_set_compression_none\fP, -\fB\%archive_write_set_compression_program\fP, -\fB\%archive_write_set_compressor_options\fP, -\fB\%archive_write_set_format_options\fP, -\fB\%archive_write_set_options\fP, -\fB\%archive_write_open\fP, -\fB\%archive_write_open_fd\fP, -\fB\%archive_write_open_FILE\fP, -\fB\%archive_write_open_filename\fP, -\fB\%archive_write_open_memory\fP, -\fB\%archive_write_header\fP, -\fB\%archive_write_data\fP, -\fB\%archive_write_finish_entry\fP, -\fB\%archive_write_close\fP, -\fB\%archive_write_finish\fP -\- functions for creating archives -.SH SYNOPSIS -.ad l -\fB#include <archive.h>\fP -.br -\fIstruct archive *\fP -.br -\fB\%archive_write_new\fP(\fI\%void\fP); -.br -\fIint\fP -.br -\fB\%archive_write_get_bytes_per_block\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_write_set_bytes_per_block\fP(\fI\%struct\ archive\ *\fP, \fI\%int\ bytes_per_block\fP); -.br -\fIint\fP -.br -\fB\%archive_write_set_bytes_in_last_block\fP(\fI\%struct\ archive\ *\fP, \fI\%int\fP); -.br -\fIint\fP -.br -\fB\%archive_write_set_compression_bzip2\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_write_set_compression_compress\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_write_set_compression_gzip\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_write_set_compression_none\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_write_set_compression_program\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ char\ *\ cmd\fP); -.br -\fIint\fP -.br -\fB\%archive_write_set_format_cpio\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_write_set_format_pax\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_write_set_format_pax_restricted\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_write_set_format_shar\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_write_set_format_shar_binary\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_write_set_format_ustar\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_write_set_format_options\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ char\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_write_set_compressor_options\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ char\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_write_set_options\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ char\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_write_open\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *client_data\fP, \fI\%archive_open_callback\ *\fP, \fI\%archive_write_callback\ *\fP, \fI\%archive_close_callback\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_write_open_fd\fP(\fI\%struct\ archive\ *\fP, \fI\%int\ fd\fP); -.br -\fIint\fP -.br -\fB\%archive_write_open_FILE\fP(\fI\%struct\ archive\ *\fP, \fI\%FILE\ *file\fP); -.br -\fIint\fP -.br -\fB\%archive_write_open_filename\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ char\ *filename\fP); -.br -\fIint\fP -.br -\fB\%archive_write_open_memory\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *buffer\fP, \fI\%size_t\ bufferSize\fP, \fI\%size_t\ *outUsed\fP); -.br -\fIint\fP -.br -\fB\%archive_write_header\fP(\fI\%struct\ archive\ *\fP, \fI\%struct\ archive_entry\ *\fP); -.br -\fIssize_t\fP -.br -\fB\%archive_write_data\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ void\ *\fP, \fI\%size_t\fP); -.br -\fIint\fP -.br -\fB\%archive_write_finish_entry\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_write_close\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_write_finish\fP(\fI\%struct\ archive\ *\fP); -.SH DESCRIPTION -.ad l -These functions provide a complete API for creating streaming -archive files. -The general process is to first create the -Tn struct archive -object, set any desired options, initialize the archive, append entries, then -close the archive and release all resources. -The following summary describes the functions in approximately -the order they are ordinarily used: -.RS 5 -.TP -\fB\%archive_write_new\fP() -Allocates and initializes a -Tn struct archive -object suitable for writing a tar archive. -.TP -\fB\%archive_write_set_bytes_per_block\fP() -Sets the block size used for writing the archive data. -Every call to the write callback function, except possibly the last one, will -use this value for the length. -The third parameter is a boolean that specifies whether or not the final block -written will be padded to the full block size. -If it is zero, the last block will not be padded. -If it is non-zero, padding will be added both before and after compression. -The default is to use a block size of 10240 bytes and to pad the last block. -Note that a block size of zero will suppress internal blocking -and cause writes to be sent directly to the write callback as they occur. -.TP -\fB\%archive_write_get_bytes_per_block\fP() -Retrieve the block size to be used for writing. -A value of -1 here indicates that the library should use default values. -A value of zero indicates that internal blocking is suppressed. -.TP -\fB\%archive_write_set_bytes_in_last_block\fP() -Sets the block size used for writing the last block. -If this value is zero, the last block will be padded to the same size -as the other blocks. -Otherwise, the final block will be padded to a multiple of this size. -In particular, setting it to 1 will cause the final block to not be padded. -For compressed output, any padding generated by this option -is applied only after the compression. -The uncompressed data is always unpadded. -The default is to pad the last block to the full block size (note that -\fB\%archive_write_open_filename\fP() -will set this based on the file type). -Unlike the other -``set'' -functions, this function can be called after the archive is opened. -.TP -\fB\%archive_write_get_bytes_in_last_block\fP() -Retrieve the currently-set value for last block size. -A value of -1 here indicates that the library should use default values. -.TP -\fB\%archive_write_set_format_cpio\fP(), -\fB\%archive_write_set_format_pax\fP(), -\fB\%archive_write_set_format_pax_restricted\fP(), -\fB\%archive_write_set_format_shar\fP(), -\fB\%archive_write_set_format_shar_binary\fP(), -\fB\%archive_write_set_format_ustar\fP() -Sets the format that will be used for the archive. -The library can write -POSIX octet-oriented cpio format archives, -POSIX-standard -``pax interchange'' -format archives, -traditional -``shar'' -archives, -enhanced -``binary'' -shar archives that store a variety of file attributes and handle binary files, -and -POSIX-standard -``ustar'' -archives. -The pax interchange format is a backwards-compatible tar format that -adds key/value attributes to each entry and supports arbitrary -filenames, linknames, uids, sizes, etc. -``Restricted pax interchange format'' -is the library default; this is the same as pax format, but suppresses -the pax extended header for most normal files. -In most cases, this will result in ordinary ustar archives. -.TP -\fB\%archive_write_set_compression_bzip2\fP(), -\fB\%archive_write_set_compression_compress\fP(), -\fB\%archive_write_set_compression_gzip\fP(), -\fB\%archive_write_set_compression_none\fP() -The resulting archive will be compressed as specified. -Note that the compressed output is always properly blocked. -.TP -\fB\%archive_write_set_compression_program\fP() -The archive will be fed into the specified compression program. -The output of that program is blocked and written to the client -write callbacks. -.TP -\fB\%archive_write_set_compressor_options\fP(), -\fB\%archive_write_set_format_options\fP(), -\fB\%archive_write_set_options\fP() -Specifies options that will be passed to the currently-enabled -compressor and/or format writer. -The argument is a comma-separated list of individual options. -Individual options have one of the following forms: -.RS 5 -.TP -\fIoption=value\fP -The option/value pair will be provided to every module. -Modules that do not accept an option with this name will ignore it. -.TP -\fIoption\fP -The option will be provided to every module with a value of -``1''. -.TP -\fI!option\fP -The option will be provided to every module with a NULL value. -.TP -\fImodule:option=value\fP, \fImodule:option\fP, \fImodule:!option\fP -As above, but the corresponding option and value will be provided -only to modules whose name matches -\fImodule\fP. -.RE -The return value will be -\fBARCHIVE_OK\fP -if any module accepts the option, or -\fBARCHIVE_WARN\fP -if no module accepted the option, or -\fBARCHIVE_FATAL\fP -if there was a fatal error while attempting to process the option. -.PP -The currently supported options are: -.RS 5 -.TP -Compressor gzip -.RS 5 -.TP -\fBcompression-level\fP -The value is interpreted as a decimal integer specifying the -gzip compression level. -.RE -.TP -Compressor xz -.RS 5 -.TP -\fBcompression-level\fP -The value is interpreted as a decimal integer specifying the -compression level. -.RE -.TP -Format mtree -.RS 5 -.TP -\fBcksum\fP, \fBdevice\fP, \fBflags\fP, \fBgid\fP, \fBgname\fP, \fBindent\fP, \fBlink\fP, \fBmd5\fP, \fBmode\fP, \fBnlink\fP, \fBrmd160\fP, \fBsha1\fP, \fBsha256\fP, \fBsha384\fP, \fBsha512\fP, \fBsize\fP, \fBtime\fP, \fBuid\fP, \fBuname\fP -Enable a particular keyword in the mtree output. -Prefix with an exclamation mark to disable the corresponding keyword. -The default is equivalent to -``device, flags, gid, gname, link, mode, nlink, size, time, type, uid, uname''. -.TP -\fBall\fP -Enables all of the above keywords. -.TP -\fBuse-set\fP -Enables generation of -\fB/set\fP -lines that specify default values for the following files and/or directories. -.TP -\fBindent\fP -XXX needs explanation XXX -.RE -.RE -.TP -\fB\%archive_write_open\fP() -Freeze the settings, open the archive, and prepare for writing entries. -This is the most generic form of this function, which accepts -pointers to three callback functions which will be invoked by -the compression layer to write the constructed archive. -.TP -\fB\%archive_write_open_fd\fP() -A convenience form of -\fB\%archive_write_open\fP() -that accepts a file descriptor. -The -\fB\%archive_write_open_fd\fP() -function is safe for use with tape drives or other -block-oriented devices. -.TP -\fB\%archive_write_open_FILE\fP() -A convenience form of -\fB\%archive_write_open\fP() -that accepts a -\fIFILE *\fP -pointer. -Note that -\fB\%archive_write_open_FILE\fP() -is not safe for writing to tape drives or other devices -that require correct blocking. -.TP -\fB\%archive_write_open_file\fP() -A deprecated synonym for -\fB\%archive_write_open_filename\fP(). -.TP -\fB\%archive_write_open_filename\fP() -A convenience form of -\fB\%archive_write_open\fP() -that accepts a filename. -A NULL argument indicates that the output should be written to standard output; -an argument of -``-'' -will open a file with that name. -If you have not invoked -\fB\%archive_write_set_bytes_in_last_block\fP(), -then -\fB\%archive_write_open_filename\fP() -will adjust the last-block padding depending on the file: -it will enable padding when writing to standard output or -to a character or block device node, it will disable padding otherwise. -You can override this by manually invoking -\fB\%archive_write_set_bytes_in_last_block\fP() -before calling -\fB\%archive_write_open\fP(). -The -\fB\%archive_write_open_filename\fP() -function is safe for use with tape drives or other -block-oriented devices. -.TP -\fB\%archive_write_open_memory\fP() -A convenience form of -\fB\%archive_write_open\fP() -that accepts a pointer to a block of memory that will receive -the archive. -The final -\fIsize_t *\fP -argument points to a variable that will be updated -after each write to reflect how much of the buffer -is currently in use. -You should be careful to ensure that this variable -remains allocated until after the archive is -closed. -.TP -\fB\%archive_write_header\fP() -Build and write a header using the data in the provided -Tn struct archive_entry -structure. -See -\fBarchive_entry\fP(3) -for information on creating and populating -Tn struct archive_entry -objects. -.TP -\fB\%archive_write_data\fP() -Write data corresponding to the header just written. -Returns number of bytes written or -1 on error. -.TP -\fB\%archive_write_finish_entry\fP() -Close out the entry just written. -In particular, this writes out the final padding required by some formats. -Ordinarily, clients never need to call this, as it -is called automatically by -\fB\%archive_write_next_header\fP() -and -\fB\%archive_write_close\fP() -as needed. -.TP -\fB\%archive_write_close\fP() -Complete the archive and invoke the close callback. -.TP -\fB\%archive_write_finish\fP() -Invokes -\fB\%archive_write_close\fP() -if it was not invoked manually, then releases all resources. -Note that this function was declared to return -\fIvoid\fP -in libarchive 1.x, which made it impossible to detect errors when -\fB\%archive_write_close\fP() -was invoked implicitly from this function. -This is corrected beginning with libarchive 2.0. -.RE -More information about the -\fIstruct\fP archive -object and the overall design of the library can be found in the -\fBlibarchive\fP(3) -overview. -.SH IMPLEMENTATION -.ad l -Compression support is built-in to libarchive, which uses zlib and bzlib -to handle gzip and bzip2 compression, respectively. -.SH CLIENT CALLBACKS -.ad l -To use this library, you will need to define and register -callback functions that will be invoked to write data to the -resulting archive. -These functions are registered by calling -\fB\%archive_write_open\fP(): -.RS 5 -.IP -\fItypedef int\fP -\fB\%archive_open_callback\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *client_data\fP) -.RE -.PP -The open callback is invoked by -\fB\%archive_write_open\fP(). -It should return -\fBARCHIVE_OK\fP -if the underlying file or data source is successfully -opened. -If the open fails, it should call -\fB\%archive_set_error\fP() -to register an error code and message and return -\fBARCHIVE_FATAL\fP. -.RS 5 -.IP -\fItypedef ssize_t\fP -\fB\%archive_write_callback\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *client_data\fP, \fI\%const\ void\ *buffer\fP, \fI\%size_t\ length\fP) -.RE -.PP -The write callback is invoked whenever the library -needs to write raw bytes to the archive. -For correct blocking, each call to the write callback function -should translate into a single -\fBwrite\fP(2) -system call. -This is especially critical when writing archives to tape drives. -On success, the write callback should return the -number of bytes actually written. -On error, the callback should invoke -\fB\%archive_set_error\fP() -to register an error code and message and return -1. -.RS 5 -.IP -\fItypedef int\fP -\fB\%archive_close_callback\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *client_data\fP) -.RE -.PP -The close callback is invoked by archive_close when -the archive processing is complete. -The callback should return -\fBARCHIVE_OK\fP -on success. -On failure, the callback should invoke -\fB\%archive_set_error\fP() -to register an error code and message and -return -\fBARCHIVE_FATAL.\fP -.SH EXAMPLE -.ad l -The following sketch illustrates basic usage of the library. -In this example, -the callback functions are simply wrappers around the standard -\fBopen\fP(2), -\fBwrite\fP(2), -and -\fBclose\fP(2) -system calls. -.RS 4 -.nf -#ifdef __linux__ -#define _FILE_OFFSET_BITS 64 -#endif -#include <sys/stat.h> -#include <archive.h> -#include <archive_entry.h> -#include <fcntl.h> -#include <stdlib.h> -#include <unistd.h> -struct mydata { - const char *name; - int fd; -}; -int -myopen(struct archive *a, void *client_data) -{ - struct mydata *mydata = client_data; - mydata->fd = open(mydata->name, O_WRONLY | O_CREAT, 0644); - if (mydata->fd >= 0) - return (ARCHIVE_OK); - else - return (ARCHIVE_FATAL); -} -ssize_t -mywrite(struct archive *a, void *client_data, const void *buff, size_t n) -{ - struct mydata *mydata = client_data; - return (write(mydata->fd, buff, n)); -} -int -myclose(struct archive *a, void *client_data) -{ - struct mydata *mydata = client_data; - if (mydata->fd > 0) - close(mydata->fd); - return (0); -} -void -write_archive(const char *outname, const char **filename) -{ - struct mydata *mydata = malloc(sizeof(struct mydata)); - struct archive *a; - struct archive_entry *entry; - struct stat st; - char buff[8192]; - int len; - int fd; - a = archive_write_new(); - mydata->name = outname; - archive_write_set_compression_gzip(a); - archive_write_set_format_ustar(a); - archive_write_open(a, mydata, myopen, mywrite, myclose); - while (*filename) { - stat(*filename, &st); - entry = archive_entry_new(); - archive_entry_copy_stat(entry, &st); - archive_entry_set_pathname(entry, *filename); - archive_write_header(a, entry); - fd = open(*filename, O_RDONLY); - len = read(fd, buff, sizeof(buff)); - while ( len > 0 ) { - archive_write_data(a, buff, len); - len = read(fd, buff, sizeof(buff)); - } - archive_entry_free(entry); - filename++; - } - archive_write_finish(a); -} -int main(int argc, const char **argv) -{ - const char *outname; - argv++; - outname = argv++; - write_archive(outname, argv); - return 0; -} -.RE -.SH RETURN VALUES -.ad l -Most functions return -\fBARCHIVE_OK\fP -(zero) on success, or one of several non-zero -error codes for errors. -Specific error codes include: -\fBARCHIVE_RETRY\fP -for operations that might succeed if retried, -\fBARCHIVE_WARN\fP -for unusual conditions that do not prevent further operations, and -\fBARCHIVE_FATAL\fP -for serious errors that make remaining operations impossible. -The -\fB\%archive_errno\fP() -and -\fB\%archive_error_string\fP() -functions can be used to retrieve an appropriate error code and a -textual error message. -.PP -\fB\%archive_write_new\fP() -returns a pointer to a newly-allocated -Tn struct archive -object. -.PP -\fB\%archive_write_data\fP() -returns a count of the number of bytes actually written. -On error, -1 is returned and the -\fB\%archive_errno\fP() -and -\fB\%archive_error_string\fP() -functions will return appropriate values. -Note that if the client-provided write callback function -returns a non-zero value, that error will be propagated back to the caller -through whatever API function resulted in that call, which -may include -\fB\%archive_write_header\fP(), -\fB\%archive_write_data\fP(), -\fB\%archive_write_close\fP(), -or -\fB\%archive_write_finish\fP(). -The client callback can call -\fB\%archive_set_error\fP() -to provide values that can then be retrieved by -\fB\%archive_errno\fP() -and -\fB\%archive_error_string\fP(). -.SH SEE ALSO -.ad l -\fBtar\fP(1), -\fBlibarchive\fP(3), -\fBtar\fP(5) -.SH HISTORY -.ad l -The -\fB\%libarchive\fP -library first appeared in -FreeBSD 5.3. -.SH AUTHORS -.ad l --nosplit -The -\fB\%libarchive\fP -library was written by -Tim Kientzle \%<kientzle@acm.org.> -.SH BUGS -.ad l -There are many peculiar bugs in historic tar implementations that may cause -certain programs to reject archives written by this library. -For example, several historic implementations calculated header checksums -incorrectly and will thus reject valid archives; GNU tar does not fully support -pax interchange format; some old tar implementations required specific -field terminations. -.PP -The default pax interchange format eliminates most of the historic -tar limitations and provides a generic key/value attribute facility -for vendor-defined extensions. -One oversight in POSIX is the failure to provide a standard attribute -for large device numbers. -This library uses -``SCHILY.devminor'' -and -``SCHILY.devmajor'' -for device numbers that exceed the range supported by the backwards-compatible -ustar header. -These keys are compatible with Joerg Schilling's -\fB\%star\fP -archiver. -Other implementations may not recognize these keys and will thus be unable -to correctly restore device nodes with large device numbers from archives -created by this library. diff --git a/libarchive/libarchive-2.8.0/doc/man/archive_write_disk.3 b/libarchive/libarchive-2.8.0/doc/man/archive_write_disk.3 deleted file mode 100644 index a58181e..0000000 --- a/libarchive/libarchive-2.8.0/doc/man/archive_write_disk.3 +++ /dev/null @@ -1,386 +0,0 @@ -.TH archive_write_disk 3 "August 5, 2008" "" -.SH NAME -.ad l -\fB\%archive_write_disk_new\fP, -\fB\%archive_write_disk_set_options\fP, -\fB\%archive_write_disk_set_skip_file\fP, -\fB\%archive_write_disk_set_group_lookup\fP, -\fB\%archive_write_disk_set_standard_lookup\fP, -\fB\%archive_write_disk_set_user_lookup\fP, -\fB\%archive_write_header\fP, -\fB\%archive_write_data\fP, -\fB\%archive_write_finish_entry\fP, -\fB\%archive_write_close\fP, -\fB\%archive_write_finish\fP -\- functions for creating objects on disk -.SH SYNOPSIS -.ad l -\fB#include <archive.h>\fP -.br -\fIstruct archive *\fP -.br -\fB\%archive_write_disk_new\fP(\fI\%void\fP); -.br -\fIint\fP -.br -\fB\%archive_write_disk_set_options\fP(\fI\%struct\ archive\ *\fP, \fI\%int\ flags\fP); -.br -\fIint\fP -.br -\fB\%archive_write_disk_set_skip_file\fP(\fI\%struct\ archive\ *\fP, \fI\%dev_t\fP, \fI\%ino_t\fP); -.br -\fIint\fP -.br -\fB\%archive_write_disk_set_group_lookup\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *\fP, \fI\%gid_t\ (*)(void\ *,\ const\ char\ *gname,\ gid_t\ gid)\fP, \fI\%void\ (*cleanup)(void\ *)\fP); -.br -\fIint\fP -.br -\fB\%archive_write_disk_set_standard_lookup\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_write_disk_set_user_lookup\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *\fP, \fI\%uid_t\ (*)(void\ *,\ const\ char\ *uname,\ uid_t\ uid)\fP, \fI\%void\ (*cleanup)(void\ *)\fP); -.br -\fIint\fP -.br -\fB\%archive_write_header\fP(\fI\%struct\ archive\ *\fP, \fI\%struct\ archive_entry\ *\fP); -.br -\fIssize_t\fP -.br -\fB\%archive_write_data\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ void\ *\fP, \fI\%size_t\fP); -.br -\fIint\fP -.br -\fB\%archive_write_finish_entry\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_write_close\fP(\fI\%struct\ archive\ *\fP); -.br -\fIint\fP -.br -\fB\%archive_write_finish\fP(\fI\%struct\ archive\ *\fP); -.SH DESCRIPTION -.ad l -These functions provide a complete API for creating objects on -disk from -Tn struct archive_entry -descriptions. -They are most naturally used when extracting objects from an archive -using the -\fB\%archive_read\fP() -interface. -The general process is to read -Tn struct archive_entry -objects from an archive, then write those objects to a -Tn struct archive -object created using the -\fB\%archive_write_disk\fP() -family functions. -This interface is deliberately very similar to the -\fB\%archive_write\fP() -interface used to write objects to a streaming archive. -.RS 5 -.TP -\fB\%archive_write_disk_new\fP() -Allocates and initializes a -Tn struct archive -object suitable for writing objects to disk. -.TP -\fB\%archive_write_disk_set_skip_file\fP() -Records the device and inode numbers of a file that should not be -overwritten. -This is typically used to ensure that an extraction process does not -overwrite the archive from which objects are being read. -This capability is technically unnecessary but can be a significant -performance optimization in practice. -.TP -\fB\%archive_write_disk_set_options\fP() -The options field consists of a bitwise OR of one or more of the -following values: -.RS 5 -.TP -\fBARCHIVE_EXTRACT_OWNER\fP -The user and group IDs should be set on the restored file. -By default, the user and group IDs are not restored. -.TP -\fBARCHIVE_EXTRACT_PERM\fP -Full permissions (including SGID, SUID, and sticky bits) should -be restored exactly as specified, without obeying the -current umask. -Note that SUID and SGID bits can only be restored if the -user and group ID of the object on disk are correct. -If -\fBARCHIVE_EXTRACT_OWNER\fP -is not specified, then SUID and SGID bits will only be restored -if the default user and group IDs of newly-created objects on disk -happen to match those specified in the archive entry. -By default, only basic permissions are restored, and umask is obeyed. -.TP -\fBARCHIVE_EXTRACT_TIME\fP -The timestamps (mtime, ctime, and atime) should be restored. -By default, they are ignored. -Note that restoring of atime is not currently supported. -.TP -\fBARCHIVE_EXTRACT_NO_OVERWRITE\fP -Existing files on disk will not be overwritten. -By default, existing regular files are truncated and overwritten; -existing directories will have their permissions updated; -other pre-existing objects are unlinked and recreated from scratch. -.TP -\fBARCHIVE_EXTRACT_UNLINK\fP -Existing files on disk will be unlinked before any attempt to -create them. -In some cases, this can prove to be a significant performance improvement. -By default, existing files are truncated and rewritten, but -the file is not recreated. -In particular, the default behavior does not break existing hard links. -.TP -\fBARCHIVE_EXTRACT_ACL\fP -Attempt to restore ACLs. -By default, extended ACLs are ignored. -.TP -\fBARCHIVE_EXTRACT_FFLAGS\fP -Attempt to restore extended file flags. -By default, file flags are ignored. -.TP -\fBARCHIVE_EXTRACT_XATTR\fP -Attempt to restore POSIX.1e extended attributes. -By default, they are ignored. -.TP -\fBARCHIVE_EXTRACT_SECURE_SYMLINKS\fP -Refuse to extract any object whose final location would be altered -by a symlink on disk. -This is intended to help guard against a variety of mischief -caused by archives that (deliberately or otherwise) extract -files outside of the current directory. -The default is not to perform this check. -If -\fBARCHIVE_EXTRACT_UNLINK\fP -is specified together with this option, the library will -remove any intermediate symlinks it finds and return an -error only if such symlink could not be removed. -.TP -\fBARCHIVE_EXTRACT_SECURE_NODOTDOT\fP -Refuse to extract a path that contains a -\fI\& ..\fP -element anywhere within it. -The default is to not refuse such paths. -Note that paths ending in -\fI\& ..\fP -always cause an error, regardless of this flag. -.TP -\fBARCHIVE_EXTRACT_SPARSE\fP -Scan data for blocks of NUL bytes and try to recreate them with holes. -This results in sparse files, independent of whether the archive format -supports or uses them. -.RE -.TP -\fB\%archive_write_disk_set_group_lookup\fP(), -\fB\%archive_write_disk_set_user_lookup\fP() -The -Tn struct archive_entry -objects contain both names and ids that can be used to identify users -and groups. -These names and ids describe the ownership of the file itself and -also appear in ACL lists. -By default, the library uses the ids and ignores the names, but -this can be overridden by registering user and group lookup functions. -To register, you must provide a lookup function which -accepts both a name and id and returns a suitable id. -You may also provide a -Tn void * -pointer to a private data structure and a cleanup function for -that data. -The cleanup function will be invoked when the -Tn struct archive -object is destroyed. -.TP -\fB\%archive_write_disk_set_standard_lookup\fP() -This convenience function installs a standard set of user -and group lookup functions. -These functions use -\fBgetpwnam\fP(3) -and -\fBgetgrnam\fP(3) -to convert names to ids, defaulting to the ids if the names cannot -be looked up. -These functions also implement a simple memory cache to reduce -the number of calls to -\fBgetpwnam\fP(3) -and -\fBgetgrnam\fP(3). -.TP -\fB\%archive_write_header\fP() -Build and write a header using the data in the provided -Tn struct archive_entry -structure. -See -\fBarchive_entry\fP(3) -for information on creating and populating -Tn struct archive_entry -objects. -.TP -\fB\%archive_write_data\fP() -Write data corresponding to the header just written. -Returns number of bytes written or -1 on error. -.TP -\fB\%archive_write_finish_entry\fP() -Close out the entry just written. -Ordinarily, clients never need to call this, as it -is called automatically by -\fB\%archive_write_next_header\fP() -and -\fB\%archive_write_close\fP() -as needed. -.TP -\fB\%archive_write_close\fP() -Set any attributes that could not be set during the initial restore. -For example, directory timestamps are not restored initially because -restoring a subsequent file would alter that timestamp. -Similarly, non-writable directories are initially created with -write permissions (so that their contents can be restored). -The -\fB\%archive_write_disk_new\fP -library maintains a list of all such deferred attributes and -sets them when this function is invoked. -.TP -\fB\%archive_write_finish\fP() -Invokes -\fB\%archive_write_close\fP() -if it was not invoked manually, then releases all resources. -.RE -More information about the -\fIstruct\fP archive -object and the overall design of the library can be found in the -\fBlibarchive\fP(3) -overview. -Many of these functions are also documented under -\fBarchive_write\fP(3). -.SH RETURN VALUES -.ad l -Most functions return -\fBARCHIVE_OK\fP -(zero) on success, or one of several non-zero -error codes for errors. -Specific error codes include: -\fBARCHIVE_RETRY\fP -for operations that might succeed if retried, -\fBARCHIVE_WARN\fP -for unusual conditions that do not prevent further operations, and -\fBARCHIVE_FATAL\fP -for serious errors that make remaining operations impossible. -The -\fB\%archive_errno\fP() -and -\fB\%archive_error_string\fP() -functions can be used to retrieve an appropriate error code and a -textual error message. -.PP -\fB\%archive_write_disk_new\fP() -returns a pointer to a newly-allocated -Tn struct archive -object. -.PP -\fB\%archive_write_data\fP() -returns a count of the number of bytes actually written. -On error, -1 is returned and the -\fB\%archive_errno\fP() -and -\fB\%archive_error_string\fP() -functions will return appropriate values. -.SH SEE ALSO -.ad l -\fBarchive_read\fP(3), -\fBarchive_write\fP(3), -\fBtar\fP(1), -\fBlibarchive\fP(3) -.SH HISTORY -.ad l -The -\fB\%libarchive\fP -library first appeared in -FreeBSD 5.3. -The -\fB\%archive_write_disk\fP -interface was added to -\fB\%libarchive\fP 2.0 -and first appeared in -FreeBSD 6.3. -.SH AUTHORS -.ad l --nosplit -The -\fB\%libarchive\fP -library was written by -Tim Kientzle \%<kientzle@acm.org.> -.SH BUGS -.ad l -Directories are actually extracted in two distinct phases. -Directories are created during -\fB\%archive_write_header\fP(), -but final permissions are not set until -\fB\%archive_write_close\fP(). -This separation is necessary to correctly handle borderline -cases such as a non-writable directory containing -files, but can cause unexpected results. -In particular, directory permissions are not fully -restored until the archive is closed. -If you use -\fBchdir\fP(2) -to change the current directory between calls to -\fB\%archive_read_extract\fP() -or before calling -\fB\%archive_read_close\fP(), -you may confuse the permission-setting logic with -the result that directory permissions are restored -incorrectly. -.PP -The library attempts to create objects with filenames longer than -\fBPATH_MAX\fP -by creating prefixes of the full path and changing the current directory. -Currently, this logic is limited in scope; the fixup pass does -not work correctly for such objects and the symlink security check -option disables the support for very long pathnames. -.PP -Restoring the path -\fIaa/../bb\fP -does create each intermediate directory. -In particular, the directory -\fIaa\fP -is created as well as the final object -\fIbb\fP. -In theory, this can be exploited to create an entire directory heirarchy -with a single request. -Of course, this does not work if the -\fBARCHIVE_EXTRACT_NODOTDOT\fP -option is specified. -.PP -Implicit directories are always created obeying the current umask. -Explicit objects are created obeying the current umask unless -\fBARCHIVE_EXTRACT_PERM\fP -is specified, in which case they current umask is ignored. -.PP -SGID and SUID bits are restored only if the correct user and -group could be set. -If -\fBARCHIVE_EXTRACT_OWNER\fP -is not specified, then no attempt is made to set the ownership. -In this case, SGID and SUID bits are restored only if the -user and group of the final object happen to match those specified -in the entry. -.PP -The -``standard'' -user-id and group-id lookup functions are not the defaults because -\fBgetgrnam\fP(3) -and -\fBgetpwnam\fP(3) -are sometimes too large for particular applications. -The current design allows the application author to use a more -compact implementation when appropriate. -.PP -There should be a corresponding -\fB\%archive_read_disk\fP -interface that walks a directory heirarchy and returns archive -entry objects. diff --git a/libarchive/libarchive-2.8.0/doc/man/bsdcpio.1 b/libarchive/libarchive-2.8.0/doc/man/bsdcpio.1 deleted file mode 100644 index 76217b4..0000000 --- a/libarchive/libarchive-2.8.0/doc/man/bsdcpio.1 +++ /dev/null @@ -1,446 +0,0 @@ -.TH BSDCPIO 1 "December 21, 2007" "" -.SH NAME -.ad l -\fB\%cpio\fP -\- copy files to and from archives -.SH SYNOPSIS -.ad l -.br -\fB\%cpio\fP -{\fB\-i\fP} -[\fIoptions\fP] -[\fIpattern\fP ...] -[\fI<\fP archive] -.br -\fB\%cpio\fP -{\fB\-o\fP} -[\fIoptions\fP] -\fI<\fP name-list -[\fI>\fP archive] -.br -\fB\%cpio\fP -{\fB\-p\fP} -[\fIoptions\fP] -\fIdest-dir\fP -\fI<\fP name-list -.SH DESCRIPTION -.ad l -\fB\%cpio\fP -copies files between archives and directories. -This implementation can extract from tar, pax, cpio, zip, jar, ar, -and ISO 9660 cdrom images and can create tar, pax, cpio, ar, -and shar archives. -.PP -The first option to -\fB\%cpio\fP -is a mode indicator from the following list: -.RS 5 -.TP -\fB\-i\fP -Input. -Read an archive from standard input (unless overriden) and extract the -contents to disk or (if the -\fB\-t\fP -option is specified) -list the contents to standard output. -If one or more file patterns are specified, only files matching -one of the patterns will be extracted. -.TP -\fB\-o\fP -Output. -Read a list of filenames from standard input and produce a new archive -on standard output (unless overriden) containing the specified items. -.TP -\fB\-p\fP -Pass-through. -Read a list of filenames from standard input and copy the files to the -specified directory. -.RE -.PP -.SH OPTIONS -.ad l -Unless specifically stated otherwise, options are applicable in -all operating modes. -.RS 5 -.TP -\fB\-0\fP -Read filenames separated by NUL characters instead of newlines. -This is necessary if any of the filenames being read might contain newlines. -.TP -\fB\-A\fP -(o mode only) -Append to the specified archive. -(Not yet implemented.) -.TP -\fB\-a\fP -(o and p modes) -Reset access times on files after they are read. -.TP -\fB\-B\fP -(o mode only) -Block output to records of 5120 bytes. -.TP -\fB\-C\fP \fIsize\fP -(o mode only) -Block output to records of -\fIsize\fP -bytes. -.TP -\fB\-c\fP -(o mode only) -Use the old POSIX portable character format. -Equivalent to -\fB\--format\fP \fIodc\fP. -.TP -\fB\-d\fP -(i and p modes) -Create directories as necessary. -.TP -\fB\-E\fP \fIfile\fP -(i mode only) -Read list of file name patterns from -\fIfile\fP -to list and extract. -.TP -\fB\-F\fP \fIfile\fP -Read archive from or write archive to -\fIfile\fP. -.TP -\fB\-f\fP \fIpattern\fP -(i mode only) -Ignore files that match -\fIpattern\fP. -.TP -\fB\--format\fP \fIformat\fP -(o mode only) -Produce the output archive in the specified format. -Supported formats include: -.PP -.RS 5 -.TP -\fIcpio\fP -Synonym for -\fIodc\fP. -.TP -\fInewc\fP -The SVR4 portable cpio format. -.TP -\fIodc\fP -The old POSIX.1 portable octet-oriented cpio format. -.TP -\fIpax\fP -The POSIX.1 pax format, an extension of the ustar format. -.TP -\fIustar\fP -The POSIX.1 tar format. -.RE -.PP -The default format is -\fIodc\fP. -See -\fBlibarchive_formats\fP(5) -for more complete information about the -formats currently supported by the underlying -\fBlibarchive\fP(3) -library. -.TP -\fB\-H\fP \fIformat\fP -Synonym for -\fB\--format\fP. -.TP -\fB\-h\fP, \fB\--help\fP -Print usage information. -.TP -\fB\-I\fP \fIfile\fP -Read archive from -\fIfile\fP. -.TP -\fB\-i\fP -Input mode. -See above for description. -.TP -\fB\--insecure\fP -(i and p mode only) -Disable security checks during extraction or copying. -This allows extraction via symbolic links and path names containing -Sq .. -in the name. -.TP -\fB\-J\fP -(o mode only) -Compress the file with xz-compatible compression before writing it. -In input mode, this option is ignored; xz compression is recognized -automatically on input. -.TP -\fB\-j\fP -Synonym for -\fB\-y\fP. -.TP -\fB\-L\fP -(o and p modes) -All symbolic links will be followed. -Normally, symbolic links are archived and copied as symbolic links. -With this option, the target of the link will be archived or copied instead. -.TP -\fB\-l\fP -(p mode only) -Create links from the target directory to the original files, -instead of copying. -.TP -\fB\-lzma\fP -(o mode only) -Compress the file with lzma-compatible compression before writing it. -In input mode, this option is ignored; lzma compression is recognized -automatically on input. -.TP -\fB\-m\fP -(i and p modes) -Set file modification time on created files to match -those in the source. -.TP -\fB\-n\fP -(i mode, only with -\fB\-t\fP) -Display numeric uid and gid. -By default, -\fB\%cpio\fP -displays the user and group names when they are provided in the -archive, or looks up the user and group names in the system -password database. -.TP -\fB\-no-preserve-owner\fP -(i mode only) -Do not attempt to restore file ownership. -This is the default when run by non-root users. -.TP -\fB\-O\fP \fIfile\fP -Write archive to -\fIfile\fP. -.TP -\fB\-o\fP -Output mode. -See above for description. -.TP -\fB\-p\fP -Pass-through mode. -See above for description. -.TP -\fB\-preserve-owner\fP -(i mode only) -Restore file ownership. -This is the default when run by the root user. -.TP -\fB\--quiet\fP -Suppress unnecessary messages. -.TP -\fB\-R\fP [user] [:] [group] -Set the owner and/or group on files in the output. -If group is specified with no user -(for example, -\fB\-R\fP \fI:wheel\fP) -then the group will be set but not the user. -If the user is specified with a trailing colon and no group -(for example, -\fB\-R\fP \fIroot:\fP) -then the group will be set to the user's default group. -If the user is specified with no trailing colon, then -the user will be set but not the group. -In -\fB\-i\fP -and -\fB\-p\fP -modes, this option can only be used by the super-user. -(For compatibility, a period can be used in place of the colon.) -.TP -\fB\-r\fP -(All modes.) -Rename files interactively. -For each file, a prompt is written to -\fI/dev/tty\fP -containing the name of the file and a line is read from -\fI/dev/tty\fP. -If the line read is blank, the file is skipped. -If the line contains a single period, the file is processed normally. -Otherwise, the line is taken to be the new name of the file. -.TP -\fB\-t\fP -(i mode only) -List the contents of the archive to stdout; -do not restore the contents to disk. -.TP -\fB\-u\fP -(i and p modes) -Unconditionally overwrite existing files. -Ordinarily, an older file will not overwrite a newer file on disk. -.TP -\fB\-v\fP -Print the name of each file to stderr as it is processed. -With -\fB\-t\fP, -provide a detailed listing of each file. -.TP -\fB\--version\fP -Print the program version information and exit. -.TP -\fB\-y\fP -(o mode only) -Compress the archive with bzip2-compatible compression before writing it. -In input mode, this option is ignored; -bzip2 compression is recognized automatically on input. -.TP -\fB\-Z\fP -(o mode only) -Compress the archive with compress-compatible compression before writing it. -In input mode, this option is ignored; -compression is recognized automatically on input. -.TP -\fB\-z\fP -(o mode only) -Compress the archive with gzip-compatible compression before writing it. -In input mode, this option is ignored; -gzip compression is recognized automatically on input. -.RE -.SH ENVIRONMENT -.ad l -The following environment variables affect the execution of -\fB\%cpio\fP: -.RS 5 -.TP -.B LANG -The locale to use. -See -\fBenviron\fP(7) -for more information. -.TP -.B TZ -The timezone to use when displaying dates. -See -\fBenviron\fP(7) -for more information. -.RE -.SH EXIT STATUS -.ad l -The \fBcpio\fP utility exits 0 on success, and >0 if an error occurs. -.SH EXAMPLES -.ad l -The -\fB\%cpio\fP -command is traditionally used to copy file heirarchies in conjunction -with the -\fBfind\fP(1) -command. -The first example here simply copies all files from -\fIsrc\fP -to -\fIdest\fP: -.RS 4 -\fB\%find\fP \fIsrc\fP | \fB\%cpio\fP \fB\-pmud\fP \fIdest\fP -.RE -.PP -By carefully selecting options to the -\fBfind\fP(1) -command and combining it with other standard utilities, -it is possible to exercise very fine control over which files are copied. -This next example copies files from -\fIsrc\fP -to -\fIdest\fP -that are more than 2 days old and whose names match a particular pattern: -.RS 4 -\fB\%find\fP \fIsrc\fP \fB\-mtime\fP \fI+2\fP | \fB\%grep\fP foo[bar] | \fB\%cpio\fP \fB\-pdmu\fP \fIdest\fP -.RE -.PP -This example copies files from -\fIsrc\fP -to -\fIdest\fP -that are more than 2 days old and which contain the word -``foobar'': -.RS 4 -\fB\%find\fP \fIsrc\fP \fB\-mtime\fP \fI+2\fP | \fB\%xargs\fP \fB\%grep\fP -l foobar | \fB\%cpio\fP \fB\-pdmu\fP \fIdest\fP -.RE -.SH COMPATIBILITY -.ad l -The mode options i, o, and p and the options -a, B, c, d, f, l, m, r, t, u, and v comply with SUSv2. -.PP -The old POSIX.1 standard specified that only -\fB\-i\fP, -\fB\-o\fP, -and -\fB\-p\fP -were interpreted as command-line options. -Each took a single argument of a list of modifier -characters. -For example, the standard syntax allows -\fB\-imu\fP -but does not support -\fB\-miu\fP -or -\fB\-i\fP \fB\-m\fP \fB\-u\fP, -since -\fIm\fP -and -\fIu\fP -are only modifiers to -\fB\-i\fP, -they are not command-line options in their own right. -The syntax supported by this implementation is backwards-compatible -with the standard. -For best compatibility, scripts should limit themselves to the -standard syntax. -.SH SEE ALSO -.ad l -\fBbzip2\fP(1), -\fBtar\fP(1), -\fBgzip\fP(1), -\fBmt\fP(1), -\fBpax\fP(1), -\fBlibarchive\fP(3), -\fBcpio\fP(5), -\fBlibarchive-formats\fP(5), -\fBtar\fP(5) -.SH STANDARDS -.ad l -There is no current POSIX standard for the cpio command; it appeared -in -ISO/IEC 9945-1:1996 (``POSIX.1'') -but was dropped from -IEEE Std 1003.1-2001 (``POSIX.1''). -.PP -The cpio, ustar, and pax interchange file formats are defined by -IEEE Std 1003.1-2001 (``POSIX.1'') -for the pax command. -.SH HISTORY -.ad l -The original -\fB\%cpio\fP -and -\fB\%find\fP -utilities were written by Dick Haight -while working in AT&T's Unix Support Group. -They first appeared in 1977 in PWB/UNIX 1.0, the -``Programmer's Work Bench'' -system developed for use within AT&T. -They were first released outside of AT&T as part of System III Unix in 1981. -As a result, -\fB\%cpio\fP -actually predates -\fB\%tar\fP, -even though it was not well-known outside of AT&T until some time later. -.PP -This is a complete re-implementation based on the -\fBlibarchive\fP(3) -library. -.SH BUGS -.ad l -The cpio archive format has several basic limitations: -It does not store user and group names, only numbers. -As a result, it cannot be reliably used to transfer -files between systems with dissimilar user and group numbering. -Older cpio formats limit the user and group numbers to -16 or 18 bits, which is insufficient for modern systems. -The cpio archive formats cannot support files over 4 gigabytes, -except for the -``odc'' -variant, which can support files up to 8 gigabytes. diff --git a/libarchive/libarchive-2.8.0/doc/man/bsdtar.1 b/libarchive/libarchive-2.8.0/doc/man/bsdtar.1 deleted file mode 100644 index bd9f618..0000000 --- a/libarchive/libarchive-2.8.0/doc/man/bsdtar.1 +++ /dev/null @@ -1,1024 +0,0 @@ -.TH BSDTAR 1 "Oct 12, 2009" "" -.SH NAME -.ad l -\fB\%tar\fP -\- manipulate tape archives -.SH SYNOPSIS -.ad l -.br -\fB\%tar\fP -[\fIbundled-flags\fP <args>] -[<\fIfile\fP> | <\fIpattern\fP> ...] -.br -\fB\%tar\fP -{\fB\-c\fP} -[\fIoptions\fP] -[\fIfiles\fP | \fIdirectories\fP] -.br -\fB\%tar\fP -{\fB\-r\fP | \fB\-u\fP} -\fB\-f\fP \fIarchive-file\fP -[\fIoptions\fP] -[\fIfiles\fP | \fIdirectories\fP] -.br -\fB\%tar\fP -{\fB\-t\fP | \fB\-x\fP} -[\fIoptions\fP] -[\fIpatterns\fP] -.SH DESCRIPTION -.ad l -\fB\%tar\fP -creates and manipulates streaming archive files. -This implementation can extract from tar, pax, cpio, zip, jar, ar, -and ISO 9660 cdrom images and can create tar, pax, cpio, ar, -and shar archives. -.PP -The first synopsis form shows a -``bundled'' -option word. -This usage is provided for compatibility with historical implementations. -See COMPATIBILITY below for details. -.PP -The other synopsis forms show the preferred usage. -The first option to -\fB\%tar\fP -is a mode indicator from the following list: -.RS 5 -.TP -\fB\-c\fP -Create a new archive containing the specified items. -.TP -\fB\-r\fP -Like -\fB\-c\fP, -but new entries are appended to the archive. -Note that this only works on uncompressed archives stored in regular files. -The -\fB\-f\fP -option is required. -.TP -\fB\-t\fP -List archive contents to stdout. -.TP -\fB\-u\fP -Like -\fB\-r\fP, -but new entries are added only if they have a modification date -newer than the corresponding entry in the archive. -Note that this only works on uncompressed archives stored in regular files. -The -\fB\-f\fP -option is required. -.TP -\fB\-x\fP -Extract to disk from the archive. -If a file with the same name appears more than once in the archive, -each copy will be extracted, with later copies overwriting (replacing) -earlier copies. -.RE -.PP -In -\fB\-c\fP, -\fB\-r\fP, -or -\fB\-u\fP -mode, each specified file or directory is added to the -archive in the order specified on the command line. -By default, the contents of each directory are also archived. -.PP -In extract or list mode, the entire command line -is read and parsed before the archive is opened. -The pathnames or patterns on the command line indicate -which items in the archive should be processed. -Patterns are shell-style globbing patterns as -documented in -\fBtcsh\fP(1). -.SH OPTIONS -.ad l -Unless specifically stated otherwise, options are applicable in -all operating modes. -.RS 5 -.TP -\fB@\fP \fIarchive\fP -(c and r mode only) -The specified archive is opened and the entries -in it will be appended to the current archive. -As a simple example, -.RS 4 -\fB\%tar\fP \fB\-c\fP \fB\-f\fP \fI-\fP \fInewfile\fP \fB@\fP \fIoriginal.tar\fP -.RE -writes a new archive to standard output containing a file -\fInewfile\fP -and all of the entries from -\fIoriginal.tar\fP. -In contrast, -.RS 4 -\fB\%tar\fP \fB\-c\fP \fB\-f\fP \fI-\fP \fInewfile\fP \fIoriginal.tar\fP -.RE -creates a new archive with only two entries. -Similarly, -.RS 4 -\fB\%tar\fP \fB\-czf\fP \fI-\fP \fB\--format\fP \fBpax\fP \fB@\fP \fI-\fP -.RE -reads an archive from standard input (whose format will be determined -automatically) and converts it into a gzip-compressed -pax-format archive on stdout. -In this way, -\fB\%tar\fP -can be used to convert archives from one format to another. -.TP -\fB\-b\fP \fIblocksize\fP -Specify the block size, in 512-byte records, for tape drive I/O. -As a rule, this argument is only needed when reading from or writing -to tape drives, and usually not even then as the default block size of -20 records (10240 bytes) is very common. -.TP -\fB\-C\fP \fIdirectory\fP -In c and r mode, this changes the directory before adding -the following files. -In x mode, change directories after opening the archive -but before extracting entries from the archive. -.TP -\fB\--check-links\fP -(c and r modes only) -Issue a warning message unless all links to each file are archived. -.TP -\fB\--chroot\fP -(x mode only) -\fB\%chroot\fP() -to the current directory after processing any -\fB\-C\fP -options and before extracting any files. -.TP -\fB\--exclude\fP \fIpattern\fP -Do not process files or directories that match the -specified pattern. -Note that exclusions take precedence over patterns or filenames -specified on the command line. -.TP -\fB\--format\fP \fIformat\fP -(c, r, u mode only) -Use the specified format for the created archive. -Supported formats include -``cpio'', -``pax'', -``shar'', -and -``ustar''. -Other formats may also be supported; see -\fBlibarchive-formats\fP(5) -for more information about currently-supported formats. -In r and u modes, when extending an existing archive, the format specified -here must be compatible with the format of the existing archive on disk. -.TP -\fB\-f\fP \fIfile\fP -Read the archive from or write the archive to the specified file. -The filename can be -\fI-\fP -for standard input or standard output. -If not specified, the default tape device will be used. -(On -FreeBSD, -the default tape device is -\fI/dev/sa0\fP.) -.TP -\fB\-H\fP -(c and r mode only) -Symbolic links named on the command line will be followed; the -target of the link will be archived, not the link itself. -.TP -\fB\-h\fP -(c and r mode only) -Synonym for -\fB\-L\fP. -.TP -\fB\-I\fP -Synonym for -\fB\-T\fP. -.TP -\fB\--include\fP \fIpattern\fP -Process only files or directories that match the specified pattern. -Note that exclusions specified with -\fB\--exclude\fP -take precedence over inclusions. -If no inclusions are explicitly specified, all entries are processed by -default. -The -\fB\--include\fP -option is especially useful when filtering archives. -For example, the command -.RS 4 -\fB\%tar\fP \fB\-c\fP \fB\-f\fP \fInew.tar\fP \fB\--include='*foo*'\fP \fB@\fP \fIold.tgz\fP -.RE -creates a new archive -\fInew.tar\fP -containing only the entries from -\fIold.tgz\fP -containing the string -Sq foo. -.TP -\fB\-j\fP -(c mode only) -Compress the resulting archive with -\fBbzip2\fP(1). -In extract or list modes, this option is ignored. -Note that, unlike other -\fB\%tar\fP -implementations, this implementation recognizes bzip2 compression -automatically when reading archives. -.TP -\fB\-k\fP -(x mode only) -Do not overwrite existing files. -In particular, if a file appears more than once in an archive, -later copies will not overwrite earlier copies. -.TP -\fB\--keep-newer-files\fP -(x mode only) -Do not overwrite existing files that are newer than the -versions appearing in the archive being extracted. -.TP -\fB\-L\fP -(c and r mode only) -All symbolic links will be followed. -Normally, symbolic links are archived as such. -With this option, the target of the link will be archived instead. -.TP -\fB\-l\fP -This is a synonym for the -\fB\--check-links\fP -option. -.TP -\fB\-m\fP -(x mode only) -Do not extract modification time. -By default, the modification time is set to the time stored in the archive. -.TP -\fB\-n\fP -(c, r, u modes only) -Do not recursively archive the contents of directories. -.TP -\fB\--newer\fP \fIdate\fP -(c, r, u modes only) -Only include files and directories newer than the specified date. -This compares ctime entries. -.TP -\fB\--newer-mtime\fP \fIdate\fP -(c, r, u modes only) -Like -\fB\--newer\fP, -except it compares mtime entries instead of ctime entries. -.TP -\fB\--newer-than\fP \fIfile\fP -(c, r, u modes only) -Only include files and directories newer than the specified file. -This compares ctime entries. -.TP -\fB\--newer-mtime-than\fP \fIfile\fP -(c, r, u modes only) -Like -\fB\--newer-than\fP, -except it compares mtime entries instead of ctime entries. -.TP -\fB\--nodump\fP -(c and r modes only) -Honor the nodump file flag by skipping this file. -.TP -\fB\--null\fP -(use with -\fB\-I\fP, -\fB\-T\fP, -or -\fB\-X\fP) -Filenames or patterns are separated by null characters, -not by newlines. -This is often used to read filenames output by the -\fB\-print0\fP -option to -\fBfind\fP(1). -.TP -\fB\--numeric-owner\fP -(x mode only) -Ignore symbolic user and group names when restoring archives to disk, -only numeric uid and gid values will be obeyed. -.TP -\fB\-O\fP -(x, t modes only) -In extract (-x) mode, files will be written to standard out rather than -being extracted to disk. -In list (-t) mode, the file listing will be written to stderr rather than -the usual stdout. -.TP -\fB\-o\fP -(x mode) -Use the user and group of the user running the program rather -than those specified in the archive. -Note that this has no significance unless -\fB\-p\fP -is specified, and the program is being run by the root user. -In this case, the file modes and flags from -the archive will be restored, but ACLs or owner information in -the archive will be discarded. -.TP -\fB\-o\fP -(c, r, u mode) -A synonym for -\fB\--format\fP \fIustar\fP -.TP -\fB\--one-file-system\fP -(c, r, and u modes) -Do not cross mount points. -.TP -\fB\--options\fP \fIoptions\fP -Select optional behaviors for particular modules. -The argument is a text string containing comma-separated -keywords and values. -These are passed to the modules that handle particular -formats to control how those formats will behave. -Each option has one of the following forms: -.RS 5 -.TP -\fIkey=value\fP -The key will be set to the specified value in every module that supports it. -Modules that do not support this key will ignore it. -.TP -\fIkey\fP -The key will be enabled in every module that supports it. -This is equivalent to -\fIkey\fP \fB=1\fP. -.TP -\fI!key\fP -The key will be disabled in every module that supports it. -.TP -\fImodule:key=value\fP, \fImodule:key\fP, \fImodule:!key\fP -As above, but the corresponding key and value will be provided -only to modules whose name matches -\fImodule\fP. -.RE -The currently supported modules and keys are: -.RS 5 -.TP -\fBiso9660:joliet\fP -Support Joliet extensions. -This is enabled by default, use -\fB!joliet\fP -or -\fBiso9660:!joliet\fP -to disable. -.TP -\fBiso9660:rockridge\fP -Support Rock Ridge extensions. -This is enabled by default, use -\fB!rockridge\fP -or -\fBiso9660:!rockridge\fP -to disable. -.TP -\fBgzip:compression-level\fP -A decimal integer from 0 to 9 specifying the gzip compression level. -.TP -\fBxz:compression-level\fP -A decimal integer from 0 to 9 specifying the xz compression level. -.TP -\fBmtree:\fP \fIkeyword\fP -The mtree writer module allows you to specify which mtree keywords -will be included in the output. -Supported keywords include: -\fBcksum\fP, \fBdevice\fP, \fBflags\fP, \fBgid\fP, \fBgname\fP, \fBindent\fP, -\fBlink\fP, \fBmd5\fP, \fBmode\fP, \fBnlink\fP, \fBrmd160\fP, \fBsha1\fP, \fBsha256\fP, -\fBsha384\fP, \fBsha512\fP, \fBsize\fP, \fBtime\fP, \fBuid\fP, \fBuname\fP. -The default is equivalent to: -``device, flags, gid, gname, link, mode, nlink, size, time, type, uid, uname''. -.TP -\fBmtree:all\fP -Enables all of the above keywords. -You can also use -\fBmtree:!all\fP -to disable all keywords. -.TP -\fBmtree:use-set\fP -Enable generation of -\fB/set\fP -lines in the output. -.TP -\fBmtree:indent\fP -Produce human-readable output by indenting options and splitting lines -to fit into 80 columns. -.TP -\fBzip:compression\fP=\fItype\fP -Use -\fItype\fP -as compression method. -Supported values are store (uncompressed) and deflate (gzip algorithm). -.RE -If a provided option is not supported by any module, that -is a fatal error. -.TP -\fB\-P\fP -Preserve pathnames. -By default, absolute pathnames (those that begin with a / -character) have the leading slash removed both when creating archives -and extracting from them. -Also, -\fB\%tar\fP -will refuse to extract archive entries whose pathnames contain -\fI\& ..\fP -or whose target directory would be altered by a symlink. -This option suppresses these behaviors. -.TP -\fB\-p\fP -(x mode only) -Preserve file permissions. -Attempt to restore the full permissions, including owner, file modes, file -flags and ACLs, if available, for each item extracted from the archive. -By default, newly-created files are owned by the user running -\fB\%tar\fP, -the file mode is restored for newly-created regular files, and -all other types of entries receive default permissions. -If -\fB\%tar\fP -is being run by root, the default is to restore the owner unless the -\fB\-o\fP -option is also specified. -.TP -\fB\-q\fP (\fB\--fast-read\fP) -(x and t mode only) -Extract or list only the first archive entry that matches each pattern -or filename operand. -Exit as soon as each specified pattern or filename has been matched. -By default, the archive is always read to the very end, since -there can be multiple entries with the same name and, by convention, -later entries overwrite earlier entries. -This option is provided as a performance optimization. -.TP -\fB\-S\fP -(x mode only) -Extract files as sparse files. -For every block on disk, check first if it contains only NULL bytes and seek -over it otherwise. -This works similiar to the conv=sparse option of dd. -.TP -\fB\--strip-components\fP \fIcount\fP -(x mode only) -Remove the specified number of leading path elements. -Pathnames with fewer elements will be silently skipped. -Note that the pathname is edited after checking inclusion/exclusion patterns -but before security checks. -.TP -\fB\-s\fP \fIpattern\fP -Modify file or archive member names according to -\fIpattern\fP. -The pattern has the format -\fI/old/new/\fP [gps] -where -\fIold\fP -is a basic regular expression, -\fInew\fP -is the replacement string of the matched part, -and the optional trailing letters modify -how the replacement is handled. -If -\fIold\fP -is not matched, the pattern is skipped. -Within -\fInew\fP, -~ is substituted with the match, \1 to \9 with the content of -the corresponding captured group. -The optional trailing g specifies that matching should continue -after the matched part and stopped on the first unmatched pattern. -The optional trailing s specifies that the pattern applies to the value -of symbolic links. -The optional trailing p specifies that after a successful substitution -the original path name and the new path name should be printed to -standard error. -.TP -\fB\-T\fP \fIfilename\fP -In x or t mode, -\fB\%tar\fP -will read the list of names to be extracted from -\fIfilename\fP. -In c mode, -\fB\%tar\fP -will read names to be archived from -\fIfilename\fP. -The special name -``-C'' -on a line by itself will cause the current directory to be changed to -the directory specified on the following line. -Names are terminated by newlines unless -\fB\--null\fP -is specified. -Note that -\fB\--null\fP -also disables the special handling of lines containing -``-C''. -.TP -\fB\-U\fP -(x mode only) -Unlink files before creating them. -Without this option, -\fB\%tar\fP -overwrites existing files, which preserves existing hardlinks. -With this option, existing hardlinks will be broken, as will any -symlink that would affect the location of an extracted file. -.TP -\fB\--use-compress-program\fP \fIprogram\fP -Pipe the input (in x or t mode) or the output (in c mode) through -\fIprogram\fP -instead of using the builtin compression support. -.TP -\fB\-v\fP -Produce verbose output. -In create and extract modes, -\fB\%tar\fP -will list each file name as it is read from or written to -the archive. -In list mode, -\fB\%tar\fP -will produce output similar to that of -\fBls\fP(1). -Additional -\fB\-v\fP -options will provide additional detail. -.TP -\fB\--version\fP -Print version of -\fB\%tar\fP -and -\fB\%libarchive\fP, -and exit. -.TP -\fB\-w\fP -Ask for confirmation for every action. -.TP -\fB\-X\fP \fIfilename\fP -Read a list of exclusion patterns from the specified file. -See -\fB\--exclude\fP -for more information about the handling of exclusions. -.TP -\fB\-y\fP -(c mode only) -Compress the resulting archive with -\fBbzip2\fP(1). -In extract or list modes, this option is ignored. -Note that, unlike other -\fB\%tar\fP -implementations, this implementation recognizes bzip2 compression -automatically when reading archives. -.TP -\fB\-z\fP -(c mode only) -Compress the resulting archive with -\fBgzip\fP(1). -In extract or list modes, this option is ignored. -Note that, unlike other -\fB\%tar\fP -implementations, this implementation recognizes gzip compression -automatically when reading archives. -.TP -\fB\-Z\fP -(c mode only) -Compress the resulting archive with -\fBcompress\fP(1). -In extract or list modes, this option is ignored. -Note that, unlike other -\fB\%tar\fP -implementations, this implementation recognizes compress compression -automatically when reading archives. -.RE -.SH ENVIRONMENT -.ad l -The following environment variables affect the execution of -\fB\%tar\fP: -.RS 5 -.TP -.B LANG -The locale to use. -See -\fBenviron\fP(7) -for more information. -.TP -.B TAPE -The default tape device. -The -\fB\-f\fP -option overrides this. -.TP -.B TZ -The timezone to use when displaying dates. -See -\fBenviron\fP(7) -for more information. -.RE -.SH FILES -.ad l -.RS 5 -.TP -.B /dev/sa0 -The default tape device, if not overridden by the -.IR TAPE -environment variable or the -\fB\-f\fP -option. -.RE -.SH EXIT STATUS -.ad l -The \fBtar\fP utility exits 0 on success, and >0 if an error occurs. -.SH EXAMPLES -.ad l -The following creates a new archive -called -\fIfile.tar.gz\fP -that contains two files -\fIsource.c\fP -and -\fIsource.h\fP: -.RS 4 -\fB\%tar\fP \fB\-czf\fP \fIfile.tar.gz\fP \fIsource.c\fP \fIsource.h\fP -.RE -.PP -To view a detailed table of contents for this -archive: -.RS 4 -\fB\%tar\fP \fB\-tvf\fP \fIfile.tar.gz\fP -.RE -.PP -To extract all entries from the archive on -the default tape drive: -.RS 4 -\fB\%tar\fP \fB\-x\fP -.RE -.PP -To examine the contents of an ISO 9660 cdrom image: -.RS 4 -\fB\%tar\fP \fB\-tf\fP \fIimage.iso\fP -.RE -.PP -To move file hierarchies, invoke -\fB\%tar\fP -as -.RS 4 -\fB\%tar\fP \fB\-cf\fP \fI-\fP \fB\-C\fP \fIsrcdir\\fP. | \fB\%tar\fP \fB\-xpf\fP \fI-\fP \fB\-C\fP \fIdestdir\fP -.RE -or more traditionally -.RS 4 -cd srcdir \&; \fB\%tar\fP \fB\-cf\fP \fI-\\fP. | (cd destdir \&; \fB\%tar\fP \fB\-xpf\fP \fI-\fP) -.RE -.PP -In create mode, the list of files and directories to be archived -can also include directory change instructions of the form -\fB-C\fP \fIfoo/baz\fP -and archive inclusions of the form -\fB@\fP \fIarchive-file\fP. -For example, the command line -.RS 4 -\fB\%tar\fP \fB\-c\fP \fB\-f\fP \fInew.tar\fP \fIfoo1\fP \fB@\fP \fIold.tgz\fP \fB-C\fP \fI/tmp\fP \fIfoo2\fP -.RE -will create a new archive -\fInew.tar\fP. -\fB\%tar\fP -will read the file -\fIfoo1\fP -from the current directory and add it to the output archive. -It will then read each entry from -\fIold.tgz\fP -and add those entries to the output archive. -Finally, it will switch to the -\fI/tmp\fP -directory and add -\fIfoo2\fP -to the output archive. -.PP -An input file in -\fBmtree\fP(5) -format can be used to create an output archive with arbitrary ownership, -permissions, or names that differ from existing data on disk: -.PP -.RS 4 -$ cat input.mtree -.RE -.RS 4 -#mtree -.RE -.RS 4 -usr/bin uid=0 gid=0 mode=0755 type=dir -.RE -.RS 4 -usr/bin/ls uid=0 gid=0 mode=0755 type=file content=myls -.RE -.RS 4 -$ tar -cvf output.tar @input.mtree -.RE -.PP -The -\fB\--newer\fP -and -\fB\--newer-mtime\fP -switches accept a variety of common date and time specifications, including -``12 Mar 2005 7:14:29pm'', -``2005-03-12 19:14'', -``5 minutes ago'', -and -``19:14 PST May 1''. -.PP -The -\fB\--options\fP -argument can be used to control various details of archive generation -or reading. -For example, you can generate mtree output which only contains -\fBtype\fP, \fBtime\fP, -and -\fBuid\fP -keywords: -.RS 4 -\fB\%tar\fP \fB\-cf\fP \fIfile.tar\fP \fB\--format=mtree\fP \fB\--options='!all,type,time,uid'\fP \fIdir\fP -.RE -or you can set the compression level used by gzip or xz compression: -.RS 4 -\fB\%tar\fP \fB\-czf\fP \fIfile.tar\fP \fB\--options='compression-level=9'\fP. -.RE -For more details, see the explanation of the -\fB\%archive_read_set_options\fP() -and -\fB\%archive_write_set_options\fP() -API calls that are described in -\fBarchive_read\fP(3) -and -\fBarchive_write\fP(3). -.SH COMPATIBILITY -.ad l -The bundled-arguments format is supported for compatibility -with historic implementations. -It consists of an initial word (with no leading - character) in which -each character indicates an option. -Arguments follow as separate words. -The order of the arguments must match the order -of the corresponding characters in the bundled command word. -For example, -.RS 4 -\fB\%tar\fP \fBtbf\fP 32 \fIfile.tar\fP -.RE -specifies three flags -\fBt\fP, -\fBb\fP, -and -\fBf\fP. -The -\fBb\fP -and -\fBf\fP -flags both require arguments, -so there must be two additional items -on the command line. -The -\fI32\fP -is the argument to the -\fBb\fP -flag, and -\fIfile.tar\fP -is the argument to the -\fBf\fP -flag. -.PP -The mode options c, r, t, u, and x and the options -b, f, l, m, o, v, and w comply with SUSv2. -.PP -For maximum portability, scripts that invoke -\fB\%tar\fP -should use the bundled-argument format above, should limit -themselves to the -\fBc\fP, -\fBt\fP, -and -\fBx\fP -modes, and the -\fBb\fP, -\fBf\fP, -\fBm\fP, -\fBv\fP, -and -\fBw\fP -options. -.PP -Additional long options are provided to improve compatibility with other -tar implementations. -.SH SECURITY -.ad l -Certain security issues are common to many archiving programs, including -\fB\%tar\fP. -In particular, carefully-crafted archives can request that -\fB\%tar\fP -extract files to locations outside of the target directory. -This can potentially be used to cause unwitting users to overwrite -files they did not intend to overwrite. -If the archive is being extracted by the superuser, any file -on the system can potentially be overwritten. -There are three ways this can happen. -Although -\fB\%tar\fP -has mechanisms to protect against each one, -savvy users should be aware of the implications: -.RS 5 -.IP \(bu -Archive entries can have absolute pathnames. -By default, -\fB\%tar\fP -removes the leading -\fI/\fP -character from filenames before restoring them to guard against this problem. -.IP \(bu -Archive entries can have pathnames that include -\fI\& ..\fP -components. -By default, -\fB\%tar\fP -will not extract files containing -\fI\& ..\fP -components in their pathname. -.IP \(bu -Archive entries can exploit symbolic links to restore -files to other directories. -An archive can restore a symbolic link to another directory, -then use that link to restore a file into that directory. -To guard against this, -\fB\%tar\fP -checks each extracted path for symlinks. -If the final path element is a symlink, it will be removed -and replaced with the archive entry. -If -\fB\-U\fP -is specified, any intermediate symlink will also be unconditionally removed. -If neither -\fB\-U\fP -nor -\fB\-P\fP -is specified, -\fB\%tar\fP -will refuse to extract the entry. -.RE -To protect yourself, you should be wary of any archives that -come from untrusted sources. -You should examine the contents of an archive with -.RS 4 -\fB\%tar\fP \fB\-tf\fP \fIfilename\fP -.RE -before extraction. -You should use the -\fB\-k\fP -option to ensure that -\fB\%tar\fP -will not overwrite any existing files or the -\fB\-U\fP -option to remove any pre-existing files. -You should generally not extract archives while running with super-user -privileges. -Note that the -\fB\-P\fP -option to -\fB\%tar\fP -disables the security checks above and allows you to extract -an archive while preserving any absolute pathnames, -\fI\& ..\fP -components, or symlinks to other directories. -.SH SEE ALSO -.ad l -\fBbzip2\fP(1), -\fBcompress\fP(1), -\fBcpio\fP(1), -\fBgzip\fP(1), -\fBmt\fP(1), -\fBpax\fP(1), -\fBshar\fP(1), -\fBlibarchive\fP(3), -\fBlibarchive-formats\fP(5), -\fBtar\fP(5) -.SH STANDARDS -.ad l -There is no current POSIX standard for the tar command; it appeared -in -ISO/IEC 9945-1:1996 (``POSIX.1'') -but was dropped from -IEEE Std 1003.1-2001 (``POSIX.1''). -The options used by this implementation were developed by surveying a -number of existing tar implementations as well as the old POSIX specification -for tar and the current POSIX specification for pax. -.PP -The ustar and pax interchange file formats are defined by -IEEE Std 1003.1-2001 (``POSIX.1'') -for the pax command. -.SH HISTORY -.ad l -A -\fB\%tar\fP -command appeared in Seventh Edition Unix, which was released in January, 1979. -There have been numerous other implementations, -many of which extended the file format. -John Gilmore's -\fB\%pdtar\fP -public-domain implementation (circa November, 1987) -was quite influential, and formed the basis of GNU tar. -GNU tar was included as the standard system tar -in -FreeBSD -beginning with -FreeBSD 1.0. -.PP -This is a complete re-implementation based on the -\fBlibarchive\fP(3) -library. -.SH BUGS -.ad l -This program follows -ISO/IEC 9945-1:1996 (``POSIX.1'') -for the definition of the -\fB\-l\fP -option. -Note that GNU tar prior to version 1.15 treated -\fB\-l\fP -as a synonym for the -\fB\--one-file-system\fP -option. -.PP -The -\fB\-C\fP \fIdir\fP -option may differ from historic implementations. -.PP -All archive output is written in correctly-sized blocks, even -if the output is being compressed. -Whether or not the last output block is padded to a full -block size varies depending on the format and the -output device. -For tar and cpio formats, the last block of output is padded -to a full block size if the output is being -written to standard output or to a character or block device such as -a tape drive. -If the output is being written to a regular file, the last block -will not be padded. -Many compressors, including -\fBgzip\fP(1) -and -\fBbzip2\fP(1), -complain about the null padding when decompressing an archive created by -\fB\%tar\fP, -although they still extract it correctly. -.PP -The compression and decompression is implemented internally, so -there may be insignificant differences between the compressed output -generated by -.RS 4 -\fB\%tar\fP \fB\-czf\fP \fI-\fP file -.RE -and that generated by -.RS 4 -\fB\%tar\fP \fB\-cf\fP \fI-\fP file | \fB\%gzip\fP -.RE -.PP -The default should be to read and write archives to the standard I/O paths, -but tradition (and POSIX) dictates otherwise. -.PP -The -\fBr\fP -and -\fBu\fP -modes require that the archive be uncompressed -and located in a regular file on disk. -Other archives can be modified using -\fBc\fP -mode with the -\fI@archive-file\fP -extension. -.PP -To archive a file called -\fI@foo\fP -or -\fI-foo\fP -you must specify it as -\fI\& ./@foo\fP -or -\fI\& ./-foo\fP, -respectively. -.PP -In create mode, a leading -\fI\& ./\fP -is always removed. -A leading -\fI/\fP -is stripped unless the -\fB\-P\fP -option is specified. -.PP -There needs to be better support for file selection on both create -and extract. -.PP -There is not yet any support for multi-volume archives or for archiving -sparse files. -.PP -Converting between dissimilar archive formats (such as tar and cpio) using the -\fB@\fP \fI-\fP -convention can cause hard link information to be lost. -(This is a consequence of the incompatible ways that different archive -formats store hardlink information.) -.PP -There are alternative long options for many of the short options that -are deliberately not documented. diff --git a/libarchive/libarchive-2.8.0/doc/man/cpio.5 b/libarchive/libarchive-2.8.0/doc/man/cpio.5 deleted file mode 100644 index 922df01..0000000 --- a/libarchive/libarchive-2.8.0/doc/man/cpio.5 +++ /dev/null @@ -1,329 +0,0 @@ -.TH CPIO 5 "October 5, 2007" "" -.SH NAME -.ad l -\fB\%cpio\fP -\- format of cpio archive files -.SH DESCRIPTION -.ad l -The -\fB\%cpio\fP -archive format collects any number of files, directories, and other -file system objects (symbolic links, device nodes, etc.) into a single -stream of bytes. -.SS General Format -Each file system object in a -\fB\%cpio\fP -archive comprises a header record with basic numeric metadata -followed by the full pathname of the entry and the file data. -The header record stores a series of integer values that generally -follow the fields in -\fIstruct\fP stat. -(See -\fBstat\fP(2) -for details.) -The variants differ primarily in how they store those integers -(binary, octal, or hexadecimal). -The header is followed by the pathname of the -entry (the length of the pathname is stored in the header) -and any file data. -The end of the archive is indicated by a special record with -the pathname -``TRAILER!!!''. -.SS PWB format -XXX Any documentation of the original PWB/UNIX 1.0 format? XXX -.SS Old Binary Format -The old binary -\fB\%cpio\fP -format stores numbers as 2-byte and 4-byte binary values. -Each entry begins with a header in the following format: -.RS 4 -.nf -struct header_old_cpio { - unsigned short c_magic; - unsigned short c_dev; - unsigned short c_ino; - unsigned short c_mode; - unsigned short c_uid; - unsigned short c_gid; - unsigned short c_nlink; - unsigned short c_rdev; - unsigned short c_mtime[2]; - unsigned short c_namesize; - unsigned short c_filesize[2]; -}; -.RE -.PP -The -\fIunsigned\fP short -fields here are 16-bit integer values; the -\fIunsigned\fP int -fields are 32-bit integer values. -The fields are as follows -.RS 5 -.TP -\fImagic\fP -The integer value octal 070707. -This value can be used to determine whether this archive is -written with little-endian or big-endian integers. -.TP -\fIdev\fP, \fIino\fP -The device and inode numbers from the disk. -These are used by programs that read -\fB\%cpio\fP -archives to determine when two entries refer to the same file. -Programs that synthesize -\fB\%cpio\fP -archives should be careful to set these to distinct values for each entry. -.TP -\fImode\fP -The mode specifies both the regular permissions and the file type. -It consists of several bit fields as follows: -.RS 5 -.TP -0170000 -This masks the file type bits. -.TP -0140000 -File type value for sockets. -.TP -0120000 -File type value for symbolic links. -For symbolic links, the link body is stored as file data. -.TP -0100000 -File type value for regular files. -.TP -0060000 -File type value for block special devices. -.TP -0040000 -File type value for directories. -.TP -0020000 -File type value for character special devices. -.TP -0010000 -File type value for named pipes or FIFOs. -.TP -0004000 -SUID bit. -.TP -0002000 -SGID bit. -.TP -0001000 -Sticky bit. -On some systems, this modifies the behavior of executables and/or directories. -.TP -0000777 -The lower 9 bits specify read/write/execute permissions -for world, group, and user following standard POSIX conventions. -.RE -.TP -\fIuid\fP, \fIgid\fP -The numeric user id and group id of the owner. -.TP -\fInlink\fP -The number of links to this file. -Directories always have a value of at least two here. -Note that hardlinked files include file data with every copy in the archive. -.TP -\fIrdev\fP -For block special and character special entries, -this field contains the associated device number. -For all other entry types, it should be set to zero by writers -and ignored by readers. -.TP -\fImtime\fP -Modification time of the file, indicated as the number -of seconds since the start of the epoch, -00:00:00 UTC January 1, 1970. -The four-byte integer is stored with the most-significant 16 bits first -followed by the least-significant 16 bits. -Each of the two 16 bit values are stored in machine-native byte order. -.TP -\fInamesize\fP -The number of bytes in the pathname that follows the header. -This count includes the trailing NUL byte. -.TP -\fIfilesize\fP -The size of the file. -Note that this archive format is limited to -four gigabyte file sizes. -See -\fImtime\fP -above for a description of the storage of four-byte integers. -.RE -.PP -The pathname immediately follows the fixed header. -If the -\fBnamesize\fP -is odd, an additional NUL byte is added after the pathname. -The file data is then appended, padded with NUL -bytes to an even length. -.PP -Hardlinked files are not given special treatment; -the full file contents are included with each copy of the -file. -.SS Portable ASCII Format -Version 2 of the Single UNIX Specification (``SUSv2'') -standardized an ASCII variant that is portable across all -platforms. -It is commonly known as the -``old character'' -format or as the -``odc'' -format. -It stores the same numeric fields as the old binary format, but -represents them as 6-character or 11-character octal values. -.RS 4 -.nf -struct cpio_odc_header { - char c_magic[6]; - char c_dev[6]; - char c_ino[6]; - char c_mode[6]; - char c_uid[6]; - char c_gid[6]; - char c_nlink[6]; - char c_rdev[6]; - char c_mtime[11]; - char c_namesize[6]; - char c_filesize[11]; -}; -.RE -.PP -The fields are identical to those in the old binary format. -The name and file body follow the fixed header. -Unlike the old binary format, there is no additional padding -after the pathname or file contents. -If the files being archived are themselves entirely ASCII, then -the resulting archive will be entirely ASCII, except for the -NUL byte that terminates the name field. -.SS New ASCII Format -The "new" ASCII format uses 8-byte hexadecimal fields for -all numbers and separates device numbers into separate fields -for major and minor numbers. -.RS 4 -.nf -struct cpio_newc_header { - char c_magic[6]; - char c_ino[8]; - char c_mode[8]; - char c_uid[8]; - char c_gid[8]; - char c_nlink[8]; - char c_mtime[8]; - char c_filesize[8]; - char c_devmajor[8]; - char c_devminor[8]; - char c_rdevmajor[8]; - char c_rdevminor[8]; - char c_namesize[8]; - char c_check[8]; -}; -.RE -.PP -Except as specified below, the fields here match those specified -for the old binary format above. -.RS 5 -.TP -\fImagic\fP -The string -``070701''. -.TP -\fIcheck\fP -This field is always set to zero by writers and ignored by readers. -See the next section for more details. -.RE -.PP -The pathname is followed by NUL bytes so that the total size -of the fixed header plus pathname is a multiple of four. -Likewise, the file data is padded to a multiple of four bytes. -Note that this format supports only 4 gigabyte files (unlike the -older ASCII format, which supports 8 gigabyte files). -.PP -In this format, hardlinked files are handled by setting the -filesize to zero for each entry except the last one that -appears in the archive. -.SS New CRC Format -The CRC format is identical to the new ASCII format described -in the previous section except that the magic field is set -to -``070702'' -and the -\fIcheck\fP -field is set to the sum of all bytes in the file data. -This sum is computed treating all bytes as unsigned values -and using unsigned arithmetic. -Only the least-significant 32 bits of the sum are stored. -.SS HP variants -The -\fB\%cpio\fP -implementation distributed with HPUX used XXXX but stored -device numbers differently XXX. -.SS Other Extensions and Variants -Sun Solaris uses additional file types to store extended file -data, including ACLs and extended attributes, as special -entries in cpio archives. -.PP -XXX Others? XXX -.SH BUGS -.ad l -The -``CRC'' -format is mis-named, as it uses a simple checksum and -not a cyclic redundancy check. -.PP -The old binary format is limited to 16 bits for user id, -group id, device, and inode numbers. -It is limited to 4 gigabyte file sizes. -.PP -The old ASCII format is limited to 18 bits for -the user id, group id, device, and inode numbers. -It is limited to 8 gigabyte file sizes. -.PP -The new ASCII format is limited to 4 gigabyte file sizes. -.PP -None of the cpio formats store user or group names, -which are essential when moving files between systems with -dissimilar user or group numbering. -.PP -Especially when writing older cpio variants, it may be necessary -to map actual device/inode values to synthesized values that -fit the available fields. -With very large filesystems, this may be necessary even for -the newer formats. -.SH SEE ALSO -.ad l -\fBcpio\fP(1), -\fBtar\fP(5) -.SH STANDARDS -.ad l -The -\fB\%cpio\fP -utility is no longer a part of POSIX or the Single Unix Standard. -It last appeared in -Version 2 of the Single UNIX Specification (``SUSv2''). -It has been supplanted in subsequent standards by -\fBpax\fP(1). -The portable ASCII format is currently part of the specification for the -\fBpax\fP(1) -utility. -.SH HISTORY -.ad l -The original cpio utility was written by Dick Haight -while working in AT&T's Unix Support Group. -It appeared in 1977 as part of PWB/UNIX 1.0, the -``Programmer's Work Bench'' -derived from -At v6 -that was used internally at AT&T. -Both the old binary and old character formats were in use -by 1980, according to the System III source released -by SCO under their -``Ancient Unix'' -license. -The character format was adopted as part of -IEEE Std 1003.1-1988 (``POSIX.1''). -XXX when did "newc" appear? Who invented it? When did HP come out with their variant? When did Sun introduce ACLs and extended attributes? XXX diff --git a/libarchive/libarchive-2.8.0/doc/man/libarchive-formats.5 b/libarchive/libarchive-2.8.0/doc/man/libarchive-formats.5 deleted file mode 100644 index ff87c8b..0000000 --- a/libarchive/libarchive-2.8.0/doc/man/libarchive-formats.5 +++ /dev/null @@ -1,341 +0,0 @@ -.TH libarchive-formats 5 "December 27, 2009" "" -.SH NAME -.ad l -\fB\%libarchive-formats\fP -\- archive formats supported by the libarchive library -.SH DESCRIPTION -.ad l -The -\fBlibarchive\fP(3) -library reads and writes a variety of streaming archive formats. -Generally speaking, all of these archive formats consist of a series of -``entries''. -Each entry stores a single file system object, such as a file, directory, -or symbolic link. -.PP -The following provides a brief description of each format supported -by libarchive, with some information about recognized extensions or -limitations of the current library support. -Note that just because a format is supported by libarchive does not -imply that a program that uses libarchive will support that format. -Applications that use libarchive specify which formats they wish -to support, though many programs do use libarchive convenience -functions to enable all supported formats. -.SS Tar Formats -The -\fBlibarchive\fP(3) -library can read most tar archives. -However, it only writes POSIX-standard -``ustar'' -and -``pax interchange'' -formats. -.PP -All tar formats store each entry in one or more 512-byte records. -The first record is used for file metadata, including filename, -timestamp, and mode information, and the file data is stored in -subsequent records. -Later variants have extended this by either appropriating undefined -areas of the header record, extending the header to multiple records, -or by storing special entries that modify the interpretation of -subsequent entries. -.PP -.RS 5 -.TP -\fBgnutar\fP -The -\fBlibarchive\fP(3) -library can read GNU-format tar archives. -It currently supports the most popular GNU extensions, including -modern long filename and linkname support, as well as atime and ctime data. -The libarchive library does not support multi-volume -archives, nor the old GNU long filename format. -It can read GNU sparse file entries, including the new POSIX-based -formats, but cannot write GNU sparse file entries. -.TP -\fBpax\fP -The -\fBlibarchive\fP(3) -library can read and write POSIX-compliant pax interchange format -archives. -Pax interchange format archives are an extension of the older ustar -format that adds a separate entry with additional attributes stored -as key/value pairs immediately before each regular entry. -The presence of these additional entries is the only difference between -pax interchange format and the older ustar format. -The extended attributes are of unlimited length and are stored -as UTF-8 Unicode strings. -Keywords defined in the standard are in all lowercase; vendors are allowed -to define custom keys by preceding them with the vendor name in all uppercase. -When writing pax archives, libarchive uses many of the SCHILY keys -defined by Joerg Schilling's -``star'' -archiver and a few LIBARCHIVE keys. -The libarchive library can read most of the SCHILY keys -and most of the GNU keys introduced by GNU tar. -It silently ignores any keywords that it does not understand. -.TP -\fBrestricted\fP pax -The libarchive library can also write pax archives in which it -attempts to suppress the extended attributes entry whenever -possible. -The result will be identical to a ustar archive unless the -extended attributes entry is required to store a long file -name, long linkname, extended ACL, file flags, or if any of the standard -ustar data (user name, group name, UID, GID, etc) cannot be fully -represented in the ustar header. -In all cases, the result can be dearchived by any program that -can read POSIX-compliant pax interchange format archives. -Programs that correctly read ustar format (see below) will also be -able to read this format; any extended attributes will be extracted as -separate files stored in -\fIPaxHeader\fP -directories. -.TP -\fBustar\fP -The libarchive library can both read and write this format. -This format has the following limitations: -.RS 5 -.IP \(bu -Device major and minor numbers are limited to 21 bits. -Nodes with larger numbers will not be added to the archive. -.IP \(bu -Path names in the archive are limited to 255 bytes. -(Shorter if there is no / character in exactly the right place.) -.IP \(bu -Symbolic links and hard links are stored in the archive with -the name of the referenced file. -This name is limited to 100 bytes. -.IP \(bu -Extended attributes, file flags, and other extended -security information cannot be stored. -.IP \(bu -Archive entries are limited to 8 gigabytes in size. -.RE -Note that the pax interchange format has none of these restrictions. -.RE -.PP -The libarchive library also reads a variety of commonly-used extensions to -the basic tar format. -These extensions are recognized automatically whenever they appear. -.RS 5 -.TP -Numeric extensions. -The POSIX standards require fixed-length numeric fields to be written with -some character position reserved for terminators. -Libarchive allows these fields to be written without terminator characters. -This extends the allowable range; in particular, ustar archives with this -extension can support entries up to 64 gigabytes in size. -Libarchive also recognizes base-256 values in most numeric fields. -This essentially removes all limitations on file size, modification time, -and device numbers. -.TP -Solaris extensions -Libarchive recognizes ACL and extended attribute records written -by Solaris tar. -Currently, libarchive only has support for old-style ACLs; the -newer NFSv4 ACLs are recognized but discarded. -.RE -.PP -The first tar program appeared in Seventh Edition Unix in 1979. -The first official standard for the tar file format was the -``ustar'' -(Unix Standard Tar) format defined by POSIX in 1988. -POSIX.1-2001 extended the ustar format to create the -``pax interchange'' -format. -.SS Cpio Formats -The libarchive library can read a number of common cpio variants and can write -``odc'' -and -``newc'' -format archives. -A cpio archive stores each entry as a fixed-size header followed -by a variable-length filename and variable-length data. -Unlike the tar format, the cpio format does only minimal padding -of the header or file data. -There are several cpio variants, which differ primarily in -how they store the initial header: some store the values as -octal or hexadecimal numbers in ASCII, others as binary values of -varying byte order and length. -.RS 5 -.TP -\fBbinary\fP -The libarchive library transparently reads both big-endian and little-endian -variants of the original binary cpio format. -This format used 32-bit binary values for file size and mtime, -and 16-bit binary values for the other fields. -.TP -\fBodc\fP -The libarchive library can both read and write this -POSIX-standard format, which is officially known as the -``cpio interchange format'' -or the -``octet-oriented cpio archive format'' -and sometimes unofficially referred to as the -``old character format''. -This format stores the header contents as octal values in ASCII. -It is standard, portable, and immune from byte-order confusion. -File sizes and mtime are limited to 33 bits (8GB file size), -other fields are limited to 18 bits. -.TP -\fBSVR4\fP -The libarchive library can read both CRC and non-CRC variants of -this format. -The SVR4 format uses eight-digit hexadecimal values for -all header fields. -This limits file size to 4GB, and also limits the mtime and -other fields to 32 bits. -The SVR4 format can optionally include a CRC of the file -contents, although libarchive does not currently verify this CRC. -.RE -.PP -Cpio first appeared in PWB/UNIX 1.0, which was released within -AT&T in 1977. -PWB/UNIX 1.0 formed the basis of System III Unix, released outside -of AT&T in 1981. -This makes cpio older than tar, although cpio was not included -in Version 7 AT&T Unix. -As a result, the tar command became much better known in universities -and research groups that used Version 7. -The combination of the -\fB\%find\fP -and -\fB\%cpio\fP -utilities provided very precise control over file selection. -Unfortunately, the format has many limitations that make it unsuitable -for widespread use. -Only the POSIX format permits files over 4GB, and its 18-bit -limit for most other fields makes it unsuitable for modern systems. -In addition, cpio formats only store numeric UID/GID values (not -usernames and group names), which can make it very difficult to correctly -transfer archives across systems with dissimilar user numbering. -.SS Shar Formats -A -``shell archive'' -is a shell script that, when executed on a POSIX-compliant -system, will recreate a collection of file system objects. -The libarchive library can write two different kinds of shar archives: -.RS 5 -.TP -\fBshar\fP -The traditional shar format uses a limited set of POSIX -commands, including -\fBecho\fP(1), -\fBmkdir\fP(1), -and -\fBsed\fP(1). -It is suitable for portably archiving small collections of plain text files. -However, it is not generally well-suited for large archives -(many implementations of -\fBsh\fP(1) -have limits on the size of a script) nor should it be used with non-text files. -.TP -\fBshardump\fP -This format is similar to shar but encodes files using -\fBuuencode\fP(1) -so that the result will be a plain text file regardless of the file contents. -It also includes additional shell commands that attempt to reproduce as -many file attributes as possible, including owner, mode, and flags. -The additional commands used to restore file attributes make -shardump archives less portable than plain shar archives. -.RE -.SS ISO9660 format -Libarchive can read and extract from files containing ISO9660-compliant -CDROM images. -In many cases, this can remove the need to burn a physical CDROM -just in order to read the files contained in an ISO9660 image. -It also avoids security and complexity issues that come with -virtual mounts and loopback devices. -Libarchive supports the most common Rockridge extensions and has partial -support for Joliet extensions. -If both extensions are present, the Joliet extensions will be -used and the Rockridge extensions will be ignored. -In particular, this can create problems with hardlinks and symlinks, -which are supported by Rockridge but not by Joliet. -.SS Zip format -Libarchive can read and write zip format archives that have -uncompressed entries and entries compressed with the -``deflate'' -algorithm. -Older zip compression algorithms are not supported. -It can extract jar archives, archives that use Zip64 extensions and many -self-extracting zip archives. -Libarchive reads Zip archives as they are being streamed, -which allows it to read archives of arbitrary size. -It currently does not use the central directory; this -limits libarchive's ability to support some self-extracting -archives and ones that have been modified in certain ways. -.SS Archive (library) file format -The Unix archive format (commonly created by the -\fBar\fP(1) -archiver) is a general-purpose format which is -used almost exclusively for object files to be -read by the link editor -\fBld\fP(1). -The ar format has never been standardised. -There are two common variants: -the GNU format derived from SVR4, -and the BSD format, which first appeared in 4.4BSD. -The two differ primarily in their handling of filenames -longer than 15 characters: -the GNU/SVR4 variant writes a filename table at the beginning of the archive; -the BSD format stores each long filename in an extension -area adjacent to the entry. -Libarchive can read both extensions, -including archives that may include both types of long filenames. -Programs using libarchive can write GNU/SVR4 format -if they provide a filename table to be written into -the archive before any of the entries. -Any entries whose names are not in the filename table -will be written using BSD-style long filenames. -This can cause problems for programs such as -GNU ld that do not support the BSD-style long filenames. -.SS mtree -Libarchive can read and write files in -\fBmtree\fP(5) -format. -This format is not a true archive format, but rather a textual description -of a file hierarchy in which each line specifies the name of a file and -provides specific metadata about that file. -Libarchive can read all of the keywords supported by both -the NetBSD and FreeBSD versions of -\fBmtree\fP(1), -although many of the keywords cannot currently be stored in an -Tn archive_entry -object. -When writing, libarchive supports use of the -\fBarchive_write_set_options\fP(3) -interface to specify which keywords should be included in the -output. -If libarchive was compiled with access to suitable -cryptographic libraries (such as the OpenSSL libraries), -it can compute hash entries such as -\fBsha512\fP -or -\fBmd5\fP -from file data being written to the mtree writer. -.PP -When reading an mtree file, libarchive will locate the corresponding -files on disk using the -\fBcontents\fP -keyword if present or the regular filename. -If it can locate and open the file on disk, it will use that -to fill in any metadata that is missing from the mtree file -and will read the file contents and return those to the program -using libarchive. -If it cannot locate and open the file on disk, libarchive -will return an error for any attempt to read the entry -body. -.SH SEE ALSO -.ad l -\fBar\fP(1), -\fBcpio\fP(1), -\fBmkisofs\fP(1), -\fBshar\fP(1), -\fBtar\fP(1), -\fBzip\fP(1), -\fBzlib\fP(3), -\fBcpio\fP(5), -\fBmtree\fP(5), -\fBtar\fP(5) diff --git a/libarchive/libarchive-2.8.0/doc/man/libarchive.3 b/libarchive/libarchive-2.8.0/doc/man/libarchive.3 deleted file mode 100644 index 1af1861..0000000 --- a/libarchive/libarchive-2.8.0/doc/man/libarchive.3 +++ /dev/null @@ -1,315 +0,0 @@ -.TH LIBARCHIVE 3 "August 19, 2006" "" -.SH NAME -.ad l -\fB\%libarchive\fP -\- functions for reading and writing streaming archives -.SH LIBRARY -.ad l -Lb libarchive -.SH OVERVIEW -.ad l -The -\fB\%libarchive\fP -library provides a flexible interface for reading and writing -streaming archive files such as tar and cpio. -The library is inherently stream-oriented; readers serially iterate through -the archive, writers serially add things to the archive. -In particular, note that there is no built-in support for -random access nor for in-place modification. -.PP -When reading an archive, the library automatically detects the -format and the compression. -The library currently has read support for: -.RS 5 -.IP \(bu -old-style tar archives, -.IP \(bu -most variants of the POSIX -``ustar'' -format, -.IP \(bu -the POSIX -``pax interchange'' -format, -.IP \(bu -GNU-format tar archives, -.IP \(bu -most common cpio archive formats, -.IP \(bu -ISO9660 CD images (with or without RockRidge extensions), -.IP \(bu -Zip archives. -.RE -The library automatically detects archives compressed with -\fBgzip\fP(1), -\fBbzip2\fP(1), -or -\fBcompress\fP(1) -and decompresses them transparently. -.PP -When writing an archive, you can specify the compression -to be used and the format to use. -The library can write -.RS 5 -.IP \(bu -POSIX-standard -``ustar'' -archives, -.IP \(bu -POSIX -``pax interchange format'' -archives, -.IP \(bu -POSIX octet-oriented cpio archives, -.IP \(bu -two different variants of shar archives. -.RE -Pax interchange format is an extension of the tar archive format that -eliminates essentially all of the limitations of historic tar formats -in a standard fashion that is supported -by POSIX-compliant -\fBpax\fP(1) -implementations on many systems as well as several newer implementations of -\fBtar\fP(1). -Note that the default write format will suppress the pax extended -attributes for most entries; explicitly requesting pax format will -enable those attributes for all entries. -.PP -The read and write APIs are accessed through the -\fB\%archive_read_XXX\fP() -functions and the -\fB\%archive_write_XXX\fP() -functions, respectively, and either can be used independently -of the other. -.PP -The rest of this manual page provides an overview of the library -operation. -More detailed information can be found in the individual manual -pages for each API or utility function. -.SH READING AN ARCHIVE -.ad l -To read an archive, you must first obtain an initialized -Tn struct archive -object from -\fB\%archive_read_new\fP(). -You can then modify this object for the desired operations with the -various -\fB\%archive_read_set_XXX\fP() -and -\fB\%archive_read_support_XXX\fP() -functions. -In particular, you will need to invoke appropriate -\fB\%archive_read_support_XXX\fP() -functions to enable the corresponding compression and format -support. -Note that these latter functions perform two distinct operations: -they cause the corresponding support code to be linked into your -program, and they enable the corresponding auto-detect code. -Unless you have specific constraints, you will generally want -to invoke -\fB\%archive_read_support_compression_all\fP() -and -\fB\%archive_read_support_format_all\fP() -to enable auto-detect for all formats and compression types -currently supported by the library. -.PP -Once you have prepared the -Tn struct archive -object, you call -\fB\%archive_read_open\fP() -to actually open the archive and prepare it for reading. -There are several variants of this function; -the most basic expects you to provide pointers to several -functions that can provide blocks of bytes from the archive. -There are convenience forms that allow you to -specify a filename, file descriptor, -\fIFILE *\fP -object, or a block of memory from which to read the archive data. -Note that the core library makes no assumptions about the -size of the blocks read; -callback functions are free to read whatever block size is -most appropriate for the medium. -.PP -Each archive entry consists of a header followed by a certain -amount of data. -You can obtain the next header with -\fB\%archive_read_next_header\fP(), -which returns a pointer to an -Tn struct archive_entry -structure with information about the current archive element. -If the entry is a regular file, then the header will be followed -by the file data. -You can use -\fB\%archive_read_data\fP() -(which works much like the -\fBread\fP(2) -system call) -to read this data from the archive. -You may prefer to use the higher-level -\fB\%archive_read_data_skip\fP(), -which reads and discards the data for this entry, -\fB\%archive_read_data_to_buffer\fP(), -which reads the data into an in-memory buffer, -\fB\%archive_read_data_to_file\fP(), -which copies the data to the provided file descriptor, or -\fB\%archive_read_extract\fP(), -which recreates the specified entry on disk and copies data -from the archive. -In particular, note that -\fB\%archive_read_extract\fP() -uses the -Tn struct archive_entry -structure that you provide it, which may differ from the -entry just read from the archive. -In particular, many applications will want to override the -pathname, file permissions, or ownership. -.PP -Once you have finished reading data from the archive, you -should call -\fB\%archive_read_close\fP() -to close the archive, then call -\fB\%archive_read_finish\fP() -to release all resources, including all memory allocated by the library. -.PP -The -\fBarchive_read\fP(3) -manual page provides more detailed calling information for this API. -.SH WRITING AN ARCHIVE -.ad l -You use a similar process to write an archive. -The -\fB\%archive_write_new\fP() -function creates an archive object useful for writing, -the various -\fB\%archive_write_set_XXX\fP() -functions are used to set parameters for writing the archive, and -\fB\%archive_write_open\fP() -completes the setup and opens the archive for writing. -.PP -Individual archive entries are written in a three-step -process: -You first initialize a -Tn struct archive_entry -structure with information about the new entry. -At a minimum, you should set the pathname of the -entry and provide a -\fIstruct\fP stat -with a valid -\fIst_mode\fP -field, which specifies the type of object and -\fIst_size\fP -field, which specifies the size of the data portion of the object. -The -\fB\%archive_write_header\fP() -function actually writes the header data to the archive. -You can then use -\fB\%archive_write_data\fP() -to write the actual data. -.PP -After all entries have been written, use the -\fB\%archive_write_finish\fP() -function to release all resources. -.PP -The -\fBarchive_write\fP(3) -manual page provides more detailed calling information for this API. -.SH DESCRIPTION -.ad l -Detailed descriptions of each function are provided by the -corresponding manual pages. -.PP -All of the functions utilize an opaque -Tn struct archive -datatype that provides access to the archive contents. -.PP -The -Tn struct archive_entry -structure contains a complete description of a single archive -entry. -It uses an opaque interface that is fully documented in -\fBarchive_entry\fP(3). -.PP -Users familiar with historic formats should be aware that the newer -variants have eliminated most restrictions on the length of textual fields. -Clients should not assume that filenames, link names, user names, or -group names are limited in length. -In particular, pax interchange format can easily accommodate pathnames -in arbitrary character sets that exceed -\fIPATH_MAX\fP. -.SH RETURN VALUES -.ad l -Most functions return zero on success, non-zero on error. -The return value indicates the general severity of the error, ranging -from -\fBARCHIVE_WARN\fP, -which indicates a minor problem that should probably be reported -to the user, to -\fBARCHIVE_FATAL\fP, -which indicates a serious problem that will prevent any further -operations on this archive. -On error, the -\fB\%archive_errno\fP() -function can be used to retrieve a numeric error code (see -\fBerrno\fP(2)). -The -\fB\%archive_error_string\fP() -returns a textual error message suitable for display. -.PP -\fB\%archive_read_new\fP() -and -\fB\%archive_write_new\fP() -return pointers to an allocated and initialized -Tn struct archive -object. -.PP -\fB\%archive_read_data\fP() -and -\fB\%archive_write_data\fP() -return a count of the number of bytes actually read or written. -A value of zero indicates the end of the data for this entry. -A negative value indicates an error, in which case the -\fB\%archive_errno\fP() -and -\fB\%archive_error_string\fP() -functions can be used to obtain more information. -.SH ENVIRONMENT -.ad l -There are character set conversions within the -\fBarchive_entry\fP(3) -functions that are impacted by the currently-selected locale. -.SH SEE ALSO -.ad l -\fBtar\fP(1), -\fBarchive_entry\fP(3), -\fBarchive_read\fP(3), -\fBarchive_util\fP(3), -\fBarchive_write\fP(3), -\fBtar\fP(5) -.SH HISTORY -.ad l -The -\fB\%libarchive\fP -library first appeared in -FreeBSD 5.3. -.SH AUTHORS -.ad l --nosplit -The -\fB\%libarchive\fP -library was written by -Tim Kientzle \%<kientzle@acm.org.> -.SH BUGS -.ad l -Some archive formats support information that is not supported by -Tn struct archive_entry. -Such information cannot be fully archived or restored using this library. -This includes, for example, comments, character sets, -or the arbitrary key/value pairs that can appear in -pax interchange format archives. -.PP -Conversely, of course, not all of the information that can be -stored in an -Tn struct archive_entry -is supported by all formats. -For example, cpio formats do not support nanosecond timestamps; -old tar formats do not support large device numbers. diff --git a/libarchive/libarchive-2.8.0/doc/man/libarchive_internals.3 b/libarchive/libarchive-2.8.0/doc/man/libarchive_internals.3 deleted file mode 100644 index 98b99a3..0000000 --- a/libarchive/libarchive-2.8.0/doc/man/libarchive_internals.3 +++ /dev/null @@ -1,361 +0,0 @@ -.TH LIBARCHIVE 3 "April 16, 2007" "" -.SH NAME -.ad l -\fB\%libarchive_internals\fP -\- description of libarchive internal interfaces -.SH OVERVIEW -.ad l -The -\fB\%libarchive\fP -library provides a flexible interface for reading and writing -streaming archive files such as tar and cpio. -Internally, it follows a modular layered design that should -make it easy to add new archive and compression formats. -.SH GENERAL ARCHITECTURE -.ad l -Externally, libarchive exposes most operations through an -opaque, object-style interface. -The -\fBarchive_entry\fP(1) -objects store information about a single filesystem object. -The rest of the library provides facilities to write -\fBarchive_entry\fP(1) -objects to archive files, -read them from archive files, -and write them to disk. -(There are plans to add a facility to read -\fBarchive_entry\fP(1) -objects from disk as well.) -.PP -The read and write APIs each have four layers: a public API -layer, a format layer that understands the archive file format, -a compression layer, and an I/O layer. -The I/O layer is completely exposed to clients who can replace -it entirely with their own functions. -.PP -In order to provide as much consistency as possible for clients, -some public functions are virtualized. -Eventually, it should be possible for clients to open -an archive or disk writer, and then use a single set of -code to select and write entries, regardless of the target. -.SH READ ARCHITECTURE -.ad l -From the outside, clients use the -\fBarchive_read\fP(3) -API to manipulate an -\fB\%archive\fP -object to read entries and bodies from an archive stream. -Internally, the -\fB\%archive\fP -object is cast to an -\fB\%archive_read\fP -object, which holds all read-specific data. -The API has four layers: -The lowest layer is the I/O layer. -This layer can be overridden by clients, but most clients use -the packaged I/O callbacks provided, for example, by -\fBarchive_read_open_memory\fP(3), -and -\fBarchive_read_open_fd\fP(3). -The compression layer calls the I/O layer to -read bytes and decompresses them for the format layer. -The format layer unpacks a stream of uncompressed bytes and -creates -\fB\%archive_entry\fP -objects from the incoming data. -The API layer tracks overall state -(for example, it prevents clients from reading data before reading a header) -and invokes the format and compression layer operations -through registered function pointers. -In particular, the API layer drives the format-detection process: -When opening the archive, it reads an initial block of data -and offers it to each registered compression handler. -The one with the highest bid is initialized with the first block. -Similarly, the format handlers are polled to see which handler -is the best for each archive. -(Prior to 2.4.0, the format bidders were invoked for each -entry, but this design hindered error recovery.) -.SS I/O Layer and Client Callbacks -The read API goes to some lengths to be nice to clients. -As a result, there are few restrictions on the behavior of -the client callbacks. -.PP -The client read callback is expected to provide a block -of data on each call. -A zero-length return does indicate end of file, but otherwise -blocks may be as small as one byte or as large as the entire file. -In particular, blocks may be of different sizes. -.PP -The client skip callback returns the number of bytes actually -skipped, which may be much smaller than the skip requested. -The only requirement is that the skip not be larger. -In particular, clients are allowed to return zero for any -skip that they don't want to handle. -The skip callback must never be invoked with a negative value. -.PP -Keep in mind that not all clients are reading from disk: -clients reading from networks may provide different-sized -blocks on every request and cannot skip at all; -advanced clients may use -\fBmmap\fP(2) -to read the entire file into memory at once and return the -entire file to libarchive as a single block; -other clients may begin asynchronous I/O operations for the -next block on each request. -.SS Decompresssion Layer -The decompression layer not only handles decompression, -it also buffers data so that the format handlers see a -much nicer I/O model. -The decompression API is a two stage peek/consume model. -A read_ahead request specifies a minimum read amount; -the decompression layer must provide a pointer to at least -that much data. -If more data is immediately available, it should return more: -the format layer handles bulk data reads by asking for a minimum -of one byte and then copying as much data as is available. -.PP -A subsequent call to the -\fB\%consume\fP() -function advances the read pointer. -Note that data returned from a -\fB\%read_ahead\fP() -call is guaranteed to remain in place until -the next call to -\fB\%read_ahead\fP(). -Intervening calls to -\fB\%consume\fP() -should not cause the data to move. -.PP -Skip requests must always be handled exactly. -Decompression handlers that cannot seek forward should -not register a skip handler; -the API layer fills in a generic skip handler that reads and discards data. -.PP -A decompression handler has a specific lifecycle: -.RS 5 -.TP -Registration/Configuration -When the client invokes the public support function, -the decompression handler invokes the internal -\fB\%__archive_read_register_compression\fP() -function to provide bid and initialization functions. -This function returns -\fBNULL\fP -on error or else a pointer to a -\fBstruct\fP decompressor_t. -This structure contains a -\fIvoid\fP * config -slot that can be used for storing any customization information. -.TP -Bid -The bid function is invoked with a pointer and size of a block of data. -The decompressor can access its config data -through the -\fIdecompressor\fP -element of the -\fBarchive_read\fP -object. -The bid function is otherwise stateless. -In particular, it must not perform any I/O operations. -.PP -The value returned by the bid function indicates its suitability -for handling this data stream. -A bid of zero will ensure that this decompressor is never invoked. -Return zero if magic number checks fail. -Otherwise, your initial implementation should return the number of bits -actually checked. -For example, if you verify two full bytes and three bits of another -byte, bid 19. -Note that the initial block may be very short; -be careful to only inspect the data you are given. -(The current decompressors require two bytes for correct bidding.) -.TP -Initialize -The winning bidder will have its init function called. -This function should initialize the remaining slots of the -\fIstruct\fP decompressor_t -object pointed to by the -\fIdecompressor\fP -element of the -\fIarchive_read\fP -object. -In particular, it should allocate any working data it needs -in the -\fIdata\fP -slot of that structure. -The init function is called with the block of data that -was used for tasting. -At this point, the decompressor is responsible for all I/O -requests to the client callbacks. -The decompressor is free to read more data as and when -necessary. -.TP -Satisfy I/O requests -The format handler will invoke the -\fIread_ahead\fP, -\fIconsume\fP, -and -\fIskip\fP -functions as needed. -.TP -Finish -The finish method is called only once when the archive is closed. -It should release anything stored in the -\fIdata\fP -and -\fIconfig\fP -slots of the -\fIdecompressor\fP -object. -It should not invoke the client close callback. -.RE -.SS Format Layer -The read formats have a similar lifecycle to the decompression handlers: -.RS 5 -.TP -Registration -Allocate your private data and initialize your pointers. -.TP -Bid -Formats bid by invoking the -\fB\%read_ahead\fP() -decompression method but not calling the -\fB\%consume\fP() -method. -This allows each bidder to look ahead in the input stream. -Bidders should not look further ahead than necessary, as long -look aheads put pressure on the decompression layer to buffer -lots of data. -Most formats only require a few hundred bytes of look ahead; -look aheads of a few kilobytes are reasonable. -(The ISO9660 reader sometimes looks ahead by 48k, which -should be considered an upper limit.) -.TP -Read header -The header read is usually the most complex part of any format. -There are a few strategies worth mentioning: -For formats such as tar or cpio, reading and parsing the header is -straightforward since headers alternate with data. -For formats that store all header data at the beginning of the file, -the first header read request may have to read all headers into -memory and store that data, sorted by the location of the file -data. -Subsequent header read requests will skip forward to the -beginning of the file data and return the corresponding header. -.TP -Read Data -The read data interface supports sparse files; this requires that -each call return a block of data specifying the file offset and -size. -This may require you to carefully track the location so that you -can return accurate file offsets for each read. -Remember that the decompressor will return as much data as it has. -Generally, you will want to request one byte, -examine the return value to see how much data is available, and -possibly trim that to the amount you can use. -You should invoke consume for each block just before you return it. -.TP -Skip All Data -The skip data call should skip over all file data and trailing padding. -This is called automatically by the API layer just before each -header read. -It is also called in response to the client calling the public -\fB\%data_skip\fP() -function. -.TP -Cleanup -On cleanup, the format should release all of its allocated memory. -.RE -.SS API Layer -XXX to do XXX -.SH WRITE ARCHITECTURE -.ad l -The write API has a similar set of four layers: -an API layer, a format layer, a compression layer, and an I/O layer. -The registration here is much simpler because only -one format and one compression can be registered at a time. -.SS I/O Layer and Client Callbacks -XXX To be written XXX -.SS Compression Layer -XXX To be written XXX -.SS Format Layer -XXX To be written XXX -.SS API Layer -XXX To be written XXX -.SH WRITE_DISK ARCHITECTURE -.ad l -The write_disk API is intended to look just like the write API -to clients. -Since it does not handle multiple formats or compression, it -is not layered internally. -.SH GENERAL SERVICES -.ad l -The -\fB\%archive_read\fP, -\fB\%archive_write\fP, -and -\fB\%archive_write_disk\fP -objects all contain an initial -\fB\%archive\fP -object which provides common support for a set of standard services. -(Recall that ANSI/ISO C90 guarantees that you can cast freely between -a pointer to a structure and a pointer to the first element of that -structure.) -The -\fB\%archive\fP -object has a magic value that indicates which API this object -is associated with, -slots for storing error information, -and function pointers for virtualized API functions. -.SH MISCELLANEOUS NOTES -.ad l -Connecting existing archiving libraries into libarchive is generally -quite difficult. -In particular, many existing libraries strongly assume that you -are reading from a file; they seek forwards and backwards as necessary -to locate various pieces of information. -In contrast, libarchive never seeks backwards in its input, which -sometimes requires very different approaches. -.PP -For example, libarchive's ISO9660 support operates very differently -from most ISO9660 readers. -The libarchive support utilizes a work-queue design that -keeps a list of known entries sorted by their location in the input. -Whenever libarchive's ISO9660 implementation is asked for the next -header, checks this list to find the next item on the disk. -Directories are parsed when they are encountered and new -items are added to the list. -This design relies heavily on the ISO9660 image being optimized so that -directories always occur earlier on the disk than the files they -describe. -.PP -Depending on the specific format, such approaches may not be possible. -The ZIP format specification, for example, allows archivers to store -key information only at the end of the file. -In theory, it is possible to create ZIP archives that cannot -be read without seeking. -Fortunately, such archives are very rare, and libarchive can read -most ZIP archives, though it cannot always extract as much information -as a dedicated ZIP program. -.SH SEE ALSO -.ad l -\fBarchive\fP(3), -\fBarchive_entry\fP(3), -\fBarchive_read\fP(3), -\fBarchive_write\fP(3), -\fBarchive_write_disk\fP(3) -.SH HISTORY -.ad l -The -\fB\%libarchive\fP -library first appeared in -FreeBSD 5.3. -.SH AUTHORS -.ad l --nosplit -The -\fB\%libarchive\fP -library was written by -Tim Kientzle \%<kientzle@acm.org.> -.SH BUGS -.ad l diff --git a/libarchive/libarchive-2.8.0/doc/man/mtree.5 b/libarchive/libarchive-2.8.0/doc/man/mtree.5 deleted file mode 100644 index 2cf2e3a..0000000 --- a/libarchive/libarchive-2.8.0/doc/man/mtree.5 +++ /dev/null @@ -1,282 +0,0 @@ -.TH MTREE 5 "August 20, 2007" "" -.SH NAME -.ad l -\fB\%mtree\fP -\- format of mtree dir hierarchy files -.SH DESCRIPTION -.ad l -The -\fB\%mtree\fP -format is a textual format that describes a collection of filesystem objects. -Such files are typically used to create or verify directory hierarchies. -.SS General Format -An -\fB\%mtree\fP -file consists of a series of lines, each providing information -about a single filesystem object. -Leading whitespace is always ignored. -.PP -When encoding file or pathnames, any backslash character or -character outside of the 95 printable ASCII characters must be -encoded as a a backslash followed by three -octal digits. -When reading mtree files, any appearance of a backslash -followed by three octal digits should be converted into the -corresponding character. -.PP -Each line is interpreted independently as one of the following types: -.RS 5 -.TP -Signature -The first line of any mtree file must begin with -``#mtree''. -If a file contains any full path entries, the first line should -begin with -``#mtree v2.0'', -otherwise, the first line should begin with -``#mtree v1.0''. -.TP -Blank -Blank lines are ignored. -.TP -Comment -Lines beginning with -\fB#\fP -are ignored. -.TP -Special -Lines beginning with -\fB/\fP -are special commands that influence -the interpretation of later lines. -.TP -Relative -If the first whitespace-delimited word has no -\fB/\fP -characters, -it is the name of a file in the current directory. -Any relative entry that describes a directory changes the -current directory. -.TP -dot-dot -As a special case, a relative entry with the filename -\fI\& ..\fP -changes the current directory to the parent directory. -Options on dot-dot entries are always ignored. -.TP -Full -If the first whitespace-delimited word has a -\fB/\fP -character after -the first character, it is the pathname of a file relative to the -starting directory. -There can be multiple full entries describing the same file. -.RE -.PP -Some tools that process -\fB\%mtree\fP -files may require that multiple lines describing the same file -occur consecutively. -It is not permitted for the same file to be mentioned using -both a relative and a full file specification. -.SS Special commands -Two special commands are currently defined: -.RS 5 -.TP -\fB/set\fP -This command defines default values for one or more keywords. -It is followed on the same line by one or more whitespace-separated -keyword definitions. -These definitions apply to all following files that do not specify -a value for that keyword. -.TP -\fB/unset\fP -This command removes any default value set by a previous -\fB/set\fP -command. -It is followed on the same line by one or more keywords -separated by whitespace. -.RE -.SS Keywords -After the filename, a full or relative entry consists of zero -or more whitespace-separated keyword definitions. -Each such definition consists of a key from the following -list immediately followed by an '=' sign -and a value. -Software programs reading mtree files should warn about -unrecognized keywords. -.PP -Currently supported keywords are as follows: -.RS 5 -.TP -\fBcksum\fP -The checksum of the file using the default algorithm specified by -the -\fBcksum\fP(1) -utility. -.TP -\fBcontents\fP -The full pathname of a file that holds the contents of this file. -.TP -\fBflags\fP -The file flags as a symbolic name. -See -\fBchflags\fP(1) -for information on these names. -If no flags are to be set the string -``none'' -may be used to override the current default. -.TP -\fBgid\fP -The file group as a numeric value. -.TP -\fBgname\fP -The file group as a symbolic name. -.TP -\fBignore\fP -Ignore any file hierarchy below this file. -.TP -\fBlink\fP -The target of the symbolic link when type=link. -.TP -\fBmd5\fP -The MD5 message digest of the file. -.TP -\fBmd5digest\fP -A synonym for -\fBmd5\fP. -.TP -\fBmode\fP -The current file's permissions as a numeric (octal) or symbolic -value. -.TP -\fBnlink\fP -The number of hard links the file is expected to have. -.TP -\fBnochange\fP -Make sure this file or directory exists but otherwise ignore all attributes. -.TP -\fBripemd160digest\fP -The -Tn RIPEMD160 -message digest of the file. -.TP -\fBrmd160\fP -A synonym for -\fBripemd160digest\fP. -.TP -\fBrmd160digest\fP -A synonym for -\fBripemd160digest\fP. -.TP -\fBsha1\fP -The -Tn FIPS -160-1 -(``Tn SHA-1'') -message digest of the file. -.TP -\fBsha1digest\fP -A synonym for -\fBsha1\fP. -.TP -\fBsha256\fP -The -Tn FIPS -180-2 -(``Tn SHA-256'') -message digest of the file. -.TP -\fBsha256digest\fP -A synonym for -\fBsha256\fP. -.TP -\fBsize\fP -The size, in bytes, of the file. -.TP -\fBtime\fP -The last modification time of the file. -.TP -\fBtype\fP -The type of the file; may be set to any one of the following: -.PP -.RS 5 -.TP -\fBblock\fP -block special device -.TP -\fBchar\fP -character special device -.TP -\fBdir\fP -directory -.TP -\fBfifo\fP -fifo -.TP -\fBfile\fP -regular file -.TP -\fBlink\fP -symbolic link -.TP -\fBsocket\fP -socket -.RE -.TP -\fBuid\fP -The file owner as a numeric value. -.TP -\fBuname\fP -The file owner as a symbolic name. -.RE -.PP -.SH SEE ALSO -.ad l -\fBcksum\fP(1), -\fBfind\fP(1), -\fBmtree\fP(8) -.SH BUGS -.ad l -The -FreeBSD -implementation of mtree does not currently support -the -\fB\%mtree\fP -2.0 -format. -The requirement for a -``#mtree'' -signature line is new and not yet widely implemented. -.SH HISTORY -.ad l -The -\fB\%mtree\fP -utility appeared in -Bx 4.3 Reno. -The -Tn MD5 -digest capability was added in -FreeBSD 2.1, -in response to the widespread use of programs which can spoof -\fBcksum\fP(1). -The -Tn SHA-1 -and -Tn RIPEMD160 -digests were added in -FreeBSD 4.0, -as new attacks have demonstrated weaknesses in -Tn MD5. -The -Tn SHA-256 -digest was added in -FreeBSD 6.0. -Support for file flags was added in -FreeBSD 4.0, -and mostly comes from -NetBSD. -The -``full'' -entry format was added by -NetBSD. diff --git a/libarchive/libarchive-2.8.0/doc/man/tar.5 b/libarchive/libarchive-2.8.0/doc/man/tar.5 deleted file mode 100644 index ab19958..0000000 --- a/libarchive/libarchive-2.8.0/doc/man/tar.5 +++ /dev/null @@ -1,869 +0,0 @@ -.TH tar 5 "December 27, 2009" "" -.SH NAME -.ad l -\fB\%tar\fP -\- format of tape archive files -.SH DESCRIPTION -.ad l -The -\fB\%tar\fP -archive format collects any number of files, directories, and other -file system objects (symbolic links, device nodes, etc.) into a single -stream of bytes. -The format was originally designed to be used with -tape drives that operate with fixed-size blocks, but is widely used as -a general packaging mechanism. -.SS General Format -A -\fB\%tar\fP -archive consists of a series of 512-byte records. -Each file system object requires a header record which stores basic metadata -(pathname, owner, permissions, etc.) and zero or more records containing any -file data. -The end of the archive is indicated by two records consisting -entirely of zero bytes. -.PP -For compatibility with tape drives that use fixed block sizes, -programs that read or write tar files always read or write a fixed -number of records with each I/O operation. -These -``blocks'' -are always a multiple of the record size. -The maximum block size supported by early -implementations was 10240 bytes or 20 records. -This is still the default for most implementations -although block sizes of 1MiB (2048 records) or larger are -commonly used with modern high-speed tape drives. -(Note: the terms -``block'' -and -``record'' -here are not entirely standard; this document follows the -convention established by John Gilmore in documenting -\fB\%pdtar\fP.) -.SS Old-Style Archive Format -The original tar archive format has been extended many times to -include additional information that various implementors found -necessary. -This section describes the variant implemented by the tar command -included in -At v7, -which seems to be the earliest widely-used version of the tar program. -.PP -The header record for an old-style -\fB\%tar\fP -archive consists of the following: -.RS 4 -.nf -struct header_old_tar { - char name[100]; - char mode[8]; - char uid[8]; - char gid[8]; - char size[12]; - char mtime[12]; - char checksum[8]; - char linkflag[1]; - char linkname[100]; - char pad[255]; -}; -.RE -All unused bytes in the header record are filled with nulls. -.RS 5 -.TP -\fIname\fP -Pathname, stored as a null-terminated string. -Early tar implementations only stored regular files (including -hardlinks to those files). -One common early convention used a trailing "/" character to indicate -a directory name, allowing directory permissions and owner information -to be archived and restored. -.TP -\fImode\fP -File mode, stored as an octal number in ASCII. -.TP -\fIuid\fP, \fIgid\fP -User id and group id of owner, as octal numbers in ASCII. -.TP -\fIsize\fP -Size of file, as octal number in ASCII. -For regular files only, this indicates the amount of data -that follows the header. -In particular, this field was ignored by early tar implementations -when extracting hardlinks. -Modern writers should always store a zero length for hardlink entries. -.TP -\fImtime\fP -Modification time of file, as an octal number in ASCII. -This indicates the number of seconds since the start of the epoch, -00:00:00 UTC January 1, 1970. -Note that negative values should be avoided -here, as they are handled inconsistently. -.TP -\fIchecksum\fP -Header checksum, stored as an octal number in ASCII. -To compute the checksum, set the checksum field to all spaces, -then sum all bytes in the header using unsigned arithmetic. -This field should be stored as six octal digits followed by a null and a space -character. -Note that many early implementations of tar used signed arithmetic -for the checksum field, which can cause interoperability problems -when transferring archives between systems. -Modern robust readers compute the checksum both ways and accept the -header if either computation matches. -.TP -\fIlinkflag\fP, \fIlinkname\fP -In order to preserve hardlinks and conserve tape, a file -with multiple links is only written to the archive the first -time it is encountered. -The next time it is encountered, the -\fIlinkflag\fP -is set to an ASCII -Sq 1 -and the -\fIlinkname\fP -field holds the first name under which this file appears. -(Note that regular files have a null value in the -\fIlinkflag\fP -field.) -.RE -.PP -Early tar implementations varied in how they terminated these fields. -The tar command in -At v7 -used the following conventions (this is also documented in early BSD manpages): -the pathname must be null-terminated; -the mode, uid, and gid fields must end in a space and a null byte; -the size and mtime fields must end in a space; -the checksum is terminated by a null and a space. -Early implementations filled the numeric fields with leading spaces. -This seems to have been common practice until the -IEEE Std 1003.1-1988 (``POSIX.1'') -standard was released. -For best portability, modern implementations should fill the numeric -fields with leading zeros. -.SS Pre-POSIX Archives -An early draft of -IEEE Std 1003.1-1988 (``POSIX.1'') -served as the basis for John Gilmore's -\fB\%pdtar\fP -program and many system implementations from the late 1980s -and early 1990s. -These archives generally follow the POSIX ustar -format described below with the following variations: -.RS 5 -.IP \(bu -The magic value is -``ustar\ \&'' -(note the following space). -The version field contains a space character followed by a null. -.IP \(bu -The numeric fields are generally filled with leading spaces -(not leading zeros as recommended in the final standard). -.IP \(bu -The prefix field is often not used, limiting pathnames to -the 100 characters of old-style archives. -.RE -.SS POSIX ustar Archives -IEEE Std 1003.1-1988 (``POSIX.1'') -defined a standard tar file format to be read and written -by compliant implementations of -\fBtar\fP(1). -This format is often called the -``ustar'' -format, after the magic value used -in the header. -(The name is an acronym for -``Unix Standard TAR''.) -It extends the historic format with new fields: -.RS 4 -.nf -struct header_posix_ustar { - char name[100]; - char mode[8]; - char uid[8]; - char gid[8]; - char size[12]; - char mtime[12]; - char checksum[8]; - char typeflag[1]; - char linkname[100]; - char magic[6]; - char version[2]; - char uname[32]; - char gname[32]; - char devmajor[8]; - char devminor[8]; - char prefix[155]; - char pad[12]; -}; -.RE -.RS 5 -.TP -\fItypeflag\fP -Type of entry. -POSIX extended the earlier -\fIlinkflag\fP -field with several new type values: -.RS 5 -.TP -``0'' -Regular file. -NUL should be treated as a synonym, for compatibility purposes. -.TP -``1'' -Hard link. -.TP -``2'' -Symbolic link. -.TP -``3'' -Character device node. -.TP -``4'' -Block device node. -.TP -``5'' -Directory. -.TP -``6'' -FIFO node. -.TP -``7'' -Reserved. -.TP -Other -A POSIX-compliant implementation must treat any unrecognized typeflag value -as a regular file. -In particular, writers should ensure that all entries -have a valid filename so that they can be restored by readers that do not -support the corresponding extension. -Uppercase letters "A" through "Z" are reserved for custom extensions. -Note that sockets and whiteout entries are not archivable. -.RE -It is worth noting that the -\fIsize\fP -field, in particular, has different meanings depending on the type. -For regular files, of course, it indicates the amount of data -following the header. -For directories, it may be used to indicate the total size of all -files in the directory, for use by operating systems that pre-allocate -directory space. -For all other types, it should be set to zero by writers and ignored -by readers. -.TP -\fImagic\fP -Contains the magic value -``ustar'' -followed by a NUL byte to indicate that this is a POSIX standard archive. -Full compliance requires the uname and gname fields be properly set. -.TP -\fIversion\fP -Version. -This should be -``00'' -(two copies of the ASCII digit zero) for POSIX standard archives. -.TP -\fIuname\fP, \fIgname\fP -User and group names, as null-terminated ASCII strings. -These should be used in preference to the uid/gid values -when they are set and the corresponding names exist on -the system. -.TP -\fIdevmajor\fP, \fIdevminor\fP -Major and minor numbers for character device or block device entry. -.TP -\fIname\fP, \fIprefix\fP -If the pathname is too long to fit in the 100 bytes provided by the standard -format, it can be split at any -\fI/\fP -character with the first portion going into the prefix field. -If the prefix field is not empty, the reader will prepend -the prefix value and a -\fI/\fP -character to the regular name field to obtain the full pathname. -The standard does not require a trailing -\fI/\fP -character on directory names, though most implementations still -include this for compatibility reasons. -.RE -.PP -Note that all unused bytes must be set to -.BR NUL. -.PP -Field termination is specified slightly differently by POSIX -than by previous implementations. -The -\fImagic\fP, -\fIuname\fP, -and -\fIgname\fP -fields must have a trailing -.BR NUL. -The -\fIpathname\fP, -\fIlinkname\fP, -and -\fIprefix\fP -fields must have a trailing -.BR NUL -unless they fill the entire field. -(In particular, it is possible to store a 256-character pathname if it -happens to have a -\fI/\fP -as the 156th character.) -POSIX requires numeric fields to be zero-padded in the front, and requires -them to be terminated with either space or -.BR NUL -characters. -.PP -Currently, most tar implementations comply with the ustar -format, occasionally extending it by adding new fields to the -blank area at the end of the header record. -.SS Pax Interchange Format -There are many attributes that cannot be portably stored in a -POSIX ustar archive. -IEEE Std 1003.1-2001 (``POSIX.1'') -defined a -``pax interchange format'' -that uses two new types of entries to hold text-formatted -metadata that applies to following entries. -Note that a pax interchange format archive is a ustar archive in every -respect. -The new data is stored in ustar-compatible archive entries that use the -``x'' -or -``g'' -typeflag. -In particular, older implementations that do not fully support these -extensions will extract the metadata into regular files, where the -metadata can be examined as necessary. -.PP -An entry in a pax interchange format archive consists of one or -two standard ustar entries, each with its own header and data. -The first optional entry stores the extended attributes -for the following entry. -This optional first entry has an "x" typeflag and a size field that -indicates the total size of the extended attributes. -The extended attributes themselves are stored as a series of text-format -lines encoded in the portable UTF-8 encoding. -Each line consists of a decimal number, a space, a key string, an equals -sign, a value string, and a new line. -The decimal number indicates the length of the entire line, including the -initial length field and the trailing newline. -An example of such a field is: -.RS 4 -25 ctime=1084839148.1212\en -.RE -Keys in all lowercase are standard keys. -Vendors can add their own keys by prefixing them with an all uppercase -vendor name and a period. -Note that, unlike the historic header, numeric values are stored using -decimal, not octal. -A description of some common keys follows: -.RS 5 -.TP -\fBatime\fP, \fBctime\fP, \fBmtime\fP -File access, inode change, and modification times. -These fields can be negative or include a decimal point and a fractional value. -.TP -\fBuname\fP, \fBuid\fP, \fBgname\fP, \fBgid\fP -User name, group name, and numeric UID and GID values. -The user name and group name stored here are encoded in UTF8 -and can thus include non-ASCII characters. -The UID and GID fields can be of arbitrary length. -.TP -\fBlinkpath\fP -The full path of the linked-to file. -Note that this is encoded in UTF8 and can thus include non-ASCII characters. -.TP -\fBpath\fP -The full pathname of the entry. -Note that this is encoded in UTF8 and can thus include non-ASCII characters. -.TP -\fBrealtime.*\fP, \fBsecurity.*\fP -These keys are reserved and may be used for future standardization. -.TP -\fBsize\fP -The size of the file. -Note that there is no length limit on this field, allowing conforming -archives to store files much larger than the historic 8GB limit. -.TP -\fBSCHILY.*\fP -Vendor-specific attributes used by Joerg Schilling's -\fB\%star\fP -implementation. -.TP -\fBSCHILY.acl.access\fP, \fBSCHILY.acl.default\fP -Stores the access and default ACLs as textual strings in a format -that is an extension of the format specified by POSIX.1e draft 17. -In particular, each user or group access specification can include a fourth -colon-separated field with the numeric UID or GID. -This allows ACLs to be restored on systems that may not have complete -user or group information available (such as when NIS/YP or LDAP services -are temporarily unavailable). -.TP -\fBSCHILY.devminor\fP, \fBSCHILY.devmajor\fP -The full minor and major numbers for device nodes. -.TP -\fBSCHILY.fflags\fP -The file flags. -.TP -\fBSCHILY.realsize\fP -The full size of the file on disk. -XXX explain? XXX -.TP -\fBSCHILY.dev,\fP \fBSCHILY.ino\fP, \fBSCHILY.nlinks\fP -The device number, inode number, and link count for the entry. -In particular, note that a pax interchange format archive using Joerg -Schilling's -\fBSCHILY.*\fP -extensions can store all of the data from -\fIstruct\fP stat. -.TP -\fBLIBARCHIVE.xattr.\fP \fInamespace\fP.\fIkey\fP -Libarchive stores POSIX.1e-style extended attributes using -keys of this form. -The -\fIkey\fP -value is URL-encoded: -All non-ASCII characters and the two special characters -``='' -and -``%'' -are encoded as -``%'' -followed by two uppercase hexadecimal digits. -The value of this key is the extended attribute value -encoded in base 64. -XXX Detail the base-64 format here XXX -.TP -\fBVENDOR.*\fP -XXX document other vendor-specific extensions XXX -.RE -.PP -Any values stored in an extended attribute override the corresponding -values in the regular tar header. -Note that compliant readers should ignore the regular fields when they -are overridden. -This is important, as existing archivers are known to store non-compliant -values in the standard header fields in this situation. -There are no limits on length for any of these fields. -In particular, numeric fields can be arbitrarily large. -All text fields are encoded in UTF8. -Compliant writers should store only portable 7-bit ASCII characters in -the standard ustar header and use extended -attributes whenever a text value contains non-ASCII characters. -.PP -In addition to the -\fBx\fP -entry described above, the pax interchange format -also supports a -\fBg\fP -entry. -The -\fBg\fP -entry is identical in format, but specifies attributes that serve as -defaults for all subsequent archive entries. -The -\fBg\fP -entry is not widely used. -.PP -Besides the new -\fBx\fP -and -\fBg\fP -entries, the pax interchange format has a few other minor variations -from the earlier ustar format. -The most troubling one is that hardlinks are permitted to have -data following them. -This allows readers to restore any hardlink to a file without -having to rewind the archive to find an earlier entry. -However, it creates complications for robust readers, as it is no longer -clear whether or not they should ignore the size field for hardlink entries. -.SS GNU Tar Archives -The GNU tar program started with a pre-POSIX format similar to that -described earlier and has extended it using several different mechanisms: -It added new fields to the empty space in the header (some of which was later -used by POSIX for conflicting purposes); -it allowed the header to be continued over multiple records; -and it defined new entries that modify following entries -(similar in principle to the -\fBx\fP -entry described above, but each GNU special entry is single-purpose, -unlike the general-purpose -\fBx\fP -entry). -As a result, GNU tar archives are not POSIX compatible, although -more lenient POSIX-compliant readers can successfully extract most -GNU tar archives. -.RS 4 -.nf -struct header_gnu_tar { - char name[100]; - char mode[8]; - char uid[8]; - char gid[8]; - char size[12]; - char mtime[12]; - char checksum[8]; - char typeflag[1]; - char linkname[100]; - char magic[6]; - char version[2]; - char uname[32]; - char gname[32]; - char devmajor[8]; - char devminor[8]; - char atime[12]; - char ctime[12]; - char offset[12]; - char longnames[4]; - char unused[1]; - struct { - char offset[12]; - char numbytes[12]; - } sparse[4]; - char isextended[1]; - char realsize[12]; - char pad[17]; -}; -.RE -.RS 5 -.TP -\fItypeflag\fP -GNU tar uses the following special entry types, in addition to -those defined by POSIX: -.RS 5 -.TP -7 -GNU tar treats type "7" records identically to type "0" records, -except on one obscure RTOS where they are used to indicate the -pre-allocation of a contiguous file on disk. -.TP -D -This indicates a directory entry. -Unlike the POSIX-standard "5" -typeflag, the header is followed by data records listing the names -of files in this directory. -Each name is preceded by an ASCII "Y" -if the file is stored in this archive or "N" if the file is not -stored in this archive. -Each name is terminated with a null, and -an extra null marks the end of the name list. -The purpose of this -entry is to support incremental backups; a program restoring from -such an archive may wish to delete files on disk that did not exist -in the directory when the archive was made. -.PP -Note that the "D" typeflag specifically violates POSIX, which requires -that unrecognized typeflags be restored as normal files. -In this case, restoring the "D" entry as a file could interfere -with subsequent creation of the like-named directory. -.TP -K -The data for this entry is a long linkname for the following regular entry. -.TP -L -The data for this entry is a long pathname for the following regular entry. -.TP -M -This is a continuation of the last file on the previous volume. -GNU multi-volume archives guarantee that each volume begins with a valid -entry header. -To ensure this, a file may be split, with part stored at the end of one volume, -and part stored at the beginning of the next volume. -The "M" typeflag indicates that this entry continues an existing file. -Such entries can only occur as the first or second entry -in an archive (the latter only if the first entry is a volume label). -The -\fIsize\fP -field specifies the size of this entry. -The -\fIoffset\fP -field at bytes 369-380 specifies the offset where this file fragment -begins. -The -\fIrealsize\fP -field specifies the total size of the file (which must equal -\fIsize\fP -plus -\fIoffset\fP). -When extracting, GNU tar checks that the header file name is the one it is -expecting, that the header offset is in the correct sequence, and that -the sum of offset and size is equal to realsize. -.TP -N -Type "N" records are no longer generated by GNU tar. -They contained a -list of files to be renamed or symlinked after extraction; this was -originally used to support long names. -The contents of this record -are a text description of the operations to be done, in the form -``Rename %s to %s\en'' -or -``Symlink %s to %s\en ;'' -in either case, both -filenames are escaped using K&R C syntax. -Due to security concerns, "N" records are now generally ignored -when reading archives. -.TP -S -This is a -``sparse'' -regular file. -Sparse files are stored as a series of fragments. -The header contains a list of fragment offset/length pairs. -If more than four such entries are required, the header is -extended as necessary with -``extra'' -header extensions (an older format that is no longer used), or -``sparse'' -extensions. -.TP -V -The -\fIname\fP -field should be interpreted as a tape/volume header name. -This entry should generally be ignored on extraction. -.RE -.TP -\fImagic\fP -The magic field holds the five characters -``ustar'' -followed by a space. -Note that POSIX ustar archives have a trailing null. -.TP -\fIversion\fP -The version field holds a space character followed by a null. -Note that POSIX ustar archives use two copies of the ASCII digit -``0''. -.TP -\fIatime\fP, \fIctime\fP -The time the file was last accessed and the time of -last change of file information, stored in octal as with -\fImtime\fP. -.TP -\fIlongnames\fP -This field is apparently no longer used. -.TP -Sparse \fIoffset\fP / \fInumbytes\fP -Each such structure specifies a single fragment of a sparse -file. -The two fields store values as octal numbers. -The fragments are each padded to a multiple of 512 bytes -in the archive. -On extraction, the list of fragments is collected from the -header (including any extension headers), and the data -is then read and written to the file at appropriate offsets. -.TP -\fIisextended\fP -If this is set to non-zero, the header will be followed by additional -``sparse header'' -records. -Each such record contains information about as many as 21 additional -sparse blocks as shown here: -.RS 4 -.nf -struct gnu_sparse_header { - struct { - char offset[12]; - char numbytes[12]; - } sparse[21]; - char isextended[1]; - char padding[7]; -}; -.RE -.TP -\fIrealsize\fP -A binary representation of the file's complete size, with a much larger range -than the POSIX file size. -In particular, with -\fBM\fP -type files, the current entry is only a portion of the file. -In that case, the POSIX size field will indicate the size of this -entry; the -\fIrealsize\fP -field will indicate the total size of the file. -.RE -.SS GNU tar pax archives -GNU tar 1.14 (XXX check this XXX) and later will write -pax interchange format archives when you specify the -\fB\--posix\fP -flag. -This format uses custom keywords to store sparse file information. -There have been three iterations of this support, referred to -as -``0.0'', -``0.1'', -and -``1.0''. -.RS 5 -.TP -\fBGNU.sparse.numblocks\fP, \fBGNU.sparse.offset\fP, \fBGNU.sparse.numbytes\fP, \fBGNU.sparse.size\fP -The -``0.0'' -format used an initial -\fBGNU.sparse.numblocks\fP -attribute to indicate the number of blocks in the file, a pair of -\fBGNU.sparse.offset\fP -and -\fBGNU.sparse.numbytes\fP -to indicate the offset and size of each block, -and a single -\fBGNU.sparse.size\fP -to indicate the full size of the file. -This is not the same as the size in the tar header because the -latter value does not include the size of any holes. -This format required that the order of attributes be preserved and -relied on readers accepting multiple appearances of the same attribute -names, which is not officially permitted by the standards. -.TP -\fBGNU.sparse.map\fP -The -``0.1'' -format used a single attribute that stored a comma-separated -list of decimal numbers. -Each pair of numbers indicated the offset and size, respectively, -of a block of data. -This does not work well if the archive is extracted by an archiver -that does not recognize this extension, since many pax implementations -simply discard unrecognized attributes. -.TP -\fBGNU.sparse.major\fP, \fBGNU.sparse.minor\fP, \fBGNU.sparse.name\fP, \fBGNU.sparse.realsize\fP -The -``1.0'' -format stores the sparse block map in one or more 512-byte blocks -prepended to the file data in the entry body. -The pax attributes indicate the existence of this map -(via the -\fBGNU.sparse.major\fP -and -\fBGNU.sparse.minor\fP -fields) -and the full size of the file. -The -\fBGNU.sparse.name\fP -holds the true name of the file. -To avoid confusion, the name stored in the regular tar header -is a modified name so that extraction errors will be apparent -to users. -.RE -.SS Solaris Tar -XXX More Details Needed XXX -.PP -Solaris tar (beginning with SunOS XXX 5.7 ?? XXX) supports an -``extended'' -format that is fundamentally similar to pax interchange format, -with the following differences: -.RS 5 -.IP \(bu -Extended attributes are stored in an entry whose type is -\fBX\fP, -not -\fBx\fP, -as used by pax interchange format. -The detailed format of this entry appears to be the same -as detailed above for the -\fBx\fP -entry. -.IP \(bu -An additional -\fBA\fP -entry is used to store an ACL for the following regular entry. -The body of this entry contains a seven-digit octal number -followed by a zero byte, followed by the -textual ACL description. -The octal value is the number of ACL entries -plus a constant that indicates the ACL type: 01000000 -for POSIX.1e ACLs and 03000000 for NFSv4 ACLs. -.RE -.SS AIX Tar -XXX More details needed XXX -.SS Mac OS X Tar -The tar distributed with Apple's Mac OS X stores most regular files -as two separate entries in the tar archive. -The two entries have the same name except that the first -one has -``._'' -added to the beginning of the name. -This first entry stores the -``resource fork'' -with additional attributes for the file. -The Mac OS X -\fB\%CopyFile\fP() -API is used to separate a file on disk into separate -resource and data streams and to reassemble those separate -streams when the file is restored to disk. -.SS Other Extensions -One obvious extension to increase the size of files is to -eliminate the terminating characters from the various -numeric fields. -For example, the standard only allows the size field to contain -11 octal digits, reserving the twelfth byte for a trailing -NUL character. -Allowing 12 octal digits allows file sizes up to 64 GB. -.PP -Another extension, utilized by GNU tar, star, and other newer -\fB\%tar\fP -implementations, permits binary numbers in the standard numeric fields. -This is flagged by setting the high bit of the first byte. -This permits 95-bit values for the length and time fields -and 63-bit values for the uid, gid, and device numbers. -GNU tar supports this extension for the -length, mtime, ctime, and atime fields. -Joerg Schilling's star program supports this extension for -all numeric fields. -Note that this extension is largely obsoleted by the extended attribute -record provided by the pax interchange format. -.PP -Another early GNU extension allowed base-64 values rather than octal. -This extension was short-lived and is no longer supported by any -implementation. -.SH SEE ALSO -.ad l -\fBar\fP(1), -\fBpax\fP(1), -\fBtar\fP(1) -.SH STANDARDS -.ad l -The -\fB\%tar\fP -utility is no longer a part of POSIX or the Single Unix Standard. -It last appeared in -Version 2 of the Single UNIX Specification (``SUSv2''). -It has been supplanted in subsequent standards by -\fBpax\fP(1). -The ustar format is currently part of the specification for the -\fBpax\fP(1) -utility. -The pax interchange file format is new with -IEEE Std 1003.1-2001 (``POSIX.1''). -.SH HISTORY -.ad l -A -\fB\%tar\fP -command appeared in Seventh Edition Unix, which was released in January, 1979. -It replaced the -\fB\%tp\fP -program from Fourth Edition Unix which in turn replaced the -\fB\%tap\fP -program from First Edition Unix. -John Gilmore's -\fB\%pdtar\fP -public-domain implementation (circa 1987) was highly influential -and formed the basis of -\fB\%GNU\fP tar -(circa 1988). -Joerg Shilling's -\fB\%star\fP -archiver is another open-source (GPL) archiver (originally developed -circa 1985) which features complete support for pax interchange -format. -.PP -This documentation was written as part of the -\fB\%libarchive\fP -and -\fB\%bsdtar\fP -project by -Tim Kientzle \%<kientzle@FreeBSD.org.> diff --git a/libarchive/libarchive-2.8.0/doc/mdoc2man.awk b/libarchive/libarchive-2.8.0/doc/mdoc2man.awk deleted file mode 100644 index c55b953..0000000 --- a/libarchive/libarchive-2.8.0/doc/mdoc2man.awk +++ /dev/null @@ -1,391 +0,0 @@ -#!/usr/bin/awk -# -# Copyright (c) 2003 Peter Stuge <stuge-mdoc2man@cdy.org> -# -# 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 4") -} - -# End an indented display -function dispend() { - linecmd(".RE") -} - -# Collect rest of input line -function wtail() { - retval="" - while(w<nwords) { - if(length(retval)) - retval=retval " " - retval=retval words[++w] - } - return retval -} - -function splitwords(l, dest, n, o, w) { - n = 1 - delete dest - while (length(l) > 0) { - sub("^[ \t]*", "", l) - if (match(l, "^\"")) { - l = substr(l, 2) - o = index(l, "\"") - if (o > 0) { - w = substr(l, 1, o-1) - l = substr(l, o+1) - dest[n++] = w - } else { - dest[n++] = l - l = "" - } - } else { - o = match(l, "[ \t]") - if (o > 0) { - w = substr(l, 1, o-1) - l = substr(l, o+1) - dest[n++] = w - } else { - dest[n++] = l - l = "" - } - } - } - return n-1 -} - -! /^\./ { - out = $0 - endline() - next -} - -/^\.\\"/ { next } - -{ - sub("^\\.","") - nwords=splitwords($0, words) - # TODO: Instead of iterating 'w' over the array, have a separate - # function that returns 'next word' and use that. This will allow - # proper handling of double-quoted arguments as well. - for(w=1;w<=nwords;w++) { - if(match(words[w],"^Li$")) { # Literal; rest of line is unformatted - dispstart() - displaylines = 1 - } else if(match(words[w],"^Dl$")) { # Display literal - dispstart() - displaylines = 1 - } else if(match(words[w],"^Bd$")) { # Begin display - if(match(words[w+1],"-literal")) { - dispstart() - linecmd(".nf") - displaylines=10000 - w=nwords - } - } else if(match(words[w],"^Ed$")) { # End display - displaylines = 0 - dispend() - } else if(match(words[w],"^Ns$")) { # Suppress space after next word - nextsep = "" - } else if(match(words[w],"^No$")) { # Normal text - add(words[++w]) - } else if(match(words[w],"^Dq$")) { # Quote - addopen("``") - add(words[++w]) - while(w<nwords&&!match(words[w+1],"^[\\.,]")) - add(words[++w]) - addclose("''") - } else if(match(words[w],"^Do$")) { - addopen("``") - } else if(match(words[w],"^Dc$")) { - addclose("''") - } else if(match(words[w],"^Oo$")) { - addopen("[") - } else if(match(words[w],"^Oc$")) { - addclose("]") - } else if(match(words[w],"^Ao$")) { - addopen("<") - } else if(match(words[w],"^Ac$")) { - addclose(">") - } 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$")) { - section=wtail() - add(".SH " section) - linecmd(".ad l") - } 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 >= nwords) - n=name - else if (match(words[w+1], "^[A-Z][a-z]$")) - n=name - else if (match(words[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") - } 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$")) { - linecmd(".PP") - } else if(match(words[w],"^An$")) { - endline() - } else if(match(words[w],"^Ss$")) { - add(".SS") - } else if(match(words[w],"^Ft$")) { - if (match(section, "SYNOPSIS")) { - breakline() - } - add("\\fI" wtail() "\\fP") - if (match(section, "SYNOPSIS")) { - breakline() - } - } else if(match(words[w],"^Fn$")) { - ++w - F = "\\fB\\%" words[w] "\\fP(" - Fsep = "" - while(w<nwords) { - ++w - if (match(words[w], "^[.,:]$")) { - --w - break - } - gsub(" ", "\\ ", words[w]) - F = F Fsep "\\fI\\%" words[w] "\\fP" - Fsep = ", " - } - add(F ")") - if (match(section, "SYNOPSIS")) { - addclose(";") - } - } else if(match(words[w],"^Fo$")) { - w++ - F = "\\fB\\%" words[w] "\\fP(" - Fsep = "" - } else if(match(words[w],"^Fa$")) { - w++ - gsub(" ", "\\ ", words[w]) - F = F Fsep "\\fI\\%" words[w] "\\fP" - Fsep = ", " - } else if(match(words[w],"^Fc$")) { - add(F ")") - if (match(section, "SYNOPSIS")) { - addclose(";") - } - } 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") - } 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 - linecmd(".RS 5") - 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$")) { - linecmd(".RE") - 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],"^Xo$")) { - # TODO: Figure out how to handle this - } else if(match(words[w],"^Xc$")) { - # TODO: Figure out how to handle this - } 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.8.0/doc/mdoc2wiki.awk b/libarchive/libarchive-2.8.0/doc/mdoc2wiki.awk deleted file mode 100644 index 146d961..0000000 --- a/libarchive/libarchive-2.8.0/doc/mdoc2wiki.awk +++ /dev/null @@ -1,448 +0,0 @@ -#!/usr/bin/awk -# -# Copyright (c) 2003 Peter Stuge <stuge-mdoc2man@cdy.org> -# -# 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 - listdepth = 0 - trailer = "" - out = "" - sep = "" - nextsep = " " - spaces = " " -} - -# 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("{{{") -} - -# End an indented display -function dispend() { - linecmd("}}}") -} - -# Collect rest of input line -function wtail() { - retval="" - while(w<nwords) { - if(length(retval)) - retval=retval " " - retval=retval words[++w] - } - return retval -} - -function splitwords(l, dest, n, o, w) { - n = 1 - delete dest - while (length(l) > 0) { - sub("^[ \t]*", "", l) - if (match(l, "^\"")) { - l = substr(l, 2) - o = index(l, "\"") - if (o > 0) { - w = substr(l, 1, o-1) - l = substr(l, o+1) - dest[n++] = w - } else { - dest[n++] = l - l = "" - } - } else { - o = match(l, "[ \t]") - if (o > 0) { - w = substr(l, 1, o-1) - l = substr(l, o+1) - dest[n++] = w - } else { - dest[n++] = l - l = "" - } - } - } - return n-1 -} - -! /^\./ { - out = $0 - endline() - next -} - -/^\.\\"/ { next } - -{ - sub("^\\.","") - nwords=splitwords($0, words) - # TODO: Instead of iterating 'w' over the array, have a separate - # function that returns 'next word' and use that. This will allow - # proper handling of double-quoted arguments as well. - for(w=1;w<=nwords;w++) { - if(match(words[w],"^Li$")) { # Literal; rest of line is unformatted - dispstart() - displaylines = 1 - } else if(match(words[w],"^Dl$")) { # Display literal - dispstart() - displaylines = 1 - } else if(match(words[w],"^Bd$")) { # Begin display - if(match(words[w+1],"-literal")) { - dispstart() - displaylines=10000 - w=nwords - } - } else if(match(words[w],"^Ed$")) { # End display - displaylines = 0 - dispend() - } else if(match(words[w],"^Ns$")) { # Suppress space before next word - sep="" - } else if(match(words[w],"^No$")) { # Normal text - add(words[++w]) - } else if(match(words[w],"^Dq$")) { # Quote - addopen("\"") - add(words[++w]) - while(w<nwords&&!match(words[w+1],"^[\\.,]")) - add(words[++w]) - addclose("\"") - } else if(match(words[w],"^Do$")) { - addopen("\"") - } else if(match(words[w],"^Dc$")) { - addclose("\"") - } else if(match(words[w],"^Oo$")) { - addopen("`[`") - } else if(match(words[w],"^Oc$")) { - addclose("`]`") - } else if(match(words[w],"^Ao$")) { - addopen("`<`") - } else if(match(words[w],"^Ac$")) { - addclose("`>`") - } 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],"^Bx$")) { - add("BSD") - } 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 *" name "* utility exits 0 on success, and >0 if an error occurs.") - } - } else if(match(words[w],"^Os$")) { - add("#summary " id " manual page") - } else if(match(words[w],"^Sh$")) { - section=wtail() - linecmd("== " section " ==") - } else if(match(words[w],"^Xr$")) { - add("*" words[++w] "*(" words[++w] ")" words[++w]) - } else if(match(words[w],"^Nm$")) { - if(match(section,"SYNOPSIS")) - breakline() - if(w >= nwords) - n=name - else if (match(words[w+1], "^[A-Z][a-z]$")) - n=name - else if (match(words[w+1], "^[.,;:]$")) - n=name - else { - n=words[++w] - if(!length(name)) - name=n - } - if(!length(n)) - n=name - if (displaylines == 0) - add("*" n "*") - else - add(n) - } else if(match(words[w],"^Nd$")) { - add("- " wtail()) - } else if(match(words[w],"^Fl$")) { - if (displaylines == 0) - add("*-" words[++w] "*") - else - add("-" words[++w]) - } else if(match(words[w],"^Ar$")) { - if(w==nwords) - add("_file ..._") - else { - ++w - gsub("<", "`<`", words[w]) - add("_" words[w] "_") - } - } else if(match(words[w],"^Cm$")) { - ++w - if (displaylines == 0) { - gsub("^_", "`_`", words[w]) - gsub("\\*$", "`*`", words[w]) - add("*" words[w] "*") - } else - add(words[w]) - } else if(match(words[w],"^Op$")) { - addopen("`[`") - option=1 - trailer="`]`" trailer - } else if(match(words[w],"^Pp$")) { - ++w - endline() - print "" - } else if(match(words[w],"^An$")) { - if (match(words[w+1],"-nosplit")) - ++w - endline() - } else if(match(words[w],"^Ss$")) { - add("===") - trailer="===" - } else if(match(words[w],"^Ft$")) { - if (match(section, "SYNOPSIS")) { - breakline() - } - l = wtail() - gsub("\\*", "`*`", l) - - add("*" l "*") - if (match(section, "SYNOPSIS")) { - breakline() - } - } else if(match(words[w],"^Fn$")) { - ++w - F = "*" words[w] "*(" - Fsep = "" - while(w<nwords) { - ++w - if (match(words[w], "^[.,:]$")) { - --w - break - } - gsub("\\*", "`*`", words[w]) - F = F Fsep "_" words[w] "_" - Fsep = ", " - } - add(F ")") - if (match(section, "SYNOPSIS")) { - addclose(";") - } - } else if(match(words[w],"^Fo$")) { - w++ - F = "*" words[w] "*(" - Fsep = "" - } else if(match(words[w],"^Fa$")) { - w++ - gsub("\\*", "`*`", words[w]) - F = F Fsep "_" words[w] "_" - Fsep = ", " - } else if(match(words[w],"^Fc$")) { - add(F ")") - if (match(section, "SYNOPSIS")) { - addclose(";") - } - } else if(match(words[w],"^Va$")) { - w++ - add("_" words[w] "_") - } else if(match(words[w],"^In$")) { - w++ - add("*#include <" words[w] ">*") - } else if(match(words[w],"^Pa$")) { - w++ -# if(match(words[w],"^\\.")) -# add("\\&") - if (displaylines == 0) - add("_" words[w] "_") - else - add(words[w]) - } else if(match(words[w],"^Dv$")) { - linecmd() - } 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],"^Tn$")) { - n=wtail() - gsub("\\*$", "`*`", n) - add("*" n "*") - } else if(match(words[w],"^Ic$")) { - add("\\fB") - trailer="\\fP" trailer - } else if(match(words[w],"^Bl$")) { - ++listdepth - listnext[listdepth]="" - if(match(words[w+1],"-bullet")) { - optlist[listdepth]=1 - addopen("<ul>") - listclose[listdepth]="</ul>" - } else if(match(words[w+1],"-enum")) { - optlist[listdepth]=2 - enum=0 - addopen("<ol>") - listclose[listdepth]="</ol>" - } else if(match(words[w+1],"-tag")) { - optlist[listdepth]=3 - addopen("<dl>") - listclose[listdepth]="</dl>" - } else if(match(words[w+1],"-item")) { - optlist[listdepth]=4 - addopen("<ul>") - listclose[listdepth]="</ul>" - } - w=nwords - } else if(match(words[w],"^El$")) { - addclose(listnext[listdepth]) - addclose(listclose[listdepth]) - listclose[listdepth]="" - listdepth-- - } else if(match(words[w],"^It$")) { - addclose(listnext[listdepth]) - if(optlist[listdepth]==1) { - addpunct("<li>") - listnext[listdepth] = "</li>" - } else if(optlist[listdepth]==2) { - addpunct("<li>") - listnext[listdepth] = "</li>" - } else if(optlist[listdepth]==3) { - addpunct("<dt>") - listnext[listdepth] = "</dt>" - if(match(words[w+1],"^Xo$")) { - # Suppress trailer - w++ - } else if(match(words[w+1],"^Pa$|^Ev$")) { - addopen("*") - w++ - add(words[++w] "*") - } else { - trailer = listnext[listdepth] "<dd>" trailer - listnext[listdepth] = "</dd>" - } - } else if(optlist[listdepth]==4) { - addpunct("<li>") - listnext[listdepth] = "</li>" - } - } else if(match(words[w],"^Xo$")) { - # TODO: Figure out how to handle this - } else if(match(words[w],"^Xc$")) { - # TODO: Figure out how to handle this - if (optlist[listdepth] == 3) { - addclose(listnext[listdepth]) - addopen("<dd>") - listnext[listdepth] = "</dd>" - } - } 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 { - sub("\\\\&", "", words[w]) - add(words[w]) - } - } - if(match(out,"^\\.[^a-zA-Z]")) - sub("^\\.","",out) - endline() -} diff --git a/libarchive/libarchive-2.8.0/doc/pdf/Makefile b/libarchive/libarchive-2.8.0/doc/pdf/Makefile deleted file mode 100644 index a563105..0000000 --- a/libarchive/libarchive-2.8.0/doc/pdf/Makefile +++ /dev/null @@ -1,46 +0,0 @@ - -default: all - - -archive_entry.3.pdf: ../../libarchive/archive_entry.3 - groff -mdoc -T ps ../../libarchive/archive_entry.3 | ps2pdf - - > archive_entry.3.pdf - -archive_read.3.pdf: ../../libarchive/archive_read.3 - groff -mdoc -T ps ../../libarchive/archive_read.3 | ps2pdf - - > archive_read.3.pdf - -archive_read_disk.3.pdf: ../../libarchive/archive_read_disk.3 - groff -mdoc -T ps ../../libarchive/archive_read_disk.3 | ps2pdf - - > archive_read_disk.3.pdf - -archive_util.3.pdf: ../../libarchive/archive_util.3 - groff -mdoc -T ps ../../libarchive/archive_util.3 | ps2pdf - - > archive_util.3.pdf - -archive_write.3.pdf: ../../libarchive/archive_write.3 - groff -mdoc -T ps ../../libarchive/archive_write.3 | ps2pdf - - > archive_write.3.pdf - -archive_write_disk.3.pdf: ../../libarchive/archive_write_disk.3 - groff -mdoc -T ps ../../libarchive/archive_write_disk.3 | ps2pdf - - > archive_write_disk.3.pdf - -cpio.5.pdf: ../../libarchive/cpio.5 - groff -mdoc -T ps ../../libarchive/cpio.5 | ps2pdf - - > cpio.5.pdf - -libarchive-formats.5.pdf: ../../libarchive/libarchive-formats.5 - groff -mdoc -T ps ../../libarchive/libarchive-formats.5 | ps2pdf - - > libarchive-formats.5.pdf - -libarchive.3.pdf: ../../libarchive/libarchive.3 - groff -mdoc -T ps ../../libarchive/libarchive.3 | ps2pdf - - > libarchive.3.pdf - -libarchive_internals.3.pdf: ../../libarchive/libarchive_internals.3 - groff -mdoc -T ps ../../libarchive/libarchive_internals.3 | ps2pdf - - > libarchive_internals.3.pdf - -mtree.5.pdf: ../../libarchive/mtree.5 - groff -mdoc -T ps ../../libarchive/mtree.5 | ps2pdf - - > mtree.5.pdf - -tar.5.pdf: ../../libarchive/tar.5 - groff -mdoc -T ps ../../libarchive/tar.5 | ps2pdf - - > tar.5.pdf - -bsdtar.1.pdf: ../../tar/bsdtar.1 - groff -mdoc -T ps ../../tar/bsdtar.1 | ps2pdf - - > bsdtar.1.pdf - -bsdcpio.1.pdf: ../../cpio/bsdcpio.1 - groff -mdoc -T ps ../../cpio/bsdcpio.1 | ps2pdf - - > bsdcpio.1.pdf -all: archive_entry.3.pdf archive_read.3.pdf archive_read_disk.3.pdf archive_util.3.pdf archive_write.3.pdf archive_write_disk.3.pdf cpio.5.pdf libarchive-formats.5.pdf libarchive.3.pdf libarchive_internals.3.pdf mtree.5.pdf tar.5.pdf bsdtar.1.pdf bsdcpio.1.pdf diff --git a/libarchive/libarchive-2.8.0/doc/pdf/archive_entry.3.pdf b/libarchive/libarchive-2.8.0/doc/pdf/archive_entry.3.pdf Binary files differdeleted file mode 100644 index 658d0ad..0000000 --- a/libarchive/libarchive-2.8.0/doc/pdf/archive_entry.3.pdf +++ /dev/null diff --git a/libarchive/libarchive-2.8.0/doc/pdf/archive_read.3.pdf b/libarchive/libarchive-2.8.0/doc/pdf/archive_read.3.pdf Binary files differdeleted file mode 100644 index 12581db..0000000 --- a/libarchive/libarchive-2.8.0/doc/pdf/archive_read.3.pdf +++ /dev/null diff --git a/libarchive/libarchive-2.8.0/doc/pdf/archive_read_disk.3.pdf b/libarchive/libarchive-2.8.0/doc/pdf/archive_read_disk.3.pdf Binary files differdeleted file mode 100644 index 0f21d06..0000000 --- a/libarchive/libarchive-2.8.0/doc/pdf/archive_read_disk.3.pdf +++ /dev/null diff --git a/libarchive/libarchive-2.8.0/doc/pdf/archive_util.3.pdf b/libarchive/libarchive-2.8.0/doc/pdf/archive_util.3.pdf Binary files differdeleted file mode 100644 index a7ff8ed..0000000 --- a/libarchive/libarchive-2.8.0/doc/pdf/archive_util.3.pdf +++ /dev/null diff --git a/libarchive/libarchive-2.8.0/doc/pdf/archive_write.3.pdf b/libarchive/libarchive-2.8.0/doc/pdf/archive_write.3.pdf Binary files differdeleted file mode 100644 index 4e0069a..0000000 --- a/libarchive/libarchive-2.8.0/doc/pdf/archive_write.3.pdf +++ /dev/null diff --git a/libarchive/libarchive-2.8.0/doc/pdf/archive_write_disk.3.pdf b/libarchive/libarchive-2.8.0/doc/pdf/archive_write_disk.3.pdf Binary files differdeleted file mode 100644 index ed8f673..0000000 --- a/libarchive/libarchive-2.8.0/doc/pdf/archive_write_disk.3.pdf +++ /dev/null diff --git a/libarchive/libarchive-2.8.0/doc/pdf/bsdcpio.1.pdf b/libarchive/libarchive-2.8.0/doc/pdf/bsdcpio.1.pdf Binary files differdeleted file mode 100644 index 771e5c6..0000000 --- a/libarchive/libarchive-2.8.0/doc/pdf/bsdcpio.1.pdf +++ /dev/null diff --git a/libarchive/libarchive-2.8.0/doc/pdf/bsdtar.1.pdf b/libarchive/libarchive-2.8.0/doc/pdf/bsdtar.1.pdf Binary files differdeleted file mode 100644 index 0ebd4f2..0000000 --- a/libarchive/libarchive-2.8.0/doc/pdf/bsdtar.1.pdf +++ /dev/null diff --git a/libarchive/libarchive-2.8.0/doc/pdf/cpio.5.pdf b/libarchive/libarchive-2.8.0/doc/pdf/cpio.5.pdf Binary files differdeleted file mode 100644 index 8bd1276..0000000 --- a/libarchive/libarchive-2.8.0/doc/pdf/cpio.5.pdf +++ /dev/null diff --git a/libarchive/libarchive-2.8.0/doc/pdf/libarchive-formats.5.pdf b/libarchive/libarchive-2.8.0/doc/pdf/libarchive-formats.5.pdf Binary files differdeleted file mode 100644 index db03ba1..0000000 --- a/libarchive/libarchive-2.8.0/doc/pdf/libarchive-formats.5.pdf +++ /dev/null diff --git a/libarchive/libarchive-2.8.0/doc/pdf/libarchive.3.pdf b/libarchive/libarchive-2.8.0/doc/pdf/libarchive.3.pdf Binary files differdeleted file mode 100644 index 25e2b0c..0000000 --- a/libarchive/libarchive-2.8.0/doc/pdf/libarchive.3.pdf +++ /dev/null diff --git a/libarchive/libarchive-2.8.0/doc/pdf/libarchive_internals.3.pdf b/libarchive/libarchive-2.8.0/doc/pdf/libarchive_internals.3.pdf Binary files differdeleted file mode 100644 index a0eafe5..0000000 --- a/libarchive/libarchive-2.8.0/doc/pdf/libarchive_internals.3.pdf +++ /dev/null diff --git a/libarchive/libarchive-2.8.0/doc/pdf/mtree.5.pdf b/libarchive/libarchive-2.8.0/doc/pdf/mtree.5.pdf Binary files differdeleted file mode 100644 index 9297b0d..0000000 --- a/libarchive/libarchive-2.8.0/doc/pdf/mtree.5.pdf +++ /dev/null diff --git a/libarchive/libarchive-2.8.0/doc/pdf/tar.5.pdf b/libarchive/libarchive-2.8.0/doc/pdf/tar.5.pdf Binary files differdeleted file mode 100644 index 6c934df..0000000 --- a/libarchive/libarchive-2.8.0/doc/pdf/tar.5.pdf +++ /dev/null diff --git a/libarchive/libarchive-2.8.0/doc/text/Makefile b/libarchive/libarchive-2.8.0/doc/text/Makefile deleted file mode 100644 index 2671acd..0000000 --- a/libarchive/libarchive-2.8.0/doc/text/Makefile +++ /dev/null @@ -1,46 +0,0 @@ - -default: all - - -archive_entry.3.txt: ../../libarchive/archive_entry.3 - nroff -mdoc ../../libarchive/archive_entry.3 | col -b > archive_entry.3.txt - -archive_read.3.txt: ../../libarchive/archive_read.3 - nroff -mdoc ../../libarchive/archive_read.3 | col -b > archive_read.3.txt - -archive_read_disk.3.txt: ../../libarchive/archive_read_disk.3 - nroff -mdoc ../../libarchive/archive_read_disk.3 | col -b > archive_read_disk.3.txt - -archive_util.3.txt: ../../libarchive/archive_util.3 - nroff -mdoc ../../libarchive/archive_util.3 | col -b > archive_util.3.txt - -archive_write.3.txt: ../../libarchive/archive_write.3 - nroff -mdoc ../../libarchive/archive_write.3 | col -b > archive_write.3.txt - -archive_write_disk.3.txt: ../../libarchive/archive_write_disk.3 - nroff -mdoc ../../libarchive/archive_write_disk.3 | col -b > archive_write_disk.3.txt - -cpio.5.txt: ../../libarchive/cpio.5 - nroff -mdoc ../../libarchive/cpio.5 | col -b > cpio.5.txt - -libarchive-formats.5.txt: ../../libarchive/libarchive-formats.5 - nroff -mdoc ../../libarchive/libarchive-formats.5 | col -b > libarchive-formats.5.txt - -libarchive.3.txt: ../../libarchive/libarchive.3 - nroff -mdoc ../../libarchive/libarchive.3 | col -b > libarchive.3.txt - -libarchive_internals.3.txt: ../../libarchive/libarchive_internals.3 - nroff -mdoc ../../libarchive/libarchive_internals.3 | col -b > libarchive_internals.3.txt - -mtree.5.txt: ../../libarchive/mtree.5 - nroff -mdoc ../../libarchive/mtree.5 | col -b > mtree.5.txt - -tar.5.txt: ../../libarchive/tar.5 - nroff -mdoc ../../libarchive/tar.5 | col -b > tar.5.txt - -bsdtar.1.txt: ../../tar/bsdtar.1 - nroff -mdoc ../../tar/bsdtar.1 | col -b > bsdtar.1.txt - -bsdcpio.1.txt: ../../cpio/bsdcpio.1 - nroff -mdoc ../../cpio/bsdcpio.1 | col -b > bsdcpio.1.txt -all: archive_entry.3.txt archive_read.3.txt archive_read_disk.3.txt archive_util.3.txt archive_write.3.txt archive_write_disk.3.txt cpio.5.txt libarchive-formats.5.txt libarchive.3.txt libarchive_internals.3.txt mtree.5.txt tar.5.txt bsdtar.1.txt bsdcpio.1.txt diff --git a/libarchive/libarchive-2.8.0/doc/text/archive_entry.3.txt b/libarchive/libarchive-2.8.0/doc/text/archive_entry.3.txt deleted file mode 100644 index a2e5f3c..0000000 --- a/libarchive/libarchive-2.8.0/doc/text/archive_entry.3.txt +++ /dev/null @@ -1,361 +0,0 @@ -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, - 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_link, - archive_entry_copy_link_w, archive_entry_copy_pathname_w, - archive_entry_copy_sourcepath, 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_sourcepath, - archive_entry_stat, archive_entry_symlink, archive_entry_uid, - archive_entry_uname -- functions for manipulating archive entry descrip- - tions - -SYNOPSIS - #include <archive_entry.h> - - 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 char * * - archive_entry_copy_fflags_text_w(struct archive_entry *, const char *); - - 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_sourcepath(struct archive_entry *, const char *); - - 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 char * - archive_entry_sourcepath(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() and archive_entry_copy_fflags_text_w() - functions parse the provided text and sets the internal bitmap values. - This is a platform-specific operation; names that are not meaningful on - the current platform will be ignored. The function returns a pointer to - the start of the first name that was not recognized, or NULL if every - name was recognized. Note that every name--including names that follow - an unrecognized name--will be evaluated, and the bitmaps will be set to - reflect every name that is recognized. (In particular, this differs from - 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 <kientzle@acm.org>. - -FreeBSD 8.0 May 12, 2008 FreeBSD 8.0 diff --git a/libarchive/libarchive-2.8.0/doc/text/archive_read.3.txt b/libarchive/libarchive-2.8.0/doc/text/archive_read.3.txt deleted file mode 100644 index 08ebef0..0000000 --- a/libarchive/libarchive-2.8.0/doc/text/archive_read.3.txt +++ /dev/null @@ -1,496 +0,0 @@ -archive_read(3) FreeBSD Library Functions Manual archive_read(3) - -NAME - archive_read_new, archive_read_set_filter_options, - archive_read_set_format_options, archive_read_set_options, - archive_read_support_compression_all, - archive_read_support_compression_bzip2, - archive_read_support_compression_compress, - archive_read_support_compression_gzip, - archive_read_support_compression_lzma, - archive_read_support_compression_none, - archive_read_support_compression_xz, - archive_read_support_compression_program, - archive_read_support_compression_program_signature, - archive_read_support_format_all, archive_read_support_format_ar, - archive_read_support_format_cpio, archive_read_support_format_empty, - archive_read_support_format_iso9660, archive_read_support_format_mtree, - archive_read_support_format_raw, 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_next_header2, 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_extract2, - archive_read_extract_set_progress_callback, archive_read_close, - archive_read_finish -- functions for reading streaming archives - -SYNOPSIS - #include <archive.h> - - 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_lzma(struct archive *); - - int - archive_read_support_compression_none(struct archive *); - - int - archive_read_support_compression_xz(struct archive *); - - int - archive_read_support_compression_program(struct archive *, - const char *cmd); - - int - archive_read_support_compression_program_signature(struct archive *, - const char *cmd, const void *signature, size_t signature_length); - - int - archive_read_support_format_all(struct archive *); - - int - archive_read_support_format_ar(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_mtree(struct archive *); - - int - archive_read_support_format_raw(struct archive *); - - int - archive_read_support_format_tar(struct archive *); - - int - archive_read_support_format_zip(struct archive *); - - int - archive_read_set_filter_options(struct archive *, const char *); - - int - archive_read_set_format_options(struct archive *, const char *); - - int - archive_read_set_options(struct archive *, const char *); - - 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 **); - - int - archive_read_next_header2(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); - - int - archive_read_extract2(struct archive *src, struct archive_entry *, - struct archive *dest); - - 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_bzip2(), - archive_read_support_compression_compress(), - archive_read_support_compression_gzip(), - archive_read_support_compression_lzma(), - archive_read_support_compression_none(), - archive_read_support_compression_xz() - Enables auto-detection code and decompression support for the - specified compression. Returns ARCHIVE_OK if the compression is - fully supported, or ARCHIVE_WARN if the compression is supported - only through an external program. Note that decompression using - an external program is usually slower than decompression through - built-in libraries. Note that ``none'' is always enabled by - default. - archive_read_support_compression_all() - Enables all available decompression filters. - 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_compression_program_signature() - This feeds data through the specified external program but only - if the initial bytes of the data match the specified signature - value. - archive_read_support_format_all(), archive_read_support_format_ar(), - archive_read_support_format_cpio(), - archive_read_support_format_empty(), - archive_read_support_format_iso9660(), - archive_read_support_format_mtree(), - 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_support_format_raw() - The ``raw'' format handler allows libarchive to be used to read - arbitrary data. It treats any data stream as an archive with a - single entry. The pathname of this entry is ``data''; all other - entry fields are unset. This is not enabled by - archive_read_support_format_all() in order to avoid erroneous - handling of damaged archives. - archive_read_set_filter_options(), archive_read_set_format_options(), - archive_read_set_options() - Specifies options that will be passed to currently-registered - filters (including decompression filters) and/or format readers. - The argument is a comma-separated list of individual options. - Individual options have one of the following forms: - option=value - The option/value pair will be provided to every module. - Modules that do not accept an option with this name will - ignore it. - option The option will be provided to every module with a value - of ``1''. - !option - The option will be provided to every module with a NULL - value. - module:option=value, module:option, module:!option - As above, but the corresponding option and value will be - provided only to modules whose name matches module. - The return value will be ARCHIVE_OK if any module accepts the - option, or ARCHIVE_WARN if no module accepted the option, or - ARCHIVE_FATAL if there was a fatal error while attempting to - process the option. - - The currently supported options are: - Format iso9660 - joliet Support Joliet extensions. Defaults to enabled, - use !joliet to disable. - 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. This is a convenience wrapper around - archive_read_next_header2() that reuses an internal struct - archive_entry object for each request. - archive_read_next_header2() - Read the header for the next entry and populate the provided - 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_extract2() - This is another version of archive_read_extract() that allows you - to provide your own restore object. In particular, this allows - you to override the standard lookup functions using - archive_write_disk_set_group_lookup(3), and - archive_write_disk_set_user_lookup(3). Note that - archive_read_extract2() does not accept a flags argument; you - should use archive_write_disk_set_options() to set the restore - options yourself. - 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 <kientzle@acm.org>. - -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 8.0 April 13, 2009 FreeBSD 8.0 diff --git a/libarchive/libarchive-2.8.0/doc/text/archive_read_disk.3.txt b/libarchive/libarchive-2.8.0/doc/text/archive_read_disk.3.txt deleted file mode 100644 index 0522bf4..0000000 --- a/libarchive/libarchive-2.8.0/doc/text/archive_read_disk.3.txt +++ /dev/null @@ -1,204 +0,0 @@ -archive_read_disk(3) FreeBSD Library Functions Manual archive_read_disk(3) - -NAME - archive_read_disk_new, archive_read_disk_set_symlink_logical, - archive_read_disk_set_symlink_physical, - archive_read_disk_set_symlink_hybrid, archive_read_disk_entry_from_file, - archive_read_disk_gname, archive_read_disk_uname, - archive_read_disk_set_uname_lookup, archive_read_disk_set_gname_lookup, - archive_read_disk_set_standard_lookup, archive_read_close, - archive_read_finish -- functions for reading objects from disk - -SYNOPSIS - #include <archive.h> - - struct archive * - archive_read_disk_new(void); - - int - archive_read_disk_set_symlink_logical(struct archive *); - - int - archive_read_disk_set_symlink_physical(struct archive *); - - int - archive_read_disk_set_symlink_hybrid(struct archive *); - - int - archive_read_disk_gname(struct archive *, gid_t); - - int - archive_read_disk_uname(struct archive *, uid_t); - - int - archive_read_disk_set_gname_lookup(struct archive *, void *, - const char *(*lookup)(void *, gid_t), void (*cleanup)(void *)); - - int - archive_read_disk_set_uname_lookup(struct archive *, void *, - const char *(*lookup)(void *, uid_t), void (*cleanup)(void *)); - - int - archive_read_disk_set_standard_lookup(struct archive *); - - int - archive_read_disk_entry_from_file(struct archive *, - struct archive_entry *, int fd, const struct stat *); - - int - archive_read_close(struct archive *); - - int - archive_read_finish(struct archive *); - -DESCRIPTION - These functions provide an API for reading information about objects on - disk. In particular, they provide an interface for populating struct - archive_entry objects. - - archive_read_disk_new() - Allocates and initializes a struct archive object suitable for - reading object information from disk. - - archive_read_disk_set_symlink_logical(), - archive_read_disk_set_symlink_physical(), - archive_read_disk_set_symlink_hybrid() - This sets the mode used for handling symbolic links. The - ``logical'' mode follows all symbolic links. The ``physical'' - mode does not follow any symbolic links. The ``hybrid'' mode - currently behaves identically to the ``logical'' mode. - - archive_read_disk_gname(), archive_read_disk_uname() - Returns a user or group name given a gid or uid value. By - default, these always return a NULL string. - - archive_read_disk_set_gname_lookup(), - archive_read_disk_set_uname_lookup() - These allow you to override the functions used for user and group - name lookups. 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 or when new lookup functions are registered. - - archive_read_disk_set_standard_lookup() - This convenience function installs a standard set of user and - group name lookup functions. These functions use getpwid(3) and - getgrid(3) to convert ids to names, defaulting to NULL if the - names cannot be looked up. These functions also implement a sim- - ple memory cache to reduce the number of calls to getpwid(3) and - getgrid(3). - - archive_read_disk_entry_from_file() - Populates a struct archive_entry object with information about a - particular file. The archive_entry object must have already been - created with archive_entry_new(3) and at least one of the source - path or path fields must already be set. (If both are set, the - source path will be used.) - - Information is read from disk using the path name from the struct - archive_entry object. If a file descriptor is provided, some - information will be obtained using that file descriptor, on plat- - forms that support the appropriate system calls. - - If a pointer to a struct stat is provided, information from that - structure will be used instead of reading from the disk where - appropriate. This can provide performance benefits in scenarios - where struct stat information has already been read from the disk - as a side effect of some other operation. (For example, direc- - tory traversal libraries often provide this information.) - - Where necessary, user and group ids are converted to user and - group names using the currently registered lookup functions - above. This affects the file ownership fields and ACL values in - the struct archive_entry object. - - archive_read_close() - This currently does nothing. - - 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. - -EXAMPLE - The following illustrates basic usage of the library by showing how to - use it to copy an item on disk into an archive. - - void - file_to_archive(struct archive *a, const char *name) - { - char buff[8192]; - size_t bytes_read; - struct archive *ard; - struct archive_entry *entry; - int fd; - - ard = archive_read_disk_new(); - archive_read_disk_set_standard_lookup(ard); - entry = archive_entry_new(); - fd = open(name, O_RDONLY); - if (fd < 0) - return; - archive_entry_copy_sourcepath(entry, name); - archive_read_disk_entry_from_file(ard, entry, fd, NULL); - archive_write_header(a, entry); - while ((bytes_read = read(fd, buff, sizeof(buff))) > 0) - archive_write_data(a, buff, bytes_read); - archive_write_finish_entry(a); - archive_read_finish(ard); - archive_entry_free(entry); - } - -RETURN VALUES - Most functions return ARCHIVE_OK (zero) on success, or one of several - negative 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(3) and archive_error_string(3) functions can be - used to retrieve an appropriate error code and a textual error message. - (See archive_util(3) for details.) - - archive_read_disk_new() returns a pointer to a newly-allocated struct - archive object or NULL if the allocation failed for any reason. - - archive_read_disk_gname() and archive_read_disk_uname() return const char - * pointers to the textual name or NULL if the lookup failed for any rea- - son. The returned pointer points to internal storage that may be reused - on the next call to either of these functions; callers should copy the - string if they need to continue accessing it. - -SEE ALSO - archive_read(3), archive_write(3), archive_write_disk(3), tar(1), - libarchive(3) - -HISTORY - The libarchive library first appeared in FreeBSD 5.3. The - archive_read_disk interface was added to libarchive 2.6 and first - appeared in FreeBSD 8.0. - -AUTHORS - The libarchive library was written by Tim Kientzle - <kientzle@freebsd.org>. - -BUGS - The ``standard'' user name and group name lookup functions are not the - defaults because getgrid(3) and getpwid(3) are sometimes too large for - particular applications. The current design allows the application - author to use a more compact implementation when appropriate. - - The full list of metadata read from disk by - archive_read_disk_entry_from_file() is necessarily system-dependent. - - The archive_read_disk_entry_from_file() function reads as much informa- - tion as it can from disk. Some method should be provided to limit this - so that clients who do not need ACLs, for instance, can avoid the extra - work needed to look up such information. - - This API should provide a set of methods for walking a directory tree. - That would make it a direct parallel of the archive_read(3) API. When - such methods are implemented, the ``hybrid'' symbolic link mode will make - sense. - -FreeBSD 8.0 March 10, 2009 FreeBSD 8.0 diff --git a/libarchive/libarchive-2.8.0/doc/text/archive_util.3.txt b/libarchive/libarchive-2.8.0/doc/text/archive_util.3.txt deleted file mode 100644 index 190fc26..0000000 --- a/libarchive/libarchive-2.8.0/doc/text/archive_util.3.txt +++ /dev/null @@ -1,99 +0,0 @@ -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_file_count, archive_format, archive_format_name, - archive_set_error -- libarchive utility functions - -SYNOPSIS - #include <archive.h> - - 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_file_count(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_file_count() - Returns a count of the number of files processed by this archive - object. The count is incremented by calls to - archive_write_header or archive_read_next_header. - 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 <kientzle@acm.org>. - -FreeBSD 8.0 January 8, 2005 FreeBSD 8.0 diff --git a/libarchive/libarchive-2.8.0/doc/text/archive_write.3.txt b/libarchive/libarchive-2.8.0/doc/text/archive_write.3.txt deleted file mode 100644 index 132289b..0000000 --- a/libarchive/libarchive-2.8.0/doc/text/archive_write.3.txt +++ /dev/null @@ -1,486 +0,0 @@ -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_compress, - archive_write_set_compression_gzip, archive_write_set_compression_none, - archive_write_set_compression_program, - archive_write_set_compressor_options, archive_write_set_format_options, - archive_write_set_options, 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 archives - -SYNOPSIS - #include <archive.h> - - 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_compress(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_set_format_options(struct archive *, const char *); - - int - archive_write_set_compressor_options(struct archive *, const char *); - - int - archive_write_set_options(struct archive *, const char *); - - 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_compress(), - 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_set_compressor_options(), - archive_write_set_format_options(), archive_write_set_options() - Specifies options that will be passed to the currently-enabled - compressor and/or format writer. The argument is a comma-sepa- - rated list of individual options. Individual options have one of - the following forms: - option=value - The option/value pair will be provided to every module. - Modules that do not accept an option with this name will - ignore it. - option The option will be provided to every module with a value - of ``1''. - !option - The option will be provided to every module with a NULL - value. - module:option=value, module:option, module:!option - As above, but the corresponding option and value will be - provided only to modules whose name matches module. - The return value will be ARCHIVE_OK if any module accepts the - option, or ARCHIVE_WARN if no module accepted the option, or - ARCHIVE_FATAL if there was a fatal error while attempting to - process the option. - - The currently supported options are: - Compressor gzip - compression-level - The value is interpreted as a decimal integer - specifying the gzip compression level. - Compressor xz - compression-level - The value is interpreted as a decimal integer - specifying the compression level. - Format mtree - cksum, device, flags, gid, gname, indent, link, md5, - mode, nlink, rmd160, sha1, sha256, sha384, - sha512, size, time, uid, uname - Enable a particular keyword in the mtree output. - Prefix with an exclamation mark to disable the - corresponding keyword. The default is equivalent - to ``device, flags, gid, gname, link, mode, - nlink, size, time, type, uid, uname''. - all Enables all of the above keywords. - use-set - Enables generation of /set lines that specify - default values for the following files and/or - directories. - indent XXX needs explanation XXX - - 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, const 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. - - #ifdef __linux__ - #define _FILE_OFFSET_BITS 64 - #endif - #include <sys/stat.h> - #include <archive.h> - #include <archive_entry.h> - #include <fcntl.h> - #include <stdlib.h> - #include <unistd.h> - - struct mydata { - const char *name; - int fd; - }; - - int - myopen(struct archive *a, void *client_data) - { - struct mydata *mydata = client_data; - - mydata->fd = open(mydata->name, O_WRONLY | O_CREAT, 0644); - if (mydata->fd >= 0) - return (ARCHIVE_OK); - else - return (ARCHIVE_FATAL); - } - - ssize_t - mywrite(struct archive *a, void *client_data, const void *buff, size_t n) - { - struct mydata *mydata = client_data; - - return (write(mydata->fd, buff, n)); - } - - int - myclose(struct archive *a, void *client_data) - { - struct mydata *mydata = client_data; - - if (mydata->fd > 0) - close(mydata->fd); - return (0); - } - - void - write_archive(const char *outname, const char **filename) - { - struct mydata *mydata = malloc(sizeof(struct mydata)); - struct archive *a; - struct archive_entry *entry; - struct stat st; - char buff[8192]; - int len; - int fd; - - a = archive_write_new(); - mydata->name = outname; - archive_write_set_compression_gzip(a); - archive_write_set_format_ustar(a); - archive_write_open(a, mydata, myopen, mywrite, myclose); - while (*filename) { - stat(*filename, &st); - entry = archive_entry_new(); - archive_entry_copy_stat(entry, &st); - archive_entry_set_pathname(entry, *filename); - archive_write_header(a, entry); - fd = open(*filename, O_RDONLY); - len = read(fd, buff, sizeof(buff)); - while ( len > 0 ) { - archive_write_data(a, buff, len); - len = read(fd, buff, sizeof(buff)); - } - archive_entry_free(entry); - filename++; - } - archive_write_finish(a); - } - - int main(int argc, const char **argv) - { - const char *outname; - argv++; - outname = argv++; - write_archive(outname, argv); - return 0; - } - -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 <kientzle@acm.org>. - -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 8.0 May 11, 2008 FreeBSD 8.0 diff --git a/libarchive/libarchive-2.8.0/doc/text/archive_write_disk.3.txt b/libarchive/libarchive-2.8.0/doc/text/archive_write_disk.3.txt deleted file mode 100644 index e63ec61..0000000 --- a/libarchive/libarchive-2.8.0/doc/text/archive_write_disk.3.txt +++ /dev/null @@ -1,257 +0,0 @@ -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 <archive.h> - - 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_EXTRACT_SPARSE - Scan data for blocks of NUL bytes and try to recreate - them with holes. This results in sparse files, indepen- - dent of whether the archive format supports or uses them. - - 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 <kientzle@acm.org>. - -BUGS - Directories are actually extracted in two distinct phases. Directories - are created during archive_write_header(), but final permissions are not - set until archive_write_close(). This separation is necessary to 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 8.0 August 5, 2008 FreeBSD 8.0 diff --git a/libarchive/libarchive-2.8.0/doc/text/bsdcpio.1.txt b/libarchive/libarchive-2.8.0/doc/text/bsdcpio.1.txt deleted file mode 100644 index b8810a6..0000000 --- a/libarchive/libarchive-2.8.0/doc/text/bsdcpio.1.txt +++ /dev/null @@ -1,250 +0,0 @@ -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 (unless overriden) - and extract the contents to disk or (if the -t option is speci- - fied) list the contents to standard output. If one or more file - patterns are specified, 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 (unless overriden) 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. - - -0 Read filenames separated by NUL characters instead of newlines. - This is necessary if any of the filenames being read might con- - tain newlines. - - -A (o mode only) Append to the specified archive. (Not yet imple- - mented.) - - -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 size - (o mode only) Block output to records of size 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. - - -E file - (i mode only) Read list of file name patterns from file to list - and extract. - - -F file - Read archive from or write archive to file. - - -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. - - -H format - Synonym for --format. - - -h, --help - Print usage information. - - -I file - Read archive from file. - - -i Input mode. See above for description. - - --insecure - (i and p mode only) Disable security checks during extraction or - copying. This allows extraction via symbolic links and path - names containing `..' in the name. - - -J (o mode only) Compress the file with xz-compatible compression - before writing it. In input mode, this option is ignored; xz - compression is recognized automatically on input. - - -j Synonym for -y. - - -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. - - -lzma (o mode only) Compress the file with lzma-compatible compression - before writing it. In input mode, this option is ignored; lzma - compression is recognized automatically on input. - - -m (i and p modes) Set file modification time on created files to - match those in the source. - - -n (i mode, only with -t) Display numeric uid and gid. By default, - cpio displays the user and group names when they are provided in - the archive, or looks up the user and group names in the system - password database. - - -no-preserve-owner - (i mode only) Do not attempt to restore file ownership. This is - the default when run by non-root users. - - -O file - Write archive to file. - - -o Output mode. See above for description. - - -p Pass-through mode. See above for description. - - -preserve-owner - (i mode only) Restore file ownership. This is the default when - run by the root user. - - --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 it. In input mode, this option is ignored; - bzip2 compression is recognized automatically on input. - - -Z (o mode only) Compress the archive with compress-compatible com- - pression before writing it. In input mode, this option is - ignored; compression is recognized automatically on input. - - -z (o mode only) Compress the archive with gzip-compatible compres- - sion before writing it. 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 8.0 December 21, 2007 FreeBSD 8.0 diff --git a/libarchive/libarchive-2.8.0/doc/text/bsdtar.1.txt b/libarchive/libarchive-2.8.0/doc/text/bsdtar.1.txt deleted file mode 100644 index b5d2148..0000000 --- a/libarchive/libarchive-2.8.0/doc/text/bsdtar.1.txt +++ /dev/null @@ -1,549 +0,0 @@ -BSDTAR(1) FreeBSD General Commands Manual BSDTAR(1) - -NAME - tar -- manipulate tape archives - -SYNOPSIS - tar [bundled-flags <args>] [<file> | <pattern> ...] - 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 - (c and r modes only) Issue a warning message unless all links to - each file are archived. - - --chroot - (x mode only) chroot() to the current directory after processing - any -C options and before extracting any files. - - --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 - (c, r, u mode only) Use the specified format for the created ar- - chive. 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. In r and u modes, when extending an existing ar- - chive, the format specified here must be compatible with the for- - mat of the existing archive on disk. - - -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.) - - -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 - 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. - - --keep-newer-files - (x mode only) Do not overwrite existing files that are newer than - the versions appearing in the archive being extracted. - - -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 - (c, r, u modes only) Only include files and directories newer - than the specified date. This compares ctime entries. - - --newer-mtime date - (c, r, u modes only) Like --newer, except it compares mtime - entries instead of ctime entries. - - --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 - (c, r, u modes only) Like --newer-than, except it compares mtime - entries instead of ctime entries. - - --nodump - (c and r modes only) Honor the nodump file flag by skipping this - file. - - --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). - - --numeric-owner - (x mode only) Ignore symbolic user and group names when restoring - archives to disk, only numeric uid and gid values will be obeyed. - - -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) 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 -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 information - in the archive will be discarded. - - -o (c, r, u mode) A synonym for --format ustar - - --one-file-system - (c, r, and u modes) Do not cross mount points. - - --options options - Select optional behaviors for particular modules. The argument - is a text string containing comma-separated keywords and values. - These are passed to the modules that handle particular formats to - control how those formats will behave. Each option has one of - the following forms: - key=value - The key will be set to the specified value in every mod- - ule that supports it. Modules that do not support this - key will ignore it. - key The key will be enabled in every module that supports it. - This is equivalent to key=1. - !key The key will be disabled in every module that supports - it. - module:key=value, module:key, module:!key - As above, but the corresponding key and value will be - provided only to modules whose name matches module. - The currently supported modules and keys are: - iso9660:joliet - Support Joliet extensions. This is enabled by default, - use !joliet or iso9660:!joliet to disable. - iso9660:rockridge - Support Rock Ridge extensions. This is enabled by - default, use !rockridge or iso9660:!rockridge to disable. - gzip:compression-level - A decimal integer from 0 to 9 specifying the gzip com- - pression level. - xz:compression-level - A decimal integer from 0 to 9 specifying the xz compres- - sion level. - mtree:keyword - The mtree writer module allows you to specify which mtree - keywords will be included in the output. Supported key- - words include: cksum, device, flags, gid, gname, indent, - link, md5, mode, nlink, rmd160, sha1, sha256, sha384, - sha512, size, time, uid, uname. The default is equiva- - lent to: ``device, flags, gid, gname, link, mode, nlink, - size, time, type, uid, uname''. - mtree:all - Enables all of the above keywords. You can also use - mtree:!all to disable all keywords. - mtree:use-set - Enable generation of /set lines in the output. - mtree:indent - Produce human-readable output by indenting options and - splitting lines to fit into 80 columns. - zip:compression=type - Use type as compression method. Supported values are - store (uncompressed) and deflate (gzip algorithm). - If a provided option is not supported by any module, that is a - fatal error. - - -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. - - -q (--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. - - -S (x mode only) Extract files as sparse files. For every block on - disk, check first if it contains only NULL bytes and seek over it - otherwise. This works similiar to the conv=sparse option of dd. - - --strip-components count - (x mode only) Remove the specified number of leading path ele- - ments. Pathnames with fewer elements will be silently skipped. - Note that the pathname is edited after checking inclusion/exclu- - sion patterns but before security checks. - - -s pattern - Modify file or archive member names according to pattern. The - pattern has the format /old/new/[gps] where old is a basic regu- - lar expression, new is the replacement string of the matched - part, and the optional trailing letters modify how the replace- - ment is handled. If old is not matched, the pattern is skipped. - Within new, ~ is substituted with the match, 1 to 9 with the con- - tent of the corresponding captured group. The optional trailing - g specifies that matching should continue after the matched part - and stopped on the first unmatched pattern. The optional trail- - ing s specifies that the pattern applies to the value of symbolic - links. The optional trailing p specifies that after a successful - substitution the original path name and the new path name should - be printed to standard error. - - -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. - - --version - Print version of tar and libarchive, and exit. - - -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. - - -Z (c mode only) Compress the resulting archive with compress(1). - In extract or list modes, this option is ignored. Note that, - unlike other tar implementations, this implementation recognizes - compress 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. - - An input file in mtree(5) format can be used to create an output archive - with arbitrary ownership, permissions, or names that differ from existing - data on disk: - - $ cat input.mtree - #mtree - usr/bin uid=0 gid=0 mode=0755 type=dir - usr/bin/ls uid=0 gid=0 mode=0755 type=file content=myls - $ tar -cvf output.tar @input.mtree - - 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''. - - The --options argument can be used to control various details of archive - generation or reading. For example, you can generate mtree output which - only contains type, time, and uid keywords: - tar -cf file.tar --format=mtree --options='!all,type,time,uid' dir - or you can set the compression level used by gzip or xz compression: - tar -czf file.tar --options='compression-level=9'. - For more details, see the explanation of the archive_read_set_options() - and archive_write_set_options() API calls that are described in - archive_read(3) and archive_write(3). - -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. - - Additional long options are provided 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), compress(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 8.0 Oct 12, 2009 FreeBSD 8.0 diff --git a/libarchive/libarchive-2.8.0/doc/text/cpio.5.txt b/libarchive/libarchive-2.8.0/doc/text/cpio.5.txt deleted file mode 100644 index 5ece811..0000000 --- a/libarchive/libarchive-2.8.0/doc/text/cpio.5.txt +++ /dev/null @@ -1,235 +0,0 @@ -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 NUL 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 NUL byte is added after the pathname. The file data - is then appended, padded with NUL bytes to an even length. - - Hardlinked files are not given special treatment; the full file contents - are included with each copy of the file. - - 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 NUL 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 NUL bytes so that the total size of the fixed - header plus pathname is a multiple of four. Likewise, the file data is - padded to a multiple of four bytes. Note that this format supports only - 4 gigabyte files (unlike the older ASCII format, which supports 8 giga- - byte 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 8.0 October 5, 2007 FreeBSD 8.0 diff --git a/libarchive/libarchive-2.8.0/doc/text/libarchive-formats.5.txt b/libarchive/libarchive-2.8.0/doc/text/libarchive-formats.5.txt deleted file mode 100644 index 9e6523d..0000000 --- a/libarchive/libarchive-2.8.0/doc/text/libarchive-formats.5.txt +++ /dev/null @@ -1,241 +0,0 @@ -libarchive-formats(5) FreeBSD File Formats Manual libarchive-formats(5) - -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, though many programs do use - libarchive convenience functions to enable all supported formats. - - 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 immediately - before each regular entry. The presence of these additional - entries is the only difference between pax interchange format and - the older ustar format. The extended attributes are of unlimited - length and are stored as UTF-8 Unicode strings. Keywords defined - in the standard are in all lowercase; vendors are allowed to - define custom keys by preceding them with the vendor name in all - uppercase. When writing pax archives, libarchive uses many of - the SCHILY keys defined by Joerg Schilling's ``star'' archiver - and a few LIBARCHIVE keys. The libarchive library can read most - of the SCHILY keys and most of the GNU keys introduced by GNU - tar. It silently ignores any keywords that it does not under- - stand. - - 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 8 gigabytes in size. - Note that the pax interchange format has none of these restric- - tions. - - The libarchive library also reads a variety of commonly-used extensions - to the basic tar format. These extensions are recognized automatically - whenever they appear. - - Numeric extensions. - The POSIX standards require fixed-length numeric fields to be - written with some character position reserved for terminators. - Libarchive allows these fields to be written without terminator - characters. This extends the allowable range; in particular, - ustar archives with this extension can support entries up to 64 - gigabytes in size. Libarchive also recognizes base-256 values in - most numeric fields. This essentially removes all limitations on - file size, modification time, and device numbers. - - Solaris extensions - Libarchive recognizes ACL and extended attribute records written - by Solaris tar. Currently, libarchive only has support for old- - style ACLs; the newer NFSv4 ACLs are recognized but discarded. - - 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 the tar format, the cpio format does only - minimal padding of the header or file data. There are several cpio vari- - ants, 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 transparently reads both big-endian and - little-endian variants of the original binary cpio format. This - format used 32-bit binary values for file size and mtime, and - 16-bit binary values for the other fields. - - odc The libarchive library can both read and write this POSIX-stan- - dard format, which is officially known as the ``cpio interchange - format'' or the ``octet-oriented cpio archive format'' and some- - times unofficially referred to as the ``old character format''. - This format stores the header contents as octal values in ASCII. - It is standard, portable, and immune from byte-order confusion. - File sizes and mtime are limited to 33 bits (8GB file size), - other fields are limited to 18 bits. - - 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. In many cases, this can remove the need to burn a physical - CDROM just in order to read the files contained in an ISO9660 image. It - also avoids security and complexity issues that come with virtual mounts - and loopback devices. Libarchive supports the most common Rockridge - extensions and has partial support for Joliet extensions. If both exten- - sions are present, the Joliet extensions will be used and the Rockridge - extensions will be ignored. In particular, this can create problems with - hardlinks and symlinks, which are supported by Rockridge but not by - Joliet. - - Zip format - Libarchive can read and write zip format archives that have uncompressed - entries and entries compressed with the ``deflate'' algorithm. Older zip - compression algorithms are not supported. It can extract jar archives, - archives that use Zip64 extensions and many self-extracting zip archives. - Libarchive reads Zip archives as they are being streamed, which allows it - to read archives of arbitrary size. It currently does not use the cen- - tral directory; this limits libarchive's ability to support some self- - extracting archives and ones that have been modified in certain ways. - - 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. The two differ - primarily in their handling of filenames longer than 15 characters: the - GNU/SVR4 variant writes a filename table at the beginning of the archive; - the BSD format stores each long filename in an extension area adjacent to - the entry. Libarchive can read both extensions, including archives that - may include both types of long filenames. Programs using libarchive can - write GNU/SVR4 format if they provide a filename table to be written into - the archive before any of the entries. Any entries whose names are not - in the filename table will be written using BSD-style long filenames. - This can cause problems for programs such as GNU ld that do not support - the BSD-style long filenames. - - mtree - Libarchive can read and write files in mtree(5) format. This format is - not a true archive format, but rather a textual description of a file - hierarchy in which each line specifies the name of a file and provides - specific metadata about that file. Libarchive can read all of the key- - words supported by both the NetBSD and FreeBSD versions of mtree(1), - although many of the keywords cannot currently be stored in an - archive_entry object. When writing, libarchive supports use of the - archive_write_set_options(3) interface to specify which keywords should - be included in the output. If libarchive was compiled with access to - suitable cryptographic libraries (such as the OpenSSL libraries), it can - compute hash entries such as sha512 or md5 from file data being written - to the mtree writer. - - When reading an mtree file, libarchive will locate the corresponding - files on disk using the contents keyword if present or the regular file- - name. If it can locate and open the file on disk, it will use that to - fill in any metadata that is missing from the mtree file and will read - the file contents and return those to the program using libarchive. If - it cannot locate and open the file on disk, libarchive will return an - error for any attempt to read the entry body. - -SEE ALSO - ar(1), cpio(1), mkisofs(1), shar(1), tar(1), zip(1), zlib(3), cpio(5), - mtree(5), tar(5) - -FreeBSD 8.0 December 27, 2009 FreeBSD 8.0 diff --git a/libarchive/libarchive-2.8.0/doc/text/libarchive.3.txt b/libarchive/libarchive-2.8.0/doc/text/libarchive.3.txt deleted file mode 100644 index f00d977..0000000 --- a/libarchive/libarchive-2.8.0/doc/text/libarchive.3.txt +++ /dev/null @@ -1,185 +0,0 @@ -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 <kientzle@acm.org>. - -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 8.0 August 19, 2006 FreeBSD 8.0 diff --git a/libarchive/libarchive-2.8.0/doc/text/libarchive_internals.3.txt b/libarchive/libarchive-2.8.0/doc/text/libarchive_internals.3.txt deleted file mode 100644 index e5e65bd..0000000 --- a/libarchive/libarchive-2.8.0/doc/text/libarchive_internals.3.txt +++ /dev/null @@ -1,248 +0,0 @@ -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 <kientzle@acm.org>. - -BUGS -FreeBSD 8.0 April 16, 2007 FreeBSD 8.0 diff --git a/libarchive/libarchive-2.8.0/doc/text/mtree.5.txt b/libarchive/libarchive-2.8.0/doc/text/mtree.5.txt deleted file mode 100644 index 375e4a2..0000000 --- a/libarchive/libarchive-2.8.0/doc/text/mtree.5.txt +++ /dev/null @@ -1,158 +0,0 @@ -MTREE(5) FreeBSD File Formats Manual MTREE(5) - -NAME - mtree -- format of mtree dir hierarchy 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 hierarchies. - - 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 definition consists - of a key from the following list immediately followed by an '=' sign and - a value. Software programs reading mtree files should warn about 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 that holds 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. - - gid The file group as a numeric value. - - gname The file group as a symbolic name. - - ignore Ignore any file hierarchy below this file. - - link The target of the symbolic link when type=link. - - md5 The MD5 message digest of the file. - - md5digest A synonym for md5. - - 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. - - ripemd160digest - The RIPEMD160 message digest of the file. - - rmd160 A synonym for ripemd160digest. - - rmd160digest - A synonym for ripemd160digest. - - 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. - - size The size, in bytes, of the file. - - 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 - - uid The file owner as a numeric value. - - uname The file owner as a symbolic name. - -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 8.0 August 20, 2007 FreeBSD 8.0 diff --git a/libarchive/libarchive-2.8.0/doc/text/tar.5.txt b/libarchive/libarchive-2.8.0/doc/text/tar.5.txt deleted file mode 100644 index d110436..0000000 --- a/libarchive/libarchive-2.8.0/doc/text/tar.5.txt +++ /dev/null @@ -1,601 +0,0 @@ -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 maximum block size supported by early implemen- - tations was 10240 bytes or 20 records. This is still the default for - most implementations although block sizes of 1MiB (2048 records) or - larger are commonly used with modern high-speed tape drives. (Note: the - terms ``block'' and ``record'' here are not entirely standard; this docu- - ment follows the convention established by John Gilmore in documenting - 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 seems to be the earliest widely-used version - 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. NUL 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 NUL 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. - - name, prefix - 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 into the prefix field. 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 pathname. - The standard does not require a trailing / character on directory - names, though most implementations still include this for compat- - ibility reasons. - - Note that all unused bytes must be set to NUL. - - Field termination is specified slightly differently by POSIX than by pre- - vious implementations. The magic, uname, and gname fields must have a - trailing NUL. The pathname, linkname, and prefix fields must have a - trailing NUL 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 requires them to be terminated with either space or NUL - 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.fflags - The file flags. - - SCHILY.realsize - The full size of the file on disk. XXX explain? XXX - - 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. - - 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. Due to security concerns, "N" records are now gen- - erally ignored when reading archives. - - 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. - - GNU tar pax archives - GNU tar 1.14 (XXX check this XXX) and later will write pax interchange - format archives when you specify the --posix flag. This format uses cus- - tom keywords to store sparse file information. There have been three - iterations of this support, referred to as ``0.0'', ``0.1'', and ``1.0''. - - GNU.sparse.numblocks, GNU.sparse.offset, GNU.sparse.numbytes, - GNU.sparse.size - The ``0.0'' format used an initial GNU.sparse.numblocks attribute - to indicate the number of blocks in the file, a pair of - GNU.sparse.offset and GNU.sparse.numbytes to indicate the offset - and size of each block, and a single GNU.sparse.size to indicate - the full size of the file. This is not the same as the size in - the tar header because the latter value does not include the size - of any holes. This format required that the order of attributes - be preserved and relied on readers accepting multiple appearances - of the same attribute names, which is not officially permitted by - the standards. - - GNU.sparse.map - The ``0.1'' format used a single attribute that stored a comma- - separated list of decimal numbers. Each pair of numbers indi- - cated the offset and size, respectively, of a block of data. - This does not work well if the archive is extracted by an - archiver that does not recognize this extension, since many pax - implementations simply discard unrecognized attributes. - - GNU.sparse.major, GNU.sparse.minor, GNU.sparse.name, GNU.sparse.realsize - The ``1.0'' format stores the sparse block map in one or more - 512-byte blocks prepended to the file data in the entry body. - The pax attributes indicate the existence of this map (via the - GNU.sparse.major and GNU.sparse.minor fields) and the full size - of the file. The GNU.sparse.name holds the true name of the - file. To avoid confusion, the name stored in the regular tar - header is a modified name so that extraction errors will be - apparent to users. - - 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 followed by a zero byte, followed by the textual ACL - description. The octal value is the number of ACL entries plus a - constant that indicates the ACL type: 01000000 for POSIX.1e ACLs - and 03000000 for NFSv4 ACLs. - - AIX Tar - XXX More details needed XXX - - Mac OS X Tar - The tar distributed with Apple's Mac OS X stores most regular files as - two separate entries in the tar archive. The two entries have the same - name except that the first one has ``._'' added to the beginning of the - name. This first entry stores the ``resource fork'' with additional - attributes for the file. The Mac OS X CopyFile() API is used to separate - a file on disk into separate resource and data streams and to reassemble - those separate streams when the file is restored to disk. - - Other Extensions - One obvious extension to increase the size of files is to eliminate the - terminating characters from the various numeric fields. For example, the - standard only allows the size field to contain 11 octal digits, reserving - the twelfth byte for a trailing NUL character. Allowing 12 octal digits - allows file sizes up to 64 GB. - - Another extension, utilized by GNU tar, star, and other newer tar imple- - mentations, permits binary numbers in the standard numeric fields. This - is flagged by setting the high bit of the first byte. This permits - 95-bit values for the length and time fields and 63-bit values for the - uid, gid, and device numbers. GNU tar supports this extension for the - length, mtime, ctime, and atime fields. Joerg Schilling's star program - supports this extension for all numeric fields. Note that this extension - is largely obsoleted by the extended attribute record provided by the pax - interchange format. - - Another early GNU extension allowed base-64 values rather than octal. - This extension was short-lived and is no longer supported by any imple- - mentation. - -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 (circa 1988). Joerg Shilling's star - archiver is another open-source (GPL) archiver (originally developed - circa 1985) which features complete support for pax interchange format. - - This documentation was written as part of the libarchive and bsdtar - project by Tim Kientzle <kientzle@FreeBSD.org>. - -FreeBSD 8.0 December 27, 2009 FreeBSD 8.0 diff --git a/libarchive/libarchive-2.8.0/doc/update.sh b/libarchive/libarchive-2.8.0/doc/update.sh deleted file mode 100644 index 1427d70..0000000 --- a/libarchive/libarchive-2.8.0/doc/update.sh +++ /dev/null @@ -1,107 +0,0 @@ -#!/bin/sh - -# -# Simple script to repopulate the 'doc' tree from -# the mdoc man pages stored in each project. -# - -# Collect list of man pages, relative to my subdirs -cd man -MANPAGES=`for d in libarchive tar cpio;do ls ../../$d/*.[135];done | grep -v '\.so\.'` -cd .. - -# Build Makefile in 'man' directory -cd man -rm -f *.[135] -echo > Makefile -echo "default: all" >>Makefile -echo >>Makefile -all="all:" -for f in $MANPAGES; do - outname="`basename $f`" - echo >> Makefile - echo $outname: ../mdoc2man.awk $f >> Makefile - echo " awk -f ../mdoc2man.awk < $f > $outname" >> Makefile - all="$all $outname" -done -echo $all >>Makefile -cd .. - -# Rebuild Makefile in 'text' directory -cd text -rm -f *.txt -echo > Makefile -echo "default: all" >>Makefile -echo >>Makefile -all="all:" -for f in $MANPAGES; do - outname="`basename $f`.txt" - echo >> Makefile - echo $outname: $f >> Makefile - echo " nroff -mdoc $f | col -b > $outname" >> Makefile - all="$all $outname" -done -echo $all >>Makefile -cd .. - -# Rebuild Makefile in 'pdf' directory -cd pdf -rm -f *.pdf -echo > Makefile -echo "default: all" >>Makefile -echo >>Makefile -all="all:" -for f in $MANPAGES; do - outname="`basename $f`.pdf" - echo >> Makefile - echo $outname: $f >> Makefile - echo " groff -mdoc -T ps $f | ps2pdf - - > $outname" >> Makefile - all="$all $outname" -done -echo $all >>Makefile -cd .. - -# Build Makefile in 'html' directory -cd html -rm -f *.html -echo > Makefile -echo "default: all" >>Makefile -echo >>Makefile -all="all:" -for f in $MANPAGES; do - outname="`basename $f`.html" - echo >> Makefile - echo $outname: ../mdoc2man.awk $f >> Makefile - echo " groff -mdoc -T html $f > $outname" >> Makefile - all="$all $outname" -done -echo $all >>Makefile -cd .. - -# Build Makefile in 'wiki' directory -cd wiki -rm -f *.wiki -echo > Makefile -echo "default: all" >>Makefile -echo >>Makefile -all="all:" -for f in $MANPAGES; do - outname="`basename $f | awk '{ac=split($0,a,"[_.-]");o="ManPage";for(w=0;w<=ac;++w){o=o toupper(substr(a[w],1,1)) substr(a[w],2)};print o}'`.wiki" - echo >> Makefile - echo $outname: ../mdoc2wiki.awk $f >> Makefile - echo " awk -f ../mdoc2wiki.awk < $f > $outname" >> Makefile - all="$all $outname" -done -echo $all >>Makefile -cd .. - -# Convert all of the manpages to -man format -(cd man && make) -# Format all of the manpages to text -(cd text && make) -# Format all of the manpages to PDF -(cd pdf && make) -# Format all of the manpages to HTML -(cd html && make) -# Format all of the manpages to Google Wiki syntax -(cd wiki && make) diff --git a/libarchive/libarchive-2.8.0/doc/wiki/Makefile b/libarchive/libarchive-2.8.0/doc/wiki/Makefile deleted file mode 100644 index e6d6038..0000000 --- a/libarchive/libarchive-2.8.0/doc/wiki/Makefile +++ /dev/null @@ -1,46 +0,0 @@ - -default: all - - -ManPageArchiveEntry3.wiki: ../mdoc2wiki.awk ../../libarchive/archive_entry.3 - awk -f ../mdoc2wiki.awk < ../../libarchive/archive_entry.3 > ManPageArchiveEntry3.wiki - -ManPageArchiveRead3.wiki: ../mdoc2wiki.awk ../../libarchive/archive_read.3 - awk -f ../mdoc2wiki.awk < ../../libarchive/archive_read.3 > ManPageArchiveRead3.wiki - -ManPageArchiveReadDisk3.wiki: ../mdoc2wiki.awk ../../libarchive/archive_read_disk.3 - awk -f ../mdoc2wiki.awk < ../../libarchive/archive_read_disk.3 > ManPageArchiveReadDisk3.wiki - -ManPageArchiveUtil3.wiki: ../mdoc2wiki.awk ../../libarchive/archive_util.3 - awk -f ../mdoc2wiki.awk < ../../libarchive/archive_util.3 > ManPageArchiveUtil3.wiki - -ManPageArchiveWrite3.wiki: ../mdoc2wiki.awk ../../libarchive/archive_write.3 - awk -f ../mdoc2wiki.awk < ../../libarchive/archive_write.3 > ManPageArchiveWrite3.wiki - -ManPageArchiveWriteDisk3.wiki: ../mdoc2wiki.awk ../../libarchive/archive_write_disk.3 - awk -f ../mdoc2wiki.awk < ../../libarchive/archive_write_disk.3 > ManPageArchiveWriteDisk3.wiki - -ManPageCpio5.wiki: ../mdoc2wiki.awk ../../libarchive/cpio.5 - awk -f ../mdoc2wiki.awk < ../../libarchive/cpio.5 > ManPageCpio5.wiki - -ManPageLibarchiveFormats5.wiki: ../mdoc2wiki.awk ../../libarchive/libarchive-formats.5 - awk -f ../mdoc2wiki.awk < ../../libarchive/libarchive-formats.5 > ManPageLibarchiveFormats5.wiki - -ManPageLibarchive3.wiki: ../mdoc2wiki.awk ../../libarchive/libarchive.3 - awk -f ../mdoc2wiki.awk < ../../libarchive/libarchive.3 > ManPageLibarchive3.wiki - -ManPageLibarchiveInternals3.wiki: ../mdoc2wiki.awk ../../libarchive/libarchive_internals.3 - awk -f ../mdoc2wiki.awk < ../../libarchive/libarchive_internals.3 > ManPageLibarchiveInternals3.wiki - -ManPageMtree5.wiki: ../mdoc2wiki.awk ../../libarchive/mtree.5 - awk -f ../mdoc2wiki.awk < ../../libarchive/mtree.5 > ManPageMtree5.wiki - -ManPageTar5.wiki: ../mdoc2wiki.awk ../../libarchive/tar.5 - awk -f ../mdoc2wiki.awk < ../../libarchive/tar.5 > ManPageTar5.wiki - -ManPageBsdtar1.wiki: ../mdoc2wiki.awk ../../tar/bsdtar.1 - awk -f ../mdoc2wiki.awk < ../../tar/bsdtar.1 > ManPageBsdtar1.wiki - -ManPageBsdcpio1.wiki: ../mdoc2wiki.awk ../../cpio/bsdcpio.1 - awk -f ../mdoc2wiki.awk < ../../cpio/bsdcpio.1 > ManPageBsdcpio1.wiki -all: ManPageArchiveEntry3.wiki ManPageArchiveRead3.wiki ManPageArchiveReadDisk3.wiki ManPageArchiveUtil3.wiki ManPageArchiveWrite3.wiki ManPageArchiveWriteDisk3.wiki ManPageCpio5.wiki ManPageLibarchiveFormats5.wiki ManPageLibarchive3.wiki ManPageLibarchiveInternals3.wiki ManPageMtree5.wiki ManPageTar5.wiki ManPageBsdtar1.wiki ManPageBsdcpio1.wiki diff --git a/libarchive/libarchive-2.8.0/doc/wiki/ManPageArchiveEntry3.wiki b/libarchive/libarchive-2.8.0/doc/wiki/ManPageArchiveEntry3.wiki deleted file mode 100644 index d4109a8..0000000 --- a/libarchive/libarchive-2.8.0/doc/wiki/ManPageArchiveEntry3.wiki +++ /dev/null @@ -1,504 +0,0 @@ -#summary archive_entry 3 manual page -== 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*, -*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_link*, -*archive_entry_copy_link_w*, -*archive_entry_copy_pathname_w*, -*archive_entry_copy_sourcepath*, -*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_sourcepath*, -*archive_entry_stat*, -*archive_entry_symlink*, -*archive_entry_uid*, -*archive_entry_uname* -- functions for manipulating archive entry descriptions -== SYNOPSIS == -*#include <archive_entry.h>* -<br> -*void* -<br> -*archive_entry_acl_add_entry*(_struct archive_entry `*`_, _int type_, _int permset_, _int tag_, _int qual_, _const char `*`name_); -<br> -*void* -<br> -*archive_entry_acl_add_entry_w*(_struct archive_entry `*`_, _int type_, _int permset_, _int tag_, _int qual_, _const wchar_t `*`name_); -<br> -*void* -<br> -*archive_entry_acl_clear*(_struct archive_entry `*`_); -<br> -*int* -<br> -*archive_entry_acl_count*(_struct archive_entry `*`_, _int type_); -<br> -*int* -<br> -*archive_entry_acl_next*(_struct archive_entry `*`_, _int want_type_, _int `*`type_, _int `*`permset_, _int `*`tag_, _int `*`qual_, _const char `*``*`name_); -<br> -*int* -<br> -*archive_entry_acl_next_w*(_struct archive_entry `*`_, _int want_type_, _int `*`type_, _int `*`permset_, _int `*`tag_, _int `*`qual_, _const wchar_t `*``*`name_); -<br> -*int* -<br> -*archive_entry_acl_reset*(_struct archive_entry `*`_, _int want_type_); -<br> -*const wchar_t `*`* -<br> -*archive_entry_acl_text_w*(_struct archive_entry `*`_, _int flags_); -<br> -*time_t* -<br> -*archive_entry_atime*(_struct archive_entry `*`_); -<br> -*long* -<br> -*archive_entry_atime_nsec*(_struct archive_entry `*`_); -<br> -*struct archive_entry `*`* -<br> -*archive_entry_clear*(_struct archive_entry `*`_); -<br> -*struct archive_entry `*`* -<br> -*archive_entry_clone*(_struct archive_entry `*`_); -<br> -*const char `*` `*`* -<br> -*archive_entry_copy_fflags_text_w*(_struct archive_entry `*`_, _const char `*`_); -<br> -*const wchar_t `*`* -<br> -*archive_entry_copy_fflags_text_w*(_struct archive_entry `*`_, _const wchar_t `*`_); -<br> -*void* -<br> -*archive_entry_copy_gname*(_struct archive_entry `*`_, _const char `*`_); -<br> -*void* -<br> -*archive_entry_copy_gname_w*(_struct archive_entry `*`_, _const wchar_t `*`_); -<br> -*void* -<br> -*archive_entry_copy_hardlink*(_struct archive_entry `*`_, _const char `*`_); -<br> -*void* -<br> -*archive_entry_copy_hardlink_w*(_struct archive_entry `*`_, _const wchar_t `*`_); -<br> -*void* -<br> -*archive_entry_copy_sourcepath*(_struct archive_entry `*`_, _const char `*`_); -<br> -*void* -<br> -*archive_entry_copy_pathname_w*(_struct archive_entry `*`_, _const wchar_t `*`_); -<br> -*void* -<br> -*archive_entry_copy_stat*(_struct archive_entry `*`_, _const struct stat `*`_); -<br> -*void* -<br> -*archive_entry_copy_symlink*(_struct archive_entry `*`_, _const char `*`_); -<br> -*void* -<br> -*archive_entry_copy_symlink_w*(_struct archive_entry `*`_, _const wchar_t `*`_); -<br> -*void* -<br> -*archive_entry_copy_uname*(_struct archive_entry `*`_, _const char `*`_); -<br> -*void* -<br> -*archive_entry_copy_uname_w*(_struct archive_entry `*`_, _const wchar_t `*`_); -<br> -*dev_t* -<br> -*archive_entry_dev*(_struct archive_entry `*`_); -<br> -*dev_t* -<br> -*archive_entry_devmajor*(_struct archive_entry `*`_); -<br> -*dev_t* -<br> -*archive_entry_devminor*(_struct archive_entry `*`_); -<br> -*mode_t* -<br> -*archive_entry_filetype*(_struct archive_entry `*`_); -<br> -*void* -<br> -*archive_entry_fflags*(_struct archive_entry `*`_, _unsigned long `*`set_, _unsigned long `*`clear_); -<br> -*const char `*`* -<br> -*archive_entry_fflags_text*(_struct archive_entry `*`_); -<br> -*void* -<br> -*archive_entry_free*(_struct archive_entry `*`_); -<br> -*const char `*`* -<br> -*archive_entry_gname*(_struct archive_entry `*`_); -<br> -*const char `*`* -<br> -*archive_entry_hardlink*(_struct archive_entry `*`_); -<br> -*ino_t* -<br> -*archive_entry_ino*(_struct archive_entry `*`_); -<br> -*mode_t* -<br> -*archive_entry_mode*(_struct archive_entry `*`_); -<br> -*time_t* -<br> -*archive_entry_mtime*(_struct archive_entry `*`_); -<br> -*long* -<br> -*archive_entry_mtime_nsec*(_struct archive_entry `*`_); -<br> -*unsigned int* -<br> -*archive_entry_nlink*(_struct archive_entry `*`_); -<br> -*struct archive_entry `*`* -<br> -*archive_entry_new*(_void_); -<br> -*const char `*`* -<br> -*archive_entry_pathname*(_struct archive_entry `*`_); -<br> -*const wchar_t `*`* -<br> -*archive_entry_pathname_w*(_struct archive_entry `*`_); -<br> -*dev_t* -<br> -*archive_entry_rdev*(_struct archive_entry `*`_); -<br> -*dev_t* -<br> -*archive_entry_rdevmajor*(_struct archive_entry `*`_); -<br> -*dev_t* -<br> -*archive_entry_rdevminor*(_struct archive_entry `*`_); -<br> -*void* -<br> -*archive_entry_set_dev*(_struct archive_entry `*`_, _dev_t_); -<br> -*void* -<br> -*archive_entry_set_devmajor*(_struct archive_entry `*`_, _dev_t_); -<br> -*void* -<br> -*archive_entry_set_devminor*(_struct archive_entry `*`_, _dev_t_); -<br> -*void* -<br> -*archive_entry_set_filetype*(_struct archive_entry `*`_, _unsigned int_); -<br> -*void* -<br> -*archive_entry_set_fflags*(_struct archive_entry `*`_, _unsigned long set_, _unsigned long clear_); -<br> -*void* -<br> -*archive_entry_set_gid*(_struct archive_entry `*`_, _gid_t_); -<br> -*void* -<br> -*archive_entry_set_gname*(_struct archive_entry `*`_, _const char `*`_); -<br> -*void* -<br> -*archive_entry_set_hardlink*(_struct archive_entry `*`_, _const char `*`_); -<br> -*void* -<br> -*archive_entry_set_ino*(_struct archive_entry `*`_, _unsigned long_); -<br> -*void* -<br> -*archive_entry_set_link*(_struct archive_entry `*`_, _const char `*`_); -<br> -*void* -<br> -*archive_entry_set_mode*(_struct archive_entry `*`_, _mode_t_); -<br> -*void* -<br> -*archive_entry_set_mtime*(_struct archive_entry `*`_, _time_t_, _long nanos_); -<br> -*void* -<br> -*archive_entry_set_nlink*(_struct archive_entry `*`_, _unsigned int_); -<br> -*void* -<br> -*archive_entry_set_pathname*(_struct archive_entry `*`_, _const char `*`_); -<br> -*void* -<br> -*archive_entry_set_rdev*(_struct archive_entry `*`_, _dev_t_); -<br> -*void* -<br> -*archive_entry_set_rdevmajor*(_struct archive_entry `*`_, _dev_t_); -<br> -*void* -<br> -*archive_entry_set_rdevminor*(_struct archive_entry `*`_, _dev_t_); -<br> -*void* -<br> -*archive_entry_set_size*(_struct archive_entry `*`_, _int64_t_); -<br> -*void* -<br> -*archive_entry_set_symlink*(_struct archive_entry `*`_, _const char `*`_); -<br> -*void* -<br> -*archive_entry_set_uid*(_struct archive_entry `*`_, _uid_t_); -<br> -*void* -<br> -*archive_entry_set_uname*(_struct archive_entry `*`_, _const char `*`_); -<br> -*int64_t* -<br> -*archive_entry_size*(_struct archive_entry `*`_); -<br> -*const char `*`* -<br> -*archive_entry_sourcepath*(_struct archive_entry `*`_); -<br> -*const struct stat `*`* -<br> -*archive_entry_stat*(_struct archive_entry `*`_); -<br> -*const char `*`* -<br> -*archive_entry_symlink*(_struct archive_entry `*`_); -<br> -*const char `*`* -<br> -*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: -<dl> -<dt>*archive_entry_clear*()</dt><dd> -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. -</dd><dt>*archive_entry_clone*()</dt><dd> -A deep copy operation; all text fields are duplicated. -</dd><dt>*archive_entry_free*()</dt><dd> -Releases the -*struct archive_entry* -object. -</dd><dt>*archive_entry_new*()</dt><dd> -Allocate and return a blank -*struct archive_entry* -object. -</dd></dl> -=== Set and Get Functions=== -Most of the functions here set or read entries in an object. -Such functions have one of the following forms: -<dl> -<dt>*archive_entry_set_XXXX*()</dt><dd> -Stores the provided data in the object. -In particular, for strings, the pointer is stored, -not the referenced string. -</dd><dt>*archive_entry_copy_XXXX*()</dt><dd> -As above, except that the referenced data is copied -into the object. -</dd><dt>*archive_entry_XXXX*()</dt><dd> -Returns the specified data. -In the case of strings, a const-qualified pointer to -the string is returned. -</dd></dl> -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 discarded in favor of the new data. - -There are a few set/get functions that merit additional description: -<dl> -<dt>*archive_entry_set_link*()</dt><dd> -This function sets the symlink field if it is already set. -Otherwise, it sets the hardlink field. -</dd></dl> -=== 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 -*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*() -and -*archive_entry_copy_fflags_text_w*() -functions parse the provided text and sets the internal bitmap values. -This is a platform-specific operation; names that are not meaningful -on the current platform will be ignored. -The function returns a pointer to the start of the first name that was not -recognized, or NULL if every name was recognized. -Note that every name--including names that follow an unrecognized name--will -be evaluated, and the bitmaps will be set to reflect every name that is -recognized. -(In particular, this differs from -*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 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 -== SEE ALSO == -*archive*(3) -== HISTORY == -The -*libarchive* -library first appeared in -FreeBSD 5.3. -== AUTHORS == -The -*libarchive* -library was written by -Tim Kientzle <kientzle@acm.org.> diff --git a/libarchive/libarchive-2.8.0/doc/wiki/ManPageArchiveRead3.wiki b/libarchive/libarchive-2.8.0/doc/wiki/ManPageArchiveRead3.wiki deleted file mode 100644 index 9d3f62c..0000000 --- a/libarchive/libarchive-2.8.0/doc/wiki/ManPageArchiveRead3.wiki +++ /dev/null @@ -1,694 +0,0 @@ -#summary archive_read 3 manual page -== NAME == -*archive_read_new*, -*archive_read_set_filter_options*, -*archive_read_set_format_options*, -*archive_read_set_options*, -*archive_read_support_compression_all*, -*archive_read_support_compression_bzip2*, -*archive_read_support_compression_compress*, -*archive_read_support_compression_gzip*, -*archive_read_support_compression_lzma*, -*archive_read_support_compression_none*, -*archive_read_support_compression_xz*, -*archive_read_support_compression_program*, -*archive_read_support_compression_program_signature*, -*archive_read_support_format_all*, -*archive_read_support_format_ar*, -*archive_read_support_format_cpio*, -*archive_read_support_format_empty*, -*archive_read_support_format_iso9660*, -*archive_read_support_format_mtree,* -*archive_read_support_format_raw,* -*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_next_header2*, -*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_extract2*, -*archive_read_extract_set_progress_callback*, -*archive_read_close*, -*archive_read_finish* -- functions for reading streaming archives -== SYNOPSIS == -*#include <archive.h>* -<br> -*struct archive `*`* -<br> -*archive_read_new*(_void_); -<br> -*int* -<br> -*archive_read_support_compression_all*(_struct archive `*`_); -<br> -*int* -<br> -*archive_read_support_compression_bzip2*(_struct archive `*`_); -<br> -*int* -<br> -*archive_read_support_compression_compress*(_struct archive `*`_); -<br> -*int* -<br> -*archive_read_support_compression_gzip*(_struct archive `*`_); -<br> -*int* -<br> -*archive_read_support_compression_lzma*(_struct archive `*`_); -<br> -*int* -<br> -*archive_read_support_compression_none*(_struct archive `*`_); -<br> -*int* -<br> -*archive_read_support_compression_xz*(_struct archive `*`_); -<br> -*int* -<br> -*archive_read_support_compression_program*(_struct archive `*`_, _const char `*`cmd_); -<br> -*int* -<br> -*archive_read_support_compression_program_signature*(_struct archive `*`_, _const char `*`cmd_, _const void `*`signature_, _size_t signature_length_); -<br> -*int* -<br> -*archive_read_support_format_all*(_struct archive `*`_); -<br> -*int* -<br> -*archive_read_support_format_ar*(_struct archive `*`_); -<br> -*int* -<br> -*archive_read_support_format_cpio*(_struct archive `*`_); -<br> -*int* -<br> -*archive_read_support_format_empty*(_struct archive `*`_); -<br> -*int* -<br> -*archive_read_support_format_iso9660*(_struct archive `*`_); -<br> -*int* -<br> -*archive_read_support_format_mtree*(_struct archive `*`_); -<br> -*int* -<br> -*archive_read_support_format_raw*(_struct archive `*`_); -<br> -*int* -<br> -*archive_read_support_format_tar*(_struct archive `*`_); -<br> -*int* -<br> -*archive_read_support_format_zip*(_struct archive `*`_); -<br> -*int* -<br> -*archive_read_set_filter_options*(_struct archive `*`_, _const char `*`_); -<br> -*int* -<br> -*archive_read_set_format_options*(_struct archive `*`_, _const char `*`_); -<br> -*int* -<br> -*archive_read_set_options*(_struct archive `*`_, _const char `*`_); -<br> -*int* -<br> -*archive_read_open*(_struct archive `*`_, _void `*`client_data_, _archive_open_callback `*`_, _archive_read_callback `*`_, _archive_close_callback `*`_); -<br> -*int* -<br> -*archive_read_open2*(_struct archive `*`_, _void `*`client_data_, _archive_open_callback `*`_, _archive_read_callback `*`_, _archive_skip_callback `*`_, _archive_close_callback `*`_); -<br> -*int* -<br> -*archive_read_open_FILE*(_struct archive `*`_, _FILE `*`file_); -<br> -*int* -<br> -*archive_read_open_fd*(_struct archive `*`_, _int fd_, _size_t block_size_); -<br> -*int* -<br> -*archive_read_open_filename*(_struct archive `*`_, _const char `*`filename_, _size_t block_size_); -<br> -*int* -<br> -*archive_read_open_memory*(_struct archive `*`_, _void `*`buff_, _size_t size_); -<br> -*int* -<br> -*archive_read_next_header*(_struct archive `*`_, _struct archive_entry `*``*`_); -<br> -*int* -<br> -*archive_read_next_header2*(_struct archive `*`_, _struct archive_entry `*`_); -<br> -*ssize_t* -<br> -*archive_read_data*(_struct archive `*`_, _void `*`buff_, _size_t len_); -<br> -*int* -<br> -*archive_read_data_block*(_struct archive `*`_, _const void `*``*`buff_, _size_t `*`len_, _off_t `*`offset_); -<br> -*int* -<br> -*archive_read_data_skip*(_struct archive `*`_); -<br> -*int* -<br> -*archive_read_data_into_buffer*(_struct archive `*`_, _void `*`_, _ssize_t len_); -<br> -*int* -<br> -*archive_read_data_into_fd*(_struct archive `*`_, _int fd_); -<br> -*int* -<br> -*archive_read_extract*(_struct archive `*`_, _struct archive_entry `*`_, _int flags_); -<br> -*int* -<br> -*archive_read_extract2*(_struct archive `*`src_, _struct archive_entry `*`_, _struct archive `*`dest_); -<br> -*void* -<br> -*archive_read_extract_set_progress_callback*(_struct archive `*`_, _void (`*`func)(void `*`)_, _void `*`user_data_); -<br> -*int* -<br> -*archive_read_close*(_struct archive `*`_); -<br> -*int* -<br> -*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: -<dl> -<dt>*archive_read_new*()</dt><dd> -Allocates and initializes a -*struct archive* -object suitable for reading from an archive. -</dd><dt> -*archive_read_support_compression_bzip2*(), -*archive_read_support_compression_compress*(), -*archive_read_support_compression_gzip*(), -*archive_read_support_compression_lzma*(), -*archive_read_support_compression_none*(), -*archive_read_support_compression_xz*() -</dt> <dd> -Enables auto-detection code and decompression support for the -specified compression. -Returns -*ARCHIVE_OK* -if the compression is fully supported, or -*ARCHIVE_WARN* -if the compression is supported only through an external program. -Note that decompression using an external program is usually slower than -decompression through built-in libraries. -Note that -"none" -is always enabled by default. -</dd><dt>*archive_read_support_compression_all*()</dt><dd> -Enables all available decompression filters. -</dd><dt>*archive_read_support_compression_program*()</dt><dd> -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. -</dd><dt>*archive_read_support_compression_program_signature*()</dt><dd> -This feeds data through the specified external program -but only if the initial bytes of the data match the specified -signature value. -</dd><dt> -*archive_read_support_format_all*(), -*archive_read_support_format_ar*(), -*archive_read_support_format_cpio*(), -*archive_read_support_format_empty*(), -*archive_read_support_format_iso9660*(), -*archive_read_support_format_mtree*(), -*archive_read_support_format_tar*(), -*archive_read_support_format_zip*() -</dt> <dd> -Enables support---including auto-detection code---for the -specified 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 available formats. -Only empty archives are supported by default. -</dd><dt>*archive_read_support_format_raw*()</dt><dd> -The -"raw" -format handler allows libarchive to be used to read arbitrary data. -It treats any data stream as an archive with a single entry. -The pathname of this entry is -"data ;" -all other entry fields are unset. -This is not enabled by -*archive_read_support_format_all*() -in order to avoid erroneous handling of damaged archives. -</dd><dt> -*archive_read_set_filter_options*(), -*archive_read_set_format_options*(), -*archive_read_set_options*() -</dt> <dd> -Specifies options that will be passed to currently-registered -filters (including decompression filters) and/or format readers. -The argument is a comma-separated list of individual options. -Individual options have one of the following forms: -<dl> -<dt>_option=value_</dt><dd> -The option/value pair will be provided to every module. -Modules that do not accept an option with this name will ignore it. -</dd><dt>_option_</dt><dd> -The option will be provided to every module with a value of -"1". -</dd><dt>_!option_</dt><dd> -The option will be provided to every module with a NULL value. -</dd><dt>_module:option=value_, _module:option_, _module:!option_</dt><dd> -As above, but the corresponding option and value will be provided -only to modules whose name matches -_module_. -</dd></dl> -The return value will be -*ARCHIVE_OK* -if any module accepts the option, or -*ARCHIVE_WARN* -if no module accepted the option, or -*ARCHIVE_FATAL* -if there was a fatal error while attempting to process the option. - -The currently supported options are: -<dl> -<dt>Format iso9660</dt><dd> -<dl> -<dt>*joliet*</dt><dd> -Support Joliet extensions. -Defaults to enabled, use -*!joliet* -to disable. -</dd></dl> -</dd></dl> -</dd><dt>*archive_read_open*()</dt><dd> -The same as -*archive_read_open2*(), -except that the skip callback is assumed to be -NULL. -</dd><dt>*archive_read_open2*()</dt><dd> -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. -</dd><dt>*archive_read_open_FILE*()</dt><dd> -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. -</dd><dt>*archive_read_open_fd*()</dt><dd> -Like -*archive_read_open*(), -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. -</dd><dt>*archive_read_open_file*()</dt><dd> -This is a deprecated synonym for -*archive_read_open_filename*(). -</dd><dt>*archive_read_open_filename*()</dt><dd> -Like -*archive_read_open*(), -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. -</dd><dt>*archive_read_open_memory*()</dt><dd> -Like -*archive_read_open*(), -except that it accepts a pointer and size of a block of -memory containing the archive data. -</dd><dt>*archive_read_next_header*()</dt><dd> -Read the header for the next entry and return a pointer to -a -*struct archive_entry .* -This is a convenience wrapper around -*archive_read_next_header2*() -that reuses an internal -*struct archive_entry* -object for each request. -</dd><dt>*archive_read_next_header2*()</dt><dd> -Read the header for the next entry and populate the provided -*struct archive_entry .* -</dd><dt>*archive_read_data*()</dt><dd> -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 -continuous stream of data. -</dd><dt>*archive_read_data_block*()</dt><dd> -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 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. -</dd><dt>*archive_read_data_skip*()</dt><dd> -A convenience function that repeatedly calls -*archive_read_data_block*() -to skip all of the data for this archive entry. -</dd><dt>*archive_read_data_into_buffer*()</dt><dd> -This function is deprecated and will be removed. -Use -*archive_read_data*() -instead. -</dd><dt>*archive_read_data_into_fd*()</dt><dd> -A convenience function that repeatedly calls -*archive_read_data_block*() -to copy the entire entry to the provided file descriptor. -</dd><dt>*archive_read_extract*(), *archive_read_extract_set_skip_file*()</dt><dd> -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). -</dd><dt>*archive_read_extract2*()</dt><dd> -This is another version of -*archive_read_extract*() -that allows you to provide your own restore object. -In particular, this allows you to override the standard lookup functions -using -*archive_write_disk_set_group_lookup*(3), -and -*archive_write_disk_set_user_lookup*(3). -Note that -*archive_read_extract2*() -does not accept a -_flags_ -argument; you should use -*archive_write_disk_set_options*() -to set the restore options yourself. -</dd><dt>*archive_read_extract_set_progress_callback*()</dt><dd> -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. -</dd><dt>*archive_read_close*()</dt><dd> -Complete the archive and invoke the close callback. -</dd><dt>*archive_read_finish*()</dt><dd> -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. -</dd></dl> - -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 appropriate 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: -<ul> -<li> -*typedef ssize_t* -*archive_read_callback*(_struct archive `*`_, _void `*`client_data_, _const void `*``*`buffer_) -</li><li> -*typedef int* -*archive_skip_callback*(_struct archive `*`_, _void `*`client_data_, _size_t request_) -</li><li> -*typedef int* -*archive_open_callback*(_struct archive `*`_, _void `*`client_data_) -</li><li> -*typedef int* -*archive_close_callback*(_struct archive `*`_, _void `*`client_data_) -</li></ul> - -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 processing 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 operation 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*() -functions. - -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 eventually 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 <kientzle@acm.org.> -== BUGS == -Many traditional archiver programs treat -empty files as valid empty archives. -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. diff --git a/libarchive/libarchive-2.8.0/doc/wiki/ManPageArchiveReadDisk3.wiki b/libarchive/libarchive-2.8.0/doc/wiki/ManPageArchiveReadDisk3.wiki deleted file mode 100644 index 4135470..0000000 --- a/libarchive/libarchive-2.8.0/doc/wiki/ManPageArchiveReadDisk3.wiki +++ /dev/null @@ -1,287 +0,0 @@ -#summary archive_read_disk 3 manual page -== NAME == -*archive_read_disk_new*, -*archive_read_disk_set_symlink_logical*, -*archive_read_disk_set_symlink_physical*, -*archive_read_disk_set_symlink_hybrid*, -*archive_read_disk_entry_from_file*, -*archive_read_disk_gname*, -*archive_read_disk_uname*, -*archive_read_disk_set_uname_lookup*, -*archive_read_disk_set_gname_lookup*, -*archive_read_disk_set_standard_lookup*, -*archive_read_close*, -*archive_read_finish* -- functions for reading objects from disk -== SYNOPSIS == -*#include <archive.h>* -<br> -*struct archive `*`* -<br> -*archive_read_disk_new*(_void_); -<br> -*int* -<br> -*archive_read_disk_set_symlink_logical*(_struct archive `*`_); -<br> -*int* -<br> -*archive_read_disk_set_symlink_physical*(_struct archive `*`_); -<br> -*int* -<br> -*archive_read_disk_set_symlink_hybrid*(_struct archive `*`_); -<br> -*int* -<br> -*archive_read_disk_gname*(_struct archive `*`_, _gid_t_); -<br> -*int* -<br> -*archive_read_disk_uname*(_struct archive `*`_, _uid_t_); -<br> -*int* -<br> -*archive_read_disk_set_gname_lookup*(_struct archive `*`_, _void `*`_, _const char `*`(`*`lookup)(void `*`, gid_t)_, _void (`*`cleanup)(void `*`)_); -<br> -*int* -<br> -*archive_read_disk_set_uname_lookup*(_struct archive `*`_, _void `*`_, _const char `*`(`*`lookup)(void `*`, uid_t)_, _void (`*`cleanup)(void `*`)_); -<br> -*int* -<br> -*archive_read_disk_set_standard_lookup*(_struct archive `*`_); -<br> -*int* -<br> -*archive_read_disk_entry_from_file*(_struct archive `*`_, _struct archive_entry `*`_, _int fd_, _const struct stat `*`_); -<br> -*int* -<br> -*archive_read_close*(_struct archive `*`_); -<br> -*int* -<br> -*archive_read_finish*(_struct archive `*`_); -== DESCRIPTION == -These functions provide an API for reading information about -objects on disk. -In particular, they provide an interface for populating -*struct archive_entry* -objects. -<dl> -<dt>*archive_read_disk_new*()</dt><dd> -Allocates and initializes a -*struct archive* -object suitable for reading object information from disk. -</dd><dt> -*archive_read_disk_set_symlink_logical*(), -*archive_read_disk_set_symlink_physical*(), -*archive_read_disk_set_symlink_hybrid*() -</dt> <dd> -This sets the mode used for handling symbolic links. -The -"logical" -mode follows all symbolic links. -The -"physical" -mode does not follow any symbolic links. -The -"hybrid" -mode currently behaves identically to the -"logical" -mode. -</dd><dt> -*archive_read_disk_gname*(), -*archive_read_disk_uname*() -</dt> <dd> -Returns a user or group name given a gid or uid value. -By default, these always return a NULL string. -</dd><dt> -*archive_read_disk_set_gname_lookup*(), -*archive_read_disk_set_uname_lookup*() -</dt> <dd> -These allow you to override the functions used for -user and group name lookups. -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 or when new lookup functions are registered. -</dd><dt>*archive_read_disk_set_standard_lookup*()</dt><dd> -This convenience function installs a standard set of user -and group name lookup functions. -These functions use -*getpwid*(3) -and -*getgrid*(3) -to convert ids to names, defaulting to NULL if the names cannot -be looked up. -These functions also implement a simple memory cache to reduce -the number of calls to -*getpwid*(3) -and -*getgrid*(3). -</dd><dt>*archive_read_disk_entry_from_file*()</dt><dd> -Populates a -*struct archive_entry* -object with information about a particular file. -The -*archive_entry* -object must have already been created with -*archive_entry_new*(3) -and at least one of the source path or path fields must already be set. -(If both are set, the source path will be used.) - -Information is read from disk using the path name from the -*struct archive_entry* -object. -If a file descriptor is provided, some information will be obtained using -that file descriptor, on platforms that support the appropriate -system calls. - -If a pointer to a -*struct stat* -is provided, information from that structure will be used instead -of reading from the disk where appropriate. -This can provide performance benefits in scenarios where -*struct stat* -information has already been read from the disk as a side effect -of some other operation. -(For example, directory traversal libraries often provide this information.) - -Where necessary, user and group ids are converted to user and group names -using the currently registered lookup functions above. -This affects the file ownership fields and ACL values in the -*struct archive_entry* -object. -</dd><dt>*archive_read_close*()</dt><dd> -This currently does nothing. -</dd><dt>*archive_write_finish*()</dt><dd> -Invokes -*archive_write_close*() -if it was not invoked manually, then releases all resources. -</dd></dl> -More information about the -_struct_ archive -object and the overall design of the library can be found in the -*libarchive*(3) -overview. -== EXAMPLE == -The following illustrates basic usage of the library by -showing how to use it to copy an item on disk into an archive. -{{{ -void -file_to_archive(struct archive *a, const char *name) -{ - char buff[8192]; - size_t bytes_read; - struct archive *ard; - struct archive_entry *entry; - int fd; - ard = archive_read_disk_new(); - archive_read_disk_set_standard_lookup(ard); - entry = archive_entry_new(); - fd = open(name, O_RDONLY); - if (fd < 0) - return; - archive_entry_copy_sourcepath(entry, name); - archive_read_disk_entry_from_file(ard, entry, fd, NULL); - archive_write_header(a, entry); - while ((bytes_read = read(fd, buff, sizeof(buff))) > 0) - archive_write_data(a, buff, bytes_read); - archive_write_finish_entry(a); - archive_read_finish(ard); - archive_entry_free(entry); -} -}}} -== RETURN VALUES == -Most functions return -*ARCHIVE_OK* -(zero) on success, or one of several negative -error codes for errors. -Specific error codes include: -*ARCHIVE_RETRY* -for operations that might succeed if retried, -*ARCHIVE_WARN* -for unusual conditions that do not prevent further operations, and -*ARCHIVE_FATAL* -for serious errors that make remaining operations impossible. -The -*archive_errno*(3) -and -*archive_error_string*(3) -functions can be used to retrieve an appropriate error code and a -textual error message. -(See -*archive_util*(3) -for details.) - -*archive_read_disk_new*() -returns a pointer to a newly-allocated -*struct archive* -object or NULL if the allocation failed for any reason. - -*archive_read_disk_gname*() -and -*archive_read_disk_uname*() -return -*const char `*`* -pointers to the textual name or NULL if the lookup failed for any reason. -The returned pointer points to internal storage that -may be reused on the next call to either of these functions; -callers should copy the string if they need to continue accessing it. - -== SEE ALSO == -*archive_read*(3), -*archive_write*(3), -*archive_write_disk*(3), -*tar*(1), -*libarchive*(3) -== HISTORY == -The -*libarchive* -library first appeared in -FreeBSD 5.3. -The -*archive_read_disk* -interface was added to -*libarchive* 2.6 -and first appeared in -FreeBSD 8.0. -== AUTHORS == -The -*libarchive* -library was written by -Tim Kientzle <kientzle@freebsd.org.> -== BUGS == -The -"standard" -user name and group name lookup functions are not the defaults because -*getgrid*(3) -and -*getpwid*(3) -are sometimes too large for particular applications. -The current design allows the application author to use a more -compact implementation when appropriate. - -The full list of metadata read from disk by -*archive_read_disk_entry_from_file*() -is necessarily system-dependent. - -The -*archive_read_disk_entry_from_file*() -function reads as much information as it can from disk. -Some method should be provided to limit this so that clients who -do not need ACLs, for instance, can avoid the extra work needed -to look up such information. - -This API should provide a set of methods for walking a directory tree. -That would make it a direct parallel of the -*archive_read*(3) -API. -When such methods are implemented, the -"hybrid" -symbolic link mode will make sense. diff --git a/libarchive/libarchive-2.8.0/doc/wiki/ManPageArchiveUtil3.wiki b/libarchive/libarchive-2.8.0/doc/wiki/ManPageArchiveUtil3.wiki deleted file mode 100644 index e33b007..0000000 --- a/libarchive/libarchive-2.8.0/doc/wiki/ManPageArchiveUtil3.wiki +++ /dev/null @@ -1,146 +0,0 @@ -#summary archive_util 3 manual page -== NAME == -*archive_clear_error*, -*archive_compression*, -*archive_compression_name*, -*archive_copy_error*, -*archive_errno*, -*archive_error_string*, -*archive_file_count*, -*archive_format*, -*archive_format_name*, -*archive_set_error* -- libarchive utility functions -== SYNOPSIS == -*#include <archive.h>* -<br> -*void* -<br> -*archive_clear_error*(_struct archive `*`_); -<br> -*int* -<br> -*archive_compression*(_struct archive `*`_); -<br> -*const char `*`* -<br> -*archive_compression_name*(_struct archive `*`_); -<br> -*void* -<br> -*archive_copy_error*(_struct archive `*`_, _struct archive `*`_); -<br> -*int* -<br> -*archive_errno*(_struct archive `*`_); -<br> -*const char `*`* -<br> -*archive_error_string*(_struct archive `*`_); -<br> -*int* -<br> -*archive_file_count*(_struct archive `*`_); -<br> -*int* -<br> -*archive_format*(_struct archive `*`_); -<br> -*const char `*`* -<br> -*archive_format_name*(_struct archive `*`_); -<br> -*void* -<br> -*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. -<dl> -<dt>*archive_clear_error*()</dt><dd> -Clears any error information left over from a previous call. -Not generally used in client code. -</dd><dt>*archive_compression*()</dt><dd> -Returns a numeric code indicating the current compression. -This value is set by -*archive_read_open*(). -</dd><dt>*archive_compression_name*()</dt><dd> -Returns a text description of the current compression suitable for display. -</dd><dt>*archive_copy_error*()</dt><dd> -Copies error information from one archive to another. -</dd><dt>*archive_errno*()</dt><dd> -Returns a numeric error code (see -*errno*(2)) -indicating the reason for the most recent error return. -</dd><dt>*archive_error_string*()</dt><dd> -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). -</dd><dt>*archive_file_count*()</dt><dd> -Returns a count of the number of files processed by this archive object. -The count is incremented by calls to -*archive_write_header*() -or -*archive_read_next_header*(.) -</dd><dt>*archive_format*()</dt><dd> -Returns a numeric code indicating the format of the current -archive 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. -</dd><dt>*archive_format_name*()</dt><dd> -A textual description of the format of the current entry. -</dd><dt>*archive_set_error*()</dt><dd> -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-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. -</dd></dl> -== 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 <kientzle@acm.org.> diff --git a/libarchive/libarchive-2.8.0/doc/wiki/ManPageArchiveWrite3.wiki b/libarchive/libarchive-2.8.0/doc/wiki/ManPageArchiveWrite3.wiki deleted file mode 100644 index 30ccd8f..0000000 --- a/libarchive/libarchive-2.8.0/doc/wiki/ManPageArchiveWrite3.wiki +++ /dev/null @@ -1,630 +0,0 @@ -#summary archive_write 3 manual page -== 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_compress*, -*archive_write_set_compression_gzip*, -*archive_write_set_compression_none*, -*archive_write_set_compression_program*, -*archive_write_set_compressor_options*, -*archive_write_set_format_options*, -*archive_write_set_options*, -*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 archives -== SYNOPSIS == -*#include <archive.h>* -<br> -*struct archive `*`* -<br> -*archive_write_new*(_void_); -<br> -*int* -<br> -*archive_write_get_bytes_per_block*(_struct archive `*`_); -<br> -*int* -<br> -*archive_write_set_bytes_per_block*(_struct archive `*`_, _int bytes_per_block_); -<br> -*int* -<br> -*archive_write_set_bytes_in_last_block*(_struct archive `*`_, _int_); -<br> -*int* -<br> -*archive_write_set_compression_bzip2*(_struct archive `*`_); -<br> -*int* -<br> -*archive_write_set_compression_compress*(_struct archive `*`_); -<br> -*int* -<br> -*archive_write_set_compression_gzip*(_struct archive `*`_); -<br> -*int* -<br> -*archive_write_set_compression_none*(_struct archive `*`_); -<br> -*int* -<br> -*archive_write_set_compression_program*(_struct archive `*`_, _const char `*` cmd_); -<br> -*int* -<br> -*archive_write_set_format_cpio*(_struct archive `*`_); -<br> -*int* -<br> -*archive_write_set_format_pax*(_struct archive `*`_); -<br> -*int* -<br> -*archive_write_set_format_pax_restricted*(_struct archive `*`_); -<br> -*int* -<br> -*archive_write_set_format_shar*(_struct archive `*`_); -<br> -*int* -<br> -*archive_write_set_format_shar_binary*(_struct archive `*`_); -<br> -*int* -<br> -*archive_write_set_format_ustar*(_struct archive `*`_); -<br> -*int* -<br> -*archive_write_set_format_options*(_struct archive `*`_, _const char `*`_); -<br> -*int* -<br> -*archive_write_set_compressor_options*(_struct archive `*`_, _const char `*`_); -<br> -*int* -<br> -*archive_write_set_options*(_struct archive `*`_, _const char `*`_); -<br> -*int* -<br> -*archive_write_open*(_struct archive `*`_, _void `*`client_data_, _archive_open_callback `*`_, _archive_write_callback `*`_, _archive_close_callback `*`_); -<br> -*int* -<br> -*archive_write_open_fd*(_struct archive `*`_, _int fd_); -<br> -*int* -<br> -*archive_write_open_FILE*(_struct archive `*`_, _FILE `*`file_); -<br> -*int* -<br> -*archive_write_open_filename*(_struct archive `*`_, _const char `*`filename_); -<br> -*int* -<br> -*archive_write_open_memory*(_struct archive `*`_, _void `*`buffer_, _size_t bufferSize_, _size_t `*`outUsed_); -<br> -*int* -<br> -*archive_write_header*(_struct archive `*`_, _struct archive_entry `*`_); -<br> -*ssize_t* -<br> -*archive_write_data*(_struct archive `*`_, _const void `*`_, _size_t_); -<br> -*int* -<br> -*archive_write_finish_entry*(_struct archive `*`_); -<br> -*int* -<br> -*archive_write_close*(_struct archive `*`_); -<br> -*int* -<br> -*archive_write_finish*(_struct archive `*`_); -== DESCRIPTION == -These functions provide a complete API for creating 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: -<dl> -<dt>*archive_write_new*()</dt><dd> -Allocates and initializes a -*struct archive* -object suitable for writing a tar archive. -</dd><dt>*archive_write_set_bytes_per_block*()</dt><dd> -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. -</dd><dt>*archive_write_get_bytes_per_block*()</dt><dd> -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. -</dd><dt>*archive_write_set_bytes_in_last_block*()</dt><dd> -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 -*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. -</dd><dt>*archive_write_get_bytes_in_last_block*()</dt><dd> -Retrieve the currently-set value for last block size. -A value of -1 here indicates that the library should use default values. -</dd><dt> -*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*() -</dt> <dd> -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. -</dd><dt> -*archive_write_set_compression_bzip2*(), -*archive_write_set_compression_compress*(), -*archive_write_set_compression_gzip*(), -*archive_write_set_compression_none*() -</dt> <dd> -The resulting archive will be compressed as specified. -Note that the compressed output is always properly blocked. -</dd><dt>*archive_write_set_compression_program*()</dt><dd> -The archive will be fed into the specified compression program. -The output of that program is blocked and written to the client -write callbacks. -</dd><dt> -*archive_write_set_compressor_options*(), -*archive_write_set_format_options*(), -*archive_write_set_options*() -</dt> <dd> -Specifies options that will be passed to the currently-enabled -compressor and/or format writer. -The argument is a comma-separated list of individual options. -Individual options have one of the following forms: -<dl> -<dt>_option=value_</dt><dd> -The option/value pair will be provided to every module. -Modules that do not accept an option with this name will ignore it. -</dd><dt>_option_</dt><dd> -The option will be provided to every module with a value of -"1". -</dd><dt>_!option_</dt><dd> -The option will be provided to every module with a NULL value. -</dd><dt>_module:option=value_, _module:option_, _module:!option_</dt><dd> -As above, but the corresponding option and value will be provided -only to modules whose name matches -_module_. -</dd></dl> -The return value will be -*ARCHIVE_OK* -if any module accepts the option, or -*ARCHIVE_WARN* -if no module accepted the option, or -*ARCHIVE_FATAL* -if there was a fatal error while attempting to process the option. - -The currently supported options are: -<dl> -<dt>Compressor gzip</dt><dd> -<dl> -<dt>*compression-level*</dt><dd> -The value is interpreted as a decimal integer specifying the -gzip compression level. -</dd></dl> -</dd><dt>Compressor xz</dt><dd> -<dl> -<dt>*compression-level*</dt><dd> -The value is interpreted as a decimal integer specifying the -compression level. -</dd></dl> -</dd><dt>Format mtree</dt><dd> -<dl> -<dt>*cksum*, *device*, *flags*, *gid*, *gname*, *indent*, *link*, *md5*, *mode*, *nlink*, *rmd160*, *sha1*, *sha256*, *sha384*, *sha512*, *size*, *time*, *uid*, *uname*</dt><dd> -Enable a particular keyword in the mtree output. -Prefix with an exclamation mark to disable the corresponding keyword. -The default is equivalent to -"device, flags, gid, gname, link, mode, nlink, size, time, type, uid, uname". -</dd><dt>*all*</dt><dd> -Enables all of the above keywords. -</dd><dt>*use-set*</dt><dd> -Enables generation of -*/set* -lines that specify default values for the following files and/or directories. -</dd><dt>*indent*</dt><dd> -XXX needs explanation XXX -</dd></dl> -</dd></dl> -</dd><dt>*archive_write_open*()</dt><dd> -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. -</dd><dt>*archive_write_open_fd*()</dt><dd> -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. -</dd><dt>*archive_write_open_FILE*()</dt><dd> -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. -</dd><dt>*archive_write_open_file*()</dt><dd> -A deprecated synonym for -*archive_write_open_filename*(). -</dd><dt>*archive_write_open_filename*()</dt><dd> -A convenience form of -*archive_write_open*() -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 -*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. -</dd><dt>*archive_write_open_memory*()</dt><dd> -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 allocated until after the archive is -closed. -</dd><dt>*archive_write_header*()</dt><dd> -Build and write a header using the data in the provided -*struct archive_entry* -structure. -See -*archive_entry*(3) -for information on creating and populating -*struct archive_entry* -objects. -</dd><dt>*archive_write_data*()</dt><dd> -Write data corresponding to the header just written. -Returns number of bytes written or -1 on error. -</dd><dt>*archive_write_finish_entry*()</dt><dd> -Close out the entry just written. -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. -</dd><dt>*archive_write_close*()</dt><dd> -Complete the archive and invoke the close callback. -</dd><dt>*archive_write_finish*()</dt><dd> -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 impossible to detect errors when -*archive_write_close*() -was invoked implicitly from this function. -This is corrected beginning with libarchive 2.0. -</dd></dl> -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 functions that will be invoked to write data to the -resulting archive. -These functions are registered by calling -*archive_write_open*(): -<ul> -<li> -*typedef int* -*archive_open_callback*(_struct archive `*`_, _void `*`client_data_) -</li></ul> - -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*. -<ul> -<li> -*typedef ssize_t* -*archive_write_callback*(_struct archive `*`_, _void `*`client_data_, _const void `*`buffer_, _size_t length_) -</li></ul> - -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 -*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. -<ul> -<li> -*typedef int* -*archive_close_callback*(_struct archive `*`_, _void `*`client_data_) -</li></ul> - -The close callback is invoked by archive_close when -the archive processing 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. -{{{ -#ifdef __linux__ -#define _FILE_OFFSET_BITS 64 -#endif -#include <sys/stat.h> -#include <archive.h> -#include <archive_entry.h> -#include <fcntl.h> -#include <stdlib.h> -#include <unistd.h> -struct mydata { - const char *name; - int fd; -}; -int -myopen(struct archive *a, void *client_data) -{ - struct mydata *mydata = client_data; - mydata->fd = open(mydata->name, O_WRONLY | O_CREAT, 0644); - if (mydata->fd >= 0) - return (ARCHIVE_OK); - else - return (ARCHIVE_FATAL); -} -ssize_t -mywrite(struct archive *a, void *client_data, const void *buff, size_t n) -{ - struct mydata *mydata = client_data; - return (write(mydata->fd, buff, n)); -} -int -myclose(struct archive *a, void *client_data) -{ - struct mydata *mydata = client_data; - if (mydata->fd > 0) - close(mydata->fd); - return (0); -} -void -write_archive(const char *outname, const char **filename) -{ - struct mydata *mydata = malloc(sizeof(struct mydata)); - struct archive *a; - struct archive_entry *entry; - struct stat st; - char buff[8192]; - int len; - int fd; - a = archive_write_new(); - mydata->name = outname; - archive_write_set_compression_gzip(a); - archive_write_set_format_ustar(a); - archive_write_open(a, mydata, myopen, mywrite, myclose); - while (*filename) { - stat(*filename, &st); - entry = archive_entry_new(); - archive_entry_copy_stat(entry, &st); - archive_entry_set_pathname(entry, *filename); - archive_write_header(a, entry); - fd = open(*filename, O_RDONLY); - len = read(fd, buff, sizeof(buff)); - while ( len > 0 ) { - archive_write_data(a, buff, len); - len = read(fd, buff, sizeof(buff)); - } - archive_entry_free(entry); - filename++; - } - archive_write_finish(a); -} -int main(int argc, const char **argv) -{ - const char *outname; - argv++; - outname = argv++; - write_archive(outname, argv); - return 0; -} -}}} -== RETURN VALUES == -Most functions return -*ARCHIVE_OK* -(zero) on success, or one of several non-zero -error codes for errors. -Specific error codes include: -*ARCHIVE_RETRY* -for operations that might succeed if retried, -*ARCHIVE_WARN* -for unusual conditions that do not prevent further operations, and -*ARCHIVE_FATAL* -for serious errors that make remaining operations impossible. -The -*archive_errno*() -and -*archive_error_string*() -functions can be used to retrieve an appropriate error code and a -textual error message. - -*archive_write_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 <kientzle@acm.org.> -== 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 -*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. diff --git a/libarchive/libarchive-2.8.0/doc/wiki/ManPageArchiveWriteDisk3.wiki b/libarchive/libarchive-2.8.0/doc/wiki/ManPageArchiveWriteDisk3.wiki deleted file mode 100644 index f71f85f..0000000 --- a/libarchive/libarchive-2.8.0/doc/wiki/ManPageArchiveWriteDisk3.wiki +++ /dev/null @@ -1,358 +0,0 @@ -#summary archive_write_disk 3 manual page -== NAME == -*archive_write_disk_new*, -*archive_write_disk_set_options*, -*archive_write_disk_set_skip_file*, -*archive_write_disk_set_group_lookup*, -*archive_write_disk_set_standard_lookup*, -*archive_write_disk_set_user_lookup*, -*archive_write_header*, -*archive_write_data*, -*archive_write_finish_entry*, -*archive_write_close*, -*archive_write_finish* -- functions for creating objects on disk -== SYNOPSIS == -*#include <archive.h>* -<br> -*struct archive `*`* -<br> -*archive_write_disk_new*(_void_); -<br> -*int* -<br> -*archive_write_disk_set_options*(_struct archive `*`_, _int flags_); -<br> -*int* -<br> -*archive_write_disk_set_skip_file*(_struct archive `*`_, _dev_t_, _ino_t_); -<br> -*int* -<br> -*archive_write_disk_set_group_lookup*(_struct archive `*`_, _void `*`_, _gid_t (`*`)(void `*`, const char `*`gname, gid_t gid)_, _void (`*`cleanup)(void `*`)_); -<br> -*int* -<br> -*archive_write_disk_set_standard_lookup*(_struct archive `*`_); -<br> -*int* -<br> -*archive_write_disk_set_user_lookup*(_struct archive `*`_, _void `*`_, _uid_t (`*`)(void `*`, const char `*`uname, uid_t uid)_, _void (`*`cleanup)(void `*`)_); -<br> -*int* -<br> -*archive_write_header*(_struct archive `*`_, _struct archive_entry `*`_); -<br> -*ssize_t* -<br> -*archive_write_data*(_struct archive `*`_, _const void `*`_, _size_t_); -<br> -*int* -<br> -*archive_write_finish_entry*(_struct archive `*`_); -<br> -*int* -<br> -*archive_write_close*(_struct archive `*`_); -<br> -*int* -<br> -*archive_write_finish*(_struct archive `*`_); -== DESCRIPTION == -These functions provide a complete API for creating objects on -disk from -*struct archive_entry* -descriptions. -They are most naturally used when extracting objects from an archive -using the -*archive_read*() -interface. -The general process is to read -*struct archive_entry* -objects from an archive, then write those objects to a -*struct archive* -object created using the -*archive_write_disk*() -family functions. -This interface is deliberately very similar to the -*archive_write*() -interface used to write objects to a streaming archive. -<dl> -<dt>*archive_write_disk_new*()</dt><dd> -Allocates and initializes a -*struct archive* -object suitable for writing objects to disk. -</dd><dt>*archive_write_disk_set_skip_file*()</dt><dd> -Records the device and inode numbers of a file that should not be -overwritten. -This is typically used to ensure that an extraction process does not -overwrite the archive from which objects are being read. -This capability is technically unnecessary but can be a significant -performance optimization in practice. -</dd><dt>*archive_write_disk_set_options*()</dt><dd> -The options field consists of a bitwise OR of one or more of the -following values: -<dl> -<dt>*ARCHIVE_EXTRACT_OWNER*</dt><dd> -The user and group IDs should be set on the restored file. -By default, the user and group IDs are not restored. -</dd><dt>*ARCHIVE_EXTRACT_PERM*</dt><dd> -Full permissions (including SGID, SUID, and sticky bits) should -be restored exactly as specified, without obeying the -current umask. -Note that SUID and SGID bits can only be restored if the -user and group ID of the object on disk are correct. -If -*ARCHIVE_EXTRACT_OWNER* -is not specified, then SUID and SGID bits will only be restored -if the default user and group IDs of newly-created objects on disk -happen to match those specified in the archive entry. -By default, only basic permissions are restored, and umask is obeyed. -</dd><dt>*ARCHIVE_EXTRACT_TIME*</dt><dd> -The timestamps (mtime, ctime, and atime) should be restored. -By default, they are ignored. -Note that restoring of atime is not currently supported. -</dd><dt>*ARCHIVE_EXTRACT_NO_OVERWRITE*</dt><dd> -Existing files on disk will not be overwritten. -By default, existing regular files are truncated and overwritten; -existing directories will have their permissions updated; -other pre-existing objects are unlinked and recreated from scratch. -</dd><dt>*ARCHIVE_EXTRACT_UNLINK*</dt><dd> -Existing files on disk will be unlinked before any attempt to -create them. -In some cases, this can prove to be a significant performance improvement. -By default, existing files are truncated and rewritten, but -the file is not recreated. -In particular, the default behavior does not break existing hard links. -</dd><dt>*ARCHIVE_EXTRACT_ACL*</dt><dd> -Attempt to restore ACLs. -By default, extended ACLs are ignored. -</dd><dt>*ARCHIVE_EXTRACT_FFLAGS*</dt><dd> -Attempt to restore extended file flags. -By default, file flags are ignored. -</dd><dt>*ARCHIVE_EXTRACT_XATTR*</dt><dd> -Attempt to restore POSIX.1e extended attributes. -By default, they are ignored. -</dd><dt>*ARCHIVE_EXTRACT_SECURE_SYMLINKS*</dt><dd> -Refuse to extract any object whose final location would be altered -by a symlink on disk. -This is intended to help guard against a variety of mischief -caused by archives that (deliberately or otherwise) extract -files outside of the current directory. -The default is not to perform this check. -If -*ARCHIVE_EXTRACT_UNLINK* -is specified together with this option, the library will -remove any intermediate symlinks it finds and return an -error only if such symlink could not be removed. -</dd><dt>*ARCHIVE_EXTRACT_SECURE_NODOTDOT*</dt><dd> -Refuse to extract a path that contains a -_.._ -element anywhere within it. -The default is to not refuse such paths. -Note that paths ending in -_.._ -always cause an error, regardless of this flag. -</dd><dt>*ARCHIVE_EXTRACT_SPARSE*</dt><dd> -Scan data for blocks of NUL bytes and try to recreate them with holes. -This results in sparse files, independent of whether the archive format -supports or uses them. -</dd></dl> -</dd><dt> -*archive_write_disk_set_group_lookup*(), -*archive_write_disk_set_user_lookup*() -</dt> <dd> -The -*struct archive_entry* -objects contain both names and ids that can be used to identify users -and groups. -These names and ids describe the ownership of the file itself and -also appear in ACL lists. -By default, the library uses the ids and ignores the names, but -this can be overridden by registering user and group lookup functions. -To register, you must provide a lookup function which -accepts both a name and id and returns a suitable id. -You may also provide a -*void `*`* -pointer to a private data structure and a cleanup function for -that data. -The cleanup function will be invoked when the -*struct archive* -object is destroyed. -</dd><dt>*archive_write_disk_set_standard_lookup*()</dt><dd> -This convenience function installs a standard set of user -and group lookup functions. -These functions use -*getpwnam*(3) -and -*getgrnam*(3) -to convert names to ids, defaulting to the ids if the names cannot -be looked up. -These functions also implement a simple memory cache to reduce -the number of calls to -*getpwnam*(3) -and -*getgrnam*(3). -</dd><dt>*archive_write_header*()</dt><dd> -Build and write a header using the data in the provided -*struct archive_entry* -structure. -See -*archive_entry*(3) -for information on creating and populating -*struct archive_entry* -objects. -</dd><dt>*archive_write_data*()</dt><dd> -Write data corresponding to the header just written. -Returns number of bytes written or -1 on error. -</dd><dt>*archive_write_finish_entry*()</dt><dd> -Close out the entry just written. -Ordinarily, clients never need to call this, as it -is called automatically by -*archive_write_next_header*() -and -*archive_write_close*() -as needed. -</dd><dt>*archive_write_close*()</dt><dd> -Set any attributes that could not be set during the initial restore. -For example, directory timestamps are not restored initially because -restoring a subsequent file would alter that timestamp. -Similarly, non-writable directories are initially created with -write permissions (so that their contents can be restored). -The -*archive_write_disk_new* -library maintains a list of all such deferred attributes and -sets them when this function is invoked. -</dd><dt>*archive_write_finish*()</dt><dd> -Invokes -*archive_write_close*() -if it was not invoked manually, then releases all resources. -</dd></dl> -More information about the -_struct_ archive -object and the overall design of the library can be found in the -*libarchive*(3) -overview. -Many of these functions are also documented under -*archive_write*(3). -== RETURN VALUES == -Most functions return -*ARCHIVE_OK* -(zero) on success, or one of several non-zero -error codes for errors. -Specific error codes include: -*ARCHIVE_RETRY* -for operations that might succeed if retried, -*ARCHIVE_WARN* -for unusual conditions that do not prevent further operations, and -*ARCHIVE_FATAL* -for serious errors that make remaining operations impossible. -The -*archive_errno*() -and -*archive_error_string*() -functions can be used to retrieve an appropriate error code and a -textual error message. - -*archive_write_disk_new*() -returns a pointer to a newly-allocated -*struct archive* -object. - -*archive_write_data*() -returns a count of the number of bytes actually written. -On error, -1 is returned and the -*archive_errno*() -and -*archive_error_string*() -functions will return appropriate values. -== SEE ALSO == -*archive_read*(3), -*archive_write*(3), -*tar*(1), -*libarchive*(3) -== HISTORY == -The -*libarchive* -library first appeared in -FreeBSD 5.3. -The -*archive_write_disk* -interface was added to -*libarchive* 2.0 -and first appeared in -FreeBSD 6.3. -== AUTHORS == -The -*libarchive* -library was written by -Tim Kientzle <kientzle@acm.org.> -== BUGS == -Directories are actually extracted in two distinct phases. -Directories are created during -*archive_write_header*(), -but final permissions are not set until -*archive_write_close*(). -This separation is necessary to correctly handle borderline -cases such as a non-writable directory containing -files, but can cause unexpected results. -In particular, directory permissions are not fully -restored until the archive is closed. -If you use -*chdir*(2) -to change the current directory between calls to -*archive_read_extract*() -or before calling -*archive_read_close*(), -you may confuse the permission-setting logic with -the result that directory permissions are restored -incorrectly. - -The library attempts to create objects with filenames longer than -*PATH_MAX* -by creating prefixes of the full path and changing the current directory. -Currently, this logic is limited in scope; the fixup pass does -not work correctly for such objects and the symlink security check -option disables the support for very long pathnames. - -Restoring the path -_aa/../bb_ -does create each intermediate directory. -In particular, the directory -_aa_ -is created as well as the final object -_bb_. -In theory, this can be exploited to create an entire directory heirarchy -with a single request. -Of course, this does not work if the -*ARCHIVE_EXTRACT_NODOTDOT* -option is specified. - -Implicit directories are always created obeying the current umask. -Explicit objects are created obeying the current umask unless -*ARCHIVE_EXTRACT_PERM* -is specified, in which case they current umask is ignored. - -SGID and SUID bits are restored only if the correct user and -group could be set. -If -*ARCHIVE_EXTRACT_OWNER* -is not specified, then no attempt is made to set the ownership. -In this case, SGID and SUID bits are restored only if the -user and group of the final object happen to match those specified -in the entry. - -The -"standard" -user-id and group-id lookup functions are not the defaults because -*getgrnam*(3) -and -*getpwnam*(3) -are sometimes too large for particular applications. -The current design allows the application author to use a more -compact implementation when appropriate. - -There should be a corresponding -*archive_read_disk* -interface that walks a directory heirarchy and returns archive -entry objects. diff --git a/libarchive/libarchive-2.8.0/doc/wiki/ManPageBsdcpio1.wiki b/libarchive/libarchive-2.8.0/doc/wiki/ManPageBsdcpio1.wiki deleted file mode 100644 index d3c24f5..0000000 --- a/libarchive/libarchive-2.8.0/doc/wiki/ManPageBsdcpio1.wiki +++ /dev/null @@ -1,386 +0,0 @@ -#summary BSDCPIO 1 manual page -== NAME == -*cpio* -- copy files to and from archives -== SYNOPSIS == -<br> -*cpio* -{*-i*} -`[`_options_`]` -`[`_pattern_ ...`]` -`[`_`<`_ archive`]` -<br> -*cpio* -{*-o*} -`[`_options_`]` -_`<`_ name-list -`[`_>_ archive`]` -<br> -*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: -<dl> -<dt>*-i*</dt><dd> -Input. -Read an archive from standard input (unless overriden) and extract the -contents to disk or (if the -*-t* -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. -</dd><dt>*-o*</dt><dd> -Output. -Read a list of filenames from standard input and produce a new archive -on standard output (unless overriden) containing the specified items. -</dd><dt>*-p*</dt><dd> -Pass-through. -Read a list of filenames from standard input and copy the files to the -specified directory. -</dd></dl> - -== OPTIONS == -Unless specifically stated otherwise, options are applicable in -all operating modes. -<dl> -<dt>*-0*</dt><dd> -Read filenames separated by NUL characters instead of newlines. -This is necessary if any of the filenames being read might contain newlines. -</dd><dt>*-A*</dt><dd> -(o mode only) -Append to the specified archive. -(Not yet implemented.) -</dd><dt>*-a*</dt><dd> -(o and p modes) -Reset access times on files after they are read. -</dd><dt>*-B*</dt><dd> -(o mode only) -Block output to records of 5120 bytes. -</dd><dt>*-C* _size_</dt><dd> -(o mode only) -Block output to records of -_size_ -bytes. -</dd><dt>*-c*</dt><dd> -(o mode only) -Use the old POSIX portable character format. -Equivalent to -*--format* _odc_. -</dd><dt>*-d*</dt><dd> -(i and p modes) -Create directories as necessary. -</dd><dt>*-E* _file_</dt><dd> -(i mode only) -Read list of file name patterns from -_file_ -to list and extract. -</dd><dt>*-F* _file_</dt><dd> -Read archive from or write archive to -_file_. -</dd><dt>*-f* _pattern_</dt><dd> -(i mode only) -Ignore files that match -_pattern_. -</dd><dt>*--format* _format_</dt><dd> -(o mode only) -Produce the output archive in the specified format. -Supported formats include: - -<dl> -<dt>_cpio_</dt><dd> -Synonym for -_odc_. -</dd><dt>_newc_</dt><dd> -The SVR4 portable cpio format. -</dd><dt>_odc_</dt><dd> -The old POSIX.1 portable octet-oriented cpio format. -</dd><dt>_pax_</dt><dd> -The POSIX.1 pax format, an extension of the ustar format. -</dd><dt>_ustar_</dt><dd> -The POSIX.1 tar format. -</dd></dl> - -The default format is -_odc_. -See -*libarchive_formats*(5) -for more complete information about the -formats currently supported by the underlying -*libarchive*(3) -library. -</dd><dt>*-H* _format_</dt><dd> -Synonym for -*--format*. -</dd><dt>*-h*, *--help*</dt><dd> -Print usage information. -</dd><dt>*-I* _file_</dt><dd> -Read archive from -_file_. -</dd><dt>*-i*</dt><dd> -Input mode. -See above for description. -</dd><dt>*--insecure*</dt><dd> -(i and p mode only) -Disable security checks during extraction or copying. -This allows extraction via symbolic links and path names containing -Sq .. -in the name. -</dd><dt>*-J*</dt><dd> -(o mode only) -Compress the file with xz-compatible compression before writing it. -In input mode, this option is ignored; xz compression is recognized -automatically on input. -</dd><dt>*-j*</dt><dd> -Synonym for -*-y*. -</dd><dt>*-L*</dt><dd> -(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. -</dd><dt>*-l*</dt><dd> -(p mode only) -Create links from the target directory to the original files, -instead of copying. -</dd><dt>*-lzma*</dt><dd> -(o mode only) -Compress the file with lzma-compatible compression before writing it. -In input mode, this option is ignored; lzma compression is recognized -automatically on input. -</dd><dt>*-m*</dt><dd> -(i and p modes) -Set file modification time on created files to match -those in the source. -</dd><dt>*-n*</dt><dd> -(i mode, only with -*-t*) -Display numeric uid and gid. -By default, -*cpio* -displays the user and group names when they are provided in the -archive, or looks up the user and group names in the system -password database. -</dd><dt>*-no-preserve-owner*</dt><dd> -(i mode only) -Do not attempt to restore file ownership. -This is the default when run by non-root users. -</dd><dt>*-O* _file_</dt><dd> -Write archive to -_file_. -</dd><dt>*-o*</dt><dd> -Output mode. -See above for description. -</dd><dt>*-p*</dt><dd> -Pass-through mode. -See above for description. -</dd><dt>*-preserve-owner*</dt><dd> -(i mode only) -Restore file ownership. -This is the default when run by the root user. -</dd><dt>*--quiet*</dt><dd> -Suppress unnecessary messages. -</dd><dt>*-R* `[`user`]``[`:`]``[`group`]`</dt><dd> -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.) -</dd><dt>*-r*</dt><dd> -(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. -</dd><dt>*-t*</dt><dd> -(i mode only) -List the contents of the archive to stdout; -do not restore the contents to disk. -</dd><dt>*-u*</dt><dd> -(i and p modes) -Unconditionally overwrite existing files. -Ordinarily, an older file will not overwrite a newer file on disk. -</dd><dt>*-v*</dt><dd> -Print the name of each file to stderr as it is processed. -With -*-t*, -provide a detailed listing of each file. -</dd><dt>*--version*</dt><dd> -Print the program version information and exit. -</dd><dt>*-y*</dt><dd> -(o mode only) -Compress the archive with bzip2-compatible compression before writing it. -In input mode, this option is ignored; -bzip2 compression is recognized automatically on input. -</dd><dt>*-Z*</dt><dd> -(o mode only) -Compress the archive with compress-compatible compression before writing it. -In input mode, this option is ignored; -compression is recognized automatically on input. -</dd><dt>*-z*</dt><dd> -(o mode only) -Compress the archive with gzip-compatible compression before writing it. -In input mode, this option is ignored; -gzip compression is recognized automatically on input. -</dd></dl> -== ENVIRONMENT == -The following environment variables affect the execution of -*cpio*: -<dl> -<dt>*LANG* -The locale to use. -See -*environ*(7) -for more information. -</dt><dt>*TZ* -The timezone to use when displaying dates. -See -*environ*(7) -for more information. -</dt></dl> -== 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 conjunction -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 control 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 particular 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 interpreted 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 standard. -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 formats cannot support files over 4 gigabytes, -except for the -"odc" -variant, which can support files up to 8 gigabytes. diff --git a/libarchive/libarchive-2.8.0/doc/wiki/ManPageBsdtar1.wiki b/libarchive/libarchive-2.8.0/doc/wiki/ManPageBsdtar1.wiki deleted file mode 100644 index c1fedb1..0000000 --- a/libarchive/libarchive-2.8.0/doc/wiki/ManPageBsdtar1.wiki +++ /dev/null @@ -1,941 +0,0 @@ -#summary BSDTAR 1 manual page -== NAME == -*tar* -- manipulate tape archives -== SYNOPSIS == -<br> -*tar* -`[`_bundled-flags_ `<`args`>``]` -`[``<`_file_`>` | `<`_pattern_`>` ...`]` -<br> -*tar* -{*-c*} -`[`_options_`]` -`[`_files_ | _directories_`]` -<br> -*tar* -{*-r* | *-u*} -*-f* _archive-file_ -`[`_options_`]` -`[`_files_ | _directories_`]` -<br> -*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 COMPATIBILITY below for details. - -The other synopsis forms show the preferred usage. -The first option to -*tar* -is a mode indicator from the following list: -<dl> -<dt>*-c*</dt><dd> -Create a new archive containing the specified items. -</dd><dt>*-r*</dt><dd> -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. -</dd><dt>*-t*</dt><dd> -List archive contents to stdout. -</dd><dt>*-u*</dt><dd> -Like -*-r*, -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 -*-f* -option is required. -</dd><dt>*-x*</dt><dd> -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. -</dd></dl> - -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 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 -*tcsh*(1). -== OPTIONS == -Unless specifically stated otherwise, options are applicable in -all operating modes. -<dl> -<dt>*@*_archive_</dt><dd> -(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, -{{{ -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 determined -automatically) and converts it into a gzip-compressed -pax-format archive on stdout. -In this way, -*tar* -can be used to convert archives from one format to another. -</dd><dt>*-b* _blocksize_</dt><dd> -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. -</dd><dt>*-C* _directory_</dt><dd> -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. -</dd><dt>*--check-links*</dt><dd> -(c and r modes only) -Issue a warning message unless all links to each file are archived. -</dd><dt>*--chroot*</dt><dd> -(x mode only) -*chroot*() -to the current directory after processing any -*-C* -options and before extracting any files. -</dd><dt>*--exclude* _pattern_</dt><dd> -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. -</dd><dt>*--format* _format_</dt><dd> -(c, r, u mode only) -Use the specified format for the created archive. -Supported formats include -"cpio", -"pax", -"shar", -and -"ustar". -Other formats may also be supported; see -*libarchive-formats*(5) -for more information about currently-supported formats. -In r and u modes, when extending an existing archive, the format specified -here must be compatible with the format of the existing archive on disk. -</dd><dt>*-f* _file_</dt><dd> -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_.) -</dd><dt>*-H*</dt><dd> -(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. -</dd><dt>*-h*</dt><dd> -(c and r mode only) -Synonym for -*-L*. -</dd><dt>*-I*</dt><dd> -Synonym for -*-T*. -</dd><dt>*--include* _pattern_</dt><dd> -Process only files or directories that match the specified pattern. -Note that exclusions specified with -*--exclude* -take precedence over inclusions. -If no inclusions are explicitly specified, 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 -Sq foo. -</dd><dt>*-j*</dt><dd> -(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. -</dd><dt>*-k*</dt><dd> -(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. -</dd><dt>*--keep-newer-files*</dt><dd> -(x mode only) -Do not overwrite existing files that are newer than the -versions appearing in the archive being extracted. -</dd><dt>*-L*</dt><dd> -(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. -</dd><dt>*-l*</dt><dd> -This is a synonym for the -*--check-links* -option. -</dd><dt>*-m*</dt><dd> -(x mode only) -Do not extract modification time. -By default, the modification time is set to the time stored in the archive. -</dd><dt>*-n*</dt><dd> -(c, r, u modes only) -Do not recursively archive the contents of directories. -</dd><dt>*--newer* _date_</dt><dd> -(c, r, u modes only) -Only include files and directories newer than the specified date. -This compares ctime entries. -</dd><dt>*--newer-mtime* _date_</dt><dd> -(c, r, u modes only) -Like -*--newer*, -except it compares mtime entries instead of ctime entries. -</dd><dt>*--newer-than* _file_</dt><dd> -(c, r, u modes only) -Only include files and directories newer than the specified file. -This compares ctime entries. -</dd><dt>*--newer-mtime-than* _file_</dt><dd> -(c, r, u modes only) -Like -*--newer-than*, -except it compares mtime entries instead of ctime entries. -</dd><dt>*--nodump*</dt><dd> -(c and r modes only) -Honor the nodump file flag by skipping this file. -</dd><dt>*--null*</dt><dd> -(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). -</dd><dt>*--numeric-owner*</dt><dd> -(x mode only) -Ignore symbolic user and group names when restoring archives to disk, -only numeric uid and gid values will be obeyed. -</dd><dt>*-O*</dt><dd> -(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. -</dd><dt>*-o*</dt><dd> -(x mode) -Use the user and group of the user running the program rather -than those specified in the archive. -Note that this has no significance unless -*-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 information in -the archive will be discarded. -</dd><dt>*-o*</dt><dd> -(c, r, u mode) -A synonym for -*--format* _ustar_ -</dd><dt>*--one-file-system*</dt><dd> -(c, r, and u modes) -Do not cross mount points. -</dd><dt>*--options* _options_</dt><dd> -Select optional behaviors for particular modules. -The argument is a text string containing comma-separated -keywords and values. -These are passed to the modules that handle particular -formats to control how those formats will behave. -Each option has one of the following forms: -<dl> -<dt>_key=value_</dt><dd> -The key will be set to the specified value in every module that supports it. -Modules that do not support this key will ignore it. -</dd><dt>_key_</dt><dd> -The key will be enabled in every module that supports it. -This is equivalent to -_key_*=1*. -</dd><dt>_!key_</dt><dd> -The key will be disabled in every module that supports it. -</dd><dt>_module:key=value_, _module:key_, _module:!key_</dt><dd> -As above, but the corresponding key and value will be provided -only to modules whose name matches -_module_. -</dd></dl> -The currently supported modules and keys are: -<dl> -<dt>*iso9660:joliet*</dt><dd> -Support Joliet extensions. -This is enabled by default, use -*!joliet* -or -*iso9660:!joliet* -to disable. -</dd><dt>*iso9660:rockridge*</dt><dd> -Support Rock Ridge extensions. -This is enabled by default, use -*!rockridge* -or -*iso9660:!rockridge* -to disable. -</dd><dt>*gzip:compression-level*</dt><dd> -A decimal integer from 0 to 9 specifying the gzip compression level. -</dd><dt>*xz:compression-level*</dt><dd> -A decimal integer from 0 to 9 specifying the xz compression level. -</dd><dt>*mtree:*_keyword_</dt><dd> -The mtree writer module allows you to specify which mtree keywords -will be included in the output. -Supported keywords include: -*cksum*, *device*, *flags*, *gid*, *gname*, *indent*, -*link*, *md5*, *mode*, *nlink*, *rmd160*, *sha1*, *sha256*, -*sha384*, *sha512*, *size*, *time*, *uid*, *uname*. -The default is equivalent to: -"device, flags, gid, gname, link, mode, nlink, size, time, type, uid, uname". -</dd><dt>*mtree:all*</dt><dd> -Enables all of the above keywords. -You can also use -*mtree:!all* -to disable all keywords. -</dd><dt>*mtree:use-set*</dt><dd> -Enable generation of -*/set* -lines in the output. -</dd><dt>*mtree:indent*</dt><dd> -Produce human-readable output by indenting options and splitting lines -to fit into 80 columns. -</dd><dt>*zip:compression*=_type_</dt><dd> -Use -_type_ -as compression method. -Supported values are store (uncompressed) and deflate (gzip algorithm). -</dd></dl> -If a provided option is not supported by any module, that -is a fatal error. -</dd><dt>*-P*</dt><dd> -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. -</dd><dt>*-p*</dt><dd> -(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. -</dd><dt>*-q* (*--fast-read*)</dt><dd> -(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. -</dd><dt>*-S*</dt><dd> -(x mode only) -Extract files as sparse files. -For every block on disk, check first if it contains only NULL bytes and seek -over it otherwise. -This works similiar to the conv=sparse option of dd. -</dd><dt>*--strip-components* _count_</dt><dd> -(x mode only) -Remove the specified number of leading path elements. -Pathnames with fewer elements will be silently skipped. -Note that the pathname is edited after checking inclusion/exclusion patterns -but before security checks. -</dd><dt>*-s* _pattern_</dt><dd> -Modify file or archive member names according to -_pattern_. -The pattern has the format -_/old/new/_`[`gps`]` -where -_old_ -is a basic regular expression, -_new_ -is the replacement string of the matched part, -and the optional trailing letters modify -how the replacement is handled. -If -_old_ -is not matched, the pattern is skipped. -Within -_new_, -~ is substituted with the match, \1 to \9 with the content of -the corresponding captured group. -The optional trailing g specifies that matching should continue -after the matched part and stopped on the first unmatched pattern. -The optional trailing s specifies that the pattern applies to the value -of symbolic links. -The optional trailing p specifies that after a successful substitution -the original path name and the new path name should be printed to -standard error. -</dd><dt>*-T* _filename_</dt><dd> -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 specified 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". -</dd><dt>*-U*</dt><dd> -(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. -</dd><dt>*--use-compress-program* _program_</dt><dd> -Pipe the input (in x or t mode) or the output (in c mode) through -_program_ -instead of using the builtin compression support. -</dd><dt>*-v*</dt><dd> -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. -</dd><dt>*--version*</dt><dd> -Print version of -*tar* -and -*libarchive*, -and exit. -</dd><dt>*-w*</dt><dd> -Ask for confirmation for every action. -</dd><dt>*-X* _filename_</dt><dd> -Read a list of exclusion patterns from the specified file. -See -*--exclude* -for more information about the handling of exclusions. -</dd><dt>*-y*</dt><dd> -(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. -</dd><dt>*-z*</dt><dd> -(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. -</dd><dt>*-Z*</dt><dd> -(c mode only) -Compress the resulting archive with -*compress*(1). -In extract or list modes, this option is ignored. -Note that, unlike other -*tar* -implementations, this implementation recognizes compress compression -automatically when reading archives. -</dd></dl> -== ENVIRONMENT == -The following environment variables affect the execution of -*tar*: -<dl> -<dt>*LANG* -The locale to use. -See -*environ*(7) -for more information. -</dt><dt>*TAPE* -The default tape device. -The -*-f* -option overrides this. -</dt><dt>*TZ* -The timezone to use when displaying dates. -See -*environ*(7) -for more information. -</dt></dl> -== FILES == -<dl> -<dt>*/dev/sa0* -The default tape device, if not overridden by the -.IR TAPE -environment variable or the -*-f* -option. -</dt></dl> -== 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 -*-C*_foo/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. - -An input file in -*mtree*(5) -format can be used to create an output archive with arbitrary ownership, -permissions, or names that differ from existing data on disk: - -{{{ -$ cat input.mtree -}}} -{{{ -#mtree -}}} -{{{ -usr/bin uid=0 gid=0 mode=0755 type=dir -}}} -{{{ -usr/bin/ls uid=0 gid=0 mode=0755 type=file content=myls -}}} -{{{ -$ tar -cvf output.tar @input.mtree -}}} - -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". - -The -*--options* -argument can be used to control various details of archive generation -or reading. -For example, you can generate mtree output which only contains -*type*, *time*, -and -*uid* -keywords: -{{{ -tar -cf file.tar --format=mtree --options='!all,type,time,uid' dir -}}} -or you can set the compression level used by gzip or xz compression: -{{{ -tar -czf file.tar --options='compression-level=9'. -}}} -For more details, see the explanation of the -*archive_read_set_options*() -and -*archive_write_set_options*() -API calls that are described in -*archive_read*(3) -and -*archive_write*(3). -== 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, -{{{ -tar tbf 32 file.tar -}}} -specifies three flags -*t*, -*b*, -and -*f*. -The -*b* -and -*f* -flags both require arguments, -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. - -Additional long options are provided 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 superuser, 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: -<ul> -<li> -Archive entries can have absolute pathnames. -By default, -*tar* -removes the leading -_/_ -character from filenames before restoring them to guard against this problem. -</li><li> -Archive entries can have pathnames that include -_.._ -components. -By default, -*tar* -will not extract files containing -_.._ -components in their pathname. -</li><li> -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. -</li></ul> -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 preserving any absolute pathnames, -_.._ -components, or symlinks to other directories. -== SEE ALSO == -*bzip2*(1), -*compress*(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 specification 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 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 -*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. diff --git a/libarchive/libarchive-2.8.0/doc/wiki/ManPageCpio5.wiki b/libarchive/libarchive-2.8.0/doc/wiki/ManPageCpio5.wiki deleted file mode 100644 index f39f64f..0000000 --- a/libarchive/libarchive-2.8.0/doc/wiki/ManPageCpio5.wiki +++ /dev/null @@ -1,297 +0,0 @@ -#summary CPIO 5 manual page -== 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 generally -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 -<dl> -<dt>_magic_</dt><dd> -The integer value octal 070707. -This value can be used to determine whether this archive is -written with little-endian or big-endian integers. -</dd><dt>_dev_, _ino_</dt><dd> -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. -</dd><dt>_mode_</dt><dd> -The mode specifies both the regular permissions and the file type. -It consists of several bit fields as follows: -<dl> -<dt>0170000</dt><dd> -This masks the file type bits. -</dd><dt>0140000</dt><dd> -File type value for sockets. -</dd><dt>0120000</dt><dd> -File type value for symbolic links. -For symbolic links, the link body is stored as file data. -</dd><dt>0100000</dt><dd> -File type value for regular files. -</dd><dt>0060000</dt><dd> -File type value for block special devices. -</dd><dt>0040000</dt><dd> -File type value for directories. -</dd><dt>0020000</dt><dd> -File type value for character special devices. -</dd><dt>0010000</dt><dd> -File type value for named pipes or FIFOs. -</dd><dt>0004000</dt><dd> -SUID bit. -</dd><dt>0002000</dt><dd> -SGID bit. -</dd><dt>0001000</dt><dd> -Sticky bit. -On some systems, this modifies the behavior of executables and/or directories. -</dd><dt>0000777</dt><dd> -The lower 9 bits specify read/write/execute permissions -for world, group, and user following standard POSIX conventions. -</dd></dl> -</dd><dt>_uid_, _gid_</dt><dd> -The numeric user id and group id of the owner. -</dd><dt>_nlink_</dt><dd> -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. -</dd><dt>_rdev_</dt><dd> -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. -</dd><dt>_mtime_</dt><dd> -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. -</dd><dt>_namesize_</dt><dd> -The number of bytes in the pathname that follows the header. -This count includes the trailing NUL byte. -</dd><dt>_filesize_</dt><dd> -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. -</dd></dl> - -The pathname immediately follows the fixed header. -If the -*namesize* -is odd, an additional NUL byte is added after the pathname. -The file data is then appended, padded with NUL -bytes to an even length. - -Hardlinked files are not given special treatment; -the full file contents are included with each copy of the -file. -=== 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 -NUL 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 numbers. -{{{ -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. -<dl> -<dt>_magic_</dt><dd> -The string -"070701". -</dd><dt>_check_</dt><dd> -This field is always set to zero by writers and ignored by readers. -See the next section for more details. -</dd></dl> - -The pathname is followed by NUL bytes so that the total size -of the fixed header plus pathname is a multiple of four. -Likewise, the file data is padded to a multiple of four bytes. -Note that this format supports only 4 gigabyte files (unlike the -older ASCII format, which supports 8 gigabyte files). - -In this format, hardlinked files are handled by setting the -filesize to zero for each entry except the last one that -appears in the archive. -=== 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 -_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 arithmetic. -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 archives. - -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 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. -== SEE ALSO == -*cpio*(1), -*tar*(5) -== STANDARDS == -The -*cpio* -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 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 -At v6 -that was used internally at AT&T. -Both the old binary and old character formats were in use -by 1980, according to the System III source released -by SCO under their -"Ancient Unix" -license. -The character format was adopted as part of -IEEE Std 1003.1-1988 (``POSIX.1''). -XXX when did "newc" appear? Who invented it? When did HP come out with their variant? When did Sun introduce ACLs and extended attributes? XXX diff --git a/libarchive/libarchive-2.8.0/doc/wiki/ManPageLibarchive3.wiki b/libarchive/libarchive-2.8.0/doc/wiki/ManPageLibarchive3.wiki deleted file mode 100644 index 997212f..0000000 --- a/libarchive/libarchive-2.8.0/doc/wiki/ManPageLibarchive3.wiki +++ /dev/null @@ -1,302 +0,0 @@ -#summary LIBARCHIVE 3 manual page -== NAME == -*libarchive* -- functions for reading and writing streaming archives -== LIBRARY == -Lb libarchive -== 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 modification. - -When reading an archive, the library automatically detects the -format and the compression. -The library currently has read support for: -<ul> -<li> -old-style tar archives, -</li><li> -most variants of the POSIX -"ustar" -format, -</li><li> -the POSIX -"pax interchange" -format, -</li><li> -GNU-format tar archives, -</li><li> -most common cpio archive formats, -</li><li> -ISO9660 CD images (with or without RockRidge extensions), -</li><li> -Zip archives. -</li></ul> -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 -<ul> -<li> -POSIX-standard -"ustar" -archives, -</li><li> -POSIX -"pax interchange format" -archives, -</li><li> -POSIX octet-oriented cpio archives, -</li><li> -two different variants of shar archives. -</li></ul> -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) -implementations 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*() -functions 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 -operation. -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 corresponding 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 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, -*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 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 -*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 information 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*() -function to release all resources. - -The -*archive_write*(3) -manual page provides more detailed calling information 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 provides 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 documented in -*archive_entry*(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 -_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 message suitable for display. - -*archive_read_new*() -and -*archive_write_new*() -return pointers to an allocated 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 <kientzle@acm.org.> -== 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 support large device numbers. diff --git a/libarchive/libarchive-2.8.0/doc/wiki/ManPageLibarchiveFormats5.wiki b/libarchive/libarchive-2.8.0/doc/wiki/ManPageLibarchiveFormats5.wiki deleted file mode 100644 index 0a8f362..0000000 --- a/libarchive/libarchive-2.8.0/doc/wiki/ManPageLibarchiveFormats5.wiki +++ /dev/null @@ -1,327 +0,0 @@ -#summary libarchive-formats 5 manual page -== 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 -limitations of the current library support. -Note that just because a format is supported by libarchive does not -imply that a program that uses libarchive will support that format. -Applications that use libarchive specify which formats they wish -to support, though many programs do use libarchive convenience -functions to enable all supported formats. -=== 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. - -<dl> -<dt>*gnutar*</dt><dd> -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. -</dd><dt>*pax*</dt><dd> -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 immediately before each regular entry. -The presence of these additional entries is the only difference between -pax interchange format and the older ustar format. -The extended attributes are of unlimited length and are stored -as UTF-8 Unicode strings. -Keywords defined in the standard are in all lowercase; vendors are allowed -to define custom keys by preceding them with the vendor name in all uppercase. -When writing pax archives, libarchive uses many of the SCHILY keys -defined by Joerg Schilling's -"star" -archiver and a few LIBARCHIVE keys. -The libarchive library can read most of the SCHILY keys -and most of the GNU keys introduced by GNU tar. -It silently ignores any keywords that it does not understand. -</dd><dt>*restricted* pax</dt><dd> -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 -_PaxHeader_ -directories. -</dd><dt>*ustar*</dt><dd> -The libarchive library can both read and write this format. -This format has the following limitations: -<ul> -<li> -Device major and minor numbers are limited to 21 bits. -Nodes with larger numbers will not be added to the archive. -</li><li> -Path names in the archive are limited to 255 bytes. -(Shorter if there is no / character in exactly the right place.) -</li><li> -Symbolic links and hard links are stored in the archive with -the name of the referenced file. -This name is limited to 100 bytes. -</li><li> -Extended attributes, file flags, and other extended -security information cannot be stored. -</li><li> -Archive entries are limited to 8 gigabytes in size. -</li></ul> -Note that the pax interchange format has none of these restrictions. -</dd></dl> - -The libarchive library also reads a variety of commonly-used extensions to -the basic tar format. -These extensions are recognized automatically whenever they appear. -<dl> -<dt>Numeric extensions.</dt><dd> -The POSIX standards require fixed-length numeric fields to be written with -some character position reserved for terminators. -Libarchive allows these fields to be written without terminator characters. -This extends the allowable range; in particular, ustar archives with this -extension can support entries up to 64 gigabytes in size. -Libarchive also recognizes base-256 values in most numeric fields. -This essentially removes all limitations on file size, modification time, -and device numbers. -</dd><dt>Solaris extensions</dt><dd> -Libarchive recognizes ACL and extended attribute records written -by Solaris tar. -Currently, libarchive only has support for old-style ACLs; the -newer NFSv4 ACLs are recognized but discarded. -</dd></dl> - -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 the tar format, the cpio format does only minimal padding -of the header or file data. -There are several cpio variants, which differ primarily in -how they store the initial header: some store the values as -octal or hexadecimal numbers in ASCII, others as binary values of -varying byte order and length. -<dl> -<dt>*binary*</dt><dd> -The libarchive library transparently reads both big-endian and little-endian -variants of the original binary cpio format. -This format used 32-bit binary values for file size and mtime, -and 16-bit binary values for the other fields. -</dd><dt>*odc*</dt><dd> -The libarchive library can both read and write this -POSIX-standard format, which is officially known as the -"cpio interchange format" -or the -"octet-oriented cpio archive format" -and sometimes unofficially referred to as the -"old character format". -This format stores the header contents as octal values in ASCII. -It is standard, portable, and immune from byte-order confusion. -File sizes and mtime are limited to 33 bits (8GB file size), -other fields are limited to 18 bits. -</dd><dt>*SVR4*</dt><dd> -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. -</dd></dl> - -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 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. -=== 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: -<dl> -<dt>*shar*</dt><dd> -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. -However, 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. -</dd><dt>*shardump*</dt><dd> -This format is similar to shar but encodes files using -*uuencode*(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. -</dd></dl> -=== ISO9660 format=== -Libarchive can read and extract from files containing ISO9660-compliant -CDROM images. -In many cases, this can remove the need to burn a physical CDROM -just in order to read the files contained in an ISO9660 image. -It also avoids security and complexity issues that come with -virtual mounts and loopback devices. -Libarchive supports the most common Rockridge extensions and has partial -support for Joliet extensions. -If both extensions are present, the Joliet extensions will be -used and the Rockridge extensions will be ignored. -In particular, this can create problems with hardlinks and symlinks, -which are supported by Rockridge but not by Joliet. -=== Zip format=== -Libarchive can read and write zip format archives that have -uncompressed entries and entries compressed with the -"deflate" -algorithm. -Older zip compression algorithms are not supported. -It can extract jar archives, archives that use Zip64 extensions and many -self-extracting zip archives. -Libarchive reads Zip archives as they are being streamed, -which allows it to read archives of arbitrary size. -It currently does not use the central directory; this -limits libarchive's ability to support some self-extracting -archives and ones that have been modified in certain ways. -=== 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 standardised. -There are two common variants: -the GNU format derived from SVR4, -and the BSD format, which first appeared in 4.4BSD. -The two differ primarily in their handling of filenames -longer than 15 characters: -the GNU/SVR4 variant writes a filename table at the beginning of the archive; -the BSD format stores each long filename in an extension -area adjacent to the entry. -Libarchive can read both extensions, -including archives that may include both types of long filenames. -Programs using libarchive can write GNU/SVR4 format -if they provide a filename table to be written into -the archive before any of the entries. -Any entries whose names are not in the filename table -will be written using BSD-style long filenames. -This can cause problems for programs such as -GNU ld that do not support the BSD-style long filenames. -=== mtree=== -Libarchive can read and write files in -*mtree*(5) -format. -This format is not a true archive format, but rather a textual description -of a file hierarchy in which each line specifies the name of a file and -provides specific metadata about that file. -Libarchive can read all of the keywords supported by both -the NetBSD and FreeBSD versions of -*mtree*(1), -although many of the keywords cannot currently be stored in an -*archive_entry* -object. -When writing, libarchive supports use of the -*archive_write_set_options*(3) -interface to specify which keywords should be included in the -output. -If libarchive was compiled with access to suitable -cryptographic libraries (such as the OpenSSL libraries), -it can compute hash entries such as -*sha512* -or -*md5* -from file data being written to the mtree writer. - -When reading an mtree file, libarchive will locate the corresponding -files on disk using the -*contents* -keyword if present or the regular filename. -If it can locate and open the file on disk, it will use that -to fill in any metadata that is missing from the mtree file -and will read the file contents and return those to the program -using libarchive. -If it cannot locate and open the file on disk, libarchive -will return an error for any attempt to read the entry -body. -== SEE ALSO == -*ar*(1), -*cpio*(1), -*mkisofs*(1), -*shar*(1), -*tar*(1), -*zip*(1), -*zlib*(3), -*cpio*(5), -*mtree*(5), -*tar*(5) diff --git a/libarchive/libarchive-2.8.0/doc/wiki/ManPageLibarchiveInternals3.wiki b/libarchive/libarchive-2.8.0/doc/wiki/ManPageLibarchiveInternals3.wiki deleted file mode 100644 index b21fedb..0000000 --- a/libarchive/libarchive-2.8.0/doc/wiki/ManPageLibarchiveInternals3.wiki +++ /dev/null @@ -1,337 +0,0 @@ -#summary LIBARCHIVE 3 manual page -== 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 archive 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 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. -== 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. -Internally, 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 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 -*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 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.) -=== 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 -*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 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 -*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: -<dl> -<dt>Registration/Configuration</dt><dd> -When the client invokes the public support function, -the decompression 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 contains a -_void_ * config -slot that can be used for storing any customization information. -</dd><dt>Bid</dt><dd> -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 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.) -</dd><dt>Initialize</dt><dd> -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. -</dd><dt>Satisfy I/O requests</dt><dd> -The format handler will invoke the -_read_ahead_, -_consume_, -and -_skip_ -functions as needed. -</dd><dt>Finish</dt><dd> -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. -</dd></dl> -=== Format Layer=== -The read formats have a similar lifecycle to the decompression handlers: -<dl> -<dt>Registration</dt><dd> -Allocate your private data and initialize your pointers. -</dd><dt>Bid</dt><dd> -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.) -</dd><dt>Read header</dt><dd> -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. -</dd><dt>Read Data</dt><dd> -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. -</dd><dt>Skip All Data</dt><dd> -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. -</dd><dt>Cleanup</dt><dd> -On cleanup, the format should release all of its allocated memory. -</dd></dl> -=== 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 registered 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 contain 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. -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. -== 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 <kientzle@acm.org.> -== BUGS == diff --git a/libarchive/libarchive-2.8.0/doc/wiki/ManPageMtree5.wiki b/libarchive/libarchive-2.8.0/doc/wiki/ManPageMtree5.wiki deleted file mode 100644 index fd49e30..0000000 --- a/libarchive/libarchive-2.8.0/doc/wiki/ManPageMtree5.wiki +++ /dev/null @@ -1,237 +0,0 @@ -#summary MTREE 5 manual page -== NAME == -*mtree* -- format of mtree dir hierarchy 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 hierarchies. -=== 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 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: -<dl> -<dt>Signature</dt><dd> -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". -</dd><dt>Blank</dt><dd> -Blank lines are ignored. -</dd><dt>Comment</dt><dd> -Lines beginning with -*#* -are ignored. -</dd><dt>Special</dt><dd> -Lines beginning with -*/* -are special commands that influence -the interpretation of later lines. -</dd><dt>Relative</dt><dd> -If the first whitespace-delimited word has no -*/* -characters, -it is the name of a file in the current directory. -Any relative entry that describes a directory changes the -current directory. -</dd><dt>dot-dot</dt><dd> -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. -</dd><dt>Full</dt><dd> -If the first whitespace-delimited word has a -*/* -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. -</dd></dl> - -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 specification. -=== Special commands=== -Two special commands are currently defined: -<dl> -<dt>*/set*</dt><dd> -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. -</dd><dt>*/unset*</dt><dd> -This command removes any default value set by a previous -*/set* -command. -It is followed on the same line by one or more keywords -separated by whitespace. -</dd></dl> -=== Keywords=== -After the filename, a full or relative entry consists of zero -or more whitespace-separated keyword definitions. -Each such definition consists of a key from the following -list immediately followed by an '=' sign -and a value. -Software programs reading mtree files should warn about -unrecognized keywords. - -Currently supported keywords are as follows: -<dl> -<dt>*cksum*</dt><dd> -The checksum of the file using the default algorithm specified by -the -*cksum*(1) -utility. -</dd><dt>*contents*</dt><dd> -The full pathname of a file that holds the contents of this file. -</dd><dt>*flags*</dt><dd> -The file flags as a symbolic name. -See -*chflags*(1) -for information on these names. -If no flags are to be set the string -"none" -may be used to override the current default. -</dd><dt>*gid*</dt><dd> -The file group as a numeric value. -</dd><dt>*gname*</dt><dd> -The file group as a symbolic name. -</dd><dt>*ignore*</dt><dd> -Ignore any file hierarchy below this file. -</dd><dt>*link*</dt><dd> -The target of the symbolic link when type=link. -</dd><dt>*md5*</dt><dd> -The MD5 message digest of the file. -</dd><dt>*md5digest*</dt><dd> -A synonym for -*md5*. -</dd><dt>*mode*</dt><dd> -The current file's permissions as a numeric (octal) or symbolic -value. -</dd><dt>*nlink*</dt><dd> -The number of hard links the file is expected to have. -</dd><dt>*nochange*</dt><dd> -Make sure this file or directory exists but otherwise ignore all attributes. -</dd><dt>*ripemd160digest*</dt><dd> -The -*RIPEMD160* -message digest of the file. -</dd><dt>*rmd160*</dt><dd> -A synonym for -*ripemd160digest*. -</dd><dt>*rmd160digest*</dt><dd> -A synonym for -*ripemd160digest*. -</dd><dt>*sha1*</dt><dd> -The -*FIPS* -160-1 -("Tn SHA-1") -message digest of the file. -</dd><dt>*sha1digest*</dt><dd> -A synonym for -*sha1*. -</dd><dt>*sha256*</dt><dd> -The -*FIPS* -180-2 -("Tn SHA-256") -message digest of the file. -</dd><dt>*sha256digest*</dt><dd> -A synonym for -*sha256*. -</dd><dt>*size*</dt><dd> -The size, in bytes, of the file. -</dd><dt>*time*</dt><dd> -The last modification time of the file. -</dd><dt>*type*</dt><dd> -The type of the file; may be set to any one of the following: - -<dl> -<dt>*block*</dt><dd> -block special device -</dd><dt>*char*</dt><dd> -character special device -</dd><dt>*dir*</dt><dd> -directory -</dd><dt>*fifo*</dt><dd> -fifo -</dd><dt>*file*</dt><dd> -regular file -</dd><dt>*link*</dt><dd> -symbolic link -</dd><dt>*socket*</dt><dd> -socket -</dd></dl> -</dd><dt>*uid*</dt><dd> -The file owner as a numeric value. -</dd><dt>*uname*</dt><dd> -The file owner as a symbolic name. -</dd></dl> - -== 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 -BSD 4.3 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. diff --git a/libarchive/libarchive-2.8.0/doc/wiki/ManPageTar5.wiki b/libarchive/libarchive-2.8.0/doc/wiki/ManPageTar5.wiki deleted file mode 100644 index 12fd514..0000000 --- a/libarchive/libarchive-2.8.0/doc/wiki/ManPageTar5.wiki +++ /dev/null @@ -1,805 +0,0 @@ -#summary tar 5 manual page -== 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 maximum block size supported by early -implementations was 10240 bytes or 20 records. -This is still the default for most implementations -although block sizes of 1MiB (2048 records) or larger are -commonly used with modern high-speed tape drives. -(Note: the terms -"block" -and -"record" -here are not entirely standard; this document follows the -convention established by John Gilmore in documenting -*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 -At v7, -which seems to be the earliest widely-used version 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. -<dl> -<dt>_name_</dt><dd> -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. -</dd><dt>_mode_</dt><dd> -File mode, stored as an octal number in ASCII. -</dd><dt>_uid_, _gid_</dt><dd> -User id and group id of owner, as octal numbers in ASCII. -</dd><dt>_size_</dt><dd> -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. -</dd><dt>_mtime_</dt><dd> -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. -</dd><dt>_checksum_</dt><dd> -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. -</dd><dt>_linkflag_, _linkname_</dt><dd> -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 -Sq 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.) -</dd></dl> - -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. -=== 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: -<ul> -<li> -The magic value is -"ustar\ \&" -(note the following space). -The version field contains a space character followed by a null. -</li><li> -The numeric fields are generally filled with leading spaces -(not leading zeros as recommended in the final standard). -</li><li> -The prefix field is often not used, limiting pathnames to -the 100 characters of old-style archives. -</li></ul> -=== 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]; -}; -}}} -<dl> -<dt>_typeflag_</dt><dd> -Type of entry. -POSIX extended the earlier -_linkflag_ -field with several new type values: -<dl> -<dt>"0"</dt><dd> -Regular file. -NUL should be treated as a synonym, for compatibility purposes. -</dd><dt>"1"</dt><dd> -Hard link. -</dd><dt>"2"</dt><dd> -Symbolic link. -</dd><dt>"3"</dt><dd> -Character device node. -</dd><dt>"4"</dt><dd> -Block device node. -</dd><dt>"5"</dt><dd> -Directory. -</dd><dt>"6"</dt><dd> -FIFO node. -</dd><dt>"7"</dt><dd> -Reserved. -</dd><dt>Other</dt><dd> -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. -</dd></dl> -It is worth noting that the -_size_ -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. -</dd><dt>_magic_</dt><dd> -Contains the magic value -"ustar" -followed by a NUL byte to indicate that this is a POSIX standard archive. -Full compliance requires the uname and gname fields be properly set. -</dd><dt>_version_</dt><dd> -Version. -This should be -"00" -(two copies of the ASCII digit zero) for POSIX standard archives. -</dd><dt>_uname_, _gname_</dt><dd> -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. -</dd><dt>_devmajor_, _devminor_</dt><dd> -Major and minor numbers for character device or block device entry. -</dd><dt>_name_, _prefix_</dt><dd> -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 into the prefix field. -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 pathname. -The standard does not require a trailing -_/_ -character on directory names, though most implementations still -include this for compatibility reasons. -</dd></dl> - -Note that all unused bytes must be set to -NUL. - -Field termination is specified slightly differently by POSIX -than by previous implementations. -The -_magic_, -_uname_, -and -_gname_ -fields must have a trailing -NUL. -The -_pathname_, -_linkname_, -and -_prefix_ -fields must have a trailing -NUL -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 requires -them to be terminated with either space or -NUL -characters. - -Currently, most tar implementations comply with the ustar -format, occasionally extending it by adding new fields to the -blank area at the end of the header record. -=== 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: -{{{ -25 ctime=1084839148.1212\en -}}} -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: -<dl> -<dt>*atime*, *ctime*, *mtime*</dt><dd> -File access, inode change, and modification times. -These fields can be negative or include a decimal point and a fractional value. -</dd><dt>*uname*, *uid*, *gname*, *gid*</dt><dd> -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. -</dd><dt>*linkpath*</dt><dd> -The full path of the linked-to file. -Note that this is encoded in UTF8 and can thus include non-ASCII characters. -</dd><dt>*path*</dt><dd> -The full pathname of the entry. -Note that this is encoded in UTF8 and can thus include non-ASCII characters. -</dd><dt>*realtime.`*`*, *security.`*`*</dt><dd> -These keys are reserved and may be used for future standardization. -</dd><dt>*size*</dt><dd> -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. -</dd><dt>*SCHILY.`*`*</dt><dd> -Vendor-specific attributes used by Joerg Schilling's -*star* -implementation. -</dd><dt>*SCHILY.acl.access*, *SCHILY.acl.default*</dt><dd> -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). -</dd><dt>*SCHILY.devminor*, *SCHILY.devmajor*</dt><dd> -The full minor and major numbers for device nodes. -</dd><dt>*SCHILY.fflags*</dt><dd> -The file flags. -</dd><dt>*SCHILY.realsize*</dt><dd> -The full size of the file on disk. -XXX explain? XXX -</dd><dt>*SCHILY.dev,* *SCHILY.ino*, *SCHILY.nlinks*</dt><dd> -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. -</dd><dt>*LIBARCHIVE.xattr.*_namespace_._key_</dt><dd> -Libarchive stores POSIX.1e-style extended attributes using -keys of this form. -The -_key_ -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 -</dd><dt>*VENDOR.`*`*</dt><dd> -XXX document other vendor-specific extensions XXX -</dd></dl> - -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 -*x* -entry described above, the pax interchange format -also supports a -*g* -entry. -The -*g* -entry is identical in format, but specifies 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 modify 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 compatible, 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]; -}; -}}} -<dl> -<dt>_typeflag_</dt><dd> -GNU tar uses the following special entry types, in addition to -those defined by POSIX: -<dl> -<dt>7</dt><dd> -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. -</dd><dt>D</dt><dd> -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. -</dd><dt>K</dt><dd> -The data for this entry is a long linkname for the following regular entry. -</dd><dt>L</dt><dd> -The data for this entry is a long pathname for the following regular entry. -</dd><dt>M</dt><dd> -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 -_size_ -field specifies 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. -</dd><dt>N</dt><dd> -Type "N" records are no longer generated by GNU tar. -They contained a -list of files to be renamed or symlinked after extraction; this was -originally used to support long names. -The contents of this record -are a text description of the operations to be done, in the form -"Rename %s to %s\en" -or -"Symlink %s to %s\en ;" -in either case, both -filenames are escaped using K&R C syntax. -Due to security concerns, "N" records are now generally ignored -when reading archives. -</dd><dt>S</dt><dd> -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. -</dd><dt>V</dt><dd> -The -_name_ -field should be interpreted as a tape/volume header name. -This entry should generally be ignored on extraction. -</dd></dl> -</dd><dt>_magic_</dt><dd> -The magic field holds the five characters -"ustar" -followed by a space. -Note that POSIX ustar archives have a trailing null. -</dd><dt>_version_</dt><dd> -The version field holds a space character followed by a null. -Note that POSIX ustar archives use two copies of the ASCII digit -"0". -</dd><dt>_atime_, _ctime_</dt><dd> -The time the file was last accessed and the time of -last change of file information, stored in octal as with -_mtime_. -</dd><dt>_longnames_</dt><dd> -This field is apparently no longer used. -</dd><dt>Sparse _offset_ / _numbytes_</dt><dd> -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. -</dd><dt>_isextended_</dt><dd> -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: -{{{ -struct gnu_sparse_header { - struct { - char offset[12]; - char numbytes[12]; - } sparse[21]; - char isextended[1]; - char padding[7]; -}; -}}} -</dd><dt>_realsize_</dt><dd> -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. -</dd></dl> -=== GNU tar pax archives=== -GNU tar 1.14 (XXX check this XXX) and later will write -pax interchange format archives when you specify the -*--posix* -flag. -This format uses custom keywords to store sparse file information. -There have been three iterations of this support, referred to -as -"0.0", -"0.1", -and -"1.0". -<dl> -<dt>*GNU.sparse.numblocks*, *GNU.sparse.offset*, *GNU.sparse.numbytes*, *GNU.sparse.size*</dt><dd> -The -"0.0" -format used an initial -*GNU.sparse.numblocks* -attribute to indicate the number of blocks in the file, a pair of -*GNU.sparse.offset* -and -*GNU.sparse.numbytes* -to indicate the offset and size of each block, -and a single -*GNU.sparse.size* -to indicate the full size of the file. -This is not the same as the size in the tar header because the -latter value does not include the size of any holes. -This format required that the order of attributes be preserved and -relied on readers accepting multiple appearances of the same attribute -names, which is not officially permitted by the standards. -</dd><dt>*GNU.sparse.map*</dt><dd> -The -"0.1" -format used a single attribute that stored a comma-separated -list of decimal numbers. -Each pair of numbers indicated the offset and size, respectively, -of a block of data. -This does not work well if the archive is extracted by an archiver -that does not recognize this extension, since many pax implementations -simply discard unrecognized attributes. -</dd><dt>*GNU.sparse.major*, *GNU.sparse.minor*, *GNU.sparse.name*, *GNU.sparse.realsize*</dt><dd> -The -"1.0" -format stores the sparse block map in one or more 512-byte blocks -prepended to the file data in the entry body. -The pax attributes indicate the existence of this map -(via the -*GNU.sparse.major* -and -*GNU.sparse.minor* -fields) -and the full size of the file. -The -*GNU.sparse.name* -holds the true name of the file. -To avoid confusion, the name stored in the regular tar header -is a modified name so that extraction errors will be apparent -to users. -</dd></dl> -=== 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: -<ul> -<li> -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. -</li><li> -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 -followed by a zero byte, followed by the -textual ACL description. -The octal value is the number of ACL entries -plus a constant that indicates the ACL type: 01000000 -for POSIX.1e ACLs and 03000000 for NFSv4 ACLs. -</li></ul> -=== AIX Tar=== -XXX More details needed XXX -=== Mac OS X Tar=== -The tar distributed with Apple's Mac OS X stores most regular files -as two separate entries in the tar archive. -The two entries have the same name except that the first -one has -"._" -added to the beginning of the name. -This first entry stores the -"resource fork" -with additional attributes for the file. -The Mac OS X -*CopyFile*() -API is used to separate a file on disk into separate -resource and data streams and to reassemble those separate -streams when the file is restored to disk. -=== Other Extensions=== -One obvious extension to increase the size of files is to -eliminate the terminating characters from the various -numeric fields. -For example, the standard only allows the size field to contain -11 octal digits, reserving the twelfth byte for a trailing -NUL character. -Allowing 12 octal digits allows file sizes up to 64 GB. - -Another 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 byte. -This permits 95-bit values for the length and time fields -and 63-bit values for the uid, gid, and device numbers. -GNU tar supports this extension for the -length, mtime, ctime, and atime fields. -Joerg Schilling's star program supports this extension for -all numeric fields. -Note that this extension is largely obsoleted by the extended attribute -record provided by the pax interchange format. - -Another early GNU extension allowed base-64 values rather than octal. -This extension was short-lived and is no longer supported by any -implementation. -== 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 -(circa 1988). -Joerg Shilling's -*star* -archiver is another open-source (GPL) archiver (originally developed -circa 1985) which features complete support for pax interchange -format. - -This documentation was written as part of the -*libarchive* -and -*bsdtar* -project by -Tim Kientzle <kientzle@FreeBSD.org.> |