diff options
Diffstat (limited to 'libarchive/libarchive-2.7.1/doc/text')
15 files changed, 0 insertions, 4205 deletions
diff --git a/libarchive/libarchive-2.7.1/doc/text/Makefile b/libarchive/libarchive-2.7.1/doc/text/Makefile deleted file mode 100644 index 2671acd..0000000 --- a/libarchive/libarchive-2.7.1/doc/text/Makefile +++ /dev/null @@ -1,46 +0,0 @@ - -default: all - - -archive_entry.3.txt: ../../libarchive/archive_entry.3 - nroff -mdoc ../../libarchive/archive_entry.3 | col -b > archive_entry.3.txt - -archive_read.3.txt: ../../libarchive/archive_read.3 - nroff -mdoc ../../libarchive/archive_read.3 | col -b > archive_read.3.txt - -archive_read_disk.3.txt: ../../libarchive/archive_read_disk.3 - nroff -mdoc ../../libarchive/archive_read_disk.3 | col -b > archive_read_disk.3.txt - -archive_util.3.txt: ../../libarchive/archive_util.3 - nroff -mdoc ../../libarchive/archive_util.3 | col -b > archive_util.3.txt - -archive_write.3.txt: ../../libarchive/archive_write.3 - nroff -mdoc ../../libarchive/archive_write.3 | col -b > archive_write.3.txt - -archive_write_disk.3.txt: ../../libarchive/archive_write_disk.3 - nroff -mdoc ../../libarchive/archive_write_disk.3 | col -b > archive_write_disk.3.txt - -cpio.5.txt: ../../libarchive/cpio.5 - nroff -mdoc ../../libarchive/cpio.5 | col -b > cpio.5.txt - -libarchive-formats.5.txt: ../../libarchive/libarchive-formats.5 - nroff -mdoc ../../libarchive/libarchive-formats.5 | col -b > libarchive-formats.5.txt - -libarchive.3.txt: ../../libarchive/libarchive.3 - nroff -mdoc ../../libarchive/libarchive.3 | col -b > libarchive.3.txt - -libarchive_internals.3.txt: ../../libarchive/libarchive_internals.3 - nroff -mdoc ../../libarchive/libarchive_internals.3 | col -b > libarchive_internals.3.txt - -mtree.5.txt: ../../libarchive/mtree.5 - nroff -mdoc ../../libarchive/mtree.5 | col -b > mtree.5.txt - -tar.5.txt: ../../libarchive/tar.5 - nroff -mdoc ../../libarchive/tar.5 | col -b > tar.5.txt - -bsdtar.1.txt: ../../tar/bsdtar.1 - nroff -mdoc ../../tar/bsdtar.1 | col -b > bsdtar.1.txt - -bsdcpio.1.txt: ../../cpio/bsdcpio.1 - nroff -mdoc ../../cpio/bsdcpio.1 | col -b > bsdcpio.1.txt -all: archive_entry.3.txt archive_read.3.txt archive_read_disk.3.txt archive_util.3.txt archive_write.3.txt archive_write_disk.3.txt cpio.5.txt libarchive-formats.5.txt libarchive.3.txt libarchive_internals.3.txt mtree.5.txt tar.5.txt bsdtar.1.txt bsdcpio.1.txt diff --git a/libarchive/libarchive-2.7.1/doc/text/archive_entry.3.txt b/libarchive/libarchive-2.7.1/doc/text/archive_entry.3.txt deleted file mode 100644 index a2e5f3c..0000000 --- a/libarchive/libarchive-2.7.1/doc/text/archive_entry.3.txt +++ /dev/null @@ -1,361 +0,0 @@ -archive_entry(3) FreeBSD Library Functions Manual archive_entry(3) - -NAME - archive_entry_acl_add_entry, archive_entry_acl_add_entry_w, - archive_entry_acl_clear, archive_entry_acl_count, archive_entry_acl_next, - archive_entry_acl_next_w, archive_entry_acl_reset, - archive_entry_acl_text_w, archive_entry_atime, archive_entry_atime_nsec, - archive_entry_clear, archive_entry_clone, archive_entry_copy_fflags_text, - archive_entry_copy_fflags_text_w, archive_entry_copy_gname, - archive_entry_copy_gname_w, archive_entry_copy_hardlink, - archive_entry_copy_hardlink_w, archive_entry_copy_link, - archive_entry_copy_link_w, archive_entry_copy_pathname_w, - archive_entry_copy_sourcepath, archive_entry_copy_stat, - archive_entry_copy_symlink, archive_entry_copy_symlink_w, - archive_entry_copy_uname, archive_entry_copy_uname_w, archive_entry_dev, - archive_entry_devmajor, archive_entry_devminor, archive_entry_filetype, - archive_entry_fflags, archive_entry_fflags_text, archive_entry_free, - archive_entry_gid, archive_entry_gname, archive_entry_hardlink, - archive_entry_ino, archive_entry_mode, archive_entry_mtime, - archive_entry_mtime_nsec, archive_entry_nlink, archive_entry_new, - archive_entry_pathname, archive_entry_pathname_w, archive_entry_rdev, - archive_entry_rdevmajor, archive_entry_rdevminor, - archive_entry_set_atime, archive_entry_set_ctime, archive_entry_set_dev, - archive_entry_set_devmajor, archive_entry_set_devminor, - archive_entry_set_filetype, archive_entry_set_fflags, - archive_entry_set_gid, archive_entry_set_gname, - archive_entry_set_hardlink, archive_entry_set_link, - archive_entry_set_mode, archive_entry_set_mtime, - archive_entry_set_pathname, archive_entry_set_rdevmajor, - archive_entry_set_rdevminor, archive_entry_set_size, - archive_entry_set_symlink, archive_entry_set_uid, - archive_entry_set_uname, archive_entry_size, archive_entry_sourcepath, - archive_entry_stat, archive_entry_symlink, archive_entry_uid, - archive_entry_uname -- functions for manipulating archive entry descrip- - tions - -SYNOPSIS - #include <archive_entry.h> - - void - archive_entry_acl_add_entry(struct archive_entry *, int type, - int permset, int tag, int qual, const char *name); - - void - archive_entry_acl_add_entry_w(struct archive_entry *, int type, - int permset, int tag, int qual, const wchar_t *name); - - void - archive_entry_acl_clear(struct archive_entry *); - - int - archive_entry_acl_count(struct archive_entry *, int type); - - int - archive_entry_acl_next(struct archive_entry *, int want_type, int *type, - int *permset, int *tag, int *qual, const char **name); - - int - archive_entry_acl_next_w(struct archive_entry *, int want_type, - int *type, int *permset, int *tag, int *qual, const wchar_t **name); - - int - archive_entry_acl_reset(struct archive_entry *, int want_type); - - const wchar_t * - archive_entry_acl_text_w(struct archive_entry *, int flags); - - time_t - archive_entry_atime(struct archive_entry *); - - long - archive_entry_atime_nsec(struct archive_entry *); - - struct archive_entry * - archive_entry_clear(struct archive_entry *); - - struct archive_entry * - archive_entry_clone(struct archive_entry *); - - const char * * - archive_entry_copy_fflags_text_w(struct archive_entry *, const char *); - - const wchar_t * - archive_entry_copy_fflags_text_w(struct archive_entry *, - const wchar_t *); - - void - archive_entry_copy_gname(struct archive_entry *, const char *); - - void - archive_entry_copy_gname_w(struct archive_entry *, const wchar_t *); - - void - archive_entry_copy_hardlink(struct archive_entry *, const char *); - - void - archive_entry_copy_hardlink_w(struct archive_entry *, const wchar_t *); - - void - archive_entry_copy_sourcepath(struct archive_entry *, const char *); - - void - archive_entry_copy_pathname_w(struct archive_entry *, const wchar_t *); - - void - archive_entry_copy_stat(struct archive_entry *, const struct stat *); - - void - archive_entry_copy_symlink(struct archive_entry *, const char *); - - void - archive_entry_copy_symlink_w(struct archive_entry *, const wchar_t *); - - void - archive_entry_copy_uname(struct archive_entry *, const char *); - - void - archive_entry_copy_uname_w(struct archive_entry *, const wchar_t *); - - dev_t - archive_entry_dev(struct archive_entry *); - - dev_t - archive_entry_devmajor(struct archive_entry *); - - dev_t - archive_entry_devminor(struct archive_entry *); - - mode_t - archive_entry_filetype(struct archive_entry *); - - void - archive_entry_fflags(struct archive_entry *, unsigned long *set, - unsigned long *clear); - - const char * - archive_entry_fflags_text(struct archive_entry *); - - void - archive_entry_free(struct archive_entry *); - - const char * - archive_entry_gname(struct archive_entry *); - - const char * - archive_entry_hardlink(struct archive_entry *); - - ino_t - archive_entry_ino(struct archive_entry *); - - mode_t - archive_entry_mode(struct archive_entry *); - - time_t - archive_entry_mtime(struct archive_entry *); - - long - archive_entry_mtime_nsec(struct archive_entry *); - - unsigned int - archive_entry_nlink(struct archive_entry *); - - struct archive_entry * - archive_entry_new(void); - - const char * - archive_entry_pathname(struct archive_entry *); - - const wchar_t * - archive_entry_pathname_w(struct archive_entry *); - - dev_t - archive_entry_rdev(struct archive_entry *); - - dev_t - archive_entry_rdevmajor(struct archive_entry *); - - dev_t - archive_entry_rdevminor(struct archive_entry *); - - void - archive_entry_set_dev(struct archive_entry *, dev_t); - - void - archive_entry_set_devmajor(struct archive_entry *, dev_t); - - void - archive_entry_set_devminor(struct archive_entry *, dev_t); - - void - archive_entry_set_filetype(struct archive_entry *, unsigned int); - - void - archive_entry_set_fflags(struct archive_entry *, unsigned long set, - unsigned long clear); - - void - archive_entry_set_gid(struct archive_entry *, gid_t); - - void - archive_entry_set_gname(struct archive_entry *, const char *); - - void - archive_entry_set_hardlink(struct archive_entry *, const char *); - - void - archive_entry_set_ino(struct archive_entry *, unsigned long); - - void - archive_entry_set_link(struct archive_entry *, const char *); - - void - archive_entry_set_mode(struct archive_entry *, mode_t); - - void - archive_entry_set_mtime(struct archive_entry *, time_t, long nanos); - - void - archive_entry_set_nlink(struct archive_entry *, unsigned int); - - void - archive_entry_set_pathname(struct archive_entry *, const char *); - - void - archive_entry_set_rdev(struct archive_entry *, dev_t); - - void - archive_entry_set_rdevmajor(struct archive_entry *, dev_t); - - void - archive_entry_set_rdevminor(struct archive_entry *, dev_t); - - void - archive_entry_set_size(struct archive_entry *, int64_t); - - void - archive_entry_set_symlink(struct archive_entry *, const char *); - - void - archive_entry_set_uid(struct archive_entry *, uid_t); - - void - archive_entry_set_uname(struct archive_entry *, const char *); - - int64_t - archive_entry_size(struct archive_entry *); - - const char * - archive_entry_sourcepath(struct archive_entry *); - - const struct stat * - archive_entry_stat(struct archive_entry *); - - const char * - archive_entry_symlink(struct archive_entry *); - - const char * - archive_entry_uname(struct archive_entry *); - -DESCRIPTION - These functions create and manipulate data objects that represent entries - within an archive. You can think of a struct archive_entry as a heavy- - duty version of struct stat: it includes everything from struct stat plus - associated pathname, textual group and user names, etc. These objects - are used by libarchive(3) to represent the metadata associated with a - particular entry in an archive. - - Create and Destroy - There are functions to allocate, destroy, clear, and copy archive_entry - objects: - archive_entry_clear() - Erases the object, resetting all internal fields to the same - state as a newly-created object. This is provided to allow you - to quickly recycle objects without thrashing the heap. - archive_entry_clone() - A deep copy operation; all text fields are duplicated. - archive_entry_free() - Releases the struct archive_entry object. - archive_entry_new() - Allocate and return a blank struct archive_entry object. - - Set and Get Functions - Most of the functions here set or read entries in an object. Such func- - tions have one of the following forms: - archive_entry_set_XXXX() - Stores the provided data in the object. In particular, for - strings, the pointer is stored, not the referenced string. - archive_entry_copy_XXXX() - As above, except that the referenced data is copied into the - object. - archive_entry_XXXX() - Returns the specified data. In the case of strings, a const- - qualified pointer to the string is returned. - String data can be set or accessed as wide character strings or normal - char strings. The functions that use wide character strings are suffixed - with _w. Note that these are different representations of the same data: - For example, if you store a narrow string and read the corresponding wide - string, the object will transparently convert formats using the current - locale. Similarly, if you store a wide string and then store a narrow - string for the same data, the previously-set wide string will be dis- - carded in favor of the new data. - - There are a few set/get functions that merit additional description: - archive_entry_set_link() - This function sets the symlink field if it is already set. Oth- - erwise, it sets the hardlink field. - - File Flags - File flags are transparently converted between a bitmap representation - and a textual format. For example, if you set the bitmap and ask for - text, the library will build a canonical text format. However, if you - set a text format and request a text format, you will get back the same - text, even if it is ill-formed. If you need to canonicalize a textual - flags string, you should first set the text form, then request the bitmap - form, then use that to set the bitmap form. Setting the bitmap format - will clear the internal text representation and force it to be recon- - structed when you next request the text form. - - The bitmap format consists of two integers, one containing bits that - should be set, the other specifying bits that should be cleared. Bits - not mentioned in either bitmap will be ignored. Usually, the bitmap of - bits to be cleared will be set to zero. In unusual circumstances, you - can force a fully-specified set of file flags by setting the bitmap of - flags to clear to the complement of the bitmap of flags to set. (This - differs from fflagstostr(3), which only includes names for set bits.) - Converting a bitmap to a textual string is a platform-specific operation; - bits that are not meaningful on the current platform will be ignored. - - The canonical text format is a comma-separated list of flag names. The - archive_entry_copy_fflags_text() and archive_entry_copy_fflags_text_w() - functions parse the provided text and sets the internal bitmap values. - This is a platform-specific operation; names that are not meaningful on - the current platform will be ignored. The function returns a pointer to - the start of the first name that was not recognized, or NULL if every - name was recognized. Note that every name--including names that follow - an unrecognized name--will be evaluated, and the bitmaps will be set to - reflect every name that is recognized. (In particular, this differs from - strtofflags(3), which stops parsing at the first unrecognized name.) - - ACL Handling - XXX This needs serious help. XXX - - An ``Access Control List'' (ACL) is a list of permissions that grant - access to particular users or groups beyond what would normally be pro- - vided by standard POSIX mode bits. The ACL handling here addresses some - deficiencies in the POSIX.1e draft 17 ACL specification. In particular, - POSIX.1e draft 17 specifies several different formats, but none of those - formats include both textual user/group names and numeric UIDs/GIDs. - - XXX explain ACL stuff XXX - -SEE ALSO - archive(3) - -HISTORY - The libarchive library first appeared in FreeBSD 5.3. - -AUTHORS - The libarchive library was written by Tim Kientzle <kientzle@acm.org>. - -FreeBSD 8.0 May 12, 2008 FreeBSD 8.0 diff --git a/libarchive/libarchive-2.7.1/doc/text/archive_read.3.txt b/libarchive/libarchive-2.7.1/doc/text/archive_read.3.txt deleted file mode 100644 index 8153fd5..0000000 --- a/libarchive/libarchive-2.7.1/doc/text/archive_read.3.txt +++ /dev/null @@ -1,454 +0,0 @@ -archive_read(3) FreeBSD Library Functions Manual archive_read(3) - -NAME - archive_read_new, archive_read_set_filter_options, - archive_read_set_format_options, archive_read_set_options, - archive_read_support_compression_all, - archive_read_support_compression_bzip2, - archive_read_support_compression_compress, - archive_read_support_compression_gzip, - archive_read_support_compression_none, - archive_read_support_compression_program, - archive_read_support_format_all, archive_read_support_format_cpio, - archive_read_support_format_empty, archive_read_support_format_iso9660, - 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_none(struct archive *); - - int - archive_read_support_compression_program(struct archive *, - const char *cmd); - - int - archive_read_support_format_all(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_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_all(), - archive_read_support_compression_bzip2(), - archive_read_support_compression_compress(), - archive_read_support_compression_gzip(), - archive_read_support_compression_none() - Enables auto-detection code and decompression support for the - specified compression. Note that ``none'' is always enabled by - default. For convenience, archive_read_support_compression_all() - enables all available decompression code. - archive_read_support_compression_program() - Data is fed through the specified external program before being - dearchived. Note that this disables automatic detection of the - compression format, so it makes no sense to specify this in con- - junction with any other decompression option. - archive_read_support_format_all(), archive_read_support_format_cpio(), - archive_read_support_format_empty(), - archive_read_support_format_iso9660(), - archive_read_support_format_tar(), - archive_read_support_format_zip() - Enables support---including auto-detection code---for the speci- - fied archive format. For example, - archive_read_support_format_tar() enables support for a variety - of standard tar formats, old-style tar, ustar, pax interchange - format, and many common variants. For convenience, - archive_read_support_format_all() enables support for all avail- - able formats. Only empty archives are supported by default. - archive_read_set_filter_options(), archive_read_set_format_options(), - archive_read_set_options() - Specifies options that will be passed to currently-registered - filters (including decompression filters) and/or format readers. - The argument is a comma-separated list of individual options. - Individual options have one of the following forms: - option=value - The option/value pair will be provided to every module. - Modules that do not accept an option with this name will - ignore it. - option The option will be provided to every module with a value - of ``1''. - !option - The option will be provided to every module with a NULL - value. - module:option=value, module:option, module:!option - As above, but the corresponding option and value will be - provided only to modules whose name matches module. - The return value will be ARCHIVE_OK if any module accepts the - option, or ARCHIVE_WARN if no module accepted the option, or - ARCHIVE_FATAL if there was a fatal error while attempting to - process the option. - - The currently supported options are: - Format iso9660 - joliet Support Joliet extensions. Defaults to enabled, - use !joliet to disable. - archive_read_open() - The same as archive_read_open2(), except that the skip callback - is assumed to be NULL. - archive_read_open2() - Freeze the settings, open the archive, and prepare for reading - entries. This is the most generic version of this call, which - accepts four callback functions. Most clients will want to use - archive_read_open_filename(), archive_read_open_FILE(), - archive_read_open_fd(), or archive_read_open_memory() instead. - The library invokes the client-provided functions to obtain raw - bytes from the archive. - archive_read_open_FILE() - Like archive_read_open(), except that it accepts a FILE * - pointer. This function should not be used with tape drives or - other devices that require strict I/O blocking. - archive_read_open_fd() - Like archive_read_open(), except that it accepts a file descrip- - tor and block size rather than a set of function pointers. Note - that the file descriptor will not be automatically closed at end- - of-archive. This function is safe for use with tape drives or - other blocked devices. - archive_read_open_file() - This is a deprecated synonym for archive_read_open_filename(). - archive_read_open_filename() - Like archive_read_open(), except that it accepts a simple file- - name and a block size. A NULL filename represents standard - input. This function is safe for use with tape drives or other - blocked devices. - archive_read_open_memory() - Like archive_read_open(), except that it accepts a pointer and - size of a block of memory containing the archive data. - archive_read_next_header() - Read the header for the next entry and return a pointer to a - struct archive_entry. This is a convenience wrapper around - archive_read_next_header2() that uses an internal struct - archive_entry object. - archive_read_next_header2() - Read the header for the next entry and populate the provided - struct archive_entry. - archive_read_data() - Read data associated with the header just read. Internally, this - is a convenience function that calls archive_read_data_block() - and fills any gaps with nulls so that callers see a single con- - tinuous stream of data. - archive_read_data_block() - Return the next available block of data for this entry. Unlike - archive_read_data(), the archive_read_data_block() function - avoids copying data and allows you to correctly handle sparse - files, as supported by some archive formats. The library guaran- - tees that offsets will increase and that blocks will not overlap. - Note that the blocks returned from this function can be much - larger than the block size read from disk, due to compression and - internal buffer optimizations. - archive_read_data_skip() - A convenience function that repeatedly calls - archive_read_data_block() to skip all of the data for this ar- - chive entry. - archive_read_data_into_buffer() - This function is deprecated and will be removed. Use - archive_read_data() instead. - archive_read_data_into_fd() - A convenience function that repeatedly calls - archive_read_data_block() to copy the entire entry to the pro- - vided file descriptor. - archive_read_extract(), archive_read_extract_set_skip_file() - A convenience function that wraps the corresponding - archive_write_disk(3) interfaces. The first call to - archive_read_extract() creates a restore object using - archive_write_disk_new(3) and - archive_write_disk_set_standard_lookup(3), then transparently - invokes archive_write_disk_set_options(3), - archive_write_header(3), archive_write_data(3), and - archive_write_finish_entry(3) to create the entry on disk and - copy data into it. The flags argument is passed unmodified to - archive_write_disk_set_options(3). - archive_read_extract2() - This is another version of archive_read_extract() that allows you - to provide your own restore object. In particular, this allows - you to override the standard lookup functions using - archive_write_disk_set_group_lookup(3), and - archive_write_disk_set_user_lookup(3). Note that - archive_read_extract2() does not accept a flags argument; you - should use archive_write_disk_set_options() to set the restore - options yourself. - archive_read_extract_set_progress_callback() - Sets a pointer to a user-defined callback that can be used for - updating progress displays during extraction. The progress func- - tion will be invoked during the extraction of large regular - files. The progress function will be invoked with the pointer - provided to this call. Generally, the data pointed to should - include a reference to the archive object and the archive_entry - object so that various statistics can be retrieved for the - progress display. - archive_read_close() - Complete the archive and invoke the close callback. - archive_read_finish() - Invokes archive_read_close() if it was not invoked manually, then - release all resources. Note: In libarchive 1.x, this function - was declared to return void, which made it impossible to detect - certain errors when archive_read_close() was invoked implicitly - from this function. The declaration is corrected beginning with - libarchive 2.0. - - Note that the library determines most of the relevant information about - the archive by inspection. In particular, it automatically detects - gzip(1) or bzip2(1) compression and transparently performs the appropri- - ate decompression. It also automatically detects the archive format. - - A complete description of the struct archive and struct archive_entry - objects can be found in the overview manual page for libarchive(3). - -CLIENT CALLBACKS - The callback functions must match the following prototypes: - - typedef ssize_t archive_read_callback(struct archive *, - void *client_data, const void **buffer) - - typedef int archive_skip_callback(struct archive *, - void *client_data, size_t request) - - typedef int archive_open_callback(struct archive *, void - *client_data) - - typedef int archive_close_callback(struct archive *, void - *client_data) - - The open callback is invoked by archive_open(). It should return - ARCHIVE_OK if the underlying file or data source is successfully opened. - If the open fails, it should call archive_set_error() to register an - error code and message and return ARCHIVE_FATAL. - - The read callback is invoked whenever the library requires raw bytes from - the archive. The read callback should read data into a buffer, set the - const void **buffer argument to point to the available data, and return a - count of the number of bytes available. The library will invoke the read - callback again only after it has consumed this data. The library imposes - no constraints on the size of the data blocks returned. On end-of-file, - the read callback should return zero. On error, the read callback should - invoke archive_set_error() to register an error code and message and - return -1. - - The skip callback is invoked when the library wants to ignore a block of - data. The return value is the number of bytes actually skipped, which - may differ from the request. If the callback cannot skip data, it should - return zero. If the skip callback is not provided (the function pointer - is NULL ), the library will invoke the read function instead and simply - discard the result. A skip callback can provide significant performance - gains when reading uncompressed archives from slow disk drives or other - media that can skip quickly. - - The close callback is invoked by archive_close when the archive process- - ing is complete. The callback should return ARCHIVE_OK on success. On - failure, the callback should invoke archive_set_error() to register an - error code and message and return ARCHIVE_FATAL. - -EXAMPLE - The following illustrates basic usage of the library. In this example, - the callback functions are simply wrappers around the standard open(2), - read(2), and close(2) system calls. - - void - list_archive(const char *name) - { - struct mydata *mydata; - struct archive *a; - struct archive_entry *entry; - - mydata = malloc(sizeof(struct mydata)); - a = archive_read_new(); - mydata->name = name; - archive_read_support_compression_all(a); - archive_read_support_format_all(a); - archive_read_open(a, mydata, myopen, myread, myclose); - while (archive_read_next_header(a, &entry) == ARCHIVE_OK) { - printf("%s\n",archive_entry_pathname(entry)); - archive_read_data_skip(a); - } - archive_read_finish(a); - free(mydata); - } - - ssize_t - myread(struct archive *a, void *client_data, const void **buff) - { - struct mydata *mydata = client_data; - - *buff = mydata->buff; - return (read(mydata->fd, mydata->buff, 10240)); - } - - int - myopen(struct archive *a, void *client_data) - { - struct mydata *mydata = client_data; - - mydata->fd = open(mydata->name, O_RDONLY); - return (mydata->fd >= 0 ? ARCHIVE_OK : ARCHIVE_FATAL); - } - - int - myclose(struct archive *a, void *client_data) - { - struct mydata *mydata = client_data; - - if (mydata->fd > 0) - close(mydata->fd); - return (ARCHIVE_OK); - } - -RETURN VALUES - Most functions return zero on success, non-zero on error. The possible - return codes include: ARCHIVE_OK (the operation succeeded), ARCHIVE_WARN - (the operation succeeded but a non-critical error was encountered), - ARCHIVE_EOF (end-of-archive was encountered), ARCHIVE_RETRY (the opera- - tion failed but can be retried), and ARCHIVE_FATAL (there was a fatal - error; the archive should be closed immediately). Detailed error codes - and textual descriptions are available from the archive_errno() and - archive_error_string() functions. - - archive_read_new() returns a pointer to a freshly allocated struct - archive object. It returns NULL on error. - - archive_read_data() returns a count of bytes actually read or zero at the - end of the entry. On error, a value of ARCHIVE_FATAL, ARCHIVE_WARN, or - ARCHIVE_RETRY is returned and an error code and textual description can - be retrieved from the archive_errno() and archive_error_string() func- - tions. - - The library expects the client callbacks to behave similarly. If there - is an error, you can use archive_set_error() to set an appropriate error - code and description, then return one of the non-zero values above. - (Note that the value eventually returned to the client may not be the - same; many errors that are not critical at the level of basic I/O can - prevent the archive from being properly read, thus most I/O errors even- - tually cause ARCHIVE_FATAL to be returned.) - -SEE ALSO - tar(1), archive(3), archive_util(3), tar(5) - -HISTORY - The libarchive library first appeared in FreeBSD 5.3. - -AUTHORS - The libarchive library was written by Tim Kientzle <kientzle@acm.org>. - -BUGS - Many traditional archiver programs treat empty files as valid empty ar- - chives. For example, many implementations of tar(1) allow you to append - entries to an empty file. Of course, it is impossible to determine the - format of an empty file by inspecting the contents, so this library - treats empty files as having a special ``empty'' format. - -FreeBSD 8.0 August 19, 2006 FreeBSD 8.0 diff --git a/libarchive/libarchive-2.7.1/doc/text/archive_read_disk.3.txt b/libarchive/libarchive-2.7.1/doc/text/archive_read_disk.3.txt deleted file mode 100644 index 0522bf4..0000000 --- a/libarchive/libarchive-2.7.1/doc/text/archive_read_disk.3.txt +++ /dev/null @@ -1,204 +0,0 @@ -archive_read_disk(3) FreeBSD Library Functions Manual archive_read_disk(3) - -NAME - archive_read_disk_new, archive_read_disk_set_symlink_logical, - archive_read_disk_set_symlink_physical, - archive_read_disk_set_symlink_hybrid, archive_read_disk_entry_from_file, - archive_read_disk_gname, archive_read_disk_uname, - archive_read_disk_set_uname_lookup, archive_read_disk_set_gname_lookup, - archive_read_disk_set_standard_lookup, archive_read_close, - archive_read_finish -- functions for reading objects from disk - -SYNOPSIS - #include <archive.h> - - struct archive * - archive_read_disk_new(void); - - int - archive_read_disk_set_symlink_logical(struct archive *); - - int - archive_read_disk_set_symlink_physical(struct archive *); - - int - archive_read_disk_set_symlink_hybrid(struct archive *); - - int - archive_read_disk_gname(struct archive *, gid_t); - - int - archive_read_disk_uname(struct archive *, uid_t); - - int - archive_read_disk_set_gname_lookup(struct archive *, void *, - const char *(*lookup)(void *, gid_t), void (*cleanup)(void *)); - - int - archive_read_disk_set_uname_lookup(struct archive *, void *, - const char *(*lookup)(void *, uid_t), void (*cleanup)(void *)); - - int - archive_read_disk_set_standard_lookup(struct archive *); - - int - archive_read_disk_entry_from_file(struct archive *, - struct archive_entry *, int fd, const struct stat *); - - int - archive_read_close(struct archive *); - - int - archive_read_finish(struct archive *); - -DESCRIPTION - These functions provide an API for reading information about objects on - disk. In particular, they provide an interface for populating struct - archive_entry objects. - - archive_read_disk_new() - Allocates and initializes a struct archive object suitable for - reading object information from disk. - - archive_read_disk_set_symlink_logical(), - archive_read_disk_set_symlink_physical(), - archive_read_disk_set_symlink_hybrid() - This sets the mode used for handling symbolic links. The - ``logical'' mode follows all symbolic links. The ``physical'' - mode does not follow any symbolic links. The ``hybrid'' mode - currently behaves identically to the ``logical'' mode. - - archive_read_disk_gname(), archive_read_disk_uname() - Returns a user or group name given a gid or uid value. By - default, these always return a NULL string. - - archive_read_disk_set_gname_lookup(), - archive_read_disk_set_uname_lookup() - These allow you to override the functions used for user and group - name lookups. You may also provide a void * pointer to a private - data structure and a cleanup function for that data. The cleanup - function will be invoked when the struct archive object is - destroyed or when new lookup functions are registered. - - archive_read_disk_set_standard_lookup() - This convenience function installs a standard set of user and - group name lookup functions. These functions use getpwid(3) and - getgrid(3) to convert ids to names, defaulting to NULL if the - names cannot be looked up. These functions also implement a sim- - ple memory cache to reduce the number of calls to getpwid(3) and - getgrid(3). - - archive_read_disk_entry_from_file() - Populates a struct archive_entry object with information about a - particular file. The archive_entry object must have already been - created with archive_entry_new(3) and at least one of the source - path or path fields must already be set. (If both are set, the - source path will be used.) - - Information is read from disk using the path name from the struct - archive_entry object. If a file descriptor is provided, some - information will be obtained using that file descriptor, on plat- - forms that support the appropriate system calls. - - If a pointer to a struct stat is provided, information from that - structure will be used instead of reading from the disk where - appropriate. This can provide performance benefits in scenarios - where struct stat information has already been read from the disk - as a side effect of some other operation. (For example, direc- - tory traversal libraries often provide this information.) - - Where necessary, user and group ids are converted to user and - group names using the currently registered lookup functions - above. This affects the file ownership fields and ACL values in - the struct archive_entry object. - - archive_read_close() - This currently does nothing. - - archive_write_finish() - Invokes archive_write_close() if it was not invoked manually, - then releases all resources. - More information about the struct archive object and the overall design - of the library can be found in the libarchive(3) overview. - -EXAMPLE - The following illustrates basic usage of the library by showing how to - use it to copy an item on disk into an archive. - - void - file_to_archive(struct archive *a, const char *name) - { - char buff[8192]; - size_t bytes_read; - struct archive *ard; - struct archive_entry *entry; - int fd; - - ard = archive_read_disk_new(); - archive_read_disk_set_standard_lookup(ard); - entry = archive_entry_new(); - fd = open(name, O_RDONLY); - if (fd < 0) - return; - archive_entry_copy_sourcepath(entry, name); - archive_read_disk_entry_from_file(ard, entry, fd, NULL); - archive_write_header(a, entry); - while ((bytes_read = read(fd, buff, sizeof(buff))) > 0) - archive_write_data(a, buff, bytes_read); - archive_write_finish_entry(a); - archive_read_finish(ard); - archive_entry_free(entry); - } - -RETURN VALUES - Most functions return ARCHIVE_OK (zero) on success, or one of several - negative error codes for errors. Specific error codes include: - ARCHIVE_RETRY for operations that might succeed if retried, ARCHIVE_WARN - for unusual conditions that do not prevent further operations, and - ARCHIVE_FATAL for serious errors that make remaining operations impossi- - ble. The archive_errno(3) and archive_error_string(3) functions can be - used to retrieve an appropriate error code and a textual error message. - (See archive_util(3) for details.) - - archive_read_disk_new() returns a pointer to a newly-allocated struct - archive object or NULL if the allocation failed for any reason. - - archive_read_disk_gname() and archive_read_disk_uname() return const char - * pointers to the textual name or NULL if the lookup failed for any rea- - son. The returned pointer points to internal storage that may be reused - on the next call to either of these functions; callers should copy the - string if they need to continue accessing it. - -SEE ALSO - archive_read(3), archive_write(3), archive_write_disk(3), tar(1), - libarchive(3) - -HISTORY - The libarchive library first appeared in FreeBSD 5.3. The - archive_read_disk interface was added to libarchive 2.6 and first - appeared in FreeBSD 8.0. - -AUTHORS - The libarchive library was written by Tim Kientzle - <kientzle@freebsd.org>. - -BUGS - The ``standard'' user name and group name lookup functions are not the - defaults because getgrid(3) and getpwid(3) are sometimes too large for - particular applications. The current design allows the application - author to use a more compact implementation when appropriate. - - The full list of metadata read from disk by - archive_read_disk_entry_from_file() is necessarily system-dependent. - - The archive_read_disk_entry_from_file() function reads as much informa- - tion as it can from disk. Some method should be provided to limit this - so that clients who do not need ACLs, for instance, can avoid the extra - work needed to look up such information. - - This API should provide a set of methods for walking a directory tree. - That would make it a direct parallel of the archive_read(3) API. When - such methods are implemented, the ``hybrid'' symbolic link mode will make - sense. - -FreeBSD 8.0 March 10, 2009 FreeBSD 8.0 diff --git a/libarchive/libarchive-2.7.1/doc/text/archive_util.3.txt b/libarchive/libarchive-2.7.1/doc/text/archive_util.3.txt deleted file mode 100644 index f6e2a9f..0000000 --- a/libarchive/libarchive-2.7.1/doc/text/archive_util.3.txt +++ /dev/null @@ -1,91 +0,0 @@ -archive_util(3) FreeBSD Library Functions Manual archive_util(3) - -NAME - archive_clear_error, archive_compression, archive_compression_name, - archive_copy_error, archive_errno, archive_error_string, archive_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_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_format() - Returns a numeric code indicating the format of the current ar- - chive entry. This value is set by a successful call to - archive_read_next_header(). Note that it is common for this - value to change from entry to entry. For example, a tar archive - might have several entries that utilize GNU tar extensions and - several entries that do not. These entries will have different - format codes. - archive_format_name() - A textual description of the format of the current entry. - archive_set_error() - Sets the numeric error code and error description that will be - returned by archive_errno() and archive_error_string(). This - function should be used within I/O callbacks to set system-spe- - cific error codes and error descriptions. This function accepts - a printf-like format string and arguments. However, you should - be careful to use only the following printf format specifiers: - ``%c'', ``%d'', ``%jd'', ``%jo'', ``%ju'', ``%jx'', ``%ld'', - ``%lo'', ``%lu'', ``%lx'', ``%o'', ``%u'', ``%s'', ``%x'', - ``%%''. Field-width specifiers and other printf features are not - uniformly supported and should not be used. - -SEE ALSO - archive_read(3), archive_write(3), libarchive(3), printf(3) - -HISTORY - The libarchive library first appeared in FreeBSD 5.3. - -AUTHORS - The libarchive library was written by Tim Kientzle <kientzle@acm.org>. - -FreeBSD 8.0 January 8, 2005 FreeBSD 8.0 diff --git a/libarchive/libarchive-2.7.1/doc/text/archive_write.3.txt b/libarchive/libarchive-2.7.1/doc/text/archive_write.3.txt deleted file mode 100644 index 31d63ae..0000000 --- a/libarchive/libarchive-2.7.1/doc/text/archive_write.3.txt +++ /dev/null @@ -1,483 +0,0 @@ -archive_write(3) FreeBSD Library Functions Manual archive_write(3) - -NAME - archive_write_new, archive_write_set_format_cpio, - archive_write_set_format_pax, archive_write_set_format_pax_restricted, - archive_write_set_format_shar, archive_write_set_format_shar_binary, - archive_write_set_format_ustar, archive_write_get_bytes_per_block, - archive_write_set_bytes_per_block, archive_write_set_bytes_in_last_block, - archive_write_set_compression_bzip2, - archive_write_set_compression_compress, - archive_write_set_compression_gzip, archive_write_set_compression_none, - archive_write_set_compression_program, - archive_write_set_compressor_options, archive_write_set_format_options, - archive_write_set_options, archive_write_open, archive_write_open_fd, - archive_write_open_FILE, archive_write_open_filename, - archive_write_open_memory, archive_write_header, archive_write_data, - archive_write_finish_entry, archive_write_close, archive_write_finish -- - functions for creating archives - -SYNOPSIS - #include <archive.h> - - struct archive * - archive_write_new(void); - - int - archive_write_get_bytes_per_block(struct archive *); - - int - archive_write_set_bytes_per_block(struct archive *, int bytes_per_block); - - int - archive_write_set_bytes_in_last_block(struct archive *, int); - - int - archive_write_set_compression_bzip2(struct archive *); - - int - archive_write_set_compression_compress(struct archive *); - - int - archive_write_set_compression_gzip(struct archive *); - - int - archive_write_set_compression_none(struct archive *); - - int - archive_write_set_compression_program(struct archive *, - const char * cmd); - - int - archive_write_set_format_cpio(struct archive *); - - int - archive_write_set_format_pax(struct archive *); - - int - archive_write_set_format_pax_restricted(struct archive *); - - int - archive_write_set_format_shar(struct archive *); - - int - archive_write_set_format_shar_binary(struct archive *); - - int - archive_write_set_format_ustar(struct archive *); - - int - archive_write_set_format_options(struct archive *, const char *); - - int - archive_write_set_compressor_options(struct archive *, const char *); - - int - archive_write_set_options(struct archive *, const char *); - - int - archive_write_open(struct archive *, void *client_data, - archive_open_callback *, archive_write_callback *, - archive_close_callback *); - - int - archive_write_open_fd(struct archive *, int fd); - - int - archive_write_open_FILE(struct archive *, FILE *file); - - int - archive_write_open_filename(struct archive *, const char *filename); - - int - archive_write_open_memory(struct archive *, void *buffer, - size_t bufferSize, size_t *outUsed); - - int - archive_write_header(struct archive *, struct archive_entry *); - - ssize_t - archive_write_data(struct archive *, const void *, size_t); - - int - archive_write_finish_entry(struct archive *); - - int - archive_write_close(struct archive *); - - int - archive_write_finish(struct archive *); - -DESCRIPTION - These functions provide a complete API for creating streaming archive - files. The general process is to first create the struct archive object, - set any desired options, initialize the archive, append entries, then - close the archive and release all resources. The following summary - describes the functions in approximately the order they are ordinarily - used: - - archive_write_new() - Allocates and initializes a struct archive object suitable for - writing a tar archive. - - archive_write_set_bytes_per_block() - Sets the block size used for writing the archive data. Every - call to the write callback function, except possibly the last - one, will use this value for the length. The third parameter is - a boolean that specifies whether or not the final block written - will be padded to the full block size. If it is zero, the last - block will not be padded. If it is non-zero, padding will be - added both before and after compression. The default is to use a - block size of 10240 bytes and to pad the last block. Note that a - block size of zero will suppress internal blocking and cause - writes to be sent directly to the write callback as they occur. - - archive_write_get_bytes_per_block() - Retrieve the block size to be used for writing. A value of -1 - here indicates that the library should use default values. A - value of zero indicates that internal blocking is suppressed. - - archive_write_set_bytes_in_last_block() - Sets the block size used for writing the last block. If this - value is zero, the last block will be padded to the same size as - the other blocks. Otherwise, the final block will be padded to a - multiple of this size. In particular, setting it to 1 will cause - the final block to not be padded. For compressed output, any - padding generated by this option is applied only after the com- - pression. The uncompressed data is always unpadded. The default - is to pad the last block to the full block size (note that - archive_write_open_filename() will set this based on the file - type). Unlike the other ``set'' functions, this function can be - called after the archive is opened. - - archive_write_get_bytes_in_last_block() - Retrieve the currently-set value for last block size. A value of - -1 here indicates that the library should use default values. - - archive_write_set_format_cpio(), archive_write_set_format_pax(), - archive_write_set_format_pax_restricted(), - archive_write_set_format_shar(), - archive_write_set_format_shar_binary(), - archive_write_set_format_ustar() - Sets the format that will be used for the archive. The library - can write POSIX octet-oriented cpio format archives, POSIX-stan- - dard ``pax interchange'' format archives, traditional ``shar'' - archives, enhanced ``binary'' shar archives that store a variety - of file attributes and handle binary files, and POSIX-standard - ``ustar'' archives. The pax interchange format is a backwards- - compatible tar format that adds key/value attributes to each - entry and supports arbitrary filenames, linknames, uids, sizes, - etc. ``Restricted pax interchange format'' is the library - default; this is the same as pax format, but suppresses the pax - extended header for most normal files. In most cases, this will - result in ordinary ustar archives. - - archive_write_set_compression_bzip2(), - archive_write_set_compression_compress(), - archive_write_set_compression_gzip(), - archive_write_set_compression_none() - The resulting archive will be compressed as specified. Note that - the compressed output is always properly blocked. - - archive_write_set_compression_program() - The archive will be fed into the specified compression program. - The output of that program is blocked and written to the client - write callbacks. - - archive_write_set_compressor_options(), - archive_write_set_format_options(), archive_write_set_options() - Specifies options that will be passed to the currently-enabled - compressor and/or format writer. The argument is a comma-sepa- - rated list of individual options. Individual options have one of - the following forms: - option=value - The option/value pair will be provided to every module. - Modules that do not accept an option with this name will - ignore it. - option The option will be provided to every module with a value - of ``1''. - !option - The option will be provided to every module with a NULL - value. - module:option=value, module:option, module:!option - As above, but the corresponding option and value will be - provided only to modules whose name matches module. - The return value will be ARCHIVE_OK if any module accepts the - option, or ARCHIVE_WARN if no module accepted the option, or - ARCHIVE_FATAL if there was a fatal error while attempting to - process the option. - - The currently supported options are: - Compressor gzip - compression-level - The value is interpreted as a decimal integer - specifying the gzip compression level. - Compressor xz - compression-level - The value is interpreted as a decimal integer - specifying the compression level. - Format mtree - cksum, device, flags, gid, gname, indent, link, md5, - mode, nlink, rmd160, sha1, sha256, sha384, - sha512, size, time, uid, uname - Enable a particular keyword in the mtree output. - Prefix with an exclamation mark to disable the - corresponding keyword. The default is equivalent - to ``device, flags, gid, gname, link, mode, - nlink, size, time, type, uid, uname''. - all Enables all of the above keywords. - use-set - Enables generation of /set lines that specify - default values for the following files and/or - directories. - indent XXX needs explanation XXX - - archive_write_open() - Freeze the settings, open the archive, and prepare for writing - entries. This is the most generic form of this function, which - accepts pointers to three callback functions which will be - invoked by the compression layer to write the constructed ar- - chive. - - archive_write_open_fd() - A convenience form of archive_write_open() that accepts a file - descriptor. The archive_write_open_fd() function is safe for use - with tape drives or other block-oriented devices. - - archive_write_open_FILE() - A convenience form of archive_write_open() that accepts a FILE * - pointer. Note that archive_write_open_FILE() is not safe for - writing to tape drives or other devices that require correct - blocking. - - archive_write_open_file() - A deprecated synonym for archive_write_open_filename(). - - archive_write_open_filename() - A convenience form of archive_write_open() that accepts a file- - name. A NULL argument indicates that the output should be writ- - ten to standard output; an argument of ``-'' will open a file - with that name. If you have not invoked - archive_write_set_bytes_in_last_block(), then - archive_write_open_filename() will adjust the last-block padding - depending on the file: it will enable padding when writing to - standard output or to a character or block device node, it will - disable padding otherwise. You can override this by manually - invoking archive_write_set_bytes_in_last_block() before calling - archive_write_open(). The archive_write_open_filename() function - is safe for use with tape drives or other block-oriented devices. - - archive_write_open_memory() - A convenience form of archive_write_open() that accepts a pointer - to a block of memory that will receive the archive. The final - size_t * argument points to a variable that will be updated after - each write to reflect how much of the buffer is currently in use. - You should be careful to ensure that this variable remains allo- - cated until after the archive is closed. - - archive_write_header() - Build and write a header using the data in the provided struct - archive_entry structure. See archive_entry(3) for information on - creating and populating struct archive_entry objects. - - archive_write_data() - Write data corresponding to the header just written. Returns - number of bytes written or -1 on error. - - archive_write_finish_entry() - Close out the entry just written. In particular, this writes out - the final padding required by some formats. Ordinarily, clients - never need to call this, as it is called automatically by - archive_write_next_header() and archive_write_close() as needed. - - archive_write_close() - Complete the archive and invoke the close callback. - - archive_write_finish() - Invokes archive_write_close() if it was not invoked manually, - then releases all resources. Note that this function was - declared to return void in libarchive 1.x, which made it impossi- - ble to detect errors when archive_write_close() was invoked - implicitly from this function. This is corrected beginning with - libarchive 2.0. - More information about the struct archive object and the overall design - of the library can be found in the libarchive(3) overview. - -IMPLEMENTATION - Compression support is built-in to libarchive, which uses zlib and bzlib - to handle gzip and bzip2 compression, respectively. - -CLIENT CALLBACKS - To use this library, you will need to define and register callback func- - tions that will be invoked to write data to the resulting archive. These - functions are registered by calling archive_write_open(): - - typedef int archive_open_callback(struct archive *, void - *client_data) - - The open callback is invoked by archive_write_open(). It should return - ARCHIVE_OK if the underlying file or data source is successfully opened. - If the open fails, it should call archive_set_error() to register an - error code and message and return ARCHIVE_FATAL. - - typedef ssize_t archive_write_callback(struct archive *, - void *client_data, const void *buffer, size_t length) - - The write callback is invoked whenever the library needs to write raw - bytes to the archive. For correct blocking, each call to the write call- - back function should translate into a single write(2) system call. This - is especially critical when writing archives to tape drives. On success, - the write callback should return the number of bytes actually written. - On error, the callback should invoke archive_set_error() to register an - error code and message and return -1. - - typedef int archive_close_callback(struct archive *, void - *client_data) - - The close callback is invoked by archive_close when the archive process- - ing is complete. The callback should return ARCHIVE_OK on success. On - failure, the callback should invoke archive_set_error() to register an - error code and message and return ARCHIVE_FATAL. - -EXAMPLE - The following sketch illustrates basic usage of the library. In this - example, the callback functions are simply wrappers around the standard - open(2), write(2), and close(2) system calls. - - #include <sys/stat.h> - #include <archive.h> - #include <archive_entry.h> - #include <fcntl.h> - #include <stdlib.h> - #include <unistd.h> - - struct mydata { - const char *name; - int fd; - }; - - int - myopen(struct archive *a, void *client_data) - { - struct mydata *mydata = client_data; - - mydata->fd = open(mydata->name, O_WRONLY | O_CREAT, 0644); - if (mydata->fd >= 0) - return (ARCHIVE_OK); - else - return (ARCHIVE_FATAL); - } - - ssize_t - mywrite(struct archive *a, void *client_data, const void *buff, size_t n) - { - struct mydata *mydata = client_data; - - return (write(mydata->fd, buff, n)); - } - - int - myclose(struct archive *a, void *client_data) - { - struct mydata *mydata = client_data; - - if (mydata->fd > 0) - close(mydata->fd); - return (0); - } - - void - write_archive(const char *outname, const char **filename) - { - struct mydata *mydata = malloc(sizeof(struct mydata)); - struct archive *a; - struct archive_entry *entry; - struct stat st; - char buff[8192]; - int len; - int fd; - - a = archive_write_new(); - mydata->name = outname; - archive_write_set_compression_gzip(a); - archive_write_set_format_ustar(a); - archive_write_open(a, mydata, myopen, mywrite, myclose); - while (*filename) { - stat(*filename, &st); - entry = archive_entry_new(); - archive_entry_copy_stat(entry, &st); - archive_entry_set_pathname(entry, *filename); - archive_write_header(a, entry); - fd = open(*filename, O_RDONLY); - len = read(fd, buff, sizeof(buff)); - while ( len > 0 ) { - archive_write_data(a, buff, len); - len = read(fd, buff, sizeof(buff)); - } - archive_entry_free(entry); - filename++; - } - archive_write_finish(a); - } - - int main(int argc, const char **argv) - { - const char *outname; - argv++; - outname = argv++; - write_archive(outname, argv); - return 0; - } - -RETURN VALUES - Most functions return ARCHIVE_OK (zero) on success, or one of several - non-zero error codes for errors. Specific error codes include: - ARCHIVE_RETRY for operations that might succeed if retried, ARCHIVE_WARN - for unusual conditions that do not prevent further operations, and - ARCHIVE_FATAL for serious errors that make remaining operations impossi- - ble. The archive_errno() and archive_error_string() functions can be - used to retrieve an appropriate error code and a textual error message. - - archive_write_new() returns a pointer to a newly-allocated struct archive - object. - - archive_write_data() returns a count of the number of bytes actually - written. On error, -1 is returned and the archive_errno() and - archive_error_string() functions will return appropriate values. Note - that if the client-provided write callback function returns a non-zero - value, that error will be propagated back to the caller through whatever - API function resulted in that call, which may include - archive_write_header(), archive_write_data(), archive_write_close(), or - archive_write_finish(). The client callback can call archive_set_error() - to provide values that can then be retrieved by archive_errno() and - archive_error_string(). - -SEE ALSO - tar(1), libarchive(3), tar(5) - -HISTORY - The libarchive library first appeared in FreeBSD 5.3. - -AUTHORS - The libarchive library was written by Tim Kientzle <kientzle@acm.org>. - -BUGS - There are many peculiar bugs in historic tar implementations that may - cause certain programs to reject archives written by this library. For - example, several historic implementations calculated header checksums - incorrectly and will thus reject valid archives; GNU tar does not fully - support pax interchange format; some old tar implementations required - specific field terminations. - - The default pax interchange format eliminates most of the historic tar - limitations and provides a generic key/value attribute facility for ven- - dor-defined extensions. One oversight in POSIX is the failure to provide - a standard attribute for large device numbers. This library uses - ``SCHILY.devminor'' and ``SCHILY.devmajor'' for device numbers that - exceed the range supported by the backwards-compatible ustar header. - These keys are compatible with Joerg Schilling's star archiver. Other - implementations may not recognize these keys and will thus be unable to - correctly restore device nodes with large device numbers from archives - created by this library. - -FreeBSD 8.0 May 11, 2008 FreeBSD 8.0 diff --git a/libarchive/libarchive-2.7.1/doc/text/archive_write_disk.3.txt b/libarchive/libarchive-2.7.1/doc/text/archive_write_disk.3.txt deleted file mode 100644 index e63ec61..0000000 --- a/libarchive/libarchive-2.7.1/doc/text/archive_write_disk.3.txt +++ /dev/null @@ -1,257 +0,0 @@ -archive_write_disk(3) FreeBSD Library Functions Manual archive_write_disk(3) - -NAME - archive_write_disk_new, archive_write_disk_set_options, - archive_write_disk_set_skip_file, archive_write_disk_set_group_lookup, - archive_write_disk_set_standard_lookup, - archive_write_disk_set_user_lookup, archive_write_header, - archive_write_data, archive_write_finish_entry, archive_write_close, - archive_write_finish -- functions for creating objects on disk - -SYNOPSIS - #include <archive.h> - - struct archive * - archive_write_disk_new(void); - - int - archive_write_disk_set_options(struct archive *, int flags); - - int - archive_write_disk_set_skip_file(struct archive *, dev_t, ino_t); - - int - archive_write_disk_set_group_lookup(struct archive *, void *, - gid_t (*)(void *, const char *gname, gid_t gid), - void (*cleanup)(void *)); - - int - archive_write_disk_set_standard_lookup(struct archive *); - - int - archive_write_disk_set_user_lookup(struct archive *, void *, - uid_t (*)(void *, const char *uname, uid_t uid), - void (*cleanup)(void *)); - - int - archive_write_header(struct archive *, struct archive_entry *); - - ssize_t - archive_write_data(struct archive *, const void *, size_t); - - int - archive_write_finish_entry(struct archive *); - - int - archive_write_close(struct archive *); - - int - archive_write_finish(struct archive *); - -DESCRIPTION - These functions provide a complete API for creating objects on disk from - struct archive_entry descriptions. They are most naturally used when - extracting objects from an archive using the archive_read() interface. - The general process is to read struct archive_entry objects from an ar- - chive, then write those objects to a struct archive object created using - the archive_write_disk() family functions. This interface is deliber- - ately very similar to the archive_write() interface used to write objects - to a streaming archive. - - archive_write_disk_new() - Allocates and initializes a struct archive object suitable for - writing objects to disk. - - archive_write_disk_set_skip_file() - Records the device and inode numbers of a file that should not be - overwritten. This is typically used to ensure that an extraction - process does not overwrite the archive from which objects are - being read. This capability is technically unnecessary but can - be a significant performance optimization in practice. - - archive_write_disk_set_options() - The options field consists of a bitwise OR of one or more of the - following values: - ARCHIVE_EXTRACT_OWNER - The user and group IDs should be set on the restored - file. By default, the user and group IDs are not - restored. - ARCHIVE_EXTRACT_PERM - Full permissions (including SGID, SUID, and sticky bits) - should be restored exactly as specified, without obeying - the current umask. Note that SUID and SGID bits can only - be restored if the user and group ID of the object on - disk are correct. If ARCHIVE_EXTRACT_OWNER is not speci- - fied, then SUID and SGID bits will only be restored if - the default user and group IDs of newly-created objects - on disk happen to match those specified in the archive - entry. By default, only basic permissions are restored, - and umask is obeyed. - ARCHIVE_EXTRACT_TIME - The timestamps (mtime, ctime, and atime) should be - restored. By default, they are ignored. Note that - restoring of atime is not currently supported. - ARCHIVE_EXTRACT_NO_OVERWRITE - Existing files on disk will not be overwritten. By - default, existing regular files are truncated and over- - written; existing directories will have their permissions - updated; other pre-existing objects are unlinked and - recreated from scratch. - ARCHIVE_EXTRACT_UNLINK - Existing files on disk will be unlinked before any - attempt to create them. In some cases, this can prove to - be a significant performance improvement. By default, - existing files are truncated and rewritten, but the file - is not recreated. In particular, the default behavior - does not break existing hard links. - ARCHIVE_EXTRACT_ACL - Attempt to restore ACLs. By default, extended ACLs are - ignored. - ARCHIVE_EXTRACT_FFLAGS - Attempt to restore extended file flags. By default, file - flags are ignored. - ARCHIVE_EXTRACT_XATTR - Attempt to restore POSIX.1e extended attributes. By - default, they are ignored. - ARCHIVE_EXTRACT_SECURE_SYMLINKS - Refuse to extract any object whose final location would - be altered by a symlink on disk. This is intended to - help guard against a variety of mischief caused by ar- - chives that (deliberately or otherwise) extract files - outside of the current directory. The default is not to - perform this check. If ARCHIVE_EXTRACT_UNLINK is speci- - fied together with this option, the library will remove - any intermediate symlinks it finds and return an error - only if such symlink could not be removed. - ARCHIVE_EXTRACT_SECURE_NODOTDOT - Refuse to extract a path that contains a .. element any- - where within it. The default is to not refuse such - paths. Note that paths ending in .. always cause an - error, regardless of this flag. - ARCHIVE_EXTRACT_SPARSE - Scan data for blocks of NUL bytes and try to recreate - them with holes. This results in sparse files, indepen- - dent of whether the archive format supports or uses them. - - archive_write_disk_set_group_lookup(), - archive_write_disk_set_user_lookup() - The struct archive_entry objects contain both names and ids that - can be used to identify users and groups. These names and ids - describe the ownership of the file itself and also appear in ACL - lists. By default, the library uses the ids and ignores the - names, but this can be overridden by registering user and group - lookup functions. To register, you must provide a lookup func- - tion which accepts both a name and id and returns a suitable id. - You may also provide a void * pointer to a private data structure - and a cleanup function for that data. The cleanup function will - be invoked when the struct archive object is destroyed. - - archive_write_disk_set_standard_lookup() - This convenience function installs a standard set of user and - group lookup functions. These functions use getpwnam(3) and - getgrnam(3) to convert names to ids, defaulting to the ids if the - names cannot be looked up. These functions also implement a sim- - ple memory cache to reduce the number of calls to getpwnam(3) and - getgrnam(3). - - archive_write_header() - Build and write a header using the data in the provided struct - archive_entry structure. See archive_entry(3) for information on - creating and populating struct archive_entry objects. - - archive_write_data() - Write data corresponding to the header just written. Returns - number of bytes written or -1 on error. - - archive_write_finish_entry() - Close out the entry just written. Ordinarily, clients never need - to call this, as it is called automatically by - archive_write_next_header() and archive_write_close() as needed. - - archive_write_close() - Set any attributes that could not be set during the initial - restore. For example, directory timestamps are not restored ini- - tially because restoring a subsequent file would alter that time- - stamp. Similarly, non-writable directories are initially created - with write permissions (so that their contents can be restored). - The archive_write_disk_new library maintains a list of all such - deferred attributes and sets them when this function is invoked. - - archive_write_finish() - Invokes archive_write_close() if it was not invoked manually, - then releases all resources. - More information about the struct archive object and the overall design - of the library can be found in the libarchive(3) overview. Many of these - functions are also documented under archive_write(3). - -RETURN VALUES - Most functions return ARCHIVE_OK (zero) on success, or one of several - non-zero error codes for errors. Specific error codes include: - ARCHIVE_RETRY for operations that might succeed if retried, ARCHIVE_WARN - for unusual conditions that do not prevent further operations, and - ARCHIVE_FATAL for serious errors that make remaining operations impossi- - ble. The archive_errno() and archive_error_string() functions can be - used to retrieve an appropriate error code and a textual error message. - - archive_write_disk_new() returns a pointer to a newly-allocated struct - archive object. - - archive_write_data() returns a count of the number of bytes actually - written. On error, -1 is returned and the archive_errno() and - archive_error_string() functions will return appropriate values. - -SEE ALSO - archive_read(3), archive_write(3), tar(1), libarchive(3) - -HISTORY - The libarchive library first appeared in FreeBSD 5.3. The - archive_write_disk interface was added to libarchive 2.0 and first - appeared in FreeBSD 6.3. - -AUTHORS - The libarchive library was written by Tim Kientzle <kientzle@acm.org>. - -BUGS - Directories are actually extracted in two distinct phases. Directories - are created during archive_write_header(), but final permissions are not - set until archive_write_close(). This separation is necessary to cor- - rectly handle borderline cases such as a non-writable directory contain- - ing files, but can cause unexpected results. In particular, directory - permissions are not fully restored until the archive is closed. If you - use chdir(2) to change the current directory between calls to - archive_read_extract() or before calling archive_read_close(), you may - confuse the permission-setting logic with the result that directory per- - missions are restored incorrectly. - - The library attempts to create objects with filenames longer than - PATH_MAX by creating prefixes of the full path and changing the current - directory. Currently, this logic is limited in scope; the fixup pass - does not work correctly for such objects and the symlink security check - option disables the support for very long pathnames. - - Restoring the path aa/../bb does create each intermediate directory. In - particular, the directory aa is created as well as the final object bb. - In theory, this can be exploited to create an entire directory heirarchy - with a single request. Of course, this does not work if the - ARCHIVE_EXTRACT_NODOTDOT option is specified. - - Implicit directories are always created obeying the current umask. - Explicit objects are created obeying the current umask unless - ARCHIVE_EXTRACT_PERM is specified, in which case they current umask is - ignored. - - SGID and SUID bits are restored only if the correct user and group could - be set. If ARCHIVE_EXTRACT_OWNER is not specified, then no attempt is - made to set the ownership. In this case, SGID and SUID bits are restored - only if the user and group of the final object happen to match those - specified in the entry. - - The ``standard'' user-id and group-id lookup functions are not the - defaults because getgrnam(3) and getpwnam(3) are sometimes too large for - particular applications. The current design allows the application - author to use a more compact implementation when appropriate. - - There should be a corresponding archive_read_disk interface that walks a - directory heirarchy and returns archive entry objects. - -FreeBSD 8.0 August 5, 2008 FreeBSD 8.0 diff --git a/libarchive/libarchive-2.7.1/doc/text/bsdcpio.1.txt b/libarchive/libarchive-2.7.1/doc/text/bsdcpio.1.txt deleted file mode 100644 index 6c50327..0000000 --- a/libarchive/libarchive-2.7.1/doc/text/bsdcpio.1.txt +++ /dev/null @@ -1,222 +0,0 @@ -BSDCPIO(1) FreeBSD General Commands Manual BSDCPIO(1) - -NAME - cpio -- copy files to and from archives - -SYNOPSIS - cpio {-i} [options] [pattern ...] [< archive] - cpio {-o} [options] < name-list [> archive] - cpio {-p} [options] dest-dir < name-list - -DESCRIPTION - cpio copies files between archives and directories. This implementation - can extract from tar, pax, cpio, zip, jar, ar, and ISO 9660 cdrom images - and can create tar, pax, cpio, ar, and shar archives. - - The first option to cpio is a mode indicator from the following list: - -i Input. Read an archive from standard input (unless overriden) - and extract the contents to disk or (if the -t option is speci- - fied) list the contents to standard output. If one or more file - patterns are specified, only files matching one of the patterns - will be extracted. - -o Output. Read a list of filenames from standard input and produce - a new archive on standard output (unless overriden) containing - the specified items. - -p Pass-through. Read a list of filenames from standard input and - copy the files to the specified directory. - -OPTIONS - Unless specifically stated otherwise, options are applicable in all oper- - ating modes. - - -A (o mode only) Append to the specified archive. (Not yet imple- - mented.) - - -a (o and p modes) Reset access times on files after they are read. - - -B (o mode only) Block output to records of 5120 bytes. - - -C size - (o mode only) Block output to records of size bytes. - - -c (o mode only) Use the old POSIX portable character format. - Equivalent to --format odc. - - -d (i and p modes) Create directories as necessary. - - -E file - (i mode only) Read list of file name patterns from file to list - and extract. - - -F file - Read archive from or write archive to file. - - -f pattern - (i mode only) Ignore files that match pattern. - - --format format - (o mode only) Produce the output archive in the specified format. - Supported formats include: - - cpio Synonym for odc. - newc The SVR4 portable cpio format. - odc The old POSIX.1 portable octet-oriented cpio format. - pax The POSIX.1 pax format, an extension of the ustar for- - mat. - ustar The POSIX.1 tar format. - - The default format is odc. See libarchive_formats(5) for more - complete information about the formats currently supported by the - underlying libarchive(3) library. - - -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. - - -L (o and p modes) All symbolic links will be followed. Normally, - symbolic links are archived and copied as symbolic links. With - this option, the target of the link will be archived or copied - instead. - - -l (p mode only) Create links from the target directory to the orig- - inal files, instead of copying. - - -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. - - -O file - Write archive to file. - - -o Output mode. See above for description. - - -p Pass-through mode. See above for description. - - --quiet - Suppress unnecessary messages. - - -R [user][:][group] - Set the owner and/or group on files in the output. If group is - specified with no user (for example, -R :wheel) then the group - will be set but not the user. If the user is specified with a - trailing colon and no group (for example, -R root:) then the - group will be set to the user's default group. If the user is - specified with no trailing colon, then the user will be set but - not the group. In -i and -p modes, this option can only be used - by the super-user. (For compatibility, a period can be used in - place of the colon.) - - -r (All modes.) Rename files interactively. For each file, a - prompt is written to /dev/tty containing the name of the file and - a line is read from /dev/tty. If the line read is blank, the - file is skipped. If the line contains a single period, the file - is processed normally. Otherwise, the line is taken to be the - new name of the file. - - -t (i mode only) List the contents of the archive to stdout; do not - restore the contents to disk. - - -u (i and p modes) Unconditionally overwrite existing files. Ordi- - narily, an older file will not overwrite a newer file on disk. - - -v Print the name of each file to stderr as it is processed. With - -t, provide a detailed listing of each file. - - --version - Print the program version information and exit. - - -y (o mode only) Compress the archive with bzip2-compatible compres- - sion before writing it. In input mode, this option is ignored; - bzip2 compression is recognized automatically on input. - - -Z (o mode only) Compress the archive with compress-compatible com- - pression before writing it. In input mode, this option is - ignored; compression is recognized automatically on input. - - -z (o mode only) Compress the archive with gzip-compatible compres- - sion before writing it. In input mode, this option is ignored; - gzip compression is recognized automatically on input. - -ENVIRONMENT - The following environment variables affect the execution of cpio: - - LANG The locale to use. See environ(7) for more information. - - TZ The timezone to use when displaying dates. See environ(7) for - more information. - -EXIT STATUS - The cpio utility exits 0 on success, and >0 if an error occurs. - -EXAMPLES - The cpio command is traditionally used to copy file heirarchies in con- - junction with the find(1) command. The first example here simply copies - all files from src to dest: - find src | cpio -pmud dest - - By carefully selecting options to the find(1) command and combining it - with other standard utilities, it is possible to exercise very fine con- - trol over which files are copied. This next example copies files from - src to dest that are more than 2 days old and whose names match a partic- - ular pattern: - find src -mtime +2 | grep foo[bar] | cpio -pdmu dest - - This example copies files from src to dest that are more than 2 days old - and which contain the word ``foobar'': - find src -mtime +2 | xargs grep -l foobar | cpio -pdmu dest - -COMPATIBILITY - The mode options i, o, and p and the options a, B, c, d, f, l, m, r, t, - u, and v comply with SUSv2. - - The old POSIX.1 standard specified that only -i, -o, and -p were inter- - preted as command-line options. Each took a single argument of a list of - modifier characters. For example, the standard syntax allows -imu but - does not support -miu or -i -m -u, since m and u are only modifiers to - -i, they are not command-line options in their own right. The syntax - supported by this implementation is backwards-compatible with the stan- - dard. For best compatibility, scripts should limit themselves to the - standard syntax. - -SEE ALSO - bzip2(1), tar(1), gzip(1), mt(1), pax(1), libarchive(3), cpio(5), - libarchive-formats(5), tar(5) - -STANDARDS - There is no current POSIX standard for the cpio command; it appeared in - ISO/IEC 9945-1:1996 (``POSIX.1'') but was dropped from IEEE Std - 1003.1-2001 (``POSIX.1''). - - The cpio, ustar, and pax interchange file formats are defined by IEEE Std - 1003.1-2001 (``POSIX.1'') for the pax command. - -HISTORY - The original cpio and find utilities were written by Dick Haight while - working in AT&T's Unix Support Group. They first appeared in 1977 in - PWB/UNIX 1.0, the ``Programmer's Work Bench'' system developed for use - within AT&T. They were first released outside of AT&T as part of System - III Unix in 1981. As a result, cpio actually predates tar, even though - it was not well-known outside of AT&T until some time later. - - This is a complete re-implementation based on the libarchive(3) library. - -BUGS - The cpio archive format has several basic limitations: It does not store - user and group names, only numbers. As a result, it cannot be reliably - used to transfer files between systems with dissimilar user and group - numbering. Older cpio formats limit the user and group numbers to 16 or - 18 bits, which is insufficient for modern systems. The cpio archive for- - mats cannot support files over 4 gigabytes, except for the ``odc'' vari- - ant, which can support files up to 8 gigabytes. - -FreeBSD 8.0 December 21, 2007 FreeBSD 8.0 diff --git a/libarchive/libarchive-2.7.1/doc/text/bsdtar.1.txt b/libarchive/libarchive-2.7.1/doc/text/bsdtar.1.txt deleted file mode 100644 index 0913a8a..0000000 --- a/libarchive/libarchive-2.7.1/doc/text/bsdtar.1.txt +++ /dev/null @@ -1,541 +0,0 @@ -BSDTAR(1) FreeBSD General Commands Manual BSDTAR(1) - -NAME - tar -- manipulate tape archives - -SYNOPSIS - tar [bundled-flags <args>] [<file> | <pattern> ...] - tar {-c} [options] [files | directories] - tar {-r | -u} -f archive-file [options] [files | directories] - tar {-t | -x} [options] [patterns] - -DESCRIPTION - tar creates and manipulates streaming archive files. This implementation - can extract from tar, pax, cpio, zip, jar, ar, and ISO 9660 cdrom images - and can create tar, pax, cpio, ar, and shar archives. - - The first synopsis form shows a ``bundled'' option word. This usage is - provided for compatibility with historical implementations. See COMPATI- - BILITY below for details. - - The other synopsis forms show the preferred usage. The first option to - tar is a mode indicator from the following list: - -c Create a new archive containing the specified items. - -r Like -c, but new entries are appended to the archive. Note that - this only works on uncompressed archives stored in regular files. - The -f option is required. - -t List archive contents to stdout. - -u Like -r, but new entries are added only if they have a modifica- - tion date newer than the corresponding entry in the archive. - Note that this only works on uncompressed archives stored in reg- - ular files. The -f option is required. - -x Extract to disk from the archive. If a file with the same name - appears more than once in the archive, each copy will be - extracted, with later copies overwriting (replacing) earlier - copies. - - In -c, -r, or -u mode, each specified file or directory is added to the - archive in the order specified on the command line. By default, the con- - tents of each directory are also archived. - - In extract or list mode, the entire command line is read and parsed - before the archive is opened. The pathnames or patterns on the command - line indicate which items in the archive should be processed. Patterns - are shell-style globbing patterns as documented in tcsh(1). - -OPTIONS - Unless specifically stated otherwise, options are applicable in all oper- - ating modes. - - @archive - (c and r mode only) The specified archive is opened and the - entries in it will be appended to the current archive. As a sim- - ple example, - tar -c -f - newfile @original.tar - writes a new archive to standard output containing a file newfile - and all of the entries from original.tar. In contrast, - tar -c -f - newfile original.tar - creates a new archive with only two entries. Similarly, - tar -czf - --format pax @- - reads an archive from standard input (whose format will be deter- - mined automatically) and converts it into a gzip-compressed pax- - format archive on stdout. In this way, tar can be used to con- - vert archives from one format to another. - - -b blocksize - Specify the block size, in 512-byte records, for tape drive I/O. - As a rule, this argument is only needed when reading from or - writing to tape drives, and usually not even then as the default - block size of 20 records (10240 bytes) is very common. - - -C directory - In c and r mode, this changes the directory before adding the - following files. In x mode, change directories after opening the - archive but before extracting entries from the archive. - - --check-links - (c and r modes only) Issue a warning message unless all links to - each file are archived. - - --chroot - (x mode only) chroot() to the current directory after processing - any -C options and before extracting any files. - - --exclude pattern - Do not process files or directories that match the specified pat- - tern. Note that exclusions take precedence over patterns or - filenames specified on the command line. - - --format format - (c, r, u mode only) Use the specified format for the created ar- - chive. Supported formats include ``cpio'', ``pax'', ``shar'', - and ``ustar''. Other formats may also be supported; see - libarchive-formats(5) for more information about currently-sup- - ported formats. In r and u modes, when extending an existing ar- - chive, the format specified here must be compatible with the for- - mat of the existing archive on disk. - - -f file - Read the archive from or write the archive to the specified file. - The filename can be - for standard input or standard output. If - not specified, the default tape device will be used. (On - FreeBSD, the default tape device is /dev/sa0.) - - -H (c and r mode only) Symbolic links named on the command line will - be followed; the target of the link will be archived, not the - link itself. - - -h (c and r mode only) Synonym for -L. - - -I Synonym for -T. - - --include pattern - Process only files or directories that match the specified pat- - tern. Note that exclusions specified with --exclude take prece- - dence over inclusions. If no inclusions are explicitly speci- - fied, all entries are processed by default. The --include option - is especially useful when filtering archives. For example, the - command - tar -c -f new.tar --include='*foo*' @old.tgz - creates a new archive new.tar containing only the entries from - old.tgz containing the string `foo'. - - -j (c mode only) Compress the resulting archive with bzip2(1). In - extract or list modes, this option is ignored. Note that, unlike - other tar implementations, this implementation recognizes bzip2 - compression automatically when reading archives. - - -k (x mode only) Do not overwrite existing files. In particular, if - a file appears more than once in an archive, later copies will - not overwrite earlier copies. - - --keep-newer-files - (x mode only) Do not overwrite existing files that are newer than - the versions appearing in the archive being extracted. - - -L (c and r mode only) All symbolic links will be followed. Nor- - mally, symbolic links are archived as such. With this option, - the target of the link will be archived instead. - - -l This is a synonym for the --check-links option. - - -m (x mode only) Do not extract modification time. By default, the - modification time is set to the time stored in the archive. - - -n (c, r, u modes only) Do not recursively archive the contents of - directories. - - --newer date - (c, r, u modes only) Only include files and directories newer - than the specified date. This compares ctime entries. - - --newer-mtime date - (c, r, u modes only) Like --newer, except it compares mtime - entries instead of ctime entries. - - --newer-than file - (c, r, u modes only) Only include files and directories newer - than the specified file. This compares ctime entries. - - --newer-mtime-than file - (c, r, u modes only) Like --newer-than, except it compares mtime - entries instead of ctime entries. - - --nodump - (c and r modes only) Honor the nodump file flag by skipping this - file. - - --null (use with -I, -T, or -X) Filenames or patterns are separated by - null characters, not by newlines. This is often used to read - filenames output by the -print0 option to find(1). - - --numeric-owner - (x mode only) Ignore symbolic user and group names when restoring - archives to disk, only numeric uid and gid values will be obeyed. - - -O (x, t modes only) In extract (-x) mode, files will be written to - standard out rather than being extracted to disk. In list (-t) - mode, the file listing will be written to stderr rather than the - usual stdout. - - -o (x mode) Use the user and group of the user running the program - rather than those specified in the archive. Note that this has - no significance unless -p is specified, and the program is being - run by the root user. In this case, the file modes and flags - from the archive will be restored, but ACLs or owner information - in the archive will be discarded. - - -o (c, r, u mode) A synonym for --format ustar - - --one-file-system - (c, r, and u modes) Do not cross mount points. - - --options options - Select optional behaviors for particular modules. The argument - is a text string containing comma-separated keywords and values. - These are passed to the modules that handle particular formats to - control how those formats will behave. Each option has one of - the following forms: - key=value - The key will be set to the specified value in every mod- - ule that supports it. Modules that do not support this - key will ignore it. - key The key will be enabled in every module that supports it. - This is equivalent to key=1. - !key The key will be disabled in every module that supports - it. - module:key=value, module:key, module:!key - As above, but the corresponding key and value will be - provided only to modules whose name matches module. - The currently supported modules and keys are: - iso9660:joliet - Support Joliet extensions. This is enabled by default, - use !joliet or iso9660:!joliet to disable. - gzip:compression-level - A decimal integer from 0 to 9 specifying the gzip com- - pression level. - xz:compression-level - A decimal integer from 0 to 9 specifying the xz compres- - sion level. - mtree:keyword - The mtree writer module allows you to specify which mtree - keywords will be included in the output. Supported key- - words include: cksum, device, flags, gid, gname, indent, - link, md5, mode, nlink, rmd160, sha1, sha256, sha384, - sha512, size, time, uid, uname. The default is equiva- - lent to: ``device, flags, gid, gname, link, mode, nlink, - size, time, type, uid, uname''. - mtree:all - Enables all of the above keywords. You can also use - mtree:!all to disable all keywords. - mtree:use-set - Enable generation of /set lines in the output. - mtree:indent - XXX need explanation XXX - If a provided option is not supported by any module, that is a - fatal error. - - -P Preserve pathnames. By default, absolute pathnames (those that - begin with a / character) have the leading slash removed both - when creating archives and extracting from them. Also, tar will - refuse to extract archive entries whose pathnames contain .. or - whose target directory would be altered by a symlink. This - option suppresses these behaviors. - - -p (x mode only) Preserve file permissions. Attempt to restore the - full permissions, including owner, file modes, file flags and - ACLs, if available, for each item extracted from the archive. By - default, newly-created files are owned by the user running tar, - the file mode is restored for newly-created regular files, and - all other types of entries receive default permissions. If tar - is being run by root, the default is to restore the owner unless - the -o option is also specified. - - -q (--fast-read) - (x and t mode only) Extract or list only the first archive entry - that matches each pattern or filename operand. Exit as soon as - each specified pattern or filename has been matched. By default, - the archive is always read to the very end, since there can be - multiple entries with the same name and, by convention, later - entries overwrite earlier entries. This option is provided as a - performance optimization. - - -S (x mode only) Extract files as sparse files. For every block on - disk, check first if it contains only NULL bytes and seek over it - otherwise. This works similiar to the conv=sparse option of dd. - - --strip-components count - (x mode only) Remove the specified number of leading path ele- - ments. Pathnames with fewer elements will be silently skipped. - Note that the pathname is edited after checking inclusion/exclu- - sion patterns but before security checks. - - -s pattern - Modify file or archive member names according to pattern. The - pattern has the format /old/new/[gps]. old is a basic regular - expression. If it doesn't apply, the pattern is skipped. new is - the replacement string of the matched part. ~ is substituted - with the match, 1 to 9 with the content of the corresponding cap- - tured 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 speci- - fied on the following line. Names are terminated by newlines - unless --null is specified. Note that --null also disables the - special handling of lines containing ``-C''. - - -U (x mode only) Unlink files before creating them. Without this - option, tar overwrites existing files, which preserves existing - hardlinks. With this option, existing hardlinks will be broken, - as will any symlink that would affect the location of an - extracted file. - - --use-compress-program program - Pipe the input (in x or t mode) or the output (in c mode) through - program instead of using the builtin compression support. - - -v Produce verbose output. In create and extract modes, tar will - list each file name as it is read from or written to the archive. - In list mode, tar will produce output similar to that of ls(1). - Additional -v options will provide additional detail. - - --version - Print version of tar and libarchive, and exit. - - -w Ask for confirmation for every action. - - -X filename - Read a list of exclusion patterns from the specified file. See - --exclude for more information about the handling of exclusions. - - -y (c mode only) Compress the resulting archive with bzip2(1). In - extract or list modes, this option is ignored. Note that, unlike - other tar implementations, this implementation recognizes bzip2 - compression automatically when reading archives. - - -z (c mode only) Compress the resulting archive with gzip(1). In - extract or list modes, this option is ignored. Note that, unlike - other tar implementations, this implementation recognizes gzip - compression automatically when reading archives. - - -Z (c mode only) Compress the resulting archive with compress(1). - In extract or list modes, this option is ignored. Note that, - unlike other tar implementations, this implementation recognizes - compress compression automatically when reading archives. - -ENVIRONMENT - The following environment variables affect the execution of tar: - - LANG The locale to use. See environ(7) for more information. - - TAPE The default tape device. The -f option overrides this. - - TZ The timezone to use when displaying dates. See environ(7) for - more information. - -FILES - /dev/sa0 The default tape device, if not overridden by the TAPE envi- - ronment variable or the -f option. - -EXIT STATUS - The tar utility exits 0 on success, and >0 if an error occurs. - -EXAMPLES - The following creates a new archive called file.tar.gz that contains two - files source.c and source.h: - tar -czf file.tar.gz source.c source.h - - To view a detailed table of contents for this archive: - tar -tvf file.tar.gz - - To extract all entries from the archive on the default tape drive: - tar -x - - To examine the contents of an ISO 9660 cdrom image: - tar -tf image.iso - - To move file hierarchies, invoke tar as - tar -cf - -C srcdir . | tar -xpf - -C destdir - or more traditionally - cd srcdir ; tar -cf - . | (cd destdir ; tar -xpf -) - - In create mode, the list of files and directories to be archived can also - include directory change instructions of the form -Cfoo/baz and archive - inclusions of the form @archive-file. For example, the command line - tar -c -f new.tar foo1 @old.tgz -C/tmp foo2 - will create a new archive new.tar. tar will read the file foo1 from the - current directory and add it to the output archive. It will then read - each entry from old.tgz and add those entries to the output archive. - Finally, it will switch to the /tmp directory and add foo2 to the output - archive. - - An input file in mtree(5) format can be used to create an output archive - with arbitrary ownership, permissions, or names that differ from existing - data on disk: - - $ cat input.mtree - #mtree - usr/bin uid=0 gid=0 mode=0755 type=dir - usr/bin/ls uid=0 gid=0 mode=0755 type=file content=myls - $ tar -cvf output.tar @input.mtree - - The --newer and --newer-mtime switches accept a variety of common date - and time specifications, including ``12 Mar 2005 7:14:29pm'', - ``2005-03-12 19:14'', ``5 minutes ago'', and ``19:14 PST May 1''. - - The --options argument can be used to control various details of archive - generation or reading. For example, you can generate mtree output which - only contains type, time, and uid keywords: - tar -cf file.tar --format=mtree --options='!all,type,time,uid' dir - or you can set the compression level used by gzip or xz compression: - tar -czf file.tar --options='compression-level=9'. - For more details, see the explanation of the archive_read_set_options() - and archive_write_set_options() API calls that are described in - archive_read(3) and archive_write(3). - -COMPATIBILITY - The bundled-arguments format is supported for compatibility with historic - implementations. It consists of an initial word (with no leading - char- - acter) in which each character indicates an option. Arguments follow as - separate words. The order of the arguments must match the order of the - corresponding characters in the bundled command word. For example, - tar tbf 32 file.tar - specifies three flags t, b, and f. The b and f flags both require argu- - ments, so there must be two additional items on the command line. The 32 - is the argument to the b flag, and file.tar is the argument to the f - flag. - - The mode options c, r, t, u, and x and the options b, f, l, m, o, v, and - w comply with SUSv2. - - For maximum portability, scripts that invoke tar should use the bundled- - argument format above, should limit themselves to the c, t, and x modes, - and the b, f, m, v, and w options. - - Additional long options are provided to improve compatibility with other - tar implementations. - -SECURITY - Certain security issues are common to many archiving programs, including - tar. In particular, carefully-crafted archives can request that tar - extract files to locations outside of the target directory. This can - potentially be used to cause unwitting users to overwrite files they did - not intend to overwrite. If the archive is being extracted by the supe- - ruser, any file on the system can potentially be overwritten. There are - three ways this can happen. Although tar has mechanisms to protect - against each one, savvy users should be aware of the implications: - - o Archive entries can have absolute pathnames. By default, tar - removes the leading / character from filenames before restoring - them to guard against this problem. - - o Archive entries can have pathnames that include .. components. - By default, tar will not extract files containing .. components - in their pathname. - - o Archive entries can exploit symbolic links to restore files to - other directories. An archive can restore a symbolic link to - another directory, then use that link to restore a file into that - directory. To guard against this, tar checks each extracted path - for symlinks. If the final path element is a symlink, it will be - removed and replaced with the archive entry. If -U is specified, - any intermediate symlink will also be unconditionally removed. - If neither -U nor -P is specified, tar will refuse to extract the - entry. - To protect yourself, you should be wary of any archives that come from - untrusted sources. You should examine the contents of an archive with - tar -tf filename - before extraction. You should use the -k option to ensure that tar will - not overwrite any existing files or the -U option to remove any pre- - existing files. You should generally not extract archives while running - with super-user privileges. Note that the -P option to tar disables the - security checks above and allows you to extract an archive while preserv- - ing any absolute pathnames, .. components, or symlinks to other directo- - ries. - -SEE ALSO - bzip2(1), compress(1), cpio(1), gzip(1), mt(1), pax(1), shar(1), - libarchive(3), libarchive-formats(5), tar(5) - -STANDARDS - There is no current POSIX standard for the tar command; it appeared in - ISO/IEC 9945-1:1996 (``POSIX.1'') but was dropped from IEEE Std - 1003.1-2001 (``POSIX.1''). The options used by this implementation were - developed by surveying a number of existing tar implementations as well - as the old POSIX specification for tar and the current POSIX specifica- - tion for pax. - - The ustar and pax interchange file formats are defined by IEEE Std - 1003.1-2001 (``POSIX.1'') for the pax command. - -HISTORY - A tar command appeared in Seventh Edition Unix, which was released in - January, 1979. There have been numerous other implementations, many of - which extended the file format. John Gilmore's pdtar public-domain - implementation (circa November, 1987) was quite influential, and formed - the basis of GNU tar. GNU tar was included as the standard system tar in - FreeBSD beginning with FreeBSD 1.0. - - This is a complete re-implementation based on the libarchive(3) library. - -BUGS - This program follows ISO/IEC 9945-1:1996 (``POSIX.1'') for the definition - of the -l option. Note that GNU tar prior to version 1.15 treated -l as - a synonym for the --one-file-system option. - - The -C dir option may differ from historic implementations. - - All archive output is written in correctly-sized blocks, even if the out- - put is being compressed. Whether or not the last output block is padded - to a full block size varies depending on the format and the output - device. For tar and cpio formats, the last block of output is padded to - a full block size if the output is being written to standard output or to - a character or block device such as a tape drive. If the output is being - written to a regular file, the last block will not be padded. Many com- - pressors, including gzip(1) and bzip2(1), complain about the null padding - when decompressing an archive created by tar, although they still extract - it correctly. - - The compression and decompression is implemented internally, so there may - be insignificant differences between the compressed output generated by - tar -czf - file - and that generated by - tar -cf - file | gzip - - The default should be to read and write archives to the standard I/O - paths, but tradition (and POSIX) dictates otherwise. - - The r and u modes require that the archive be uncompressed and located in - a regular file on disk. Other archives can be modified using c mode with - the @archive-file extension. - - To archive a file called @foo or -foo you must specify it as ./@foo or - ./-foo, respectively. - - In create mode, a leading ./ is always removed. A leading / is stripped - unless the -P option is specified. - - There needs to be better support for file selection on both create and - extract. - - There is not yet any support for multi-volume archives or for archiving - sparse files. - - Converting between dissimilar archive formats (such as tar and cpio) - using the @- convention can cause hard link information to be lost. - (This is a consequence of the incompatible ways that different archive - formats store hardlink information.) - - There are alternative long options for many of the short options that are - deliberately not documented. - -FreeBSD 8.0 March 25, 2009 FreeBSD 8.0 diff --git a/libarchive/libarchive-2.7.1/doc/text/cpio.5.txt b/libarchive/libarchive-2.7.1/doc/text/cpio.5.txt deleted file mode 100644 index 5ece811..0000000 --- a/libarchive/libarchive-2.7.1/doc/text/cpio.5.txt +++ /dev/null @@ -1,235 +0,0 @@ -CPIO(5) FreeBSD File Formats Manual CPIO(5) - -NAME - cpio -- format of cpio archive files - -DESCRIPTION - The cpio archive format collects any number of files, directories, and - other file system objects (symbolic links, device nodes, etc.) into a - single stream of bytes. - - General Format - Each file system object in a cpio archive comprises a header record with - basic numeric metadata followed by the full pathname of the entry and the - file data. The header record stores a series of integer values that gen- - erally follow the fields in struct stat. (See stat(2) for details.) The - variants differ primarily in how they store those integers (binary, - octal, or hexadecimal). The header is followed by the pathname of the - entry (the length of the pathname is stored in the header) and any file - data. The end of the archive is indicated by a special record with the - pathname ``TRAILER!!!''. - - PWB format - XXX Any documentation of the original PWB/UNIX 1.0 format? XXX - - Old Binary Format - The old binary cpio format stores numbers as 2-byte and 4-byte binary - values. Each entry begins with a header in the following format: - - struct header_old_cpio { - unsigned short c_magic; - unsigned short c_dev; - unsigned short c_ino; - unsigned short c_mode; - unsigned short c_uid; - unsigned short c_gid; - unsigned short c_nlink; - unsigned short c_rdev; - unsigned short c_mtime[2]; - unsigned short c_namesize; - unsigned short c_filesize[2]; - }; - - The unsigned short fields here are 16-bit integer values; the unsigned - int fields are 32-bit integer values. The fields are as follows - - magic The integer value octal 070707. This value can be used to deter- - mine whether this archive is written with little-endian or big- - endian integers. - - dev, ino - The device and inode numbers from the disk. These are used by - programs that read cpio archives to determine when two entries - refer to the same file. Programs that synthesize cpio archives - should be careful to set these to distinct values for each entry. - - mode The mode specifies both the regular permissions and the file - type. It consists of several bit fields as follows: - 0170000 This masks the file type bits. - 0140000 File type value for sockets. - 0120000 File type value for symbolic links. For symbolic links, - the link body is stored as file data. - 0100000 File type value for regular files. - 0060000 File type value for block special devices. - 0040000 File type value for directories. - 0020000 File type value for character special devices. - 0010000 File type value for named pipes or FIFOs. - 0004000 SUID bit. - 0002000 SGID bit. - 0001000 Sticky bit. On some systems, this modifies the behavior - of executables and/or directories. - 0000777 The lower 9 bits specify read/write/execute permissions - for world, group, and user following standard POSIX con- - ventions. - - uid, gid - The numeric user id and group id of the owner. - - nlink The number of links to this file. Directories always have a - value of at least two here. Note that hardlinked files include - file data with every copy in the archive. - - rdev For block special and character special entries, this field con- - tains the associated device number. For all other entry types, - it should be set to zero by writers and ignored by readers. - - mtime Modification time of the file, indicated as the number of seconds - since the start of the epoch, 00:00:00 UTC January 1, 1970. The - four-byte integer is stored with the most-significant 16 bits - first followed by the least-significant 16 bits. Each of the two - 16 bit values are stored in machine-native byte order. - - namesize - The number of bytes in the pathname that follows the header. - This count includes the trailing NUL byte. - - filesize - The size of the file. Note that this archive format is limited - to four gigabyte file sizes. See mtime above for a description - of the storage of four-byte integers. - - The pathname immediately follows the fixed header. If the namesize is - odd, an additional NUL byte is added after the pathname. The file data - is then appended, padded with NUL bytes to an even length. - - Hardlinked files are not given special treatment; the full file contents - are included with each copy of the file. - - Portable ASCII Format - Version 2 of the Single UNIX Specification (``SUSv2'') standardized an - ASCII variant that is portable across all platforms. It is commonly - known as the ``old character'' format or as the ``odc'' format. It - stores the same numeric fields as the old binary format, but represents - them as 6-character or 11-character octal values. - - struct cpio_odc_header { - char c_magic[6]; - char c_dev[6]; - char c_ino[6]; - char c_mode[6]; - char c_uid[6]; - char c_gid[6]; - char c_nlink[6]; - char c_rdev[6]; - char c_mtime[11]; - char c_namesize[6]; - char c_filesize[11]; - }; - - The fields are identical to those in the old binary format. The name and - file body follow the fixed header. Unlike the old binary format, there - is no additional padding after the pathname or file contents. If the - files being archived are themselves entirely ASCII, then the resulting - archive will be entirely ASCII, except for the NUL byte that terminates - the name field. - - New ASCII Format - The "new" ASCII format uses 8-byte hexadecimal fields for all numbers and - separates device numbers into separate fields for major and minor num- - bers. - - struct cpio_newc_header { - char c_magic[6]; - char c_ino[8]; - char c_mode[8]; - char c_uid[8]; - char c_gid[8]; - char c_nlink[8]; - char c_mtime[8]; - char c_filesize[8]; - char c_devmajor[8]; - char c_devminor[8]; - char c_rdevmajor[8]; - char c_rdevminor[8]; - char c_namesize[8]; - char c_check[8]; - }; - - Except as specified below, the fields here match those specified for the - old binary format above. - - magic The string ``070701''. - - check This field is always set to zero by writers and ignored by read- - ers. See the next section for more details. - - The pathname is followed by NUL bytes so that the total size of the fixed - header plus pathname is a multiple of four. Likewise, the file data is - padded to a multiple of four bytes. Note that this format supports only - 4 gigabyte files (unlike the older ASCII format, which supports 8 giga- - byte files). - - In this format, hardlinked files are handled by setting the filesize to - zero for each entry except the last one that appears in the archive. - - New CRC Format - The CRC format is identical to the new ASCII format described in the pre- - vious section except that the magic field is set to ``070702'' and the - check field is set to the sum of all bytes in the file data. This sum is - computed treating all bytes as unsigned values and using unsigned arith- - metic. Only the least-significant 32 bits of the sum are stored. - - HP variants - The cpio implementation distributed with HPUX used XXXX but stored device - numbers differently XXX. - - Other Extensions and Variants - Sun Solaris uses additional file types to store extended file data, - including ACLs and extended attributes, as special entries in cpio ar- - chives. - - XXX Others? XXX - -BUGS - The ``CRC'' format is mis-named, as it uses a simple checksum and not a - cyclic redundancy check. - - The old binary format is limited to 16 bits for user id, group id, - device, and inode numbers. It is limited to 4 gigabyte file sizes. - - The old ASCII format is limited to 18 bits for the user id, group id, - device, and inode numbers. It is limited to 8 gigabyte file sizes. - - The new ASCII format is limited to 4 gigabyte file sizes. - - None of the cpio formats store user or group names, which are essential - when moving files between systems with dissimilar user or group number- - ing. - - Especially when writing older cpio variants, it may be necessary to map - actual device/inode values to synthesized values that fit the available - fields. With very large filesystems, this may be necessary even for the - newer formats. - -SEE ALSO - cpio(1), tar(5) - -STANDARDS - The cpio utility is no longer a part of POSIX or the Single Unix Stan- - dard. It last appeared in Version 2 of the Single UNIX Specification - (``SUSv2''). It has been supplanted in subsequent standards by pax(1). - The portable ASCII format is currently part of the specification for the - pax(1) utility. - -HISTORY - The original cpio utility was written by Dick Haight while working in - AT&T's Unix Support Group. It appeared in 1977 as part of PWB/UNIX 1.0, - the ``Programmer's Work Bench'' derived from Version 6 AT&T UNIX that was - used internally at AT&T. Both the old binary and old character formats - were in use by 1980, according to the System III source released by SCO - under their ``Ancient Unix'' license. The character format was adopted - as part of IEEE Std 1003.1-1988 (``POSIX.1''). XXX when did "newc" - appear? Who invented it? When did HP come out with their variant? When - did Sun introduce ACLs and extended attributes? XXX - -FreeBSD 8.0 October 5, 2007 FreeBSD 8.0 diff --git a/libarchive/libarchive-2.7.1/doc/text/libarchive-formats.5.txt b/libarchive/libarchive-2.7.1/doc/text/libarchive-formats.5.txt deleted file mode 100644 index 0692ac7..0000000 --- a/libarchive/libarchive-2.7.1/doc/text/libarchive-formats.5.txt +++ /dev/null @@ -1,186 +0,0 @@ -libarchive-formats(3) FreeBSD Library Functions Manual libarchive-formats(3) - -NAME - libarchive-formats -- archive formats supported by the libarchive library - -DESCRIPTION - The libarchive(3) library reads and writes a variety of streaming archive - formats. Generally speaking, all of these archive formats consist of a - series of ``entries''. Each entry stores a single file system object, - such as a file, directory, or symbolic link. - - The following provides a brief description of each format supported by - libarchive, with some information about recognized extensions or limita- - tions of the current library support. Note that just because a format is - supported by libarchive does not imply that a program that uses - libarchive will support that format. Applications that use libarchive - specify which formats they wish to support. - - 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. The pres- - ence of this additional entry 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 Uni- - code strings. Keywords defined in the standard are in all lower- - case; vendors are allowed to define custom keys by preceding them - with the vendor name in all uppercase. When writing pax ar- - chives, libarchive uses many of the SCHILY keys defined by Joerg - Schilling's ``star'' archiver. The libarchive library can read - most of the SCHILY keys. 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 pos- - sible. The result will be identical to a ustar archive unless - the extended attributes entry is required to store a long file - name, long linkname, extended ACL, file flags, or if any of the - standard ustar data (user name, group name, UID, GID, etc) cannot - be fully represented in the ustar header. In all cases, the - result can be dearchived by any program that can read POSIX-com- - pliant pax interchange format archives. Programs that correctly - read ustar format (see below) will also be able to read this for- - mat; any extended attributes will be extracted as separate files - stored in PaxHeader directories. - - ustar The libarchive library can both read and write this format. This - format has the following limitations: - o Device major and minor numbers are limited to 21 bits. Nodes - with larger numbers will not be added to the archive. - o Path names in the archive are limited to 255 bytes. (Shorter - if there is no / character in exactly the right place.) - o Symbolic links and hard links are stored in the archive with - the name of the referenced file. This name is limited to 100 - bytes. - o Extended attributes, file flags, and other extended security - information cannot be stored. - o Archive entries are limited to 2 gigabytes in size. - Note that the pax interchange format has none of these restric- - tions. - - The libarchive library can also read a variety of commonly-used exten- - sions to the basic tar format. In particular, it supports base-256 val- - ues in certain numeric fields. This essentially removes the limitations - on file size, modification time, and device numbers. - - 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 tar, cpio does only minimal padding of the - header or file data. There are a variety of cpio formats, 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 can read both big-endian and little-endian - variants of the original binary cpio format. This format used - 32-bit binary values for file size and mtime, and 16-bit binary - values for the other fields. - - odc The libarchive library can both read and write this POSIX-stan- - dard format. This format stores the header contents as octal - values in ASCII. It is standard, portable, and immune from byte- - order confusion. File sizes and mtime are limited to 33 bits - (8GB file size), other fields are limited to 18 bits. - - SVR4 The libarchive library can read both CRC and non-CRC variants of - this format. The SVR4 format uses eight-digit hexadecimal values - for all header fields. This limits file size to 4GB, and also - limits the mtime and other fields to 32 bits. The SVR4 format - can optionally include a CRC of the file contents, although - libarchive does not currently verify this CRC. - - Cpio first appeared in PWB/UNIX 1.0, which was released within AT&T in - 1977. PWB/UNIX 1.0 formed the basis of System III Unix, released outside - of AT&T in 1981. This makes cpio older than tar, although cpio was not - included in Version 7 AT&T Unix. As a result, the tar command became - much better known in universities and research groups that used Version - 7. The combination of the find and cpio utilities provided very precise - control over file selection. Unfortunately, the format has many limita- - tions that make it unsuitable for widespread use. Only the POSIX format - permits files over 4GB, and its 18-bit limit for most other fields makes - it unsuitable for modern systems. In addition, cpio formats only store - numeric UID/GID values (not usernames and group names), which can make it - very difficult to correctly transfer archives across systems with dissim- - ilar user numbering. - - Shar Formats - A ``shell archive'' is a shell script that, when executed on a POSIX-com- - pliant system, will recreate a collection of file system objects. The - libarchive library can write two different kinds of shar archives: - - shar The traditional shar format uses a limited set of POSIX commands, - including echo(1), mkdir(1), and sed(1). It is suitable for - portably archiving small collections of plain text files. How- - ever, it is not generally well-suited for large archives (many - implementations of sh(1) have limits on the size of a script) nor - should it be used with non-text files. - - shardump - This format is similar to shar but encodes files using - uuencode(1) so that the result will be a plain text file regard- - less of the file contents. It also includes additional shell - commands that attempt to reproduce as many file attributes as - possible, including owner, mode, and flags. The additional com- - mands used to restore file attributes make shardump archives less - portable than plain shar archives. - - ISO9660 format - Libarchive can read and extract from files containing ISO9660-compliant - CDROM images. It also has partial support for Rockridge extensions. In - many cases, this can remove the need to burn a physical CDROM. It also - avoids security and complexity issues that come with virtual mounts and - loopback devices. - - Zip format - Libarchive can extract from most zip format archives. It currently only - supports uncompressed entries and entries compressed with the ``deflate'' - algorithm. Older zip compression algorithms are not supported. - - Archive (library) file format - The Unix archive format (commonly created by the ar(1) archiver) is a - general-purpose format which is used almost exclusively for object files - to be read by the link editor ld(1). The ar format has never been stan- - dardised. There are two common variants: the GNU format derived from - SVR4, and the BSD format, which first appeared in 4.4BSD. Libarchive - provides read and write support for both variants. - - mtree - Libarchive can read files in mtree(5) format. This format is not a true - archive format, but rather a description of a file hierarchy. When - requested, libarchive obtains the contents of the files described by the - mtree(5) format from files on disk instead. - -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 April 27, 2004 FreeBSD 8.0 diff --git a/libarchive/libarchive-2.7.1/doc/text/libarchive.3.txt b/libarchive/libarchive-2.7.1/doc/text/libarchive.3.txt deleted file mode 100644 index f00d977..0000000 --- a/libarchive/libarchive-2.7.1/doc/text/libarchive.3.txt +++ /dev/null @@ -1,185 +0,0 @@ -LIBARCHIVE(3) FreeBSD Library Functions Manual LIBARCHIVE(3) - -NAME - libarchive -- functions for reading and writing streaming archives - -LIBRARY - Streaming Archive Library (libarchive, -larchive) - -OVERVIEW - The libarchive library provides a flexible interface for reading and - writing streaming archive files such as tar and cpio. The library is - inherently stream-oriented; readers serially iterate through the archive, - writers serially add things to the archive. In particular, note that - there is no built-in support for random access nor for in-place modifica- - tion. - - When reading an archive, the library automatically detects the format and - the compression. The library currently has read support for: - o old-style tar archives, - o most variants of the POSIX ``ustar'' format, - o the POSIX ``pax interchange'' format, - o GNU-format tar archives, - o most common cpio archive formats, - o ISO9660 CD images (with or without RockRidge extensions), - o Zip archives. - The library automatically detects archives compressed with gzip(1), - bzip2(1), or compress(1) and decompresses them transparently. - - When writing an archive, you can specify the compression to be used and - the format to use. The library can write - o POSIX-standard ``ustar'' archives, - o POSIX ``pax interchange format'' archives, - o POSIX octet-oriented cpio archives, - o two different variants of shar archives. - Pax interchange format is an extension of the tar archive format that - eliminates essentially all of the limitations of historic tar formats in - a standard fashion that is supported by POSIX-compliant pax(1) implemen- - tations on many systems as well as several newer implementations of - tar(1). Note that the default write format will suppress the pax - extended attributes for most entries; explicitly requesting pax format - will enable those attributes for all entries. - - The read and write APIs are accessed through the archive_read_XXX() func- - tions and the archive_write_XXX() functions, respectively, and either can - be used independently of the other. - - The rest of this manual page provides an overview of the library opera- - tion. More detailed information can be found in the individual manual - pages for each API or utility function. - -READING AN ARCHIVE - To read an archive, you must first obtain an initialized struct archive - object from archive_read_new(). You can then modify this object for the - desired operations with the various archive_read_set_XXX() and - archive_read_support_XXX() functions. In particular, you will need to - invoke appropriate archive_read_support_XXX() functions to enable the - corresponding compression and format support. Note that these latter - functions perform two distinct operations: they cause the corresponding - support code to be linked into your program, and they enable the corre- - sponding auto-detect code. Unless you have specific constraints, you - will generally want to invoke archive_read_support_compression_all() and - archive_read_support_format_all() to enable auto-detect for all formats - and compression types currently supported by the library. - - Once you have prepared the struct archive object, you call - archive_read_open() to actually open the archive and prepare it for read- - ing. There are several variants of this function; the most basic expects - you to provide pointers to several functions that can provide blocks of - bytes from the archive. There are convenience forms that allow you to - specify a filename, file descriptor, FILE * object, or a block of memory - from which to read the archive data. Note that the core library makes no - assumptions about the size of the blocks read; callback functions are - free to read whatever block size is most appropriate for the medium. - - Each archive entry consists of a header followed by a certain amount of - data. You can obtain the next header with archive_read_next_header(), - which returns a pointer to an struct archive_entry structure with infor- - mation about the current archive element. If the entry is a regular - file, then the header will be followed by the file data. You can use - archive_read_data() (which works much like the read(2) system call) to - read this data from the archive. You may prefer to use the higher-level - archive_read_data_skip(), which reads and discards the data for this - entry, archive_read_data_to_buffer(), which reads the data into an in- - memory buffer, archive_read_data_to_file(), which copies the data to the - provided file descriptor, or archive_read_extract(), which recreates the - specified entry on disk and copies data from the archive. In particular, - note that archive_read_extract() uses the struct archive_entry structure - that you provide it, which may differ from the entry just read from the - archive. In particular, many applications will want to override the - pathname, file permissions, or ownership. - - Once you have finished reading data from the archive, you should call - archive_read_close() to close the archive, then call - archive_read_finish() to release all resources, including all memory - allocated by the library. - - The archive_read(3) manual page provides more detailed calling informa- - tion for this API. - -WRITING AN ARCHIVE - You use a similar process to write an archive. The archive_write_new() - function creates an archive object useful for writing, the various - archive_write_set_XXX() functions are used to set parameters for writing - the archive, and archive_write_open() completes the setup and opens the - archive for writing. - - Individual archive entries are written in a three-step process: You first - initialize a struct archive_entry structure with information about the - new entry. At a minimum, you should set the pathname of the entry and - provide a struct stat with a valid st_mode field, which specifies the - type of object and st_size field, which specifies the size of the data - portion of the object. The archive_write_header() function actually - writes the header data to the archive. You can then use - archive_write_data() to write the actual data. - - After all entries have been written, use the archive_write_finish() func- - tion to release all resources. - - The archive_write(3) manual page provides more detailed calling informa- - tion for this API. - -DESCRIPTION - Detailed descriptions of each function are provided by the corresponding - manual pages. - - All of the functions utilize an opaque struct archive datatype that pro- - vides access to the archive contents. - - The struct archive_entry structure contains a complete description of a - single archive entry. It uses an opaque interface that is fully docu- - mented in archive_entry(3). - - Users familiar with historic formats should be aware that the newer vari- - ants have eliminated most restrictions on the length of textual fields. - Clients should not assume that filenames, link names, user names, or - group names are limited in length. In particular, pax interchange format - can easily accommodate pathnames in arbitrary character sets that exceed - PATH_MAX. - -RETURN VALUES - Most functions return zero on success, non-zero on error. The return - value indicates the general severity of the error, ranging from - ARCHIVE_WARN, which indicates a minor problem that should probably be - reported to the user, to ARCHIVE_FATAL, which indicates a serious problem - that will prevent any further operations on this archive. On error, the - archive_errno() function can be used to retrieve a numeric error code - (see errno(2)). The archive_error_string() returns a textual error mes- - sage suitable for display. - - archive_read_new() and archive_write_new() return pointers to an allo- - cated and initialized struct archive object. - - archive_read_data() and archive_write_data() return a count of the number - of bytes actually read or written. A value of zero indicates the end of - the data for this entry. A negative value indicates an error, in which - case the archive_errno() and archive_error_string() functions can be used - to obtain more information. - -ENVIRONMENT - There are character set conversions within the archive_entry(3) functions - that are impacted by the currently-selected locale. - -SEE ALSO - tar(1), archive_entry(3), archive_read(3), archive_util(3), - archive_write(3), tar(5) - -HISTORY - The libarchive library first appeared in FreeBSD 5.3. - -AUTHORS - The libarchive library was written by Tim Kientzle <kientzle@acm.org>. - -BUGS - Some archive formats support information that is not supported by struct - archive_entry. Such information cannot be fully archived or restored - using this library. This includes, for example, comments, character - sets, or the arbitrary key/value pairs that can appear in pax interchange - format archives. - - Conversely, of course, not all of the information that can be stored in - an struct archive_entry is supported by all formats. For example, cpio - formats do not support nanosecond timestamps; old tar formats do not sup- - port large device numbers. - -FreeBSD 8.0 August 19, 2006 FreeBSD 8.0 diff --git a/libarchive/libarchive-2.7.1/doc/text/libarchive_internals.3.txt b/libarchive/libarchive-2.7.1/doc/text/libarchive_internals.3.txt deleted file mode 100644 index e5e65bd..0000000 --- a/libarchive/libarchive-2.7.1/doc/text/libarchive_internals.3.txt +++ /dev/null @@ -1,248 +0,0 @@ -LIBARCHIVE(3) FreeBSD Library Functions Manual LIBARCHIVE(3) - -NAME - libarchive_internals -- description of libarchive internal interfaces - -OVERVIEW - The libarchive library provides a flexible interface for reading and - writing streaming archive files such as tar and cpio. Internally, it - follows a modular layered design that should make it easy to add new ar- - chive and compression formats. - -GENERAL ARCHITECTURE - Externally, libarchive exposes most operations through an opaque, object- - style interface. The archive_entry(1) objects store information about a - single filesystem object. The rest of the library provides facilities to - write archive_entry(1) objects to archive files, read them from archive - files, and write them to disk. (There are plans to add a facility to - read archive_entry(1) objects from disk as well.) - - The read and write APIs each have four layers: a public API layer, a for- - mat layer that understands the archive file format, a compression layer, - and an I/O layer. The I/O layer is completely exposed to clients who can - replace it entirely with their own functions. - - In order to provide as much consistency as possible for clients, some - public functions are virtualized. Eventually, it should be possible for - clients to open an archive or disk writer, and then use a single set of - code to select and write entries, regardless of the target. - -READ ARCHITECTURE - From the outside, clients use the archive_read(3) API to manipulate an - archive object to read entries and bodies from an archive stream. Inter- - nally, the archive object is cast to an archive_read object, which holds - all read-specific data. The API has four layers: The lowest layer is the - I/O layer. This layer can be overridden by clients, but most clients use - the packaged I/O callbacks provided, for example, by - archive_read_open_memory(3), and archive_read_open_fd(3). The compres- - sion layer calls the I/O layer to read bytes and decompresses them for - the format layer. The format layer unpacks a stream of uncompressed - bytes and creates archive_entry objects from the incoming data. The API - layer tracks overall state (for example, it prevents clients from reading - data before reading a header) and invokes the format and compression - layer operations through registered function pointers. In particular, - the API layer drives the format-detection process: When opening the ar- - chive, it reads an initial block of data and offers it to each registered - compression handler. The one with the highest bid is initialized with - the first block. Similarly, the format handlers are polled to see which - handler is the best for each archive. (Prior to 2.4.0, the format bid- - ders were invoked for each entry, but this design hindered error recov- - ery.) - - I/O Layer and Client Callbacks - The read API goes to some lengths to be nice to clients. As a result, - there are few restrictions on the behavior of the client callbacks. - - The client read callback is expected to provide a block of data on each - call. A zero-length return does indicate end of file, but otherwise - blocks may be as small as one byte or as large as the entire file. In - particular, blocks may be of different sizes. - - The client skip callback returns the number of bytes actually skipped, - which may be much smaller than the skip requested. The only requirement - is that the skip not be larger. In particular, clients are allowed to - return zero for any skip that they don't want to handle. The skip call- - back must never be invoked with a negative value. - - Keep in mind that not all clients are reading from disk: clients reading - from networks may provide different-sized blocks on every request and - cannot skip at all; advanced clients may use mmap(2) to read the entire - file into memory at once and return the entire file to libarchive as a - single block; other clients may begin asynchronous I/O operations for the - next block on each request. - - Decompresssion Layer - The decompression layer not only handles decompression, it also buffers - data so that the format handlers see a much nicer I/O model. The decom- - pression API is a two stage peek/consume model. A read_ahead request - specifies a minimum read amount; the decompression layer must provide a - pointer to at least that much data. If more data is immediately avail- - able, it should return more: the format layer handles bulk data reads by - asking for a minimum of one byte and then copying as much data as is - available. - - A subsequent call to the consume() function advances the read pointer. - Note that data returned from a read_ahead() call is guaranteed to remain - in place until the next call to read_ahead(). Intervening calls to - consume() should not cause the data to move. - - Skip requests must always be handled exactly. Decompression handlers - that cannot seek forward should not register a skip handler; the API - layer fills in a generic skip handler that reads and discards data. - - A decompression handler has a specific lifecycle: - Registration/Configuration - When the client invokes the public support function, the decom- - pression handler invokes the internal - __archive_read_register_compression() function to provide bid and - initialization functions. This function returns NULL on error or - else a pointer to a struct decompressor_t. This structure con- - tains a void * config slot that can be used for storing any cus- - tomization information. - Bid The bid function is invoked with a pointer and size of a block of - data. The decompressor can access its config data through the - decompressor element of the archive_read object. The bid func- - tion is otherwise stateless. In particular, it must not perform - any I/O operations. - - The value returned by the bid function indicates its suitability - for handling this data stream. A bid of zero will ensure that - this decompressor is never invoked. Return zero if magic number - checks fail. Otherwise, your initial implementation should - return the number of bits actually checked. For example, if you - verify two full bytes and three bits of another byte, bid 19. - Note that the initial block may be very short; be careful to only - inspect the data you are given. (The current decompressors - require two bytes for correct bidding.) - Initialize - The winning bidder will have its init function called. This - function should initialize the remaining slots of the struct - decompressor_t object pointed to by the decompressor element of - the archive_read object. In particular, it should allocate any - working data it needs in the data slot of that structure. The - init function is called with the block of data that was used for - tasting. At this point, the decompressor is responsible for all - I/O requests to the client callbacks. The decompressor is free - to read more data as and when necessary. - Satisfy I/O requests - The format handler will invoke the read_ahead, consume, and skip - functions as needed. - Finish The finish method is called only once when the archive is closed. - It should release anything stored in the data and config slots of - the decompressor object. It should not invoke the client close - callback. - - Format Layer - The read formats have a similar lifecycle to the decompression handlers: - Registration - Allocate your private data and initialize your pointers. - Bid Formats bid by invoking the read_ahead() decompression method but - not calling the consume() method. This allows each bidder to - look ahead in the input stream. Bidders should not look further - ahead than necessary, as long look aheads put pressure on the - decompression layer to buffer lots of data. Most formats only - require a few hundred bytes of look ahead; look aheads of a few - kilobytes are reasonable. (The ISO9660 reader sometimes looks - ahead by 48k, which should be considered an upper limit.) - Read header - The header read is usually the most complex part of any format. - There are a few strategies worth mentioning: For formats such as - tar or cpio, reading and parsing the header is straightforward - since headers alternate with data. For formats that store all - header data at the beginning of the file, the first header read - request may have to read all headers into memory and store that - data, sorted by the location of the file data. Subsequent header - read requests will skip forward to the beginning of the file data - and return the corresponding header. - Read Data - The read data interface supports sparse files; this requires that - each call return a block of data specifying the file offset and - size. This may require you to carefully track the location so - that you can return accurate file offsets for each read. Remem- - ber that the decompressor will return as much data as it has. - Generally, you will want to request one byte, examine the return - value to see how much data is available, and possibly trim that - to the amount you can use. You should invoke consume for each - block just before you return it. - Skip All Data - The skip data call should skip over all file data and trailing - padding. This is called automatically by the API layer just - before each header read. It is also called in response to the - client calling the public data_skip() function. - Cleanup - On cleanup, the format should release all of its allocated mem- - ory. - - API Layer - XXX to do XXX - -WRITE ARCHITECTURE - The write API has a similar set of four layers: an API layer, a format - layer, a compression layer, and an I/O layer. The registration here is - much simpler because only one format and one compression can be regis- - tered at a time. - - I/O Layer and Client Callbacks - XXX To be written XXX - - Compression Layer - XXX To be written XXX - - Format Layer - XXX To be written XXX - - API Layer - XXX To be written XXX - -WRITE_DISK ARCHITECTURE - The write_disk API is intended to look just like the write API to - clients. Since it does not handle multiple formats or compression, it is - not layered internally. - -GENERAL SERVICES - The archive_read, archive_write, and archive_write_disk objects all con- - tain an initial archive object which provides common support for a set of - standard services. (Recall that ANSI/ISO C90 guarantees that you can - cast freely between a pointer to a structure and a pointer to the first - element of that structure.) The archive object has a magic value that - indicates which API this object is associated with, slots for storing - error information, and function pointers for virtualized API functions. - -MISCELLANEOUS NOTES - Connecting existing archiving libraries into libarchive is generally - quite difficult. In particular, many existing libraries strongly assume - that you are reading from a file; they seek forwards and backwards as - necessary to locate various pieces of information. In contrast, - libarchive never seeks backwards in its input, which sometimes requires - very different approaches. - - For example, libarchive's ISO9660 support operates very differently from - most ISO9660 readers. The libarchive support utilizes a work-queue - design that keeps a list of known entries sorted by their location in the - input. Whenever libarchive's ISO9660 implementation is asked for the - next header, checks this list to find the next item on the disk. Direc- - tories are parsed when they are encountered and new items are added to - the list. This design relies heavily on the ISO9660 image being opti- - mized so that directories always occur earlier on the disk than the files - they describe. - - Depending on the specific format, such approaches may not be possible. - The ZIP format specification, for example, allows archivers to store key - information only at the end of the file. In theory, it is possible to - create ZIP archives that cannot be read without seeking. Fortunately, - such archives are very rare, and libarchive can read most ZIP archives, - though it cannot always extract as much information as a dedicated ZIP - program. - -SEE ALSO - archive(3), archive_entry(3), archive_read(3), archive_write(3), - archive_write_disk(3) - -HISTORY - The libarchive library first appeared in FreeBSD 5.3. - -AUTHORS - The libarchive library was written by Tim Kientzle <kientzle@acm.org>. - -BUGS -FreeBSD 8.0 April 16, 2007 FreeBSD 8.0 diff --git a/libarchive/libarchive-2.7.1/doc/text/mtree.5.txt b/libarchive/libarchive-2.7.1/doc/text/mtree.5.txt deleted file mode 100644 index 375e4a2..0000000 --- a/libarchive/libarchive-2.7.1/doc/text/mtree.5.txt +++ /dev/null @@ -1,158 +0,0 @@ -MTREE(5) FreeBSD File Formats Manual MTREE(5) - -NAME - mtree -- format of mtree dir hierarchy files - -DESCRIPTION - The mtree format is a textual format that describes a collection of - filesystem objects. Such files are typically used to create or verify - directory hierarchies. - - General Format - An mtree file consists of a series of lines, each providing information - about a single filesystem object. Leading whitespace is always ignored. - - When encoding file or pathnames, any backslash character or character - outside of the 95 printable ASCII characters must be encoded as a a back- - slash followed by three octal digits. When reading mtree files, any - appearance of a backslash followed by three octal digits should be con- - verted into the corresponding character. - - Each line is interpreted independently as one of the following types: - - Signature The first line of any mtree file must begin with ``#mtree''. - If a file contains any full path entries, the first line - should begin with ``#mtree v2.0'', otherwise, the first line - should begin with ``#mtree v1.0''. - - Blank Blank lines are ignored. - - Comment Lines beginning with # are ignored. - - Special Lines beginning with / are special commands that influence - the interpretation of later lines. - - Relative If the first whitespace-delimited word has no / characters, - it is the name of a file in the current directory. Any rela- - tive entry that describes a directory changes the current - directory. - - dot-dot As a special case, a relative entry with the filename .. - changes the current directory to the parent directory. - Options on dot-dot entries are always ignored. - - Full If the first whitespace-delimited word has a / character - after the first character, it is the pathname of a file rela- - tive to the starting directory. There can be multiple full - entries describing the same file. - - Some tools that process mtree files may require that multiple lines - describing the same file occur consecutively. It is not permitted for - the same file to be mentioned using both a relative and a full file spec- - ification. - - Special commands - Two special commands are currently defined: - - /set This command defines default values for one or more keywords. - It is followed on the same line by one or more whitespace- - separated keyword definitions. These definitions apply to - all following files that do not specify a value for that key- - word. - - /unset This command removes any default value set by a previous /set - command. It is followed on the same line by one or more key- - words separated by whitespace. - - Keywords - After the filename, a full or relative entry consists of zero or more - whitespace-separated keyword definitions. Each such definition consists - of a key from the following list immediately followed by an '=' sign and - a value. Software programs reading mtree files should warn about unrec- - ognized keywords. - - Currently supported keywords are as follows: - - cksum The checksum of the file using the default algorithm speci- - fied by the cksum(1) utility. - - contents The full pathname of a file that holds the contents of this - file. - - flags The file flags as a symbolic name. See chflags(1) for infor- - mation on these names. If no flags are to be set the string - ``none'' may be used to override the current default. - - gid The file group as a numeric value. - - gname The file group as a symbolic name. - - ignore Ignore any file hierarchy below this file. - - link The target of the symbolic link when type=link. - - md5 The MD5 message digest of the file. - - md5digest A synonym for md5. - - mode The current file's permissions as a numeric (octal) or sym- - bolic value. - - nlink The number of hard links the file is expected to have. - - nochange Make sure this file or directory exists but otherwise ignore - all attributes. - - ripemd160digest - The RIPEMD160 message digest of the file. - - rmd160 A synonym for ripemd160digest. - - rmd160digest - A synonym for ripemd160digest. - - sha1 The FIPS 160-1 (``SHA-1'') message digest of the file. - - sha1digest A synonym for sha1. - - sha256 The FIPS 180-2 (``SHA-256'') message digest of the file. - - sha256digest - A synonym for sha256. - - size The size, in bytes, of the file. - - time The last modification time of the file. - - type The type of the file; may be set to any one of the following: - - block block special device - char character special device - dir directory - fifo fifo - file regular file - link symbolic link - socket socket - - uid The file owner as a numeric value. - - uname The file owner as a symbolic name. - -SEE ALSO - cksum(1), find(1), mtree(8) - -BUGS - The FreeBSD implementation of mtree does not currently support the mtree - 2.0 format. The requirement for a ``#mtree'' signature line is new and - not yet widely implemented. - -HISTORY - The mtree utility appeared in 4.3BSD-Reno. The MD5 digest capability was - added in FreeBSD 2.1, in response to the widespread use of programs which - can spoof cksum(1). The SHA-1 and RIPEMD160 digests were added in - FreeBSD 4.0, as new attacks have demonstrated weaknesses in MD5. The - SHA-256 digest was added in FreeBSD 6.0. Support for file flags was - added in FreeBSD 4.0, and mostly comes from NetBSD. The ``full'' entry - format was added by NetBSD. - -FreeBSD 8.0 August 20, 2007 FreeBSD 8.0 diff --git a/libarchive/libarchive-2.7.1/doc/text/tar.5.txt b/libarchive/libarchive-2.7.1/doc/text/tar.5.txt deleted file mode 100644 index e2b0d61..0000000 --- a/libarchive/libarchive-2.7.1/doc/text/tar.5.txt +++ /dev/null @@ -1,534 +0,0 @@ -TAR(5) FreeBSD File Formats Manual TAR(5) - -NAME - tar -- format of tape archive files - -DESCRIPTION - The tar archive format collects any number of files, directories, and - other file system objects (symbolic links, device nodes, etc.) into a - single stream of bytes. The format was originally designed to be used - with tape drives that operate with fixed-size blocks, but is widely used - as a general packaging mechanism. - - General Format - A tar archive consists of a series of 512-byte records. Each file system - object requires a header record which stores basic metadata (pathname, - owner, permissions, etc.) and zero or more records containing any file - data. The end of the archive is indicated by two records consisting - entirely of zero bytes. - - For compatibility with tape drives that use fixed block sizes, programs - that read or write tar files always read or write a fixed number of - records with each I/O operation. These ``blocks'' are always a multiple - of the record size. The most common block size--and the maximum sup- - ported by historic implementations--is 10240 bytes or 20 records. (Note: - the terms ``block'' and ``record'' here are not entirely standard; this - document follows the convention established by John Gilmore in document- - ing 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 is one of the earliest widely-used versions of - the tar program. - - The header record for an old-style tar archive consists of the following: - - struct header_old_tar { - char name[100]; - char mode[8]; - char uid[8]; - char gid[8]; - char size[12]; - char mtime[12]; - char checksum[8]; - char linkflag[1]; - char linkname[100]; - char pad[255]; - }; - All unused bytes in the header record are filled with nulls. - - name Pathname, stored as a null-terminated string. Early tar imple- - mentations only stored regular files (including hardlinks to - those files). One common early convention used a trailing "/" - character to indicate a directory name, allowing directory per- - missions and owner information to be archived and restored. - - mode File mode, stored as an octal number in ASCII. - - uid, gid - User id and group id of owner, as octal numbers in ASCII. - - size Size of file, as octal number in ASCII. For regular files only, - this indicates the amount of data that follows the header. In - particular, this field was ignored by early tar implementations - when extracting hardlinks. Modern writers should always store a - zero length for hardlink entries. - - mtime Modification time of file, as an octal number in ASCII. This - indicates the number of seconds since the start of the epoch, - 00:00:00 UTC January 1, 1970. Note that negative values should - be avoided here, as they are handled inconsistently. - - checksum - Header checksum, stored as an octal number in ASCII. To compute - the checksum, set the checksum field to all spaces, then sum all - bytes in the header using unsigned arithmetic. This field should - be stored as six octal digits followed by a null and a space - character. Note that many early implementations of tar used - signed arithmetic for the checksum field, which can cause inter- - operability problems when transferring archives between systems. - Modern robust readers compute the checksum both ways and accept - the header if either computation matches. - - linkflag, linkname - In order to preserve hardlinks and conserve tape, a file with - multiple links is only written to the archive the first time it - is encountered. The next time it is encountered, the linkflag is - set to an ASCII `1' and the linkname field holds the first name - under which this file appears. (Note that regular files have a - null value in the linkflag field.) - - Early tar implementations varied in how they terminated these fields. - The tar command in Version 7 AT&T UNIX used the following conventions - (this is also documented in early BSD manpages): the pathname must be - null-terminated; the mode, uid, and gid fields must end in a space and a - null byte; the size and mtime fields must end in a space; the checksum is - terminated by a null and a space. Early implementations filled the - numeric fields with leading spaces. This seems to have been common prac- - tice until the IEEE Std 1003.1-1988 (``POSIX.1'') standard was released. - For best portability, modern implementations should fill the numeric - fields with leading zeros. - - Pre-POSIX Archives - An early draft of IEEE Std 1003.1-1988 (``POSIX.1'') served as the basis - for John Gilmore's pdtar program and many system implementations from the - late 1980s and early 1990s. These archives generally follow the POSIX - ustar format described below with the following variations: - o The magic value is ``ustar '' (note the following space). The - version field contains a space character followed by a null. - o The numeric fields are generally filled with leading spaces (not - leading zeros as recommended in the final standard). - o The prefix field is often not used, limiting pathnames to the 100 - characters of old-style archives. - - POSIX ustar Archives - IEEE Std 1003.1-1988 (``POSIX.1'') defined a standard tar file format to - be read and written by compliant implementations of tar(1). This format - is often called the ``ustar'' format, after the magic value used in the - header. (The name is an acronym for ``Unix Standard TAR''.) It extends - the historic format with new fields: - - struct header_posix_ustar { - char name[100]; - char mode[8]; - char uid[8]; - char gid[8]; - char size[12]; - char mtime[12]; - char checksum[8]; - char typeflag[1]; - char linkname[100]; - char magic[6]; - char version[2]; - char uname[32]; - char gname[32]; - char devmajor[8]; - char devminor[8]; - char prefix[155]; - char pad[12]; - }; - - typeflag - Type of entry. POSIX extended the earlier linkflag field with - several new type values: - ``0'' Regular file. NUL should be treated as a synonym, for - compatibility purposes. - ``1'' Hard link. - ``2'' Symbolic link. - ``3'' Character device node. - ``4'' Block device node. - ``5'' Directory. - ``6'' FIFO node. - ``7'' Reserved. - Other A POSIX-compliant implementation must treat any unrecog- - nized typeflag value as a regular file. In particular, - writers should ensure that all entries have a valid file- - name so that they can be restored by readers that do not - support the corresponding extension. Uppercase letters - "A" through "Z" are reserved for custom extensions. Note - that sockets and whiteout entries are not archivable. - It is worth noting that the size field, in particular, has dif- - ferent meanings depending on the type. For regular files, of - course, it indicates the amount of data following the header. - For directories, it may be used to indicate the total size of all - files in the directory, for use by operating systems that pre- - allocate directory space. For all other types, it should be set - to zero by writers and ignored by readers. - - magic Contains the magic value ``ustar'' followed by a NUL byte to - indicate that this is a POSIX standard archive. Full compliance - requires the uname and gname fields be properly set. - - version - Version. This should be ``00'' (two copies of the ASCII digit - zero) for POSIX standard archives. - - uname, gname - User and group names, as null-terminated ASCII strings. These - should be used in preference to the uid/gid values when they are - set and the corresponding names exist on the system. - - devmajor, devminor - Major and minor numbers for character device or block device - entry. - - prefix First part of pathname. 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 here. 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 path- - name. - - Note that all unused bytes must be set to NUL. - - Field termination is specified slightly differently by POSIX than by pre- - vious implementations. The magic, uname, and gname fields must have a - trailing NUL. The pathname, linkname, and prefix fields must have a - trailing NUL unless they fill the entire field. (In particular, it is - possible to store a 256-character pathname if it happens to have a / as - the 156th character.) POSIX requires numeric fields to be zero-padded in - the front, and allows them to be terminated with either space or NUL - characters. - - Currently, most tar implementations comply with the ustar format, occa- - sionally extending it by adding new fields to the blank area at the end - of the header record. - - Pax Interchange Format - There are many attributes that cannot be portably stored in a POSIX ustar - archive. IEEE Std 1003.1-2001 (``POSIX.1'') defined a ``pax interchange - format'' that uses two new types of entries to hold text-formatted meta- - data that applies to following entries. Note that a pax interchange for- - mat archive is a ustar archive in every respect. The new data is stored - in ustar-compatible archive entries that use the ``x'' or ``g'' typeflag. - In particular, older implementations that do not fully support these - extensions will extract the metadata into regular files, where the meta- - data can be examined as necessary. - - An entry in a pax interchange format archive consists of one or two stan- - dard ustar entries, each with its own header and data. The first - optional entry stores the extended attributes for the following entry. - This optional first entry has an "x" typeflag and a size field that indi- - cates the total size of the extended attributes. The extended attributes - themselves are stored as a series of text-format lines encoded in the - portable UTF-8 encoding. Each line consists of a decimal number, a - space, a key string, an equals sign, a value string, and a new line. The - decimal number indicates the length of the entire line, including the - initial length field and the trailing newline. An example of such a - field is: - 25 ctime=1084839148.1212\n - Keys in all lowercase are standard keys. Vendors can add their own keys - by prefixing them with an all uppercase vendor name and a period. Note - that, unlike the historic header, numeric values are stored using deci- - mal, not octal. A description of some common keys follows: - - atime, ctime, mtime - File access, inode change, and modification times. These fields - can be negative or include a decimal point and a fractional - value. - - uname, uid, gname, gid - User name, group name, and numeric UID and GID values. The user - name and group name stored here are encoded in UTF8 and can thus - include non-ASCII characters. The UID and GID fields can be of - arbitrary length. - - linkpath - The full path of the linked-to file. Note that this is encoded - in UTF8 and can thus include non-ASCII characters. - - path The full pathname of the entry. Note that this is encoded in - UTF8 and can thus include non-ASCII characters. - - realtime.*, security.* - These keys are reserved and may be used for future standardiza- - tion. - - size The size of the file. Note that there is no length limit on this - field, allowing conforming archives to store files much larger - than the historic 8GB limit. - - SCHILY.* - Vendor-specific attributes used by Joerg Schilling's star imple- - mentation. - - SCHILY.acl.access, SCHILY.acl.default - Stores the access and default ACLs as textual strings in a format - that is an extension of the format specified by POSIX.1e draft - 17. In particular, each user or group access specification can - include a fourth colon-separated field with the numeric UID or - GID. This allows ACLs to be restored on systems that may not - have complete user or group information available (such as when - NIS/YP or LDAP services are temporarily unavailable). - - SCHILY.devminor, SCHILY.devmajor - The full minor and major numbers for device nodes. - - SCHILY.dev, SCHILY.ino, SCHILY.nlinks - The device number, inode number, and link count for the entry. - In particular, note that a pax interchange format archive using - Joerg Schilling's SCHILY.* extensions can store all of the data - from struct stat. - - LIBARCHIVE.xattr.namespace.key - Libarchive stores POSIX.1e-style extended attributes using keys - of this form. The key value is URL-encoded: All non-ASCII char- - acters and the two special characters ``='' and ``%'' are encoded - as ``%'' followed by two uppercase hexadecimal digits. The value - of this key is the extended attribute value encoded in base 64. - XXX Detail the base-64 format here XXX - - VENDOR.* - XXX document other vendor-specific extensions XXX - - Any values stored in an extended attribute override the corresponding - values in the regular tar header. Note that compliant readers should - ignore the regular fields when they are overridden. This is important, - as existing archivers are known to store non-compliant values in the - standard header fields in this situation. There are no limits on length - for any of these fields. In particular, numeric fields can be arbitrar- - ily large. All text fields are encoded in UTF8. Compliant writers - should store only portable 7-bit ASCII characters in the standard ustar - header and use extended attributes whenever a text value contains non- - ASCII characters. - - In addition to the x entry described above, the pax interchange format - also supports a g entry. The g entry is identical in format, but speci- - fies attributes that serve as defaults for all subsequent archive - entries. The g entry is not widely used. - - Besides the new x and g entries, the pax interchange format has a few - other minor variations from the earlier ustar format. The most troubling - one is that hardlinks are permitted to have data following them. This - allows readers to restore any hardlink to a file without having to rewind - the archive to find an earlier entry. However, it creates complications - for robust readers, as it is no longer clear whether or not they should - ignore the size field for hardlink entries. - - GNU Tar Archives - The GNU tar program started with a pre-POSIX format similar to that - described earlier and has extended it using several different mechanisms: - It added new fields to the empty space in the header (some of which was - later used by POSIX for conflicting purposes); it allowed the header to - be continued over multiple records; and it defined new entries that mod- - ify following entries (similar in principle to the x entry described - above, but each GNU special entry is single-purpose, unlike the general- - purpose x entry). As a result, GNU tar archives are not POSIX compati- - ble, although more lenient POSIX-compliant readers can successfully - extract most GNU tar archives. - - struct header_gnu_tar { - char name[100]; - char mode[8]; - char uid[8]; - char gid[8]; - char size[12]; - char mtime[12]; - char checksum[8]; - char typeflag[1]; - char linkname[100]; - char magic[6]; - char version[2]; - char uname[32]; - char gname[32]; - char devmajor[8]; - char devminor[8]; - char atime[12]; - char ctime[12]; - char offset[12]; - char longnames[4]; - char unused[1]; - struct { - char offset[12]; - char numbytes[12]; - } sparse[4]; - char isextended[1]; - char realsize[12]; - char pad[17]; - }; - - typeflag - GNU tar uses the following special entry types, in addition to - those defined by POSIX: - - 7 GNU tar treats type "7" records identically to type "0" - records, except on one obscure RTOS where they are used - to indicate the pre-allocation of a contiguous file on - disk. - - D This indicates a directory entry. Unlike the POSIX-stan- - dard "5" typeflag, the header is followed by data records - listing the names of files in this directory. Each name - is preceded by an ASCII "Y" if the file is stored in this - archive or "N" if the file is not stored in this archive. - Each name is terminated with a null, and an extra null - marks the end of the name list. The purpose of this - entry is to support incremental backups; a program - restoring from such an archive may wish to delete files - on disk that did not exist in the directory when the ar- - chive was made. - - Note that the "D" typeflag specifically violates POSIX, - which requires that unrecognized typeflags be restored as - normal files. In this case, restoring the "D" entry as a - file could interfere with subsequent creation of the - like-named directory. - - K The data for this entry is a long linkname for the fol- - lowing regular entry. - - L The data for this entry is a long pathname for the fol- - lowing regular entry. - - M This is a continuation of the last file on the previous - volume. GNU multi-volume archives guarantee that each - volume begins with a valid entry header. To ensure this, - a file may be split, with part stored at the end of one - volume, and part stored at the beginning of the next vol- - ume. The "M" typeflag indicates that this entry contin- - ues an existing file. Such entries can only occur as the - first or second entry in an archive (the latter only if - the first entry is a volume label). The size field spec- - ifies the size of this entry. The offset field at bytes - 369-380 specifies the offset where this file fragment - begins. The realsize field specifies the total size of - the file (which must equal size plus offset). When - extracting, GNU tar checks that the header file name is - the one it is expecting, that the header offset is in the - correct sequence, and that the sum of offset and size is - equal to realsize. FreeBSD's version of GNU tar does not - handle the corner case of an archive's being continued in - the middle of a long name or other extension header. - - N Type "N" records are no longer generated by GNU tar. - They contained a list of files to be renamed or symlinked - after extraction; this was originally used to support - long names. The contents of this record are a text - description of the operations to be done, in the form - ``Rename %s to %s\n'' or ``Symlink %s to %s\n''; in - either case, both filenames are escaped using K&R C syn- - tax. - - S This is a ``sparse'' regular file. Sparse files are - stored as a series of fragments. The header contains a - list of fragment offset/length pairs. If more than four - such entries are required, the header is extended as nec- - essary with ``extra'' header extensions (an older format - that is no longer used), or ``sparse'' extensions. - - V The name field should be interpreted as a tape/volume - header name. This entry should generally be ignored on - extraction. - - magic The magic field holds the five characters ``ustar'' followed by a - space. Note that POSIX ustar archives have a trailing null. - - version - The version field holds a space character followed by a null. - Note that POSIX ustar archives use two copies of the ASCII digit - ``0''. - - atime, ctime - The time the file was last accessed and the time of last change - of file information, stored in octal as with mtime. - - longnames - This field is apparently no longer used. - - Sparse offset / numbytes - Each such structure specifies a single fragment of a sparse file. - The two fields store values as octal numbers. The fragments are - each padded to a multiple of 512 bytes in the archive. On - extraction, the list of fragments is collected from the header - (including any extension headers), and the data is then read and - written to the file at appropriate offsets. - - isextended - If this is set to non-zero, the header will be followed by addi- - tional ``sparse header'' records. Each such record contains - information about as many as 21 additional sparse blocks as shown - here: - - struct gnu_sparse_header { - struct { - char offset[12]; - char numbytes[12]; - } sparse[21]; - char isextended[1]; - char padding[7]; - }; - - realsize - A binary representation of the file's complete size, with a much - larger range than the POSIX file size. In particular, with M - type files, the current entry is only a portion of the file. In - that case, the POSIX size field will indicate the size of this - entry; the realsize field will indicate the total size of the - file. - - Solaris Tar - XXX More Details Needed XXX - - Solaris tar (beginning with SunOS XXX 5.7 ?? XXX) supports an - ``extended'' format that is fundamentally similar to pax interchange for- - mat, with the following differences: - o Extended attributes are stored in an entry whose type is X, not - x, as used by pax interchange format. The detailed format of - this entry appears to be the same as detailed above for the x - entry. - o An additional A entry is used to store an ACL for the following - regular entry. The body of this entry contains a seven-digit - octal number (whose value is 01000000 plus the number of ACL - entries) followed by a zero byte, followed by the textual ACL - description. - - Other Extensions - One common 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 character. 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 such archives are almost never seen. - However, there is still code in GNU tar to support them; this code is - responsible for a very cryptic warning message that is sometimes seen - when GNU tar encounters a damaged archive. - -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. Joerg Shilling's star archiver is - another open-source (GPL) archiver (originally developed circa 1985) - which features complete support for pax interchange format. - -FreeBSD 8.0 May 20, 2004 FreeBSD 8.0 |