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