diff options
Diffstat (limited to 'archivers/libarchive/files/doc/man')
| -rw-r--r-- | archivers/libarchive/files/doc/man/Makefile | 5 | ||||
| -rw-r--r-- | archivers/libarchive/files/doc/man/archive_entry.3 | 810 | ||||
| -rw-r--r-- | archivers/libarchive/files/doc/man/archive_read.3 | 861 | ||||
| -rw-r--r-- | archivers/libarchive/files/doc/man/archive_read_disk.3 | 300 | ||||
| -rw-r--r-- | archivers/libarchive/files/doc/man/archive_util.3 | 187 | ||||
| -rw-r--r-- | archivers/libarchive/files/doc/man/archive_write.3 | 721 | ||||
| -rw-r--r-- | archivers/libarchive/files/doc/man/archive_write_disk.3 | 286 | ||||
| -rw-r--r-- | archivers/libarchive/files/doc/man/bsdcpio.1 | 114 | ||||
| -rw-r--r-- | archivers/libarchive/files/doc/man/bsdtar.1 | 380 | ||||
| -rw-r--r-- | archivers/libarchive/files/doc/man/cpio.5 | 50 | ||||
| -rw-r--r-- | archivers/libarchive/files/doc/man/libarchive-formats.5 | 152 | ||||
| -rw-r--r-- | archivers/libarchive/files/doc/man/libarchive.3 | 206 | ||||
| -rw-r--r-- | archivers/libarchive/files/doc/man/libarchive_internals.3 | 95 | ||||
| -rw-r--r-- | archivers/libarchive/files/doc/man/mtree.5 | 31 | ||||
| -rw-r--r-- | archivers/libarchive/files/doc/man/tar.5 | 244 |
15 files changed, 2307 insertions, 2135 deletions
diff --git a/archivers/libarchive/files/doc/man/Makefile b/archivers/libarchive/files/doc/man/Makefile index c33aac4c647..d3a90196331 100644 --- a/archivers/libarchive/files/doc/man/Makefile +++ b/archivers/libarchive/files/doc/man/Makefile @@ -8,6 +8,9 @@ archive_entry.3: ../mdoc2man.awk ../../libarchive/archive_entry.3 archive_read.3: ../mdoc2man.awk ../../libarchive/archive_read.3 awk -f ../mdoc2man.awk < ../../libarchive/archive_read.3 > archive_read.3 +archive_read_disk.3: ../mdoc2man.awk ../../libarchive/archive_read_disk.3 + awk -f ../mdoc2man.awk < ../../libarchive/archive_read_disk.3 > archive_read_disk.3 + archive_util.3: ../mdoc2man.awk ../../libarchive/archive_util.3 awk -f ../mdoc2man.awk < ../../libarchive/archive_util.3 > archive_util.3 @@ -40,4 +43,4 @@ bsdtar.1: ../mdoc2man.awk ../../tar/bsdtar.1 bsdcpio.1: ../mdoc2man.awk ../../cpio/bsdcpio.1 awk -f ../mdoc2man.awk < ../../cpio/bsdcpio.1 > bsdcpio.1 -all: archive_entry.3 archive_read.3 archive_util.3 archive_write.3 archive_write_disk.3 cpio.5 libarchive-formats.5 libarchive.3 libarchive_internals.3 mtree.5 tar.5 bsdtar.1 bsdcpio.1 +all: archive_entry.3 archive_read.3 archive_read_disk.3 archive_util.3 archive_write.3 archive_write_disk.3 cpio.5 libarchive-formats.5 libarchive.3 libarchive_internals.3 mtree.5 tar.5 bsdtar.1 bsdcpio.1 diff --git a/archivers/libarchive/files/doc/man/archive_entry.3 b/archivers/libarchive/files/doc/man/archive_entry.3 index 994b4743c33..d459f00af99 100644 --- a/archivers/libarchive/files/doc/man/archive_entry.3 +++ b/archivers/libarchive/files/doc/man/archive_entry.3 @@ -1,530 +1,370 @@ .TH archive_entry 3 "May 12, 2008" "" .SH NAME -\fBarchive_entry_acl_add_entry\fP, -\fBarchive_entry_acl_add_entry_w\fP, -\fBarchive_entry_acl_clear\fP, -\fBarchive_entry_acl_count\fP, -\fBarchive_entry_acl_next\fP, -\fBarchive_entry_acl_next_w\fP, -\fBarchive_entry_acl_reset\fP, -\fBarchive_entry_acl_text_w\fP, -\fBarchive_entry_atime\fP, -\fBarchive_entry_atime_nsec\fP, -\fBarchive_entry_clear\fP, -\fBarchive_entry_clone\fP, -\fBarchive_entry_copy_fflags_text\fP, -\fBarchive_entry_copy_fflags_text_w\fP, -\fBarchive_entry_copy_gname\fP, -\fBarchive_entry_copy_gname_w\fP, -\fBarchive_entry_copy_hardlink\fP, -\fBarchive_entry_copy_hardlink_w\fP, -\fBarchive_entry_copy_link\fP, -\fBarchive_entry_copy_link_w\fP, -\fBarchive_entry_copy_pathname_w\fP, -\fBarchive_entry_copy_sourcepath\fP, -\fBarchive_entry_copy_stat\fP, -\fBarchive_entry_copy_symlink\fP, -\fBarchive_entry_copy_symlink_w\fP, -\fBarchive_entry_copy_uname\fP, -\fBarchive_entry_copy_uname_w\fP, -\fBarchive_entry_dev\fP, -\fBarchive_entry_devmajor\fP, -\fBarchive_entry_devminor\fP, -\fBarchive_entry_filetype\fP, -\fBarchive_entry_fflags\fP, -\fBarchive_entry_fflags_text\fP, -\fBarchive_entry_free\fP, -\fBarchive_entry_gid\fP, -\fBarchive_entry_gname\fP, -\fBarchive_entry_hardlink\fP, -\fBarchive_entry_ino\fP, -\fBarchive_entry_mode\fP, -\fBarchive_entry_mtime\fP, -\fBarchive_entry_mtime_nsec\fP, -\fBarchive_entry_nlink\fP, -\fBarchive_entry_new\fP, -\fBarchive_entry_pathname\fP, -\fBarchive_entry_pathname_w\fP, -\fBarchive_entry_rdev\fP, -\fBarchive_entry_rdevmajor\fP, -\fBarchive_entry_rdevminor\fP, -\fBarchive_entry_set_atime\fP, -\fBarchive_entry_set_ctime\fP, -\fBarchive_entry_set_dev\fP, -\fBarchive_entry_set_devmajor\fP, -\fBarchive_entry_set_devminor\fP, -\fBarchive_entry_set_filetype\fP, -\fBarchive_entry_set_fflags\fP, -\fBarchive_entry_set_gid\fP, -\fBarchive_entry_set_gname\fP, -\fBarchive_entry_set_hardlink\fP, -\fBarchive_entry_set_link\fP, -\fBarchive_entry_set_mode\fP, -\fBarchive_entry_set_mtime\fP, -\fBarchive_entry_set_pathname\fP, -\fBarchive_entry_set_rdevmajor\fP, -\fBarchive_entry_set_rdevminor\fP, -\fBarchive_entry_set_size\fP, -\fBarchive_entry_set_symlink\fP, -\fBarchive_entry_set_uid\fP, -\fBarchive_entry_set_uname\fP, -\fBarchive_entry_size\fP, -\fBarchive_entry_sourcepath\fP, -\fBarchive_entry_stat\fP, -\fBarchive_entry_symlink\fP, -\fBarchive_entry_uid\fP, -\fBarchive_entry_uname\fP +.ad l +\fB\%archive_entry_acl_add_entry\fP, +\fB\%archive_entry_acl_add_entry_w\fP, +\fB\%archive_entry_acl_clear\fP, +\fB\%archive_entry_acl_count\fP, +\fB\%archive_entry_acl_next\fP, +\fB\%archive_entry_acl_next_w\fP, +\fB\%archive_entry_acl_reset\fP, +\fB\%archive_entry_acl_text_w\fP, +\fB\%archive_entry_atime\fP, +\fB\%archive_entry_atime_nsec\fP, +\fB\%archive_entry_clear\fP, +\fB\%archive_entry_clone\fP, +\fB\%archive_entry_copy_fflags_text\fP, +\fB\%archive_entry_copy_fflags_text_w\fP, +\fB\%archive_entry_copy_gname\fP, +\fB\%archive_entry_copy_gname_w\fP, +\fB\%archive_entry_copy_hardlink\fP, +\fB\%archive_entry_copy_hardlink_w\fP, +\fB\%archive_entry_copy_link\fP, +\fB\%archive_entry_copy_link_w\fP, +\fB\%archive_entry_copy_pathname_w\fP, +\fB\%archive_entry_copy_sourcepath\fP, +\fB\%archive_entry_copy_stat\fP, +\fB\%archive_entry_copy_symlink\fP, +\fB\%archive_entry_copy_symlink_w\fP, +\fB\%archive_entry_copy_uname\fP, +\fB\%archive_entry_copy_uname_w\fP, +\fB\%archive_entry_dev\fP, +\fB\%archive_entry_devmajor\fP, +\fB\%archive_entry_devminor\fP, +\fB\%archive_entry_filetype\fP, +\fB\%archive_entry_fflags\fP, +\fB\%archive_entry_fflags_text\fP, +\fB\%archive_entry_free\fP, +\fB\%archive_entry_gid\fP, +\fB\%archive_entry_gname\fP, +\fB\%archive_entry_hardlink\fP, +\fB\%archive_entry_ino\fP, +\fB\%archive_entry_mode\fP, +\fB\%archive_entry_mtime\fP, +\fB\%archive_entry_mtime_nsec\fP, +\fB\%archive_entry_nlink\fP, +\fB\%archive_entry_new\fP, +\fB\%archive_entry_pathname\fP, +\fB\%archive_entry_pathname_w\fP, +\fB\%archive_entry_rdev\fP, +\fB\%archive_entry_rdevmajor\fP, +\fB\%archive_entry_rdevminor\fP, +\fB\%archive_entry_set_atime\fP, +\fB\%archive_entry_set_ctime\fP, +\fB\%archive_entry_set_dev\fP, +\fB\%archive_entry_set_devmajor\fP, +\fB\%archive_entry_set_devminor\fP, +\fB\%archive_entry_set_filetype\fP, +\fB\%archive_entry_set_fflags\fP, +\fB\%archive_entry_set_gid\fP, +\fB\%archive_entry_set_gname\fP, +\fB\%archive_entry_set_hardlink\fP, +\fB\%archive_entry_set_link\fP, +\fB\%archive_entry_set_mode\fP, +\fB\%archive_entry_set_mtime\fP, +\fB\%archive_entry_set_pathname\fP, +\fB\%archive_entry_set_rdevmajor\fP, +\fB\%archive_entry_set_rdevminor\fP, +\fB\%archive_entry_set_size\fP, +\fB\%archive_entry_set_symlink\fP, +\fB\%archive_entry_set_uid\fP, +\fB\%archive_entry_set_uname\fP, +\fB\%archive_entry_size\fP, +\fB\%archive_entry_sourcepath\fP, +\fB\%archive_entry_stat\fP, +\fB\%archive_entry_symlink\fP, +\fB\%archive_entry_uid\fP, +\fB\%archive_entry_uname\fP \- functions for manipulating archive entry descriptions .SH SYNOPSIS +.ad l \fB#include <archive_entry.h>\fP .br \fIvoid\fP -.RE -Fo archive_entry_acl_add_entry -Fa "struct archive_entry *" -Fa "int type" -Fa "int permset" -Fa "int tag" -Fa "int qual" -Fa "const char *name" -Fc +.br +\fB\%archive_entry_acl_add_entry\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%int\ type\fP, \fI\%int\ permset\fP, \fI\%int\ tag\fP, \fI\%int\ qual\fP, \fI\%const\ char\ *name\fP); +.br \fIvoid\fP -.RE -Fo archive_entry_acl_add_entry_w -Fa "struct archive_entry *" -Fa "int type" -Fa "int permset" -Fa "int tag" -Fa "int qual" -Fa "const wchar_t *name" -Fc +.br +\fB\%archive_entry_acl_add_entry_w\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%int\ type\fP, \fI\%int\ permset\fP, \fI\%int\ tag\fP, \fI\%int\ qual\fP, \fI\%const\ wchar_t\ *name\fP); +.br \fIvoid\fP -.RE -.nh -\fBarchive_entry_acl_clear\fP -.hy -("struct archive_entry *"); +.br +\fB\%archive_entry_acl_clear\fP(\fI\%struct\ archive_entry\ *\fP); +.br \fIint\fP -.RE -.nh -\fBarchive_entry_acl_count\fP -.hy -("struct archive_entry *" "int type"); +.br +\fB\%archive_entry_acl_count\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%int\ type\fP); +.br \fIint\fP -.RE -Fo archive_entry_acl_next -Fa "struct archive_entry *" -Fa "int want_type" -Fa "int *type" -Fa "int *permset" -Fa "int *tag" -Fa "int *qual" -Fa "const char **name" -Fc +.br +\fB\%archive_entry_acl_next\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%int\ want_type\fP, \fI\%int\ *type\fP, \fI\%int\ *permset\fP, \fI\%int\ *tag\fP, \fI\%int\ *qual\fP, \fI\%const\ char\ **name\fP); +.br \fIint\fP -.RE -Fo archive_entry_acl_next_w -Fa "struct archive_entry *" -Fa "int want_type" -Fa "int *type" -Fa "int *permset" -Fa "int *tag" -Fa "int *qual" -Fa "const wchar_t **name" -Fc +.br +\fB\%archive_entry_acl_next_w\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%int\ want_type\fP, \fI\%int\ *type\fP, \fI\%int\ *permset\fP, \fI\%int\ *tag\fP, \fI\%int\ *qual\fP, \fI\%const\ wchar_t\ **name\fP); +.br \fIint\fP -.RE -.nh -\fBarchive_entry_acl_reset\fP -.hy -("struct archive_entry *" "int want_type"); +.br +\fB\%archive_entry_acl_reset\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%int\ want_type\fP); +.br \fIconst wchar_t *\fP -.RE -.nh -\fBarchive_entry_acl_text_w\fP -.hy -("struct archive_entry *" "int flags"); +.br +\fB\%archive_entry_acl_text_w\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%int\ flags\fP); +.br \fItime_t\fP -.RE -.nh -\fBarchive_entry_atime\fP -.hy -("struct archive_entry *"); +.br +\fB\%archive_entry_atime\fP(\fI\%struct\ archive_entry\ *\fP); +.br \fIlong\fP -.RE -.nh -\fBarchive_entry_atime_nsec\fP -.hy -("struct archive_entry *"); -\fI"struct archive_entry *"\fP -.RE -.nh -\fBarchive_entry_clear\fP -.hy -("struct archive_entry *"); +.br +\fB\%archive_entry_atime_nsec\fP(\fI\%struct\ archive_entry\ *\fP); +.br \fIstruct archive_entry *\fP -.RE -.nh -\fBarchive_entry_clone\fP -.hy -("struct archive_entry *"); +.br +\fB\%archive_entry_clear\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fIstruct archive_entry *\fP +.br +\fB\%archive_entry_clone\fP(\fI\%struct\ archive_entry\ *\fP); +.br \fIconst char * *\fP -.RE -.nh -\fBarchive_entry_copy_fflags_text_w\fP -.hy -("struct archive_entry *" "const char *"); +.br +\fB\%archive_entry_copy_fflags_text_w\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ char\ *\fP); +.br \fIconst wchar_t *\fP -.RE -.nh -\fBarchive_entry_copy_fflags_text_w\fP -.hy -("struct archive_entry *" "const wchar_t *"); +.br +\fB\%archive_entry_copy_fflags_text_w\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ wchar_t\ *\fP); +.br \fIvoid\fP -.RE -.nh -\fBarchive_entry_copy_gname\fP -.hy -("struct archive_entry *" "const char *"); +.br +\fB\%archive_entry_copy_gname\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ char\ *\fP); +.br \fIvoid\fP -.RE -.nh -\fBarchive_entry_copy_gname_w\fP -.hy -("struct archive_entry *" "const wchar_t *"); +.br +\fB\%archive_entry_copy_gname_w\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ wchar_t\ *\fP); +.br \fIvoid\fP -.RE -.nh -\fBarchive_entry_copy_hardlink\fP -.hy -("struct archive_entry *" "const char *"); +.br +\fB\%archive_entry_copy_hardlink\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ char\ *\fP); +.br \fIvoid\fP -.RE -.nh -\fBarchive_entry_copy_hardlink_w\fP -.hy -("struct archive_entry *" "const wchar_t *"); +.br +\fB\%archive_entry_copy_hardlink_w\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ wchar_t\ *\fP); +.br \fIvoid\fP -.RE -.nh -\fBarchive_entry_copy_sourcepath\fP -.hy -("struct archive_entry *" "const char *"); +.br +\fB\%archive_entry_copy_sourcepath\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ char\ *\fP); +.br \fIvoid\fP -.RE -.nh -\fBarchive_entry_copy_pathname_w\fP -.hy -("struct archive_entry *" "const wchar_t *"); +.br +\fB\%archive_entry_copy_pathname_w\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ wchar_t\ *\fP); +.br \fIvoid\fP -.RE -.nh -\fBarchive_entry_copy_stat\fP -.hy -("struct archive_entry *" "const struct stat *"); +.br +\fB\%archive_entry_copy_stat\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ struct\ stat\ *\fP); +.br \fIvoid\fP -.RE -.nh -\fBarchive_entry_copy_symlink\fP -.hy -("struct archive_entry *" "const char *"); +.br +\fB\%archive_entry_copy_symlink\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ char\ *\fP); +.br \fIvoid\fP -.RE -.nh -\fBarchive_entry_copy_symlink_w\fP -.hy -("struct archive_entry *" "const wchar_t *"); +.br +\fB\%archive_entry_copy_symlink_w\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ wchar_t\ *\fP); +.br \fIvoid\fP -.RE -.nh -\fBarchive_entry_copy_uname\fP -.hy -("struct archive_entry *" "const char *"); +.br +\fB\%archive_entry_copy_uname\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ char\ *\fP); +.br \fIvoid\fP -.RE -.nh -\fBarchive_entry_copy_uname_w\fP -.hy -("struct archive_entry *" "const wchar_t *"); +.br +\fB\%archive_entry_copy_uname_w\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ wchar_t\ *\fP); +.br \fIdev_t\fP -.RE -.nh -\fBarchive_entry_dev\fP -.hy -("struct archive_entry *"); +.br +\fB\%archive_entry_dev\fP(\fI\%struct\ archive_entry\ *\fP); +.br \fIdev_t\fP -.RE -.nh -\fBarchive_entry_devmajor\fP -.hy -("struct archive_entry *"); +.br +\fB\%archive_entry_devmajor\fP(\fI\%struct\ archive_entry\ *\fP); +.br \fIdev_t\fP -.RE -.nh -\fBarchive_entry_devminor\fP -.hy -("struct archive_entry *"); +.br +\fB\%archive_entry_devminor\fP(\fI\%struct\ archive_entry\ *\fP); +.br \fImode_t\fP -.RE -.nh -\fBarchive_entry_filetype\fP -.hy -("struct archive_entry *"); +.br +\fB\%archive_entry_filetype\fP(\fI\%struct\ archive_entry\ *\fP); +.br \fIvoid\fP -.RE -Fo archive_entry_fflags -Fa "struct archive_entry *" -Fa "unsigned long *set" -Fa "unsigned long *clear" -Fc +.br +\fB\%archive_entry_fflags\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%unsigned\ long\ *set\fP, \fI\%unsigned\ long\ *clear\fP); +.br \fIconst char *\fP -.RE -.nh -\fBarchive_entry_fflags_text\fP -.hy -("struct archive_entry *"); +.br +\fB\%archive_entry_fflags_text\fP(\fI\%struct\ archive_entry\ *\fP); +.br \fIvoid\fP -.RE -.nh -\fBarchive_entry_free\fP -.hy -("struct archive_entry *"); +.br +\fB\%archive_entry_free\fP(\fI\%struct\ archive_entry\ *\fP); +.br \fIconst char *\fP -.RE -.nh -\fBarchive_entry_gname\fP -.hy -("struct archive_entry *"); +.br +\fB\%archive_entry_gname\fP(\fI\%struct\ archive_entry\ *\fP); +.br \fIconst char *\fP -.RE -.nh -\fBarchive_entry_hardlink\fP -.hy -("struct archive_entry *"); +.br +\fB\%archive_entry_hardlink\fP(\fI\%struct\ archive_entry\ *\fP); +.br \fIino_t\fP -.RE -.nh -\fBarchive_entry_ino\fP -.hy -("struct archive_entry *"); +.br +\fB\%archive_entry_ino\fP(\fI\%struct\ archive_entry\ *\fP); +.br \fImode_t\fP -.RE -.nh -\fBarchive_entry_mode\fP -.hy -("struct archive_entry *"); +.br +\fB\%archive_entry_mode\fP(\fI\%struct\ archive_entry\ *\fP); +.br \fItime_t\fP -.RE -.nh -\fBarchive_entry_mtime\fP -.hy -("struct archive_entry *"); +.br +\fB\%archive_entry_mtime\fP(\fI\%struct\ archive_entry\ *\fP); +.br \fIlong\fP -.RE -.nh -\fBarchive_entry_mtime_nsec\fP -.hy -("struct archive_entry *"); +.br +\fB\%archive_entry_mtime_nsec\fP(\fI\%struct\ archive_entry\ *\fP); +.br \fIunsigned int\fP -.RE -.nh -\fBarchive_entry_nlink\fP -.hy -("struct archive_entry *"); +.br +\fB\%archive_entry_nlink\fP(\fI\%struct\ archive_entry\ *\fP); +.br \fIstruct archive_entry *\fP -.RE -.nh -\fBarchive_entry_new\fP -.hy -("void"); +.br +\fB\%archive_entry_new\fP(\fI\%void\fP); +.br \fIconst char *\fP -.RE -.nh -\fBarchive_entry_pathname\fP -.hy -("struct archive_entry *"); +.br +\fB\%archive_entry_pathname\fP(\fI\%struct\ archive_entry\ *\fP); +.br \fIconst wchar_t *\fP -.RE -.nh -\fBarchive_entry_pathname_w\fP -.hy -("struct archive_entry *"); +.br +\fB\%archive_entry_pathname_w\fP(\fI\%struct\ archive_entry\ *\fP); +.br \fIdev_t\fP -.RE -.nh -\fBarchive_entry_rdev\fP -.hy -("struct archive_entry *"); +.br +\fB\%archive_entry_rdev\fP(\fI\%struct\ archive_entry\ *\fP); +.br \fIdev_t\fP -.RE -.nh -\fBarchive_entry_rdevmajor\fP -.hy -("struct archive_entry *"); +.br +\fB\%archive_entry_rdevmajor\fP(\fI\%struct\ archive_entry\ *\fP); +.br \fIdev_t\fP -.RE -.nh -\fBarchive_entry_rdevminor\fP -.hy -("struct archive_entry *"); +.br +\fB\%archive_entry_rdevminor\fP(\fI\%struct\ archive_entry\ *\fP); +.br \fIvoid\fP -.RE -.nh -\fBarchive_entry_set_dev\fP -.hy -("struct archive_entry *" "dev_t"); +.br +\fB\%archive_entry_set_dev\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%dev_t\fP); +.br \fIvoid\fP -.RE -.nh -\fBarchive_entry_set_devmajor\fP -.hy -("struct archive_entry *" "dev_t"); +.br +\fB\%archive_entry_set_devmajor\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%dev_t\fP); +.br \fIvoid\fP -.RE -.nh -\fBarchive_entry_set_devminor\fP -.hy -("struct archive_entry *" "dev_t"); +.br +\fB\%archive_entry_set_devminor\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%dev_t\fP); +.br \fIvoid\fP -.RE -.nh -\fBarchive_entry_set_filetype\fP -.hy -("struct archive_entry *" "unsigned int"); +.br +\fB\%archive_entry_set_filetype\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%unsigned\ int\fP); +.br \fIvoid\fP -.RE -Fo archive_entry_set_fflags -Fa "struct archive_entry *" -Fa "unsigned long set" -Fa "unsigned long clear" -Fc +.br +\fB\%archive_entry_set_fflags\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%unsigned\ long\ set\fP, \fI\%unsigned\ long\ clear\fP); +.br \fIvoid\fP -.RE -.nh -\fBarchive_entry_set_gid\fP -.hy -("struct archive_entry *" "gid_t"); +.br +\fB\%archive_entry_set_gid\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%gid_t\fP); +.br \fIvoid\fP -.RE -.nh -\fBarchive_entry_set_gname\fP -.hy -("struct archive_entry *" "const char *"); +.br +\fB\%archive_entry_set_gname\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ char\ *\fP); +.br \fIvoid\fP -.RE -.nh -\fBarchive_entry_set_hardlink\fP -.hy -("struct archive_entry *" "const char *"); +.br +\fB\%archive_entry_set_hardlink\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ char\ *\fP); +.br \fIvoid\fP -.RE -.nh -\fBarchive_entry_set_ino\fP -.hy -("struct archive_entry *" "unsigned long"); +.br +\fB\%archive_entry_set_ino\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%unsigned\ long\fP); +.br \fIvoid\fP -.RE -.nh -\fBarchive_entry_set_link\fP -.hy -("struct archive_entry *" "const char *"); +.br +\fB\%archive_entry_set_link\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ char\ *\fP); +.br \fIvoid\fP -.RE -.nh -\fBarchive_entry_set_mode\fP -.hy -("struct archive_entry *" "mode_t"); +.br +\fB\%archive_entry_set_mode\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%mode_t\fP); +.br \fIvoid\fP -.RE -.nh -\fBarchive_entry_set_mtime\fP -.hy -("struct archive_entry *" "time_t" "long nanos"); +.br +\fB\%archive_entry_set_mtime\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%time_t\fP, \fI\%long\ nanos\fP); +.br \fIvoid\fP -.RE -.nh -\fBarchive_entry_set_nlink\fP -.hy -("struct archive_entry *" "unsigned int"); +.br +\fB\%archive_entry_set_nlink\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%unsigned\ int\fP); +.br \fIvoid\fP -.RE -.nh -\fBarchive_entry_set_pathname\fP -.hy -("struct archive_entry *" "const char *"); +.br +\fB\%archive_entry_set_pathname\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ char\ *\fP); +.br \fIvoid\fP -.RE -.nh -\fBarchive_entry_set_rdev\fP -.hy -("struct archive_entry *" "dev_t"); +.br +\fB\%archive_entry_set_rdev\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%dev_t\fP); +.br \fIvoid\fP -.RE -.nh -\fBarchive_entry_set_rdevmajor\fP -.hy -("struct archive_entry *" "dev_t"); +.br +\fB\%archive_entry_set_rdevmajor\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%dev_t\fP); +.br \fIvoid\fP -.RE -.nh -\fBarchive_entry_set_rdevminor\fP -.hy -("struct archive_entry *" "dev_t"); +.br +\fB\%archive_entry_set_rdevminor\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%dev_t\fP); +.br \fIvoid\fP -.RE -.nh -\fBarchive_entry_set_size\fP -.hy -("struct archive_entry *" "int64_t"); +.br +\fB\%archive_entry_set_size\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%int64_t\fP); +.br \fIvoid\fP -.RE -.nh -\fBarchive_entry_set_symlink\fP -.hy -("struct archive_entry *" "const char *"); +.br +\fB\%archive_entry_set_symlink\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ char\ *\fP); +.br \fIvoid\fP -.RE -.nh -\fBarchive_entry_set_uid\fP -.hy -("struct archive_entry *" "uid_t"); +.br +\fB\%archive_entry_set_uid\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%uid_t\fP); +.br \fIvoid\fP -.RE -.nh -\fBarchive_entry_set_uname\fP -.hy -("struct archive_entry *" "const char *"); +.br +\fB\%archive_entry_set_uname\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ char\ *\fP); +.br \fIint64_t\fP -.RE -.nh -\fBarchive_entry_size\fP -.hy -("struct archive_entry *"); +.br +\fB\%archive_entry_size\fP(\fI\%struct\ archive_entry\ *\fP); +.br \fIconst char *\fP -.RE -.nh -\fBarchive_entry_sourcepath\fP -.hy -("struct archive_entry *"); +.br +\fB\%archive_entry_sourcepath\fP(\fI\%struct\ archive_entry\ *\fP); +.br \fIconst struct stat *\fP -.RE -.nh -\fBarchive_entry_stat\fP -.hy -("struct archive_entry *"); +.br +\fB\%archive_entry_stat\fP(\fI\%struct\ archive_entry\ *\fP); +.br \fIconst char *\fP -.RE -.nh -\fBarchive_entry_symlink\fP -.hy -("struct archive_entry *"); +.br +\fB\%archive_entry_symlink\fP(\fI\%struct\ archive_entry\ *\fP); +.br \fIconst char *\fP -.RE -.nh -\fBarchive_entry_uname\fP -.hy -("struct archive_entry *"); +.br +\fB\%archive_entry_uname\fP(\fI\%struct\ archive_entry\ *\fP); .SH DESCRIPTION +.ad l These functions create and manipulate data objects that represent entries within an archive. You can think of a @@ -542,63 +382,46 @@ entry in an archive. There are functions to allocate, destroy, clear, and copy \fIarchive_entry\fP objects: +.RS 5 .TP -.nh -\fBarchive_entry_clear\fP -.hy -(); +\fB\%archive_entry_clear\fP() Erases the object, resetting all internal fields to the same state as a newly-created object. This is provided to allow you to quickly recycle objects without thrashing the heap. .TP -.nh -\fBarchive_entry_clone\fP -.hy -(); +\fB\%archive_entry_clone\fP() A deep copy operation; all text fields are duplicated. .TP -.nh -\fBarchive_entry_free\fP -.hy -(); +\fB\%archive_entry_free\fP() Releases the Tn struct archive_entry object. .TP -.nh -\fBarchive_entry_new\fP -.hy -(); +\fB\%archive_entry_new\fP() Allocate and return a blank Tn struct archive_entry object. +.RE .SS Set and Get Functions Most of the functions here set or read entries in an object. Such functions have one of the following forms: +.RS 5 .TP -.nh -\fBarchive_entry_set_XXXX\fP -.hy -(); +\fB\%archive_entry_set_XXXX\fP() Stores the provided data in the object. In particular, for strings, the pointer is stored, not the referenced string. .TP -.nh -\fBarchive_entry_copy_XXXX\fP -.hy -(); +\fB\%archive_entry_copy_XXXX\fP() As above, except that the referenced data is copied into the object. .TP -.nh -\fBarchive_entry_XXXX\fP -.hy -(); +\fB\%archive_entry_XXXX\fP() Returns the specified data. In the case of strings, a const-qualified pointer to the string is returned. +.RE String data can be set or accessed as wide character strings or normal \fIchar\fP @@ -612,14 +435,14 @@ using the current locale. Similarly, if you store a wide string and then store a narrow string for the same data, the previously-set wide string will be discarded in favor of the new data. +.PP There are a few set/get functions that merit additional description: +.RS 5 .TP -.nh -\fBarchive_entry_set_link\fP -.hy -(); +\fB\%archive_entry_set_link\fP() This function sets the symlink field if it is already set. Otherwise, it sets the hardlink field. +.RE .SS File Flags File flags are transparently converted between a bitmap representation and a textual format. @@ -631,6 +454,7 @@ If you need to canonicalize a textual flags string, you should first set the text form, then request the bitmap form, then use that to set the bitmap form. Setting the bitmap format will clear the internal text representation and force it to be reconstructed when you next request the text form. +.PP The bitmap format consists of two integers, one containing bits that should be set, the other specifying bits that should be cleared. @@ -645,17 +469,12 @@ which only includes names for set bits.) Converting a bitmap to a textual string is a platform-specific operation; bits that are not meaningful on the current platform will be ignored. +.PP The canonical text format is a comma-separated list of flag names. The -.nh -\fBarchive_entry_copy_fflags_text\fP -.hy -(); +\fB\%archive_entry_copy_fflags_text\fP() and -.nh -\fBarchive_entry_copy_fflags_text_w\fP -.hy -(); +\fB\%archive_entry_copy_fflags_text_w\fP() functions parse the provided text and sets the internal bitmap values. This is a platform-specific operation; names that are not meaningful on the current platform will be ignored. @@ -670,6 +489,7 @@ which stops parsing at the first unrecognized name.) .SS ACL Handling XXX This needs serious help. XXX +.PP An ``Access Control List'' (ACL) is a list of permissions that grant access to particular users or @@ -679,17 +499,21 @@ specification. In particular, POSIX.1e draft 17 specifies several different formats, but none of those formats include both textual user/group names and numeric UIDs/GIDs. +.PP XXX explain ACL stuff XXX .SH SEE ALSO +.ad l \fBarchive\fP(3) .SH HISTORY +.ad l The -\fBlibarchive\fP +\fB\%libarchive\fP library first appeared in FreeBSD 5.3. .SH AUTHORS +.ad l -nosplit The -\fBlibarchive\fP +\fB\%libarchive\fP library was written by -Tim Kientzle <kientzle@acm.org.> +Tim Kientzle \%<kientzle@acm.org.> diff --git a/archivers/libarchive/files/doc/man/archive_read.3 b/archivers/libarchive/files/doc/man/archive_read.3 index 91908e824ec..b1bd4f3dcca 100644 --- a/archivers/libarchive/files/doc/man/archive_read.3 +++ b/archivers/libarchive/files/doc/man/archive_read.3 @@ -1,233 +1,212 @@ -.TH archive_read 3 "August 19, 2006" "" +.TH archive_read 3 "April 13, 2009" "" .SH NAME -\fBarchive_read_new\fP, -\fBarchive_read_support_compression_all\fP, -\fBarchive_read_support_compression_bzip2\fP, -\fBarchive_read_support_compression_compress\fP, -\fBarchive_read_support_compression_gzip\fP, -\fBarchive_read_support_compression_none\fP, -\fBarchive_read_support_compression_program\fP, -\fBarchive_read_support_format_all\fP, -\fBarchive_read_support_format_cpio\fP, -\fBarchive_read_support_format_empty\fP, -\fBarchive_read_support_format_iso9660\fP, -\fBarchive_read_support_format_tar\fP, -\fBarchive_read_support_format_zip\fP, -\fBarchive_read_open\fP, -\fBarchive_read_open2\fP, -\fBarchive_read_open_fd\fP, -\fBarchive_read_open_FILE\fP, -\fBarchive_read_open_filename\fP, -\fBarchive_read_open_memory\fP, -\fBarchive_read_next_header\fP, -\fBarchive_read_data\fP, -\fBarchive_read_data_block\fP, -\fBarchive_read_data_skip\fP, -\fBarchive_read_data_into_buffer\fP, -\fBarchive_read_data_into_fd\fP, -\fBarchive_read_extract\fP, -\fBarchive_read_extract2\fP, -\fBarchive_read_extract_set_progress_callback\fP, -\fBarchive_read_close\fP, -\fBarchive_read_finish\fP +.ad l +\fB\%archive_read_new\fP, +\fB\%archive_read_set_filter_options\fP, +\fB\%archive_read_set_format_options\fP, +\fB\%archive_read_set_options\fP, +\fB\%archive_read_support_compression_all\fP, +\fB\%archive_read_support_compression_bzip2\fP, +\fB\%archive_read_support_compression_compress\fP, +\fB\%archive_read_support_compression_gzip\fP, +\fB\%archive_read_support_compression_lzma\fP, +\fB\%archive_read_support_compression_none\fP, +\fB\%archive_read_support_compression_xz\fP, +\fB\%archive_read_support_compression_program\fP, +\fB\%archive_read_support_compression_program_signature\fP, +\fB\%archive_read_support_format_all\fP, +\fB\%archive_read_support_format_ar\fP, +\fB\%archive_read_support_format_cpio\fP, +\fB\%archive_read_support_format_empty\fP, +\fB\%archive_read_support_format_iso9660\fP, +\fB\%archive_read_support_format_mtree,\fP +\fB\%archive_read_support_format_raw,\fP +\fB\%archive_read_support_format_tar\fP, +\fB\%archive_read_support_format_zip\fP, +\fB\%archive_read_open\fP, +\fB\%archive_read_open2\fP, +\fB\%archive_read_open_fd\fP, +\fB\%archive_read_open_FILE\fP, +\fB\%archive_read_open_filename\fP, +\fB\%archive_read_open_memory\fP, +\fB\%archive_read_next_header\fP, +\fB\%archive_read_next_header2\fP, +\fB\%archive_read_data\fP, +\fB\%archive_read_data_block\fP, +\fB\%archive_read_data_skip\fP, +\fB\%archive_read_data_into_buffer\fP, +\fB\%archive_read_data_into_fd\fP, +\fB\%archive_read_extract\fP, +\fB\%archive_read_extract2\fP, +\fB\%archive_read_extract_set_progress_callback\fP, +\fB\%archive_read_close\fP, +\fB\%archive_read_finish\fP \- functions for reading streaming archives .SH SYNOPSIS +.ad l \fB#include <archive.h>\fP .br \fIstruct archive *\fP -.RE -.nh -\fBarchive_read_new\fP -.hy -("void"); +.br +\fB\%archive_read_new\fP(\fI\%void\fP); +.br \fIint\fP -.RE -.nh -\fBarchive_read_support_compression_all\fP -.hy -("struct archive *"); +.br +\fB\%archive_read_support_compression_all\fP(\fI\%struct\ archive\ *\fP); +.br \fIint\fP -.RE -.nh -\fBarchive_read_support_compression_bzip2\fP -.hy -("struct archive *"); +.br +\fB\%archive_read_support_compression_bzip2\fP(\fI\%struct\ archive\ *\fP); +.br \fIint\fP -.RE -.nh -\fBarchive_read_support_compression_compress\fP -.hy -("struct archive *"); +.br +\fB\%archive_read_support_compression_compress\fP(\fI\%struct\ archive\ *\fP); +.br \fIint\fP -.RE -.nh -\fBarchive_read_support_compression_gzip\fP -.hy -("struct archive *"); +.br +\fB\%archive_read_support_compression_gzip\fP(\fI\%struct\ archive\ *\fP); +.br \fIint\fP -.RE -.nh -\fBarchive_read_support_compression_none\fP -.hy -("struct archive *"); +.br +\fB\%archive_read_support_compression_lzma\fP(\fI\%struct\ archive\ *\fP); +.br \fIint\fP -.RE -Fo archive_read_support_compression_program -Fa "struct archive *" -Fa "const char *cmd" -Fc +.br +\fB\%archive_read_support_compression_none\fP(\fI\%struct\ archive\ *\fP); +.br \fIint\fP -.RE -.nh -\fBarchive_read_support_format_all\fP -.hy -("struct archive *"); +.br +\fB\%archive_read_support_compression_xz\fP(\fI\%struct\ archive\ *\fP); +.br \fIint\fP -.RE -.nh -\fBarchive_read_support_format_cpio\fP -.hy -("struct archive *"); +.br +\fB\%archive_read_support_compression_program\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ char\ *cmd\fP); +.br \fIint\fP -.RE -.nh -\fBarchive_read_support_format_empty\fP -.hy -("struct archive *"); +.br +\fB\%archive_read_support_compression_program_signature\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ char\ *cmd\fP, \fI\%const\ void\ *signature\fP, \fI\%size_t\ signature_length\fP); +.br \fIint\fP -.RE -.nh -\fBarchive_read_support_format_iso9660\fP -.hy -("struct archive *"); +.br +\fB\%archive_read_support_format_all\fP(\fI\%struct\ archive\ *\fP); +.br \fIint\fP -.RE -.nh -\fBarchive_read_support_format_tar\fP -.hy -("struct archive *"); +.br +\fB\%archive_read_support_format_ar\fP(\fI\%struct\ archive\ *\fP); +.br \fIint\fP -.RE -.nh -\fBarchive_read_support_format_zip\fP -.hy -("struct archive *"); +.br +\fB\%archive_read_support_format_cpio\fP(\fI\%struct\ archive\ *\fP); +.br \fIint\fP -.RE -Fo archive_read_open -Fa "struct archive *" -Fa "void *client_data" -Fa "archive_open_callback *" -Fa "archive_read_callback *" -Fa "archive_close_callback *" -Fc +.br +\fB\%archive_read_support_format_empty\fP(\fI\%struct\ archive\ *\fP); +.br \fIint\fP -.RE -Fo archive_read_open2 -Fa "struct archive *" -Fa "void *client_data" -Fa "archive_open_callback *" -Fa "archive_read_callback *" -Fa "archive_skip_callback *" -Fa "archive_close_callback *" -Fc +.br +\fB\%archive_read_support_format_iso9660\fP(\fI\%struct\ archive\ *\fP); +.br \fIint\fP -.RE -.nh -\fBarchive_read_open_FILE\fP -.hy -("struct archive *" "FILE *file"); +.br +\fB\%archive_read_support_format_mtree\fP(\fI\%struct\ archive\ *\fP); +.br \fIint\fP -.RE -.nh -\fBarchive_read_open_fd\fP -.hy -("struct archive *" "int fd" "size_t block_size"); +.br +\fB\%archive_read_support_format_raw\fP(\fI\%struct\ archive\ *\fP); +.br \fIint\fP -.RE -Fo archive_read_open_filename -Fa "struct archive *" -Fa "const char *filename" -Fa "size_t block_size" -Fc +.br +\fB\%archive_read_support_format_tar\fP(\fI\%struct\ archive\ *\fP); +.br \fIint\fP -.RE -.nh -\fBarchive_read_open_memory\fP -.hy -("struct archive *" "void *buff" "size_t size"); +.br +\fB\%archive_read_support_format_zip\fP(\fI\%struct\ archive\ *\fP); +.br \fIint\fP -.RE -.nh -\fBarchive_read_next_header\fP -.hy -("struct archive *" "struct archive_entry **"); +.br +\fB\%archive_read_set_filter_options\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ char\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_read_set_format_options\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ char\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_read_set_options\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ char\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_read_open\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *client_data\fP, \fI\%archive_open_callback\ *\fP, \fI\%archive_read_callback\ *\fP, \fI\%archive_close_callback\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_read_open2\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *client_data\fP, \fI\%archive_open_callback\ *\fP, \fI\%archive_read_callback\ *\fP, \fI\%archive_skip_callback\ *\fP, \fI\%archive_close_callback\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_read_open_FILE\fP(\fI\%struct\ archive\ *\fP, \fI\%FILE\ *file\fP); +.br +\fIint\fP +.br +\fB\%archive_read_open_fd\fP(\fI\%struct\ archive\ *\fP, \fI\%int\ fd\fP, \fI\%size_t\ block_size\fP); +.br +\fIint\fP +.br +\fB\%archive_read_open_filename\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ char\ *filename\fP, \fI\%size_t\ block_size\fP); +.br +\fIint\fP +.br +\fB\%archive_read_open_memory\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *buff\fP, \fI\%size_t\ size\fP); +.br +\fIint\fP +.br +\fB\%archive_read_next_header\fP(\fI\%struct\ archive\ *\fP, \fI\%struct\ archive_entry\ **\fP); +.br +\fIint\fP +.br +\fB\%archive_read_next_header2\fP(\fI\%struct\ archive\ *\fP, \fI\%struct\ archive_entry\ *\fP); +.br \fIssize_t\fP -.RE -.nh -\fBarchive_read_data\fP -.hy -("struct archive *" "void *buff" "size_t len"); +.br +\fB\%archive_read_data\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *buff\fP, \fI\%size_t\ len\fP); +.br \fIint\fP -.RE -Fo archive_read_data_block -Fa "struct archive *" -Fa "const void **buff" -Fa "size_t *len" -Fa "off_t *offset" -Fc +.br +\fB\%archive_read_data_block\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ void\ **buff\fP, \fI\%size_t\ *len\fP, \fI\%off_t\ *offset\fP); +.br \fIint\fP -.RE -.nh -\fBarchive_read_data_skip\fP -.hy -("struct archive *"); +.br +\fB\%archive_read_data_skip\fP(\fI\%struct\ archive\ *\fP); +.br \fIint\fP -.RE -.nh -\fBarchive_read_data_into_buffer\fP -.hy -("struct archive *" "void *" "ssize_t len"); +.br +\fB\%archive_read_data_into_buffer\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *\fP, \fI\%ssize_t\ len\fP); +.br \fIint\fP -.RE -.nh -\fBarchive_read_data_into_fd\fP -.hy -("struct archive *" "int fd"); +.br +\fB\%archive_read_data_into_fd\fP(\fI\%struct\ archive\ *\fP, \fI\%int\ fd\fP); +.br \fIint\fP -.RE -Fo archive_read_extract -Fa "struct archive *" -Fa "struct archive_entry *" -Fa "int flags" -Fc +.br +\fB\%archive_read_extract\fP(\fI\%struct\ archive\ *\fP, \fI\%struct\ archive_entry\ *\fP, \fI\%int\ flags\fP); +.br \fIint\fP -.RE -Fo archive_read_extract2 -Fa "struct archive *src" -Fa "struct archive_entry *" -Fa "struct archive *dest" -Fc +.br +\fB\%archive_read_extract2\fP(\fI\%struct\ archive\ *src\fP, \fI\%struct\ archive_entry\ *\fP, \fI\%struct\ archive\ *dest\fP); +.br \fIvoid\fP -.RE -Fo archive_read_extract_set_progress_callback -Fa "struct archive *" -Fa "void (*func)(void *)" -Fa "void *user_data" -Fc +.br +\fB\%archive_read_extract_set_progress_callback\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ (*func)(void\ *)\fP, \fI\%void\ *user_data\fP); +.br \fIint\fP -.RE -.nh -\fBarchive_read_close\fP -.hy -("struct archive *"); +.br +\fB\%archive_read_close\fP(\fI\%struct\ archive\ *\fP); +.br \fIint\fP -.RE -.nh -\fBarchive_read_finish\fP -.hy -("struct archive *"); +.br +\fB\%archive_read_finish\fP(\fI\%struct\ archive\ *\fP); .SH DESCRIPTION +.ad l These functions provide a complete API for reading streaming archives. The general process is to first create the Tn struct archive @@ -236,244 +215,206 @@ headers and associated data, then close the archive and release all resources. The following summary describes the functions in approximately the order they would be used: +.RS 5 .TP -.nh -\fBarchive_read_new\fP -.hy -(); +\fB\%archive_read_new\fP() Allocates and initializes a Tn struct archive object suitable for reading from an archive. .TP -Xo -.nh -\fBarchive_read_support_compression_all\fP -.hy -(,); -.nh -\fBarchive_read_support_compression_bzip2\fP -.hy -(,); -.nh -\fBarchive_read_support_compression_compress\fP -.hy -(,); -.nh -\fBarchive_read_support_compression_gzip\fP -.hy -(,); -.nh -\fBarchive_read_support_compression_none\fP -.hy -(); -Xc +\fB\%archive_read_support_compression_bzip2\fP(), +\fB\%archive_read_support_compression_compress\fP(), +\fB\%archive_read_support_compression_gzip\fP(), +\fB\%archive_read_support_compression_lzma\fP(), +\fB\%archive_read_support_compression_none\fP(), +\fB\%archive_read_support_compression_xz\fP() Enables auto-detection code and decompression support for the specified compression. +Returns +\fBARCHIVE_OK\fP +if the compression is fully supported, or +\fBARCHIVE_WARN\fP +if the compression is supported only through an external program. +Note that decompression using an external program is usually slower than +decompression through built-in libraries. Note that ``none'' is always enabled by default. -For convenience, -.nh -\fBarchive_read_support_compression_all\fP -.hy -(); -enables all available decompression code. -.TP -.nh -\fBarchive_read_support_compression_program\fP -.hy -(); +.TP +\fB\%archive_read_support_compression_all\fP() +Enables all available decompression filters. +.TP +\fB\%archive_read_support_compression_program\fP() Data is fed through the specified external program before being dearchived. Note that this disables automatic detection of the compression format, so it makes no sense to specify this in conjunction with any other decompression option. .TP -Xo -.nh -\fBarchive_read_support_format_all\fP -.hy -(,); -.nh -\fBarchive_read_support_format_cpio\fP -.hy -(,); -.nh -\fBarchive_read_support_format_empty\fP -.hy -(,); -.nh -\fBarchive_read_support_format_iso9660\fP -.hy -(,); -.nh -\fBarchive_read_support_format_tar\fP -.hy -(,); -.nh -\fBarchive_read_support_format_zip\fP -.hy -(); -Xc +\fB\%archive_read_support_compression_program_signature\fP() +This feeds data through the specified external program +but only if the initial bytes of the data match the specified +signature value. +.TP +\fB\%archive_read_support_format_all\fP(), +\fB\%archive_read_support_format_ar\fP(), +\fB\%archive_read_support_format_cpio\fP(), +\fB\%archive_read_support_format_empty\fP(), +\fB\%archive_read_support_format_iso9660\fP(), +\fB\%archive_read_support_format_mtree\fP(), +\fB\%archive_read_support_format_tar\fP(), +\fB\%archive_read_support_format_zip\fP() Enables support---including auto-detection code---for the specified archive format. For example, -.nh -\fBarchive_read_support_format_tar\fP -.hy -(); +\fB\%archive_read_support_format_tar\fP() enables support for a variety of standard tar formats, old-style tar, ustar, pax interchange format, and many common variants. For convenience, -.nh -\fBarchive_read_support_format_all\fP -.hy -(); +\fB\%archive_read_support_format_all\fP() enables support for all available formats. Only empty archives are supported by default. .TP -.nh -\fBarchive_read_open\fP -.hy -(); +\fB\%archive_read_support_format_raw\fP() +The +``raw'' +format handler allows libarchive to be used to read arbitrary data. +It treats any data stream as an archive with a single entry. +The pathname of this entry is +``data ;'' +all other entry fields are unset. +This is not enabled by +\fB\%archive_read_support_format_all\fP() +in order to avoid erroneous handling of damaged archives. +.TP +\fB\%archive_read_set_filter_options\fP(), +\fB\%archive_read_set_format_options\fP(), +\fB\%archive_read_set_options\fP() +Specifies options that will be passed to currently-registered +filters (including decompression filters) and/or format readers. +The argument is a comma-separated list of individual options. +Individual options have one of the following forms: +.RS 5 +.TP +\fIoption=value\fP +The option/value pair will be provided to every module. +Modules that do not accept an option with this name will ignore it. +.TP +\fIoption\fP +The option will be provided to every module with a value of +``1''. +.TP +\fI!option\fP +The option will be provided to every module with a NULL value. +.TP +\fImodule:option=value\fP, \fImodule:option\fP, \fImodule:!option\fP +As above, but the corresponding option and value will be provided +only to modules whose name matches +\fImodule\fP. +.RE +The return value will be +\fBARCHIVE_OK\fP +if any module accepts the option, or +\fBARCHIVE_WARN\fP +if no module accepted the option, or +\fBARCHIVE_FATAL\fP +if there was a fatal error while attempting to process the option. +.PP +The currently supported options are: +.RS 5 +.TP +Format iso9660 +.RS 5 +.TP +\fBjoliet\fP +Support Joliet extensions. +Defaults to enabled, use +\fB!joliet\fP +to disable. +.RE +.RE +.TP +\fB\%archive_read_open\fP() The same as -.nh -\fBarchive_read_open2\fP -.hy -(,); +\fB\%archive_read_open2\fP(), except that the skip callback is assumed to be .BR NULL. .TP -.nh -\fBarchive_read_open2\fP -.hy -(); +\fB\%archive_read_open2\fP() Freeze the settings, open the archive, and prepare for reading entries. This is the most generic version of this call, which accepts four callback functions. Most clients will want to use -.nh -\fBarchive_read_open_filename\fP -.hy -(,); -.nh -\fBarchive_read_open_FILE\fP -.hy -(,); -.nh -\fBarchive_read_open_fd\fP -.hy -(,); +\fB\%archive_read_open_filename\fP(), +\fB\%archive_read_open_FILE\fP(), +\fB\%archive_read_open_fd\fP(), or -.nh -\fBarchive_read_open_memory\fP -.hy -(); +\fB\%archive_read_open_memory\fP() instead. The library invokes the client-provided functions to obtain raw bytes from the archive. .TP -.nh -\fBarchive_read_open_FILE\fP -.hy -(); +\fB\%archive_read_open_FILE\fP() Like -.nh -\fBarchive_read_open\fP -.hy -(,); +\fB\%archive_read_open\fP(), except that it accepts a -\fI"FILE *"\fP -.RE +\fIFILE *\fP pointer. This function should not be used with tape drives or other devices that require strict I/O blocking. .TP -.nh -\fBarchive_read_open_fd\fP -.hy -(); +\fB\%archive_read_open_fd\fP() Like -.nh -\fBarchive_read_open\fP -.hy -(,); +\fB\%archive_read_open\fP(), except that it accepts a file descriptor and block size rather than a set of function pointers. Note that the file descriptor will not be automatically closed at end-of-archive. This function is safe for use with tape drives or other blocked devices. .TP -.nh -\fBarchive_read_open_file\fP -.hy -(); +\fB\%archive_read_open_file\fP() This is a deprecated synonym for -.nh -\fBarchive_read_open_filename\fP -.hy -(.); -.TP -.nh -\fBarchive_read_open_filename\fP -.hy -(); +\fB\%archive_read_open_filename\fP(). +.TP +\fB\%archive_read_open_filename\fP() Like -.nh -\fBarchive_read_open\fP -.hy -(,); +\fB\%archive_read_open\fP(), except that it accepts a simple filename and a block size. A NULL filename represents standard input. This function is safe for use with tape drives or other blocked devices. .TP -.nh -\fBarchive_read_open_memory\fP -.hy -(); +\fB\%archive_read_open_memory\fP() Like -.nh -\fBarchive_read_open\fP -.hy -(,); +\fB\%archive_read_open\fP(), except that it accepts a pointer and size of a block of memory containing the archive data. .TP -.nh -\fBarchive_read_next_header\fP -.hy -(); +\fB\%archive_read_next_header\fP() Read the header for the next entry and return a pointer to a Tn struct archive_entry. +This is a convenience wrapper around +\fB\%archive_read_next_header2\fP() +that reuses an internal +Tn struct archive_entry +object for each request. .TP -.nh -\fBarchive_read_data\fP -.hy -(); +\fB\%archive_read_next_header2\fP() +Read the header for the next entry and populate the provided +Tn struct archive_entry. +.TP +\fB\%archive_read_data\fP() Read data associated with the header just read. Internally, this is a convenience function that calls -.nh -\fBarchive_read_data_block\fP -.hy -(); +\fB\%archive_read_data_block\fP() and fills any gaps with nulls so that callers see a single continuous stream of data. .TP -.nh -\fBarchive_read_data_block\fP -.hy -(); +\fB\%archive_read_data_block\fP() Return the next available block of data for this entry. Unlike -.nh -\fBarchive_read_data\fP -.hy -(,); +\fB\%archive_read_data\fP(), the -.nh -\fBarchive_read_data_block\fP -.hy -(); +\fB\%archive_read_data_block\fP() function avoids copying data and allows you to correctly handle sparse files, as supported by some archive formats. The library guarantees that offsets will increase and that blocks @@ -482,55 +423,28 @@ Note that the blocks returned from this function can be much larger than the block size read from disk, due to compression and internal buffer optimizations. .TP -.nh -\fBarchive_read_data_skip\fP -.hy -(); +\fB\%archive_read_data_skip\fP() A convenience function that repeatedly calls -.nh -\fBarchive_read_data_block\fP -.hy -(); +\fB\%archive_read_data_block\fP() to skip all of the data for this archive entry. .TP -.nh -\fBarchive_read_data_into_buffer\fP -.hy -(); +\fB\%archive_read_data_into_buffer\fP() This function is deprecated and will be removed. Use -.nh -\fBarchive_read_data\fP -.hy -(); +\fB\%archive_read_data\fP() instead. .TP -.nh -\fBarchive_read_data_into_fd\fP -.hy -(); +\fB\%archive_read_data_into_fd\fP() A convenience function that repeatedly calls -.nh -\fBarchive_read_data_block\fP -.hy -(); +\fB\%archive_read_data_block\fP() to copy the entire entry to the provided file descriptor. .TP -.nh -\fBarchive_read_extract\fP -.hy -(, .nh); -\fBarchive_read_extract_set_skip_file\fP -.hy -(); +\fB\%archive_read_extract\fP(), \fB\%archive_read_extract_set_skip_file\fP() A convenience function that wraps the corresponding \fBarchive_write_disk\fP(3) interfaces. The first call to -.nh -\fBarchive_read_extract\fP -.hy -(); +\fB\%archive_read_extract\fP() creates a restore object using \fBarchive_write_disk_new\fP(3) and @@ -547,15 +461,9 @@ The argument is passed unmodified to \fBarchive_write_disk_set_options\fP(3). .TP -.nh -\fBarchive_read_extract2\fP -.hy -(); +\fB\%archive_read_extract2\fP() This is another version of -.nh -\fBarchive_read_extract\fP -.hy -(); +\fB\%archive_read_extract\fP() that allows you to provide your own restore object. In particular, this allows you to override the standard lookup functions using @@ -563,23 +471,14 @@ using and \fBarchive_write_disk_set_user_lookup\fP(3). Note that -.nh -\fBarchive_read_extract2\fP -.hy -(); +\fB\%archive_read_extract2\fP() does not accept a \fIflags\fP argument; you should use -.nh -\fBarchive_write_disk_set_options\fP -.hy -(); +\fB\%archive_write_disk_set_options\fP() to set the restore options yourself. .TP -.nh -\fBarchive_read_extract_set_progress_callback\fP -.hy -(); +\fB\%archive_read_extract_set_progress_callback\fP() Sets a pointer to a user-defined callback that can be used for updating progress displays during extraction. The progress function will be invoked during the extraction of large @@ -589,32 +488,21 @@ Generally, the data pointed to should include a reference to the archive object and the archive_entry object so that various statistics can be retrieved for the progress display. .TP -.nh -\fBarchive_read_close\fP -.hy -(); +\fB\%archive_read_close\fP() Complete the archive and invoke the close callback. .TP -.nh -\fBarchive_read_finish\fP -.hy -(); +\fB\%archive_read_finish\fP() Invokes -.nh -\fBarchive_read_close\fP -.hy -(); +\fB\%archive_read_close\fP() if it was not invoked manually, then release all resources. Note: In libarchive 1.x, this function was declared to return -\fIvoid,\fP -.RE +\fIvoid ,\fP which made it impossible to detect certain errors when -.nh -\fBarchive_read_close\fP -.hy -(); +\fB\%archive_read_close\fP() was invoked implicitly from this function. The declaration is corrected beginning with libarchive 2.0. +.RE +.PP Note that the library determines most of the relevant information about the archive by inspection. In particular, it automatically detects @@ -623,6 +511,7 @@ or \fBbzip2\fP(1) compression and transparently performs the appropriate decompression. It also automatically detects the archive format. +.PP A complete description of the Tn struct archive and @@ -630,58 +519,39 @@ Tn struct archive_entry objects can be found in the overview manual page for \fBlibarchive\fP(3). .SH CLIENT CALLBACKS +.ad l The callback functions must match the following prototypes: +.RS 5 .IP \fItypedef ssize_t\fP -.RE -Fo archive_read_callback -Fa "struct archive *" -Fa "void *client_data" -Fa "const void **buffer" -Fc +\fB\%archive_read_callback\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *client_data\fP, \fI\%const\ void\ **buffer\fP) .IP \fItypedef int\fP -.RE -Fo archive_skip_callback -Fa "struct archive *" -Fa "void *client_data" -Fa "size_t request" -Fc +\fB\%archive_skip_callback\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *client_data\fP, \fI\%size_t\ request\fP) .IP \fItypedef int\fP -.RE -.nh -\fBarchive_open_callback\fP -.hy -("struct archive *" "void *client_data"); +\fB\%archive_open_callback\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *client_data\fP) .IP \fItypedef int\fP +\fB\%archive_close_callback\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *client_data\fP) .RE -.nh -\fBarchive_close_callback\fP -.hy -("struct archive *" "void *client_data"); +.PP The open callback is invoked by -.nh -\fBarchive_open\fP -.hy -(.); +\fB\%archive_open\fP(). It should return \fBARCHIVE_OK\fP if the underlying file or data source is successfully opened. If the open fails, it should call -.nh -\fBarchive_set_error\fP -.hy -(); +\fB\%archive_set_error\fP() to register an error code and message and return \fBARCHIVE_FATAL\fP. +.PP The read callback is invoked whenever the library requires raw bytes from the archive. The read callback should read data into a buffer, set the -.RS +.RS 4 const void **buffer .RE argument to point to the available data, and @@ -693,12 +563,10 @@ of the data blocks returned. On end-of-file, the read callback should return zero. On error, the read callback should invoke -.nh -\fBarchive_set_error\fP -.hy -(); +\fB\%archive_set_error\fP() to register an error code and message and return -1. +.PP The skip callback is invoked when the library wants to ignore a block of data. The return value is the number of bytes actually @@ -714,20 +582,19 @@ A skip callback can provide significant performance gains when reading uncompressed archives from slow disk drives or other media that can skip quickly. +.PP The close callback is invoked by archive_close when the archive processing is complete. The callback should return \fBARCHIVE_OK\fP on success. On failure, the callback should invoke -.nh -\fBarchive_set_error\fP -.hy -(); +\fB\%archive_set_error\fP() to register an error code and message and return \fBARCHIVE_FATAL.\fP .SH EXAMPLE +.ad l The following illustrates basic usage of the library. In this example, the callback functions are simply wrappers around the standard @@ -736,7 +603,8 @@ the callback functions are simply wrappers around the standard and \fBclose\fP(2) system calls. -.RS +.RS 4 +.nf void list_archive(const char *name) { @@ -780,6 +648,7 @@ myclose(struct archive *a, void *client_data) } .RE .SH RETURN VALUES +.ad l Most functions return zero on success, non-zero on error. The possible return codes include: \fBARCHIVE_OK\fP @@ -794,30 +663,20 @@ and \fBARCHIVE_FATAL\fP (there was a fatal error; the archive should be closed immediately). Detailed error codes and textual descriptions are available from the -.nh -\fBarchive_errno\fP -.hy -(); +\fB\%archive_errno\fP() and -.nh -\fBarchive_error_string\fP -.hy -(); +\fB\%archive_error_string\fP() functions. -.nh -\fBarchive_read_new\fP -.hy -(); +.PP +\fB\%archive_read_new\fP() returns a pointer to a freshly allocated Tn struct archive object. It returns .BR NULL on error. -.nh -\fBarchive_read_data\fP -.hy -(); +.PP +\fB\%archive_read_data\fP() returns a count of bytes actually read or zero at the end of the entry. On error, a value of \fBARCHIVE_FATAL\fP, @@ -825,22 +684,14 @@ On error, a value of or \fBARCHIVE_RETRY\fP is returned and an error code and textual description can be retrieved from the -.nh -\fBarchive_errno\fP -.hy -(); +\fB\%archive_errno\fP() and -.nh -\fBarchive_error_string\fP -.hy -(); +\fB\%archive_error_string\fP() functions. +.PP The library expects the client callbacks to behave similarly. If there is an error, you can use -.nh -\fBarchive_set_error\fP -.hy -(); +\fB\%archive_set_error\fP() to set an appropriate error code and description, then return one of the non-zero values above. (Note that the value eventually returned to the client may @@ -850,22 +701,26 @@ thus most I/O errors eventually cause \fBARCHIVE_FATAL\fP to be returned.) .SH SEE ALSO +.ad l \fBtar\fP(1), \fBarchive\fP(3), \fBarchive_util\fP(3), \fBtar\fP(5) .SH HISTORY +.ad l The -\fBlibarchive\fP +\fB\%libarchive\fP library first appeared in FreeBSD 5.3. .SH AUTHORS +.ad l -nosplit The -\fBlibarchive\fP +\fB\%libarchive\fP library was written by -Tim Kientzle <kientzle@acm.org.> +Tim Kientzle \%<kientzle@acm.org.> .SH BUGS +.ad l Many traditional archiver programs treat empty files as valid empty archives. For example, many implementations of diff --git a/archivers/libarchive/files/doc/man/archive_read_disk.3 b/archivers/libarchive/files/doc/man/archive_read_disk.3 new file mode 100644 index 00000000000..6e10f4f4c68 --- /dev/null +++ b/archivers/libarchive/files/doc/man/archive_read_disk.3 @@ -0,0 +1,300 @@ +.TH archive_read_disk 3 "March 10, 2009" "" +.SH NAME +.ad l +\fB\%archive_read_disk_new\fP, +\fB\%archive_read_disk_set_symlink_logical\fP, +\fB\%archive_read_disk_set_symlink_physical\fP, +\fB\%archive_read_disk_set_symlink_hybrid\fP, +\fB\%archive_read_disk_entry_from_file\fP, +\fB\%archive_read_disk_gname\fP, +\fB\%archive_read_disk_uname\fP, +\fB\%archive_read_disk_set_uname_lookup\fP, +\fB\%archive_read_disk_set_gname_lookup\fP, +\fB\%archive_read_disk_set_standard_lookup\fP, +\fB\%archive_read_close\fP, +\fB\%archive_read_finish\fP +\- functions for reading objects from disk +.SH SYNOPSIS +.ad l +\fB#include <archive.h>\fP +.br +\fIstruct archive *\fP +.br +\fB\%archive_read_disk_new\fP(\fI\%void\fP); +.br +\fIint\fP +.br +\fB\%archive_read_disk_set_symlink_logical\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_read_disk_set_symlink_physical\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_read_disk_set_symlink_hybrid\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_read_disk_gname\fP(\fI\%struct\ archive\ *\fP, \fI\%gid_t\fP); +.br +\fIint\fP +.br +\fB\%archive_read_disk_uname\fP(\fI\%struct\ archive\ *\fP, \fI\%uid_t\fP); +.br +\fIint\fP +.br +\fB\%archive_read_disk_set_gname_lookup\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *\fP, \fI\%const\ char\ *(*lookup)(void\ *,\ gid_t)\fP, \fI\%void\ (*cleanup)(void\ *)\fP); +.br +\fIint\fP +.br +\fB\%archive_read_disk_set_uname_lookup\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *\fP, \fI\%const\ char\ *(*lookup)(void\ *,\ uid_t)\fP, \fI\%void\ (*cleanup)(void\ *)\fP); +.br +\fIint\fP +.br +\fB\%archive_read_disk_set_standard_lookup\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_read_disk_entry_from_file\fP(\fI\%struct\ archive\ *\fP, \fI\%struct\ archive_entry\ *\fP, \fI\%int\ fd\fP, \fI\%const\ struct\ stat\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_read_close\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_read_finish\fP(\fI\%struct\ archive\ *\fP); +.SH DESCRIPTION +.ad l +These functions provide an API for reading information about +objects on disk. +In particular, they provide an interface for populating +Tn struct archive_entry +objects. +.RS 5 +.TP +\fB\%archive_read_disk_new\fP() +Allocates and initializes a +Tn struct archive +object suitable for reading object information from disk. +.TP +\fB\%archive_read_disk_set_symlink_logical\fP(), +\fB\%archive_read_disk_set_symlink_physical\fP(), +\fB\%archive_read_disk_set_symlink_hybrid\fP() +This sets the mode used for handling symbolic links. +The +``logical'' +mode follows all symbolic links. +The +``physical'' +mode does not follow any symbolic links. +The +``hybrid'' +mode currently behaves identically to the +``logical'' +mode. +.TP +\fB\%archive_read_disk_gname\fP(), +\fB\%archive_read_disk_uname\fP() +Returns a user or group name given a gid or uid value. +By default, these always return a NULL string. +.TP +\fB\%archive_read_disk_set_gname_lookup\fP(), +\fB\%archive_read_disk_set_uname_lookup\fP() +These allow you to override the functions used for +user and group name lookups. +You may also provide a +Tn void * +pointer to a private data structure and a cleanup function for +that data. +The cleanup function will be invoked when the +Tn struct archive +object is destroyed or when new lookup functions are registered. +.TP +\fB\%archive_read_disk_set_standard_lookup\fP() +This convenience function installs a standard set of user +and group name lookup functions. +These functions use +\fBgetpwid\fP(3) +and +\fBgetgrid\fP(3) +to convert ids to names, defaulting to NULL if the names cannot +be looked up. +These functions also implement a simple memory cache to reduce +the number of calls to +\fBgetpwid\fP(3) +and +\fBgetgrid\fP(3). +.TP +\fB\%archive_read_disk_entry_from_file\fP() +Populates a +Tn struct archive_entry +object with information about a particular file. +The +Tn archive_entry +object must have already been created with +\fBarchive_entry_new\fP(3) +and at least one of the source path or path fields must already be set. +(If both are set, the source path will be used.) +.PP +Information is read from disk using the path name from the +Tn struct archive_entry +object. +If a file descriptor is provided, some information will be obtained using +that file descriptor, on platforms that support the appropriate +system calls. +.PP +If a pointer to a +Tn struct stat +is provided, information from that structure will be used instead +of reading from the disk where appropriate. +This can provide performance benefits in scenarios where +Tn struct stat +information has already been read from the disk as a side effect +of some other operation. +(For example, directory traversal libraries often provide this information.) +.PP +Where necessary, user and group ids are converted to user and group names +using the currently registered lookup functions above. +This affects the file ownership fields and ACL values in the +Tn struct archive_entry +object. +.TP +\fB\%archive_read_close\fP() +This currently does nothing. +.TP +\fB\%archive_write_finish\fP() +Invokes +\fB\%archive_write_close\fP() +if it was not invoked manually, then releases all resources. +.RE +More information about the +\fIstruct\fP archive +object and the overall design of the library can be found in the +\fBlibarchive\fP(3) +overview. +.SH EXAMPLE +.ad l +The following illustrates basic usage of the library by +showing how to use it to copy an item on disk into an archive. +.RS 4 +.nf +void +file_to_archive(struct archive *a, const char *name) +{ + char buff[8192]; + size_t bytes_read; + struct archive *ard; + struct archive_entry *entry; + int fd; + ard = archive_read_disk_new(); + archive_read_disk_set_standard_lookup(ard); + entry = archive_entry_new(); + fd = open(name, O_RDONLY); + if (fd < 0) + return; + archive_entry_copy_sourcepath(entry, name); + archive_read_disk_entry_from_file(ard, entry, fd, NULL); + archive_write_header(a, entry); + while ((bytes_read = read(fd, buff, sizeof(buff))) > 0) + archive_write_data(a, buff, bytes_read); + archive_write_finish_entry(a); + archive_read_finish(ard); + archive_entry_free(entry); +} +.RE +.SH RETURN VALUES +.ad l +Most functions return +\fBARCHIVE_OK\fP +(zero) on success, or one of several negative +error codes for errors. +Specific error codes include: +\fBARCHIVE_RETRY\fP +for operations that might succeed if retried, +\fBARCHIVE_WARN\fP +for unusual conditions that do not prevent further operations, and +\fBARCHIVE_FATAL\fP +for serious errors that make remaining operations impossible. +The +\fBarchive_errno\fP(3) +and +\fBarchive_error_string\fP(3) +functions can be used to retrieve an appropriate error code and a +textual error message. +(See +\fBarchive_util\fP(3) +for details.) +.PP +\fB\%archive_read_disk_new\fP() +returns a pointer to a newly-allocated +Tn struct archive +object or NULL if the allocation failed for any reason. +.PP +\fB\%archive_read_disk_gname\fP() +and +\fB\%archive_read_disk_uname\fP() +return +Tn const char * +pointers to the textual name or NULL if the lookup failed for any reason. +The returned pointer points to internal storage that +may be reused on the next call to either of these functions; +callers should copy the string if they need to continue accessing it. +.PP +.SH SEE ALSO +.ad l +\fBarchive_read\fP(3), +\fBarchive_write\fP(3), +\fBarchive_write_disk\fP(3), +\fBtar\fP(1), +\fBlibarchive\fP(3) +.SH HISTORY +.ad l +The +\fB\%libarchive\fP +library first appeared in +FreeBSD 5.3. +The +\fB\%archive_read_disk\fP +interface was added to +\fB\%libarchive\fP 2.6 +and first appeared in +FreeBSD 8.0. +.SH AUTHORS +.ad l +-nosplit +The +\fB\%libarchive\fP +library was written by +Tim Kientzle \%<kientzle@freebsd.org.> +.SH BUGS +.ad l +The +``standard'' +user name and group name lookup functions are not the defaults because +\fBgetgrid\fP(3) +and +\fBgetpwid\fP(3) +are sometimes too large for particular applications. +The current design allows the application author to use a more +compact implementation when appropriate. +.PP +The full list of metadata read from disk by +\fB\%archive_read_disk_entry_from_file\fP() +is necessarily system-dependent. +.PP +The +\fB\%archive_read_disk_entry_from_file\fP() +function reads as much information as it can from disk. +Some method should be provided to limit this so that clients who +do not need ACLs, for instance, can avoid the extra work needed +to look up such information. +.PP +This API should provide a set of methods for walking a directory tree. +That would make it a direct parallel of the +\fBarchive_read\fP(3) +API. +When such methods are implemented, the +``hybrid'' +symbolic link mode will make sense. diff --git a/archivers/libarchive/files/doc/man/archive_util.3 b/archivers/libarchive/files/doc/man/archive_util.3 index 6a9b7f562b2..60375aff195 100644 --- a/archivers/libarchive/files/doc/man/archive_util.3 +++ b/archivers/libarchive/files/doc/man/archive_util.3 @@ -1,171 +1,124 @@ .TH archive_util 3 "January 8, 2005" "" .SH NAME -\fBarchive_clear_error\fP, -\fBarchive_compression\fP, -\fBarchive_compression_name\fP, -\fBarchive_copy_error\fP, -\fBarchive_errno\fP, -\fBarchive_error_string\fP, -\fBarchive_format\fP, -\fBarchive_format_name\fP, -\fBarchive_set_error\fP +.ad l +\fB\%archive_clear_error\fP, +\fB\%archive_compression\fP, +\fB\%archive_compression_name\fP, +\fB\%archive_copy_error\fP, +\fB\%archive_errno\fP, +\fB\%archive_error_string\fP, +\fB\%archive_file_count\fP, +\fB\%archive_format\fP, +\fB\%archive_format_name\fP, +\fB\%archive_set_error\fP \- libarchive utility functions .SH SYNOPSIS +.ad l \fB#include <archive.h>\fP .br \fIvoid\fP -.RE -.nh -\fBarchive_clear_error\fP -.hy -("struct archive *"); +.br +\fB\%archive_clear_error\fP(\fI\%struct\ archive\ *\fP); +.br \fIint\fP -.RE -.nh -\fBarchive_compression\fP -.hy -("struct archive *"); +.br +\fB\%archive_compression\fP(\fI\%struct\ archive\ *\fP); +.br \fIconst char *\fP -.RE -.nh -\fBarchive_compression_name\fP -.hy -("struct archive *"); +.br +\fB\%archive_compression_name\fP(\fI\%struct\ archive\ *\fP); +.br \fIvoid\fP -.RE -.nh -\fBarchive_copy_error\fP -.hy -("struct archive *" "struct archive *"); +.br +\fB\%archive_copy_error\fP(\fI\%struct\ archive\ *\fP, \fI\%struct\ archive\ *\fP); +.br \fIint\fP -.RE -.nh -\fBarchive_errno\fP -.hy -("struct archive *"); +.br +\fB\%archive_errno\fP(\fI\%struct\ archive\ *\fP); +.br \fIconst char *\fP -.RE -.nh -\fBarchive_error_string\fP -.hy -("struct archive *"); +.br +\fB\%archive_error_string\fP(\fI\%struct\ archive\ *\fP); +.br \fIint\fP -.RE -.nh -\fBarchive_format\fP -.hy -("struct archive *"); +.br +\fB\%archive_file_count\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_format\fP(\fI\%struct\ archive\ *\fP); +.br \fIconst char *\fP -.RE -.nh -\fBarchive_format_name\fP -.hy -("struct archive *"); +.br +\fB\%archive_format_name\fP(\fI\%struct\ archive\ *\fP); +.br \fIvoid\fP -.RE -Fo archive_set_error -Fa "struct archive *" -Fa "int error_code" -Fa "const char *fmt" -Fa "..." -Fc +.br +\fB\%archive_set_error\fP(\fI\%struct\ archive\ *\fP, \fI\%int\ error_code\fP, \fI\%const\ char\ *fmt\fP, \fI\%...\fP); .SH DESCRIPTION +.ad l These functions provide access to various information about the Tn struct archive object used in the \fBlibarchive\fP(3) library. +.RS 5 .TP -.nh -\fBarchive_clear_error\fP -.hy -(); +\fB\%archive_clear_error\fP() Clears any error information left over from a previous call. Not generally used in client code. .TP -.nh -\fBarchive_compression\fP -.hy -(); +\fB\%archive_compression\fP() Returns a numeric code indicating the current compression. This value is set by -.nh -\fBarchive_read_open\fP -.hy -(.); +\fB\%archive_read_open\fP(). .TP -.nh -\fBarchive_compression_name\fP -.hy -(); +\fB\%archive_compression_name\fP() Returns a text description of the current compression suitable for display. .TP -.nh -\fBarchive_copy_error\fP -.hy -(); +\fB\%archive_copy_error\fP() Copies error information from one archive to another. .TP -.nh -\fBarchive_errno\fP -.hy -(); +\fB\%archive_errno\fP() Returns a numeric error code (see \fBerrno\fP(2)) indicating the reason for the most recent error return. .TP -.nh -\fBarchive_error_string\fP -.hy -(); +\fB\%archive_error_string\fP() Returns a textual error message suitable for display. The error message here is usually more specific than that obtained from passing the result of -.nh -\fBarchive_errno\fP -.hy -(); +\fB\%archive_errno\fP() to \fBstrerror\fP(3). .TP -.nh -\fBarchive_format\fP -.hy -(); +\fB\%archive_file_count\fP() +Returns a count of the number of files processed by this archive object. +The count is incremented by calls to +\fBarchive_write_header\fP() +or +\fBarchive_read_next_header\fP(.) +.TP +\fB\%archive_format\fP() Returns a numeric code indicating the format of the current archive entry. This value is set by a successful call to -.nh -\fBarchive_read_next_header\fP -.hy -(.); +\fB\%archive_read_next_header\fP(). Note that it is common for this value to change from entry to entry. For example, a tar archive might have several entries that utilize GNU tar extensions and several entries that do not. These entries will have different format codes. .TP -.nh -\fBarchive_format_name\fP -.hy -(); +\fB\%archive_format_name\fP() A textual description of the format of the current entry. .TP -.nh -\fBarchive_set_error\fP -.hy -(); +\fB\%archive_set_error\fP() Sets the numeric error code and error description that will be returned by -.nh -\fBarchive_errno\fP -.hy -(); +\fB\%archive_errno\fP() and -.nh -\fBarchive_error_string\fP -.hy -(.); +\fB\%archive_error_string\fP(). This function should be used within I/O callbacks to set system-specific error codes and error descriptions. This function accepts a printf-like format string and arguments. @@ -188,19 +141,23 @@ format specifiers: ``%%''. Field-width specifiers and other printf features are not uniformly supported and should not be used. +.RE .SH SEE ALSO +.ad l \fBarchive_read\fP(3), \fBarchive_write\fP(3), \fBlibarchive\fP(3), \fBprintf\fP(3) .SH HISTORY +.ad l The -\fBlibarchive\fP +\fB\%libarchive\fP library first appeared in FreeBSD 5.3. .SH AUTHORS +.ad l -nosplit The -\fBlibarchive\fP +\fB\%libarchive\fP library was written by -Tim Kientzle <kientzle@acm.org.> +Tim Kientzle \%<kientzle@acm.org.> diff --git a/archivers/libarchive/files/doc/man/archive_write.3 b/archivers/libarchive/files/doc/man/archive_write.3 index 3c02d5222d4..b485dcf796a 100644 --- a/archivers/libarchive/files/doc/man/archive_write.3 +++ b/archivers/libarchive/files/doc/man/archive_write.3 @@ -1,190 +1,152 @@ .TH archive_write 3 "May 11, 2008" "" .SH NAME -\fBarchive_write_new\fP, -\fBarchive_write_set_format_cpio\fP, -\fBarchive_write_set_format_pax\fP, -\fBarchive_write_set_format_pax_restricted\fP, -\fBarchive_write_set_format_shar\fP, -\fBarchive_write_set_format_shar_binary\fP, -\fBarchive_write_set_format_ustar\fP, -\fBarchive_write_get_bytes_per_block\fP, -\fBarchive_write_set_bytes_per_block\fP, -\fBarchive_write_set_bytes_in_last_block\fP, -\fBarchive_write_set_compression_bzip2\fP, -\fBarchive_write_set_compression_compress\fP, -\fBarchive_write_set_compression_gzip\fP, -\fBarchive_write_set_compression_none\fP, -\fBarchive_write_set_compression_program\fP, -\fBarchive_write_open\fP, -\fBarchive_write_open_fd\fP, -\fBarchive_write_open_FILE\fP, -\fBarchive_write_open_filename\fP, -\fBarchive_write_open_memory\fP, -\fBarchive_write_header\fP, -\fBarchive_write_data\fP, -\fBarchive_write_finish_entry\fP, -\fBarchive_write_close\fP, -\fBarchive_write_finish\fP +.ad l +\fB\%archive_write_new\fP, +\fB\%archive_write_set_format_cpio\fP, +\fB\%archive_write_set_format_pax\fP, +\fB\%archive_write_set_format_pax_restricted\fP, +\fB\%archive_write_set_format_shar\fP, +\fB\%archive_write_set_format_shar_binary\fP, +\fB\%archive_write_set_format_ustar\fP, +\fB\%archive_write_get_bytes_per_block\fP, +\fB\%archive_write_set_bytes_per_block\fP, +\fB\%archive_write_set_bytes_in_last_block\fP, +\fB\%archive_write_set_compression_bzip2\fP, +\fB\%archive_write_set_compression_compress\fP, +\fB\%archive_write_set_compression_gzip\fP, +\fB\%archive_write_set_compression_none\fP, +\fB\%archive_write_set_compression_program\fP, +\fB\%archive_write_set_compressor_options\fP, +\fB\%archive_write_set_format_options\fP, +\fB\%archive_write_set_options\fP, +\fB\%archive_write_open\fP, +\fB\%archive_write_open_fd\fP, +\fB\%archive_write_open_FILE\fP, +\fB\%archive_write_open_filename\fP, +\fB\%archive_write_open_memory\fP, +\fB\%archive_write_header\fP, +\fB\%archive_write_data\fP, +\fB\%archive_write_finish_entry\fP, +\fB\%archive_write_close\fP, +\fB\%archive_write_finish\fP \- functions for creating archives .SH SYNOPSIS +.ad l \fB#include <archive.h>\fP .br \fIstruct archive *\fP -.RE -.nh -\fBarchive_write_new\fP -.hy -("void"); +.br +\fB\%archive_write_new\fP(\fI\%void\fP); +.br \fIint\fP -.RE -.nh -\fBarchive_write_get_bytes_per_block\fP -.hy -("struct archive *"); +.br +\fB\%archive_write_get_bytes_per_block\fP(\fI\%struct\ archive\ *\fP); +.br \fIint\fP -.RE -.nh -\fBarchive_write_set_bytes_per_block\fP -.hy -("struct archive *" "int bytes_per_block"); +.br +\fB\%archive_write_set_bytes_per_block\fP(\fI\%struct\ archive\ *\fP, \fI\%int\ bytes_per_block\fP); +.br \fIint\fP -.RE -.nh -\fBarchive_write_set_bytes_in_last_block\fP -.hy -("struct archive *" "int"); +.br +\fB\%archive_write_set_bytes_in_last_block\fP(\fI\%struct\ archive\ *\fP, \fI\%int\fP); +.br \fIint\fP -.RE -.nh -\fBarchive_write_set_compression_bzip2\fP -.hy -("struct archive *"); +.br +\fB\%archive_write_set_compression_bzip2\fP(\fI\%struct\ archive\ *\fP); +.br \fIint\fP -.RE -.nh -\fBarchive_write_set_compression_compress\fP -.hy -("struct archive *"); +.br +\fB\%archive_write_set_compression_compress\fP(\fI\%struct\ archive\ *\fP); +.br \fIint\fP -.RE -.nh -\fBarchive_write_set_compression_gzip\fP -.hy -("struct archive *"); +.br +\fB\%archive_write_set_compression_gzip\fP(\fI\%struct\ archive\ *\fP); +.br \fIint\fP -.RE -.nh -\fBarchive_write_set_compression_none\fP -.hy -("struct archive *"); +.br +\fB\%archive_write_set_compression_none\fP(\fI\%struct\ archive\ *\fP); +.br \fIint\fP -.RE -Fo archive_write_set_compression_program -Fa "struct archive *" -Fa "const char * cmd" -Fc +.br +\fB\%archive_write_set_compression_program\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ char\ *\ cmd\fP); +.br \fIint\fP -.RE -.nh -\fBarchive_write_set_format_cpio\fP -.hy -("struct archive *"); +.br +\fB\%archive_write_set_format_cpio\fP(\fI\%struct\ archive\ *\fP); +.br \fIint\fP -.RE -.nh -\fBarchive_write_set_format_pax\fP -.hy -("struct archive *"); +.br +\fB\%archive_write_set_format_pax\fP(\fI\%struct\ archive\ *\fP); +.br \fIint\fP -.RE -.nh -\fBarchive_write_set_format_pax_restricted\fP -.hy -("struct archive *"); +.br +\fB\%archive_write_set_format_pax_restricted\fP(\fI\%struct\ archive\ *\fP); +.br \fIint\fP -.RE -.nh -\fBarchive_write_set_format_shar\fP -.hy -("struct archive *"); +.br +\fB\%archive_write_set_format_shar\fP(\fI\%struct\ archive\ *\fP); +.br \fIint\fP -.RE -.nh -\fBarchive_write_set_format_shar_binary\fP -.hy -("struct archive *"); +.br +\fB\%archive_write_set_format_shar_binary\fP(\fI\%struct\ archive\ *\fP); +.br \fIint\fP -.RE -.nh -\fBarchive_write_set_format_ustar\fP -.hy -("struct archive *"); +.br +\fB\%archive_write_set_format_ustar\fP(\fI\%struct\ archive\ *\fP); +.br \fIint\fP -.RE -Fo archive_write_open -Fa "struct archive *" -Fa "void *client_data" -Fa "archive_open_callback *" -Fa "archive_write_callback *" -Fa "archive_close_callback *" -Fc +.br +\fB\%archive_write_set_format_options\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ char\ *\fP); +.br \fIint\fP -.RE -.nh -\fBarchive_write_open_fd\fP -.hy -("struct archive *" "int fd"); +.br +\fB\%archive_write_set_compressor_options\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ char\ *\fP); +.br \fIint\fP -.RE -.nh -\fBarchive_write_open_FILE\fP -.hy -("struct archive *" "FILE *file"); +.br +\fB\%archive_write_set_options\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ char\ *\fP); +.br \fIint\fP -.RE -.nh -\fBarchive_write_open_filename\fP -.hy -("struct archive *" "const char *filename"); +.br +\fB\%archive_write_open\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *client_data\fP, \fI\%archive_open_callback\ *\fP, \fI\%archive_write_callback\ *\fP, \fI\%archive_close_callback\ *\fP); +.br \fIint\fP -.RE -Fo archive_write_open_memory -Fa "struct archive *" -Fa "void *buffer" -Fa "size_t bufferSize" -Fa "size_t *outUsed" -Fc +.br +\fB\%archive_write_open_fd\fP(\fI\%struct\ archive\ *\fP, \fI\%int\ fd\fP); +.br \fIint\fP -.RE -.nh -\fBarchive_write_header\fP -.hy -("struct archive *" "struct archive_entry *"); +.br +\fB\%archive_write_open_FILE\fP(\fI\%struct\ archive\ *\fP, \fI\%FILE\ *file\fP); +.br +\fIint\fP +.br +\fB\%archive_write_open_filename\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ char\ *filename\fP); +.br +\fIint\fP +.br +\fB\%archive_write_open_memory\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *buffer\fP, \fI\%size_t\ bufferSize\fP, \fI\%size_t\ *outUsed\fP); +.br +\fIint\fP +.br +\fB\%archive_write_header\fP(\fI\%struct\ archive\ *\fP, \fI\%struct\ archive_entry\ *\fP); +.br \fIssize_t\fP -.RE -.nh -\fBarchive_write_data\fP -.hy -("struct archive *" "const void *" "size_t"); +.br +\fB\%archive_write_data\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ void\ *\fP, \fI\%size_t\fP); +.br \fIint\fP -.RE -.nh -\fBarchive_write_finish_entry\fP -.hy -("struct archive *"); +.br +\fB\%archive_write_finish_entry\fP(\fI\%struct\ archive\ *\fP); +.br \fIint\fP -.RE -.nh -\fBarchive_write_close\fP -.hy -("struct archive *"); +.br +\fB\%archive_write_close\fP(\fI\%struct\ archive\ *\fP); +.br \fIint\fP -.RE -.nh -\fBarchive_write_finish\fP -.hy -("struct archive *"); +.br +\fB\%archive_write_finish\fP(\fI\%struct\ archive\ *\fP); .SH DESCRIPTION +.ad l These functions provide a complete API for creating streaming archive files. The general process is to first create the @@ -193,19 +155,14 @@ object, set any desired options, initialize the archive, append entries, then close the archive and release all resources. The following summary describes the functions in approximately the order they are ordinarily used: +.RS 5 .TP -.nh -\fBarchive_write_new\fP -.hy -(); +\fB\%archive_write_new\fP() Allocates and initializes a Tn struct archive object suitable for writing a tar archive. .TP -.nh -\fBarchive_write_set_bytes_per_block\fP -.hy -(); +\fB\%archive_write_set_bytes_per_block\fP() Sets the block size used for writing the archive data. Every call to the write callback function, except possibly the last one, will use this value for the length. @@ -217,18 +174,12 @@ The default is to use a block size of 10240 bytes and to pad the last block. Note that a block size of zero will suppress internal blocking and cause writes to be sent directly to the write callback as they occur. .TP -.nh -\fBarchive_write_get_bytes_per_block\fP -.hy -(); +\fB\%archive_write_get_bytes_per_block\fP() Retrieve the block size to be used for writing. A value of -1 here indicates that the library should use default values. A value of zero indicates that internal blocking is suppressed. .TP -.nh -\fBarchive_write_set_bytes_in_last_block\fP -.hy -(); +\fB\%archive_write_set_bytes_in_last_block\fP() Sets the block size used for writing the last block. If this value is zero, the last block will be padded to the same size as the other blocks. @@ -238,48 +189,22 @@ For compressed output, any padding generated by this option is applied only after the compression. The uncompressed data is always unpadded. The default is to pad the last block to the full block size (note that -.nh -\fBarchive_write_open_filename\fP -.hy -(); +\fB\%archive_write_open_filename\fP() will set this based on the file type). Unlike the other ``set'' functions, this function can be called after the archive is opened. .TP -.nh -\fBarchive_write_get_bytes_in_last_block\fP -.hy -(); +\fB\%archive_write_get_bytes_in_last_block\fP() Retrieve the currently-set value for last block size. A value of -1 here indicates that the library should use default values. .TP -Xo -.nh -\fBarchive_write_set_format_cpio\fP -.hy -(,); -.nh -\fBarchive_write_set_format_pax\fP -.hy -(,); -.nh -\fBarchive_write_set_format_pax_restricted\fP -.hy -(,); -.nh -\fBarchive_write_set_format_shar\fP -.hy -(,); -.nh -\fBarchive_write_set_format_shar_binary\fP -.hy -(,); -.nh -\fBarchive_write_set_format_ustar\fP -.hy -(); -Xc +\fB\%archive_write_set_format_cpio\fP(), +\fB\%archive_write_set_format_pax\fP(), +\fB\%archive_write_set_format_pax_restricted\fP(), +\fB\%archive_write_set_format_shar\fP(), +\fB\%archive_write_set_format_shar_binary\fP(), +\fB\%archive_write_set_format_ustar\fP() Sets the format that will be used for the archive. The library can write POSIX octet-oriented cpio format archives, @@ -304,152 +229,153 @@ is the library default; this is the same as pax format, but suppresses the pax extended header for most normal files. In most cases, this will result in ordinary ustar archives. .TP -Xo -.nh -\fBarchive_write_set_compression_bzip2\fP -.hy -(,); -.nh -\fBarchive_write_set_compression_compress\fP -.hy -(,); -.nh -\fBarchive_write_set_compression_gzip\fP -.hy -(,); -.nh -\fBarchive_write_set_compression_none\fP -.hy -(); -Xc +\fB\%archive_write_set_compression_bzip2\fP(), +\fB\%archive_write_set_compression_compress\fP(), +\fB\%archive_write_set_compression_gzip\fP(), +\fB\%archive_write_set_compression_none\fP() The resulting archive will be compressed as specified. Note that the compressed output is always properly blocked. .TP -.nh -\fBarchive_write_set_compression_program\fP -.hy -(); +\fB\%archive_write_set_compression_program\fP() The archive will be fed into the specified compression program. The output of that program is blocked and written to the client write callbacks. .TP -.nh -\fBarchive_write_open\fP -.hy -(); +\fB\%archive_write_set_compressor_options\fP(), +\fB\%archive_write_set_format_options\fP(), +\fB\%archive_write_set_options\fP() +Specifies options that will be passed to the currently-enabled +compressor and/or format writer. +The argument is a comma-separated list of individual options. +Individual options have one of the following forms: +.RS 5 +.TP +\fIoption=value\fP +The option/value pair will be provided to every module. +Modules that do not accept an option with this name will ignore it. +.TP +\fIoption\fP +The option will be provided to every module with a value of +``1''. +.TP +\fI!option\fP +The option will be provided to every module with a NULL value. +.TP +\fImodule:option=value\fP, \fImodule:option\fP, \fImodule:!option\fP +As above, but the corresponding option and value will be provided +only to modules whose name matches +\fImodule\fP. +.RE +The return value will be +\fBARCHIVE_OK\fP +if any module accepts the option, or +\fBARCHIVE_WARN\fP +if no module accepted the option, or +\fBARCHIVE_FATAL\fP +if there was a fatal error while attempting to process the option. +.PP +The currently supported options are: +.RS 5 +.TP +Compressor gzip +.RS 5 +.TP +\fBcompression-level\fP +The value is interpreted as a decimal integer specifying the +gzip compression level. +.RE +.TP +Compressor xz +.RS 5 +.TP +\fBcompression-level\fP +The value is interpreted as a decimal integer specifying the +compression level. +.RE +.TP +Format mtree +.RS 5 +.TP +\fBcksum\fP, \fBdevice\fP, \fBflags\fP, \fBgid\fP, \fBgname\fP, \fBindent\fP, \fBlink\fP, \fBmd5\fP, \fBmode\fP, \fBnlink\fP, \fBrmd160\fP, \fBsha1\fP, \fBsha256\fP, \fBsha384\fP, \fBsha512\fP, \fBsize\fP, \fBtime\fP, \fBuid\fP, \fBuname\fP +Enable a particular keyword in the mtree output. +Prefix with an exclamation mark to disable the corresponding keyword. +The default is equivalent to +``device, flags, gid, gname, link, mode, nlink, size, time, type, uid, uname''. +.TP +\fBall\fP +Enables all of the above keywords. +.TP +\fBuse-set\fP +Enables generation of +\fB/set\fP +lines that specify default values for the following files and/or directories. +.TP +\fBindent\fP +XXX needs explanation XXX +.RE +.RE +.TP +\fB\%archive_write_open\fP() Freeze the settings, open the archive, and prepare for writing entries. This is the most generic form of this function, which accepts pointers to three callback functions which will be invoked by the compression layer to write the constructed archive. .TP -.nh -\fBarchive_write_open_fd\fP -.hy -(); +\fB\%archive_write_open_fd\fP() A convenience form of -.nh -\fBarchive_write_open\fP -.hy -(); +\fB\%archive_write_open\fP() that accepts a file descriptor. The -.nh -\fBarchive_write_open_fd\fP -.hy -(); +\fB\%archive_write_open_fd\fP() function is safe for use with tape drives or other block-oriented devices. .TP -.nh -\fBarchive_write_open_FILE\fP -.hy -(); +\fB\%archive_write_open_FILE\fP() A convenience form of -.nh -\fBarchive_write_open\fP -.hy -(); +\fB\%archive_write_open\fP() that accepts a -\fI"FILE *"\fP -.RE +\fIFILE *\fP pointer. Note that -.nh -\fBarchive_write_open_FILE\fP -.hy -(); +\fB\%archive_write_open_FILE\fP() is not safe for writing to tape drives or other devices that require correct blocking. .TP -.nh -\fBarchive_write_open_file\fP -.hy -(); +\fB\%archive_write_open_file\fP() A deprecated synonym for -.nh -\fBarchive_write_open_filename\fP -.hy -(.); -.TP -.nh -\fBarchive_write_open_filename\fP -.hy -(); +\fB\%archive_write_open_filename\fP(). +.TP +\fB\%archive_write_open_filename\fP() A convenience form of -.nh -\fBarchive_write_open\fP -.hy -(); +\fB\%archive_write_open\fP() that accepts a filename. A NULL argument indicates that the output should be written to standard output; an argument of ``-'' will open a file with that name. If you have not invoked -.nh -\fBarchive_write_set_bytes_in_last_block\fP -.hy -(,); +\fB\%archive_write_set_bytes_in_last_block\fP(), then -.nh -\fBarchive_write_open_filename\fP -.hy -(); +\fB\%archive_write_open_filename\fP() will adjust the last-block padding depending on the file: it will enable padding when writing to standard output or to a character or block device node, it will disable padding otherwise. You can override this by manually invoking -.nh -\fBarchive_write_set_bytes_in_last_block\fP -.hy -(); +\fB\%archive_write_set_bytes_in_last_block\fP() before calling -.nh -\fBarchive_write_open\fP -.hy -(.); +\fB\%archive_write_open\fP(). The -.nh -\fBarchive_write_open_filename\fP -.hy -(); +\fB\%archive_write_open_filename\fP() function is safe for use with tape drives or other block-oriented devices. .TP -.nh -\fBarchive_write_open_memory\fP -.hy -(); +\fB\%archive_write_open_memory\fP() A convenience form of -.nh -\fBarchive_write_open\fP -.hy -(); +\fB\%archive_write_open\fP() that accepts a pointer to a block of memory that will receive the archive. The final -\fI"size_t *"\fP -.RE +\fIsize_t *\fP argument points to a variable that will be updated after each write to reflect how much of the buffer is currently in use. @@ -457,10 +383,7 @@ You should be careful to ensure that this variable remains allocated until after the archive is closed. .TP -.nh -\fBarchive_write_header\fP -.hy -(); +\fB\%archive_write_header\fP() Build and write a header using the data in the provided Tn struct archive_entry structure. @@ -470,107 +393,72 @@ for information on creating and populating Tn struct archive_entry objects. .TP -.nh -\fBarchive_write_data\fP -.hy -(); +\fB\%archive_write_data\fP() Write data corresponding to the header just written. Returns number of bytes written or -1 on error. .TP -.nh -\fBarchive_write_finish_entry\fP -.hy -(); +\fB\%archive_write_finish_entry\fP() Close out the entry just written. In particular, this writes out the final padding required by some formats. Ordinarily, clients never need to call this, as it is called automatically by -.nh -\fBarchive_write_next_header\fP -.hy -(); +\fB\%archive_write_next_header\fP() and -.nh -\fBarchive_write_close\fP -.hy -(); +\fB\%archive_write_close\fP() as needed. .TP -.nh -\fBarchive_write_close\fP -.hy -(); +\fB\%archive_write_close\fP() Complete the archive and invoke the close callback. .TP -.nh -\fBarchive_write_finish\fP -.hy -(); +\fB\%archive_write_finish\fP() Invokes -.nh -\fBarchive_write_close\fP -.hy -(); +\fB\%archive_write_close\fP() if it was not invoked manually, then releases all resources. Note that this function was declared to return \fIvoid\fP -.RE in libarchive 1.x, which made it impossible to detect errors when -.nh -\fBarchive_write_close\fP -.hy -(); +\fB\%archive_write_close\fP() was invoked implicitly from this function. This is corrected beginning with libarchive 2.0. +.RE More information about the \fIstruct\fP archive object and the overall design of the library can be found in the \fBlibarchive\fP(3) overview. .SH IMPLEMENTATION +.ad l Compression support is built-in to libarchive, which uses zlib and bzlib to handle gzip and bzip2 compression, respectively. .SH CLIENT CALLBACKS +.ad l To use this library, you will need to define and register callback functions that will be invoked to write data to the resulting archive. These functions are registered by calling -.nh -\fBarchive_write_open\fP -.hy -(:); +\fB\%archive_write_open\fP(): +.RS 5 .IP \fItypedef int\fP +\fB\%archive_open_callback\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *client_data\fP) .RE -.nh -\fBarchive_open_callback\fP -.hy -("struct archive *" "void *client_data"); +.PP The open callback is invoked by -.nh -\fBarchive_write_open\fP -.hy -(.); +\fB\%archive_write_open\fP(). It should return \fBARCHIVE_OK\fP if the underlying file or data source is successfully opened. If the open fails, it should call -.nh -\fBarchive_set_error\fP -.hy -(); +\fB\%archive_set_error\fP() to register an error code and message and return \fBARCHIVE_FATAL\fP. +.RS 5 .IP \fItypedef ssize_t\fP +\fB\%archive_write_callback\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *client_data\fP, \fI\%const\ void\ *buffer\fP, \fI\%size_t\ length\fP) .RE -Fo archive_write_callback -Fa "struct archive *" -Fa "void *client_data" -Fa "void *buffer" -Fa "size_t length" -Fc +.PP The write callback is invoked whenever the library needs to write raw bytes to the archive. For correct blocking, each call to the write callback function @@ -581,32 +469,26 @@ This is especially critical when writing archives to tape drives. On success, the write callback should return the number of bytes actually written. On error, the callback should invoke -.nh -\fBarchive_set_error\fP -.hy -(); +\fB\%archive_set_error\fP() to register an error code and message and return -1. +.RS 5 .IP \fItypedef int\fP +\fB\%archive_close_callback\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *client_data\fP) .RE -.nh -\fBarchive_close_callback\fP -.hy -("struct archive *" "void *client_data"); +.PP The close callback is invoked by archive_close when the archive processing is complete. The callback should return \fBARCHIVE_OK\fP on success. On failure, the callback should invoke -.nh -\fBarchive_set_error\fP -.hy -(); +\fB\%archive_set_error\fP() to register an error code and message and return \fBARCHIVE_FATAL.\fP .SH EXAMPLE +.ad l The following sketch illustrates basic usage of the library. In this example, the callback functions are simply wrappers around the standard @@ -615,7 +497,11 @@ the callback functions are simply wrappers around the standard and \fBclose\fP(2) system calls. -.RS +.RS 4 +.nf +#ifdef __linux__ +#define _FILE_OFFSET_BITS 64 +#endif #include <sys/stat.h> #include <archive.h> #include <archive_entry.h> @@ -637,7 +523,7 @@ myopen(struct archive *a, void *client_data) return (ARCHIVE_FATAL); } ssize_t -mywrite(struct archive *a, void *client_data, void *buff, size_t n) +mywrite(struct archive *a, void *client_data, const void *buff, size_t n) { struct mydata *mydata = client_data; return (write(mydata->fd, buff, n)); @@ -692,6 +578,7 @@ int main(int argc, const char **argv) } .RE .SH RETURN VALUES +.ad l Most functions return \fBARCHIVE_OK\fP (zero) on success, or one of several non-zero @@ -704,98 +591,66 @@ for unusual conditions that do not prevent further operations, and \fBARCHIVE_FATAL\fP for serious errors that make remaining operations impossible. The -.nh -\fBarchive_errno\fP -.hy -(); +\fB\%archive_errno\fP() and -.nh -\fBarchive_error_string\fP -.hy -(); +\fB\%archive_error_string\fP() functions can be used to retrieve an appropriate error code and a textual error message. -.nh -\fBarchive_write_new\fP -.hy -(); +.PP +\fB\%archive_write_new\fP() returns a pointer to a newly-allocated Tn struct archive object. -.nh -\fBarchive_write_data\fP -.hy -(); +.PP +\fB\%archive_write_data\fP() returns a count of the number of bytes actually written. On error, -1 is returned and the -.nh -\fBarchive_errno\fP -.hy -(); +\fB\%archive_errno\fP() and -.nh -\fBarchive_error_string\fP -.hy -(); +\fB\%archive_error_string\fP() functions will return appropriate values. Note that if the client-provided write callback function returns a non-zero value, that error will be propagated back to the caller through whatever API function resulted in that call, which may include -.nh -\fBarchive_write_header\fP -.hy -(,); -.nh -\fBarchive_write_data\fP -.hy -(,); -.nh -\fBarchive_write_close\fP -.hy -(,); +\fB\%archive_write_header\fP(), +\fB\%archive_write_data\fP(), +\fB\%archive_write_close\fP(), or -.nh -\fBarchive_write_finish\fP -.hy -(.); +\fB\%archive_write_finish\fP(). The client callback can call -.nh -\fBarchive_set_error\fP -.hy -(); +\fB\%archive_set_error\fP() to provide values that can then be retrieved by -.nh -\fBarchive_errno\fP -.hy -(); +\fB\%archive_errno\fP() and -.nh -\fBarchive_error_string\fP -.hy -(.); +\fB\%archive_error_string\fP(). .SH SEE ALSO +.ad l \fBtar\fP(1), \fBlibarchive\fP(3), \fBtar\fP(5) .SH HISTORY +.ad l The -\fBlibarchive\fP +\fB\%libarchive\fP library first appeared in FreeBSD 5.3. .SH AUTHORS +.ad l -nosplit The -\fBlibarchive\fP +\fB\%libarchive\fP library was written by -Tim Kientzle <kientzle@acm.org.> +Tim Kientzle \%<kientzle@acm.org.> .SH BUGS +.ad l There are many peculiar bugs in historic tar implementations that may cause certain programs to reject archives written by this library. For example, several historic implementations calculated header checksums incorrectly and will thus reject valid archives; GNU tar does not fully support pax interchange format; some old tar implementations required specific field terminations. +.PP The default pax interchange format eliminates most of the historic tar limitations and provides a generic key/value attribute facility for vendor-defined extensions. @@ -808,7 +663,7 @@ and for device numbers that exceed the range supported by the backwards-compatible ustar header. These keys are compatible with Joerg Schilling's -\fBstar\fP +\fB\%star\fP archiver. Other implementations may not recognize these keys and will thus be unable to correctly restore device nodes with large device numbers from archives diff --git a/archivers/libarchive/files/doc/man/archive_write_disk.3 b/archivers/libarchive/files/doc/man/archive_write_disk.3 index e48292d0e47..a58181e23d1 100644 --- a/archivers/libarchive/files/doc/man/archive_write_disk.3 +++ b/archivers/libarchive/files/doc/man/archive_write_disk.3 @@ -1,131 +1,93 @@ -.TH archive_write_disk 3 "March 2, 2007" "" +.TH archive_write_disk 3 "August 5, 2008" "" .SH NAME -\fBarchive_write_disk_new\fP, -\fBarchive_write_disk_set_options\fP, -\fBarchive_write_disk_set_skip_file\fP, -\fBarchive_write_disk_set_group_lookup\fP, -\fBarchive_write_disk_set_standard_lookup\fP, -\fBarchive_write_disk_set_user_lookup\fP, -\fBarchive_write_header\fP, -\fBarchive_write_data\fP, -\fBarchive_write_finish_entry\fP, -\fBarchive_write_close\fP, -\fBarchive_write_finish\fP +.ad l +\fB\%archive_write_disk_new\fP, +\fB\%archive_write_disk_set_options\fP, +\fB\%archive_write_disk_set_skip_file\fP, +\fB\%archive_write_disk_set_group_lookup\fP, +\fB\%archive_write_disk_set_standard_lookup\fP, +\fB\%archive_write_disk_set_user_lookup\fP, +\fB\%archive_write_header\fP, +\fB\%archive_write_data\fP, +\fB\%archive_write_finish_entry\fP, +\fB\%archive_write_close\fP, +\fB\%archive_write_finish\fP \- functions for creating objects on disk .SH SYNOPSIS +.ad l \fB#include <archive.h>\fP .br \fIstruct archive *\fP -.RE -.nh -\fBarchive_write_disk_new\fP -.hy -("void"); +.br +\fB\%archive_write_disk_new\fP(\fI\%void\fP); +.br \fIint\fP -.RE -.nh -\fBarchive_write_disk_set_options\fP -.hy -("struct archive *" "int flags"); +.br +\fB\%archive_write_disk_set_options\fP(\fI\%struct\ archive\ *\fP, \fI\%int\ flags\fP); +.br \fIint\fP -.RE -.nh -\fBarchive_write_disk_set_skip_file\fP -.hy -("struct archive *" "dev_t" "ino_t"); +.br +\fB\%archive_write_disk_set_skip_file\fP(\fI\%struct\ archive\ *\fP, \fI\%dev_t\fP, \fI\%ino_t\fP); +.br \fIint\fP -.RE -Fo archive_write_disk_set_group_lookup -Fa "struct archive *" -Fa "void *" -Fa "gid_t (*)(void *, const char *gname, gid_t gid)" -Fa "void (*cleanup)(void *)" -Fc +.br +\fB\%archive_write_disk_set_group_lookup\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *\fP, \fI\%gid_t\ (*)(void\ *,\ const\ char\ *gname,\ gid_t\ gid)\fP, \fI\%void\ (*cleanup)(void\ *)\fP); +.br \fIint\fP -.RE -.nh -\fBarchive_write_disk_set_standard_lookup\fP -.hy -("struct archive *"); +.br +\fB\%archive_write_disk_set_standard_lookup\fP(\fI\%struct\ archive\ *\fP); +.br \fIint\fP -.RE -Fo archive_write_disk_set_user_lookup -Fa "struct archive *" -Fa "void *" -Fa "uid_t (*)(void *, const char *uname, uid_t uid)" -Fa "void (*cleanup)(void *)" -Fc +.br +\fB\%archive_write_disk_set_user_lookup\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *\fP, \fI\%uid_t\ (*)(void\ *,\ const\ char\ *uname,\ uid_t\ uid)\fP, \fI\%void\ (*cleanup)(void\ *)\fP); +.br \fIint\fP -.RE -.nh -\fBarchive_write_header\fP -.hy -("struct archive *" "struct archive_entry *"); +.br +\fB\%archive_write_header\fP(\fI\%struct\ archive\ *\fP, \fI\%struct\ archive_entry\ *\fP); +.br \fIssize_t\fP -.RE -.nh -\fBarchive_write_data\fP -.hy -("struct archive *" "const void *" "size_t"); +.br +\fB\%archive_write_data\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ void\ *\fP, \fI\%size_t\fP); +.br \fIint\fP -.RE -.nh -\fBarchive_write_finish_entry\fP -.hy -("struct archive *"); +.br +\fB\%archive_write_finish_entry\fP(\fI\%struct\ archive\ *\fP); +.br \fIint\fP -.RE -.nh -\fBarchive_write_close\fP -.hy -("struct archive *"); +.br +\fB\%archive_write_close\fP(\fI\%struct\ archive\ *\fP); +.br \fIint\fP -.RE -.nh -\fBarchive_write_finish\fP -.hy -("struct archive *"); +.br +\fB\%archive_write_finish\fP(\fI\%struct\ archive\ *\fP); .SH DESCRIPTION +.ad l These functions provide a complete API for creating objects on disk from Tn struct archive_entry descriptions. They are most naturally used when extracting objects from an archive using the -.nh -\fBarchive_read\fP -.hy -(); +\fB\%archive_read\fP() interface. The general process is to read Tn struct archive_entry objects from an archive, then write those objects to a Tn struct archive object created using the -.nh -\fBarchive_write_disk\fP -.hy -(); +\fB\%archive_write_disk\fP() family functions. This interface is deliberately very similar to the -.nh -\fBarchive_write\fP -.hy -(); +\fB\%archive_write\fP() interface used to write objects to a streaming archive. +.RS 5 .TP -.nh -\fBarchive_write_disk_new\fP -.hy -(); +\fB\%archive_write_disk_new\fP() Allocates and initializes a Tn struct archive object suitable for writing objects to disk. .TP -.nh -\fBarchive_write_disk_set_skip_file\fP -.hy -(); +\fB\%archive_write_disk_set_skip_file\fP() Records the device and inode numbers of a file that should not be overwritten. This is typically used to ensure that an extraction process does not @@ -133,12 +95,10 @@ overwrite the archive from which objects are being read. This capability is technically unnecessary but can be a significant performance optimization in practice. .TP -.nh -\fBarchive_write_disk_set_options\fP -.hy -(); +\fB\%archive_write_disk_set_options\fP() The options field consists of a bitwise OR of one or more of the following values: +.RS 5 .TP \fBARCHIVE_EXTRACT_OWNER\fP The user and group IDs should be set on the restored file. @@ -214,17 +174,10 @@ always cause an error, regardless of this flag. Scan data for blocks of NUL bytes and try to recreate them with holes. This results in sparse files, independent of whether the archive format supports or uses them. +.RE .TP -Xo -.nh -\fBarchive_write_disk_set_group_lookup\fP -.hy -(,); -.nh -\fBarchive_write_disk_set_user_lookup\fP -.hy -(); -Xc +\fB\%archive_write_disk_set_group_lookup\fP(), +\fB\%archive_write_disk_set_user_lookup\fP() The Tn struct archive_entry objects contain both names and ids that can be used to identify users @@ -243,10 +196,7 @@ The cleanup function will be invoked when the Tn struct archive object is destroyed. .TP -.nh -\fBarchive_write_disk_set_standard_lookup\fP -.hy -(); +\fB\%archive_write_disk_set_standard_lookup\fP() This convenience function installs a standard set of user and group lookup functions. These functions use @@ -261,10 +211,7 @@ the number of calls to and \fBgetgrnam\fP(3). .TP -.nh -\fBarchive_write_header\fP -.hy -(); +\fB\%archive_write_header\fP() Build and write a header using the data in the provided Tn struct archive_entry structure. @@ -274,55 +221,35 @@ for information on creating and populating Tn struct archive_entry objects. .TP -.nh -\fBarchive_write_data\fP -.hy -(); +\fB\%archive_write_data\fP() Write data corresponding to the header just written. Returns number of bytes written or -1 on error. .TP -.nh -\fBarchive_write_finish_entry\fP -.hy -(); +\fB\%archive_write_finish_entry\fP() Close out the entry just written. Ordinarily, clients never need to call this, as it is called automatically by -.nh -\fBarchive_write_next_header\fP -.hy -(); +\fB\%archive_write_next_header\fP() and -.nh -\fBarchive_write_close\fP -.hy -(); +\fB\%archive_write_close\fP() as needed. .TP -.nh -\fBarchive_write_close\fP -.hy -(); +\fB\%archive_write_close\fP() Set any attributes that could not be set during the initial restore. For example, directory timestamps are not restored initially because restoring a subsequent file would alter that timestamp. Similarly, non-writable directories are initially created with write permissions (so that their contents can be restored). The -\fBarchive_write_disk_new\fP +\fB\%archive_write_disk_new\fP library maintains a list of all such deferred attributes and sets them when this function is invoked. .TP -.nh -\fBarchive_write_finish\fP -.hy -(); +\fB\%archive_write_finish\fP() Invokes -.nh -\fBarchive_write_close\fP -.hy -(); +\fB\%archive_write_close\fP() if it was not invoked manually, then releases all resources. +.RE More information about the \fIstruct\fP archive object and the overall design of the library can be found in the @@ -331,6 +258,7 @@ overview. Many of these functions are also documented under \fBarchive_write\fP(3). .SH RETURN VALUES +.ad l Most functions return \fBARCHIVE_OK\fP (zero) on success, or one of several non-zero @@ -343,74 +271,56 @@ for unusual conditions that do not prevent further operations, and \fBARCHIVE_FATAL\fP for serious errors that make remaining operations impossible. The -.nh -\fBarchive_errno\fP -.hy -(); +\fB\%archive_errno\fP() and -.nh -\fBarchive_error_string\fP -.hy -(); +\fB\%archive_error_string\fP() functions can be used to retrieve an appropriate error code and a textual error message. -.nh -\fBarchive_write_disk_new\fP -.hy -(); +.PP +\fB\%archive_write_disk_new\fP() returns a pointer to a newly-allocated Tn struct archive object. -.nh -\fBarchive_write_data\fP -.hy -(); +.PP +\fB\%archive_write_data\fP() returns a count of the number of bytes actually written. On error, -1 is returned and the -.nh -\fBarchive_errno\fP -.hy -(); +\fB\%archive_errno\fP() and -.nh -\fBarchive_error_string\fP -.hy -(); +\fB\%archive_error_string\fP() functions will return appropriate values. .SH SEE ALSO +.ad l \fBarchive_read\fP(3), \fBarchive_write\fP(3), \fBtar\fP(1), \fBlibarchive\fP(3) .SH HISTORY +.ad l The -\fBlibarchive\fP +\fB\%libarchive\fP library first appeared in FreeBSD 5.3. The -\fBarchive_write_disk\fP +\fB\%archive_write_disk\fP interface was added to -\fBlibarchive\fP 2.0 +\fB\%libarchive\fP 2.0 and first appeared in FreeBSD 6.3. .SH AUTHORS +.ad l -nosplit The -\fBlibarchive\fP +\fB\%libarchive\fP library was written by -Tim Kientzle <kientzle@acm.org.> +Tim Kientzle \%<kientzle@acm.org.> .SH BUGS +.ad l Directories are actually extracted in two distinct phases. Directories are created during -.nh -\fBarchive_write_header\fP -.hy -(,); +\fB\%archive_write_header\fP(), but final permissions are not set until -.nh -\fBarchive_write_close\fP -.hy -(.); +\fB\%archive_write_close\fP(). This separation is necessary to correctly handle borderline cases such as a non-writable directory containing files, but can cause unexpected results. @@ -419,24 +329,20 @@ restored until the archive is closed. If you use \fBchdir\fP(2) to change the current directory between calls to -.nh -\fBarchive_read_extract\fP -.hy -(); +\fB\%archive_read_extract\fP() or before calling -.nh -\fBarchive_read_close\fP -.hy -(,); +\fB\%archive_read_close\fP(), you may confuse the permission-setting logic with the result that directory permissions are restored incorrectly. +.PP The library attempts to create objects with filenames longer than \fBPATH_MAX\fP by creating prefixes of the full path and changing the current directory. Currently, this logic is limited in scope; the fixup pass does not work correctly for such objects and the symlink security check option disables the support for very long pathnames. +.PP Restoring the path \fIaa/../bb\fP does create each intermediate directory. @@ -449,10 +355,12 @@ with a single request. Of course, this does not work if the \fBARCHIVE_EXTRACT_NODOTDOT\fP option is specified. +.PP Implicit directories are always created obeying the current umask. Explicit objects are created obeying the current umask unless \fBARCHIVE_EXTRACT_PERM\fP is specified, in which case they current umask is ignored. +.PP SGID and SUID bits are restored only if the correct user and group could be set. If @@ -461,6 +369,7 @@ is not specified, then no attempt is made to set the ownership. In this case, SGID and SUID bits are restored only if the user and group of the final object happen to match those specified in the entry. +.PP The ``standard'' user-id and group-id lookup functions are not the defaults because @@ -470,7 +379,8 @@ and are sometimes too large for particular applications. The current design allows the application author to use a more compact implementation when appropriate. +.PP There should be a corresponding -\fBarchive_read_disk\fP +\fB\%archive_read_disk\fP interface that walks a directory heirarchy and returns archive entry objects. diff --git a/archivers/libarchive/files/doc/man/bsdcpio.1 b/archivers/libarchive/files/doc/man/bsdcpio.1 index fa1bd729c86..76217b457c5 100644 --- a/archivers/libarchive/files/doc/man/bsdcpio.1 +++ b/archivers/libarchive/files/doc/man/bsdcpio.1 @@ -1,35 +1,40 @@ .TH BSDCPIO 1 "December 21, 2007" "" .SH NAME -\fBcpio\fP +.ad l +\fB\%cpio\fP \- copy files to and from archives .SH SYNOPSIS +.ad l .br -\fBcpio\fP +\fB\%cpio\fP {\fB\-i\fP} [\fIoptions\fP] [\fIpattern\fP ...] [\fI<\fP archive] .br -\fBcpio\fP +\fB\%cpio\fP {\fB\-o\fP} [\fIoptions\fP] \fI<\fP name-list [\fI>\fP archive] .br -\fBcpio\fP +\fB\%cpio\fP {\fB\-p\fP} [\fIoptions\fP] \fIdest-dir\fP \fI<\fP name-list .SH DESCRIPTION -\fBcpio\fP +.ad l +\fB\%cpio\fP copies files between archives and directories. This implementation can extract from tar, pax, cpio, zip, jar, ar, and ISO 9660 cdrom images and can create tar, pax, cpio, ar, and shar archives. +.PP The first option to -\fBcpio\fP +\fB\%cpio\fP is a mode indicator from the following list: +.RS 5 .TP \fB\-i\fP Input. @@ -50,9 +55,17 @@ on standard output (unless overriden) containing the specified items. Pass-through. Read a list of filenames from standard input and copy the files to the specified directory. +.RE +.PP .SH OPTIONS +.ad l Unless specifically stated otherwise, options are applicable in all operating modes. +.RS 5 +.TP +\fB\-0\fP +Read filenames separated by NUL characters instead of newlines. +This is necessary if any of the filenames being read might contain newlines. .TP \fB\-A\fP (o mode only) @@ -102,6 +115,8 @@ Ignore files that match (o mode only) Produce the output archive in the specified format. Supported formats include: +.PP +.RS 5 .TP \fIcpio\fP Synonym for @@ -118,6 +133,8 @@ The POSIX.1 pax format, an extension of the ustar format. .TP \fIustar\fP The POSIX.1 tar format. +.RE +.PP The default format is \fIodc\fP. See @@ -127,6 +144,13 @@ formats currently supported by the underlying \fBlibarchive\fP(3) library. .TP +\fB\-H\fP \fIformat\fP +Synonym for +\fB\--format\fP. +.TP +\fB\-h\fP, \fB\--help\fP +Print usage information. +.TP \fB\-I\fP \fIfile\fP Read archive from \fIfile\fP. @@ -142,6 +166,16 @@ This allows extraction via symbolic links and path names containing Sq .. in the name. .TP +\fB\-J\fP +(o mode only) +Compress the file with xz-compatible compression before writing it. +In input mode, this option is ignored; xz compression is recognized +automatically on input. +.TP +\fB\-j\fP +Synonym for +\fB\-y\fP. +.TP \fB\-L\fP (o and p modes) All symbolic links will be followed. @@ -153,11 +187,32 @@ With this option, the target of the link will be archived or copied instead. Create links from the target directory to the original files, instead of copying. .TP +\fB\-lzma\fP +(o mode only) +Compress the file with lzma-compatible compression before writing it. +In input mode, this option is ignored; lzma compression is recognized +automatically on input. +.TP \fB\-m\fP (i and p modes) Set file modification time on created files to match those in the source. .TP +\fB\-n\fP +(i mode, only with +\fB\-t\fP) +Display numeric uid and gid. +By default, +\fB\%cpio\fP +displays the user and group names when they are provided in the +archive, or looks up the user and group names in the system +password database. +.TP +\fB\-no-preserve-owner\fP +(i mode only) +Do not attempt to restore file ownership. +This is the default when run by non-root users. +.TP \fB\-O\fP \fIfile\fP Write archive to \fIfile\fP. @@ -170,6 +225,11 @@ See above for description. Pass-through mode. See above for description. .TP +\fB\-preserve-owner\fP +(i mode only) +Restore file ownership. +This is the default when run by the root user. +.TP \fB\--quiet\fP Suppress unnecessary messages. .TP @@ -239,9 +299,12 @@ compression is recognized automatically on input. Compress the archive with gzip-compatible compression before writing it. In input mode, this option is ignored; gzip compression is recognized automatically on input. +.RE .SH ENVIRONMENT +.ad l The following environment variables affect the execution of -\fB:\fP +\fB\%cpio\fP: +.RS 5 .TP .B LANG The locale to use. @@ -254,11 +317,14 @@ The timezone to use when displaying dates. See \fBenviron\fP(7) for more information. +.RE .SH EXIT STATUS +.ad l The \fBcpio\fP utility exits 0 on success, and >0 if an error occurs. .SH EXAMPLES +.ad l The -\fBcpio\fP +\fB\%cpio\fP command is traditionally used to copy file heirarchies in conjunction with the \fBfind\fP(1) @@ -267,9 +333,10 @@ The first example here simply copies all files from \fIsrc\fP to \fIdest\fP: -.RS -\fBcpio\fP find \fIsrc\fP | \fBcpio\fP \fB\-pmud\fP \fIdest\fP +.RS 4 +\fB\%find\fP \fIsrc\fP | \fB\%cpio\fP \fB\-pmud\fP \fIdest\fP .RE +.PP By carefully selecting options to the \fBfind\fP(1) command and combining it with other standard utilities, @@ -279,21 +346,24 @@ This next example copies files from to \fIdest\fP that are more than 2 days old and whose names match a particular pattern: -.RS -\fBcpio\fP find \fIsrc\fP \fB\-mtime\fP \fI+2\fP | \fINm\fP grep foo[bar] | \fBcpio\fP \fB\-pdmu\fP \fIdest\fP +.RS 4 +\fB\%find\fP \fIsrc\fP \fB\-mtime\fP \fI+2\fP | \fB\%grep\fP foo[bar] | \fB\%cpio\fP \fB\-pdmu\fP \fIdest\fP .RE +.PP This example copies files from \fIsrc\fP to \fIdest\fP that are more than 2 days old and which contain the word -Do foobar Dc: -.RS -\fBcpio\fP find \fIsrc\fP \fB\-mtime\fP \fI+2\fP | \fINm\fP xargs \fBcpio\fP grep -l foobar | \fBcpio\fP \fB\-pdmu\fP \fIdest\fP +``foobar'': +.RS 4 +\fB\%find\fP \fIsrc\fP \fB\-mtime\fP \fI+2\fP | \fB\%xargs\fP \fB\%grep\fP -l foobar | \fB\%cpio\fP \fB\-pdmu\fP \fIdest\fP .RE .SH COMPATIBILITY +.ad l The mode options i, o, and p and the options a, B, c, d, f, l, m, r, t, u, and v comply with SUSv2. +.PP The old POSIX.1 standard specified that only \fB\-i\fP, \fB\-o\fP, @@ -320,6 +390,7 @@ with the standard. For best compatibility, scripts should limit themselves to the standard syntax. .SH SEE ALSO +.ad l \fBbzip2\fP(1), \fBtar\fP(1), \fBgzip\fP(1), @@ -330,19 +401,22 @@ standard syntax. \fBlibarchive-formats\fP(5), \fBtar\fP(5) .SH STANDARDS +.ad l There is no current POSIX standard for the cpio command; it appeared in ISO/IEC 9945-1:1996 (``POSIX.1'') but was dropped from IEEE Std 1003.1-2001 (``POSIX.1''). +.PP The cpio, ustar, and pax interchange file formats are defined by IEEE Std 1003.1-2001 (``POSIX.1'') for the pax command. .SH HISTORY +.ad l The original -\fBcpio\fP +\fB\%cpio\fP and -\fBfind\fP +\fB\%find\fP utilities were written by Dick Haight while working in AT&T's Unix Support Group. They first appeared in 1977 in PWB/UNIX 1.0, the @@ -350,14 +424,16 @@ They first appeared in 1977 in PWB/UNIX 1.0, the system developed for use within AT&T. They were first released outside of AT&T as part of System III Unix in 1981. As a result, -\fBcpio\fP +\fB\%cpio\fP actually predates -\fBtar\fP, +\fB\%tar\fP, even though it was not well-known outside of AT&T until some time later. +.PP This is a complete re-implementation based on the \fBlibarchive\fP(3) library. .SH BUGS +.ad l The cpio archive format has several basic limitations: It does not store user and group names, only numbers. As a result, it cannot be reliably used to transfer diff --git a/archivers/libarchive/files/doc/man/bsdtar.1 b/archivers/libarchive/files/doc/man/bsdtar.1 index c1088d9e861..bd9f6189829 100644 --- a/archivers/libarchive/files/doc/man/bsdtar.1 +++ b/archivers/libarchive/files/doc/man/bsdtar.1 @@ -1,43 +1,49 @@ -.TH BSDTAR 1 "May 15, 2008" "" +.TH BSDTAR 1 "Oct 12, 2009" "" .SH NAME -\fBtar\fP +.ad l +\fB\%tar\fP \- manipulate tape archives .SH SYNOPSIS +.ad l .br -\fBtar\fP +\fB\%tar\fP [\fIbundled-flags\fP <args>] [<\fIfile\fP> | <\fIpattern\fP> ...] .br -\fBtar\fP +\fB\%tar\fP {\fB\-c\fP} [\fIoptions\fP] [\fIfiles\fP | \fIdirectories\fP] .br -\fBtar\fP +\fB\%tar\fP {\fB\-r\fP | \fB\-u\fP} \fB\-f\fP \fIarchive-file\fP [\fIoptions\fP] [\fIfiles\fP | \fIdirectories\fP] .br -\fBtar\fP +\fB\%tar\fP {\fB\-t\fP | \fB\-x\fP} [\fIoptions\fP] [\fIpatterns\fP] .SH DESCRIPTION -\fBtar\fP +.ad l +\fB\%tar\fP creates and manipulates streaming archive files. This implementation can extract from tar, pax, cpio, zip, jar, ar, and ISO 9660 cdrom images and can create tar, pax, cpio, ar, and shar archives. +.PP The first synopsis form shows a ``bundled'' option word. This usage is provided for compatibility with historical implementations. See COMPATIBILITY below for details. +.PP The other synopsis forms show the preferred usage. The first option to -\fBtar\fP +\fB\%tar\fP is a mode indicator from the following list: +.RS 5 .TP \fB\-c\fP Create a new archive containing the specified items. @@ -69,6 +75,8 @@ Extract to disk from the archive. If a file with the same name appears more than once in the archive, each copy will be extracted, with later copies overwriting (replacing) earlier copies. +.RE +.PP In \fB\-c\fP, \fB\-r\fP, @@ -77,6 +85,7 @@ or mode, each specified file or directory is added to the archive in the order specified on the command line. By default, the contents of each directory are also archived. +.PP In extract or list mode, the entire command line is read and parsed before the archive is opened. The pathnames or patterns on the command line indicate @@ -85,35 +94,37 @@ Patterns are shell-style globbing patterns as documented in \fBtcsh\fP(1). .SH OPTIONS +.ad l Unless specifically stated otherwise, options are applicable in all operating modes. +.RS 5 .TP \fB@\fP \fIarchive\fP (c and r mode only) The specified archive is opened and the entries in it will be appended to the current archive. As a simple example, -.RS -\fBtar\fP \fB\-c\fP \fB\-f\fP \fI-\fP \fInewfile\fP \fB@\fP \fIoriginal.tar\fP +.RS 4 +\fB\%tar\fP \fB\-c\fP \fB\-f\fP \fI-\fP \fInewfile\fP \fB@\fP \fIoriginal.tar\fP .RE writes a new archive to standard output containing a file \fInewfile\fP and all of the entries from \fIoriginal.tar\fP. In contrast, -.RS -\fBtar\fP \fB\-c\fP \fB\-f\fP \fI-\fP \fInewfile\fP \fIoriginal.tar\fP +.RS 4 +\fB\%tar\fP \fB\-c\fP \fB\-f\fP \fI-\fP \fInewfile\fP \fIoriginal.tar\fP .RE creates a new archive with only two entries. Similarly, -.RS -\fBtar\fP \fB\-czf\fP \fI-\fP \fB\--format\fP \fBpax\fP \fB@\fP \fI-\fP +.RS 4 +\fB\%tar\fP \fB\-czf\fP \fI-\fP \fB\--format\fP \fBpax\fP \fB@\fP \fI-\fP .RE reads an archive from standard input (whose format will be determined automatically) and converts it into a gzip-compressed pax-format archive on stdout. In this way, -\fBtar\fP +\fB\%tar\fP can be used to convert archives from one format to another. .TP \fB\-b\fP \fIblocksize\fP @@ -128,27 +139,24 @@ the following files. In x mode, change directories after opening the archive but before extracting entries from the archive. .TP -\fB\--check-links\fP (\fB\-W\fP \fBcheck-links\fP) +\fB\--check-links\fP (c and r modes only) Issue a warning message unless all links to each file are archived. .TP -\fB\--chroot\fP (\fB\-W\fP \fBchroot\fP) +\fB\--chroot\fP (x mode only) -.nh -\fBchroot\fP -.hy -(); +\fB\%chroot\fP() to the current directory after processing any \fB\-C\fP options and before extracting any files. .TP -\fB\--exclude\fP \fIpattern\fP (\fB\-W\fP \fBexclude\fP=\fIpattern\fP) +\fB\--exclude\fP \fIpattern\fP Do not process files or directories that match the specified pattern. Note that exclusions take precedence over patterns or filenames specified on the command line. .TP -\fB\--format\fP \fIformat\fP (\fB\-W\fP \fBformat\fP=\fIformat\fP) +\fB\--format\fP \fIformat\fP (c, r, u mode only) Use the specified format for the created archive. Supported formats include @@ -188,7 +196,7 @@ Synonym for Synonym for \fB\-T\fP. .TP -\fB\--include\fP \fIpattern\fP (\fB\-W\fP \fBinclude\fP=\fIpattern\fP) +\fB\--include\fP \fIpattern\fP Process only files or directories that match the specified pattern. Note that exclusions specified with \fB\--exclude\fP @@ -199,8 +207,8 @@ The \fB\--include\fP option is especially useful when filtering archives. For example, the command -.RS -\fBtar\fP \fB\-c\fP \fB\-f\fP \fInew.tar\fP \fB\--include='*foo*'\fP \fB@\fP \fIold.tgz\fP +.RS 4 +\fB\%tar\fP \fB\-c\fP \fB\-f\fP \fInew.tar\fP \fB\--include='*foo*'\fP \fB@\fP \fIold.tgz\fP .RE creates a new archive \fInew.tar\fP @@ -215,7 +223,7 @@ Compress the resulting archive with \fBbzip2\fP(1). In extract or list modes, this option is ignored. Note that, unlike other -\fBtar\fP +\fB\%tar\fP implementations, this implementation recognizes bzip2 compression automatically when reading archives. .TP @@ -225,7 +233,7 @@ Do not overwrite existing files. In particular, if a file appears more than once in an archive, later copies will not overwrite earlier copies. .TP -\fB\--keep-newer-files\fP (\fB\-W\fP \fBkeep-newer-files\fP) +\fB\--keep-newer-files\fP (x mode only) Do not overwrite existing files that are newer than the versions appearing in the archive being extracted. @@ -250,33 +258,33 @@ By default, the modification time is set to the time stored in the archive. (c, r, u modes only) Do not recursively archive the contents of directories. .TP -\fB\--newer\fP \fIdate\fP (\fB\-W\fP \fBnewer\fP=\fIdate\fP) +\fB\--newer\fP \fIdate\fP (c, r, u modes only) Only include files and directories newer than the specified date. This compares ctime entries. .TP -\fB\--newer-mtime\fP \fIdate\fP (\fB\-W\fP \fBnewer-mtime\fP=\fIdate\fP) +\fB\--newer-mtime\fP \fIdate\fP (c, r, u modes only) Like \fB\--newer\fP, except it compares mtime entries instead of ctime entries. .TP -\fB\--newer-than\fP \fIfile\fP (\fB\-W\fP \fBnewer-than\fP=\fIfile\fP) +\fB\--newer-than\fP \fIfile\fP (c, r, u modes only) Only include files and directories newer than the specified file. This compares ctime entries. .TP -\fB\--newer-mtime-than\fP \fIfile\fP (\fB\-W\fP \fBnewer-mtime-than\fP=\fIfile\fP) +\fB\--newer-mtime-than\fP \fIfile\fP (c, r, u modes only) Like \fB\--newer-than\fP, except it compares mtime entries instead of ctime entries. .TP -\fB\--nodump\fP (\fB\-W\fP \fBnodump\fP) +\fB\--nodump\fP (c and r modes only) Honor the nodump file flag by skipping this file. .TP -\fB\--null\fP (\fB\-W\fP \fBnull\fP) +\fB\--null\fP (use with \fB\-I\fP, \fB\-T\fP, @@ -317,17 +325,102 @@ the archive will be discarded. A synonym for \fB\--format\fP \fIustar\fP .TP -\fB\--one-file-system\fP (\fB\-W\fP \fBone-file-system\fP) +\fB\--one-file-system\fP (c, r, and u modes) Do not cross mount points. .TP +\fB\--options\fP \fIoptions\fP +Select optional behaviors for particular modules. +The argument is a text string containing comma-separated +keywords and values. +These are passed to the modules that handle particular +formats to control how those formats will behave. +Each option has one of the following forms: +.RS 5 +.TP +\fIkey=value\fP +The key will be set to the specified value in every module that supports it. +Modules that do not support this key will ignore it. +.TP +\fIkey\fP +The key will be enabled in every module that supports it. +This is equivalent to +\fIkey\fP \fB=1\fP. +.TP +\fI!key\fP +The key will be disabled in every module that supports it. +.TP +\fImodule:key=value\fP, \fImodule:key\fP, \fImodule:!key\fP +As above, but the corresponding key and value will be provided +only to modules whose name matches +\fImodule\fP. +.RE +The currently supported modules and keys are: +.RS 5 +.TP +\fBiso9660:joliet\fP +Support Joliet extensions. +This is enabled by default, use +\fB!joliet\fP +or +\fBiso9660:!joliet\fP +to disable. +.TP +\fBiso9660:rockridge\fP +Support Rock Ridge extensions. +This is enabled by default, use +\fB!rockridge\fP +or +\fBiso9660:!rockridge\fP +to disable. +.TP +\fBgzip:compression-level\fP +A decimal integer from 0 to 9 specifying the gzip compression level. +.TP +\fBxz:compression-level\fP +A decimal integer from 0 to 9 specifying the xz compression level. +.TP +\fBmtree:\fP \fIkeyword\fP +The mtree writer module allows you to specify which mtree keywords +will be included in the output. +Supported keywords include: +\fBcksum\fP, \fBdevice\fP, \fBflags\fP, \fBgid\fP, \fBgname\fP, \fBindent\fP, +\fBlink\fP, \fBmd5\fP, \fBmode\fP, \fBnlink\fP, \fBrmd160\fP, \fBsha1\fP, \fBsha256\fP, +\fBsha384\fP, \fBsha512\fP, \fBsize\fP, \fBtime\fP, \fBuid\fP, \fBuname\fP. +The default is equivalent to: +``device, flags, gid, gname, link, mode, nlink, size, time, type, uid, uname''. +.TP +\fBmtree:all\fP +Enables all of the above keywords. +You can also use +\fBmtree:!all\fP +to disable all keywords. +.TP +\fBmtree:use-set\fP +Enable generation of +\fB/set\fP +lines in the output. +.TP +\fBmtree:indent\fP +Produce human-readable output by indenting options and splitting lines +to fit into 80 columns. +.TP +\fBzip:compression\fP=\fItype\fP +Use +\fItype\fP +as compression method. +Supported values are store (uncompressed) and deflate (gzip algorithm). +.RE +If a provided option is not supported by any module, that +is a fatal error. +.TP \fB\-P\fP Preserve pathnames. By default, absolute pathnames (those that begin with a / character) have the leading slash removed both when creating archives and extracting from them. Also, -\fBtar\fP +\fB\%tar\fP will refuse to extract archive entries whose pathnames contain \fI\& ..\fP or whose target directory would be altered by a symlink. @@ -339,11 +432,11 @@ Preserve file permissions. Attempt to restore the full permissions, including owner, file modes, file flags and ACLs, if available, for each item extracted from the archive. By default, newly-created files are owned by the user running -\fB,\fP +\fB\%tar\fP, the file mode is restored for newly-created regular files, and all other types of entries receive default permissions. If -\fBtar\fP +\fB\%tar\fP is being run by root, the default is to restore the owner unless the \fB\-o\fP option is also specified. @@ -365,8 +458,8 @@ For every block on disk, check first if it contains only NULL bytes and seek over it otherwise. This works similiar to the conv=sparse option of dd. .TP -\fB\--strip-components\fP \fIcount\fP (\fB\-W\fP \fBstrip-components\fP=\fIcount\fP) -(x and t mode only) +\fB\--strip-components\fP \fIcount\fP +(x mode only) Remove the specified number of leading path elements. Pathnames with fewer elements will be silently skipped. Note that the pathname is edited after checking inclusion/exclusion patterns @@ -375,10 +468,20 @@ but before security checks. \fB\-s\fP \fIpattern\fP Modify file or archive member names according to \fIpattern\fP. -The pattern has the format /old/new/[gps]. -old is a basic regular expression. -If it doesn't apply, the pattern is skipped. -new is the replacement string of the matched part. +The pattern has the format +\fI/old/new/\fP [gps] +where +\fIold\fP +is a basic regular expression, +\fInew\fP +is the replacement string of the matched part, +and the optional trailing letters modify +how the replacement is handled. +If +\fIold\fP +is not matched, the pattern is skipped. +Within +\fInew\fP, ~ is substituted with the match, \1 to \9 with the content of the corresponding captured group. The optional trailing g specifies that matching should continue @@ -391,11 +494,11 @@ standard error. .TP \fB\-T\fP \fIfilename\fP In x or t mode, -\fBtar\fP +\fB\%tar\fP will read the list of names to be extracted from \fIfilename\fP. In c mode, -\fBtar\fP +\fB\%tar\fP will read names to be archived from \fIfilename\fP. The special name @@ -414,7 +517,7 @@ also disables the special handling of lines containing (x mode only) Unlink files before creating them. Without this option, -\fBtar\fP +\fB\%tar\fP overwrites existing files, which preserves existing hardlinks. With this option, existing hardlinks will be broken, as will any symlink that would affect the location of an extracted file. @@ -427,27 +530,23 @@ instead of using the builtin compression support. \fB\-v\fP Produce verbose output. In create and extract modes, -\fBtar\fP +\fB\%tar\fP will list each file name as it is read from or written to the archive. In list mode, -\fBtar\fP +\fB\%tar\fP will produce output similar to that of \fBls\fP(1). Additional \fB\-v\fP options will provide additional detail. .TP -\fB\-W\fP \fIlongopt=value\fP -Long options (preceded by -\fB\--\fP) -are only supported directly on systems that have the -\fBgetopt_long\fP(3) -function. -The -\fB\-W\fP -option can be used to access long options on systems that -do not support this function. +\fB\--version\fP +Print version of +\fB\%tar\fP +and +\fB\%libarchive\fP, +and exit. .TP \fB\-w\fP Ask for confirmation for every action. @@ -464,7 +563,7 @@ Compress the resulting archive with \fBbzip2\fP(1). In extract or list modes, this option is ignored. Note that, unlike other -\fBtar\fP +\fB\%tar\fP implementations, this implementation recognizes bzip2 compression automatically when reading archives. .TP @@ -474,7 +573,7 @@ Compress the resulting archive with \fBgzip\fP(1). In extract or list modes, this option is ignored. Note that, unlike other -\fBtar\fP +\fB\%tar\fP implementations, this implementation recognizes gzip compression automatically when reading archives. .TP @@ -484,12 +583,15 @@ Compress the resulting archive with \fBcompress\fP(1). In extract or list modes, this option is ignored. Note that, unlike other -\fBtar\fP +\fB\%tar\fP implementations, this implementation recognizes compress compression automatically when reading archives. +.RE .SH ENVIRONMENT +.ad l The following environment variables affect the execution of -\fB:\fP +\fB\%tar\fP: +.RS 5 .TP .B LANG The locale to use. @@ -508,7 +610,10 @@ The timezone to use when displaying dates. See \fBenviron\fP(7) for more information. +.RE .SH FILES +.ad l +.RS 5 .TP .B /dev/sa0 The default tape device, if not overridden by the @@ -516,9 +621,12 @@ The default tape device, if not overridden by the environment variable or the \fB\-f\fP option. +.RE .SH EXIT STATUS +.ad l The \fBtar\fP utility exits 0 on success, and >0 if an error occurs. .SH EXAMPLES +.ad l The following creates a new archive called \fIfile.tar.gz\fP @@ -526,45 +634,50 @@ that contains two files \fIsource.c\fP and \fIsource.h\fP: -.RS -\fBtar\fP \fB\-czf\fP \fIfile.tar.gz\fP \fIsource.c\fP \fIsource.h\fP +.RS 4 +\fB\%tar\fP \fB\-czf\fP \fIfile.tar.gz\fP \fIsource.c\fP \fIsource.h\fP .RE +.PP To view a detailed table of contents for this archive: -.RS -\fBtar\fP \fB\-tvf\fP \fIfile.tar.gz\fP +.RS 4 +\fB\%tar\fP \fB\-tvf\fP \fIfile.tar.gz\fP .RE +.PP To extract all entries from the archive on the default tape drive: -.RS -\fBtar\fP \fB\-x\fP +.RS 4 +\fB\%tar\fP \fB\-x\fP .RE +.PP To examine the contents of an ISO 9660 cdrom image: -.RS -\fBtar\fP \fB\-tf\fP \fIimage.iso\fP +.RS 4 +\fB\%tar\fP \fB\-tf\fP \fIimage.iso\fP .RE +.PP To move file hierarchies, invoke -\fBtar\fP +\fB\%tar\fP as -.RS -\fBtar\fP \fB\-cf\fP \fI-\fP \fB\-C\fP \fIsrcdir\\fP. | \fBtar\fP \fB\-xpf\fP \fI-\fP \fB\-C\fP \fIdestdir\fP +.RS 4 +\fB\%tar\fP \fB\-cf\fP \fI-\fP \fB\-C\fP \fIsrcdir\\fP. | \fB\%tar\fP \fB\-xpf\fP \fI-\fP \fB\-C\fP \fIdestdir\fP .RE or more traditionally -.RS -cd srcdir \&; \fBtar\fP \fB\-cf\fP \fI-\\fP. | (cd destdir \&; \fBtar\fP \fB\-xpf\fP \fI-\fP) +.RS 4 +cd srcdir \&; \fB\%tar\fP \fB\-cf\fP \fI-\\fP. | (cd destdir \&; \fB\%tar\fP \fB\-xpf\fP \fI-\fP) .RE +.PP In create mode, the list of files and directories to be archived can also include directory change instructions of the form \fB-C\fP \fIfoo/baz\fP and archive inclusions of the form \fB@\fP \fIarchive-file\fP. For example, the command line -.RS -\fBtar\fP \fB\-c\fP \fB\-f\fP \fInew.tar\fP \fIfoo1\fP \fB@\fP \fIold.tgz\fP \fB-C\fP \fI/tmp\fP \fIfoo2\fP +.RS 4 +\fB\%tar\fP \fB\-c\fP \fB\-f\fP \fInew.tar\fP \fIfoo1\fP \fB@\fP \fIold.tgz\fP \fB-C\fP \fI/tmp\fP \fIfoo2\fP .RE will create a new archive \fInew.tar\fP. -\fBtar\fP +\fB\%tar\fP will read the file \fIfoo1\fP from the current directory and add it to the output archive. @@ -576,22 +689,28 @@ Finally, it will switch to the directory and add \fIfoo2\fP to the output archive. +.PP An input file in \fBmtree\fP(5) format can be used to create an output archive with arbitrary ownership, permissions, or names that differ from existing data on disk: -.RS +.PP +.RS 4 $ cat input.mtree .RE -.RS +.RS 4 +#mtree +.RE +.RS 4 usr/bin uid=0 gid=0 mode=0755 type=dir .RE -.RS +.RS 4 usr/bin/ls uid=0 gid=0 mode=0755 type=file content=myls .RE -.RS +.RS 4 $ tar -cvf output.tar @input.mtree .RE +.PP The \fB\--newer\fP and @@ -602,7 +721,33 @@ switches accept a variety of common date and time specifications, including ``5 minutes ago'', and ``19:14 PST May 1''. +.PP +The +\fB\--options\fP +argument can be used to control various details of archive generation +or reading. +For example, you can generate mtree output which only contains +\fBtype\fP, \fBtime\fP, +and +\fBuid\fP +keywords: +.RS 4 +\fB\%tar\fP \fB\-cf\fP \fIfile.tar\fP \fB\--format=mtree\fP \fB\--options='!all,type,time,uid'\fP \fIdir\fP +.RE +or you can set the compression level used by gzip or xz compression: +.RS 4 +\fB\%tar\fP \fB\-czf\fP \fIfile.tar\fP \fB\--options='compression-level=9'\fP. +.RE +For more details, see the explanation of the +\fB\%archive_read_set_options\fP() +and +\fB\%archive_write_set_options\fP() +API calls that are described in +\fBarchive_read\fP(3) +and +\fBarchive_write\fP(3). .SH COMPATIBILITY +.ad l The bundled-arguments format is supported for compatibility with historic implementations. It consists of an initial word (with no leading - character) in which @@ -611,8 +756,8 @@ Arguments follow as separate words. The order of the arguments must match the order of the corresponding characters in the bundled command word. For example, -.RS -\fBtar\fP \fBtbf\fP 32 \fIfile.tar\fP +.RS 4 +\fB\%tar\fP \fBtbf\fP 32 \fIfile.tar\fP .RE specifies three flags \fBt\fP, @@ -635,10 +780,12 @@ flag, and is the argument to the \fBf\fP flag. +.PP The mode options c, r, t, u, and x and the options b, f, l, m, o, v, and w comply with SUSv2. +.PP For maximum portability, scripts that invoke -\fBtar\fP +\fB\%tar\fP should use the bundled-argument format above, should limit themselves to the \fBc\fP, @@ -653,13 +800,15 @@ modes, and the and \fBw\fP options. -On systems that support getopt_long(), additional long options -are available to improve compatibility with other tar implementations. +.PP +Additional long options are provided to improve compatibility with other +tar implementations. .SH SECURITY +.ad l Certain security issues are common to many archiving programs, including -\fB.\fP +\fB\%tar\fP. In particular, carefully-crafted archives can request that -\fBtar\fP +\fB\%tar\fP extract files to locations outside of the target directory. This can potentially be used to cause unwitting users to overwrite files they did not intend to overwrite. @@ -667,13 +816,14 @@ If the archive is being extracted by the superuser, any file on the system can potentially be overwritten. There are three ways this can happen. Although -\fBtar\fP +\fB\%tar\fP has mechanisms to protect against each one, savvy users should be aware of the implications: +.RS 5 .IP \(bu Archive entries can have absolute pathnames. By default, -\fBtar\fP +\fB\%tar\fP removes the leading \fI/\fP character from filenames before restoring them to guard against this problem. @@ -682,7 +832,7 @@ Archive entries can have pathnames that include \fI\& ..\fP components. By default, -\fBtar\fP +\fB\%tar\fP will not extract files containing \fI\& ..\fP components in their pathname. @@ -692,7 +842,7 @@ files to other directories. An archive can restore a symbolic link to another directory, then use that link to restore a file into that directory. To guard against this, -\fBtar\fP +\fB\%tar\fP checks each extracted path for symlinks. If the final path element is a symlink, it will be removed and replaced with the archive entry. @@ -704,19 +854,20 @@ If neither nor \fB\-P\fP is specified, -\fBtar\fP +\fB\%tar\fP will refuse to extract the entry. +.RE To protect yourself, you should be wary of any archives that come from untrusted sources. You should examine the contents of an archive with -.RS -\fBtar\fP \fB\-tf\fP \fIfilename\fP +.RS 4 +\fB\%tar\fP \fB\-tf\fP \fIfilename\fP .RE before extraction. You should use the \fB\-k\fP option to ensure that -\fBtar\fP +\fB\%tar\fP will not overwrite any existing files or the \fB\-U\fP option to remove any pre-existing files. @@ -725,12 +876,13 @@ privileges. Note that the \fB\-P\fP option to -\fBtar\fP +\fB\%tar\fP disables the security checks above and allows you to extract an archive while preserving any absolute pathnames, \fI\& ..\fP components, or symlinks to other directories. .SH SEE ALSO +.ad l \fBbzip2\fP(1), \fBcompress\fP(1), \fBcpio\fP(1), @@ -742,6 +894,7 @@ components, or symlinks to other directories. \fBlibarchive-formats\fP(5), \fBtar\fP(5) .SH STANDARDS +.ad l There is no current POSIX standard for the tar command; it appeared in ISO/IEC 9945-1:1996 (``POSIX.1'') @@ -750,17 +903,19 @@ IEEE Std 1003.1-2001 (``POSIX.1''). The options used by this implementation were developed by surveying a number of existing tar implementations as well as the old POSIX specification for tar and the current POSIX specification for pax. +.PP The ustar and pax interchange file formats are defined by IEEE Std 1003.1-2001 (``POSIX.1'') for the pax command. .SH HISTORY +.ad l A -\fBtar\fP +\fB\%tar\fP command appeared in Seventh Edition Unix, which was released in January, 1979. There have been numerous other implementations, many of which extended the file format. John Gilmore's -\fBpdtar\fP +\fB\%pdtar\fP public-domain implementation (circa November, 1987) was quite influential, and formed the basis of GNU tar. GNU tar was included as the standard system tar @@ -768,10 +923,12 @@ in FreeBSD beginning with FreeBSD 1.0. +.PP This is a complete re-implementation based on the \fBlibarchive\fP(3) library. .SH BUGS +.ad l This program follows ISO/IEC 9945-1:1996 (``POSIX.1'') for the definition of the @@ -782,9 +939,11 @@ Note that GNU tar prior to version 1.15 treated as a synonym for the \fB\--one-file-system\fP option. +.PP The \fB\-C\fP \fIdir\fP option may differ from historic implementations. +.PP All archive output is written in correctly-sized blocks, even if the output is being compressed. Whether or not the last output block is padded to a full @@ -801,20 +960,23 @@ Many compressors, including and \fBbzip2\fP(1), complain about the null padding when decompressing an archive created by -\fB,\fP +\fB\%tar\fP, although they still extract it correctly. +.PP The compression and decompression is implemented internally, so there may be insignificant differences between the compressed output generated by -.RS -\fBtar\fP \fB\-czf\fP \fI-\fP file +.RS 4 +\fB\%tar\fP \fB\-czf\fP \fI-\fP file .RE and that generated by -.RS -\fBtar\fP \fB\-cf\fP \fI-\fP file | \fBtar\fP gzip +.RS 4 +\fB\%tar\fP \fB\-cf\fP \fI-\fP file | \fB\%gzip\fP .RE +.PP The default should be to read and write archives to the standard I/O paths, but tradition (and POSIX) dictates otherwise. +.PP The \fBr\fP and @@ -826,6 +988,7 @@ Other archives can be modified using mode with the \fI@archive-file\fP extension. +.PP To archive a file called \fI@foo\fP or @@ -835,6 +998,7 @@ you must specify it as or \fI\& ./-foo\fP, respectively. +.PP In create mode, a leading \fI\& ./\fP is always removed. @@ -843,14 +1007,18 @@ A leading is stripped unless the \fB\-P\fP option is specified. +.PP There needs to be better support for file selection on both create and extract. +.PP There is not yet any support for multi-volume archives or for archiving sparse files. +.PP Converting between dissimilar archive formats (such as tar and cpio) using the \fB@\fP \fI-\fP convention can cause hard link information to be lost. (This is a consequence of the incompatible ways that different archive formats store hardlink information.) +.PP There are alternative long options for many of the short options that are deliberately not documented. diff --git a/archivers/libarchive/files/doc/man/cpio.5 b/archivers/libarchive/files/doc/man/cpio.5 index e389f71e119..922df018ff9 100644 --- a/archivers/libarchive/files/doc/man/cpio.5 +++ b/archivers/libarchive/files/doc/man/cpio.5 @@ -1,16 +1,18 @@ .TH CPIO 5 "October 5, 2007" "" .SH NAME -\fBcpio\fP +.ad l +\fB\%cpio\fP \- format of cpio archive files .SH DESCRIPTION +.ad l The -\fBcpio\fP +\fB\%cpio\fP archive format collects any number of files, directories, and other file system objects (symbolic links, device nodes, etc.) into a single stream of bytes. .SS General Format Each file system object in a -\fBcpio\fP +\fB\%cpio\fP archive comprises a header record with basic numeric metadata followed by the full pathname of the entry and the file data. The header record stores a series of integer values that generally @@ -31,10 +33,11 @@ the pathname XXX Any documentation of the original PWB/UNIX 1.0 format? XXX .SS Old Binary Format The old binary -\fBcpio\fP +\fB\%cpio\fP format stores numbers as 2-byte and 4-byte binary values. Each entry begins with a header in the following format: -.RS +.RS 4 +.nf struct header_old_cpio { unsigned short c_magic; unsigned short c_dev; @@ -49,12 +52,14 @@ struct header_old_cpio { unsigned short c_filesize[2]; }; .RE +.PP The \fIunsigned\fP short fields here are 16-bit integer values; the \fIunsigned\fP int fields are 32-bit integer values. The fields are as follows +.RS 5 .TP \fImagic\fP The integer value octal 070707. @@ -64,15 +69,16 @@ written with little-endian or big-endian integers. \fIdev\fP, \fIino\fP The device and inode numbers from the disk. These are used by programs that read -\fBcpio\fP +\fB\%cpio\fP archives to determine when two entries refer to the same file. Programs that synthesize -\fBcpio\fP +\fB\%cpio\fP archives should be careful to set these to distinct values for each entry. .TP \fImode\fP The mode specifies both the regular permissions and the file type. It consists of several bit fields as follows: +.RS 5 .TP 0170000 This masks the file type bits. @@ -112,6 +118,7 @@ On some systems, this modifies the behavior of executables and/or directories. 0000777 The lower 9 bits specify read/write/execute permissions for world, group, and user following standard POSIX conventions. +.RE .TP \fIuid\fP, \fIgid\fP The numeric user id and group id of the owner. @@ -146,12 +153,15 @@ four gigabyte file sizes. See \fImtime\fP above for a description of the storage of four-byte integers. +.RE +.PP The pathname immediately follows the fixed header. If the \fBnamesize\fP is odd, an additional NUL byte is added after the pathname. The file data is then appended, padded with NUL bytes to an even length. +.PP Hardlinked files are not given special treatment; the full file contents are included with each copy of the file. @@ -166,7 +176,8 @@ format or as the format. It stores the same numeric fields as the old binary format, but represents them as 6-character or 11-character octal values. -.RS +.RS 4 +.nf struct cpio_odc_header { char c_magic[6]; char c_dev[6]; @@ -181,6 +192,7 @@ struct cpio_odc_header { char c_filesize[11]; }; .RE +.PP The fields are identical to those in the old binary format. The name and file body follow the fixed header. Unlike the old binary format, there is no additional padding @@ -192,7 +204,8 @@ NUL byte that terminates the name field. The "new" ASCII format uses 8-byte hexadecimal fields for all numbers and separates device numbers into separate fields for major and minor numbers. -.RS +.RS 4 +.nf struct cpio_newc_header { char c_magic[6]; char c_ino[8]; @@ -210,8 +223,10 @@ struct cpio_newc_header { char c_check[8]; }; .RE +.PP Except as specified below, the fields here match those specified for the old binary format above. +.RS 5 .TP \fImagic\fP The string @@ -220,11 +235,14 @@ The string \fIcheck\fP This field is always set to zero by writers and ignored by readers. See the next section for more details. +.RE +.PP The pathname is followed by NUL bytes so that the total size of the fixed header plus pathname is a multiple of four. Likewise, the file data is padded to a multiple of four bytes. Note that this format supports only 4 gigabyte files (unlike the older ASCII format, which supports 8 gigabyte files). +.PP In this format, hardlinked files are handled by setting the filesize to zero for each entry except the last one that appears in the archive. @@ -241,40 +259,49 @@ and using unsigned arithmetic. Only the least-significant 32 bits of the sum are stored. .SS HP variants The -\fBcpio\fP +\fB\%cpio\fP implementation distributed with HPUX used XXXX but stored device numbers differently XXX. .SS Other Extensions and Variants Sun Solaris uses additional file types to store extended file data, including ACLs and extended attributes, as special entries in cpio archives. +.PP XXX Others? XXX .SH BUGS +.ad l The ``CRC'' format is mis-named, as it uses a simple checksum and not a cyclic redundancy check. +.PP The old binary format is limited to 16 bits for user id, group id, device, and inode numbers. It is limited to 4 gigabyte file sizes. +.PP The old ASCII format is limited to 18 bits for the user id, group id, device, and inode numbers. It is limited to 8 gigabyte file sizes. +.PP The new ASCII format is limited to 4 gigabyte file sizes. +.PP None of the cpio formats store user or group names, which are essential when moving files between systems with dissimilar user or group numbering. +.PP Especially when writing older cpio variants, it may be necessary to map actual device/inode values to synthesized values that fit the available fields. With very large filesystems, this may be necessary even for the newer formats. .SH SEE ALSO +.ad l \fBcpio\fP(1), \fBtar\fP(5) .SH STANDARDS +.ad l The -\fBcpio\fP +\fB\%cpio\fP utility is no longer a part of POSIX or the Single Unix Standard. It last appeared in Version 2 of the Single UNIX Specification (``SUSv2''). @@ -284,6 +311,7 @@ The portable ASCII format is currently part of the specification for the \fBpax\fP(1) utility. .SH HISTORY +.ad l The original cpio utility was written by Dick Haight while working in AT&T's Unix Support Group. It appeared in 1977 as part of PWB/UNIX 1.0, the diff --git a/archivers/libarchive/files/doc/man/libarchive-formats.5 b/archivers/libarchive/files/doc/man/libarchive-formats.5 index 580aaeaa071..ff87c8ba860 100644 --- a/archivers/libarchive/files/doc/man/libarchive-formats.5 +++ b/archivers/libarchive/files/doc/man/libarchive-formats.5 @@ -1,8 +1,10 @@ -.TH libarchive-formats 3 "April 27, 2004" "" +.TH libarchive-formats 5 "December 27, 2009" "" .SH NAME -\fBlibarchive-formats\fP +.ad l +\fB\%libarchive-formats\fP \- archive formats supported by the libarchive library .SH DESCRIPTION +.ad l The \fBlibarchive\fP(3) library reads and writes a variety of streaming archive formats. @@ -10,13 +12,15 @@ Generally speaking, all of these archive formats consist of a series of ``entries''. Each entry stores a single file system object, such as a file, directory, or symbolic link. +.PP The following provides a brief description of each format supported by libarchive, with some information about recognized extensions or limitations of the current library support. Note that just because a format is supported by libarchive does not imply that a program that uses libarchive will support that format. Applications that use libarchive specify which formats they wish -to support. +to support, though many programs do use libarchive convenience +functions to enable all supported formats. .SS Tar Formats The \fBlibarchive\fP(3) @@ -26,6 +30,7 @@ However, it only writes POSIX-standard and ``pax interchange'' formats. +.PP All tar formats store each entry in one or more 512-byte records. The first record is used for file metadata, including filename, timestamp, and mode information, and the file data is stored in @@ -34,6 +39,8 @@ Later variants have extended this by either appropriating undefined areas of the header record, extending the header to multiple records, or by storing special entries that modify the interpretation of subsequent entries. +.PP +.RS 5 .TP \fBgnutar\fP The @@ -53,8 +60,8 @@ library can read and write POSIX-compliant pax interchange format archives. Pax interchange format archives are an extension of the older ustar format that adds a separate entry with additional attributes stored -as key/value pairs. -The presence of this additional entry is the only difference between +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. @@ -63,8 +70,9 @@ to define custom keys by preceding them with the vendor name in all uppercase. When writing pax archives, libarchive uses many of the SCHILY keys defined by Joerg Schilling's ``star'' -archiver. -The libarchive library can read most of the SCHILY keys. +archiver and a few LIBARCHIVE keys. +The libarchive library can read most of the SCHILY keys +and most of the GNU keys introduced by GNU tar. It silently ignores any keywords that it does not understand. .TP \fBrestricted\fP pax @@ -87,6 +95,7 @@ directories. \fBustar\fP The libarchive library can both read and write this format. This format has the following limitations: +.RS 5 .IP \(bu Device major and minor numbers are limited to 21 bits. Nodes with larger numbers will not be added to the archive. @@ -101,13 +110,33 @@ This name is limited to 100 bytes. Extended attributes, file flags, and other extended security information cannot be stored. .IP \(bu -Archive entries are limited to 2 gigabytes in size. +Archive entries are limited to 8 gigabytes in size. +.RE Note that the pax interchange format has none of these restrictions. -The libarchive library can also read a variety of commonly-used extensions to +.RE +.PP +The libarchive library also reads a variety of commonly-used extensions to the basic tar format. -In particular, it supports base-256 values in certain numeric fields. -This essentially removes the limitations on file size, modification time, +These extensions are recognized automatically whenever they appear. +.RS 5 +.TP +Numeric extensions. +The POSIX standards require fixed-length numeric fields to be written with +some character position reserved for terminators. +Libarchive allows these fields to be written without terminator characters. +This extends the allowable range; in particular, ustar archives with this +extension can support entries up to 64 gigabytes in size. +Libarchive also recognizes base-256 values in most numeric fields. +This essentially removes all limitations on file size, modification time, and device numbers. +.TP +Solaris extensions +Libarchive recognizes ACL and extended attribute records written +by Solaris tar. +Currently, libarchive only has support for old-style ACLs; the +newer NFSv4 ACLs are recognized but discarded. +.RE +.PP The first tar program appeared in Seventh Edition Unix in 1979. The first official standard for the tar file format was the ``ustar'' @@ -123,21 +152,28 @@ and format archives. A cpio archive stores each entry as a fixed-size header followed by a variable-length filename and variable-length data. -Unlike tar, cpio does only minimal padding of the header or file data. -There are a variety of cpio formats, which differ primarily in +Unlike the tar format, the cpio format does only minimal padding +of the header or file data. +There are several cpio variants, which differ primarily in how they store the initial header: some store the values as octal or hexadecimal numbers in ASCII, others as binary values of varying byte order and length. +.RS 5 .TP \fBbinary\fP -The libarchive library can read both big-endian and little-endian +The libarchive library transparently reads both big-endian and little-endian variants of the original binary cpio format. This format used 32-bit binary values for file size and mtime, and 16-bit binary values for the other fields. .TP \fBodc\fP The libarchive library can both read and write this -POSIX-standard format. +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), @@ -152,6 +188,8 @@ This limits file size to 4GB, and also limits the mtime and other fields to 32 bits. The SVR4 format can optionally include a CRC of the file contents, although libarchive does not currently verify this CRC. +.RE +.PP Cpio first appeared in PWB/UNIX 1.0, which was released within AT&T in 1977. PWB/UNIX 1.0 formed the basis of System III Unix, released outside @@ -161,9 +199,9 @@ in Version 7 AT&T Unix. As a result, the tar command became much better known in universities and research groups that used Version 7. The combination of the -\fBfind\fP +\fB\%find\fP and -\fBcpio\fP +\fB\%cpio\fP utilities provided very precise control over file selection. Unfortunately, the format has many limitations that make it unsuitable for widespread use. @@ -178,6 +216,7 @@ A is a shell script that, when executed on a POSIX-compliant system, will recreate a collection of file system objects. The libarchive library can write two different kinds of shar archives: +.RS 5 .TP \fBshar\fP The traditional shar format uses a limited set of POSIX @@ -200,20 +239,33 @@ It also includes additional shell commands that attempt to reproduce as many file attributes as possible, including owner, mode, and flags. The additional commands used to restore file attributes make shardump archives less portable than plain shar archives. +.RE .SS ISO9660 format Libarchive can read and extract from files containing ISO9660-compliant CDROM images. -It also has partial support for Rockridge extensions. -In many cases, this can remove the need to burn a physical CDROM. +In many cases, this can remove the need to burn a physical CDROM +just in order to read the files contained in an ISO9660 image. It also avoids security and complexity issues that come with virtual mounts and loopback devices. +Libarchive supports the most common Rockridge extensions and has partial +support for Joliet extensions. +If both extensions are present, the Joliet extensions will be +used and the Rockridge extensions will be ignored. +In particular, this can create problems with hardlinks and symlinks, +which are supported by Rockridge but not by Joliet. .SS Zip format -Libarchive can extract from most zip format archives. -It currently only supports uncompressed entries and entries -compressed with the +Libarchive can read and write zip format archives that have +uncompressed entries and entries compressed with the ``deflate'' algorithm. Older zip compression algorithms are not supported. +It can extract jar archives, archives that use Zip64 extensions and many +self-extracting zip archives. +Libarchive reads Zip archives as they are being streamed, +which allows it to read archives of arbitrary size. +It currently does not use the central directory; this +limits libarchive's ability to support some self-extracting +archives and ones that have been modified in certain ways. .SS Archive (library) file format The Unix archive format (commonly created by the \fBar\fP(1) @@ -225,16 +277,58 @@ The ar format has never been standardised. There are two common variants: the GNU format derived from SVR4, and the BSD format, which first appeared in 4.4BSD. -Libarchive provides read and write support for both variants. +The two differ primarily in their handling of filenames +longer than 15 characters: +the GNU/SVR4 variant writes a filename table at the beginning of the archive; +the BSD format stores each long filename in an extension +area adjacent to the entry. +Libarchive can read both extensions, +including archives that may include both types of long filenames. +Programs using libarchive can write GNU/SVR4 format +if they provide a filename table to be written into +the archive before any of the entries. +Any entries whose names are not in the filename table +will be written using BSD-style long filenames. +This can cause problems for programs such as +GNU ld that do not support the BSD-style long filenames. .SS mtree -Libarchive can read files in +Libarchive can read and write files in \fBmtree\fP(5) -format. This format is not a true archive format, but rather a description -of a file hierarchy. When requested, libarchive obtains the contents of -the files described by the -\fBmtree\fP(5) -format from files on disk instead. +format. +This format is not a true archive format, but rather a textual description +of a file hierarchy in which each line specifies the name of a file and +provides specific metadata about that file. +Libarchive can read all of the keywords supported by both +the NetBSD and FreeBSD versions of +\fBmtree\fP(1), +although many of the keywords cannot currently be stored in an +Tn archive_entry +object. +When writing, libarchive supports use of the +\fBarchive_write_set_options\fP(3) +interface to specify which keywords should be included in the +output. +If libarchive was compiled with access to suitable +cryptographic libraries (such as the OpenSSL libraries), +it can compute hash entries such as +\fBsha512\fP +or +\fBmd5\fP +from file data being written to the mtree writer. +.PP +When reading an mtree file, libarchive will locate the corresponding +files on disk using the +\fBcontents\fP +keyword if present or the regular filename. +If it can locate and open the file on disk, it will use that +to fill in any metadata that is missing from the mtree file +and will read the file contents and return those to the program +using libarchive. +If it cannot locate and open the file on disk, libarchive +will return an error for any attempt to read the entry +body. .SH SEE ALSO +.ad l \fBar\fP(1), \fBcpio\fP(1), \fBmkisofs\fP(1), diff --git a/archivers/libarchive/files/doc/man/libarchive.3 b/archivers/libarchive/files/doc/man/libarchive.3 index 722b765e78e..1af1861fcae 100644 --- a/archivers/libarchive/files/doc/man/libarchive.3 +++ b/archivers/libarchive/files/doc/man/libarchive.3 @@ -1,21 +1,26 @@ .TH LIBARCHIVE 3 "August 19, 2006" "" .SH NAME -\fBlibarchive\fP +.ad l +\fB\%libarchive\fP \- functions for reading and writing streaming archives .SH LIBRARY +.ad l Lb libarchive .SH OVERVIEW +.ad l The -\fBlibarchive\fP +\fB\%libarchive\fP library provides a flexible interface for reading and writing streaming archive files such as tar and cpio. The library is inherently stream-oriented; readers serially iterate through the archive, writers serially add things to the archive. In particular, note that there is no built-in support for random access nor for in-place modification. +.PP When reading an archive, the library automatically detects the format and the compression. The library currently has read support for: +.RS 5 .IP \(bu old-style tar archives, .IP \(bu @@ -34,15 +39,18 @@ most common cpio archive formats, ISO9660 CD images (with or without RockRidge extensions), .IP \(bu Zip archives. +.RE The library automatically detects archives compressed with \fBgzip\fP(1), \fBbzip2\fP(1), or \fBcompress\fP(1) and decompresses them transparently. +.PP When writing an archive, you can specify the compression to be used and the format to use. The library can write +.RS 5 .IP \(bu POSIX-standard ``ustar'' @@ -55,6 +63,7 @@ archives, POSIX octet-oriented cpio archives, .IP \(bu two different variants of shar archives. +.RE Pax interchange format is an extension of the tar archive format that eliminates essentially all of the limitations of historic tar formats in a standard fashion that is supported @@ -65,47 +74,32 @@ implementations on many systems as well as several newer implementations of Note that the default write format will suppress the pax extended attributes for most entries; explicitly requesting pax format will enable those attributes for all entries. +.PP The read and write APIs are accessed through the -.nh -\fBarchive_read_XXX\fP -.hy -(); +\fB\%archive_read_XXX\fP() functions and the -.nh -\fBarchive_write_XXX\fP -.hy -(); +\fB\%archive_write_XXX\fP() functions, respectively, and either can be used independently of the other. +.PP The rest of this manual page provides an overview of the library operation. More detailed information can be found in the individual manual pages for each API or utility function. .SH READING AN ARCHIVE +.ad l To read an archive, you must first obtain an initialized Tn struct archive object from -.nh -\fBarchive_read_new\fP -.hy -(.); +\fB\%archive_read_new\fP(). You can then modify this object for the desired operations with the various -.nh -\fBarchive_read_set_XXX\fP -.hy -(); +\fB\%archive_read_set_XXX\fP() and -.nh -\fBarchive_read_support_XXX\fP -.hy -(); +\fB\%archive_read_support_XXX\fP() functions. In particular, you will need to invoke appropriate -.nh -\fBarchive_read_support_XXX\fP -.hy -(); +\fB\%archive_read_support_XXX\fP() functions to enable the corresponding compression and format support. Note that these latter functions perform two distinct operations: @@ -113,125 +107,85 @@ they cause the corresponding support code to be linked into your program, and they enable the corresponding auto-detect code. Unless you have specific constraints, you will generally want to invoke -.nh -\fBarchive_read_support_compression_all\fP -.hy -(); +\fB\%archive_read_support_compression_all\fP() and -.nh -\fBarchive_read_support_format_all\fP -.hy -(); +\fB\%archive_read_support_format_all\fP() to enable auto-detect for all formats and compression types currently supported by the library. +.PP Once you have prepared the Tn struct archive object, you call -.nh -\fBarchive_read_open\fP -.hy -(); +\fB\%archive_read_open\fP() to actually open the archive and prepare it for reading. There are several variants of this function; the most basic expects you to provide pointers to several functions that can provide blocks of bytes from the archive. There are convenience forms that allow you to specify a filename, file descriptor, -\fI"FILE *"\fP -.RE +\fIFILE *\fP object, or a block of memory from which to read the archive data. Note that the core library makes no assumptions about the size of the blocks read; callback functions are free to read whatever block size is most appropriate for the medium. +.PP Each archive entry consists of a header followed by a certain amount of data. You can obtain the next header with -.nh -\fBarchive_read_next_header\fP -.hy -(,); +\fB\%archive_read_next_header\fP(), which returns a pointer to an Tn struct archive_entry structure with information about the current archive element. If the entry is a regular file, then the header will be followed by the file data. You can use -.nh -\fBarchive_read_data\fP -.hy -(); +\fB\%archive_read_data\fP() (which works much like the \fBread\fP(2) system call) to read this data from the archive. You may prefer to use the higher-level -.nh -\fBarchive_read_data_skip\fP -.hy -(,); +\fB\%archive_read_data_skip\fP(), which reads and discards the data for this entry, -.nh -\fBarchive_read_data_to_buffer\fP -.hy -(,); +\fB\%archive_read_data_to_buffer\fP(), which reads the data into an in-memory buffer, -.nh -\fBarchive_read_data_to_file\fP -.hy -(,); +\fB\%archive_read_data_to_file\fP(), which copies the data to the provided file descriptor, or -.nh -\fBarchive_read_extract\fP -.hy -(,); +\fB\%archive_read_extract\fP(), which recreates the specified entry on disk and copies data from the archive. In particular, note that -.nh -\fBarchive_read_extract\fP -.hy -(); +\fB\%archive_read_extract\fP() uses the Tn struct archive_entry structure that you provide it, which may differ from the entry just read from the archive. In particular, many applications will want to override the pathname, file permissions, or ownership. +.PP Once you have finished reading data from the archive, you should call -.nh -\fBarchive_read_close\fP -.hy -(); +\fB\%archive_read_close\fP() to close the archive, then call -.nh -\fBarchive_read_finish\fP -.hy -(); +\fB\%archive_read_finish\fP() to release all resources, including all memory allocated by the library. +.PP The \fBarchive_read\fP(3) manual page provides more detailed calling information for this API. .SH WRITING AN ARCHIVE +.ad l You use a similar process to write an archive. The -.nh -\fBarchive_write_new\fP -.hy -(); +\fB\%archive_write_new\fP() function creates an archive object useful for writing, the various -.nh -\fBarchive_write_set_XXX\fP -.hy -(); +\fB\%archive_write_set_XXX\fP() functions are used to set parameters for writing the archive, and -.nh -\fBarchive_write_open\fP -.hy -(); +\fB\%archive_write_open\fP() completes the setup and opens the archive for writing. +.PP Individual archive entries are written in a three-step process: You first initialize a @@ -246,38 +200,35 @@ field, which specifies the type of object and \fIst_size\fP field, which specifies the size of the data portion of the object. The -.nh -\fBarchive_write_header\fP -.hy -(); +\fB\%archive_write_header\fP() function actually writes the header data to the archive. You can then use -.nh -\fBarchive_write_data\fP -.hy -(); +\fB\%archive_write_data\fP() to write the actual data. +.PP After all entries have been written, use the -.nh -\fBarchive_write_finish\fP -.hy -(); +\fB\%archive_write_finish\fP() function to release all resources. +.PP The \fBarchive_write\fP(3) manual page provides more detailed calling information for this API. .SH DESCRIPTION +.ad l Detailed descriptions of each function are provided by the corresponding manual pages. +.PP All of the functions utilize an opaque Tn struct archive datatype that provides access to the archive contents. +.PP The Tn struct archive_entry structure contains a complete description of a single archive entry. It uses an opaque interface that is fully documented in \fBarchive_entry\fP(3). +.PP Users familiar with historic formats should be aware that the newer variants have eliminated most restrictions on the length of textual fields. Clients should not assume that filenames, link names, user names, or @@ -286,6 +237,7 @@ In particular, pax interchange format can easily accommodate pathnames in arbitrary character sets that exceed \fIPATH_MAX\fP. .SH RETURN VALUES +.ad l Most functions return zero on success, non-zero on error. The return value indicates the general severity of the error, ranging from @@ -296,57 +248,37 @@ to the user, to which indicates a serious problem that will prevent any further operations on this archive. On error, the -.nh -\fBarchive_errno\fP -.hy -(); +\fB\%archive_errno\fP() function can be used to retrieve a numeric error code (see \fBerrno\fP(2)). The -.nh -\fBarchive_error_string\fP -.hy -(); +\fB\%archive_error_string\fP() returns a textual error message suitable for display. -.nh -\fBarchive_read_new\fP -.hy -(); +.PP +\fB\%archive_read_new\fP() and -.nh -\fBarchive_write_new\fP -.hy -(); +\fB\%archive_write_new\fP() return pointers to an allocated and initialized Tn struct archive object. -.nh -\fBarchive_read_data\fP -.hy -(); +.PP +\fB\%archive_read_data\fP() and -.nh -\fBarchive_write_data\fP -.hy -(); +\fB\%archive_write_data\fP() return a count of the number of bytes actually read or written. A value of zero indicates the end of the data for this entry. A negative value indicates an error, in which case the -.nh -\fBarchive_errno\fP -.hy -(); +\fB\%archive_errno\fP() and -.nh -\fBarchive_error_string\fP -.hy -(); +\fB\%archive_error_string\fP() functions can be used to obtain more information. .SH ENVIRONMENT +.ad l There are character set conversions within the \fBarchive_entry\fP(3) functions that are impacted by the currently-selected locale. .SH SEE ALSO +.ad l \fBtar\fP(1), \fBarchive_entry\fP(3), \fBarchive_read\fP(3), @@ -354,23 +286,27 @@ functions that are impacted by the currently-selected locale. \fBarchive_write\fP(3), \fBtar\fP(5) .SH HISTORY +.ad l The -\fBlibarchive\fP +\fB\%libarchive\fP library first appeared in FreeBSD 5.3. .SH AUTHORS +.ad l -nosplit The -\fBlibarchive\fP +\fB\%libarchive\fP library was written by -Tim Kientzle <kientzle@acm.org.> +Tim Kientzle \%<kientzle@acm.org.> .SH BUGS +.ad l Some archive formats support information that is not supported by Tn struct archive_entry. Such information cannot be fully archived or restored using this library. This includes, for example, comments, character sets, or the arbitrary key/value pairs that can appear in pax interchange format archives. +.PP Conversely, of course, not all of the information that can be stored in an Tn struct archive_entry diff --git a/archivers/libarchive/files/doc/man/libarchive_internals.3 b/archivers/libarchive/files/doc/man/libarchive_internals.3 index fae95d8aebf..98b99a3a9ce 100644 --- a/archivers/libarchive/files/doc/man/libarchive_internals.3 +++ b/archivers/libarchive/files/doc/man/libarchive_internals.3 @@ -1,15 +1,18 @@ .TH LIBARCHIVE 3 "April 16, 2007" "" .SH NAME -\fBlibarchive_internals\fP +.ad l +\fB\%libarchive_internals\fP \- description of libarchive internal interfaces .SH OVERVIEW +.ad l The -\fBlibarchive\fP +\fB\%libarchive\fP library provides a flexible interface for reading and writing streaming archive files such as tar and cpio. Internally, it follows a modular layered design that should make it easy to add new archive and compression formats. .SH GENERAL ARCHITECTURE +.ad l Externally, libarchive exposes most operations through an opaque, object-style interface. The @@ -23,26 +26,29 @@ and write them to disk. (There are plans to add a facility to read \fBarchive_entry\fP(1) objects from disk as well.) +.PP The read and write APIs each have four layers: a public API layer, a format layer that understands the archive file format, a compression layer, and an I/O layer. The I/O layer is completely exposed to clients who can replace it entirely with their own functions. +.PP In order to provide as much consistency as possible for clients, some public functions are virtualized. Eventually, it should be possible for clients to open an archive or disk writer, and then use a single set of code to select and write entries, regardless of the target. .SH READ ARCHITECTURE +.ad l From the outside, clients use the \fBarchive_read\fP(3) API to manipulate an -\fBarchive\fP +\fB\%archive\fP object to read entries and bodies from an archive stream. Internally, the -\fBarchive\fP +\fB\%archive\fP object is cast to an -\fBarchive_read\fP +\fB\%archive_read\fP object, which holds all read-specific data. The API has four layers: The lowest layer is the I/O layer. @@ -55,7 +61,7 @@ The compression layer calls the I/O layer to read bytes and decompresses them for the format layer. The format layer unpacks a stream of uncompressed bytes and creates -\fBarchive_entry\fP +\fB\%archive_entry\fP objects from the incoming data. The API layer tracks overall state (for example, it prevents clients from reading data before reading a header) @@ -73,17 +79,20 @@ entry, but this design hindered error recovery.) The read API goes to some lengths to be nice to clients. As a result, there are few restrictions on the behavior of the client callbacks. +.PP The client read callback is expected to provide a block of data on each call. A zero-length return does indicate end of file, but otherwise blocks may be as small as one byte or as large as the entire file. In particular, blocks may be of different sizes. +.PP The client skip callback returns the number of bytes actually skipped, which may be much smaller than the skip requested. The only requirement is that the skip not be larger. In particular, clients are allowed to return zero for any skip that they don't want to handle. The skip callback must never be invoked with a negative value. +.PP Keep in mind that not all clients are reading from disk: clients reading from networks may provide different-sized blocks on every request and cannot skip at all; @@ -104,42 +113,31 @@ that much data. If more data is immediately available, it should return more: the format layer handles bulk data reads by asking for a minimum of one byte and then copying as much data as is available. +.PP A subsequent call to the -.nh -\fBconsume\fP -.hy -(); +\fB\%consume\fP() function advances the read pointer. Note that data returned from a -.nh -\fBread_ahead\fP -.hy -(); +\fB\%read_ahead\fP() call is guaranteed to remain in place until the next call to -.nh -\fBread_ahead\fP -.hy -(.); +\fB\%read_ahead\fP(). Intervening calls to -.nh -\fBconsume\fP -.hy -(); +\fB\%consume\fP() should not cause the data to move. +.PP Skip requests must always be handled exactly. Decompression handlers that cannot seek forward should not register a skip handler; the API layer fills in a generic skip handler that reads and discards data. +.PP A decompression handler has a specific lifecycle: +.RS 5 .TP Registration/Configuration When the client invokes the public support function, the decompression handler invokes the internal -.nh -\fB__archive_read_register_compression\fP -.hy -(); +\fB\%__archive_read_register_compression\fP() function to provide bid and initialization functions. This function returns \fBNULL\fP @@ -159,6 +157,7 @@ element of the object. The bid function is otherwise stateless. In particular, it must not perform any I/O operations. +.PP The value returned by the bid function indicates its suitability for handling this data stream. A bid of zero will ensure that this decompressor is never invoked. @@ -209,23 +208,19 @@ slots of the \fIdecompressor\fP object. It should not invoke the client close callback. +.RE .SS Format Layer The read formats have a similar lifecycle to the decompression handlers: +.RS 5 .TP Registration Allocate your private data and initialize your pointers. .TP Bid Formats bid by invoking the -.nh -\fBread_ahead\fP -.hy -(); +\fB\%read_ahead\fP() decompression method but not calling the -.nh -\fBconsume\fP -.hy -(); +\fB\%consume\fP() method. This allows each bidder to look ahead in the input stream. Bidders should not look further ahead than necessary, as long @@ -265,17 +260,16 @@ The skip data call should skip over all file data and trailing padding. This is called automatically by the API layer just before each header read. It is also called in response to the client calling the public -.nh -\fBdata_skip\fP -.hy -(); +\fB\%data_skip\fP() function. .TP Cleanup On cleanup, the format should release all of its allocated memory. +.RE .SS API Layer XXX to do XXX .SH WRITE ARCHITECTURE +.ad l The write API has a similar set of four layers: an API layer, a format layer, a compression layer, and an I/O layer. The registration here is much simpler because only @@ -289,29 +283,32 @@ XXX To be written XXX .SS API Layer XXX To be written XXX .SH WRITE_DISK ARCHITECTURE +.ad l The write_disk API is intended to look just like the write API to clients. Since it does not handle multiple formats or compression, it is not layered internally. .SH GENERAL SERVICES +.ad l The -\fBarchive_read\fP, -\fBarchive_write\fP, +\fB\%archive_read\fP, +\fB\%archive_write\fP, and -\fBarchive_write_disk\fP +\fB\%archive_write_disk\fP objects all contain an initial -\fBarchive\fP +\fB\%archive\fP object which provides common support for a set of standard services. (Recall that ANSI/ISO C90 guarantees that you can cast freely between a pointer to a structure and a pointer to the first element of that structure.) The -\fBarchive\fP +\fB\%archive\fP object has a magic value that indicates which API this object is associated with, slots for storing error information, and function pointers for virtualized API functions. .SH MISCELLANEOUS NOTES +.ad l Connecting existing archiving libraries into libarchive is generally quite difficult. In particular, many existing libraries strongly assume that you @@ -319,6 +316,7 @@ are reading from a file; they seek forwards and backwards as necessary to locate various pieces of information. In contrast, libarchive never seeks backwards in its input, which sometimes requires very different approaches. +.PP For example, libarchive's ISO9660 support operates very differently from most ISO9660 readers. The libarchive support utilizes a work-queue design that @@ -330,6 +328,7 @@ items are added to the list. This design relies heavily on the ISO9660 image being optimized so that directories always occur earlier on the disk than the files they describe. +.PP Depending on the specific format, such approaches may not be possible. The ZIP format specification, for example, allows archivers to store key information only at the end of the file. @@ -339,20 +338,24 @@ Fortunately, such archives are very rare, and libarchive can read most ZIP archives, though it cannot always extract as much information as a dedicated ZIP program. .SH SEE ALSO +.ad l \fBarchive\fP(3), \fBarchive_entry\fP(3), \fBarchive_read\fP(3), \fBarchive_write\fP(3), \fBarchive_write_disk\fP(3) .SH HISTORY +.ad l The -\fBlibarchive\fP +\fB\%libarchive\fP library first appeared in FreeBSD 5.3. .SH AUTHORS +.ad l -nosplit The -\fBlibarchive\fP +\fB\%libarchive\fP library was written by -Tim Kientzle <kientzle@acm.org.> +Tim Kientzle \%<kientzle@acm.org.> .SH BUGS +.ad l diff --git a/archivers/libarchive/files/doc/man/mtree.5 b/archivers/libarchive/files/doc/man/mtree.5 index 0f4c255b495..2cf2e3a1191 100644 --- a/archivers/libarchive/files/doc/man/mtree.5 +++ b/archivers/libarchive/files/doc/man/mtree.5 @@ -1,18 +1,21 @@ .TH MTREE 5 "August 20, 2007" "" .SH NAME -\fBmtree\fP +.ad l +\fB\%mtree\fP \- format of mtree dir hierarchy files .SH DESCRIPTION +.ad l The -\fBmtree\fP +\fB\%mtree\fP format is a textual format that describes a collection of filesystem objects. Such files are typically used to create or verify directory hierarchies. .SS General Format An -\fBmtree\fP +\fB\%mtree\fP file consists of a series of lines, each providing information about a single filesystem object. Leading whitespace is always ignored. +.PP When encoding file or pathnames, any backslash character or character outside of the 95 printable ASCII characters must be encoded as a a backslash followed by three @@ -20,7 +23,9 @@ octal digits. When reading mtree files, any appearance of a backslash followed by three octal digits should be converted into the corresponding character. +.PP Each line is interpreted independently as one of the following types: +.RS 5 .TP Signature The first line of any mtree file must begin with @@ -66,14 +71,17 @@ character after the first character, it is the pathname of a file relative to the starting directory. There can be multiple full entries describing the same file. +.RE +.PP Some tools that process -\fBmtree\fP +\fB\%mtree\fP files may require that multiple lines describing the same file occur consecutively. It is not permitted for the same file to be mentioned using both a relative and a full file specification. .SS Special commands Two special commands are currently defined: +.RS 5 .TP \fB/set\fP This command defines default values for one or more keywords. @@ -88,6 +96,7 @@ This command removes any default value set by a previous command. It is followed on the same line by one or more keywords separated by whitespace. +.RE .SS Keywords After the filename, a full or relative entry consists of zero or more whitespace-separated keyword definitions. @@ -96,7 +105,9 @@ list immediately followed by an '=' sign and a value. Software programs reading mtree files should warn about unrecognized keywords. +.PP Currently supported keywords are as follows: +.RS 5 .TP \fBcksum\fP The checksum of the file using the default algorithm specified by @@ -188,6 +199,8 @@ The last modification time of the file. .TP \fBtype\fP The type of the file; may be set to any one of the following: +.PP +.RS 5 .TP \fBblock\fP block special device @@ -209,30 +222,36 @@ symbolic link .TP \fBsocket\fP socket +.RE .TP \fBuid\fP The file owner as a numeric value. .TP \fBuname\fP The file owner as a symbolic name. +.RE +.PP .SH SEE ALSO +.ad l \fBcksum\fP(1), \fBfind\fP(1), \fBmtree\fP(8) .SH BUGS +.ad l The FreeBSD implementation of mtree does not currently support the -\fBmtree\fP +\fB\%mtree\fP 2.0 format. The requirement for a ``#mtree'' signature line is new and not yet widely implemented. .SH HISTORY +.ad l The -\fBmtree\fP +\fB\%mtree\fP utility appeared in Bx 4.3 Reno. The diff --git a/archivers/libarchive/files/doc/man/tar.5 b/archivers/libarchive/files/doc/man/tar.5 index 4901e2c6c68..ab1995880ee 100644 --- a/archivers/libarchive/files/doc/man/tar.5 +++ b/archivers/libarchive/files/doc/man/tar.5 @@ -1,10 +1,12 @@ -.TH TAR 5 "May 20, 2004" "" +.TH tar 5 "December 27, 2009" "" .SH NAME -\fBtar\fP +.ad l +\fB\%tar\fP \- format of tape archive files .SH DESCRIPTION +.ad l The -\fBtar\fP +\fB\%tar\fP archive format collects any number of files, directories, and other file system objects (symbolic links, device nodes, etc.) into a single stream of bytes. @@ -13,28 +15,32 @@ tape drives that operate with fixed-size blocks, but is widely used as a general packaging mechanism. .SS General Format A -\fBtar\fP +\fB\%tar\fP archive consists of a series of 512-byte records. Each file system object requires a header record which stores basic metadata (pathname, owner, permissions, etc.) and zero or more records containing any file data. The end of the archive is indicated by two records consisting entirely of zero bytes. +.PP For compatibility with tape drives that use fixed block sizes, programs that read or write tar files always read or write a fixed number of records with each I/O operation. These ``blocks'' are always a multiple of the record size. -The most common block size\(emand the maximum supported by historic -implementations\(emis 10240 bytes or 20 records. +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 -\fBpdtar\fP.) +\fB\%pdtar\fP.) .SS Old-Style Archive Format The original tar archive format has been extended many times to include additional information that various implementors found @@ -42,11 +48,13 @@ necessary. This section describes the variant implemented by the tar command included in At v7, -which is one of the earliest widely-used versions of the tar program. +which seems to be the earliest widely-used version of the tar program. +.PP The header record for an old-style -\fBtar\fP +\fB\%tar\fP archive consists of the following: -.RS +.RS 4 +.nf struct header_old_tar { char name[100]; char mode[8]; @@ -61,6 +69,7 @@ struct header_old_tar { }; .RE All unused bytes in the header record are filled with nulls. +.RS 5 .TP \fIname\fP Pathname, stored as a null-terminated string. @@ -117,6 +126,8 @@ field holds the first name under which this file appears. (Note that regular files have a null value in the \fIlinkflag\fP field.) +.RE +.PP Early tar implementations varied in how they terminated these fields. The tar command in At v7 @@ -135,11 +146,12 @@ fields with leading zeros. An early draft of IEEE Std 1003.1-1988 (``POSIX.1'') served as the basis for John Gilmore's -\fBpdtar\fP +\fB\%pdtar\fP program and many system implementations from the late 1980s and early 1990s. These archives generally follow the POSIX ustar format described below with the following variations: +.RS 5 .IP \(bu The magic value is ``ustar\ \&'' @@ -151,6 +163,7 @@ The numeric fields are generally filled with leading spaces .IP \(bu The prefix field is often not used, limiting pathnames to the 100 characters of old-style archives. +.RE .SS POSIX ustar Archives IEEE Std 1003.1-1988 (``POSIX.1'') defined a standard tar file format to be read and written @@ -163,7 +176,8 @@ in the header. (The name is an acronym for ``Unix Standard TAR''.) It extends the historic format with new fields: -.RS +.RS 4 +.nf struct header_posix_ustar { char name[100]; char mode[8]; @@ -184,12 +198,14 @@ struct header_posix_ustar { char pad[12]; }; .RE +.RS 5 .TP \fItypeflag\fP Type of entry. POSIX extended the earlier \fIlinkflag\fP field with several new type values: +.RS 5 .TP ``0'' Regular file. @@ -224,6 +240,7 @@ have a valid filename so that they can be restored by readers that do not support the corresponding extension. Uppercase letters "A" through "Z" are reserved for custom extensions. Note that sockets and whiteout entries are not archivable. +.RE It is worth noting that the \fIsize\fP field, in particular, has different meanings depending on the type. @@ -256,18 +273,24 @@ the system. \fIdevmajor\fP, \fIdevminor\fP Major and minor numbers for character device or block device entry. .TP -\fIprefix\fP -First part of pathname. +\fIname\fP, \fIprefix\fP If the pathname is too long to fit in the 100 bytes provided by the standard format, it can be split at any \fI/\fP -character with the first portion going here. +character with the first portion going into the prefix field. If the prefix field is not empty, the reader will prepend the prefix value and a \fI/\fP character to the regular name field to obtain the full pathname. +The standard does not require a trailing +\fI/\fP +character on directory names, though most implementations still +include this for compatibility reasons. +.RE +.PP Note that all unused bytes must be set to .BR NUL. +.PP Field termination is specified slightly differently by POSIX than by previous implementations. The @@ -289,10 +312,11 @@ unless they fill the entire field. happens to have a \fI/\fP as the 156th character.) -POSIX requires numeric fields to be zero-padded in the front, and allows +POSIX requires numeric fields to be zero-padded in the front, and requires them to be terminated with either space or .BR NUL characters. +.PP Currently, most tar implementations comply with the ustar format, occasionally extending it by adding new fields to the blank area at the end of the header record. @@ -314,6 +338,7 @@ typeflag. In particular, older implementations that do not fully support these extensions will extract the metadata into regular files, where the metadata can be examined as necessary. +.PP An entry in a pax interchange format archive consists of one or two standard ustar entries, each with its own header and data. The first optional entry stores the extended attributes @@ -327,7 +352,7 @@ sign, a value string, and a new line. The decimal number indicates the length of the entire line, including the initial length field and the trailing newline. An example of such a field is: -.RS +.RS 4 25 ctime=1084839148.1212\en .RE Keys in all lowercase are standard keys. @@ -336,6 +361,7 @@ vendor name and a period. Note that, unlike the historic header, numeric values are stored using decimal, not octal. A description of some common keys follows: +.RS 5 .TP \fBatime\fP, \fBctime\fP, \fBmtime\fP File access, inode change, and modification times. @@ -365,7 +391,7 @@ archives to store files much larger than the historic 8GB limit. .TP \fBSCHILY.*\fP Vendor-specific attributes used by Joerg Schilling's -\fBstar\fP +\fB\%star\fP implementation. .TP \fBSCHILY.acl.access\fP, \fBSCHILY.acl.default\fP @@ -380,6 +406,13 @@ are temporarily unavailable). \fBSCHILY.devminor\fP, \fBSCHILY.devmajor\fP The full minor and major numbers for device nodes. .TP +\fBSCHILY.fflags\fP +The file flags. +.TP +\fBSCHILY.realsize\fP +The full size of the file on disk. +XXX explain? XXX +.TP \fBSCHILY.dev,\fP \fBSCHILY.ino\fP, \fBSCHILY.nlinks\fP The device number, inode number, and link count for the entry. In particular, note that a pax interchange format archive using Joerg @@ -407,6 +440,8 @@ XXX Detail the base-64 format here XXX .TP \fBVENDOR.*\fP XXX document other vendor-specific extensions XXX +.RE +.PP Any values stored in an extended attribute override the corresponding values in the regular tar header. Note that compliant readers should ignore the regular fields when they @@ -419,6 +454,7 @@ All text fields are encoded in UTF8. Compliant writers should store only portable 7-bit ASCII characters in the standard ustar header and use extended attributes whenever a text value contains non-ASCII characters. +.PP In addition to the \fBx\fP entry described above, the pax interchange format @@ -432,6 +468,7 @@ defaults for all subsequent archive entries. The \fBg\fP entry is not widely used. +.PP Besides the new \fBx\fP and @@ -460,7 +497,8 @@ entry). As a result, GNU tar archives are not POSIX compatible, although more lenient POSIX-compliant readers can successfully extract most GNU tar archives. -.RS +.RS 4 +.nf struct header_gnu_tar { char name[100]; char mode[8]; @@ -491,17 +529,19 @@ struct header_gnu_tar { char pad[17]; }; .RE +.RS 5 .TP \fItypeflag\fP GNU tar uses the following special entry types, in addition to those defined by POSIX: +.RS 5 .TP -"7" +7 GNU tar treats type "7" records identically to type "0" records, except on one obscure RTOS where they are used to indicate the pre-allocation of a contiguous file on disk. .TP -"D" +D This indicates a directory entry. Unlike the POSIX-standard "5" typeflag, the header is followed by data records listing the names @@ -515,18 +555,19 @@ The purpose of this entry is to support incremental backups; a program restoring from such an archive may wish to delete files on disk that did not exist in the directory when the archive was made. +.PP Note that the "D" typeflag specifically violates POSIX, which requires that unrecognized typeflags be restored as normal files. In this case, restoring the "D" entry as a file could interfere with subsequent creation of the like-named directory. .TP -"K" +K The data for this entry is a long linkname for the following regular entry. .TP -"L" +L The data for this entry is a long pathname for the following regular entry. .TP -"M" +M This is a continuation of the last file on the previous volume. GNU multi-volume archives guarantee that each volume begins with a valid entry header. @@ -551,11 +592,8 @@ plus When extracting, GNU tar checks that the header file name is the one it is expecting, that the header offset is in the correct sequence, and that the sum of offset and size is equal to realsize. -FreeBSD's version of GNU tar does not handle the corner case of an -archive's being continued in the middle of a long name or other -extension header. .TP -"N" +N Type "N" records are no longer generated by GNU tar. They contained a list of files to be renamed or symlinked after extraction; this was @@ -567,8 +605,10 @@ or ``Symlink %s to %s\en ;'' in either case, both filenames are escaped using K&R C syntax. +Due to security concerns, "N" records are now generally ignored +when reading archives. .TP -"S" +S This is a ``sparse'' regular file. @@ -581,11 +621,12 @@ header extensions (an older format that is no longer used), or ``sparse'' extensions. .TP -"V" +V The \fIname\fP field should be interpreted as a tape/volume header name. This entry should generally be ignored on extraction. +.RE .TP \fImagic\fP The magic field holds the five characters @@ -622,7 +663,8 @@ If this is set to non-zero, the header will be followed by additional records. Each such record contains information about as many as 21 additional sparse blocks as shown here: -.RS +.RS 4 +.nf struct gnu_sparse_header { struct { char offset[12]; @@ -643,12 +685,78 @@ In that case, the POSIX size field will indicate the size of this entry; the \fIrealsize\fP field will indicate the total size of the file. +.RE +.SS GNU tar pax archives +GNU tar 1.14 (XXX check this XXX) and later will write +pax interchange format archives when you specify the +\fB\--posix\fP +flag. +This format uses custom keywords to store sparse file information. +There have been three iterations of this support, referred to +as +``0.0'', +``0.1'', +and +``1.0''. +.RS 5 +.TP +\fBGNU.sparse.numblocks\fP, \fBGNU.sparse.offset\fP, \fBGNU.sparse.numbytes\fP, \fBGNU.sparse.size\fP +The +``0.0'' +format used an initial +\fBGNU.sparse.numblocks\fP +attribute to indicate the number of blocks in the file, a pair of +\fBGNU.sparse.offset\fP +and +\fBGNU.sparse.numbytes\fP +to indicate the offset and size of each block, +and a single +\fBGNU.sparse.size\fP +to indicate the full size of the file. +This is not the same as the size in the tar header because the +latter value does not include the size of any holes. +This format required that the order of attributes be preserved and +relied on readers accepting multiple appearances of the same attribute +names, which is not officially permitted by the standards. +.TP +\fBGNU.sparse.map\fP +The +``0.1'' +format used a single attribute that stored a comma-separated +list of decimal numbers. +Each pair of numbers indicated the offset and size, respectively, +of a block of data. +This does not work well if the archive is extracted by an archiver +that does not recognize this extension, since many pax implementations +simply discard unrecognized attributes. +.TP +\fBGNU.sparse.major\fP, \fBGNU.sparse.minor\fP, \fBGNU.sparse.name\fP, \fBGNU.sparse.realsize\fP +The +``1.0'' +format stores the sparse block map in one or more 512-byte blocks +prepended to the file data in the entry body. +The pax attributes indicate the existence of this map +(via the +\fBGNU.sparse.major\fP +and +\fBGNU.sparse.minor\fP +fields) +and the full size of the file. +The +\fBGNU.sparse.name\fP +holds the true name of the file. +To avoid confusion, the name stored in the regular tar header +is a modified name so that extraction errors will be apparent +to users. +.RE .SS Solaris Tar XXX More Details Needed XXX +.PP Solaris tar (beginning with SunOS XXX 5.7 ?? XXX) supports an ``extended'' format that is fundamentally similar to pax interchange format, with the following differences: +.RS 5 .IP \(bu Extended attributes are stored in an entry whose type is \fBX\fP, @@ -664,15 +772,42 @@ An additional \fBA\fP entry is used to store an ACL for the following regular entry. The body of this entry contains a seven-digit octal number -(whose value is 01000000 plus the number of ACL entries) followed by a zero byte, followed by the textual ACL description. +The octal value is the number of ACL entries +plus a constant that indicates the ACL type: 01000000 +for POSIX.1e ACLs and 03000000 for NFSv4 ACLs. +.RE +.SS AIX Tar +XXX More details needed XXX +.SS Mac OS X Tar +The tar distributed with Apple's Mac OS X stores most regular files +as two separate entries in the tar archive. +The two entries have the same name except that the first +one has +``._'' +added to the beginning of the name. +This first entry stores the +``resource fork'' +with additional attributes for the file. +The Mac OS X +\fB\%CopyFile\fP() +API is used to separate a file on disk into separate +resource and data streams and to reassemble those separate +streams when the file is restored to disk. .SS Other Extensions -One common extension, utilized by GNU tar, star, and other newer -\fBtar\fP -implementations, permits binary numbers in the standard numeric -fields. -This is flagged by setting the high bit of the first character. +One obvious extension to increase the size of files is to +eliminate the terminating characters from the various +numeric fields. +For example, the standard only allows the size field to contain +11 octal digits, reserving the twelfth byte for a trailing +NUL character. +Allowing 12 octal digits allows file sizes up to 64 GB. +.PP +Another extension, utilized by GNU tar, star, and other newer +\fB\%tar\fP +implementations, permits binary numbers in the standard numeric fields. +This is flagged by setting the high bit of the first byte. This permits 95-bit values for the length and time fields and 63-bit values for the uid, gid, and device numbers. GNU tar supports this extension for the @@ -681,19 +816,19 @@ Joerg Schilling's star program supports this extension for all numeric fields. Note that this extension is largely obsoleted by the extended attribute record provided by the pax interchange format. -Another early GNU extension allowed base-64 values rather -than octal. -This extension was short-lived and such archives are almost never seen. -However, there is still code in GNU tar to support them; this code is -responsible for a very cryptic warning message that is sometimes seen when -GNU tar encounters a damaged archive. +.PP +Another early GNU extension allowed base-64 values rather than octal. +This extension was short-lived and is no longer supported by any +implementation. .SH SEE ALSO +.ad l \fBar\fP(1), \fBpax\fP(1), \fBtar\fP(1) .SH STANDARDS +.ad l The -\fBtar\fP +\fB\%tar\fP utility is no longer a part of POSIX or the Single Unix Standard. It last appeared in Version 2 of the Single UNIX Specification (``SUSv2''). @@ -705,21 +840,30 @@ utility. The pax interchange file format is new with IEEE Std 1003.1-2001 (``POSIX.1''). .SH HISTORY +.ad l A -\fBtar\fP +\fB\%tar\fP command appeared in Seventh Edition Unix, which was released in January, 1979. It replaced the -\fBtp\fP +\fB\%tp\fP program from Fourth Edition Unix which in turn replaced the -\fBtap\fP +\fB\%tap\fP program from First Edition Unix. John Gilmore's -\fBpdtar\fP +\fB\%pdtar\fP public-domain implementation (circa 1987) was highly influential and formed the basis of -\fBGNU\fP tar. +\fB\%GNU\fP tar +(circa 1988). Joerg Shilling's -\fBstar\fP +\fB\%star\fP archiver is another open-source (GPL) archiver (originally developed circa 1985) which features complete support for pax interchange format. +.PP +This documentation was written as part of the +\fB\%libarchive\fP +and +\fB\%bsdtar\fP +project by +Tim Kientzle \%<kientzle@FreeBSD.org.> |