From baea7d877d3cf69679a39e8512a120658a478073 Mon Sep 17 00:00:00 2001 From: Tomas Bzatek Date: Fri, 5 Feb 2010 11:06:31 +0100 Subject: Rebase libarchive to 2.8.0 --- libarchive/libarchive-2.8.0/doc/html/Makefile | 46 + .../libarchive-2.8.0/doc/html/archive_entry.3.html | 694 ++++++++++ .../libarchive-2.8.0/doc/html/archive_read.3.html | 820 ++++++++++++ .../doc/html/archive_read_disk.3.html | 341 +++++ .../libarchive-2.8.0/doc/html/archive_util.3.html | 210 +++ .../libarchive-2.8.0/doc/html/archive_write.3.html | 845 ++++++++++++ .../doc/html/archive_write_disk.3.html | 421 ++++++ .../libarchive-2.8.0/doc/html/bsdcpio.1.html | 519 ++++++++ libarchive/libarchive-2.8.0/doc/html/bsdtar.1.html | 1014 ++++++++++++++ libarchive/libarchive-2.8.0/doc/html/cpio.5.html | 422 ++++++ .../doc/html/libarchive-formats.5.html | 375 ++++++ .../libarchive-2.8.0/doc/html/libarchive.3.html | 329 +++++ .../doc/html/libarchive_internals.3.html | 381 ++++++ libarchive/libarchive-2.8.0/doc/html/mtree.5.html | 339 +++++ libarchive/libarchive-2.8.0/doc/html/tar.5.html | 1400 ++++++++++++++++++++ 15 files changed, 8156 insertions(+) create mode 100644 libarchive/libarchive-2.8.0/doc/html/Makefile create mode 100644 libarchive/libarchive-2.8.0/doc/html/archive_entry.3.html create mode 100644 libarchive/libarchive-2.8.0/doc/html/archive_read.3.html create mode 100644 libarchive/libarchive-2.8.0/doc/html/archive_read_disk.3.html create mode 100644 libarchive/libarchive-2.8.0/doc/html/archive_util.3.html create mode 100644 libarchive/libarchive-2.8.0/doc/html/archive_write.3.html create mode 100644 libarchive/libarchive-2.8.0/doc/html/archive_write_disk.3.html create mode 100644 libarchive/libarchive-2.8.0/doc/html/bsdcpio.1.html create mode 100644 libarchive/libarchive-2.8.0/doc/html/bsdtar.1.html create mode 100644 libarchive/libarchive-2.8.0/doc/html/cpio.5.html create mode 100644 libarchive/libarchive-2.8.0/doc/html/libarchive-formats.5.html create mode 100644 libarchive/libarchive-2.8.0/doc/html/libarchive.3.html create mode 100644 libarchive/libarchive-2.8.0/doc/html/libarchive_internals.3.html create mode 100644 libarchive/libarchive-2.8.0/doc/html/mtree.5.html create mode 100644 libarchive/libarchive-2.8.0/doc/html/tar.5.html (limited to 'libarchive/libarchive-2.8.0/doc/html') diff --git a/libarchive/libarchive-2.8.0/doc/html/Makefile b/libarchive/libarchive-2.8.0/doc/html/Makefile new file mode 100644 index 0000000..dcab40e --- /dev/null +++ b/libarchive/libarchive-2.8.0/doc/html/Makefile @@ -0,0 +1,46 @@ + +default: all + + +archive_entry.3.html: ../mdoc2man.awk ../../libarchive/archive_entry.3 + groff -mdoc -T html ../../libarchive/archive_entry.3 > archive_entry.3.html + +archive_read.3.html: ../mdoc2man.awk ../../libarchive/archive_read.3 + groff -mdoc -T html ../../libarchive/archive_read.3 > archive_read.3.html + +archive_read_disk.3.html: ../mdoc2man.awk ../../libarchive/archive_read_disk.3 + groff -mdoc -T html ../../libarchive/archive_read_disk.3 > archive_read_disk.3.html + +archive_util.3.html: ../mdoc2man.awk ../../libarchive/archive_util.3 + groff -mdoc -T html ../../libarchive/archive_util.3 > archive_util.3.html + +archive_write.3.html: ../mdoc2man.awk ../../libarchive/archive_write.3 + groff -mdoc -T html ../../libarchive/archive_write.3 > archive_write.3.html + +archive_write_disk.3.html: ../mdoc2man.awk ../../libarchive/archive_write_disk.3 + groff -mdoc -T html ../../libarchive/archive_write_disk.3 > archive_write_disk.3.html + +cpio.5.html: ../mdoc2man.awk ../../libarchive/cpio.5 + groff -mdoc -T html ../../libarchive/cpio.5 > cpio.5.html + +libarchive-formats.5.html: ../mdoc2man.awk ../../libarchive/libarchive-formats.5 + groff -mdoc -T html ../../libarchive/libarchive-formats.5 > libarchive-formats.5.html + +libarchive.3.html: ../mdoc2man.awk ../../libarchive/libarchive.3 + groff -mdoc -T html ../../libarchive/libarchive.3 > libarchive.3.html + +libarchive_internals.3.html: ../mdoc2man.awk ../../libarchive/libarchive_internals.3 + groff -mdoc -T html ../../libarchive/libarchive_internals.3 > libarchive_internals.3.html + +mtree.5.html: ../mdoc2man.awk ../../libarchive/mtree.5 + groff -mdoc -T html ../../libarchive/mtree.5 > mtree.5.html + +tar.5.html: ../mdoc2man.awk ../../libarchive/tar.5 + groff -mdoc -T html ../../libarchive/tar.5 > tar.5.html + +bsdtar.1.html: ../mdoc2man.awk ../../tar/bsdtar.1 + groff -mdoc -T html ../../tar/bsdtar.1 > bsdtar.1.html + +bsdcpio.1.html: ../mdoc2man.awk ../../cpio/bsdcpio.1 + groff -mdoc -T html ../../cpio/bsdcpio.1 > bsdcpio.1.html +all: archive_entry.3.html archive_read.3.html archive_read_disk.3.html archive_util.3.html archive_write.3.html archive_write_disk.3.html cpio.5.html libarchive-formats.5.html libarchive.3.html libarchive_internals.3.html mtree.5.html tar.5.html bsdtar.1.html bsdcpio.1.html diff --git a/libarchive/libarchive-2.8.0/doc/html/archive_entry.3.html b/libarchive/libarchive-2.8.0/doc/html/archive_entry.3.html new file mode 100644 index 0000000..7b30d72 --- /dev/null +++ b/libarchive/libarchive-2.8.0/doc/html/archive_entry.3.html @@ -0,0 +1,694 @@ + + + + + + + + + + + + + +
+ + +

archive_entry(3) FreeBSD Library Functions +Manual archive_entry(3)

+ +

NAME

+ + +

archive_entry_acl_add_entry, +archive_entry_acl_add_entry_w, +archive_entry_acl_clear, +archive_entry_acl_count, +archive_entry_acl_next, +archive_entry_acl_next_w, +archive_entry_acl_reset, +archive_entry_acl_text_w, archive_entry_atime, +archive_entry_atime_nsec, archive_entry_clear, +archive_entry_clone, +archive_entry_copy_fflags_text, +archive_entry_copy_fflags_text_w, +archive_entry_copy_gname, +archive_entry_copy_gname_w, +archive_entry_copy_hardlink, +archive_entry_copy_hardlink_w, +archive_entry_copy_link, +archive_entry_copy_link_w, +archive_entry_copy_pathname_w, +archive_entry_copy_sourcepath, +archive_entry_copy_stat, +archive_entry_copy_symlink, +archive_entry_copy_symlink_w, +archive_entry_copy_uname, +archive_entry_copy_uname_w, archive_entry_dev, +archive_entry_devmajor, +archive_entry_devminor, +archive_entry_filetype, archive_entry_fflags, +archive_entry_fflags_text, archive_entry_free, +archive_entry_gid, archive_entry_gname, +archive_entry_hardlink, archive_entry_ino, +archive_entry_mode, archive_entry_mtime, +archive_entry_mtime_nsec, archive_entry_nlink, +archive_entry_new, archive_entry_pathname, +archive_entry_pathname_w, archive_entry_rdev, +archive_entry_rdevmajor, +archive_entry_rdevminor, +archive_entry_set_atime, +archive_entry_set_ctime, +archive_entry_set_dev, +archive_entry_set_devmajor, +archive_entry_set_devminor, +archive_entry_set_filetype, +archive_entry_set_fflags, +archive_entry_set_gid, +archive_entry_set_gname, +archive_entry_set_hardlink, +archive_entry_set_link, +archive_entry_set_mode, +archive_entry_set_mtime, +archive_entry_set_pathname, +archive_entry_set_rdevmajor, +archive_entry_set_rdevminor, +archive_entry_set_size, +archive_entry_set_symlink, +archive_entry_set_uid, +archive_entry_set_uname, archive_entry_size, +archive_entry_sourcepath, archive_entry_stat, +archive_entry_symlink, archive_entry_uid, +archive_entry_uname — functions for +manipulating archive entry descriptions

+ + +

SYNOPSIS

+ +

#include +<archive_entry.h>

+ +

void

+ + +

archive_entry_acl_add_entry(struct archive_entry *, +int type, int permset, +int tag, int qual, +const char *name);

+ +

void

+ + +

archive_entry_acl_add_entry_w(struct archive_entry *, +int type, int permset, +int tag, int qual, +const wchar_t *name);

+ +

void

+ + +

archive_entry_acl_clear(struct archive_entry *);

+ +

int

+ + +

archive_entry_acl_count(struct archive_entry *, +int type);

+ +

int

+ + +

archive_entry_acl_next(struct archive_entry *, +int want_type, int *type, +int *permset, int *tag, +int *qual, +const char **name);

+ +

int

+ + +

archive_entry_acl_next_w(struct archive_entry *, +int want_type, int *type, +int *permset, int *tag, +int *qual, +const wchar_t **name);

+ +

int

+ + +

archive_entry_acl_reset(struct archive_entry *, +int want_type);

+ +

const wchar_t +*

+ + +

archive_entry_acl_text_w(struct archive_entry *, +int flags);

+ + +

time_t

+ + +

archive_entry_atime(struct archive_entry *);

+ +

long

+ + +

archive_entry_atime_nsec(struct archive_entry *);

+ +

struct +archive_entry *

+ + +

archive_entry_clear(struct archive_entry *);

+ +

struct +archive_entry *

+ + +

archive_entry_clone(struct archive_entry *);

+ +

const char * +*

+ + +

archive_entry_copy_fflags_text_w(struct archive_entry *, +const char *);

+ +

const wchar_t +*

+ + +

archive_entry_copy_fflags_text_w(struct archive_entry *, +const wchar_t *);

+ +

void

+ + +

archive_entry_copy_gname(struct archive_entry *, +const char *);

+ +

void

+ + +

archive_entry_copy_gname_w(struct archive_entry *, +const wchar_t *);

+ +

void

+ + +

archive_entry_copy_hardlink(struct archive_entry *, +const char *);

+ +

void

+ + +

archive_entry_copy_hardlink_w(struct archive_entry *, +const wchar_t *);

+ +

void

+ + +

archive_entry_copy_sourcepath(struct archive_entry *, +const char *);

+ +

void

+ + +

archive_entry_copy_pathname_w(struct archive_entry *, +const wchar_t *);

+ +

void

+ + +

archive_entry_copy_stat(struct archive_entry *, +const struct stat *);

+ +

void

+ + +

archive_entry_copy_symlink(struct archive_entry *, +const char *);

+ +

void

+ + +

archive_entry_copy_symlink_w(struct archive_entry *, +const wchar_t *);

+ +

void

+ + +

archive_entry_copy_uname(struct archive_entry *, +const char *);

+ +

void

+ + +

archive_entry_copy_uname_w(struct archive_entry *, +const wchar_t *);

+ + +

dev_t

+ + +

archive_entry_dev(struct archive_entry *);

+ + +

dev_t

+ + +

archive_entry_devmajor(struct archive_entry *);

+ + +

dev_t

+ + +

archive_entry_devminor(struct archive_entry *);

+ + +

mode_t

+ + +

archive_entry_filetype(struct archive_entry *);

+ +

void

+ + +

archive_entry_fflags(struct archive_entry *, +unsigned long *set, +unsigned long *clear);

+ +

const char +*

+ + +

archive_entry_fflags_text(struct archive_entry *);

+ +

void

+ + +

archive_entry_free(struct archive_entry *);

+ +

const char +*

+ + +

archive_entry_gname(struct archive_entry *);

+ +

const char +*

+ + +

archive_entry_hardlink(struct archive_entry *);

+ + +

ino_t

+ + +

archive_entry_ino(struct archive_entry *);

+ + +

mode_t

+ + +

archive_entry_mode(struct archive_entry *);

+ + +

time_t

+ + +

archive_entry_mtime(struct archive_entry *);

+ +

long

+ + +

archive_entry_mtime_nsec(struct archive_entry *);

+ +

unsigned +int

+ + +

archive_entry_nlink(struct archive_entry *);

+ +

struct +archive_entry *

+ + +

archive_entry_new(void);

+ +

const char +*

+ + +

archive_entry_pathname(struct archive_entry *);

+ +

const wchar_t +*

+ + +

archive_entry_pathname_w(struct archive_entry *);

+ + +

dev_t

+ + +

archive_entry_rdev(struct archive_entry *);

+ + +

dev_t

+ + +

archive_entry_rdevmajor(struct archive_entry *);

+ + +

dev_t

+ + +

archive_entry_rdevminor(struct archive_entry *);

+ +

void

+ + +

archive_entry_set_dev(struct archive_entry *, +dev_t);

+ +

void

+ + +

archive_entry_set_devmajor(struct archive_entry *, +dev_t);

+ +

void

+ + +

archive_entry_set_devminor(struct archive_entry *, +dev_t);

+ +

void

+ + +

archive_entry_set_filetype(struct archive_entry *, +unsigned int);

+ +

void

+ + +

archive_entry_set_fflags(struct archive_entry *, +unsigned long set, +unsigned long clear);

+ +

void

+ + +

archive_entry_set_gid(struct archive_entry *, +gid_t);

+ +

void

+ + +

archive_entry_set_gname(struct archive_entry *, +const char *);

+ +

void

+ + +

archive_entry_set_hardlink(struct archive_entry *, +const char *);

+ +

void

+ + +

archive_entry_set_ino(struct archive_entry *, +unsigned long);

+ +

void

+ + +

archive_entry_set_link(struct archive_entry *, +const char *);

+ +

void

+ + +

archive_entry_set_mode(struct archive_entry *, +mode_t);

+ +

void

+ + +

archive_entry_set_mtime(struct archive_entry *, +time_t, long nanos);

+ +

void

+ + +

archive_entry_set_nlink(struct archive_entry *, +unsigned int);

+ +

void

+ + +

archive_entry_set_pathname(struct archive_entry *, +const char *);

+ +

void

+ + +

archive_entry_set_rdev(struct archive_entry *, +dev_t);

+ +

void

+ + +

archive_entry_set_rdevmajor(struct archive_entry *, +dev_t);

+ +

void

+ + +

archive_entry_set_rdevminor(struct archive_entry *, +dev_t);

+ +

void

+ + +

archive_entry_set_size(struct archive_entry *, +int64_t);

+ +

void

+ + +

archive_entry_set_symlink(struct archive_entry *, +const char *);

+ +

void

+ + +

archive_entry_set_uid(struct archive_entry *, +uid_t);

+ +

void

+ + +

archive_entry_set_uname(struct archive_entry *, +const char *);

+ + +

int64_t

+ + +

archive_entry_size(struct archive_entry *);

+ +

const char +*

+ + +

archive_entry_sourcepath(struct archive_entry *);

+ +

const struct +stat *

+ + +

archive_entry_stat(struct archive_entry *);

+ +

const char +*

+ + +

archive_entry_symlink(struct archive_entry *);

+ +

const char +*

+ + +

archive_entry_uname(struct archive_entry *);

+ + +

DESCRIPTION

+ +

These functions create and +manipulate data objects that represent entries within an +archive. You can think of a struct archive_entry as a +heavy-duty version of struct stat: it includes everything +from struct stat plus associated pathname, textual group and +user names, etc. These objects are used by libarchive(3) to +represent the metadata associated with a particular entry in +an archive.

+ +

Create and +Destroy
+There are functions to allocate, destroy, clear, and copy +archive_entry objects:

+ +

archive_entry_clear()

+ +

Erases the object, resetting +all internal fields to the same state as a newly-created +object. This is provided to allow you to quickly recycle +objects without thrashing the heap.

+ +

archive_entry_clone()

+ +

A deep copy operation; all text +fields are duplicated.

+ +

archive_entry_free()

+ +

Releases the struct +archive_entry object.

+ +

archive_entry_new()

+ +

Allocate and return a blank +struct archive_entry object.

+ +

Set and Get +Functions
+Most of the functions here set or read entries in an object. +Such functions have one of the following forms:

+ +

archive_entry_set_XXXX()

+ +

Stores the provided data in the +object. In particular, for strings, the pointer is stored, +not the referenced string.

+ +

archive_entry_copy_XXXX()

+ +

As above, except that the +referenced data is copied into the object.

+ +

archive_entry_XXXX()

+ +

Returns the specified data. In +the case of strings, a const-qualified pointer to the string +is returned.

+ +

String data can be set or +accessed as wide character strings or normal char +strings. The functions that use wide character strings are +suffixed with _w. Note that these are different +representations of the same data: For example, if you store +a narrow string and read the corresponding wide string, the +object will transparently convert formats using the current +locale. Similarly, if you store a wide string and then store +a narrow string for the same data, the previously-set wide +string will be discarded in favor of the new data.

+ +

There are a few +set/get functions that merit additional description:

+ +

archive_entry_set_link()

+ +

This function sets the symlink +field if it is already set. Otherwise, it sets the hardlink +field.

+ +

File +Flags
+File flags are transparently converted between a bitmap +representation and a textual format. For example, if you set +the bitmap and ask for text, the library will build a +canonical text format. However, if you set a text format and +request a text format, you will get back the same text, even +if it is ill-formed. If you need to canonicalize a textual +flags string, you should first set the text form, then +request the bitmap form, then use that to set the bitmap +form. Setting the bitmap format will clear the internal text +representation and force it to be reconstructed when you +next request the text form.

+ +

The bitmap +format consists of two integers, one containing bits that +should be set, the other specifying bits that should be +cleared. Bits not mentioned in either bitmap will be +ignored. Usually, the bitmap of bits to be cleared will be +set to zero. In unusual circumstances, you can force a +fully-specified set of file flags by setting the bitmap of +flags to clear to the complement of the bitmap of flags to +set. (This differs from fflagstostr(3), which only includes +names for set bits.) Converting a bitmap to a textual string +is a platform-specific operation; bits that are not +meaningful on the current platform will be ignored.

+ +

The canonical +text format is a comma-separated list of flag names. The +archive_entry_copy_fflags_text() and +archive_entry_copy_fflags_text_w() functions parse +the provided text and sets the internal bitmap values. This +is a platform-specific operation; names that are not +meaningful on the current platform will be ignored. The +function returns a pointer to the start of the first name +that was not recognized, or NULL if every name was +recognized. Note that every name--including names that +follow an unrecognized name--will be evaluated, and the +bitmaps will be set to reflect every name that is +recognized. (In particular, this differs from +strtofflags(3), which stops parsing at the first +unrecognized name.)

+ +

ACL +Handling
+XXX This needs serious help. XXX

+ +

An +‘‘Access Control List’’ (ACL) is a +list of permissions that grant access to particular users or +groups beyond what would normally be provided by standard +POSIX mode bits. The ACL handling here addresses some +deficiencies in the POSIX.1e draft 17 ACL specification. In +particular, POSIX.1e draft 17 specifies several different +formats, but none of those formats include both textual +user/group names and numeric UIDs/GIDs.

+ +

XXX explain ACL +stuff XXX

+ +

SEE ALSO

+ +

archive(3)

+ +

HISTORY

+ +

The libarchive library +first appeared in FreeBSD 5.3.

+ +

AUTHORS

+ +

The libarchive library +was written by Tim Kientzle +⟨kientzle@acm.org⟩.

+ + +

FreeBSD 8.0 +May 12, 2008 FreeBSD 8.0

+
+ + diff --git a/libarchive/libarchive-2.8.0/doc/html/archive_read.3.html b/libarchive/libarchive-2.8.0/doc/html/archive_read.3.html new file mode 100644 index 0000000..c37fcac --- /dev/null +++ b/libarchive/libarchive-2.8.0/doc/html/archive_read.3.html @@ -0,0 +1,820 @@ + + + + + + + + + + + + + +
+ + +

archive_read(3) FreeBSD Library Functions +Manual archive_read(3)

+ +

NAME

+ +

archive_read_new, +archive_read_set_filter_options, +archive_read_set_format_options, +archive_read_set_options, +archive_read_support_compression_all, +archive_read_support_compression_bzip2, +archive_read_support_compression_compress, +archive_read_support_compression_gzip, +archive_read_support_compression_lzma, +archive_read_support_compression_none, +archive_read_support_compression_xz, +archive_read_support_compression_program, +archive_read_support_compression_program_signature, +archive_read_support_format_all, +archive_read_support_format_ar, +archive_read_support_format_cpio, +archive_read_support_format_empty, +archive_read_support_format_iso9660, +archive_read_support_format_mtree, +archive_read_support_format_raw, +archive_read_support_format_tar, +archive_read_support_format_zip, +archive_read_open, archive_read_open2, +archive_read_open_fd, archive_read_open_FILE, +archive_read_open_filename, +archive_read_open_memory, +archive_read_next_header, +archive_read_next_header2, archive_read_data, +archive_read_data_block, +archive_read_data_skip, +archive_read_data_into_buffer, +archive_read_data_into_fd, +archive_read_extract, archive_read_extract2, +archive_read_extract_set_progress_callback, +archive_read_close, archive_read_finish +— functions for reading streaming archives

+ + +

SYNOPSIS

+ +

#include +<archive.h>

+ +

struct +archive *

+ + +

archive_read_new(void);

+ +

int

+ + +

archive_read_support_compression_all(struct archive *);

+ +

int

+ + +

archive_read_support_compression_bzip2(struct archive *);

+ +

int

+ + +

archive_read_support_compression_compress(struct archive *);

+ +

int

+ + +

archive_read_support_compression_gzip(struct archive *);

+ +

int

+ + +

archive_read_support_compression_lzma(struct archive *);

+ +

int

+ + +

archive_read_support_compression_none(struct archive *);

+ +

int

+ + +

archive_read_support_compression_xz(struct archive *);

+ +

int

+ + +

