diff options
Diffstat (limited to 'libarchive/libarchive-2.8.0/doc/html')
15 files changed, 8156 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> |