archive_read_support_compression_program(struct archive *, +const char *cmd);

+ +

int

+ + +

archive_read_support_compression_program_signature(struct archive *, +const char *cmd, +const void *signature, +size_t signature_length);

+ +

int

+ + +

archive_read_support_format_all(struct archive *);

+ +

int

+ + +

archive_read_support_format_ar(struct archive *);

+ +

int

+ + +

archive_read_support_format_cpio(struct archive *);

+ +

int

+ + +

archive_read_support_format_empty(struct archive *);

+ +

int

+ + +

archive_read_support_format_iso9660(struct archive *);

+ +

int

+ + +

archive_read_support_format_mtree(struct archive *);

+ +

int

+ + +

archive_read_support_format_raw(struct archive *);

+ +

int

+ + +

archive_read_support_format_tar(struct archive *);

+ +

int

+ + +

archive_read_support_format_zip(struct archive *);

+ +

int

+ + +

archive_read_set_filter_options(struct archive *, +const char *);

+ +

int

+ + +

archive_read_set_format_options(struct archive *, +const char *);

+ +

int

+ + +

archive_read_set_options(struct archive *, +const char *);

+ +

int

+ + +

archive_read_open(struct archive *, +void *client_data, +archive_open_callback *, +archive_read_callback *, +archive_close_callback *);

+ +

int

+ + +

archive_read_open2(struct archive *, +void *client_data, +archive_open_callback *, +archive_read_callback *, +archive_skip_callback *, +archive_close_callback *);

+ +

int

+ + +

archive_read_open_FILE(struct archive *, +FILE *file);

+ +

int

+ + +

archive_read_open_fd(struct archive *, +int fd, size_t block_size);

+ +

int

+ + +

archive_read_open_filename(struct archive *, +const char *filename, +size_t block_size);

+ +

int

+ + +

archive_read_open_memory(struct archive *, +void *buff, size_t size);

+ +

int

+ + +

archive_read_next_header(struct archive *, +struct archive_entry **);

+ +

int

+ + +

archive_read_next_header2(struct archive *, +struct archive_entry *);

+ + +

ssize_t

+ + +

archive_read_data(struct archive *, +void *buff, size_t len);

+ +

int

+ + +

archive_read_data_block(struct archive *, +const void **buff, size_t *len, +off_t *offset);

+ +

int

+ + +

archive_read_data_skip(struct archive *);

+ +

int

+ + +

archive_read_data_into_buffer(struct archive *, +void *, ssize_t len);

+ +

int

+ + +

archive_read_data_into_fd(struct archive *, +int fd);

+ +

int

+ + +

archive_read_extract(struct archive *, +struct archive_entry *, +int flags);

+ +

int

+ + +

archive_read_extract2(struct archive *src, +struct archive_entry *, +struct archive *dest);

+ +

void

+ + +

archive_read_extract_set_progress_callback(struct archive *, +void (*func)(void *), +void *user_data);

+ +

int

+ + +

archive_read_close(struct archive *);

+ +

int

+ + +

archive_read_finish(struct archive *);

+ + +

DESCRIPTION

+ +

These functions provide a +complete API for reading streaming archives. The general +process is to first create the struct archive object, set +options, initialize the reader, iterate over the archive +headers and associated data, then close the archive and +release all resources. The following summary describes the +functions in approximately the order they would be used:

+ +

archive_read_new()

+ +

Allocates and initializes a +struct archive object suitable for reading from an +archive.

+ + +

archive_read_support_compression_bzip2(), +archive_read_support_compression_compress(), +archive_read_support_compression_gzip(), +archive_read_support_compression_lzma(), +archive_read_support_compression_none(), +archive_read_support_compression_xz()

+ +

Enables auto-detection code and +decompression support for the specified compression. Returns +ARCHIVE_OK if the compression is fully supported, or +ARCHIVE_WARN if the compression is supported only +through an external program. Note that decompression using +an external program is usually slower than decompression +through built-in libraries. Note that +‘‘none’’ is always enabled by +default.

+ + +

archive_read_support_compression_all()

+ +

Enables all available +decompression filters.

+ + +

archive_read_support_compression_program()

+ +

Data is fed through the +specified external program before being dearchived. Note +that this disables automatic detection of the compression +format, so it makes no sense to specify this in conjunction +with any other decompression option.

+ + +

archive_read_support_compression_program_signature()

+ +

This feeds data through the +specified external program but only if the initial bytes of +the data match the specified signature value.

+ +

archive_read_support_format_all(), +archive_read_support_format_ar(), +archive_read_support_format_cpio(), +archive_read_support_format_empty(), +archive_read_support_format_iso9660(), +archive_read_support_format_mtree(), +archive_read_support_format_tar(), +archive_read_support_format_zip()

+ +

Enables support---including +auto-detection code---for the specified archive format. For +example, archive_read_support_format_tar() enables +support for a variety of standard tar formats, old-style +tar, ustar, pax interchange format, and many common +variants. For convenience, +archive_read_support_format_all() enables support for +all available formats. Only empty archives are supported by +default.

+ + +

archive_read_support_format_raw()

+ +

The +‘‘raw’’ format handler allows +libarchive to be used to read arbitrary data. It treats any +data stream as an archive with a single entry. The pathname +of this entry is ‘‘data’’; all other +entry fields are unset. This is not enabled by +archive_read_support_format_all() in order to avoid +erroneous handling of damaged archives.

+ +

archive_read_set_filter_options(), +archive_read_set_format_options(), +archive_read_set_options()

+ +

Specifies options that will be +passed to currently-registered filters (including +decompression filters) and/or format readers. The argument +is a comma-separated list of individual options. Individual +options have one of the following forms:

+ +

option=value

+ +

The option/value pair will be +provided to every module. Modules that do not accept an +option with this name will ignore it.

+ +

option

+ +

The option will +be provided to every module with a value of +‘‘1’’.

+ +

!option

+ +

The option will be provided to +every module with a NULL value.

+ +

module:option=value, +module:option, module:!option

+ +

As above, but the corresponding +option and value will be provided only to modules whose name +matches module.

+ +

The return value will be +ARCHIVE_OK if any module accepts the option, or +ARCHIVE_WARN if no module accepted the option, or +ARCHIVE_FATAL if there was a fatal error while +attempting to process the option.

+ +

The currently +supported options are:

+ +

Format iso9660
+joliet

+ +

Support Joliet +extensions. Defaults to enabled, use !joliet to +disable.

+ +

archive_read_open()

+ +

The same as +archive_read_open2(), except that the skip callback +is assumed to be NULL.

+ +

archive_read_open2()

+ +

Freeze the settings, open the +archive, and prepare for reading entries. This is the most +generic version of this call, which accepts four callback +functions. Most clients will want to use +archive_read_open_filename(), +archive_read_open_FILE(), +archive_read_open_fd(), or +archive_read_open_memory() instead. The library +invokes the client-provided functions to obtain raw bytes +from the archive.

+ +

archive_read_open_FILE()

+ +

Like +archive_read_open(), except that it accepts a FILE +* pointer. This function should not be used with tape +drives or other devices that require strict I/O +blocking.

+ +

archive_read_open_fd()

+ +

Like +archive_read_open(), except that it accepts a file +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.

+ +

archive_read_open_file()

+ +

This is a deprecated synonym +for archive_read_open_filename().

+ +

archive_read_open_filename()

+ +

Like +archive_read_open(), except that it accepts a simple +filename and a block size. A NULL filename represents +standard input. This function is safe for use with tape +drives or other blocked devices.

+ +

archive_read_open_memory()

+ +

Like +archive_read_open(), except that it accepts a pointer +and size of a block of memory containing the archive +data.

+ +

archive_read_next_header()

+ +

Read the header for the next +entry and return a pointer to a struct archive_entry. This +is a convenience wrapper around +archive_read_next_header2() that reuses an internal +struct archive_entry object for each request.

+ +

archive_read_next_header2()

+ +

Read the header for the next +entry and populate the provided struct archive_entry.

+ +

archive_read_data()

+ +

Read data associated with the +header just read. Internally, this is a convenience function +that calls archive_read_data_block() and fills any +gaps with nulls so that callers see a single continuous +stream of data.

+ +

archive_read_data_block()

+ +

Return the next available block +of data for this entry. Unlike archive_read_data(), +the archive_read_data_block() function avoids copying +data and allows you to correctly handle sparse files, as +supported by some archive formats. The library guarantees +that offsets will increase and that blocks will not overlap. +Note that the blocks returned from this function can be much +larger than the block size read from disk, due to +compression and internal buffer optimizations.

+ +

archive_read_data_skip()

+ +

A convenience function that +repeatedly calls archive_read_data_block() to skip +all of the data for this archive entry.

+ +

archive_read_data_into_buffer()

+ +

This function is deprecated and +will be removed. Use archive_read_data() instead.

+ +

archive_read_data_into_fd()

+ +

A convenience function that +repeatedly calls archive_read_data_block() to copy +the entire entry to the provided file descriptor.

+ +

archive_read_extract(), +archive_read_extract_set_skip_file()

+ +

A convenience function that +wraps the corresponding archive_write_disk(3) interfaces. +The first call to archive_read_extract() creates a +restore object using archive_write_disk_new(3) and +archive_write_disk_set_standard_lookup(3), then +transparently invokes archive_write_disk_set_options(3), +archive_write_header(3), archive_write_data(3), and +archive_write_finish_entry(3) to create the entry on disk +and copy data into it. The flags argument is passed +unmodified to archive_write_disk_set_options(3).

+ +

archive_read_extract2()

+ +

This is another version of +archive_read_extract() that allows you to provide +your own restore object. In particular, this allows you to +override the standard lookup functions using +archive_write_disk_set_group_lookup(3), and +archive_write_disk_set_user_lookup(3). Note that +archive_read_extract2() does not accept a +flags argument; you should use +archive_write_disk_set_options() to set the restore +options yourself.

+ + +

archive_read_extract_set_progress_callback()

+ +

Sets a pointer to a +user-defined callback that can be used for updating progress +displays during extraction. The progress function will be +invoked during the extraction of large regular files. The +progress function will be invoked with the pointer provided +to this call. Generally, the data pointed to should include +a reference to the archive object and the archive_entry +object so that various statistics can be retrieved for the +progress display.

+ +

archive_read_close()

+ +

Complete the archive and invoke +the close callback.

+ +

archive_read_finish()

+ +

Invokes +archive_read_close() if it was not invoked manually, +then release all resources. Note: In libarchive 1.x, this +function was declared to return void, which made it +impossible to detect certain errors when +archive_read_close() was invoked implicitly from this +function. The declaration is corrected beginning with +libarchive 2.0.

+ +

Note that the +library determines most of the relevant information about +the archive by inspection. In particular, it automatically +detects gzip(1) or bzip2(1) compression and transparently +performs the appropriate decompression. It also +automatically detects the archive format.

+ +

A complete +description of the struct archive and struct archive_entry +objects can be found in the overview manual page for +libarchive(3).

+ +

CLIENT +CALLBACKS

+ +

The callback functions must +match the following prototypes:

+ +

typedef +ssize_t

+ + +

archive_read_callback(struct archive *, +void *client_data, +const void **buffer)

+ +

typedef +int

+ + +

archive_skip_callback(struct archive *, +void *client_data, +size_t request)

+ +

typedef +int archive_open_callback(struct archive +*, void *client_data)

+ +

typedef +int archive_close_callback(struct archive +*, void *client_data)

+ +

The open +callback is invoked by archive_open(). It should +return ARCHIVE_OK if the underlying file or data +source is successfully opened. If the open fails, it should +call archive_set_error() to register an error code +and message and return ARCHIVE_FATAL.

+ +

The read +callback is invoked whenever the library requires raw bytes +from the archive. The read callback should read data into a +buffer, set the const void **buffer argument to point to the +available data, and return a count of the number of bytes +available. The library will invoke the read callback again +only after it has consumed this data. The library imposes no +constraints on the size of the data blocks returned. On +end-of-file, the read callback should return zero. On error, +the read callback should invoke archive_set_error() +to register an error code and message and return -1.

+ +

The skip +callback is invoked when the library wants to ignore a block +of data. The return value is the number of bytes actually +skipped, which may differ from the request. If the callback +cannot skip data, it should return zero. If the skip +callback is not provided (the function pointer is NULL ), +the library will invoke the read function instead and simply +discard the result. A skip callback can provide significant +performance gains when reading uncompressed archives from +slow disk drives or other media that can skip quickly.

+ +

The close +callback is invoked by archive_close when the archive +processing is complete. The callback should return +ARCHIVE_OK on success. On failure, the callback +should invoke archive_set_error() to register an +error code and message and return ARCHIVE_FATAL.

+ +

EXAMPLE

+ +

The following illustrates basic +usage of the library. In this example, the callback +functions are simply wrappers around the standard open(2), +read(2), and close(2) system calls.

+ +

void
+list_archive(const char *name)
+{
+struct mydata *mydata;
+struct archive *a;
+struct archive_entry *entry;

+ +

mydata = +malloc(sizeof(struct mydata));
+a = archive_read_new();
+mydata->name = name;
+archive_read_support_compression_all(a);
+archive_read_support_format_all(a);
+archive_read_open(a, mydata, myopen, myread, myclose);
+while (archive_read_next_header(a, &entry) == +ARCHIVE_OK) {
+printf("%s\n",archive_entry_pathname(entry));
+archive_read_data_skip(a);
+}
+archive_read_finish(a);
+free(mydata);
+}

+ +

ssize_t
+myread(struct archive *a, void *client_data, const void +**buff)
+{
+struct mydata *mydata = client_data;

+ +

*buff = +mydata->buff;
+return (read(mydata->fd, mydata->buff, 10240));
+}

+ +

int
+myopen(struct archive *a, void *client_data)
+{
+struct mydata *mydata = client_data;

+ +

mydata->fd = +open(mydata->name, O_RDONLY);
+return (mydata->fd >= 0 ? ARCHIVE_OK : ARCHIVE_FATAL); +
+}

+ +

int
+myclose(struct archive *a, void *client_data)
+{
+struct mydata *mydata = client_data;

+ +

if +(mydata->fd > 0)
+close(mydata->fd);
+return (ARCHIVE_OK);
+}

+ +

RETURN +VALUES

+ +

Most functions return zero on +success, non-zero on error. The possible return codes +include: ARCHIVE_OK (the operation succeeded), +ARCHIVE_WARN (the operation succeeded but a +non-critical error was encountered), ARCHIVE_EOF +(end-of-archive was encountered), ARCHIVE_RETRY (the +operation failed but can be retried), and +ARCHIVE_FATAL (there was a fatal error; the archive +should be closed immediately). Detailed error codes and +textual descriptions are available from the +archive_errno() and archive_error_string() +functions.

+ + +

archive_read_new() +returns a pointer to a freshly allocated struct archive +object. It returns NULL on error.

+ + +

archive_read_data() +returns a count of bytes actually read or zero at the end of +the entry. On error, a value of ARCHIVE_FATAL, +ARCHIVE_WARN, or ARCHIVE_RETRY is returned and +an error code and textual description can be retrieved from +the archive_errno() and archive_error_string() +functions.

+ +

The library +expects the client callbacks to behave similarly. If there +is an error, you can use archive_set_error() to set +an appropriate error code and description, then return one +of the non-zero values above. (Note that the value +eventually returned to the client may not be the same; many +errors that are not critical at the level of basic I/O can +prevent the archive from being properly read, thus most I/O +errors eventually cause ARCHIVE_FATAL to be +returned.)

+ +

SEE ALSO

+ +

tar(1), archive(3), +archive_util(3), tar(5)

+ +

HISTORY

+ +

The libarchive library +first appeared in FreeBSD 5.3.

+ +

AUTHORS

+ +

The libarchive library +was written by Tim Kientzle +⟨kientzle@acm.org⟩.

+ +

BUGS

+ +

Many traditional archiver +programs treat empty files as valid empty archives. For +example, many implementations of tar(1) allow you to append +entries to an empty file. Of course, it is impossible to +determine the format of an empty file by inspecting the +contents, so this library treats empty files as having a +special ‘‘empty’’ format.

+ + +

FreeBSD 8.0 +April 13, 2009 FreeBSD 8.0

+
+ + diff --git a/libarchive/libarchive-2.8.0/doc/html/archive_read_disk.3.html b/libarchive/libarchive-2.8.0/doc/html/archive_read_disk.3.html new file mode 100644 index 0000000..2257ffe --- /dev/null +++ b/libarchive/libarchive-2.8.0/doc/html/archive_read_disk.3.html @@ -0,0 +1,341 @@ + + + + + + + + + + + + + +
+ + +

archive_read_disk(3) FreeBSD Library +Functions Manual archive_read_disk(3)

+ +

NAME

+ +

archive_read_disk_new, +archive_read_disk_set_symlink_logical, +archive_read_disk_set_symlink_physical, +archive_read_disk_set_symlink_hybrid, +archive_read_disk_entry_from_file, +archive_read_disk_gname, +archive_read_disk_uname, +archive_read_disk_set_uname_lookup, +archive_read_disk_set_gname_lookup, +archive_read_disk_set_standard_lookup, +archive_read_close, archive_read_finish +— functions for reading objects from disk

+ + +

SYNOPSIS

+ +

#include +<archive.h>

+ +

struct +archive *

+ + +

archive_read_disk_new(void);

+ +

int

+ + +

archive_read_disk_set_symlink_logical(struct archive *);

+ +

int

+ + +

archive_read_disk_set_symlink_physical(struct archive *);

+ +

int

+ + +

archive_read_disk_set_symlink_hybrid(struct archive *);

+ +

int

+ + +

archive_read_disk_gname(struct archive *, +gid_t);

+ +

int

+ + +

archive_read_disk_uname(struct archive *, +uid_t);

+ +

int

+ + +

archive_read_disk_set_gname_lookup(struct archive *, +void *, +const char *(*lookup)(void *, gid_t), +void (*cleanup)(void *));

+ +

int

+ + +

archive_read_disk_set_uname_lookup(struct archive *, +void *, +const char *(*lookup)(void *, uid_t), +void (*cleanup)(void *));

+ +

int

+ + +

archive_read_disk_set_standard_lookup(struct archive *);

+ +

int

+ + +

archive_read_disk_entry_from_file(struct archive *, +struct archive_entry *, int fd, +const struct stat *);

+ +

int

+ + +

archive_read_close(struct archive *);

+ +

int

+ + +

archive_read_finish(struct archive *);

+ + +

DESCRIPTION

+ +

These functions provide an API +for reading information about objects on disk. In +particular, they provide an interface for populating struct +archive_entry objects.

+ + +

archive_read_disk_new()

+ +

Allocates and initializes a +struct archive object suitable for reading object +information from disk.

+ + +

archive_read_disk_set_symlink_logical(), +archive_read_disk_set_symlink_physical(), +archive_read_disk_set_symlink_hybrid()

+ +

This sets the mode used for +handling symbolic links. The +‘‘logical’’ mode follows all +symbolic links. The ‘‘physical’’ +mode does not follow any symbolic links. The +‘‘hybrid’’ mode currently behaves +identically to the ‘‘logical’’ +mode.

+ + +

archive_read_disk_gname(), +archive_read_disk_uname()

+ +

Returns a user or group name +given a gid or uid value. By default, these always return a +NULL string.

+ + +

archive_read_disk_set_gname_lookup(), +archive_read_disk_set_uname_lookup()

+ +

These allow you to override the +functions used for user and group name lookups. You may also +provide a void * pointer to a private data structure and a +cleanup function for that data. The cleanup function will be +invoked when the struct archive object is destroyed or when +new lookup functions are registered.

+ + +

archive_read_disk_set_standard_lookup()

+ +

This convenience function +installs a standard set of user and group name lookup +functions. These functions use getpwid(3) and getgrid(3) to +convert ids to names, defaulting to NULL if the names cannot +be looked up. These functions also implement a simple memory +cache to reduce the number of calls to getpwid(3) and +getgrid(3).

+ + +

archive_read_disk_entry_from_file()

+ +

Populates a struct +archive_entry object with information about a particular +file. The archive_entry object must have already been +created with archive_entry_new(3) and at least one of the +source path or path fields must already be set. (If both are +set, the source path will be used.)

+ +

Information is +read from disk using the path name from the struct +archive_entry object. If a file descriptor is provided, some +information will be obtained using that file descriptor, on +platforms that support the appropriate system calls.

+ +

If a pointer to +a struct stat is provided, information from that structure +will be used instead of reading from the disk where +appropriate. This can provide performance benefits in +scenarios where struct stat information has already been +read from the disk as a side effect of some other operation. +(For example, directory traversal libraries often provide +this information.)

+ +

Where +necessary, user and group ids are converted to user and +group names using the currently registered lookup functions +above. This affects the file ownership fields and ACL values +in the struct archive_entry object.

+ + +

archive_read_close()

+ +

This currently does +nothing.

+ + +

archive_write_finish()

+ +

Invokes +archive_write_close() if it was not invoked manually, +then releases all resources.

+ +

More information about the +struct archive object and the overall design of the +library can be found in the libarchive(3) overview.

+ +

EXAMPLE

+ +

The following illustrates basic +usage of the library by showing how to use it to copy an +item on disk into an archive.

+ +

void
+file_to_archive(struct archive *a, const char *name)
+{
+char buff[8192];
+size_t bytes_read;
+struct archive *ard;
+struct archive_entry *entry;
+int fd;

+ +

ard = +archive_read_disk_new();
+archive_read_disk_set_standard_lookup(ard);
+entry = archive_entry_new();
+fd = open(name, O_RDONLY);
+if (fd < 0)
+return;
+archive_entry_copy_sourcepath(entry, name);
+archive_read_disk_entry_from_file(ard, entry, fd, NULL); +
+archive_write_header(a, entry);
+while ((bytes_read = read(fd, buff, sizeof(buff))) > 0) +
+archive_write_data(a, buff, bytes_read);
+archive_write_finish_entry(a);
+archive_read_finish(ard);
+archive_entry_free(entry);
+}

+ +

RETURN +VALUES

+ +

Most functions return +ARCHIVE_OK (zero) on success, or one of several +negative error codes for errors. Specific error codes +include: ARCHIVE_RETRY for operations that might +succeed if retried, ARCHIVE_WARN for unusual +conditions that do not prevent further operations, and +ARCHIVE_FATAL for serious errors that make remaining +operations impossible. The archive_errno(3) and +archive_error_string(3) functions can be used to retrieve an +appropriate error code and a textual error message. (See +archive_util(3) for details.)

+ + +

archive_read_disk_new() +returns a pointer to a newly-allocated struct archive object +or NULL if the allocation failed for any reason.

+ + +

archive_read_disk_gname() +and archive_read_disk_uname() return const char * +pointers to the textual name or NULL if the lookup failed +for any reason. The returned pointer points to internal +storage that may be reused on the next call to either of +these functions; callers should copy the string if they need +to continue accessing it.

+ +

SEE ALSO

+ +

archive_read(3), +archive_write(3), archive_write_disk(3), tar(1), +libarchive(3)

+ +

HISTORY

+ +

The libarchive library +first appeared in FreeBSD 5.3. The +archive_read_disk interface was added to +libarchive 2.6 and first appeared in +FreeBSD 8.0.

+ +

AUTHORS

+ +

The libarchive library +was written by Tim Kientzle +⟨kientzle@freebsd.org⟩.

+ +

BUGS

+ +

The +‘‘standard’’ user name and group +name lookup functions are not the defaults because +getgrid(3) and getpwid(3) are sometimes too large for +particular applications. The current design allows the +application author to use a more compact implementation when +appropriate.

+ +

The full list of +metadata read from disk by +archive_read_disk_entry_from_file() is necessarily +system-dependent.

+ +

The +archive_read_disk_entry_from_file() function reads as +much information as it can from disk. Some method should be +provided to limit this so that clients who do not need ACLs, +for instance, can avoid the extra work needed to look up +such information.

+ +

This API should +provide a set of methods for walking a directory tree. That +would make it a direct parallel of the archive_read(3) API. +When such methods are implemented, the +‘‘hybrid’’ symbolic link mode will +make sense.

+ + +

FreeBSD 8.0 +March 10, 2009 FreeBSD 8.0

+
+ + diff --git a/libarchive/libarchive-2.8.0/doc/html/archive_util.3.html b/libarchive/libarchive-2.8.0/doc/html/archive_util.3.html new file mode 100644 index 0000000..c4dd32c --- /dev/null +++ b/libarchive/libarchive-2.8.0/doc/html/archive_util.3.html @@ -0,0 +1,210 @@ + + + + + + + + + + + + + +
+ + +

archive_util(3) FreeBSD Library Functions +Manual archive_util(3)

+ +

NAME

+ +

archive_clear_error, +archive_compression, archive_compression_name, +archive_copy_error, archive_errno, +archive_error_string, archive_file_count, +archive_format, archive_format_name, +archive_set_error — libarchive utility +functions

+ + +

SYNOPSIS

+ +

#include +<archive.h>

+ +

void

+ + +

archive_clear_error(struct archive *);

+ +

int

+ + +

archive_compression(struct archive *);

+ +

const char +*

+ + +

archive_compression_name(struct archive *);

+ +

void

+ + +

archive_copy_error(struct archive *, +struct archive *);

+ +

int

+ + +

archive_errno(struct archive *);

+ +

const char +*

+ + +

archive_error_string(struct archive *);

+ +

int

+ + +

archive_file_count(struct archive *);

+ +

int

+ + +

archive_format(struct archive *);

+ +

const char +*

+ + +

archive_format_name(struct archive *);

+ +

void

+ + +

archive_set_error(struct archive *, +int error_code, +const char *fmt, ...);

+ + +

DESCRIPTION

+ +

These functions provide access +to various information about the struct archive object used +in the libarchive(3) library.

+ +

archive_clear_error()

+ +

Clears any error information +left over from a previous call. Not generally used in client +code.

+ +

archive_compression()

+ +

Returns a numeric code +indicating the current compression. This value is set by +archive_read_open().

+ +

archive_compression_name()

+ +

Returns a text description of +the current compression suitable for display.

+ +

archive_copy_error()

+ +

Copies error information from +one archive to another.

+ +

archive_errno()

+ +

Returns a numeric error code +(see errno(2)) indicating the reason for the most recent +error return.

+ +

archive_error_string()

+ +

Returns a textual error message +suitable for display. The error message here is usually more +specific than that obtained from passing the result of +archive_errno() to strerror(3).

+ +

archive_file_count()

+ +

Returns a count of the number +of files processed by this archive object. The count is +incremented by calls to archive_write_header or +archive_read_next_header.

+ +

archive_format()

+ +

Returns a numeric code +indicating the format of the current archive entry. This +value is set by a successful call to +archive_read_next_header(). Note that it is common +for this value to change from entry to entry. For example, a +tar archive might have several entries that utilize GNU tar +extensions and several entries that do not. These entries +will have different format codes.

+ +

archive_format_name()

+ +

A textual description of the +format of the current entry.

+ +

archive_set_error()

+ +

Sets the numeric error code and +error description that will be returned by +archive_errno() and archive_error_string(). +This function should be used within I/O callbacks to set +system-specific error codes and error descriptions. This +function accepts a printf-like format string and arguments. +However, you should be careful to use only the following +printf format specifiers: ‘‘%c’’, +‘‘%d’’, +‘‘%jd’’, +‘‘%jo’’, +‘‘%ju’’, +‘‘%jx’’, +‘‘%ld’’, +‘‘%lo’’, +‘‘%lu’’, +‘‘%lx’’, +‘‘%o’’, +‘‘%u’’, +‘‘%s’’, +‘‘%x’’, +‘‘%%’’. Field-width specifiers and +other printf features are not uniformly supported and should +not be used.

+ +

SEE ALSO

+ +

archive_read(3), +archive_write(3), libarchive(3), printf(3)

+ +

HISTORY

+ +

The libarchive library +first appeared in FreeBSD 5.3.

+ +

AUTHORS

+ +

The libarchive library +was written by Tim Kientzle +⟨kientzle@acm.org⟩.

+ + +

FreeBSD 8.0 +January 8, 2005 FreeBSD 8.0

+
+ + diff --git a/libarchive/libarchive-2.8.0/doc/html/archive_write.3.html b/libarchive/libarchive-2.8.0/doc/html/archive_write.3.html new file mode 100644 index 0000000..e72c5d5 --- /dev/null +++ b/libarchive/libarchive-2.8.0/doc/html/archive_write.3.html @@ -0,0 +1,845 @@ + + + + + + + + + + + + + +
+ + +

archive_write(3) FreeBSD Library Functions +Manual archive_write(3)

+ +

NAME

+ +

archive_write_new, +archive_write_set_format_cpio, +archive_write_set_format_pax, +archive_write_set_format_pax_restricted, +archive_write_set_format_shar, +archive_write_set_format_shar_binary, +archive_write_set_format_ustar, +archive_write_get_bytes_per_block, +archive_write_set_bytes_per_block, +archive_write_set_bytes_in_last_block, +archive_write_set_compression_bzip2, +archive_write_set_compression_compress, +archive_write_set_compression_gzip, +archive_write_set_compression_none, +archive_write_set_compression_program, +archive_write_set_compressor_options, +archive_write_set_format_options, +archive_write_set_options, archive_write_open, +archive_write_open_fd, +archive_write_open_FILE, +archive_write_open_filename, +archive_write_open_memory, +archive_write_header, archive_write_data, +archive_write_finish_entry, +archive_write_close, archive_write_finish +— functions for creating archives

+ + +

SYNOPSIS

+ +

#include +<archive.h>

+ +

struct +archive *

+ + +

archive_write_new(void);

+ +

int

+ + +

archive_write_get_bytes_per_block(struct archive *);

+ +

int

+ + +

archive_write_set_bytes_per_block(struct archive *, +int bytes_per_block);

+ +

int

+ + +

archive_write_set_bytes_in_last_block(struct archive *, +int);

+ +

int

+ + +

archive_write_set_compression_bzip2(struct archive *);

+ +

int

+ + +

archive_write_set_compression_compress(struct archive *);

+ +

int

+ + +

archive_write_set_compression_gzip(struct archive *);

+ +

int

+ + +

archive_write_set_compression_none(struct archive *);

+ +

int

+ + +

archive_write_set_compression_program(struct archive *, +const char * cmd);

+ +

int

+ + +

archive_write_set_format_cpio(struct archive *);

+ +

int

+ + +

archive_write_set_format_pax(struct archive *);

+ +

int

+ + +

archive_write_set_format_pax_restricted(struct archive *);

+ +

int

+ + +

archive_write_set_format_shar(struct archive *);

+ +

int

+ + +

archive_write_set_format_shar_binary(struct archive *);

+ +

int

+ + +

archive_write_set_format_ustar(struct archive *);

+ +

int

+ + +

archive_write_set_format_options(struct archive *, +const char *);

+ +

int

+ + +

archive_write_set_compressor_options(struct archive *, +const char *);

+ +

int

+ + +

archive_write_set_options(struct archive *, +const char *);

+ +

int

+ + +

archive_write_open(struct archive *, +void *client_data, +archive_open_callback *, +archive_write_callback *, +archive_close_callback *);

+ +

int

+ + +

archive_write_open_fd(struct archive *, +int fd);

+ +

int

+ + +

archive_write_open_FILE(struct archive *, +FILE *file);

+ +

int

+ + +

archive_write_open_filename(struct archive *, +const char *filename);

+ +

int

+ + +

archive_write_open_memory(struct archive *, +void *buffer, size_t bufferSize, +size_t *outUsed);

+ +

int

+ + +

archive_write_header(struct archive *, +struct archive_entry *);

+ + +

ssize_t

+ + +

archive_write_data(struct archive *, +const void *, size_t);

+ +

int

+ + +

archive_write_finish_entry(struct archive *);

+ +

int

+ + +

archive_write_close(struct archive *);

+ +

int

+ + +

archive_write_finish(struct archive *);

+ + +

DESCRIPTION

+ +

These functions provide a +complete API for creating streaming archive files. The +general process is to first create the struct archive +object, set any desired options, initialize the archive, +append entries, then close the archive and release all +resources. The following summary describes the functions in +approximately the order they are ordinarily used:

+ + +

archive_write_new()

+ +

Allocates and initializes a +struct archive object suitable for writing a tar +archive.

+ + +

archive_write_set_bytes_per_block()

+ +

Sets the block size used for +writing the archive data. Every call to the write callback +function, except possibly the last one, will use this value +for the length. The third parameter is a boolean that +specifies whether or not the final block written will be +padded to the full block size. If it is zero, the last block +will not be padded. If it is non-zero, padding will be added +both before and after compression. The default is to use a +block size of 10240 bytes and to pad the last block. Note +that a block size of zero will suppress internal blocking +and cause writes to be sent directly to the write callback +as they occur.

+ + +

archive_write_get_bytes_per_block()

+ +

Retrieve the block size to be +used for writing. A value of -1 here indicates that the +library should use default values. A value of zero indicates +that internal blocking is suppressed.

+ + +

archive_write_set_bytes_in_last_block()

+ +

Sets the block size used for +writing the last block. If this value is zero, the last +block will be padded to the same size as the other blocks. +Otherwise, the final block will be padded to a multiple of +this size. In particular, setting it to 1 will cause the +final block to not be padded. For compressed output, any +padding generated by this option is applied only after the +compression. The uncompressed data is always unpadded. The +default is to pad the last block to the full block size +(note that archive_write_open_filename() will set +this based on the file type). Unlike the other +‘‘set’’ functions, this function can +be called after the archive is opened.

+ + +

archive_write_get_bytes_in_last_block()

+ +

Retrieve the currently-set +value for last block size. A value of -1 here indicates that +the library should use default values.

+ + +

archive_write_set_format_cpio(), +archive_write_set_format_pax(), +archive_write_set_format_pax_restricted(), +archive_write_set_format_shar(), +archive_write_set_format_shar_binary(), +archive_write_set_format_ustar()

+ +

Sets the format that will be +used for the archive. The library can write POSIX +octet-oriented cpio format archives, POSIX-standard +‘‘pax interchange’’ format archives, +traditional ‘‘shar’’ archives, +enhanced ‘‘binary’’ shar archives +that store a variety of file attributes and handle binary +files, and POSIX-standard ‘‘ustar’’ +archives. The pax interchange format is a +backwards-compatible tar format that adds key/value +attributes to each entry and supports arbitrary filenames, +linknames, uids, sizes, etc. ‘‘Restricted pax +interchange format’’ is the library default; +this is the same as pax format, but suppresses the pax +extended header for most normal files. In most cases, this +will result in ordinary ustar archives.

+ + +

archive_write_set_compression_bzip2(), +archive_write_set_compression_compress(), +archive_write_set_compression_gzip(), +archive_write_set_compression_none()

+ +

The resulting archive will be +compressed as specified. Note that the compressed output is +always properly blocked.

+ + +

archive_write_set_compression_program()

+ +

The archive will be fed into +the specified compression program. The output of that +program is blocked and written to the client write +callbacks.

+ + +

archive_write_set_compressor_options(), +archive_write_set_format_options(), +archive_write_set_options()

+ +

Specifies options that will be +passed to the currently-enabled compressor and/or format +writer. The argument is a comma-separated list of individual +options. Individual options have one of the following +forms:

+ +

option=value

+ +

The option/value pair will be +provided to every module. Modules that do not accept an +option with this name will ignore it.

+ +

option

+ +

The option will +be provided to every module with a value of +‘‘1’’.

+ +

!option

+ +

The option will be provided to +every module with a NULL value.

+ +

module:option=value, +module:option, module:!option

+ +

As above, but the corresponding +option and value will be provided only to modules whose name +matches module.

+ +

The return value will be +ARCHIVE_OK if any module accepts the option, or +ARCHIVE_WARN if no module accepted the option, or +ARCHIVE_FATAL if there was a fatal error while +attempting to process the option.

+ +

The currently +supported options are:

+ +

Compressor gzip
+compression-level

+ +

The value is interpreted as a +decimal integer specifying the gzip compression level.

+ +

Compressor xz
+compression-level

+ +

The value is interpreted as a +decimal integer specifying the compression level.

+ +

Format mtree
+cksum, device, flags, gid, +gname, indent, link, md5, +mode, nlink, rmd160, sha1, +sha256, sha384, sha512, size, +time, uid, uname

+ +

Enable a particular keyword in +the mtree output. Prefix with an exclamation mark to disable +the corresponding keyword. The default is equivalent to +‘‘device, flags, gid, gname, link, mode, nlink, +size, time, type, uid, uname’’.

+ +

all

+ +

Enables all of +the above keywords.

+ +

use-set

+ +

Enables generation of +/set lines that specify default values for the +following files and/or directories.

+ +

indent

+ +

XXX needs +explanation XXX

+ + +

archive_write_open()

+ +

Freeze the settings, open the +archive, and prepare for writing entries. This is the most +generic form of this function, which accepts pointers to +three callback functions which will be invoked by the +compression layer to write the constructed archive.

+ + +

archive_write_open_fd()

+ +

A convenience form of +archive_write_open() that accepts a file descriptor. +The archive_write_open_fd() function is safe for use +with tape drives or other block-oriented devices.

+ + +

archive_write_open_FILE()

+ +

A convenience form of +archive_write_open() that accepts a FILE * +pointer. Note that archive_write_open_FILE() is not +safe for writing to tape drives or other devices that +require correct blocking.

+ + +

archive_write_open_file()

+ +

A deprecated synonym for +archive_write_open_filename().

+ + +

archive_write_open_filename()

+ +

A convenience form of +archive_write_open() that accepts a filename. A NULL +argument indicates that the output should be written to +standard output; an argument of +‘‘-’’ will open a file with that +name. If you have not invoked +archive_write_set_bytes_in_last_block(), then +archive_write_open_filename() will adjust the +last-block padding depending on the file: it will enable +padding when writing to standard output or to a character or +block device node, it will disable padding otherwise. You +can override this by manually invoking +archive_write_set_bytes_in_last_block() before +calling archive_write_open(). The +archive_write_open_filename() function is safe for +use with tape drives or other block-oriented devices.

+ + +

archive_write_open_memory()

+ +

A convenience form of +archive_write_open() that accepts a pointer to a +block of memory that will receive the archive. The final +size_t * argument points to a variable that will be +updated after each write to reflect how much of the buffer +is currently in use. You should be careful to ensure that +this variable remains allocated until after the archive is +closed.

+ + +

archive_write_header()

+ +

Build and write a header using +the data in the provided struct archive_entry structure. See +archive_entry(3) for information on creating and populating +struct archive_entry objects.

+ + +

archive_write_data()

+ +

Write data corresponding to the +header just written. Returns number of bytes written or -1 +on error.

+ + +

archive_write_finish_entry()

+ +

Close out the entry just +written. In particular, this writes out the final padding +required by some formats. Ordinarily, clients never need to +call this, as it is called automatically by +archive_write_next_header() and +archive_write_close() as needed.

+ + +

archive_write_close()

+ +

Complete the archive and invoke +the close callback.

+ + +

archive_write_finish()

+ +

Invokes +archive_write_close() if it was not invoked manually, +then releases all resources. Note that this function was +declared to return void in libarchive 1.x, which made +it impossible to detect errors when +archive_write_close() was invoked implicitly from +this function. This is corrected beginning with libarchive +2.0.

+ +

More information about the +struct archive object and the overall design of the +library can be found in the libarchive(3) overview.

+ + +

IMPLEMENTATION

+ +

Compression support is built-in +to libarchive, which uses zlib and bzlib to handle gzip and +bzip2 compression, respectively.

+ +

CLIENT +CALLBACKS

+ +

To use this library, you will +need to define and register callback functions that will be +invoked to write data to the resulting archive. These +functions are registered by calling +archive_write_open():

+ +

typedef +int archive_open_callback(struct archive +*, void *client_data)

+ +

The open +callback is invoked by archive_write_open(). It +should return ARCHIVE_OK if the underlying file or +data source is successfully opened. If the open fails, it +should call archive_set_error() to register an error +code and message and return ARCHIVE_FATAL.

+ +

typedef +ssize_t

+ + +

archive_write_callback(struct archive *, +void *client_data, +const void *buffer, +size_t length)

+ +

The write +callback is invoked whenever the library needs to write raw +bytes to the archive. For correct blocking, each call to the +write callback function should translate into a single +write(2) system call. This is especially critical when +writing archives to tape drives. On success, the write +callback should return the number of bytes actually written. +On error, the callback should invoke +archive_set_error() to register an error code and +message and return -1.

+ +

typedef +int archive_close_callback(struct archive +*, void *client_data)

+ +

The close +callback is invoked by archive_close when the archive +processing is complete. The callback should return +ARCHIVE_OK on success. On failure, the callback +should invoke archive_set_error() to register an +error code and message and return ARCHIVE_FATAL.

+ +

EXAMPLE

+ +

The following sketch illustrates +basic usage of the library. In this example, the callback +functions are simply wrappers around the standard open(2), +write(2), and close(2) system calls.

+ +

#ifdef +__linux__

+ + + + + + + +
+ + +

#define

 + + +

_FILE_OFFSET_BITS 64

 +
+ +

#endif
+#include <sys/stat.h>
+#include <archive.h>
+#include <archive_entry.h>
+#include <fcntl.h>
+#include <stdlib.h>
+#include <unistd.h>

+ +

struct mydata +{

+ + + + + + + + +
+ + +

const char *name;

+ + +

int fd;

+ +

};

+ +

int
+myopen(struct archive *a, void *client_data)
+{
+struct mydata *mydata = client_data;

+ +

mydata->fd = +open(mydata->name, O_WRONLY | O_CREAT, 0644);
+if (mydata->fd >= 0)
+return (ARCHIVE_OK);
+else
+return (ARCHIVE_FATAL);
+}

+ +

ssize_t
+mywrite(struct archive *a, void *client_data, const void +*buff, size_t n)
+{
+struct mydata *mydata = client_data;

+ +

return +(write(mydata->fd, buff, n));
+}

+ +

int
+myclose(struct archive *a, void *client_data)
+{
+struct mydata *mydata = client_data;

+ +

if +(mydata->fd > 0)
+close(mydata->fd);
+return (0);
+}

+ +

void
+write_archive(const char *outname, const char **filename) +
+{
+struct mydata *mydata = malloc(sizeof(struct mydata));
+struct archive *a;
+struct archive_entry *entry;
+struct stat st;
+char buff[8192];
+int len;
+int fd;

+ +

a = +archive_write_new();
+mydata->name = outname;
+archive_write_set_compression_gzip(a);
+archive_write_set_format_ustar(a);
+archive_write_open(a, mydata, myopen, mywrite, myclose); +
+while (*filename) {
+stat(*filename, &st);
+entry = archive_entry_new();
+archive_entry_copy_stat(entry, &st);
+archive_entry_set_pathname(entry, *filename);
+archive_write_header(a, entry);
+fd = open(*filename, O_RDONLY);
+len = read(fd, buff, sizeof(buff));
+while ( len > 0 ) {

+ + + + + + + + +
+ + +

archive_write_data(a, buff, len);

+ + +

len = read(fd, buff, sizeof(buff));

+ +

}
+archive_entry_free(entry);
+filename++;
+}
+archive_write_finish(a);
+}

+ +

int main(int +argc, const char **argv)
+{

+ + + + + + + + + + + + + + + + + +
+ + +

const char *outname;

+ + +

argv++;

+ + +

outname = argv++;

+ + +

write_archive(outname, argv);

+ + +

return 0;

+ +

}

+ +

RETURN +VALUES

+ +

Most functions return +ARCHIVE_OK (zero) on success, or one of several +non-zero error codes for errors. Specific error codes +include: ARCHIVE_RETRY for operations that might +succeed if retried, ARCHIVE_WARN for unusual +conditions that do not prevent further operations, and +ARCHIVE_FATAL for serious errors that make remaining +operations impossible. The archive_errno() and +archive_error_string() functions can be used to +retrieve an appropriate error code and a textual error +message.

+ + +

archive_write_new() +returns a pointer to a newly-allocated struct archive +object.

+ + +

archive_write_data() +returns a count of the number of bytes actually written. On +error, -1 is returned and the archive_errno() and +archive_error_string() functions will return +appropriate values. Note that if the client-provided write +callback function returns a non-zero value, that error will +be propagated back to the caller through whatever API +function resulted in that call, which may include +archive_write_header(), archive_write_data(), +archive_write_close(), or +archive_write_finish(). The client callback can call +archive_set_error() to provide values that can then +be retrieved by archive_errno() and +archive_error_string().

+ +

SEE ALSO

+ +

tar(1), libarchive(3), +tar(5)

+ +

HISTORY

+ +

The libarchive library +first appeared in FreeBSD 5.3.

+ +

AUTHORS

+ +

The libarchive library +was written by Tim Kientzle +⟨kientzle@acm.org⟩.

+ +

BUGS

+ +

There are many peculiar bugs in +historic tar implementations that may cause certain programs +to reject archives written by this library. For example, +several historic implementations calculated header checksums +incorrectly and will thus reject valid archives; GNU tar +does not fully support pax interchange format; some old tar +implementations required specific field terminations.

+ +

The default pax +interchange format eliminates most of the historic tar +limitations and provides a generic key/value attribute +facility for vendor-defined extensions. One oversight in +POSIX is the failure to provide a standard attribute for +large device numbers. This library uses +‘‘SCHILY.devminor’’ and +‘‘SCHILY.devmajor’’ for device +numbers that exceed the range supported by the +backwards-compatible ustar header. These keys are compatible +with Joerg Schilling’s star archiver. Other +implementations may not recognize these keys and will thus +be unable to correctly restore device nodes with large +device numbers from archives created by this library.

+ + +

FreeBSD 8.0 +May 11, 2008 FreeBSD 8.0

+
+ + diff --git a/libarchive/libarchive-2.8.0/doc/html/archive_write_disk.3.html b/libarchive/libarchive-2.8.0/doc/html/archive_write_disk.3.html new file mode 100644 index 0000000..3d7ef63 --- /dev/null +++ b/libarchive/libarchive-2.8.0/doc/html/archive_write_disk.3.html @@ -0,0 +1,421 @@ + + + + + + + + + + + + + +
+ + +

archive_write_disk(3) FreeBSD Library +Functions Manual archive_write_disk(3)

+ +

NAME

+ +

archive_write_disk_new, +archive_write_disk_set_options, +archive_write_disk_set_skip_file, +archive_write_disk_set_group_lookup, +archive_write_disk_set_standard_lookup, +archive_write_disk_set_user_lookup, +archive_write_header, archive_write_data, +archive_write_finish_entry, +archive_write_close, archive_write_finish +— functions for creating objects on disk

+ + +

SYNOPSIS

+ +

#include +<archive.h>

+ +

struct +archive *

+ + +

archive_write_disk_new(void);

+ +

int

+ + +

archive_write_disk_set_options(struct archive *, +int flags);

+ +

int

+ + +

archive_write_disk_set_skip_file(struct archive *, +dev_t, ino_t);

+ +

int

+ + +

archive_write_disk_set_group_lookup(struct archive *, +void *, +gid_t (*)(void *, const char *gname, gid_t gid), +void (*cleanup)(void *));

+ +

int

+ + +

archive_write_disk_set_standard_lookup(struct archive *);

+ +

int

+ + +

archive_write_disk_set_user_lookup(struct archive *, +void *, +uid_t (*)(void *, const char *uname, uid_t uid), +void (*cleanup)(void *));

+ +

int

+ + +

archive_write_header(struct archive *, +struct archive_entry *);

+ + +

ssize_t

+ + +

archive_write_data(struct archive *, +const void *, size_t);

+ +

int

+ + +

archive_write_finish_entry(struct archive *);

+ +

int

+ + +

archive_write_close(struct archive *);

+ +

int

+ + +

archive_write_finish(struct archive *);

+ + +

DESCRIPTION

+ +

These functions provide a +complete API for creating objects on disk from struct +archive_entry descriptions. They are most naturally used +when extracting objects from an archive using the +archive_read() interface. The general process is to +read struct archive_entry objects from an archive, then +write those objects to a struct archive object created using +the archive_write_disk() family functions. This +interface is deliberately very similar to the +archive_write() interface used to write objects to a +streaming archive.

+ + +

archive_write_disk_new()

+ +

Allocates and initializes a +struct archive object suitable for writing objects to +disk.

+ + +

archive_write_disk_set_skip_file()

+ +

Records the device and inode +numbers of a file that should not be overwritten. This is +typically used to ensure that an extraction process does not +overwrite the archive from which objects are being read. +This capability is technically unnecessary but can be a +significant performance optimization in practice.

+ + +

archive_write_disk_set_options()

+ +

The options field consists of a +bitwise OR of one or more of the following values:

+ +

ARCHIVE_EXTRACT_OWNER

+ +

The user and group IDs should +be set on the restored file. By default, the user and group +IDs are not restored.

+ +

ARCHIVE_EXTRACT_PERM

+ +

Full permissions (including +SGID, SUID, and sticky bits) should be restored exactly as +specified, without obeying the current umask. Note that SUID +and SGID bits can only be restored if the user and group ID +of the object on disk are correct. If +ARCHIVE_EXTRACT_OWNER is not specified, then SUID and +SGID bits will only be restored if the default user and +group IDs of newly-created objects on disk happen to match +those specified in the archive entry. By default, only basic +permissions are restored, and umask is obeyed.

+ +

ARCHIVE_EXTRACT_TIME

+ +

The timestamps (mtime, ctime, +and atime) should be restored. By default, they are ignored. +Note that restoring of atime is not currently supported.

+ +

ARCHIVE_EXTRACT_NO_OVERWRITE

+ +

Existing files on disk will not +be overwritten. By default, existing regular files are +truncated and overwritten; existing directories will have +their permissions updated; other pre-existing objects are +unlinked and recreated from scratch.

+ +

ARCHIVE_EXTRACT_UNLINK

+ +

Existing files on disk will be +unlinked before any attempt to create them. In some cases, +this can prove to be a significant performance improvement. +By default, existing files are truncated and rewritten, but +the file is not recreated. In particular, the default +behavior does not break existing hard links.

+ +

ARCHIVE_EXTRACT_ACL

+ +

Attempt to restore ACLs. By +default, extended ACLs are ignored.

+ +

ARCHIVE_EXTRACT_FFLAGS

+ +

Attempt to restore extended +file flags. By default, file flags are ignored.

+ +

ARCHIVE_EXTRACT_XATTR

+ +

Attempt to restore POSIX.1e +extended attributes. By default, they are ignored.

+ +

ARCHIVE_EXTRACT_SECURE_SYMLINKS

+ +

Refuse to extract any object +whose final location would be altered by a symlink on disk. +This is intended to help guard against a variety of mischief +caused by archives that (deliberately or otherwise) extract +files outside of the current directory. The default is not +to perform this check. If ARCHIVE_EXTRACT_UNLINK is +specified together with this option, the library will remove +any intermediate symlinks it finds and return an error only +if such symlink could not be removed.

+ +

ARCHIVE_EXTRACT_SECURE_NODOTDOT

+ +

Refuse to extract a path that +contains a .. element anywhere within it. The default +is to not refuse such paths. Note that paths ending in +.. always cause an error, regardless of this +flag.

+ +

ARCHIVE_EXTRACT_SPARSE

+ +

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.

+ + +

archive_write_disk_set_group_lookup(), +archive_write_disk_set_user_lookup()

+ +

The struct archive_entry +objects contain both names and ids that can be used to +identify users and groups. These names and ids describe the +ownership of the file itself and also appear in ACL lists. +By default, the library uses the ids and ignores the names, +but this can be overridden by registering user and group +lookup functions. To register, you must provide a lookup +function which accepts both a name and id and returns a +suitable id. You may also provide a void * pointer to a +private data structure and a cleanup function for that data. +The cleanup function will be invoked when the struct archive +object is destroyed.

+ + +

archive_write_disk_set_standard_lookup()

+ +

This convenience function +installs a standard set of user and group lookup functions. +These functions use getpwnam(3) and getgrnam(3) to convert +names to ids, defaulting to the ids if the names cannot be +looked up. These functions also implement a simple memory +cache to reduce the number of calls to getpwnam(3) and +getgrnam(3).

+ + +

archive_write_header()

+ +

Build and write a header using +the data in the provided struct archive_entry structure. See +archive_entry(3) for information on creating and populating +struct archive_entry objects.

+ + +

archive_write_data()

+ +

Write data corresponding to the +header just written. Returns number of bytes written or -1 +on error.

+ + +

archive_write_finish_entry()

+ +

Close out the entry just +written. Ordinarily, clients never need to call this, as it +is called automatically by +archive_write_next_header() and +archive_write_close() as needed.

+ + +

archive_write_close()

+ +

Set any attributes that could +not be set during the initial restore. For example, +directory timestamps are not restored initially because +restoring a subsequent file would alter that timestamp. +Similarly, non-writable directories are initially created +with write permissions (so that their contents can be +restored). The archive_write_disk_new library +maintains a list of all such deferred attributes and sets +them when this function is invoked.

+ + +

archive_write_finish()

+ +

Invokes +archive_write_close() if it was not invoked manually, +then releases all resources.

+ +

More information about the +struct archive object and the overall design of the +library can be found in the libarchive(3) overview. Many of +these functions are also documented under +archive_write(3).

+ +

RETURN +VALUES

+ +

Most functions return +ARCHIVE_OK (zero) on success, or one of several +non-zero error codes for errors. Specific error codes +include: ARCHIVE_RETRY for operations that might +succeed if retried, ARCHIVE_WARN for unusual +conditions that do not prevent further operations, and +ARCHIVE_FATAL for serious errors that make remaining +operations impossible. The archive_errno() and +archive_error_string() functions can be used to +retrieve an appropriate error code and a textual error +message.

+ + +

archive_write_disk_new() +returns a pointer to a newly-allocated struct archive +object.

+ + +

archive_write_data() +returns a count of the number of bytes actually written. On +error, -1 is returned and the archive_errno() and +archive_error_string() functions will return +appropriate values.

+ +

SEE ALSO

+ +

archive_read(3), +archive_write(3), tar(1), libarchive(3)

+ +

HISTORY

+ +

The libarchive library +first appeared in FreeBSD 5.3. The +archive_write_disk interface was added to +libarchive 2.0 and first appeared in +FreeBSD 6.3.

+ +

AUTHORS

+ +

The libarchive library +was written by Tim Kientzle +⟨kientzle@acm.org⟩.

+ +

BUGS

+ +

Directories are actually +extracted in two distinct phases. Directories are created +during archive_write_header(), but final permissions +are not set until archive_write_close(). This +separation is necessary to correctly handle borderline cases +such as a non-writable directory containing files, but can +cause unexpected results. In particular, directory +permissions are not fully restored until the archive is +closed. If you use chdir(2) to change the current directory +between calls to archive_read_extract() or before +calling archive_read_close(), you may confuse the +permission-setting logic with the result that directory +permissions are restored incorrectly.

+ +

The library +attempts to create objects with filenames longer than +PATH_MAX by creating prefixes of the full path and +changing the current directory. Currently, this logic is +limited in scope; the fixup pass does not work correctly for +such objects and the symlink security check option disables +the support for very long pathnames.

+ +

Restoring the +path aa/../bb does create each intermediate +directory. In particular, the directory aa is created +as well as the final object bb. In theory, this can +be exploited to create an entire directory heirarchy with a +single request. Of course, this does not work if the +ARCHIVE_EXTRACT_NODOTDOT option is specified.

+ +

Implicit +directories are always created obeying the current umask. +Explicit objects are created obeying the current umask +unless ARCHIVE_EXTRACT_PERM is specified, in which +case they current umask is ignored.

+ +

SGID and SUID +bits are restored only if the correct user and group could +be set. If ARCHIVE_EXTRACT_OWNER is not specified, +then no attempt is made to set the ownership. In this case, +SGID and SUID bits are restored only if the user and group +of the final object happen to match those specified in the +entry.

+ +

The +‘‘standard’’ user-id and group-id +lookup functions are not the defaults because getgrnam(3) +and getpwnam(3) are sometimes too large for particular +applications. The current design allows the application +author to use a more compact implementation when +appropriate.

+ +

There should be +a corresponding archive_read_disk interface that +walks a directory heirarchy and returns archive entry +objects.

+ + +

FreeBSD 8.0 +August 5, 2008 FreeBSD 8.0

+
+ + diff --git a/libarchive/libarchive-2.8.0/doc/html/bsdcpio.1.html b/libarchive/libarchive-2.8.0/doc/html/bsdcpio.1.html new file mode 100644 index 0000000..951f0e2 --- /dev/null +++ b/libarchive/libarchive-2.8.0/doc/html/bsdcpio.1.html @@ -0,0 +1,519 @@ + + + + + + + + + + + + + +
+ + +

BSDCPIO(1) FreeBSD General Commands Manual +BSDCPIO(1)

+ +

NAME

+ +

cpio — copy files +to and from archives

+ + +

SYNOPSIS

+ +

cpio {−i} +[options] [pattern ...] +[< archive]
+cpio {−o} [options] < +name-list [> archive]
+cpio {−p} [options] dest-dir < +name-list

+ + +

DESCRIPTION

+ +

cpio copies files between +archives and directories. This implementation can extract +from tar, pax, cpio, zip, jar, ar, and ISO 9660 cdrom images +and can create tar, pax, cpio, ar, and shar archives.

+ +

The first option +to cpio is a mode indicator from the following +list:

+ +

−i

+ +

Input. Read an +archive from standard input (unless overriden) and extract +the contents to disk or (if the −t option is +specified) list the contents to standard output. If one or +more file patterns are specified, only files matching one of +the patterns will be extracted.

+ +

−o

+ +

Output. Read a +list of filenames from standard input and produce a new +archive on standard output (unless overriden) containing the +specified items.

+ +

−p

+ +

Pass-through. +Read a list of filenames from standard input and copy the +files to the specified directory.

+ +

OPTIONS

+ +

Unless specifically stated +otherwise, options are applicable in all operating +modes.

+ + +

−0

+ +

Read filenames +separated by NUL characters instead of newlines. This is +necessary if any of the filenames being read might contain +newlines.

+ + +

−A

+ +

(o mode only) +Append to the specified archive. (Not yet implemented.)

+ + +

−a

+ +

(o and p modes) +Reset access times on files after they are read.

+ + +

−B

+ +

(o mode only) +Block output to records of 5120 bytes.

+ +

−C +size

+ +

(o mode only) Block output to +records of size bytes.

+ + +

−c

+ +

(o mode only) +Use the old POSIX portable character format. Equivalent to +−-format odc.

+ + +

−d

+ +

(i and p modes) +Create directories as necessary.

+ +

−E +file

+ +

(i mode only) Read list of file +name patterns from file to list and extract.

+ +

−F +file

+ +

Read archive from or write +archive to file.

+ +

−f +pattern

+ +

(i mode only) Ignore files that +match pattern.

+ + +

−-format +format

+ +

(o mode only) Produce the +output archive in the specified format. Supported formats +include:

+ +

cpio

+ +

Synonym for +odc.

+ +

newc

+ +

The SVR4 +portable cpio format.

+ +

odc

+ +

The old POSIX.1 +portable octet-oriented cpio format.

+ +

pax

+ +

The POSIX.1 pax +format, an extension of the ustar format.

+ +

ustar

+ +

The POSIX.1 tar +format.

+ +

The default +format is odc. See libarchive_formats(5) for more +complete information about the formats currently supported +by the underlying libarchive(3) library.

+ +

−H +format

+ +

Synonym for +−-format.

+ +

−h, +−-help

+ +

Print usage information.

+ +

−I +file

+ +

Read archive from +file.

+ + +

−i

+ +

Input mode. See +above for description.

+ + +

−-insecure

+ +

(i and p mode only) Disable +security checks during extraction or copying. This allows +extraction via symbolic links and path names containing +‘..’ in the name.

+ + +

−J

+ +

(o mode only) +Compress the file with xz-compatible compression before +writing it. In input mode, this option is ignored; xz +compression is recognized automatically on input.

+ + +

−j

+ +

Synonym for +−y.

+ + +

−L

+ +

(o and p modes) +All symbolic links will be followed. Normally, symbolic +links are archived and copied as symbolic links. With this +option, the target of the link will be archived or copied +instead.

+ + +

−l

+ +

(p mode only) +Create links from the target directory to the original +files, instead of copying.

+ + +

−lzma

+ +

(o mode only) +Compress the file with lzma-compatible compression before +writing it. In input mode, this option is ignored; lzma +compression is recognized automatically on input.

+ + +

−m

+ +

(i and p modes) +Set file modification time on created files to match those +in the source.

+ + +

−n

+ +

(i mode, only +with −t) Display numeric uid and gid. By +default, cpio displays the user and group names when +they are provided in the archive, or looks up the user and +group names in the system password database.

+ + +

−no-preserve-owner

+ +

(i mode only) Do not attempt to +restore file ownership. This is the default when run by +non-root users.

+ +

−O +file

+ +

Write archive to +file.

+ + +

−o

+ +

Output mode. +See above for description.

+ + +

−p

+ +

Pass-through +mode. See above for description.

+ + +

−preserve-owner

+ +

(i mode only) Restore file +ownership. This is the default when run by the root +user.

+ + +

−-quiet

+ +

Suppress unnecessary +messages.

+ +

−R [ +
+user][
+:][
+group]

+ +

Set the owner and/or group on +files in the output. If group is specified with no user (for +example, −R :wheel) then the group will +be set but not the user. If the user is specified with a +trailing colon and no group (for example, −R +root:) then the group will be set to the user’s +default group. If the user is specified with no trailing +colon, then the user will be set but not the group. In +−i and −p modes, this option can +only be used by the super-user. (For compatibility, a period +can be used in place of the colon.)

+ + +

−r

+ +

(All modes.) +Rename files interactively. For each file, a prompt is +written to /dev/tty containing the name of the file +and a line is read from /dev/tty. If the line read is +blank, the file is skipped. If the line contains a single +period, the file is processed normally. Otherwise, the line +is taken to be the new name of the file.

+ + +

−t

+ +

(i mode only) +List the contents of the archive to stdout; do not restore +the contents to disk.

+ + +

−u

+ +

(i and p modes) +Unconditionally overwrite existing files. Ordinarily, an +older file will not overwrite a newer file on disk.

+ + +

−v

+ +

Print the name +of each file to stderr as it is processed. With +−t, provide a detailed listing of each +file.

+ + +

−-version

+ +

Print the program version +information and exit.

+ + +

−y

+ +

(o mode only) +Compress the archive with bzip2-compatible compression +before writing it. In input mode, this option is ignored; +bzip2 compression is recognized automatically on input.

+ + +

−Z

+ +

(o mode only) +Compress the archive with compress-compatible compression +before writing it. In input mode, this option is ignored; +compression is recognized automatically on input.

+ + +

−z

+ +

(o mode only) +Compress the archive with gzip-compatible compression before +writing it. In input mode, this option is ignored; gzip +compression is recognized automatically on input.

+ + +

ENVIRONMENT

+ +

The following environment +variables affect the execution of cpio:

+ +

LANG

+ +

The locale to +use. See environ(7) for more information.

+ +

TZ

+ +

The timezone to +use when displaying dates. See environ(7) for more +information.

+ +

EXIT +STATUS

+ +

The cpio utility +exits 0 on success, and >0 if an error +occurs.

+ + +

EXAMPLES

+ +

The cpio command is +traditionally used to copy file heirarchies in conjunction +with the find(1) command. The first example here simply +copies all files from src to dest:

+ +

find src | +cpio −pmud dest

+ +

By carefully +selecting options to the find(1) command and combining it +with other standard utilities, it is possible to exercise +very fine control over which files are copied. This next +example copies files from src to dest that are +more than 2 days old and whose names match a particular +pattern:

+ +

find src +−mtime +2 | grep foo[bar] | +cpio −pdmu dest

+ +

This example +copies files from src to dest that are more +than 2 days old and which contain the word +‘‘

+ +

foobar ’’:

+ +

find src +−mtime +2 | xargs grep -l foobar +| cpio −pdmu dest

+ + +

COMPATIBILITY

+ +

The mode options i, o, and p and +the options a, B, c, d, f, l, m, r, t, u, and v comply with +SUSv2.

+ +

The old POSIX.1 +standard specified that only −i, +−o, and −p were interpreted as +command-line options. Each took a single argument of a list +of modifier characters. For example, the standard syntax +allows −imu but does not support +−miu or −i −m −u, +since m and u are only modifiers to +−i, they are not command-line options in their +own right. The syntax supported by this implementation is +backwards-compatible with the standard. For best +compatibility, scripts should limit themselves to the +standard syntax.

+ +

SEE ALSO

+ +

bzip2(1), tar(1), gzip(1), +mt(1), pax(1), libarchive(3), cpio(5), +libarchive-formats(5), tar(5)

+ + +

STANDARDS

+ +

There is no current POSIX +standard for the cpio command; it appeared in ISO/IEC +9945-1:1996 (‘‘POSIX.1’’) but was +dropped from IEEE Std 1003.1-2001 +(‘‘POSIX.1’’).

+ +

The cpio, ustar, +and pax interchange file formats are defined by IEEE Std +1003.1-2001 (‘‘POSIX.1’’) for the +pax command.

+ +

HISTORY

+ +

The original cpio and +find utilities were written by Dick Haight while +working in AT&T’s Unix Support Group. They first +appeared in 1977 in PWB/UNIX 1.0, the +‘‘Programmer’s Work Bench’’ +system developed for use within AT&T. They were first +released outside of AT&T as part of System III Unix in +1981. As a result, cpio actually predates tar, +even though it was not well-known outside of AT&T until +some time later.

+ +

This is a +complete re-implementation based on the libarchive(3) +library.

+ +

BUGS

+ +

The cpio archive format has +several basic limitations: It does not store user and group +names, only numbers. As a result, it cannot be reliably used +to transfer files between systems with dissimilar user and +group numbering. Older cpio formats limit the user and group +numbers to 16 or 18 bits, which is insufficient for modern +systems. The cpio archive formats cannot support files over +4 gigabytes, except for the ‘‘odc’’ +variant, which can support files up to 8 gigabytes.

+ + +

FreeBSD 8.0 +December 21, 2007 FreeBSD 8.0

+
+ + diff --git a/libarchive/libarchive-2.8.0/doc/html/bsdtar.1.html b/libarchive/libarchive-2.8.0/doc/html/bsdtar.1.html new file mode 100644 index 0000000..3b84d21 --- /dev/null +++ b/libarchive/libarchive-2.8.0/doc/html/bsdtar.1.html @@ -0,0 +1,1014 @@ + + + + + + + + + + + + + +
+ + +

BSDTAR(1) FreeBSD General Commands Manual +BSDTAR(1)

+ +

NAME

+ +

tar — manipulate +tape archives

+ + +

SYNOPSIS

+ +

tar +[bundled-flags ⟨

+ +

args ⟩] [⟨
+file ⟩ | ⟨
+pattern ⟩ ...]

+ +

tar {−c} +[options] +[files | directories]
+tar {−r | −u} +−f archive-file [options] +[files | directories]
+tar {−t | −x} +[options] [patterns]

+ + +

DESCRIPTION

+ +

tar creates and +manipulates streaming archive files. This implementation can +extract from tar, pax, cpio, zip, jar, ar, and ISO 9660 +cdrom images and can create tar, pax, cpio, ar, and shar +archives.

+ +

The first +synopsis form shows a ‘‘bundled’’ +option word. This usage is provided for compatibility with +historical implementations. See COMPATIBILITY below for +details.

+ +

The other +synopsis forms show the preferred usage. The first option to +tar is a mode indicator from the following list:

+ +

−c

+ +

Create a new +archive containing the specified items.

+ +

−r

+ +

Like +−c, but new entries are appended to the +archive. Note that this only works on uncompressed archives +stored in regular files. The −f option is +required.

+ +

−t

+ +

List archive +contents to stdout.

+ +

−u

+ +

Like +−r, but new entries are added only if they have +a modification date newer than the corresponding entry in +the archive. Note that this only works on uncompressed +archives stored in regular files. The −f option +is required.

+ +

−x

+ +

Extract to disk +from the archive. If a file with the same name appears more +than once in the archive, each copy will be extracted, with +later copies overwriting (replacing) earlier copies.

+ +

In +−c, −r, or −u mode, +each specified file or directory is added to the archive in +the order specified on the command line. By default, the +contents of each directory are also archived.

+ +

In extract or +list mode, the entire command line is read and parsed before +the archive is opened. The pathnames or patterns on the +command line indicate which items in the archive should be +processed. Patterns are shell-style globbing patterns as +documented in tcsh(1).

+ +

OPTIONS

+ +

Unless specifically stated +otherwise, options are applicable in all operating +modes.

+ + +

@archive

+ +

(c and r mode only) The +specified archive is opened and the entries in it will be +appended to the current archive. As a simple example,

+ +

tar −c −f +- newfile @original.tar

+ +

writes a new archive to +standard output containing a file newfile and all of +the entries from original.tar. In contrast,

+ +

tar −c −f +- newfile original.tar

+ +

creates a new archive with only +two entries. Similarly,

+ +

tar −czf - +−-format pax @-

+ +

reads an archive from standard +input (whose format will be determined automatically) and +converts it into a gzip-compressed pax-format archive on +stdout. In this way, tar can be used to convert +archives from one format to another.

+ +

−b +blocksize

+ +

Specify the block size, in +512-byte records, for tape drive I/O. As a rule, this +argument is only needed when reading from or writing to tape +drives, and usually not even then as the default block size +of 20 records (10240 bytes) is very common.

+ +

−C +directory

+ +

In c and r mode, this changes +the directory before adding the following files. In x mode, +change directories after opening the archive but before +extracting entries from the archive.

+ + +

−-check-links

+ +

(c and r modes only) Issue a +warning message unless all links to each file are +archived.

+ + +

−-chroot

+ +

(x mode only) chroot() +to the current directory after processing any +−C options and before extracting any files.

+ + +

−-exclude +pattern

+ +

Do not process files or +directories that match the specified pattern. Note that +exclusions take precedence over patterns or filenames +specified on the command line.

+ + +

−-format +format

+ +

(c, r, u mode only) Use the +specified format for the created archive. Supported formats +include ‘‘cpio’’, +‘‘pax’’, +‘‘shar’’, and +‘‘ustar’’. Other formats may also be +supported; see libarchive-formats(5) for more information +about currently-supported formats. In r and u modes, when +extending an existing archive, the format specified here +must be compatible with the format of the existing archive +on disk.

+ +

−f +file

+ +

Read the archive from or write +the archive to the specified file. The filename can be +- for standard input or standard output. If not +specified, the default tape device will be used. (On +FreeBSD, the default tape device is /dev/sa0.)

+ + +

−H

+ +

(c and r mode +only) Symbolic links named on the command line will be +followed; the target of the link will be archived, not the +link itself.

+ + +

−h

+ +

(c and r mode +only) Synonym for −L.

+ + +

−I

+ +

Synonym for +−T.

+ + +

−-include +pattern

+ +

Process only files or +directories that match the specified pattern. Note that +exclusions specified with −-exclude take +precedence over inclusions. If no inclusions are explicitly +specified, all entries are processed by default. The +−-include option is especially useful when +filtering archives. For example, the command

+ +

tar −c −f +new.tar −-include=’*foo*’ +@old.tgz

+ +

creates a new archive +new.tar containing only the entries from +old.tgz containing the string ‘foo’.

+ + +

−j

+ +

(c mode only) +Compress the resulting archive with bzip2(1). In extract or +list modes, this option is ignored. Note that, unlike other +tar implementations, this implementation recognizes +bzip2 compression automatically when reading archives.

+ + +

−k

+ +

(x mode only) +Do not overwrite existing files. In particular, if a file +appears more than once in an archive, later copies will not +overwrite earlier copies.

+ + +

−-keep-newer-files

+ +

(x mode only) Do not overwrite +existing files that are newer than the versions appearing in +the archive being extracted.

+ + +

−L

+ +

(c and r mode +only) All symbolic links will be followed. Normally, +symbolic links are archived as such. With this option, the +target of the link will be archived instead.

+ + +

−l

+ +

This is a +synonym for the −-check-links option.

+ + +

−m

+ +

(x mode only) +Do not extract modification time. By default, the +modification time is set to the time stored in the +archive.

+ + +

−n

+ +

(c, r, u modes +only) Do not recursively archive the contents of +directories.

+ + +

−-newer +date

+ +

(c, r, u modes only) Only +include files and directories newer than the specified date. +This compares ctime entries.

+ + +

−-newer-mtime +date

+ +

(c, r, u modes only) Like +−-newer, except it compares mtime entries +instead of ctime entries.

+ + +

−-newer-than +file

+ +

(c, r, u modes only) Only +include files and directories newer than the specified file. +This compares ctime entries.

+ + +

−-newer-mtime-than +file

+ +

(c, r, u modes only) Like +−-newer-than, except it compares mtime entries +instead of ctime entries.

+ + +

−-nodump

+ +

(c and r modes only) Honor the +nodump file flag by skipping this file.

+ + +

−-null

+ +

(use with +−I, −T, or −X) +Filenames or patterns are separated by null characters, not +by newlines. This is often used to read filenames output by +the −print0 option to find(1).

+ + +

−-numeric-owner

+ +

(x mode only) Ignore symbolic +user and group names when restoring archives to disk, only +numeric uid and gid values will be obeyed.

+ + +

−O

+ +

(x, t modes +only) In extract (-x) mode, files will be written to +standard out rather than being extracted to disk. In list +(-t) mode, the file listing will be written to stderr rather +than the usual stdout.

+ + +

−o

+ +

(x mode) Use +the user and group of the user running the program rather +than those specified in the archive. Note that this has no +significance unless −p is specified, and the +program is being run by the root user. In this case, the +file modes and flags from the archive will be restored, but +ACLs or owner information in the archive will be +discarded.

+ + +

−o

+ +

(c, r, u mode) +A synonym for −-format ustar

+ + +

−-one-file-system

+ +

(c, r, and u modes) Do not +cross mount points.

+ + +

−-options +options

+ +

Select optional behaviors for +particular modules. The argument is a text string containing +comma-separated keywords and values. These are passed to the +modules that handle particular formats to control how those +formats will behave. Each option has one of the following +forms:

+ +

key=value

+ +

The key will be set to the +specified value in every module that supports it. Modules +that do not support this key will ignore it.

+ +

key

+ +

The key will be +enabled in every module that supports it. This is equivalent +to key=1.

+ +

!key

+ +

The key will be +disabled in every module that supports it.

+ +

module:key=value, module:key, +module:!key

+ +

As above, but the corresponding +key and value will be provided only to modules whose name +matches module.

+ +

The currently supported modules +and keys are:

+ +

iso9660:joliet

+ +

Support Joliet extensions. This +is enabled by default, use !joliet or +iso9660:!joliet to disable.

+ +

iso9660:rockridge

+ +

Support Rock Ridge extensions. +This is enabled by default, use !rockridge or +iso9660:!rockridge to disable.

+ +

gzip:compression-level

+ +

A decimal integer from 0 to 9 +specifying the gzip compression level.

+ +

xz:compression-level

+ +

A decimal integer from 0 to 9 +specifying the xz compression level.

+ +

mtree:keyword

+ +

The mtree writer module allows +you to specify which mtree keywords will be included in the +output. Supported keywords include: cksum, +device, flags, gid, gname, +indent, link, md5, mode, +nlink, rmd160, sha1, sha256, +sha384, sha512, size, time, +uid, uname. The default is equivalent to: +‘‘device, flags, gid, gname, link, mode, nlink, +size, time, type, uid, uname’’.

+ +

mtree:all

+ +

Enables all of the above +keywords. You can also use mtree:!all to disable all +keywords.

+ +

mtree:use-set

+ +

Enable generation of +/set lines in the output.

+ +

mtree:indent

+ +

Produce human-readable output +by indenting options and splitting lines to fit into 80 +columns.

+ +

zip:compression=type

+ +

Use type as compression +method. Supported values are store (uncompressed) and +deflate (gzip algorithm).

+ +

If a provided option is not +supported by any module, that is a fatal error.

+ + +

−P

+ +

Preserve +pathnames. By default, absolute pathnames (those that begin +with a / character) have the leading slash removed both when +creating archives and extracting from them. Also, tar +will refuse to extract archive entries whose pathnames +contain .. or whose target directory would be altered +by a symlink. This option suppresses these behaviors.

+ + +

−p

+ +

(x mode only) +Preserve file permissions. Attempt to restore the full +permissions, including owner, file modes, file flags and +ACLs, if available, for each item extracted from the +archive. By default, newly-created files are owned by the +user running tar, the file mode is restored for +newly-created regular files, and all other types of entries +receive default permissions. If tar is being run by +root, the default is to restore the owner unless the +−o option is also specified.

+ +

−q +(−-fast-read)

+ +

(x and t mode only) Extract or +list only the first archive entry that matches each pattern +or filename operand. Exit as soon as each specified pattern +or filename has been matched. By default, the archive is +always read to the very end, since there can be multiple +entries with the same name and, by convention, later entries +overwrite earlier entries. This option is provided as a +performance optimization.

+ + +

−S

+ +

(x mode only) +Extract files as sparse files. For every block on disk, +check first if it contains only NULL bytes and seek over it +otherwise. This works similiar to the conv=sparse option of +dd.

+ + +

−-strip-components +count

+ +

(x mode only) Remove the +specified number of leading path elements. Pathnames with +fewer elements will be silently skipped. Note that the +pathname is edited after checking inclusion/exclusion +patterns but before security checks.

+ +

−s +pattern

+ +

Modify file or archive member +names according to pattern. The pattern has the +format /old/new/[gps] where old is a basic +regular expression, new is the replacement string of +the matched part, and the optional trailing letters modify +how the replacement is handled. If old is not +matched, the pattern is skipped. Within new, ~ is +substituted with the match, 1 to 9 with the content of the +corresponding captured group. The optional trailing g +specifies that matching should continue after the matched +part and stopped on the first unmatched pattern. The +optional trailing s specifies that the pattern applies to +the value of symbolic links. The optional trailing p +specifies that after a successful substitution the original +path name and the new path name should be printed to +standard error.

+ +

−T +filename

+ +

In x or t mode, tar will +read the list of names to be extracted from filename. +In c mode, tar will read names to be archived from +filename. The special name +‘‘-C’’ on a line by itself will +cause the current directory to be changed to the directory +specified on the following line. Names are terminated by +newlines unless −-null is specified. Note that +−-null also disables the special handling of +lines containing ‘‘-C’’.

+ + +

−U

+ +

(x mode only) +Unlink files before creating them. Without this option, +tar overwrites existing files, which preserves +existing hardlinks. With this option, existing hardlinks +will be broken, as will any symlink that would affect the +location of an extracted file.

+ + +

−-use-compress-program +program

+ +

Pipe the input (in x or t mode) +or the output (in c mode) through program instead of +using the builtin compression support.

+ + +

−v

+ +

Produce verbose +output. In create and extract modes, tar will list +each file name as it is read from or written to the archive. +In list mode, tar will produce output similar to that +of ls(1). Additional −v options will provide +additional detail.

+ + +

−-version

+ +

Print version of tar and +libarchive, and exit.

+ + +

−w

+ +

Ask for +confirmation for every action.

+ +

−X +filename

+ +

Read a list of exclusion +patterns from the specified file. See −-exclude +for more information about the handling of exclusions.

+ + +

−y

+ +

(c mode only) +Compress the resulting archive with bzip2(1). In extract or +list modes, this option is ignored. Note that, unlike other +tar implementations, this implementation recognizes +bzip2 compression automatically when reading archives.

+ + +

−z

+ +

(c mode only) +Compress the resulting archive with gzip(1). In extract or +list modes, this option is ignored. Note that, unlike other +tar implementations, this implementation recognizes +gzip compression automatically when reading archives.

+ + +

−Z

+ +

(c mode only) +Compress the resulting archive with compress(1). In extract +or list modes, this option is ignored. Note that, unlike +other tar implementations, this implementation +recognizes compress compression automatically when reading +archives.

+ + +

ENVIRONMENT

+ +

The following environment +variables affect the execution of tar:

+ +

LANG

+ +

The locale to +use. See environ(7) for more information.

+ +

TAPE

+ +

The default +tape device. The −f option overrides this.

+ +

TZ

+ +

The timezone to +use when displaying dates. See environ(7) for more +information.

+ +

FILES
+/dev/sa0

+ +

The default +tape device, if not overridden by the TAPE environment +variable or the −f option.

+ +

EXIT +STATUS

+ +

The tar utility +exits 0 on success, and >0 if an error +occurs.

+ + +

EXAMPLES

+ +

The following creates a new +archive called file.tar.gz that contains two files +source.c and source.h:

+ +

tar −czf +file.tar.gz source.c source.h

+ +

To view a +detailed table of contents for this archive:

+ +

tar −tvf +file.tar.gz

+ +

To extract all +entries from the archive on the default tape drive:

+ +

tar −x

+ +

To examine the +contents of an ISO 9660 cdrom image:

+ +

tar −tf +image.iso

+ +

To move file +hierarchies, invoke tar as

+ +

tar −cf - +−C srcdir . | tar −xpf +- −C destdir

+ +

or more traditionally

+ +

cd srcdir ; tar +−cf - . | (cd destdir ; tar +−xpf -)

+ +

In create mode, +the list of files and directories to be archived can also +include directory change instructions of the form +-Cfoo/baz and archive inclusions of the form +@archive-file. For example, the command +line

+ +

tar −c −f +new.tar foo1 @old.tgz -C/tmp +foo2

+ +

will create a new archive +new.tar. tar will read the file foo1 +from the current directory and add it to the output archive. +It will then read each entry from old.tgz and add +those entries to the output archive. Finally, it will switch +to the /tmp directory and add foo2 to the +output archive.

+ +

An input file in +mtree(5) format can be used to create an output archive with +arbitrary ownership, permissions, or names that differ from +existing data on disk:

+ +

$ cat +input.mtree
+#mtree
+usr/bin uid=0 gid=0 mode=0755 type=dir
+usr/bin/ls uid=0 gid=0 mode=0755 type=file content=myls
+$ tar -cvf output.tar @input.mtree

+ +

The +−-newer and −-newer-mtime switches +accept a variety of common date and time specifications, +including ‘‘12 Mar 2005 7:14:29pm’’, +‘‘2005-03-12 19:14’’, +‘‘5 minutes ago’’, and +‘‘19:14 PST May 1’’.

+ +

The +−-options argument can be used to control +various details of archive generation or reading. For +example, you can generate mtree output which only contains +type, time, and uid keywords:

+ +

tar −cf +file.tar −-format=mtree +−-options=’!all,type,time,uid’ +dir

+ +

or you can set the compression +level used by gzip or xz compression:

+ +

tar −czf +file.tar +−-options=’compression-level=9’.

+ +

For more details, see the +explanation of the archive_read_set_options() and +archive_write_set_options() API calls that are +described in archive_read(3) and archive_write(3).

+ + +

COMPATIBILITY

+ +

The bundled-arguments format is +supported for compatibility with historic implementations. +It consists of an initial word (with no leading - character) +in which each character indicates an option. Arguments +follow as separate words. The order of the arguments must +match the order of the corresponding characters in the +bundled command word. For example,

+ +

tar tbf 32 +file.tar

+ +

specifies three flags t, +b, and f. The b and f flags both +require arguments, so there must be two additional items on +the command line. The 32 is the argument to the +b flag, and file.tar is the argument to the +f flag.

+ +

The mode options +c, r, t, u, and x and the options b, f, l, m, o, v, and w +comply with SUSv2.

+ +

For maximum +portability, scripts that invoke tar should use the +bundled-argument format above, should limit themselves to +the c, t, and x modes, and the +b, f, m, v, and w +options.

+ +

Additional long +options are provided to improve compatibility with other tar +implementations.

+ + +

SECURITY

+ +

Certain security issues are +common to many archiving programs, including tar. In +particular, carefully-crafted archives can request that +tar extract files to locations outside of the target +directory. This can potentially be used to cause unwitting +users to overwrite files they did not intend to overwrite. +If the archive is being extracted by the superuser, any file +on the system can potentially be overwritten. There are +three ways this can happen. Although tar has +mechanisms to protect against each one, savvy users should +be aware of the implications:

+ +

•

+ +

Archive entries can have +absolute pathnames. By default, tar removes the +leading / character from filenames before restoring +them to guard against this problem.

+ +

•

+ +

Archive entries can have +pathnames that include .. components. By default, +tar will not extract files containing .. +components in their pathname.

+ +

•

+ +

Archive entries can exploit +symbolic links to restore files to other directories. An +archive can restore a symbolic link to another directory, +then use that link to restore a file into that directory. To +guard against this, tar checks each extracted path +for symlinks. If the final path element is a symlink, it +will be removed and replaced with the archive entry. If +−U is specified, any intermediate symlink will +also be unconditionally removed. If neither −U +nor −P is specified, tar will refuse to +extract the entry.

+ +

To protect yourself, you should +be wary of any archives that come from untrusted sources. +You should examine the contents of an archive with

+ +

tar −tf +filename

+ +

before extraction. You should +use the −k option to ensure that tar +will not overwrite any existing files or the −U +option to remove any pre-existing files. You should +generally not extract archives while running with super-user +privileges. Note that the −P option to +tar disables the security checks above and allows you +to extract an archive while preserving any absolute +pathnames, .. components, or symlinks to other +directories.

+ +

SEE ALSO

+ +

bzip2(1), compress(1), cpio(1), +gzip(1), mt(1), pax(1), shar(1), libarchive(3), +libarchive-formats(5), tar(5)

+ + +

STANDARDS

+ +

There is no current POSIX +standard for the tar command; it appeared in ISO/IEC +9945-1:1996 (‘‘POSIX.1’’) but was +dropped from IEEE Std 1003.1-2001 +(‘‘POSIX.1’’). The options used by +this implementation were developed by surveying a number of +existing tar implementations as well as the old POSIX +specification for tar and the current POSIX specification +for pax.

+ +

The ustar and +pax interchange file formats are defined by IEEE Std +1003.1-2001 (‘‘POSIX.1’’) for the +pax command.

+ +

HISTORY

+ +

A tar command appeared in +Seventh Edition Unix, which was released in January, 1979. +There have been numerous other implementations, many of +which extended the file format. John Gilmore’s +pdtar public-domain implementation (circa November, +1987) was quite influential, and formed the basis of GNU +tar. GNU tar was included as the standard system tar in +FreeBSD beginning with FreeBSD 1.0.

+ +

This is a +complete re-implementation based on the libarchive(3) +library.

+ +

BUGS

+ +

This program follows ISO/IEC +9945-1:1996 (‘‘POSIX.1’’) for the +definition of the −l option. Note that GNU tar +prior to version 1.15 treated −l as a synonym +for the −-one-file-system option.

+ +

The +−C dir option may differ from historic +implementations.

+ +

All archive +output is written in correctly-sized blocks, even if the +output is being compressed. Whether or not the last output +block is padded to a full block size varies depending on the +format and the output device. For tar and cpio formats, the +last block of output is padded to a full block size if the +output is being written to standard output or to a character +or block device such as a tape drive. If the output is being +written to a regular file, the last block will not be +padded. Many compressors, including gzip(1) and bzip2(1), +complain about the null padding when decompressing an +archive created by tar, although they still extract +it correctly.

+ +

The compression +and decompression is implemented internally, so there may be +insignificant differences between the compressed output +generated by

+ +

tar −czf - +file

+ +

and that generated by

+ +

tar −cf - +file | gzip

+ +

The default +should be to read and write archives to the standard I/O +paths, but tradition (and POSIX) dictates otherwise.

+ +

The r and +u modes require that the archive be uncompressed and +located in a regular file on disk. Other archives can be +modified using c mode with the @archive-file +extension.

+ +

To archive a +file called @foo or -foo you must specify it +as ./@foo or ./-foo, respectively.

+ +

In create mode, +a leading ./ is always removed. A leading / is +stripped unless the −P option is specified.

+ +

There needs to +be better support for file selection on both create and +extract.

+ +

There is not yet +any support for multi-volume archives or for archiving +sparse files.

+ +

Converting +between dissimilar archive formats (such as tar and cpio) +using the @- convention can cause hard link +information to be lost. (This is a consequence of the +incompatible ways that different archive formats store +hardlink information.)

+ +

There are +alternative long options for many of the short options that +are deliberately not documented.

+ + +

FreeBSD 8.0 +Oct 12, 2009 FreeBSD 8.0

+
+ + diff --git a/libarchive/libarchive-2.8.0/doc/html/cpio.5.html b/libarchive/libarchive-2.8.0/doc/html/cpio.5.html new file mode 100644 index 0000000..8d4768d --- /dev/null +++ b/libarchive/libarchive-2.8.0/doc/html/cpio.5.html @@ -0,0 +1,422 @@ + + + + + + + + + + + + + +
+ + +

CPIO(5) FreeBSD File Formats Manual +CPIO(5)

+ +

NAME

+ +

cpio — format of +cpio archive files

+ + +

DESCRIPTION

+ +

The cpio archive format +collects any number of files, directories, and other file +system objects (symbolic links, device nodes, etc.) into a +single stream of bytes.

+ +

General +Format
+Each file system object in a cpio archive comprises a +header record with basic numeric metadata followed by the +full pathname of the entry and the file data. The header +record stores a series of integer values that generally +follow the fields in struct stat. (See stat(2) for +details.) The variants differ primarily in how they store +those integers (binary, octal, or hexadecimal). The header +is followed by the pathname of the entry (the length of the +pathname is stored in the header) and any file data. The end +of the archive is indicated by a special record with the +pathname ‘‘TRAILER!!!’’.

+ +

PWB +format
+XXX Any documentation of the original PWB/UNIX 1.0 format? +XXX

+ +

Old Binary +Format
+The old binary cpio format stores numbers as 2-byte +and 4-byte binary values. Each entry begins with a header in +the following format:

+ +

struct +header_old_cpio {
+unsigned short c_magic;
+unsigned short c_dev;
+unsigned short c_ino;
+unsigned short c_mode;
+unsigned short c_uid;
+unsigned short c_gid;
+unsigned short c_nlink;
+unsigned short c_rdev;

+ + + + + + +
+ + +

unsigned short c_mtime[2];

 +
+ +

unsigned short c_namesize;

+ + + + + +
+ + +

unsigned short c_filesize[2];

+ +

};

+ +

The unsigned +short fields here are 16-bit integer values; the +unsigned int fields are 32-bit integer values. The +fields are as follows

+ +

magic

+ +

The integer +value octal 070707. This value can be used to determine +whether this archive is written with little-endian or +big-endian integers.

+ +

dev, +ino

+ +

The device and inode numbers +from the disk. These are used by programs that read +cpio archives to determine when two entries refer to +the same file. Programs that synthesize cpio archives +should be careful to set these to distinct values for each +entry.

+ +

mode

+ +

The mode +specifies both the regular permissions and the file type. It +consists of several bit fields as follows:

+ +

0170000

+ +

This masks the +file type bits.

+ +

0140000

+ +

File type value +for sockets.

+ +

0120000

+ +

File type value +for symbolic links. For symbolic links, the link body is +stored as file data.

+ +

0100000

+ +

File type value +for regular files.

+ +

0060000

+ +

File type value +for block special devices.

+ +

0040000

+ +

File type value +for directories.

+ +

0020000

+ +

File type value +for character special devices.

+ +

0010000

+ +

File type value +for named pipes or FIFOs.

+ +

0004000

+ +

SUID bit.

+ +

0002000

+ +

SGID bit.

+ +

0001000

+ +

Sticky bit. On +some systems, this modifies the behavior of executables +and/or directories.

+ +

0000777

+ +

The lower 9 +bits specify read/write/execute permissions for world, +group, and user following standard POSIX conventions.

+ +

uid, +gid

+ +

The numeric user id and group +id of the owner.

+ +

nlink

+ +

The number of +links to this file. Directories always have a value of at +least two here. Note that hardlinked files include file data +with every copy in the archive.

+ +

rdev

+ +

For block +special and character special entries, this field contains +the associated device number. For all other entry types, it +should be set to zero by writers and ignored by readers.

+ +

mtime

+ +

Modification +time of the file, indicated as the number of seconds since +the start of the epoch, 00:00:00 UTC January 1, 1970. The +four-byte integer is stored with the most-significant 16 +bits first followed by the least-significant 16 bits. Each +of the two 16 bit values are stored in machine-native byte +order.

+ + +

namesize

+ +

The number of bytes in the +pathname that follows the header. This count includes the +trailing NUL byte.

+ + +

filesize

+ +

The size of the file. Note that +this archive format is limited to four gigabyte file sizes. +See mtime above for a description of the storage of +four-byte integers.

+ +

The pathname +immediately follows the fixed header. If the namesize +is odd, an additional NUL byte is added after the pathname. +The file data is then appended, padded with NUL bytes to an +even length.

+ +

Hardlinked files +are not given special treatment; the full file contents are +included with each copy of the file.

+ +

Portable +ASCII Format
+Version 2 of the Single UNIX Specification +(‘‘SUSv2’’) standardized an ASCII +variant that is portable across all platforms. It is +commonly known as the ‘‘old +character’’ format or as the +‘‘odc’’ format. It stores the same +numeric fields as the old binary format, but represents them +as 6-character or 11-character octal values.

+ +

struct +cpio_odc_header {
+char c_magic[6];
+char c_dev[6];
+char c_ino[6];
+char c_mode[6];
+char c_uid[6];
+char c_gid[6];
+char c_nlink[6];
+char c_rdev[6];
+char c_mtime[11];
+char c_namesize[6];
+char c_filesize[11];
+};

+ +

The fields are +identical to those in the old binary format. The name and +file body follow the fixed header. Unlike the old binary +format, there is no additional padding after the pathname or +file contents. If the files being archived are themselves +entirely ASCII, then the resulting archive will be entirely +ASCII, except for the NUL byte that terminates the name +field.

+ +

New ASCII +Format
+The "new" ASCII format uses 8-byte hexadecimal +fields for all numbers and separates device numbers into +separate fields for major and minor numbers.

+ +

struct +cpio_newc_header {
+char c_magic[6];
+char c_ino[8];
+char c_mode[8];
+char c_uid[8];
+char c_gid[8];
+char c_nlink[8];
+char c_mtime[8];
+char c_filesize[8];
+char c_devmajor[8];
+char c_devminor[8];
+char c_rdevmajor[8];
+char c_rdevminor[8];
+char c_namesize[8];
+char c_check[8];
+};

+ +

Except as +specified below, the fields here match those specified for +the old binary format above.

+ +

magic

+ +

The string +‘‘070701’’.

+ +

check

+ +

This field is +always set to zero by writers and ignored by readers. See +the next section for more details.

+ +

The pathname is +followed by NUL bytes so that the total size of the fixed +header plus pathname is a multiple of four. Likewise, the +file data is padded to a multiple of four bytes. Note that +this format supports only 4 gigabyte files (unlike the older +ASCII format, which supports 8 gigabyte files).

+ +

In this format, +hardlinked files are handled by setting the filesize to zero +for each entry except the last one that appears in the +archive.

+ +

New CRC +Format
+The CRC format is identical to the new ASCII format +described in the previous section except that the magic +field is set to ‘‘070702’’ and the +check field is set to the sum of all bytes in the +file data. This sum is computed treating all bytes as +unsigned values and using unsigned arithmetic. Only the +least-significant 32 bits of the sum are stored.

+ +

HP +variants
+The cpio implementation distributed with HPUX used +XXXX but stored device numbers differently XXX.

+ +

Other +Extensions and Variants
+Sun Solaris uses additional file types to store extended +file data, including ACLs and extended attributes, as +special entries in cpio archives.

+ +

XXX Others? +XXX

+ +

BUGS

+ +

The +‘‘CRC’’ format is mis-named, as it +uses a simple checksum and not a cyclic redundancy +check.

+ +

The old binary +format is limited to 16 bits for user id, group id, device, +and inode numbers. It is limited to 4 gigabyte file +sizes.

+ +

The old ASCII +format is limited to 18 bits for the user id, group id, +device, and inode numbers. It is limited to 8 gigabyte file +sizes.

+ +

The new ASCII +format is limited to 4 gigabyte file sizes.

+ +

None of the cpio +formats store user or group names, which are essential when +moving files between systems with dissimilar user or group +numbering.

+ +

Especially when +writing older cpio variants, it may be necessary to map +actual device/inode values to synthesized values that fit +the available fields. With very large filesystems, this may +be necessary even for the newer formats.

+ +

SEE ALSO

+ +

cpio(1), tar(5)

+ + +

STANDARDS

+ +

The cpio utility is no +longer a part of POSIX or the Single Unix Standard. It last +appeared in Version 2 of the Single UNIX Specification +(‘‘SUSv2’’). It has been supplanted +in subsequent standards by pax(1). The portable ASCII format +is currently part of the specification for the pax(1) +utility.

+ +

HISTORY

+ +

The original cpio utility was +written by Dick Haight while working in AT&T’s +Unix Support Group. It appeared in 1977 as part of PWB/UNIX +1.0, the ‘‘Programmer’s Work +Bench’’ derived from Version 6 AT&T +UNIX that was used internally at AT&T. Both the old +binary and old character formats were in use by 1980, +according to the System III source released by SCO under +their ‘‘Ancient Unix’’ license. The +character format was adopted as part of IEEE Std 1003.1-1988 +(‘‘POSIX.1’’). XXX when did +"newc" appear? Who invented it? When did HP come +out with their variant? When did Sun introduce ACLs and +extended attributes? XXX

+ + +

FreeBSD 8.0 +October 5, 2007 FreeBSD 8.0

+
+ + diff --git a/libarchive/libarchive-2.8.0/doc/html/libarchive-formats.5.html b/libarchive/libarchive-2.8.0/doc/html/libarchive-formats.5.html new file mode 100644 index 0000000..db26b1e --- /dev/null +++ b/libarchive/libarchive-2.8.0/doc/html/libarchive-formats.5.html @@ -0,0 +1,375 @@ + + + + + + + + + + + + + +
+ + +

libarchive-formats(5) FreeBSD File Formats +Manual libarchive-formats(5)

+ +

NAME

+ +

libarchive-formats +— archive formats supported by the libarchive +library

+ + +

DESCRIPTION

+ +

The libarchive(3) library reads +and writes a variety of streaming archive formats. Generally +speaking, all of these archive formats consist of a series +of ‘‘entries’’. Each entry stores a +single file system object, such as a file, directory, or +symbolic link.

+ +

The following +provides a brief description of each format supported by +libarchive, with some information about recognized +extensions or limitations of the current library support. +Note that just because a format is supported by libarchive +does not imply that a program that uses libarchive will +support that format. Applications that use libarchive +specify which formats they wish to support, though many +programs do use libarchive convenience functions to enable +all supported formats.

+ +

Tar +Formats
+The libarchive(3) library can read most tar archives. +However, it only writes POSIX-standard +‘‘ustar’’ and ‘‘pax +interchange’’ formats.

+ +

All tar formats +store each entry in one or more 512-byte records. The first +record is used for file metadata, including filename, +timestamp, and mode information, and the file data is stored +in subsequent records. Later variants have extended this by +either appropriating undefined areas of the header record, +extending the header to multiple records, or by storing +special entries that modify the interpretation of subsequent +entries.

+ +

gnutar

+ +

The +libarchive(3) library can read GNU-format tar archives. It +currently supports the most popular GNU extensions, +including modern long filename and linkname support, as well +as atime and ctime data. The libarchive library does not +support multi-volume archives, nor the old GNU long filename +format. It can read GNU sparse file entries, including the +new POSIX-based formats, but cannot write GNU sparse file +entries.

+ +

pax

+ +

The +libarchive(3) library can read and write POSIX-compliant pax +interchange format archives. Pax interchange format archives +are an extension of the older ustar format that adds a +separate entry with additional attributes stored as +key/value pairs immediately before each regular entry. The +presence of these additional entries is the only difference +between pax interchange format and the older ustar format. +The extended attributes are of unlimited length and are +stored as UTF-8 Unicode strings. Keywords defined in the +standard are in all lowercase; vendors are allowed to define +custom keys by preceding them with the vendor name in all +uppercase. When writing pax archives, libarchive uses many +of the SCHILY keys defined by Joerg Schilling’s +‘‘star’’ archiver and a few +LIBARCHIVE keys. The libarchive library can read most of the +SCHILY keys and most of the GNU keys introduced by GNU tar. +It silently ignores any keywords that it does not +understand.

+ +

restricted +pax

+ +

The libarchive library can also +write pax archives in which it attempts to suppress the +extended attributes entry whenever possible. The result will +be identical to a ustar archive unless the extended +attributes entry is required to store a long file name, long +linkname, extended ACL, file flags, or if any of the +standard ustar data (user name, group name, UID, GID, etc) +cannot be fully represented in the ustar header. In all +cases, the result can be dearchived by any program that can +read POSIX-compliant pax interchange format archives. +Programs that correctly read ustar format (see below) will +also be able to read this format; any extended attributes +will be extracted as separate files stored in +PaxHeader directories.

+ +

ustar

+ +

The libarchive +library can both read and write this format. This format has +the following limitations:

+ +

•

+ +

Device major and minor numbers +are limited to 21 bits. Nodes with larger numbers will not +be added to the archive.

+ +

•

+ +

Path names in the archive are +limited to 255 bytes. (Shorter if there is no / character in +exactly the right place.)

+ +

•

+ +

Symbolic links and hard links +are stored in the archive with the name of the referenced +file. This name is limited to 100 bytes.

+ +

•

+ +

Extended attributes, file +flags, and other extended security information cannot be +stored.

+ +

•

+ +

Archive entries are limited to +8 gigabytes in size.

+ +

Note that the pax interchange +format has none of these restrictions.

+ +

The libarchive +library also reads a variety of commonly-used extensions to +the basic tar format. These extensions are recognized +automatically whenever they appear.

+ +

Numeric +extensions.

+ +

The POSIX standards require +fixed-length numeric fields to be written with some +character position reserved for terminators. Libarchive +allows these fields to be written without terminator +characters. This extends the allowable range; in particular, +ustar archives with this extension can support entries up to +64 gigabytes in size. Libarchive also recognizes base-256 +values in most numeric fields. This essentially removes all +limitations on file size, modification time, and device +numbers.

+ +

Solaris +extensions

+ +

Libarchive recognizes ACL and +extended attribute records written by Solaris tar. +Currently, libarchive only has support for old-style ACLs; +the newer NFSv4 ACLs are recognized but discarded.

+ +

The first tar +program appeared in Seventh Edition Unix in 1979. The first +official standard for the tar file format was the +‘‘ustar’’ (Unix Standard Tar) format +defined by POSIX in 1988. POSIX.1-2001 extended the ustar +format to create the ‘‘pax +interchange’’ format.

+ +

Cpio +Formats
+The libarchive library can read a number of common cpio +variants and can write ‘‘odc’’ and +‘‘newc’’ format archives. A cpio +archive stores each entry as a fixed-size header followed by +a variable-length filename and variable-length data. Unlike +the tar format, the cpio format does only minimal padding of +the header or file data. There are several cpio 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.

+ +

binary

+ +

The libarchive +library transparently reads both big-endian and +little-endian variants of the original binary cpio format. +This format used 32-bit binary values for file size and +mtime, and 16-bit binary values for the other fields.

+ +

odc

+ +

The libarchive +library can both read and write this POSIX-standard format, +which is officially known as the ‘‘cpio +interchange format’’ or the +‘‘octet-oriented cpio archive +format’’ and sometimes unofficially referred to +as the ‘‘old character format’’. +This format stores the header contents as octal values in +ASCII. It is standard, portable, and immune from byte-order +confusion. File sizes and mtime are limited to 33 bits (8GB +file size), other fields are limited to 18 bits.

+ +

SVR4

+ +

The libarchive +library can read both CRC and non-CRC variants of this +format. The SVR4 format uses eight-digit hexadecimal values +for all header fields. This limits file size to 4GB, and +also limits the mtime and other fields to 32 bits. The SVR4 +format can optionally include a CRC of the file contents, +although libarchive does not currently verify this CRC.

+ +

Cpio first +appeared in PWB/UNIX 1.0, which was released within AT&T +in 1977. PWB/UNIX 1.0 formed the basis of System III Unix, +released outside of AT&T in 1981. This makes cpio older +than tar, although cpio was not included in Version 7 +AT&T Unix. As a result, the tar command became much +better known in universities and research groups that used +Version 7. The combination of the find and +cpio utilities provided very precise control over +file selection. Unfortunately, the format has many +limitations that make it unsuitable for widespread use. Only +the POSIX format permits files over 4GB, and its 18-bit +limit for most other fields makes it unsuitable for modern +systems. In addition, cpio formats only store numeric +UID/GID values (not usernames and group names), which can +make it very difficult to correctly transfer archives across +systems with dissimilar user numbering.

+ +

Shar +Formats
+A ‘‘shell archive’’ is a shell +script that, when executed on a POSIX-compliant system, will +recreate a collection of file system objects. The libarchive +library can write two different kinds of shar archives:

+ +

shar

+ +

The traditional +shar format uses a limited set of POSIX commands, including +echo(1), mkdir(1), and sed(1). It is suitable for portably +archiving small collections of plain text files. However, it +is not generally well-suited for large archives (many +implementations of sh(1) have limits on the size of a +script) nor should it be used with non-text files.

+ + +

shardump

+ +

This format is similar to shar +but encodes files using uuencode(1) so that the result will +be a plain text file regardless of the file contents. It +also includes additional shell commands that attempt to +reproduce as many file attributes as possible, including +owner, mode, and flags. The additional commands used to +restore file attributes make shardump archives less portable +than plain shar archives.

+ +

ISO9660 +format
+Libarchive can read and extract from files containing +ISO9660-compliant CDROM images. In many cases, this can +remove the need to burn a physical CDROM just in order to +read the files contained in an ISO9660 image. It also avoids +security and complexity issues that come with virtual mounts +and loopback devices. Libarchive supports the most common +Rockridge extensions and has partial support for Joliet +extensions. If both extensions are present, the Joliet +extensions will be used and the Rockridge extensions will be +ignored. In particular, this can create problems with +hardlinks and symlinks, which are supported by Rockridge but +not by Joliet.

+ +

Zip +format
+Libarchive can read and write zip format archives that have +uncompressed entries and entries compressed with the +‘‘deflate’’ algorithm. Older zip +compression algorithms are not supported. It can extract jar +archives, archives that use Zip64 extensions and many +self-extracting zip archives. Libarchive reads Zip archives +as they are being streamed, which allows it to read archives +of arbitrary size. It currently does not use the central +directory; this limits libarchive’s ability to support +some self-extracting archives and ones that have been +modified in certain ways.

+ +

Archive +(library) file format
+The Unix archive format (commonly created by the ar(1) +archiver) is a general-purpose format which is used almost +exclusively for object files to be read by the link editor +ld(1). The ar format has never been standardised. There are +two common variants: the GNU format derived from SVR4, and +the BSD format, which first appeared in 4.4BSD. The two +differ primarily in their handling of filenames longer than +15 characters: the GNU/SVR4 variant writes a filename table +at the beginning of the archive; the BSD format stores each +long filename in an extension area adjacent to the entry. +Libarchive can read both extensions, including archives that +may include both types of long filenames. Programs using +libarchive can write GNU/SVR4 format if they provide a +filename table to be written into the archive before any of +the entries. Any entries whose names are not in the filename +table will be written using BSD-style long filenames. This +can cause problems for programs such as GNU ld that do not +support the BSD-style long filenames.

+ +

mtree +
+Libarchive can read and write files in mtree(5) format. This +format is not a true archive format, but rather a textual +description of a file hierarchy in which each line specifies +the name of a file and provides specific metadata about that +file. Libarchive can read all of the keywords supported by +both the NetBSD and FreeBSD versions of mtree(1), although +many of the keywords cannot currently be stored in an +archive_entry object. When writing, libarchive supports use +of the archive_write_set_options(3) interface to specify +which keywords should be included in the output. If +libarchive was compiled with access to suitable +cryptographic libraries (such as the OpenSSL libraries), it +can compute hash entries such as sha512 or md5 +from file data being written to the mtree writer.

+ +

When reading an +mtree file, libarchive will locate the corresponding files +on disk using the contents keyword if present or the +regular filename. If it can locate and open the file on +disk, it will use that to fill in any metadata that is +missing from the mtree file and will read the file contents +and return those to the program using libarchive. If it +cannot locate and open the file on disk, libarchive will +return an error for any attempt to read the entry body.

+ +

SEE ALSO

+ +

ar(1), cpio(1), mkisofs(1), +shar(1), tar(1), zip(1), zlib(3), cpio(5), mtree(5), +tar(5)

+ + +

FreeBSD 8.0 +December 27, 2009 FreeBSD 8.0

+
+ + diff --git a/libarchive/libarchive-2.8.0/doc/html/libarchive.3.html b/libarchive/libarchive-2.8.0/doc/html/libarchive.3.html new file mode 100644 index 0000000..f02d7cb --- /dev/null +++ b/libarchive/libarchive-2.8.0/doc/html/libarchive.3.html @@ -0,0 +1,329 @@ + + + + + + + + + + + + + +
+ + +

LIBARCHIVE(3) FreeBSD Library Functions +Manual LIBARCHIVE(3)

+ +

NAME

+ +

libarchive — +functions for reading and writing streaming archives

+ +

LIBRARY

+ +

Streaming Archive Library +(libarchive, −larchive)

+ + +

OVERVIEW

+ +

The libarchive library +provides a flexible interface for reading and writing +streaming archive files such as tar and cpio. The library is +inherently stream-oriented; readers serially iterate through +the archive, writers serially add things to the archive. In +particular, note that there is no built-in support for +random access nor for in-place modification.

+ +

When reading an +archive, the library automatically detects the format and +the compression. The library currently has read support +for:

+ +

•

+ +

old-style tar archives,

+ +

•

+ +

most variants of the POSIX +‘‘ustar’’ format,

+ +

•

+ +

the POSIX ‘‘pax +interchange’’ format,

+ +

•

+ +

GNU-format tar archives,

+ +

•

+ +

most common cpio archive +formats,

+ +

•

+ +

ISO9660 CD images (with or +without RockRidge extensions),

+ +

•

+ +

Zip archives.

+ +

The library automatically +detects archives compressed with gzip(1), bzip2(1), or +compress(1) and decompresses them transparently.

+ +

When writing an +archive, you can specify the compression to be used and the +format to use. The library can write

+ +

•

+ +

POSIX-standard +‘‘ustar’’ archives,

+ +

•

+ +

POSIX ‘‘pax +interchange format’’ archives,

+ +

•

+ +

POSIX octet-oriented cpio +archives,

+ +

•

+ +

two different variants of shar +archives.

+ +

Pax interchange format is an +extension of the tar archive format that eliminates +essentially all of the limitations of historic tar formats +in a standard fashion that is supported by POSIX-compliant +pax(1) implementations on many systems as well as several +newer implementations of tar(1). Note that the default write +format will suppress the pax extended attributes for most +entries; explicitly requesting pax format will enable those +attributes for all entries.

+ +

The read and +write APIs are accessed through the +archive_read_XXX() functions and the +archive_write_XXX() functions, respectively, and +either can be used independently of the other.

+ +

The rest of this +manual page provides an overview of the library operation. +More detailed information can be found in the individual +manual pages for each API or utility function.

+ +

READING AN +ARCHIVE

+ +

To read an archive, you must +first obtain an initialized struct archive object from +archive_read_new(). You can then modify this object +for the desired operations with the various +archive_read_set_XXX() and +archive_read_support_XXX() functions. In particular, +you will need to invoke appropriate +archive_read_support_XXX() functions to enable the +corresponding compression and format support. Note that +these latter functions perform two distinct operations: they +cause the corresponding support code to be linked into your +program, and they enable the corresponding auto-detect code. +Unless you have specific constraints, you will generally +want to invoke archive_read_support_compression_all() +and archive_read_support_format_all() to enable +auto-detect for all formats and compression types currently +supported by the library.

+ +

Once you have +prepared the struct archive object, you call +archive_read_open() to actually open the archive and +prepare it for reading. There are several variants of this +function; the most basic expects you to provide pointers to +several functions that can provide blocks of bytes from the +archive. There are convenience forms that allow you to +specify a filename, file descriptor, FILE * object, +or a block of memory from which to read the archive data. +Note that the core library makes no assumptions about the +size of the blocks read; callback functions are free to read +whatever block size is most appropriate for the medium.

+ +

Each archive +entry consists of a header followed by a certain amount of +data. You can obtain the next header with +archive_read_next_header(), which returns a pointer +to an struct archive_entry structure with information about +the current archive element. If the entry is a regular file, +then the header will be followed by the file data. You can +use archive_read_data() (which works much like the +read(2) system call) to read this data from the archive. You +may prefer to use the higher-level +archive_read_data_skip(), which reads and discards +the data for this entry, +archive_read_data_to_buffer(), which reads the data +into an in-memory buffer, +archive_read_data_to_file(), which copies the data to +the provided file descriptor, or +archive_read_extract(), which recreates the specified +entry on disk and copies data from the archive. In +particular, note that archive_read_extract() uses the +struct archive_entry structure that you provide it, which +may differ from the entry just read from the archive. In +particular, many applications will want to override the +pathname, file permissions, or ownership.

+ +

Once you have +finished reading data from the archive, you should call +archive_read_close() to close the archive, then call +archive_read_finish() to release all resources, +including all memory allocated by the library.

+ +

The +archive_read(3) manual page provides more detailed calling +information for this API.

+ +

WRITING AN +ARCHIVE

+ +

You use a similar process to +write an archive. The archive_write_new() function +creates an archive object useful for writing, the various +archive_write_set_XXX() functions are used to set +parameters for writing the archive, and +archive_write_open() completes the setup and opens +the archive for writing.

+ +

Individual +archive entries are written in a three-step process: You +first initialize a struct archive_entry structure with +information about the new entry. At a minimum, you should +set the pathname of the entry and provide a struct +stat with a valid st_mode field, which specifies +the type of object and st_size field, which specifies +the size of the data portion of the object. The +archive_write_header() function actually writes the +header data to the archive. You can then use +archive_write_data() to write the actual data.

+ +

After all +entries have been written, use the +archive_write_finish() function to release all +resources.

+ +

The +archive_write(3) manual page provides more detailed calling +information for this API.

+ + +

DESCRIPTION

+ +

Detailed descriptions of each +function are provided by the corresponding manual pages.

+ +

All of the +functions utilize an opaque struct archive datatype that +provides access to the archive contents.

+ +

The struct +archive_entry structure contains a complete description of a +single archive entry. It uses an opaque interface that is +fully documented in archive_entry(3).

+ +

Users familiar +with historic formats should be aware that the newer +variants have eliminated most restrictions on the length of +textual fields. Clients should not assume that filenames, +link names, user names, or group names are limited in +length. In particular, pax interchange format can easily +accommodate pathnames in arbitrary character sets that +exceed PATH_MAX.

+ +

RETURN +VALUES

+ +

Most functions return zero on +success, non-zero on error. The return value indicates the +general severity of the error, ranging from +ARCHIVE_WARN, which indicates a minor problem that +should probably be reported to the user, to +ARCHIVE_FATAL, which indicates a serious problem that +will prevent any further operations on this archive. On +error, the archive_errno() function can be used to +retrieve a numeric error code (see errno(2)). The +archive_error_string() returns a textual error +message suitable for display.

+ + +

archive_read_new() +and archive_write_new() return pointers to an +allocated and initialized struct archive object.

+ + +

archive_read_data() +and archive_write_data() return a count of the number +of bytes actually read or written. A value of zero indicates +the end of the data for this entry. A negative value +indicates an error, in which case the archive_errno() +and archive_error_string() functions can be used to +obtain more information.

+ + +

ENVIRONMENT

+ +

There are character set +conversions within the archive_entry(3) functions that are +impacted by the currently-selected locale.

+ +

SEE ALSO

+ +

tar(1), archive_entry(3), +archive_read(3), archive_util(3), archive_write(3), +tar(5)

+ +

HISTORY

+ +

The libarchive library +first appeared in FreeBSD 5.3.

+ +

AUTHORS

+ +

The libarchive library +was written by Tim Kientzle +⟨kientzle@acm.org⟩.

+ +

BUGS

+ +

Some archive formats support +information that is not supported by struct archive_entry. +Such information cannot be fully archived or restored using +this library. This includes, for example, comments, +character sets, or the arbitrary key/value pairs that can +appear in pax interchange format archives.

+ +

Conversely, of +course, not all of the information that can be stored in an +struct archive_entry is supported by all formats. For +example, cpio formats do not support nanosecond timestamps; +old tar formats do not support large device numbers.

+ + +

FreeBSD 8.0 +August 19, 2006 FreeBSD 8.0

+
+ + diff --git a/libarchive/libarchive-2.8.0/doc/html/libarchive_internals.3.html b/libarchive/libarchive-2.8.0/doc/html/libarchive_internals.3.html new file mode 100644 index 0000000..31c716a --- /dev/null +++ b/libarchive/libarchive-2.8.0/doc/html/libarchive_internals.3.html @@ -0,0 +1,381 @@ + + + + + + + + + + + + + +
+ + +

LIBARCHIVE(3) FreeBSD Library Functions +Manual LIBARCHIVE(3)

+ +

NAME

+ +

libarchive_internals +— description of libarchive internal interfaces

+ + +

OVERVIEW

+ +

The libarchive library +provides a flexible interface for reading and writing +streaming archive files such as tar and cpio. Internally, it +follows a modular layered design that should make it easy to +add new archive and compression formats.

+ +

GENERAL +ARCHITECTURE

+ +

Externally, libarchive exposes +most operations through an opaque, object-style interface. +The archive_entry(1) objects store information about a +single filesystem object. The rest of the library provides +facilities to write archive_entry(1) objects to archive +files, read them from archive files, and write them to disk. +(There are plans to add a facility to read archive_entry(1) +objects from disk as well.)

+ +

The read and +write APIs each have four layers: a public API layer, a +format layer that understands the archive file format, a +compression layer, and an I/O layer. The I/O layer is +completely exposed to clients who can replace it entirely +with their own functions.

+ +

In order to +provide as much consistency as possible for clients, some +public functions are virtualized. Eventually, it should be +possible for clients to open an archive or disk writer, and +then use a single set of code to select and write entries, +regardless of the target.

+ +

READ +ARCHITECTURE

+ +

From the outside, clients use +the archive_read(3) API to manipulate an archive +object to read entries and bodies from an archive stream. +Internally, the archive object is cast to an +archive_read object, which holds all read-specific +data. The API has four layers: The lowest layer is the I/O +layer. This layer can be overridden by clients, but most +clients use the packaged I/O callbacks provided, for +example, by archive_read_open_memory(3), and +archive_read_open_fd(3). The compression layer calls the I/O +layer to read bytes and decompresses them for the format +layer. The format layer unpacks a stream of uncompressed +bytes and creates archive_entry objects from the +incoming data. The API layer tracks overall state (for +example, it prevents clients from reading data before +reading a header) and invokes the format and compression +layer operations through registered function pointers. In +particular, the API layer drives the format-detection +process: When opening the archive, it reads an initial block +of data and offers it to each registered compression +handler. The one with the highest bid is initialized with +the first block. Similarly, the format handlers are polled +to see which handler is the best for each archive. (Prior to +2.4.0, the format bidders were invoked for each entry, but +this design hindered error recovery.)

+ +

I/O Layer and +Client Callbacks
+The read API goes to some lengths to be nice to clients. As +a result, there are few restrictions on the behavior of the +client callbacks.

+ +

The client read +callback is expected to provide a block of data on each +call. A zero-length return does indicate end of file, but +otherwise blocks may be as small as one byte or as large as +the entire file. In particular, blocks may be of different +sizes.

+ +

The client skip +callback returns the number of bytes actually skipped, which +may be much smaller than the skip requested. The only +requirement is that the skip not be larger. In particular, +clients are allowed to return zero for any skip that they +don’t want to handle. The skip callback must never be +invoked with a negative value.

+ +

Keep in mind +that not all clients are reading from disk: clients reading +from networks may provide different-sized blocks on every +request and cannot skip at all; advanced clients may use +mmap(2) to read the entire file into memory at once and +return the entire file to libarchive as a single block; +other clients may begin asynchronous I/O operations for the +next block on each request.

+ + +

Decompresssion +Layer
+The decompression layer not only handles decompression, it +also buffers data so that the format handlers see a much +nicer I/O model. The decompression API is a two stage +peek/consume model. A read_ahead request specifies a minimum +read amount; the decompression layer must provide a pointer +to at least that much data. If more data is immediately +available, it should return more: the format layer handles +bulk data reads by asking for a minimum of one byte and then +copying as much data as is available.

+ +

A subsequent +call to the consume() function advances the read +pointer. Note that data returned from a read_ahead() +call is guaranteed to remain in place until the next call to +read_ahead(). Intervening calls to consume() +should not cause the data to move.

+ +

Skip requests +must always be handled exactly. Decompression handlers that +cannot seek forward should not register a skip handler; the +API layer fills in a generic skip handler that reads and +discards data.

+ +

A decompression +handler has a specific lifecycle:

+ +

Registration/Configuration

+ +

When the client invokes the +public support function, the decompression handler invokes +the internal __archive_read_register_compression() +function to provide bid and initialization functions. This +function returns NULL on error or else a pointer to a +struct decompressor_t. This structure contains a +void * config slot that can be used for storing any +customization information.

+ +

Bid

+ +

The bid +function is invoked with a pointer and size of a block of +data. The decompressor can access its config data through +the decompressor element of the archive_read +object. The bid function is otherwise stateless. In +particular, it must not perform any I/O operations.

+ +

The value +returned by the bid function indicates its suitability for +handling this data stream. A bid of zero will ensure that +this decompressor is never invoked. Return zero if magic +number checks fail. Otherwise, your initial implementation +should return the number of bits actually checked. For +example, if you verify two full bytes and three bits of +another byte, bid 19. Note that the initial block may be +very short; be careful to only inspect the data you are +given. (The current decompressors require two bytes for +correct bidding.)

+ +

Initialize

+ +

The winning bidder will have +its init function called. This function should initialize +the remaining slots of the struct decompressor_t +object pointed to by the decompressor element of the +archive_read object. In particular, it should +allocate any working data it needs in the data slot +of that structure. The init function is called with the +block of data that was used for tasting. At this point, the +decompressor is responsible for all I/O requests to the +client callbacks. The decompressor is free to read more data +as and when necessary.

+ +

Satisfy I/O requests

+ +

The format handler will invoke +the read_ahead, consume, and skip +functions as needed.

+ +

Finish

+ +

The finish +method is called only once when the archive is closed. It +should release anything stored in the data and +config slots of the decompressor object. It +should not invoke the client close callback.

+ +

Format +Layer
+The read formats have a similar lifecycle to the +decompression handlers:

+ +

Registration

+ +

Allocate your private data and +initialize your pointers.

+ +

Bid

+ +

Formats bid by +invoking the read_ahead() decompression method but +not calling the consume() method. This allows each +bidder to look ahead in the input stream. Bidders should not +look further ahead than necessary, as long look aheads put +pressure on the decompression layer to buffer lots of data. +Most formats only require a few hundred bytes of look ahead; +look aheads of a few kilobytes are reasonable. (The ISO9660 +reader sometimes looks ahead by 48k, which should be +considered an upper limit.)

+ +

Read header

+ +

The header read is usually the +most complex part of any format. There are a few strategies +worth mentioning: For formats such as tar or cpio, reading +and parsing the header is straightforward since headers +alternate with data. For formats that store all header data +at the beginning of the file, the first header read request +may have to read all headers into memory and store that +data, sorted by the location of the file data. Subsequent +header read requests will skip forward to the beginning of +the file data and return the corresponding header.

+ +

Read Data

+ +

The read data interface +supports sparse files; this requires that each call return a +block of data specifying the file offset and size. This may +require you to carefully track the location so that you can +return accurate file offsets for each read. Remember that +the decompressor will return as much data as it has. +Generally, you will want to request one byte, examine the +return value to see how much data is available, and possibly +trim that to the amount you can use. You should invoke +consume for each block just before you return it.

+ +

Skip All Data

+ +

The skip data call should skip +over all file data and trailing padding. This is called +automatically by the API layer just before each header read. +It is also called in response to the client calling the +public data_skip() function.

+ +

Cleanup

+ +

On cleanup, the format should +release all of its allocated memory.

+ +

API Layer +
+XXX to do XXX

+ +

WRITE +ARCHITECTURE

+ +

The write API has a similar set +of four layers: an API layer, a format layer, a compression +layer, and an I/O layer. The registration here is much +simpler because only one format and one compression can be +registered at a time.

+ +

I/O Layer and +Client Callbacks
+XXX To be written XXX

+ +

Compression +Layer
+XXX To be written XXX

+ +

Format +Layer
+XXX To be written XXX

+ +

API Layer +
+XXX To be written XXX

+ +

WRITE_DISK +ARCHITECTURE

+ +

The write_disk API is intended +to look just like the write API to clients. Since it does +not handle multiple formats or compression, it is not +layered internally.

+ +

GENERAL +SERVICES

+ +

The archive_read, +archive_write, and archive_write_disk objects +all contain an initial archive object which provides +common support for a set of standard services. (Recall that +ANSI/ISO C90 guarantees that you can cast freely between a +pointer to a structure and a pointer to the first element of +that structure.) The archive object has a magic value +that indicates which API this object is associated with, +slots for storing error information, and function pointers +for virtualized API functions.

+ +

MISCELLANEOUS +NOTES

+ +

Connecting existing archiving +libraries into libarchive is generally quite difficult. In +particular, many existing libraries strongly assume that you +are reading from a file; they seek forwards and backwards as +necessary to locate various pieces of information. In +contrast, libarchive never seeks backwards in its input, +which sometimes requires very different approaches.

+ +

For example, +libarchive’s ISO9660 support operates very differently +from most ISO9660 readers. The libarchive support utilizes a +work-queue design that keeps a list of known entries sorted +by their location in the input. Whenever libarchive’s +ISO9660 implementation is asked for the next header, checks +this list to find the next item on the disk. Directories are +parsed when they are encountered and new items are added to +the list. This design relies heavily on the ISO9660 image +being optimized so that directories always occur earlier on +the disk than the files they describe.

+ +

Depending on the +specific format, such approaches may not be possible. The +ZIP format specification, for example, allows archivers to +store key information only at the end of the file. In +theory, it is possible to create ZIP archives that cannot be +read without seeking. Fortunately, such archives are very +rare, and libarchive can read most ZIP archives, though it +cannot always extract as much information as a dedicated ZIP +program.

+ +

SEE ALSO

+ +

archive(3), archive_entry(3), +archive_read(3), archive_write(3), archive_write_disk(3)

+ +

HISTORY

+ +

The libarchive library +first appeared in FreeBSD 5.3.

+ +

AUTHORS

+ +

The libarchive library +was written by Tim Kientzle +⟨kientzle@acm.org⟩.

+ +

BUGS

+ +

FreeBSD 8.0 April 16, +2007 FreeBSD 8.0

+
+ + diff --git a/libarchive/libarchive-2.8.0/doc/html/mtree.5.html b/libarchive/libarchive-2.8.0/doc/html/mtree.5.html new file mode 100644 index 0000000..674edef --- /dev/null +++ b/libarchive/libarchive-2.8.0/doc/html/mtree.5.html @@ -0,0 +1,339 @@ + + + + + + + + + + + + + +
+ + +

MTREE(5) FreeBSD File Formats Manual +MTREE(5)

+ +

NAME

+ +

mtree — format of +mtree dir hierarchy files

+ + +

DESCRIPTION

+ +

The mtree format is a +textual format that describes a collection of filesystem +objects. Such files are typically used to create or verify +directory hierarchies.

+ +

General +Format
+An mtree file consists of a series of lines, each +providing information about a single filesystem object. +Leading whitespace is always ignored.

+ +

When encoding +file or pathnames, any backslash character or character +outside of the 95 printable ASCII characters must be encoded +as a a backslash followed by three octal digits. When +reading mtree files, any appearance of a backslash followed +by three octal digits should be converted into the +corresponding character.

+ +

Each line is +interpreted independently as one of the following types:

+ +

Signature

+ +

The first line +of any mtree file must begin with +‘‘#mtree’’. If a file contains any +full path entries, the first line should begin with +‘‘#mtree v2.0’’, otherwise, the +first line should begin with ‘‘#mtree +v1.0’’.

+ +

Blank

+ +

Blank lines are +ignored.

+ +

Comment

+ +

Lines beginning +with # are ignored.

+ +

Special

+ +

Lines beginning +with / are special commands that influence the +interpretation of later lines.

+ +

Relative

+ +

If the first +whitespace-delimited word has no / characters, it is +the name of a file in the current directory. Any relative +entry that describes a directory changes the current +directory.

+ +

dot-dot

+ +

As a special +case, a relative entry with the filename .. changes +the current directory to the parent directory. Options on +dot-dot entries are always ignored.

+ +

Full

+ +

If the first +whitespace-delimited word has a / character after the +first character, it is the pathname of a file relative to +the starting directory. There can be multiple full entries +describing the same file.

+ +

Some tools that +process mtree files may require that multiple lines +describing the same file occur consecutively. It is not +permitted for the same file to be mentioned using both a +relative and a full file specification.

+ +

Special +commands
+Two special commands are currently defined:

+ +

/set

+ +

This command +defines default values for one or more keywords. It is +followed on the same line by one or more +whitespace-separated keyword definitions. These definitions +apply to all following files that do not specify a value for +that keyword.

+ +

/unset

+ +

This command +removes any default value set by a previous /set +command. It is followed on the same line by one or more +keywords separated by whitespace.

+ +

Keywords +
+After the filename, a full or relative entry consists of +zero or more whitespace-separated keyword definitions. Each +such definition consists of a key from the following list +immediately followed by an ’=’ sign and a value. +Software programs reading mtree files should warn about +unrecognized keywords.

+ +

Currently +supported keywords are as follows:

+ +

cksum

+ +

The checksum of +the file using the default algorithm specified by the +cksum(1) utility.

+ + +

contents

+ +

The full +pathname of a file that holds the contents of this file.

+ +

flags

+ +

The file flags +as a symbolic name. See chflags(1) for information on these +names. If no flags are to be set the string +‘‘none’’ may be used to override the +current default.

+ +

gid

+ +

The file group +as a numeric value.

+ +

gname

+ +

The file group +as a symbolic name.

+ +

ignore

+ +

Ignore any file +hierarchy below this file.

+ +

link

+ +

The target of +the symbolic link when type=link.

+ +

md5

+ +

The MD5 message +digest of the file.

+ + +

md5digest

+ +

A synonym for +md5.

+ +

mode

+ +

The current +file’s permissions as a numeric (octal) or symbolic +value.

+ +

nlink

+ +

The number of +hard links the file is expected to have.

+ + +

nochange

+ +

Make sure this +file or directory exists but otherwise ignore all +attributes.

+ + +

ripemd160digest

+ +

The RIPEMD160 message digest of +the file.

+ +

rmd160

+ +

A synonym for +ripemd160digest.

+ + +

rmd160digest

+ +

A synonym for +ripemd160digest.

+ +

sha1

+ +

The FIPS 160-1 +(‘‘SHA-1’’) message digest of the +file.

+ + +

sha1digest

+ +

A synonym for +sha1.

+ +

sha256

+ +

The FIPS 180-2 +(‘‘SHA-256’’) message digest of the +file.

+ + +

sha256digest

+ +

A synonym for +sha256.

+ +

size

+ +

The size, in +bytes, of the file.

+ +

time

+ +

The last +modification time of the file.

+ +

type

+ +

The type of the +file; may be set to any one of the following:

+ +

block

+ +

block special +device

+ +

char

+ +

character +special device

+ +

dir

+ +

directory

+ +

fifo

+ +

fifo

+ +

file

+ +

regular +file

+ +

link

+ +

symbolic +link

+ +

socket

+ +

socket

+ +

uid

+ +

The file owner +as a numeric value.

+ +

uname

+ +

The file owner +as a symbolic name.

+ +

SEE ALSO

+ +

cksum(1), find(1), mtree(8)

+ +

BUGS

+ +

The FreeBSD implementation of +mtree does not currently support the mtree 2.0 +format. The requirement for a +‘‘#mtree’’ signature line is new and +not yet widely implemented.

+ +

HISTORY

+ +

The mtree utility +appeared in 4.3BSD−Reno. The MD5 digest capability was +added in FreeBSD 2.1, in response to the widespread use +of programs which can spoof cksum(1). The SHA-1 and +RIPEMD160 digests were added in FreeBSD 4.0, as new +attacks have demonstrated weaknesses in MD5. The SHA-256 +digest was added in FreeBSD 6.0. Support for file flags +was added in FreeBSD 4.0, and mostly comes from NetBSD. +The ‘‘full’’ entry format was added +by NetBSD.

+ + +

FreeBSD 8.0 +August 20, 2007 FreeBSD 8.0

+
+ + diff --git a/libarchive/libarchive-2.8.0/doc/html/tar.5.html b/libarchive/libarchive-2.8.0/doc/html/tar.5.html new file mode 100644 index 0000000..1d87324 --- /dev/null +++ b/libarchive/libarchive-2.8.0/doc/html/tar.5.html @@ -0,0 +1,1400 @@ + + + + + + + + + + + + + +
+ + +

tar(5) FreeBSD File Formats Manual +tar(5)

+ +

NAME

+ +

tar — format of +tape archive files

+ + +

DESCRIPTION

+ +

The tar archive format +collects any number of files, directories, and other file +system objects (symbolic links, device nodes, etc.) into a +single stream of bytes. The format was originally designed +to be used with tape drives that operate with fixed-size +blocks, but is widely used as a general packaging +mechanism.

+ +

General +Format
+A tar archive consists of a series of 512-byte +records. Each file system object requires a header record +which stores basic metadata (pathname, owner, permissions, +etc.) and zero or more records containing any file data. The +end of the archive is indicated by two records consisting +entirely of zero bytes.

+ +

For +compatibility with tape drives that use fixed block sizes, +programs that read or write tar files always read or write a +fixed number of records with each I/O operation. These +‘‘blocks’’ are always a multiple of +the record size. The maximum block size supported by early +implementations was 10240 bytes or 20 records. This is still +the default for most implementations although block sizes of +1MiB (2048 records) or larger are commonly used with modern +high-speed tape drives. (Note: the terms +‘‘block’’ and +‘‘record’’ here are not entirely +standard; this document follows the convention established +by John Gilmore in documenting pdtar.)

+ +

Old-Style +Archive Format
+The original tar archive format has been extended many times +to include additional information that various implementors +found necessary. This section describes the variant +implemented by the tar command included in Version 7 +AT&T UNIX, which seems to be the earliest widely-used +version of the tar program.

+ +

The header +record for an old-style tar archive consists of the +following:

+ +

struct +header_old_tar {

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +

char name[100];

 +
+ + +

char mode[8];

 +
+ + +

char uid[8];

 +
+ + +

char gid[8];

 +
+ + +

char size[12];

 +
+ + +

char mtime[12];

 +
+ + +

char checksum[8];

 +
+ + +

char linkflag[1];

 +
+ + +

char linkname[100];

 +
+ + +

char pad[255];

 +
+ +

};

+ +

All unused bytes in the header +record are filled with nulls.

+ +

name

+ +

Pathname, +stored as a null-terminated string. Early tar +implementations only stored regular files (including +hardlinks to those files). One common early convention used +a trailing "/" character to indicate a directory +name, allowing directory permissions and owner information +to be archived and restored.

+ +

mode

+ +

File mode, +stored as an octal number in ASCII.

+ +

uid, +gid

+ +

User id and group id of owner, +as octal numbers in ASCII.

+ +

size

+ +

Size of file, +as octal number in ASCII. For regular files only, this +indicates the amount of data that follows the header. In +particular, this field was ignored by early tar +implementations when extracting hardlinks. Modern writers +should always store a zero length for hardlink entries.

+ +

mtime

+ +

Modification +time of file, as an octal number in ASCII. This indicates +the number of seconds since the start of the epoch, 00:00:00 +UTC January 1, 1970. Note that negative values should be +avoided here, as they are handled inconsistently.

+ + +

checksum

+ +

Header checksum, stored as an +octal number in ASCII. To compute the checksum, set the +checksum field to all spaces, then sum all bytes in the +header using unsigned arithmetic. This field should be +stored as six octal digits followed by a null and a space +character. Note that many early implementations of tar used +signed arithmetic for the checksum field, which can cause +interoperability problems when transferring archives between +systems. Modern robust readers compute the checksum both +ways and accept the header if either computation +matches.

+ +

linkflag, +linkname

+ +

In order to preserve hardlinks +and conserve tape, a file with multiple links is only +written to the archive the first time it is encountered. The +next time it is encountered, the linkflag is set to +an ASCII ‘1’ and the linkname field holds +the first name under which this file appears. (Note that +regular files have a null value in the linkflag +field.)

+ +

Early tar +implementations varied in how they terminated these fields. +The tar command in Version 7 AT&T UNIX used the +following conventions (this is also documented in early BSD +manpages): the pathname must be null-terminated; the mode, +uid, and gid fields must end in a space and a null byte; the +size and mtime fields must end in a space; the checksum is +terminated by a null and a space. Early implementations +filled the numeric fields with leading spaces. This seems to +have been common practice until the IEEE Std 1003.1-1988 +(‘‘POSIX.1’’) standard was released. +For best portability, modern implementations should fill the +numeric fields with leading zeros.

+ +

Pre-POSIX +Archives
+An early draft of IEEE Std 1003.1-1988 +(‘‘POSIX.1’’) served as the basis +for John Gilmore’s pdtar program and many +system implementations from the late 1980s and early 1990s. +These archives generally follow the POSIX ustar format +described below with the following variations:

+ +

•

+ +

The magic value is +‘‘ustar ’’ (note the following +space). The version field contains a space character +followed by a null.

+ +

•

+ +

The numeric fields are +generally filled with leading spaces (not leading zeros as +recommended in the final standard).

+ +

•

+ +

The prefix field is often not +used, limiting pathnames to the 100 characters of old-style +archives.

+ +

POSIX ustar +Archives
+IEEE Std 1003.1-1988 (‘‘POSIX.1’’) +defined a standard tar file format to be read and written by +compliant implementations of tar(1). This format is often +called the ‘‘ustar’’ format, after +the magic value used in the header. (The name is an acronym +for ‘‘Unix Standard TAR’’.) It +extends the historic format with new fields:

+ +

struct +header_posix_ustar {

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +

char name[100];

 +
+ + +

char mode[8];

 +
+ + +

char uid[8];

 +
+ + +

char gid[8];

 +
+ + +

char size[12];

 +
+ + +

char mtime[12];

 +
+ + +

char checksum[8];

 +
+ + +

char typeflag[1];

 +
+ + +

char linkname[100];

 +
+ + +

char magic[6];

 +
+ + +

char version[2];

 +
+ + +

char uname[32];

 +
+ + +

char gname[32];

 +
+ + +

char devmajor[8];

 +
+ + +

char devminor[8];

 +
+ + +

char prefix[155];

 +
+ + +

char pad[12];

 +
+ +

};

+ + +

typeflag

+ +

Type of entry. POSIX extended +the earlier linkflag field with several new type +values:

+ +

‘‘0’’

+ +

Regular file. +NUL should be treated as a synonym, for compatibility +purposes.

+ +

‘‘1’’

+ +

Hard link.

+ +

‘‘2’’

+ +

Symbolic +link.

+ +

‘‘3’’

+ +

Character +device node.

+ +

‘‘4’’

+ +

Block device +node.

+ +

‘‘5’’

+ +

Directory.

+ +

‘‘6’’

+ +

FIFO node.

+ +

‘‘7’’

+ +

Reserved.

+ +

Other

+ +

A +POSIX-compliant implementation must treat any unrecognized +typeflag value as a regular file. In particular, writers +should ensure that all entries have a valid filename so that +they can be restored by readers that do not support the +corresponding extension. Uppercase letters "A" +through "Z" are reserved for custom extensions. +Note that sockets and whiteout entries are not +archivable.

+ +

It is worth noting that the +size field, in particular, has different meanings +depending on the type. For regular files, of course, it +indicates the amount of data following the header. For +directories, it may be used to indicate the total size of +all files in the directory, for use by operating systems +that pre-allocate directory space. For all other types, it +should be set to zero by writers and ignored by readers.

+ +

magic

+ +

Contains the +magic value ‘‘ustar’’ followed by a +NUL byte to indicate that this is a POSIX standard archive. +Full compliance requires the uname and gname fields be +properly set.

+ +

version

+ +

Version. This should be +‘‘00’’ (two copies of the ASCII +digit zero) for POSIX standard archives.

+ +

uname, +gname

+ +

User and group names, as +null-terminated ASCII strings. These should be used in +preference to the uid/gid values when they are set and the +corresponding names exist on the system.

+ +

devmajor, +devminor

+ +

Major and minor numbers for +character device or block device entry.

+ +

name, +prefix

+ +

If the pathname is too long to +fit in the 100 bytes provided by the standard format, it can +be split at any / character with the first portion +going into the prefix field. If the prefix field is not +empty, the reader will prepend the prefix value and a +/ character to the regular name field to obtain the +full pathname. The standard does not require a trailing +/ character on directory names, though most +implementations still include this for compatibility +reasons.

+ +

Note that all +unused bytes must be set to NUL.

+ +

Field +termination is specified slightly differently by POSIX than +by previous implementations. The magic, uname, +and gname fields must have a trailing NUL. The +pathname, linkname, and prefix fields +must have a trailing NUL unless they fill the entire field. +(In particular, it is possible to store a 256-character +pathname if it happens to have a / as the 156th +character.) POSIX requires numeric fields to be zero-padded +in the front, and requires them to be terminated with either +space or NUL characters.

+ +

Currently, most +tar implementations comply with the ustar format, +occasionally extending it by adding new fields to the blank +area at the end of the header record.

+ +

Pax +Interchange Format
+There are many attributes that cannot be portably stored in +a POSIX ustar archive. IEEE Std 1003.1-2001 +(‘‘POSIX.1’’) defined a +‘‘pax interchange format’’ that uses +two new types of entries to hold text-formatted metadata +that applies to following entries. Note that a pax +interchange format archive is a ustar archive in every +respect. The new data is stored in ustar-compatible archive +entries that use the ‘‘x’’ or +‘‘g’’ typeflag. In particular, older +implementations that do not fully support these extensions +will extract the metadata into regular files, where the +metadata can be examined as necessary.

+ +

An entry in a +pax interchange format archive consists of one or two +standard ustar entries, each with its own header and data. +The first optional entry stores the extended attributes for +the following entry. This optional first entry has an +"x" typeflag and a size field that indicates the +total size of the extended attributes. The extended +attributes themselves are stored as a series of text-format +lines encoded in the portable UTF-8 encoding. Each line +consists of a decimal number, a space, a key string, an +equals sign, a value string, and a new line. The decimal +number indicates the length of the entire line, including +the initial length field and the trailing newline. An +example of such a field is:

+ +

25 ctime=1084839148.1212\n

+ +

Keys in all lowercase are +standard keys. Vendors can add their own keys by prefixing +them with an all uppercase vendor name and a period. Note +that, unlike the historic header, numeric values are stored +using decimal, not octal. A description of some common keys +follows:

+ +

atime, +ctime, mtime

+ +

File access, inode change, and +modification times. These fields can be negative or include +a decimal point and a fractional value.

+ +

uname, +uid, gname, gid

+ +

User name, group name, and +numeric UID and GID values. The user name and group name +stored here are encoded in UTF8 and can thus include +non-ASCII characters. The UID and GID fields can be of +arbitrary length.

+ + +

linkpath

+ +

The full path of the linked-to +file. Note that this is encoded in UTF8 and can thus include +non-ASCII characters.

+ +

path

+ +

The full +pathname of the entry. Note that this is encoded in UTF8 and +can thus include non-ASCII characters.

+ +

realtime.*, +security.*

+ +

These keys are reserved and may +be used for future standardization.

+ +

size

+ +

The size of the +file. Note that there is no length limit on this field, +allowing conforming archives to store files much larger than +the historic 8GB limit.

+ + +

SCHILY.*

+ +

Vendor-specific attributes used +by Joerg Schilling’s star implementation.

+ + +

SCHILY.acl.access, +SCHILY.acl.default

+ +

Stores the access and default +ACLs as textual strings in a format that is an extension of +the format specified by POSIX.1e draft 17. In particular, +each user or group access specification can include a fourth +colon-separated field with the numeric UID or GID. This +allows ACLs to be restored on systems that may not have +complete user or group information available (such as when +NIS/YP or LDAP services are temporarily unavailable).

+ + +

SCHILY.devminor, +SCHILY.devmajor

+ +

The full minor and major +numbers for device nodes.

+ + +

SCHILY.fflags

+ +

The file flags.

+ + +

SCHILY.realsize

+ +

The full size of the file on +disk. XXX explain? XXX

+ +

SCHILY.dev, +SCHILY.ino, SCHILY.nlinks

+ +

The device number, inode +number, and link count for the entry. In particular, note +that a pax interchange format archive using Joerg +Schilling’s SCHILY.* extensions can store all +of the data from struct stat.

+ + +

LIBARCHIVE.xattr.namespace.key

+ +

Libarchive stores +POSIX.1e-style extended attributes using keys of this form. +The key value is URL-encoded: All non-ASCII +characters and the two special characters +‘‘=’’ and +‘‘%’’ are encoded as +‘‘%’’ followed by two uppercase +hexadecimal digits. The value of this key is the extended +attribute value encoded in base 64. XXX Detail the base-64 +format here XXX

+ + +

VENDOR.*

+ +

XXX document other +vendor-specific extensions XXX

+ +

Any values +stored in an extended attribute override the corresponding +values in the regular tar header. Note that compliant +readers should ignore the regular fields when they are +overridden. This is important, as existing archivers are +known to store non-compliant values in the standard header +fields in this situation. There are no limits on length for +any of these fields. In particular, numeric fields can be +arbitrarily large. All text fields are encoded in UTF8. +Compliant writers should store only portable 7-bit ASCII +characters in the standard ustar header and use extended +attributes whenever a text value contains non-ASCII +characters.

+ +

In addition to +the x entry described above, the pax interchange +format also supports a g entry. The g entry is +identical in format, but specifies attributes that serve as +defaults for all subsequent archive entries. The g +entry is not widely used.

+ +

Besides the new +x and g entries, the pax interchange format +has a few other minor variations from the earlier ustar +format. The most troubling one is that hardlinks are +permitted to have data following them. This allows readers +to restore any hardlink to a file without having to rewind +the archive to find an earlier entry. However, it creates +complications for robust readers, as it is no longer clear +whether or not they should ignore the size field for +hardlink entries.

+ +

GNU Tar +Archives
+The GNU tar program started with a pre-POSIX format similar +to that described earlier and has extended it using several +different mechanisms: It added new fields to the empty space +in the header (some of which was later used by POSIX for +conflicting purposes); it allowed the header to be continued +over multiple records; and it defined new entries that +modify following entries (similar in principle to the +x entry described above, but each GNU special entry +is single-purpose, unlike the general-purpose x +entry). As a result, GNU tar archives are not POSIX +compatible, although more lenient POSIX-compliant readers +can successfully extract most GNU tar archives.

+ +

struct +header_gnu_tar {

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +

char name[100];

 +
+ + +

char mode[8];

 +
+ + +

char uid[8];

 +
+ + +

char gid[8];

 +
+ + +

char size[12];

 +
+ + +

char mtime[12];

 +
+ + +

char checksum[8];

 +
+ + +

char typeflag[1];

 +
+ + +

char linkname[100];

 +
+ + +

char magic[6];

 +
+ + +

char version[2];

 +
+ + +

char uname[32];

 +
+ + +

char gname[32];

 +
+ + +

char devmajor[8];

 +
+ + +

char devminor[8];

 +
+ + +

char atime[12];

 +
+ + +

char ctime[12];

 +
+ + +

char offset[12];

 +
+ + +

char longnames[4];

 +
+ + +

char unused[1];

 +
+ + +

struct {

 +
+ + + +

char offset[12];

 +
+ + + +

char numbytes[12];

 +
+ + +

} sparse[4];

 +
+ + +

char isextended[1];

 +
+ + +

char realsize[12];

 +
+ + +

char pad[17];

 +
+ +

};

+ + +

typeflag

+ +

GNU tar uses the following +special entry types, in addition to those defined by +POSIX:

+ +

7

+ +

GNU tar treats +type "7" records identically to type "0" +records, except on one obscure RTOS where they are used to +indicate the pre-allocation of a contiguous file on +disk.

+ +

D

+ +

This indicates +a directory entry. Unlike the POSIX-standard "5" +typeflag, the header is followed by data records listing the +names of files in this directory. Each name is preceded by +an ASCII "Y" if the file is stored in this archive +or "N" if the file is not stored in this archive. +Each name is terminated with a null, and an extra null marks +the end of the name list. The purpose of this entry is to +support incremental backups; a program restoring from such +an archive may wish to delete files on disk that did not +exist in the directory when the archive was made.

+ +

Note that the +"D" typeflag specifically violates POSIX, which +requires that unrecognized typeflags be restored as normal +files. In this case, restoring the "D" entry as a +file could interfere with subsequent creation of the +like-named directory.

+ +

K

+ +

The data for +this entry is a long linkname for the following regular +entry.

+ +

L

+ +

The data for +this entry is a long pathname for the following regular +entry.

+ +

M

+ +

This is a +continuation of the last file on the previous volume. GNU +multi-volume archives guarantee that each volume begins with +a valid entry header. To ensure this, a file may be split, +with part stored at the end of one volume, and part stored +at the beginning of the next volume. The "M" +typeflag indicates that this entry continues an existing +file. Such entries can only occur as the first or second +entry in an archive (the latter only if the first entry is a +volume label). The size field specifies the size of +this entry. The offset field at bytes 369-380 +specifies the offset where this file fragment begins. The +realsize field specifies the total size of the file +(which must equal size plus offset). When +extracting, GNU tar checks that the header file name is the +one it is expecting, that the header offset is in the +correct sequence, and that the sum of offset and size is +equal to realsize.

+ +

N

+ +

Type +"N" records are no longer generated by GNU tar. +They contained a list of files to be renamed or symlinked +after extraction; this was originally used to support long +names. The contents of this record are a text description of +the operations to be done, in the form ‘‘Rename +%s to %s\n’’ or ‘‘Symlink %s to +%s\n’’; in either case, both filenames are +escaped using K&R C syntax. Due to security concerns, +"N" records are now generally ignored when reading +archives.

+ +

S

+ +

This is a +‘‘sparse’’ regular file. Sparse +files are stored as a series of fragments. The header +contains a list of fragment offset/length pairs. If more +than four such entries are required, the header is extended +as necessary with ‘‘extra’’ header +extensions (an older format that is no longer used), or +‘‘sparse’’ extensions.

+ +

V

+ +

The name +field should be interpreted as a tape/volume header name. +This entry should generally be ignored on extraction.

+ +

magic

+ +

The magic field +holds the five characters ‘‘ustar’’ +followed by a space. Note that POSIX ustar archives have a +trailing null.

+ +

version

+ +

The version field holds a space +character followed by a null. Note that POSIX ustar archives +use two copies of the ASCII digit +‘‘0’’.

+ +

atime, +ctime

+ +

The time the file was last +accessed and the time of last change of file information, +stored in octal as with mtime.

+ + +

longnames

+ +

This field is apparently no +longer used.

+ +

Sparse offset / +numbytes

+ +

Each such structure specifies a +single fragment of a sparse file. The two fields store +values as octal numbers. The fragments are each padded to a +multiple of 512 bytes in the archive. On extraction, the +list of fragments is collected from the header (including +any extension headers), and the data is then read and +written to the file at appropriate offsets.

+ + +

isextended

+ +

If this is set to non-zero, the +header will be followed by additional ‘‘sparse +header’’ records. Each such record contains +information about as many as 21 additional sparse blocks as +shown here:

+ +

struct +gnu_sparse_header {

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +

struct {

 +
+ + + +

char offset[12];

 +
+ + + +

char numbytes[12];

 +
+ + +

} sparse[21];

 +
+ + +

char isextended[1];

 +
+ + +

char padding[7];

 +
+ +

};

+ + +

realsize

+ +

A binary representation of the +file’s complete size, with a much larger range than +the POSIX file size. In particular, with M type +files, the current entry is only a portion of the file. In +that case, the POSIX size field will indicate the size of +this entry; the realsize field will indicate the +total size of the file.

+ +

GNU tar pax +archives
+GNU tar 1.14 (XXX check this XXX) and later will write pax +interchange format archives when you specify the +−-posix flag. This format uses 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’’.

+ + +

GNU.sparse.numblocks, +GNU.sparse.offset, GNU.sparse.numbytes, +GNU.sparse.size

+ +

The +‘‘0.0’’ format used an initial +GNU.sparse.numblocks attribute to indicate the number +of blocks in the file, a pair of GNU.sparse.offset +and GNU.sparse.numbytes to indicate the offset and +size of each block, and a single GNU.sparse.size to +indicate the full size of the file. This is not the same as +the size in the tar header because the latter value does not +include the size of any holes. This format required that the +order of attributes be preserved and relied on readers +accepting multiple appearances of the same attribute names, +which is not officially permitted by the standards.

+ + +

GNU.sparse.map

+ +

The +‘‘0.1’’ format used a single +attribute that stored a comma-separated list of decimal +numbers. Each pair of numbers 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.

+ + +

GNU.sparse.major, +GNU.sparse.minor, GNU.sparse.name, +GNU.sparse.realsize

+ +

The +‘‘1.0’’ format stores the sparse +block map in one or more 512-byte blocks prepended to the +file data in the entry body. The pax attributes indicate the +existence of this map (via the GNU.sparse.major and +GNU.sparse.minor fields) and the full size of the +file. The GNU.sparse.name holds the true name of the +file. To avoid confusion, the name stored in the regular tar +header is a modified name so that extraction errors will be +apparent to users.

+ +

Solaris +Tar
+XXX More Details Needed XXX

+ +

Solaris tar +(beginning with SunOS XXX 5.7 ?? XXX) supports an +‘‘extended’’ format that is +fundamentally similar to pax interchange format, with the +following differences:

+ +

•

+ +

Extended attributes are stored +in an entry whose type is X, not x, as used by +pax interchange format. The detailed format of this entry +appears to be the same as detailed above for the x +entry.

+ +

•

+ +

An additional A entry is +used to store an ACL for the following regular entry. The +body of this entry contains a seven-digit octal number +followed by a zero byte, followed by the textual ACL +description. The octal value is the number of ACL entries +plus a constant that indicates the ACL type: 01000000 for +POSIX.1e ACLs and 03000000 for NFSv4 ACLs.

+ +

AIX Tar +
+XXX More details needed XXX

+ +

Mac OS X +Tar
+The tar distributed with Apple’s Mac OS X stores most +regular files as two separate entries in the tar archive. +The two entries have the same name except that the first one +has ‘‘._’’ added to the beginning of +the name. This first entry stores the ‘‘resource +fork’’ with additional attributes for the file. +The Mac OS X CopyFile() API is used to separate a +file on disk into separate resource and data streams and to +reassemble those separate streams when the file is restored +to disk.

+ +

Other +Extensions
+One obvious extension to increase the size of files is to +eliminate the terminating characters from the various +numeric fields. For example, the standard only allows the +size field to contain 11 octal digits, reserving the twelfth +byte for a trailing NUL character. Allowing 12 octal digits +allows file sizes up to 64 GB.

+ +

Another +extension, utilized by GNU tar, star, and other newer +tar implementations, permits binary numbers in the +standard numeric fields. This is flagged by setting the high +bit of the first byte. This permits 95-bit values for the +length and time fields and 63-bit values for the uid, gid, +and device numbers. GNU tar supports this extension for the +length, mtime, ctime, and atime fields. Joerg +Schilling’s star program supports this extension for +all numeric fields. Note that this extension is largely +obsoleted by the extended attribute record provided by the +pax interchange format.

+ +

Another early +GNU extension allowed base-64 values rather than octal. This +extension was short-lived and is no longer supported by any +implementation.

+ +

SEE ALSO

+ +

ar(1), pax(1), tar(1)

+ + +

STANDARDS

+ +

The tar utility is no +longer a part of POSIX or the Single Unix Standard. It last +appeared in Version 2 of the Single UNIX Specification +(‘‘SUSv2’’). It has been supplanted +in subsequent standards by pax(1). The ustar format is +currently part of the specification for the pax(1) utility. +The pax interchange file format is new with IEEE Std +1003.1-2001 (‘‘POSIX.1’’).

+ +

HISTORY

+ +

A tar command appeared in +Seventh Edition Unix, which was released in January, 1979. +It replaced the tp program from Fourth Edition Unix +which in turn replaced the tap program from First +Edition Unix. John Gilmore’s pdtar +public-domain implementation (circa 1987) was highly +influential and formed the basis of GNU tar (circa +1988). Joerg Shilling’s star archiver is +another open-source (GPL) archiver (originally developed +circa 1985) which features complete support for pax +interchange format.

+ +

This +documentation was written as part of the libarchive +and bsdtar project by Tim Kientzle +⟨kientzle@FreeBSD.org⟩.

+ + +

FreeBSD 8.0 +December 27, 2009 FreeBSD 8.0

+
+ + -- cgit v1.2.3