diff options
Diffstat (limited to 'archivers/libarchive/files/doc')
26 files changed, 9057 insertions, 0 deletions
diff --git a/archivers/libarchive/files/doc/man/archive_entry.3 b/archivers/libarchive/files/doc/man/archive_entry.3 new file mode 100644 index 00000000000..6b1b270f1a5 --- /dev/null +++ b/archivers/libarchive/files/doc/man/archive_entry.3 @@ -0,0 +1,382 @@ +.\" Copyright (c) 2003-2007 Tim Kientzle +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: src/lib/libarchive/archive_entry.3,v 1.15 2007/07/15 19:10:34 kientzle Exp $ +.\" +.Dd December 15, 2003 +.Dt archive_entry 3 +.Os +.Sh NAME +.Nm archive_entry_acl_add_entry , +.Nm archive_entry_acl_add_entry_w , +.Nm archive_entry_acl_clear , +.Nm archive_entry_acl_count , +.Nm archive_entry_acl_next , +.Nm archive_entry_acl_next_w , +.Nm archive_entry_acl_reset , +.Nm archive_entry_acl_text_w , +.Nm archive_entry_atime , +.Nm archive_entry_atime_nsec , +.Nm archive_entry_clear , +.Nm archive_entry_clone , +.Nm archive_entry_copy_fflags_text_w , +.Nm archive_entry_copy_gname , +.Nm archive_entry_copy_gname_w , +.Nm archive_entry_copy_hardlink , +.Nm archive_entry_copy_hardlink_w , +.Nm archive_entry_copy_pathname_w , +.Nm archive_entry_copy_stat , +.Nm archive_entry_copy_symlink , +.Nm archive_entry_copy_symlink_w , +.Nm archive_entry_copy_uname , +.Nm archive_entry_copy_uname_w , +.Nm archive_entry_dev , +.Nm archive_entry_devmajor , +.Nm archive_entry_devminor , +.Nm archive_entry_filetype , +.Nm archive_entry_fflags , +.Nm archive_entry_fflags_text , +.Nm archive_entry_free , +.Nm archive_entry_gid , +.Nm archive_entry_gname , +.Nm archive_entry_hardlink , +.Nm archive_entry_ino , +.Nm archive_entry_mode , +.Nm archive_entry_mtime , +.Nm archive_entry_mtime_nsec , +.Nm archive_entry_nlink , +.Nm archive_entry_new , +.Nm archive_entry_pathname , +.Nm archive_entry_pathname_w , +.Nm archive_entry_rdev , +.Nm archive_entry_rdevmajor , +.Nm archive_entry_rdevminor , +.Nm archive_entry_set_atime , +.Nm archive_entry_set_ctime , +.Nm archive_entry_set_dev , +.Nm archive_entry_set_devmajor , +.Nm archive_entry_set_devminor , +.Nm archive_entry_set_filetype , +.Nm archive_entry_set_fflags , +.Nm archive_entry_set_gid , +.Nm archive_entry_set_gname , +.Nm archive_entry_set_hardlink , +.Nm archive_entry_set_link , +.Nm archive_entry_set_mode , +.Nm archive_entry_set_mtime , +.Nm archive_entry_set_pathname , +.Nm archive_entry_set_rdevmajor , +.Nm archive_entry_set_rdevminor , +.Nm archive_entry_set_size , +.Nm archive_entry_set_symlink , +.Nm archive_entry_set_uid , +.Nm archive_entry_set_uname , +.Nm archive_entry_size , +.Nm archive_entry_stat , +.Nm archive_entry_symlink , +.Nm archive_entry_uid , +.Nm archive_entry_uname +.Nd functions for manipulating archive entry descriptions +.Sh SYNOPSIS +.In archive_entry.h +.Ft void +.Fn archive_entry_acl_add_entry "struct archive_entry *" "int type" "int permset" "int tag" "int qual" "const char *name" +.Ft void +.Fn archive_entry_acl_add_entry_w "struct archive_entry *" "int type" "int permset" "int tag" "int qual" "const wchar_t *name" +.Ft void +.Fn archive_entry_acl_clear "struct archive_entry *" +.Ft int +.Fn archive_entry_acl_count "struct archive_entry *" "int type" +.Ft int +.Fn archive_entry_acl_next "struct archive_entry *" "int want_type" "int *type" "int *permset" "int *tag" "int *qual" "const char **name" +.Ft int +.Fn archive_entry_acl_next_w "struct archive_entry *" "int want_type" "int *type" "int *permset" "int *tag" "int *qual" "const wchar_t **name" +.Ft int +.Fn archive_entry_acl_reset "struct archive_entry *" "int want_type" +.Ft const wchar_t * +.Fn archive_entry_acl_text_w "struct archive_entry *" "int flags" +.Ft time_t +.Fn archive_entry_atime "struct archive_entry *" +.Ft long +.Fn archive_entry_atime_nsec "struct archive_entry *" +.Ft "struct archive_entry *" +.Fn archive_entry_clear "struct archive_entry *" +.Ft struct archive_entry * +.Fn archive_entry_clone "struct archive_entry *" +.Ft const wchar_t * +.Fn archive_entry_copy_fflags_text_w "struct archive_entry *" "const wchar_t *" +.Ft void +.Fn archive_entry_copy_gname "struct archive_entry *" "const char *" +.Ft void +.Fn archive_entry_copy_gname_w "struct archive_entry *" "const wchar_t *" +.Ft void +.Fn archive_entry_copy_hardlink "struct archive_entry *" "const char *" +.Ft void +.Fn archive_entry_copy_hardlink_w "struct archive_entry *" "const wchar_t *" +.Ft void +.Fn archive_entry_copy_pathname_w "struct archive_entry *" "const wchar_t *" +.Ft void +.Fn archive_entry_copy_stat "struct archive_entry *" "const struct stat *" +.Ft void +.Fn archive_entry_copy_symlink "struct archive_entry *" "const char *" +.Ft void +.Fn archive_entry_copy_symlink_w "struct archive_entry *" "const wchar_t *" +.Ft void +.Fn archive_entry_copy_uname "struct archive_entry *" "const char *" +.Ft void +.Fn archive_entry_copy_uname_w "struct archive_entry *" "const wchar_t *" +.Ft dev_t +.Fn archive_entry_dev "struct archive_entry *" +.Ft dev_t +.Fn archive_entry_devmajor "struct archive_entry *" +.Ft dev_t +.Fn archive_entry_devminor "struct archive_entry *" +.Ft mode_t +.Fn archive_entry_filetype "struct archive_entry *" +.Ft void +.Fn archive_entry_fflags "struct archive_entry *" "unsigned long *set" "unsigned long *clear" +.Ft const char * +.Fn archive_entry_fflags_text "struct archive_entry *" +.Ft void +.Fn archive_entry_free "struct archive_entry *" +.Ft const char * +.Fn archive_entry_gname "struct archive_entry *" +.Ft const char * +.Fn archive_entry_hardlink "struct archive_entry *" +.Ft ino_t +.Fn archive_entry_ino "struct archive_entry *" +.Ft mode_t +.Fn archive_entry_mode "struct archive_entry *" +.Ft time_t +.Fn archive_entry_mtime "struct archive_entry *" +.Ft long +.Fn archive_entry_mtime_nsec "struct archive_entry *" +.Ft unsigned int +.Fn archive_entry_nlink "struct archive_entry *" +.Ft struct archive_entry * +.Fn archive_entry_new "void" +.Ft const char * +.Fn archive_entry_pathname "struct archive_entry *" +.Ft const wchar_t * +.Fn archive_entry_pathname_w "struct archive_entry *" +.Ft dev_t +.Fn archive_entry_rdev "struct archive_entry *" +.Ft dev_t +.Fn archive_entry_rdevmajor "struct archive_entry *" +.Ft dev_t +.Fn archive_entry_rdevminor "struct archive_entry *" +.Ft void +.Fn archive_entry_set_dev "struct archive_entry *" "dev_t" +.Ft void +.Fn archive_entry_set_devmajor "struct archive_entry *" "dev_t" +.Ft void +.Fn archive_entry_set_devminor "struct archive_entry *" "dev_t" +.Ft void +.Fn archive_entry_set_filetype "struct archive_entry *" "unsigned int" +.Ft void +.Fn archive_entry_set_fflags "struct archive_entry *" "unsigned long set" "unsigned long clear" +.Ft void +.Fn archive_entry_set_gid "struct archive_entry *" "gid_t" +.Ft void +.Fn archive_entry_set_gname "struct archive_entry *" "const char *" +.Ft void +.Fn archive_entry_set_hardlink "struct archive_entry *" "const char *" +.Ft void +.Fn archive_entry_set_ino "struct archive_entry *" "unsigned long" +.Ft void +.Fn archive_entry_set_link "struct archive_entry *" "const char *" +.Ft void +.Fn archive_entry_set_mode "struct archive_entry *" "mode_t" +.Ft void +.Fn archive_entry_set_mtime "struct archive_entry *" "time_t" "long nanos" +.Ft void +.Fn archive_entry_set_nlink "struct archive_entry *" "unsigned int" +.Ft void +.Fn archive_entry_set_pathname "struct archive_entry *" "const char *" +.Ft void +.Fn archive_entry_set_rdev "struct archive_entry *" "dev_t" +.Ft void +.Fn archive_entry_set_rdevmajor "struct archive_entry *" "dev_t" +.Ft void +.Fn archive_entry_set_rdevminor "struct archive_entry *" "dev_t" +.Ft void +.Fn archive_entry_set_size "struct archive_entry *" "int64_t" +.Ft void +.Fn archive_entry_set_symlink "struct archive_entry *" "const char *" +.Ft void +.Fn archive_entry_set_uid "struct archive_entry *" "uid_t" +.Ft void +.Fn archive_entry_set_uname "struct archive_entry *" "const char *" +.Ft int64_t +.Fn archive_entry_size "struct archive_entry *" +.Ft const struct stat * +.Fn archive_entry_stat "struct archive_entry *" +.Ft const char * +.Fn archive_entry_symlink "struct archive_entry *" +.Ft const char * +.Fn archive_entry_uname "struct archive_entry *" +.Sh DESCRIPTION +These functions create and manipulate data objects that +represent entries within an archive. +You can think of a +.Tn struct archive_entry +as a heavy-duty version of +.Tn struct stat : +it includes everything from +.Tn struct stat +plus associated pathname, textual group and user names, etc. +These objects are used by +.Xr libarchive 3 +to represent the metadata associated with a particular +entry in an archive. +.Ss Create and Destroy +There are functions to allocate, destroy, clear, and copy +.Va archive_entry +objects: +.Bl -tag -compact -width indent +.It Fn 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. +.It Fn archive_entry_clone +A deep copy operation; all text fields are duplicated. +.It Fn archive_entry_free +Releases the +.Tn struct archive_entry +object. +.It Fn archive_entry_new +Allocate and return a blank +.Tn struct archive_entry +object. +.El +.Ss Set and Get Functions +Most of the functions here set or read entries in an object. +Such functions have one of the following forms: +.Bl -tag -compact -width indent +.It Fn archive_entry_set_XXXX +Stores the provided data in the object. +In particular, for strings, the pointer is stored, +not the referenced string. +.It Fn archive_entry_copy_XXXX +As above, except that the referenced data is copied +into the object. +.It Fn archive_entry_XXXX +Returns the specified data. +In the case of strings, a const-qualified pointer to +the string is returned. +.El +String data can be set or accessed as wide character strings +or normal +.Va char +strings. +The functions that use wide character strings are suffixed with +.Cm _w . +Note that these are different representations of the same data: +For example, if you store a narrow string and read the corresponding +wide string, the object will transparently convert formats +using the current locale. +Similarly, if you store a wide string and then store a +narrow string for the same data, the previously-set wide string will +be discarded in favor of the new data. +.Pp +There are a few set/get functions that merit additional description: +.Bl -tag -compact -width indent +.It Fn archive_entry_set_link +This function sets the symlink field if it is already set. +Otherwise, it sets the hardlink field. +.El +.Ss File Flags +File flags are transparently converted between a bitmap +representation and a textual format. +For example, if you set the bitmap and ask for text, the library +will build a canonical text format. +However, if you set a text format and request a text format, +you will get back the same text, even if it is ill-formed. +If you need to canonicalize a textual flags string, you should first set the +text form, then request the bitmap form, then use that to set the bitmap form. +Setting the bitmap format will clear the internal text representation +and force it to be reconstructed when you next request the text form. +.Pp +The bitmap format consists of two integers, one containing bits +that should be set, the other specifying bits that should be +cleared. +Bits not mentioned in either bitmap will be ignored. +Usually, the bitmap of bits to be cleared will be set to zero. +In unusual circumstances, you can force a fully-specified set +of file flags by setting the bitmap of flags to clear to the complement +of the bitmap of flags to set. +(This differs from +.Xr 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. +.Pp +The canonical text format is a comma-separated list of flag names. +The +.Fn archive_entry_copy_fflags_text_w +function parses 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 +.Xr strtofflags 3 , +which stops parsing at the first unrecognized name.) +.Ss ACL Handling +XXX This needs serious help. +XXX +.Pp +An +.Dq Access Control List +(ACL) is a list of permissions that grant access to particular users or +groups beyond what would normally be provided by standard POSIX mode bits. +The ACL handling here addresses some deficiencies in the POSIX.1e draft 17 ACL +specification. +In particular, POSIX.1e draft 17 specifies several different formats, but +none of those formats include both textual user/group names and numeric +UIDs/GIDs. +.Pp +XXX explain ACL stuff XXX +.\" .Sh EXAMPLE +.\" .Sh RETURN VALUES +.\" .Sh ERRORS +.Sh SEE ALSO +.Xr archive 3 +.Sh HISTORY +The +.Nm libarchive +library first appeared in +.Fx 5.3 . +.Sh AUTHORS +.An -nosplit +The +.Nm libarchive +library was written by +.An Tim Kientzle Aq kientzle@acm.org . +.\" .Sh BUGS diff --git a/archivers/libarchive/files/doc/man/archive_read.3 b/archivers/libarchive/files/doc/man/archive_read.3 new file mode 100644 index 00000000000..6daba3f3d11 --- /dev/null +++ b/archivers/libarchive/files/doc/man/archive_read.3 @@ -0,0 +1,524 @@ +.\" Copyright (c) 2003-2007 Tim Kientzle +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: src/lib/libarchive/archive_read.3,v 1.35 2007/09/19 16:37:45 kientzle Exp $ +.\" +.Dd August 19, 2006 +.Dt archive_read 3 +.Os +.Sh NAME +.Nm archive_read_new , +.Nm archive_read_support_compression_all , +.Nm archive_read_support_compression_bzip2 , +.Nm archive_read_support_compression_compress , +.Nm archive_read_support_compression_gzip , +.Nm archive_read_support_compression_none , +.Nm archive_read_support_compression_program , +.Nm archive_read_support_format_all , +.Nm archive_read_support_format_cpio , +.Nm archive_read_support_format_empty , +.Nm archive_read_support_format_iso9660 , +.Nm archive_read_support_format_tar , +.Nm archive_read_support_format_zip , +.Nm archive_read_open , +.Nm archive_read_open2 , +.Nm archive_read_open_fd , +.Nm archive_read_open_FILE , +.Nm archive_read_open_filename , +.Nm archive_read_open_memory , +.Nm archive_read_next_header , +.Nm archive_read_data , +.Nm archive_read_data_block , +.Nm archive_read_data_skip , +.\" #if ARCHIVE_API_VERSION < 3 +.Nm archive_read_data_into_buffer , +.\" #endif +.Nm archive_read_data_into_fd , +.Nm archive_read_extract , +.Nm archive_read_extract_set_progress_callback , +.Nm archive_read_close , +.Nm archive_read_finish +.Nd functions for reading streaming archives +.Sh SYNOPSIS +.In archive.h +.Ft struct archive * +.Fn archive_read_new "void" +.Ft int +.Fn archive_read_support_compression_all "struct archive *" +.Ft int +.Fn archive_read_support_compression_bzip2 "struct archive *" +.Ft int +.Fn archive_read_support_compression_compress "struct archive *" +.Ft int +.Fn archive_read_support_compression_gzip "struct archive *" +.Ft int +.Fn archive_read_support_compression_none "struct archive *" +.Ft int +.Fn archive_read_support_compression_program "struct archive *" "const char *cmd" +.Ft int +.Fn archive_read_support_format_all "struct archive *" +.Ft int +.Fn archive_read_support_format_cpio "struct archive *" +.Ft int +.Fn archive_read_support_format_empty "struct archive *" +.Ft int +.Fn archive_read_support_format_iso9660 "struct archive *" +.Ft int +.Fn archive_read_support_format_tar "struct archive *" +.Ft int +.Fn archive_read_support_format_zip "struct archive *" +.Ft int +.Fn archive_read_open "struct archive *" "void *client_data" "archive_open_callback *" "archive_read_callback *" "archive_close_callback *" +.Ft int +.Fn archive_read_open2 "struct archive *" "void *client_data" "archive_open_callback *" "archive_read_callback *" "archive_skip_callback *" "archive_close_callback *" +.Ft int +.Fn archive_read_open_FILE "struct archive *" "FILE *file" +.Ft int +.Fn archive_read_open_fd "struct archive *" "int fd" "size_t block_size" +.Ft int +.Fn archive_read_open_filename "struct archive *" "const char *filename" "size_t block_size" +.Ft int +.Fn archive_read_open_memory "struct archive *" "void *buff" "size_t size" +.Ft int +.Fn archive_read_next_header "struct archive *" "struct archive_entry **" +.Ft ssize_t +.Fn archive_read_data "struct archive *" "void *buff" "size_t len" +.Ft int +.Fn archive_read_data_block "struct archive *" "const void **buff" "size_t *len" "off_t *offset" +.Ft int +.Fn archive_read_data_skip "struct archive *" +.\" #if ARCHIVE_API_VERSION < 3 +.Ft int +.Fn archive_read_data_into_buffer "struct archive *" "void *" "ssize_t len" +.\" #endif +.Ft int +.Fn archive_read_data_into_fd "struct archive *" "int fd" +.Ft int +.Fn archive_read_extract "struct archive *" "struct archive_entry *" "int flags" +.Ft void +.Fn archive_read_extract_set_progress_callback "struct archive *" "void (*func)(void *)" "void *user_data" +.Ft int +.Fn archive_read_close "struct archive *" +.Ft int +.Fn archive_read_finish "struct archive *" +.Sh DESCRIPTION +These functions provide a complete API for reading streaming archives. +The general process is to first create the +.Tn struct archive +object, set options, initialize the reader, iterate over the archive +headers and associated data, then close the archive and release all +resources. +The following summary describes the functions in approximately the +order they would be used: +.Bl -tag -compact -width indent +.It Fn archive_read_new +Allocates and initializes a +.Tn struct archive +object suitable for reading from an archive. +.It Fn archive_read_support_compression_all , Fn archive_read_support_compression_bzip2 , Fn archive_read_support_compression_compress , Fn archive_read_support_compression_gzip , Fn archive_read_support_compression_none +Enables auto-detection code and decompression support for the +specified compression. +Note that +.Dq none +is always enabled by default. +For convenience, +.Fn archive_read_support_compression_all +enables all available decompression code. +.It Fn archive_read_support_compression_program +Data is fed through the specified external program before being dearchived. +Note that this disables automatic detection of the compression format, +so it makes no sense to specify this in conjunction with any other +decompression option. +.It Fn archive_read_support_format_all , Fn archive_read_support_format_cpio , Fn archive_read_support_format_empty , Fn archive_read_support_format_iso9660 , Fn archive_read_support_format_tar, Fn archive_read_support_format_zip +Enables support---including auto-detection code---for the +specified archive format. +For example, +.Fn 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, +.Fn archive_read_support_format_all +enables support for all available formats. +Only empty archives are supported by default. +.It Fn archive_read_open +The same as +.Fn archive_read_open2 , +except that the skip callback is assumed to be +.Dv NULL . +.It Fn 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 +.Fn archive_read_open_filename , +.Fn archive_read_open_FILE , +.Fn archive_read_open_fd , +or +.Fn archive_read_open_memory +instead. +The library invokes the client-provided functions to obtain +raw bytes from the archive. +.It Fn archive_read_open_FILE +Like +.Fn archive_read_open , +except that it accepts a +.Ft "FILE *" +pointer. +This function should not be used with tape drives or other devices +that require strict I/O blocking. +.It Fn archive_read_open_fd +Like +.Fn archive_read_open , +except that it accepts a file descriptor and block size rather than +a set of function pointers. +Note that the file descriptor will not be automatically closed at +end-of-archive. +This function is safe for use with tape drives or other blocked devices. +.It Fn archive_read_open_file +This is a deprecated synonym for +.Fn archive_read_open_filename . +.It Fn archive_read_open_filename +Like +.Fn archive_read_open , +except that it accepts a simple filename and a block size. +A NULL filename represents standard input. +This function is safe for use with tape drives or other blocked devices. +.It Fn archive_read_open_memory +Like +.Fn archive_read_open , +except that it accepts a pointer and size of a block of +memory containing the archive data. +.It Fn archive_read_next_header +Read the header for the next entry and return a pointer to +a +.Tn struct archive_entry . +.It Fn archive_read_data +Read data associated with the header just read. +Internally, this is a convenience function that calls +.Fn archive_read_data_block +and fills any gaps with nulls so that callers see a single +continuous stream of data. +.It Fn archive_read_data_block +Return the next available block of data for this entry. +Unlike +.Fn archive_read_data , +the +.Fn archive_read_data_block +function avoids copying data and allows you to correctly handle +sparse files, as supported by some archive formats. +The library guarantees that offsets will increase and that blocks +will not overlap. +Note that the blocks returned from this function can be much larger +than the block size read from disk, due to compression +and internal buffer optimizations. +.It Fn archive_read_data_skip +A convenience function that repeatedly calls +.Fn archive_read_data_block +to skip all of the data for this archive entry. +.\" #if ARCHIVE_API_VERSION < 3 +.It Fn archive_read_data_into_buffer +This function is deprecated and will be removed. +Use +.Fn archive_read_data +instead. +.\" #endif +.It Fn archive_read_data_into_fd +A convenience function that repeatedly calls +.Fn archive_read_data_block +to copy the entire entry to the provided file descriptor. +.It Fn archive_read_extract , Fn archive_read_extract_set_skip_file +A convenience function that wraps the corresponding +.Xr archive_write_disk 3 +interfaces. +The first call to +.Fn archive_read_extract +creates a restore object using +.Xr archive_write_disk_new 3 +and +.Xr archive_write_disk_set_standard_lookup 3 , +then transparently invokes +.Xr archive_write_disk_set_options 3 , +.Xr archive_write_header 3 , +.Xr archive_write_data 3 , +and +.Xr archive_write_finish_entry 3 +to create the entry on disk and copy data into it. +The +.Va flags +argument is passed unmodified to +.Xr archive_write_disk_set_options 3 . +.It Fn archive_read_extract_set_progress_callback +Sets a pointer to a user-defined callback that can be used +for updating progress displays during extraction. +The progress function will be invoked during the extraction of large +regular files. +The progress function will be invoked with the pointer provided to this call. +Generally, the data pointed to should include a reference to the archive +object and the archive_entry object so that various statistics +can be retrieved for the progress display. +.It Fn archive_read_close +Complete the archive and invoke the close callback. +.It Fn archive_read_finish +Invokes +.Fn archive_read_close +if it was not invoked manually, then release all resources. +Note: In libarchive 1.x, this function was declared to return +.Ft void , +which made it impossible to detect certain errors when +.Fn archive_read_close +was invoked implicitly from this function. +The declaration is corrected beginning with libarchive 2.0. +.El +.Pp +Note that the library determines most of the relevant information about +the archive by inspection. +In particular, it automatically detects +.Xr gzip 1 +or +.Xr bzip2 1 +compression and transparently performs the appropriate decompression. +It also automatically detects the archive format. +.Pp +A complete description of the +.Tn struct archive +and +.Tn struct archive_entry +objects can be found in the overview manual page for +.Xr libarchive 3 . +.Sh CLIENT CALLBACKS +The callback functions must match the following prototypes: +.Bl -item -offset indent +.It +.Ft typedef ssize_t +.Fn archive_read_callback "struct archive *" "void *client_data" "const void **buffer" +.It +.\" #if ARCHIVE_API_VERSION < 2 +.Ft typedef int +.Fn archive_skip_callback "struct archive *" "void *client_data" "size_t request" +.\" #else +.\" .Ft typedef off_t +.\" .Fn archive_skip_callback "struct archive *" "void *client_data" "off_t request" +.\" #endif +.It +.Ft typedef int +.Fn archive_open_callback "struct archive *" "void *client_data" +.It +.Ft typedef int +.Fn archive_close_callback "struct archive *" "void *client_data" +.El +.Pp +The open callback is invoked by +.Fn archive_open . +It should return +.Cm ARCHIVE_OK +if the underlying file or data source is successfully +opened. +If the open fails, it should call +.Fn archive_set_error +to register an error code and message and return +.Cm ARCHIVE_FATAL . +.Pp +The read callback is invoked whenever the library +requires raw bytes from the archive. +The read callback should read data into a buffer, +set the +.Li 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 +.Fn archive_set_error +to register an error code and message and +return -1. +.Pp +The skip callback is invoked when the +library wants to ignore a block of data. +The return value is the number of bytes actually +skipped, which may differ from the request. +If the callback cannot skip data, it should return +zero. +If the skip callback is not provided (the +function pointer is +.Dv NULL ), +the library will invoke the read function +instead and simply discard the result. +A skip callback can provide significant +performance gains when reading uncompressed +archives from slow disk drives or other media +that can skip quickly. +.Pp +The close callback is invoked by archive_close when +the archive processing is complete. +The callback should return +.Cm ARCHIVE_OK +on success. +On failure, the callback should invoke +.Fn archive_set_error +to register an error code and message and +return +.Cm ARCHIVE_FATAL. +.Sh EXAMPLE +The following illustrates basic usage of the library. +In this example, +the callback functions are simply wrappers around the standard +.Xr open 2 , +.Xr read 2 , +and +.Xr close 2 +system calls. +.Bd -literal -offset indent +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); +} +.Ed +.Sh RETURN VALUES +Most functions return zero on success, non-zero on error. +The possible return codes include: +.Cm ARCHIVE_OK +(the operation succeeded), +.Cm ARCHIVE_WARN +(the operation succeeded but a non-critical error was encountered), +.Cm ARCHIVE_EOF +(end-of-archive was encountered), +.Cm ARCHIVE_RETRY +(the operation failed but can be retried), +and +.Cm ARCHIVE_FATAL +(there was a fatal error; the archive should be closed immediately). +Detailed error codes and textual descriptions are available from the +.Fn archive_errno +and +.Fn archive_error_string +functions. +.Pp +.Fn archive_read_new +returns a pointer to a freshly allocated +.Tn struct archive +object. +It returns +.Dv NULL +on error. +.Pp +.Fn archive_read_data +returns a count of bytes actually read or zero at the end of the entry. +On error, a value of +.Cm ARCHIVE_FATAL , +.Cm ARCHIVE_WARN , +or +.Cm ARCHIVE_RETRY +is returned and an error code and textual description can be retrieved from the +.Fn archive_errno +and +.Fn archive_error_string +functions. +.Pp +The library expects the client callbacks to behave similarly. +If there is an error, you can use +.Fn archive_set_error +to set an appropriate error code and description, +then return one of the non-zero values above. +(Note that the value eventually returned to the client may +not be the same; many errors that are not critical at the level +of basic I/O can prevent the archive from being properly read, +thus most I/O errors eventually cause +.Cm ARCHIVE_FATAL +to be returned.) +.\" .Sh ERRORS +.Sh SEE ALSO +.Xr tar 1 , +.Xr archive 3 , +.Xr archive_util 3 , +.Xr tar 5 +.Sh HISTORY +The +.Nm libarchive +library first appeared in +.Fx 5.3 . +.Sh AUTHORS +.An -nosplit +The +.Nm libarchive +library was written by +.An Tim Kientzle Aq kientzle@acm.org . +.Sh BUGS +Many traditional archiver programs treat +empty files as valid empty archives. +For example, many implementations of +.Xr 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 +.Dq empty +format. diff --git a/archivers/libarchive/files/doc/man/archive_util.3 b/archivers/libarchive/files/doc/man/archive_util.3 new file mode 100644 index 00000000000..b8a030e4932 --- /dev/null +++ b/archivers/libarchive/files/doc/man/archive_util.3 @@ -0,0 +1,146 @@ +.\" Copyright (c) 2003-2007 Tim Kientzle +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: src/lib/libarchive/archive_util.3,v 1.7 2007/05/29 01:00:19 kientzle Exp $ +.\" +.Dd January 8, 2005 +.Dt archive_util 3 +.Os +.Sh NAME +.Nm archive_clear_error , +.Nm archive_compression , +.Nm archive_compression_name , +.Nm archive_copy_error , +.Nm archive_errno , +.Nm archive_error_string , +.Nm archive_format , +.Nm archive_format_name , +.Nm archive_set_error +.Nd libarchive utility functions +.Sh SYNOPSIS +.In archive.h +.Ft void +.Fn archive_clear_error "struct archive *" +.Ft int +.Fn archive_compression "struct archive *" +.Ft const char * +.Fn archive_compression_name "struct archive *" +.Ft void +.Fn archive_copy_error "struct archive *" "struct archive *" +.Ft int +.Fn archive_errno "struct archive *" +.Ft const char * +.Fn archive_error_string "struct archive *" +.Ft int +.Fn archive_format "struct archive *" +.Ft const char * +.Fn archive_format_name "struct archive *" +.Ft void +.Fn archive_set_error "struct archive *" "int error_code" "const char *fmt" "..." +.Sh DESCRIPTION +These functions provide access to various information about the +.Tn struct archive +object used in the +.Xr libarchive 3 +library. +.Bl -tag -compact -width indent +.It Fn archive_clear_error +Clears any error information left over from a previous call. +Not generally used in client code. +.It Fn archive_compression +Returns a numeric code indicating the current compression. +This value is set by +.Fn archive_read_open . +.It Fn archive_compression_name +Returns a text description of the current compression suitable for display. +.It Fn archive_copy_error +Copies error information from one archive to another. +.It Fn archive_errno +Returns a numeric error code (see +.Xr errno 2 ) +indicating the reason for the most recent error return. +.It Fn 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 +.Fn archive_errno +to +.Xr strerror 3 . +.It Fn archive_format +Returns a numeric code indicating the format of the current +archive entry. +This value is set by a successful call to +.Fn 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. +.It Fn archive_format_name +A textual description of the format of the current entry. +.It Fn archive_set_error +Sets the numeric error code and error description that will be returned +by +.Fn archive_errno +and +.Fn archive_error_string . +This function should be used within I/O callbacks to set system-specific +error codes and error descriptions. +This function accepts a printf-like format string and arguments. +However, you should be careful to use only the following printf +format specifiers: +.Dq %c , +.Dq %d , +.Dq %jd , +.Dq %jo , +.Dq %ju , +.Dq %jx , +.Dq %ld , +.Dq %lo , +.Dq %lu , +.Dq %lx , +.Dq %o , +.Dq %u , +.Dq %s , +.Dq %x , +.Dq %% . +Field-width specifiers and other printf features are +not uniformly supported and should not be used. +.El +.Sh SEE ALSO +.Xr archive_read 3 , +.Xr archive_write 3 , +.Xr libarchive 3 , +.Xr printf 3 +.Sh HISTORY +The +.Nm libarchive +library first appeared in +.Fx 5.3 . +.Sh AUTHORS +.An -nosplit +The +.Nm libarchive +library was written by +.An Tim Kientzle Aq kientzle@acm.org . diff --git a/archivers/libarchive/files/doc/man/archive_write.3 b/archivers/libarchive/files/doc/man/archive_write.3 new file mode 100644 index 00000000000..c07b6b570ea --- /dev/null +++ b/archivers/libarchive/files/doc/man/archive_write.3 @@ -0,0 +1,524 @@ +.\" Copyright (c) 2003-2007 Tim Kientzle +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: src/lib/libarchive/archive_write.3,v 1.22 2007/05/29 01:00:19 kientzle Exp $ +.\" +.Dd August 19, 2006 +.Dt archive_write 3 +.Os +.Sh NAME +.Nm archive_write_new , +.Nm archive_write_set_format_cpio , +.Nm archive_write_set_format_pax , +.Nm archive_write_set_format_pax_restricted , +.Nm archive_write_set_format_shar , +.Nm archive_write_set_format_shar_binary , +.Nm archive_write_set_format_ustar , +.Nm archive_write_get_bytes_per_block , +.Nm archive_write_set_bytes_per_block , +.Nm archive_write_set_bytes_in_last_block , +.Nm archive_write_set_compression_bzip2 , +.Nm archive_write_set_compression_gzip , +.Nm archive_write_set_compression_none , +.Nm archive_write_set_compression_program , +.Nm archive_write_open , +.Nm archive_write_open_fd , +.Nm archive_write_open_FILE , +.Nm archive_write_open_filename , +.Nm archive_write_open_memory , +.Nm archive_write_header , +.Nm archive_write_data , +.Nm archive_write_finish_entry , +.Nm archive_write_close , +.Nm archive_write_finish +.Nd functions for creating archives +.Sh SYNOPSIS +.In archive.h +.Ft struct archive * +.Fn archive_write_new "void" +.Ft int +.Fn archive_write_get_bytes_per_block "struct archive *" +.Ft int +.Fn archive_write_set_bytes_per_block "struct archive *" "int bytes_per_block" +.Ft int +.Fn archive_write_set_bytes_in_last_block "struct archive *" "int" +.Ft int +.Fn archive_write_set_compression_bzip2 "struct archive *" +.Ft int +.Fn archive_write_set_compression_gzip "struct archive *" +.Ft int +.Fn archive_write_set_compression_none "struct archive *" +.Ft int +.Fn archive_write_set_compression_program "struct archive *" "const char * cmd" +.Ft int +.Fn archive_write_set_format_cpio "struct archive *" +.Ft int +.Fn archive_write_set_format_pax "struct archive *" +.Ft int +.Fn archive_write_set_format_pax_restricted "struct archive *" +.Ft int +.Fn archive_write_set_format_shar "struct archive *" +.Ft int +.Fn archive_write_set_format_shar_binary "struct archive *" +.Ft int +.Fn archive_write_set_format_ustar "struct archive *" +.Ft int +.Fn archive_write_open "struct archive *" "void *client_data" "archive_open_callback *" "archive_write_callback *" "archive_close_callback *" +.Ft int +.Fn archive_write_open_fd "struct archive *" "int fd" +.Ft int +.Fn archive_write_open_FILE "struct archive *" "FILE *file" +.Ft int +.Fn archive_write_open_filename "struct archive *" "const char *filename" +.Ft int +.Fn archive_write_open_memory "struct archive *" "void *buffer" "size_t bufferSize" "size_t *outUsed" +.Ft int +.Fn archive_write_header "struct archive *" "struct archive_entry *" +.Ft ssize_t +.Fn archive_write_data "struct archive *" "const void *" "size_t" +.Ft int +.Fn archive_write_finish_entry "struct archive *" +.Ft int +.Fn archive_write_close "struct archive *" +.Ft int +.Fn archive_write_finish "struct archive *" +.Sh DESCRIPTION +These functions provide a complete API for creating streaming +archive files. +The general process is to first create the +.Tn struct archive +object, set any desired options, initialize the archive, append entries, then +close the archive and release all resources. +The following summary describes the functions in approximately +the order they are ordinarily used: +.Bl -tag -width indent +.It Fn archive_write_new +Allocates and initializes a +.Tn struct archive +object suitable for writing a tar archive. +.It Fn 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. +.It Fn 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. +.It Fn archive_write_set_bytes_in_last_block +Sets the block size used for writing the last block. +If this value is zero, the last block will be padded to the same size +as the other blocks. +Otherwise, the final block will be padded to a multiple of this size. +In particular, setting it to 1 will cause the final block to not be padded. +For compressed output, any padding generated by this option +is applied only after the compression. +The uncompressed data is always unpadded. +The default is to pad the last block to the full block size (note that +.Fn archive_write_open_filename +will set this based on the file type). +Unlike the other +.Dq set +functions, this function can be called after the archive is opened. +.It Fn 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. +.It Fn archive_write_set_format_cpio , Fn archive_write_set_format_pax , Fn archive_write_set_format_pax_restricted , Fn archive_write_set_format_shar , Fn archive_write_set_format_shar_binary , Fn archive_write_set_format_ustar +Sets the format that will be used for the archive. +The library can write +POSIX octet-oriented cpio format archives, +POSIX-standard +.Dq pax interchange +format archives, +traditional +.Dq shar +archives, +enhanced +.Dq binary +shar archives that store a variety of file attributes and handle binary files, +and +POSIX-standard +.Dq 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. +.Dq 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. +.It Fn archive_write_set_compression_bzip2 , Fn archive_write_set_compression_gzip , Fn archive_write_set_compression_none +The resulting archive will be compressed as specified. +Note that the compressed output is always properly blocked. +.It Fn 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. +.It Fn archive_write_open +Freeze the settings, open the archive, and prepare for writing entries. +This is the most generic form of this function, which accepts +pointers to three callback functions which will be invoked by +the compression layer to write the constructed archive. +.It Fn archive_write_open_fd +A convenience form of +.Fn archive_write_open +that accepts a file descriptor. +The +.Fn archive_write_open_fd +function is safe for use with tape drives or other +block-oriented devices. +.It Fn archive_write_open_FILE +A convenience form of +.Fn archive_write_open +that accepts a +.Ft "FILE *" +pointer. +Note that +.Fn archive_write_open_FILE +is not safe for writing to tape drives or other devices +that require correct blocking. +.It Fn archive_write_open_file +A deprecated synonym for +.Fn archive_write_open_filename . +.It Fn archive_write_open_filename +A convenience form of +.Fn archive_write_open +that accepts a filename. +A NULL argument indicates that the output should be written to standard output; +an argument of +.Dq - +will open a file with that name. +If you have not invoked +.Fn archive_write_set_bytes_in_last_block , +then +.Fn 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 +.Fn archive_write_set_bytes_in_last_block +before calling +.Fn archive_write_open . +The +.Fn archive_write_open_filename +function is safe for use with tape drives or other +block-oriented devices. +.It Fn archive_write_open_memory +A convenience form of +.Fn archive_write_open +that accepts a pointer to a block of memory that will receive +the archive. +The final +.Ft "size_t *" +argument points to a variable that will be updated +after each write to reflect how much of the buffer +is currently in use. +You should be careful to ensure that this variable +remains allocated until after the archive is +closed. +.It Fn archive_write_header +Build and write a header using the data in the provided +.Tn struct archive_entry +structure. +See +.Xr archive_entry 3 +for information on creating and populating +.Tn struct archive_entry +objects. +.It Fn archive_write_data +Write data corresponding to the header just written. +Returns number of bytes written or -1 on error. +.It Fn 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 +.Fn archive_write_next_header +and +.Fn archive_write_close +as needed. +.It Fn archive_write_close +Complete the archive and invoke the close callback. +.It Fn archive_write_finish +Invokes +.Fn archive_write_close +if it was not invoked manually, then releases all resources. +Note that this function was declared to return +.Ft void +in libarchive 1.x, which made it impossible to detect errors when +.Fn archive_write_close +was invoked implicitly from this function. +This is corrected beginning with libarchive 2.0. +.El +More information about the +.Va struct archive +object and the overall design of the library can be found in the +.Xr libarchive 3 +overview. +.Sh IMPLEMENTATION +Compression support is built-in to libarchive, which uses zlib and bzlib +to handle gzip and bzip2 compression, respectively. +.Sh CLIENT CALLBACKS +To use this library, you will need to define and register +callback functions that will be invoked to write data to the +resulting archive. +These functions are registered by calling +.Fn archive_write_open : +.Bl -item -offset indent +.It +.Ft typedef int +.Fn archive_open_callback "struct archive *" "void *client_data" +.El +.Pp +The open callback is invoked by +.Fn archive_write_open . +It should return +.Cm ARCHIVE_OK +if the underlying file or data source is successfully +opened. +If the open fails, it should call +.Fn archive_set_error +to register an error code and message and return +.Cm ARCHIVE_FATAL . +.Bl -item -offset indent +.It +.Ft typedef ssize_t +.Fn archive_write_callback "struct archive *" "void *client_data" "void *buffer" "size_t length" +.El +.Pp +The write callback is invoked whenever the library +needs to write raw bytes to the archive. +For correct blocking, each call to the write callback function +should translate into a single +.Xr 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 +.Fn archive_set_error +to register an error code and message and return -1. +.Bl -item -offset indent +.It +.Ft typedef int +.Fn archive_close_callback "struct archive *" "void *client_data" +.El +.Pp +The close callback is invoked by archive_close when +the archive processing is complete. +The callback should return +.Cm ARCHIVE_OK +on success. +On failure, the callback should invoke +.Fn archive_set_error +to register an error code and message and +return +.Cm ARCHIVE_FATAL. +.Sh EXAMPLE +The following sketch illustrates basic usage of the library. +In this example, +the callback functions are simply wrappers around the standard +.Xr open 2 , +.Xr write 2 , +and +.Xr close 2 +system calls. +.Bd -literal -offset indent +#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, 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; +} +.Ed +.Sh RETURN VALUES +Most functions return +.Cm ARCHIVE_OK +(zero) on success, or one of several non-zero +error codes for errors. +Specific error codes include: +.Cm ARCHIVE_RETRY +for operations that might succeed if retried, +.Cm ARCHIVE_WARN +for unusual conditions that do not prevent further operations, and +.Cm ARCHIVE_FATAL +for serious errors that make remaining operations impossible. +The +.Fn archive_errno +and +.Fn archive_error_string +functions can be used to retrieve an appropriate error code and a +textual error message. +.Pp +.Fn archive_write_new +returns a pointer to a newly-allocated +.Tn struct archive +object. +.Pp +.Fn archive_write_data +returns a count of the number of bytes actually written. +On error, -1 is returned and the +.Fn archive_errno +and +.Fn 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 +.Fn archive_write_header , +.Fn archive_write_data , +.Fn archive_write_close , +or +.Fn archive_write_finish . +The client callback can call +.Fn archive_set_error +to provide values that can then be retrieved by +.Fn archive_errno +and +.Fn archive_error_string . +.Sh SEE ALSO +.Xr tar 1 , +.Xr libarchive 3 , +.Xr tar 5 +.Sh HISTORY +The +.Nm libarchive +library first appeared in +.Fx 5.3 . +.Sh AUTHORS +.An -nosplit +The +.Nm libarchive +library was written by +.An Tim Kientzle Aq kientzle@acm.org . +.Sh 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. +.Pp +The default pax interchange format eliminates most of the historic +tar limitations and provides a generic key/value attribute facility +for vendor-defined extensions. +One oversight in POSIX is the failure to provide a standard attribute +for large device numbers. +This library uses +.Dq SCHILY.devminor +and +.Dq SCHILY.devmajor +for device numbers that exceed the range supported by the backwards-compatible +ustar header. +These keys are compatible with Joerg Schilling's +.Nm star +archiver. +Other implementations may not recognize these keys and will thus be unable +to correctly restore device nodes with large device numbers from archives +created by this library. diff --git a/archivers/libarchive/files/doc/man/archive_write_disk.3 b/archivers/libarchive/files/doc/man/archive_write_disk.3 new file mode 100644 index 00000000000..880a399b949 --- /dev/null +++ b/archivers/libarchive/files/doc/man/archive_write_disk.3 @@ -0,0 +1,358 @@ +.\" Copyright (c) 2003-2007 Tim Kientzle +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: src/lib/libarchive/archive_write_disk.3,v 1.1 2007/03/03 07:37:36 kientzle Exp $ +.\" +.Dd March 2, 2007 +.Dt archive_write_disk 3 +.Os +.Sh NAME +.Nm archive_write_disk_new , +.Nm archive_write_disk_set_options , +.Nm archive_write_disk_set_skip_file , +.Nm archive_write_disk_set_group_lookup , +.Nm archive_write_disk_set_standard_lookup , +.Nm archive_write_disk_set_user_lookup , +.Nm archive_write_header , +.Nm archive_write_data , +.Nm archive_write_finish_entry , +.Nm archive_write_close , +.Nm archive_write_finish +.Nd functions for creating objects on disk +.Sh SYNOPSIS +.In archive.h +.Ft struct archive * +.Fn archive_write_disk_new "void" +.Ft int +.Fn archive_write_disk_set_options "struct archive *" "int flags" +.Ft int +.Fn archive_write_disk_set_skip_file "struct archive *" "dev_t" "ino_t" +.Ft int +.Fn archive_write_disk_set_group_lookup "struct archive *" "void *" "gid_t (*)(void *, const char *gname, gid_t gid)" "void (*cleanup)(void *)" +.Ft int +.Fn archive_write_disk_set_standard_lookup "struct archive *" +.Ft int +.Fn archive_write_disk_set_user_lookup "struct archive *" "void *" "uid_t (*)(void *, const char *uname, uid_t uid)" "void (*cleanup)(void *)" +.Ft int +.Fn archive_write_header "struct archive *" "struct archive_entry *" +.Ft ssize_t +.Fn archive_write_data "struct archive *" "const void *" "size_t" +.Ft int +.Fn archive_write_finish_entry "struct archive *" +.Ft int +.Fn archive_write_close "struct archive *" +.Ft int +.Fn archive_write_finish "struct archive *" +.Sh DESCRIPTION +These functions provide a complete API for creating objects on +disk from +.Tn struct archive_entry +descriptions. +They are most naturally used when extracting objects from an archive +using the +.Fn archive_read +interface. +The general process is to read +.Tn struct archive_entry +objects from an archive, then write those objects to a +.Tn struct archive +object created using the +.Fn archive_write_disk +family functions. +This interface is deliberately very similar to the +.Fn archive_write +interface used to write objects to a streaming archive. +.Bl -tag -width indent +.It Fn archive_write_disk_new +Allocates and initializes a +.Tn struct archive +object suitable for writing objects to disk. +.It Fn 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. +.It Fn archive_write_disk_set_options +The options field consists of a bitwise OR of one or more of the +following values: +.Bl -tag -compact -width "indent" +.It Cm 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. +.It Cm 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 +.Cm ARCHIVE_EXTRACT_OWNER +is not specified, then SUID and SGID bits will only be restored +if the default user and group IDs of newly-created objects on disk +happen to match those specified in the archive entry. +By default, only basic permissions are restored, and umask is obeyed. +.It Cm 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. +.It Cm ARCHIVE_EXTRACT_NO_OVERWRITE +Existing files on disk will not be overwritten. +By default, existing regular files are truncated and overwritten; +existing directories will have their permissions updated; +other pre-existing objects are unlinked and recreated from scratch. +.It Cm 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. +.It Cm ARCHIVE_EXTRACT_ACL +Attempt to restore ACLs. +By default, extended ACLs are ignored. +.It Cm ARCHIVE_EXTRACT_FFLAGS +Attempt to restore extended file flags. +By default, file flags are ignored. +.It Cm ARCHIVE_EXTRACT_XATTR +Attempt to restore POSIX.1e extended attributes. +By default, they are ignored. +.It Cm ARCHIVE_EXTRACT_SECURE_SYMLINKS +Refuse to extract any object whose final location would be altered +by a symlink on disk. +This is intended to help guard against a variety of mischief +caused by archives that (deliberately or otherwise) extract +files outside of the current directory. +The default is not to perform this check. +If +.Cm ARCHIVE_EXTRACT_UNLINK +is specified together with this option, the library will +remove any intermediate symlinks it finds and return an +error only if such symlink could not be removed. +.It Cm ARCHIVE_EXTRACT_SECURE_NODOTDOT +Refuse to extract a path that contains a +.Pa .. +element anywhere within it. +The default is to not refuse such paths. +Note that paths ending in +.Pa .. +always cause an error, regardless of this flag. +.El +.It Fn archive_write_disk_set_group_lookup , Fn archive_write_disk_set_user_lookup +The +.Tn struct archive_entry +objects contain both names and ids that can be used to identify users +and groups. +These names and ids describe the ownership of the file itself and +also appear in ACL lists. +By default, the library uses the ids and ignores the names, but +this can be overridden by registering user and group lookup functions. +To register, you must provide a lookup function which +accepts both a name and id and returns a suitable id. +You may also provide a +.Tn void * +pointer to a private data structure and a cleanup function for +that data. +The cleanup function will be invoked when the +.Tn struct archive +object is destroyed. +.It Fn archive_write_disk_set_standard_lookup +This convenience function installs a standard set of user +and group lookup functions. +These functions use +.Xr getpwnam 3 +and +.Xr getgrnam 3 +to convert names to ids, defaulting to the ids if the names cannot +be looked up. +These functions also implement a simple memory cache to reduce +the number of calls to +.Xr getpwnam 3 +and +.Xr getgrnam 3 . +.It Fn archive_write_header +Build and write a header using the data in the provided +.Tn struct archive_entry +structure. +See +.Xr archive_entry 3 +for information on creating and populating +.Tn struct archive_entry +objects. +.It Fn archive_write_data +Write data corresponding to the header just written. +Returns number of bytes written or -1 on error. +.It Fn archive_write_finish_entry +Close out the entry just written. +Ordinarily, clients never need to call this, as it +is called automatically by +.Fn archive_write_next_header +and +.Fn archive_write_close +as needed. +.It Fn archive_write_close +Set any attributes that could not be set during the initial restore. +For example, directory timestamps are not restored initially because +restoring a subsequent file would alter that timestamp. +Similarly, non-writable directories are initially created with +write permissions (so that their contents can be restored). +The +.Nm +library maintains a list of all such deferred attributes and +sets them when this function is invoked. +.It Fn archive_write_finish +Invokes +.Fn archive_write_close +if it was not invoked manually, then releases all resources. +.El +More information about the +.Va struct archive +object and the overall design of the library can be found in the +.Xr libarchive 3 +overview. +Many of these functions are also documented under +.Xr archive_write 3 . +.Sh RETURN VALUES +Most functions return +.Cm ARCHIVE_OK +(zero) on success, or one of several non-zero +error codes for errors. +Specific error codes include: +.Cm ARCHIVE_RETRY +for operations that might succeed if retried, +.Cm ARCHIVE_WARN +for unusual conditions that do not prevent further operations, and +.Cm ARCHIVE_FATAL +for serious errors that make remaining operations impossible. +The +.Fn archive_errno +and +.Fn archive_error_string +functions can be used to retrieve an appropriate error code and a +textual error message. +.Pp +.Fn archive_write_disk_new +returns a pointer to a newly-allocated +.Tn struct archive +object. +.Pp +.Fn archive_write_data +returns a count of the number of bytes actually written. +On error, -1 is returned and the +.Fn archive_errno +and +.Fn archive_error_string +functions will return appropriate values. +.Sh SEE ALSO +.Xr archive_read 3 , +.Xr archive_write 3 , +.Xr tar 1 , +.Xr libarchive 3 +.Sh HISTORY +The +.Nm libarchive +library first appeared in +.Fx 5.3 . +The +.Nm archive_write_disk +interface was added to +.Nm libarchive 2.0 +and first appeared in +.Fx 6.3 . +.Sh AUTHORS +.An -nosplit +The +.Nm libarchive +library was written by +.An Tim Kientzle Aq kientzle@acm.org . +.Sh BUGS +Directories are actually extracted in two distinct phases. +Directories are created during +.Fn archive_write_header , +but final permissions are not set until +.Fn archive_write_close . +This separation is necessary to correctly handle borderline +cases such as a non-writable directory containing +files, but can cause unexpected results. +In particular, directory permissions are not fully +restored until the archive is closed. +If you use +.Xr chdir 2 +to change the current directory between calls to +.Fn archive_read_extract +or before calling +.Fn archive_read_close , +you may confuse the permission-setting logic with +the result that directory permissions are restored +incorrectly. +.Pp +The library attempts to create objects with filenames longer than +.Cm 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. +.Pp +Restoring the path +.Pa aa/../bb +does create each intermediate directory. +In particular, the directory +.Pa aa +is created as well as the final object +.Pa 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 +.Cm ARCHIVE_EXTRACT_NODOTDOT +option is specified. +.Pp +Implicit directories are always created obeying the current umask. +Explicit objects are created obeying the current umask unless +.Cm ARCHIVE_EXTRACT_PERM +is specified, in which case they current umask is ignored. +.Pp +SGID and SUID bits are restored only if the correct user and +group could be set. +If +.Cm 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. +.Pp +The +.Dq standard +user-id and group-id lookup functions are not the defaults because +.Xr getgrnam 3 +and +.Xr getpwnam 3 +are sometimes too large for particular applications. +The current design allows the application author to use a more +compact implementation when appropriate. +.Pp +There should be a corresponding +.Nm archive_read_disk +interface that walks a directory heirarchy and returns archive +entry objects.
\ No newline at end of file diff --git a/archivers/libarchive/files/doc/man/bsdcpio.1 b/archivers/libarchive/files/doc/man/bsdcpio.1 new file mode 100644 index 00000000000..58fc9bf5c1f --- /dev/null +++ b/archivers/libarchive/files/doc/man/bsdcpio.1 @@ -0,0 +1,362 @@ +.\" Copyright (c) 2003-2007 Tim Kientzle +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd August 05, 2007 +.Dt BSDCPIO 1 +.Os +.Sh NAME +.Nm cpio +.Nd copy files to and from archives +.Sh SYNOPSIS +.Nm +.Brq Fl i +.Op Ar options +.Op Ar pattern ... +.Op Ar < archive +.Nm +.Brq Fl o +.Op Ar options +.Ar < name-list +.Op Ar > archive +.Nm +.Brq Fl p +.Op Ar options +.Ar dest-dir +.Ar < name-list +.Sh DESCRIPTION +.Nm +copies files between archives and directories. +This implementation can extract from tar, pax, cpio, zip, jar, ar, +and ISO 9660 cdrom images and can create tar, pax, cpio, ar, +and shar archives. +.Pp +The first option to +.Nm +is a mode indicator from the following list: +.Bl -tag -compact -width indent +.It Fl i +Input. +Read an archive from standard input and extract the contents to disk or +(if the +.Fl t +option is specified) +list the contents to standard output. +.It Fl o +Output. +Read a list of filenames from standard input and produce a new archive +on standard output containing the specified items. +If one or more file patterns are specified, only files matching +one of the patterns will be extracted. +.It Fl p +Pass-through. +Read a list of filenames from standard input and copy the files to the +specified directory. +.El +.Pp +.Sh OPTIONS +Unless specifically stated otherwise, options are applicable in +all operating modes. +.Bl -tag -width indent +.It Fl a +(o and p modes) +Reset access times on files after they are read. +(Not yet implemented) +.It Fl B +(o mode only) +Block output to records of 5120 bytes. +.It Fl c +(o mode only) +Use the old POSIX portable character format. +Equivalent to +.Fl -format Ar odc . +.It Fl d +(i and p modes) +Create directories as necessary. +.It Fl f Ar pattern +(i mode only) +Ignore files that match +.Ar pattern . +(Not yet implemented.) +.It Fl -format Ar format +(o mode only) +Produce the output archive in the specified format. +Supported formats include: +.Pp +.Bl -tag -width "iso9660" -compact +.It Ar cpio +Synonym for +.Ar odc . +.It Ar newc +The SVR4 portable cpio format. +.It Ar odc +The old POSIX.1 portable octet-oriented cpio format. +.It Ar pax +The POSIX.1 pax format, an extension of the ustar format. +.It Ar ustar +The POSIX.1 tar format. +.El +.Pp +The default format is +.Ar odc . +See +.Xr libarchive_formats 5 +for more complete information about the +formats currently supported by the underlying +.Xr libarchive 3 +library. +.It Fl i +Input mode. +See above for description. +.It Fl 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. +(Not yet implemented.) +.It Fl l +(p mode only) +Create links from the target directory to the original files, +instead of copying. +.It Fl m +(i and p modes) +Set file modification time on created files to match +those in the source. +.It Fl o +Output mode. +See above for description. +.It Fl p +Pass-through mode. +See above for description. +.It Fl -quiet +(Not yet implemented.) +.It Fl R Oo user Oc Ns Oo : Oc Ns Oo group Oc +Set the owner and/or group on files in the output. +If group is specified with no user +(for example, +.Fl R Ar :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, +.Fl R Ar 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 +.Fl i +and +.Fl p +modes, this option can only be used by the super-user. +(For compatibility, a period can be used in place of the colon.) +.It Fl r +(All modes.) +Rename files interactively. +For each file, a prompt is written to +.Pa /dev/tty +containing the name of the file and a line is read from +.Pa /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. +.It Fl t +(i mode only) +List the contents of the archive to stdout; +do not restore the contents to disk. +.It Fl u +(i and p modes) +Unconditionally overwrite existing files. +Ordinarily, an older file will not overwrite a newer file on disk. +.It Fl v +Print the name of each file to stderr as it is processed. +With +.Fl t , +provide a detailed listing of each file. +.It Fl -version +Print the program version information and exit. +.It Fl y +(o mode only) +Compress the archive with bzip2-compatible compression before +writing to stdout. +In input mode, this option is ignored; +bzip2 compression is recognized automatically on input. +.It Fl z +(o mode only) +Compress the archive with gzip-compatible compression before writing +it to stdout. +In input mode, this option is ignored; +gzip compression is recognized automatically on input. +.El +.Sh ENVIRONMENT +The following environment variables affect the execution of +.Nm : +.Bl -tag -width ".Ev BLOCKSIZE" +.It Ev LANG +The locale to use. +See +.Xr environ 7 +for more information. +.It Ev TZ +The timezone to use when displaying dates. +See +.Xr environ 7 +for more information. +.El +.Sh EXIT STATUS +.Ex -std +.Sh EXAMPLES +The +.Nm +command is traditionally used to copy file heirarchies in conjunction +with the +.Xr find 1 +command. +The first example here simply copies all files from +.Pa src +to +.Pa dest : +.Dl Nm find Pa src | Nm Fl pmud Pa dest +.Pp +By carefully selecting options to the +.Xr find 1 +command and combining it with other standard utilities, +it is possible to exercise very fine control over which files are copied. +This next example copies files from +.Pa src +to +.Pa dest +that are more than 2 days old and whose names match a particular pattern: +.Dl Nm find Pa src Fl mtime Ar +2 | Nm grep foo[bar] | Nm Fl pdmu Pa dest +.Pp +This example copies files from +.Pa src +to +.Pa dest +that are more than 2 days old and which contain the word +.Do foobar Dc : +.Dl Nm find Pa src Fl mtime Ar +2 | Nm xargs Nm grep -l foobar | Nm Fl pdmu Pa dest +.Sh 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. +.Pp +The old POSIX.1 standard specified that only +.Fl i , +.Fl o , +and +.Fl p +were interpreted as command-line options. +Each took a single argument of a list of modifier +characters. +For example, the standard syntax allows +.Fl imu +but does not support +.Fl miu +or +.Fl i Fl m Fl u , +since +.Ar m +and +.Ar u +are only modifiers to +.Fl i , +they are not command-line options in their own right. +The syntax supported by this implementation is backwards-compatible +with the standard. +For best compatibility, scripts should limit themselves to the +standard syntax. +.Sh SEE ALSO +.Xr bzip2 1 , +.Xr tar 1 , +.Xr gzip 1 , +.Xr mt 1 , +.Xr pax 1 , +.Xr libarchive 3 , +.Xr cpio 5 , +.Xr libarchive-formats 5 , +.Xr tar 5 +.Sh STANDARDS +There is no current POSIX standard for the cpio command; it appeared +in +.St -p1003.1-96 +but was dropped from +.St -p1003.1-2001 . +.Pp +The cpio, ustar, and pax interchange file formats are defined by +.St -p1003.1-2001 +for the pax command. +.Sh HISTORY +The original +.Nm cpio +and +.Nm find +utilities were written by Dick Haight +while working in AT&T's Unix Support Group. +They first appeared in PWB/UNIX 1.0, the +.Dq Programmer's Work Bench +system developed for use within AT&T and released in 1977. +XXX It was first released outside of AT&T +as part of System III Unix in 1981. XXX +XXX Need to verify the previous statement. XXX +As a result, +.Nm cpio +actually predates +.Nm tar , +even though it was not well-known outside of AT&T +until some time later. +XXX When did cpio first appear in BSD? XXX +.Pp +This is a complete re-implementation based on the +.Xr libarchive 3 +library. +.Sh BUGS +The cpio archive format has several basic limitations: +It does not store user and group names, only numbers. +As a result, it cannot be reliably used to transfer +files between systems with dissimilar user and group numbering. +Older cpio formats limit the user and group numbers to +16 or 18 bits, which is insufficient for modern systems. +The cpio archive formats cannot support files over 4 gigabytes, +except for the +.Dq odc +variant, which can support files up to 8 gigabytes. +.Pp +This is an early alpha version of +.Nm . +The underlying +.Nm libarchive +library is quite mature, so the archive format support +and creation of objects on disk should be robust. +However, the cpio-specific options and features +are still very new. +Known issues that will be fixed soon: +.Bl -bullet -offset indent -compact +.It +Options documented above as +.Do Not yet implemented Dc . +.It +Filter arguments to +.Fl i , +and +.Fl it . +.El diff --git a/archivers/libarchive/files/doc/man/bsdtar.1 b/archivers/libarchive/files/doc/man/bsdtar.1 new file mode 100644 index 00000000000..db6a10aa1ca --- /dev/null +++ b/archivers/libarchive/files/doc/man/bsdtar.1 @@ -0,0 +1,769 @@ +.\" Copyright (c) 2003-2007 Tim Kientzle +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: src/usr.bin/tar/bsdtar.1,v 1.35 2007/05/29 05:39:10 kientzle Exp $ +.\" +.Dd April 13, 2004 +.Dt BSDTAR 1 +.Os +.Sh NAME +.Nm tar +.Nd manipulate tape archives +.Sh SYNOPSIS +.Nm +.Op Ar bundled-flags Ao args Ac +.Op Ao Ar file Ac | Ao Ar pattern Ac ... +.Nm +.Brq Fl c +.Op Ar options +.Op Ar files | directories +.Nm +.Brq Fl r | Fl u +.Fl f Ar archive-file +.Op Ar options +.Op Ar files | directories +.Nm +.Brq Fl t | Fl x +.Op Ar options +.Op Ar patterns +.Sh DESCRIPTION +.Nm +creates and manipulates streaming archive files. +This implementation can extract from tar, pax, cpio, zip, jar, ar, +and ISO 9660 cdrom images and can create tar, pax, cpio, ar, +and shar archives. +.Pp +The first synopsis form shows a +.Dq bundled +option word. +This usage is provided for compatibility with historical implementations. +See COMPATIBILITY below for details. +.Pp +The other synopsis forms show the preferred usage. +The first option to +.Nm +is a mode indicator from the following list: +.Bl -tag -compact -width indent +.It Fl c +Create a new archive containing the specified items. +.It Fl r +Like +.Fl c , +but new entries are appended to the archive. +Note that this only works on uncompressed archives stored in regular files. +The +.Fl f +option is required. +.It Fl t +List archive contents to stdout. +.It Fl u +Like +.Fl r , +but new entries are added only if they have a modification date +newer than the corresponding entry in the archive. +Note that this only works on uncompressed archives stored in regular files. +The +.Fl f +option is required. +.It Fl 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. +.El +.Pp +In +.Fl c , +.Fl r , +or +.Fl u +mode, each specified file or directory is added to the +archive in the order specified on the command line. +By default, the contents of each directory are also archived. +.Pp +In extract or list mode, the entire command line +is read and parsed before the archive is opened. +The pathnames or patterns on the command line indicate +which items in the archive should be processed. +Patterns are shell-style globbing patterns as +documented in +.Xr tcsh 1 . +.Sh OPTIONS +Unless specifically stated otherwise, options are applicable in +all operating modes. +.Bl -tag -width indent +.It Cm @ Ns Pa archive +(c and r mode only) +The specified archive is opened and the entries +in it will be appended to the current archive. +As a simple example, +.Dl Nm Fl c Fl f Pa - Pa newfile Cm @ Ns Pa original.tar +writes a new archive to standard output containing a file +.Pa newfile +and all of the entries from +.Pa original.tar . +In contrast, +.Dl Nm Fl c Fl f Pa - Pa newfile Pa original.tar +creates a new archive with only two entries. +Similarly, +.Dl Nm Fl czf Pa - Fl -format Cm pax Cm @ Ns Pa - +reads an archive from standard input (whose format will be determined +automatically) and converts it into a gzip-compressed +pax-format archive on stdout. +In this way, +.Nm +can be used to convert archives from one format to another. +.It Fl b Ar 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. +.It Fl C Ar 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. +.It Fl -check-links ( Fl W Cm check-links ) +(c and r modes only) +Issue a warning message unless all links to each file are archived. +.It Fl -exclude Ar pattern ( Fl W Cm exclude Ns = Ns Ar pattern ) +Do not process files or directories that match the +specified pattern. +Note that exclusions take precedence over patterns or filenames +specified on the command line. +.It Fl -format Ar format ( Fl W Cm format Ns = Ns Ar format ) +(c mode only) +Use the specified format for the created archive. +Supported formats include +.Dq cpio , +.Dq pax , +.Dq shar , +and +.Dq ustar . +Other formats may also be supported; see +.Xr libarchive-formats 5 +for more information about currently-supported formats. +.It Fl f Ar file +Read the archive from or write the archive to the specified file. +The filename can be +.Pa - +for standard input or standard output. +If not specified, the default tape device will be used. +(On +.Fx , +the default tape device is +.Pa /dev/sa0 . ) +.It Fl -fast-read ( Fl W Cm 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. +.It Fl 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. +.It Fl h +(c and r mode only) +Synonym for +.Fl L . +.It Fl I +Synonym for +.Fl T . +.It Fl -include Ar pattern ( Fl W Cm include Ns = Ns Ar pattern ) +Process only files or directories that match the specified pattern. +Note that exclusions specified with +.Fl -exclude +take precedence over inclusions. +If no inclusions are explicitly specified, all entries are processed by +default. +The +.Fl -include +option is especially useful when filtering archives. +For example, the command +.Dl Nm Fl c Fl f Pa new.tar Fl -include='*foo*' Cm @ Ns Pa old.tgz +creates a new archive +.Pa new.tar +containing only the entries from +.Pa old.tgz +containing the string +.Sq foo . +.It Fl j +(c mode only) +Compress the resulting archive with +.Xr bzip2 1 . +In extract or list modes, this option is ignored. +Note that, unlike other +.Nm tar +implementations, this implementation recognizes bzip2 compression +automatically when reading archives. +.It Fl 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. +.It Fl L +(c and r mode only) +All symbolic links will be followed. +Normally, symbolic links are archived as such. +With this option, the target of the link will be archived instead. +.It Fl l +If +.Ev POSIXLY_CORRECT +is specified in the environment, this is a synonym for the +.Fl -check-links +option. +Otherwise, an error will be displayed. +Users who desire behavior compatible with GNU tar should use +the +.Fl -one-file-system +option instead. +.It Fl m +(x mode only) +Do not extract modification time. +By default, the modification time is set to the time stored in the archive. +.It Fl n +(c, r, u modes only) +Do not recursively archive the contents of directories. +.It Fl -newer Ar date ( Fl W Cm newer Ns = Ns Ar date ) +(c, r, u modes only) +Only include files and directories newer than the specified date. +This compares ctime entries. +.It Fl -newer-mtime Ar date ( Fl W Cm newer-mtime Ns = Ns Ar date ) +(c, r, u modes only) +Like +.Fl -newer , +except it compares mtime entries instead of ctime entries. +.It Fl -newer-than Pa file ( Fl W Cm newer-than Ns = Ns Pa file ) +(c, r, u modes only) +Only include files and directories newer than the specified file. +This compares ctime entries. +.It Fl -newer-mtime-than Pa file ( Fl W Cm newer-mtime-than Ns = Ns Pa file ) +(c, r, u modes only) +Like +.Fl -newer-than , +except it compares mtime entries instead of ctime entries. +.It Fl -nodump ( Fl W Cm nodump ) +(c and r modes only) +Honor the nodump file flag by skipping this file. +.It Fl -null ( Fl W Cm null ) +(use with +.Fl I , +.Fl T , +or +.Fl X ) +Filenames or patterns are separated by null characters, +not by newlines. +This is often used to read filenames output by the +.Fl print0 +option to +.Xr find 1 . +.It Fl 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. +.It Fl o +(x mode only) +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 +.Fl 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. +.It Fl -one-file-system ( Fl W Cm one-file-system ) +(c, r, and u modes) +Do not cross mount points. +.It Fl 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, +.Nm +will refuse to extract archive entries whose pathnames contain +.Pa .. +or whose target directory would be altered by a symlink. +This option suppresses these behaviors. +.It Fl 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 +.Nm , +the file mode is restored for newly-created regular files, and +all other types of entries receive default permissions. +If +.Nm +is being run by root, the default is to restore the owner unless the +.Fl o +option is also specified. +.It Fl -strip-components Ar count ( Fl W Cm strip-components Ns = Ns Ar count ) +(x and t mode only) +Remove the specified number of leading path elements. +Pathnames with fewer elements will be silently skipped. +Note that the pathname is edited after checking inclusion/exclusion patterns +but before security checks. +.It Fl T Ar filename +In x or t mode, +.Nm +will read the list of names to be extracted from +.Pa filename . +In c mode, +.Nm +will read names to be archived from +.Pa filename . +The special name +.Dq -C +on a line by itself will cause the current directory to be changed to +the directory specified on the following line. +Names are terminated by newlines unless +.Fl -null +is specified. +Note that +.Fl -null +also disables the special handling of lines containing +.Dq -C . +.It Fl U +(x mode only) +Unlink files before creating them. +Without this option, +.Nm +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. +.It Fl -use-compress-program Ar program +Pipe the input (in x or t mode) or the output (in c mode) through +.Pa program +instead of using the builtin compression support. +.It Fl v +Produce verbose output. +In create and extract modes, +.Nm +will list each file name as it is read from or written to +the archive. +In list mode, +.Nm +will produce output similar to that of +.Xr ls 1 . +Additional +.Fl v +options will provide additional detail. +.It Fl W Ar longopt=value +Long options (preceded by +.Fl - ) +are only supported directly on systems that have the +.Xr getopt_long 3 +function. +The +.Fl W +option can be used to access long options on systems that +do not support this function. +.It Fl w +Ask for confirmation for every action. +.It Fl X Ar filename +Read a list of exclusion patterns from the specified file. +See +.Fl -exclude +for more information about the handling of exclusions. +.It Fl y +(c mode only) +Compress the resulting archive with +.Xr bzip2 1 . +In extract or list modes, this option is ignored. +Note that, unlike other +.Nm tar +implementations, this implementation recognizes bzip2 compression +automatically when reading archives. +.It Fl z +(c mode only) +Compress the resulting archive with +.Xr gzip 1 . +In extract or list modes, this option is ignored. +Note that, unlike other +.Nm tar +implementations, this implementation recognizes gzip compression +automatically when reading archives. +.El +.Sh ENVIRONMENT +The following environment variables affect the execution of +.Nm : +.Bl -tag -width ".Ev BLOCKSIZE" +.It Ev LANG +The locale to use. +See +.Xr environ 7 +for more information. +.It Ev POSIXLY_CORRECT +If this environment variable is defined, the +.Fl l +option will be interpreted in accordance with +.St -p1003.1-96 . +.It Ev TAPE +The default tape device. +The +.Fl f +option overrides this. +.It Ev TZ +The timezone to use when displaying dates. +See +.Xr environ 7 +for more information. +.El +.Sh FILES +.Bl -tag -width ".Ev BLOCKSIZE" +.It Pa /dev/sa0 +The default tape device, if not overridden by the +.Ev TAPE +environment variable or the +.Fl f +option. +.El +.Sh EXIT STATUS +.Ex -std +.Sh EXAMPLES +The following creates a new archive +called +.Ar file.tar.gz +that contains two files +.Ar source.c +and +.Ar source.h : +.Dl Nm Fl czf Pa file.tar.gz Pa source.c Pa source.h +.Pp +To view a detailed table of contents for this +archive: +.Dl Nm Fl tvf Pa file.tar.gz +.Pp +To extract all entries from the archive on +the default tape drive: +.Dl Nm Fl x +.Pp +To examine the contents of an ISO 9660 cdrom image: +.Dl Nm Fl tf Pa image.iso +.Pp +To move file hierarchies, invoke +.Nm +as +.Dl Nm Fl cf Pa - Fl C Pa srcdir\ . | Nm Fl xpf Pa - Fl C Pa destdir +or more traditionally +.Dl cd srcdir \&; Nm Fl cf Pa -\ . | ( cd destdir \&; Nm Fl xpf Pa - ) +.Pp +In create mode, the list of files and directories to be archived +can also include directory change instructions of the form +.Cm -C Ns Pa foo/baz +and archive inclusions of the form +.Cm @ Ns Pa archive-file . +For example, the command line +.Dl Nm Fl c Fl f Pa new.tar Pa foo1 Cm @ Ns Pa old.tgz Cm -C Ns Pa /tmp Pa foo2 +will create a new archive +.Pa new.tar . +.Nm +will read the file +.Pa foo1 +from the current directory and add it to the output archive. +It will then read each entry from +.Pa old.tgz +and add those entries to the output archive. +Finally, it will switch to the +.Pa /tmp +directory and add +.Pa foo2 +to the output archive. +.Pp +The +.Fl -newer +and +.Fl -newer-mtime +switches accept a variety of common date and time specifications, including +.Dq 12 Mar 2005 7:14:29pm , +.Dq 2005-03-12 19:14 , +.Dq 5 minutes ago , +and +.Dq 19:14 PST May 1 . +.Sh COMPATIBILITY +The bundled-arguments format is supported for compatibility +with historic implementations. +It consists of an initial word (with no leading - character) in which +each character indicates an option. +Arguments follow as separate words. +The order of the arguments must match the order +of the corresponding characters in the bundled command word. +For example, +.Dl Nm Cm tbf 32 Pa file.tar +specifies three flags +.Cm t , +.Cm b , +and +.Cm f . +The +.Cm b +and +.Cm f +flags both require arguments, +so there must be two additional items +on the command line. +The +.Ar 32 +is the argument to the +.Cm b +flag, and +.Ar file.tar +is the argument to the +.Cm f +flag. +.Pp +The mode options c, r, t, u, and x and the options +b, f, l, m, o, v, and w comply with SUSv2. +.Pp +For maximum portability, scripts that invoke +.Nm tar +should use the bundled-argument format above, should limit +themselves to the +.Cm c , +.Cm t , +and +.Cm x +modes, and the +.Cm b , +.Cm f , +.Cm m , +.Cm v , +and +.Cm w +options. +.Pp +On systems that support getopt_long(), additional long options +are available to improve compatibility with other tar implementations. +.Sh SECURITY +Certain security issues are common to many archiving programs, including +.Nm . +In particular, carefully-crafted archives can request that +.Nm +extract files to locations outside of the target directory. +This can potentially be used to cause unwitting users to overwrite +files they did not intend to overwrite. +If the archive is being extracted by the superuser, any file +on the system can potentially be overwritten. +There are three ways this can happen. +Although +.Nm +has mechanisms to protect against each one, +savvy users should be aware of the implications: +.Bl -bullet -width indent +.It +Archive entries can have absolute pathnames. +By default, +.Nm +removes the leading +.Pa / +character from filenames before restoring them to guard against this problem. +.It +Archive entries can have pathnames that include +.Pa .. +components. +By default, +.Nm +will not extract files containing +.Pa .. +components in their pathname. +.It +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, +.Nm +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 +.Fl U +is specified, any intermediate symlink will also be unconditionally removed. +If neither +.Fl U +nor +.Fl P +is specified, +.Nm +will refuse to extract the entry. +.El +To protect yourself, you should be wary of any archives that +come from untrusted sources. +You should examine the contents of an archive with +.Dl Nm Fl tf Pa filename +before extraction. +You should use the +.Fl k +option to ensure that +.Nm +will not overwrite any existing files or the +.Fl U +option to remove any pre-existing files. +You should generally not extract archives while running with super-user +privileges. +Note that the +.Fl P +option to +.Nm +disables the security checks above and allows you to extract +an archive while preserving any absolute pathnames, +.Pa .. +components, or symlinks to other directories. +.Sh SEE ALSO +.Xr bzip2 1 , +.Xr cpio 1 , +.Xr gzip 1 , +.Xr mt 1 , +.Xr pax 1 , +.Xr shar 1 , +.Xr libarchive 3 , +.Xr libarchive-formats 5 , +.Xr tar 5 +.Sh STANDARDS +There is no current POSIX standard for the tar command; it appeared +in +.St -p1003.1-96 +but was dropped from +.St -p1003.1-2001 . +The options used by this implementation were developed by surveying a +number of existing tar implementations as well as the old POSIX specification +for tar and the current POSIX specification for pax. +.Pp +The ustar and pax interchange file formats are defined by +.St -p1003.1-2001 +for the pax command. +.Sh HISTORY +A +.Nm 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 +.Nm 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 +.Fx +beginning with +.Fx 1.0 . +.Pp +This is a complete re-implementation based on the +.Xr libarchive 3 +library. +.Sh BUGS +POSIX and GNU violently disagree about the meaning of the +.Fl l +option. +Because of the potential for disaster if someone expects +one behavior and gets the other, the +.Fl l +option is deliberately broken in this implementation. +.Pp +The +.Fl C Pa dir +option may differ from historic implementations. +.Pp +All archive output is written in correctly-sized blocks, even +if the output is being compressed. +Whether or not the last output block is padded to a full +block size varies depending on the format and the +output device. +For tar and cpio formats, the last block of output is padded +to a full block size if the output is being +written to standard output or to a character or block device such as +a tape drive. +If the output is being written to a regular file, the last block +will not be padded. +Many compressors, including +.Xr gzip 1 +and +.Xr bzip2 1 , +complain about the null padding when decompressing an archive created by +.Nm , +although they still extract it correctly. +.Pp +The compression and decompression is implemented internally, so +there may be insignificant differences between the compressed output +generated by +.Dl Nm Fl czf Pa - file +and that generated by +.Dl Nm Fl cf Pa - file | Nm gzip +.Pp +The default should be to read and write archives to the standard I/O paths, +but tradition (and POSIX) dictates otherwise. +.Pp +The +.Cm r +and +.Cm u +modes require that the archive be uncompressed +and located in a regular file on disk. +Other archives can be modified using +.Cm c +mode with the +.Pa @archive-file +extension. +.Pp +To archive a file called +.Pa @foo +or +.Pa -foo +you must specify it as +.Pa ./@foo +or +.Pa ./-foo , +respectively. +.Pp +In create mode, a leading +.Pa ./ +is always removed. +A leading +.Pa / +is stripped unless the +.Fl P +option is specified. +.Pp +There needs to be better support for file selection on both create +and extract. +.Pp +There is not yet any support for multi-volume archives or for archiving +sparse files. +.Pp +Converting between dissimilar archive formats (such as tar and cpio) using the +.Cm @ Ns Pa - +convention can cause hard link information to be lost. +(This is a consequence of the incompatible ways that different archive +formats store hardlink information.) +.Pp +There are alternative long options for many of the short options that +are deliberately not documented. diff --git a/archivers/libarchive/files/doc/man/cpio.5 b/archivers/libarchive/files/doc/man/cpio.5 new file mode 100644 index 00000000000..2f298332d18 --- /dev/null +++ b/archivers/libarchive/files/doc/man/cpio.5 @@ -0,0 +1,325 @@ +.\" Copyright (c) 2007 Tim Kientzle +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd October 5, 2007 +.Dt CPIO 5 +.Os +.Sh NAME +.Nm cpio +.Nd format of cpio archive files +.Sh DESCRIPTION +The +.Nm +archive format collects any number of files, directories, and other +file system objects (symbolic links, device nodes, etc.) into a single +stream of bytes. +.Ss General Format +Each file system object in a +.Nm +archive comprises a header record with basic numeric metadata +followed by the full pathname of the entry and the file data. +The header record stores a series of integer values that generally +follow the fields in +.Va struct stat . +(See +.Xr 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 +.Dq TRAILER!!! . +.Ss PWB format +XXX Any documentation of the original PWB/UNIX 1.0 format? XXX +.Ss Old Binary Format +The old binary +.Nm +format stores numbers as 2-byte and 4-byte binary values. +Each entry begins with a header in the following format: +.Bd -literal -offset indent +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]; +}; +.Ed +.Pp +The +.Va unsigned short +fields here are 16-bit integer values; the +.Va unsigned int +fields are 32-bit integer values. +The fields are as follows +.Bl -tag -width indent +.It Va magic +The integer value octal 070707. +This value can be used to determine whether this archive is +written with little-endian or big-endian integers. +.It Va dev , Va ino +The device and inode numbers from the disk. +These are used by programs that read +.Nm +archives to determine when two entries refer to the same file. +Programs that synthesize +.Nm +archives should be careful to set these to distinct values for each entry. +.It Va mode +The mode specifies both the regular permissions and the file type. +It consists of several bit fields as follows: +.Bl -tag -width "MMMMMMM" -compact +.It 0170000 +This masks the file type bits. +.It 0140000 +File type value for sockets. +.It 0120000 +File type value for symbolic links. +For symbolic links, the link body is stored as file data. +.It 0100000 +File type value for regular files. +.It 0060000 +File type value for block special devices. +.It 0040000 +File type value for directories. +.It 0020000 +File type value for character special devices. +.It 0010000 +File type value for named pipes or FIFOs. +.It 0004000 +SUID bit. +.It 0002000 +SGID bit. +.It 0001000 +Sticky bit. +On some systems, this modifies the behavior of executables and/or directories. +.It 0000777 +The lower 9 bits specify read/write/execute permissions +for world, group, and user following standard POSIX conventions. +.El +.It Va uid , Va gid +The numeric user id and group id of the owner. +.It Va 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. +.It Va rdev +For block special and character special entries, +this field contains the associated device number. +For all other entry types, it should be set to zero by writers +and ignored by readers. +.It Va 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. +.It Va namesize +The number of bytes in the pathname that follows the header. +This count includes the trailing NULL byte. +.It Va filesize +The size of the file. +Note that this archive format is limited to +four gigabyte file sizes. +See +.Va mtime +above for a description of the storage of four-byte integers. +.El +.Pp +The pathname immediately follows the fixed header. +If the +.Cm namesize +is odd, an additional NULL byte is added after the pathname. +The file data is then appended, padded with NULL +bytes to an even length. +.Pp +Hardlinked files are not given special treatment; +the full file contents are included with each copy of the +file. +.Ss Portable ASCII Format +.St -susv2 +standardized an ASCII variant that is portable across all +platforms. +It is commonly known as the +.Dq old character +format or as the +.Dq odc +format. +It stores the same numeric fields as the old binary format, but +represents them as 6-character or 11-character octal values. +.Bd -literal -offset indent +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]; +}; +.Ed +.Pp +The fields are identical to those in the old binary format. +The name and file body follow the fixed header. +Unlike the old binary format, there is no additional padding +after the pathname or file contents. +If the files being archived are themselves entirely ASCII, then +the resulting archive will be entirely ASCII, except for the +NULL byte that terminates the name field. +.Ss New ASCII Format +The "new" ASCII format uses 8-byte hexadecimal fields for +all numbers and separates device numbers into separate fields +for major and minor numbers. +.Bd -literal -offset indent +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]; +}; +.Ed +.Pp +Except as specified below, the fields here match those specified +for the old binary format above. +.Bl -tag -width indent +.It Va magic +The string +.Dq 070701 . +.It Va check +This field is always set to zero by writers and ignored by readers. +See the next section for more details. +.El +.Pp +The pathname is followed by NULL bytes so that the total size +of the fixed header plus pathname is a multiple of four. +Likewise, the file data is padded to a multiple of four bytes. +Note that this format supports only 4 gigabyte files (unlike the +older ASCII format, which supports 8 gigabyte files). +.Pp +In this format, hardlinked files are handled by setting the +filesize to zero for each entry except the last one that +appears in the archive. +.Ss New CRC Format +The CRC format is identical to the new ASCII format described +in the previous section except that the magic field is set +to +.Dq 070702 +and the +.Va check +field is set to the sum of all bytes in the file data. +This sum is computed treating all bytes as unsigned values +and using unsigned arithmetic. +Only the least-significant 32 bits of the sum are stored. +.Ss HP variants +The +.Nm cpio +implementation distributed with HPUX used XXXX but stored +device numbers differently XXX. +.Ss Other Extensions and Variants +Sun Solaris uses additional file types to store extended file +data, including ACLs and extended attributes, as special +entries in cpio archives. +.Pp +XXX Others? XXX +.Sh BUGS +The +.Dq CRC +format is mis-named, as it uses a simple checksum and +not a cyclic redundancy check. +.Pp +The old binary format is limited to 16 bits for user id, +group id, device, and inode numbers. +It is limited to 4 gigabyte file sizes. +.Pp +The old ASCII format is limited to 18 bits for +the user id, group id, device, and inode numbers. +It is limited to 8 gigabyte file sizes. +.Pp +The new ASCII format is limited to 4 gigabyte file sizes. +.Pp +None of the cpio formats store user or group names, +which are essential when moving files between systems with +dissimilar user or group numbering. +.Pp +Especially when writing older cpio variants, it may be necessary +to map actual device/inode values to synthesized values that +fit the available fields. +With very large filesystems, this may be necessary even for +the newer formats. +.Sh SEE ALSO +.Xr cpio 1 , +.Xr tar 5 +.Sh STANDARDS +The +.Nm cpio +utility is no longer a part of POSIX or the Single Unix Standard. +It last appeared in +.St -susv2 . +It has been supplanted in subsequent standards by +.Xr pax 1 . +The portable ASCII format is currently part of the specification for the +.Xr pax 1 +utility. +.Sh 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 +.Dq Programmer's Work Bench +derived from +.At v6 +that was used internally at AT&T. +Both the old binary and old character formats were in use +by 1980, according to the System III source released +by SCO under their +.Dq Ancient Unix +license. +The character format was adopted as part of +.St -p1003.1-88 . +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
\ No newline at end of file diff --git a/archivers/libarchive/files/doc/man/libarchive-formats.5 b/archivers/libarchive/files/doc/man/libarchive-formats.5 new file mode 100644 index 00000000000..0606a5ba1d0 --- /dev/null +++ b/archivers/libarchive/files/doc/man/libarchive-formats.5 @@ -0,0 +1,272 @@ +.\" Copyright (c) 2003-2007 Tim Kientzle +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: src/lib/libarchive/libarchive-formats.5,v 1.14 2007/04/05 05:07:53 kientzle Exp $ +.\" +.Dd April 27, 2004 +.Dt libarchive-formats 3 +.Os +.Sh NAME +.Nm libarchive-formats +.Nd archive formats supported by the libarchive library +.Sh DESCRIPTION +The +.Xr libarchive 3 +library reads and writes a variety of streaming archive formats. +Generally speaking, all of these archive formats consist of a series of +.Dq entries . +Each entry stores a single file system object, such as a file, directory, +or symbolic link. +.Pp +The following provides a brief description of each format supported +by libarchive, with some information about recognized extensions or +limitations of the current library support. +Note that just because a format is supported by libarchive does not +imply that a program that uses libarchive will support that format. +Applications that use libarchive specify which formats they wish +to support. +.Ss Tar Formats +The +.Xr libarchive 3 +library can read most tar archives. +However, it only writes POSIX-standard +.Dq ustar +and +.Dq pax interchange +formats. +.Pp +All tar formats store each entry in one or more 512-byte records. +The first record is used for file metadata, including filename, +timestamp, and mode information, and the file data is stored in +subsequent records. +Later variants have extended this by either appropriating undefined +areas of the header record, extending the header to multiple records, +or by storing special entries that modify the interpretation of +subsequent entries. +.Pp +.Bl -tag -width indent +.It Cm gnutar +The +.Xr 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. +.It Cm pax +The +.Xr 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 presence 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 Unicode strings. +Keywords defined in the standard are in all lowercase; vendors are allowed +to define custom keys by preceding them with the vendor name in all uppercase. +When writing pax archives, libarchive uses many of the SCHILY keys +defined by Joerg Schilling's +.Dq star +archiver. +The libarchive library can read most of the SCHILY keys. +It silently ignores any keywords that it does not understand. +.It Cm restricted pax +The libarchive library can also write pax archives in which it +attempts to suppress the extended attributes entry whenever +possible. +The result will be identical to a ustar archive unless the +extended attributes entry is required to store a long file +name, long linkname, extended ACL, file flags, or if any of the standard +ustar data (user name, group name, UID, GID, etc) cannot be fully +represented in the ustar header. +In all cases, the result can be dearchived by any program that +can read POSIX-compliant pax interchange format archives. +Programs that correctly read ustar format (see below) will also be +able to read this format; any extended attributes will be extracted as +separate files stored in +.Pa PaxHeader +directories. +.It Cm ustar +The libarchive library can both read and write this format. +This format has the following limitations: +.Bl -bullet -compact +.It +Device major and minor numbers are limited to 21 bits. +Nodes with larger numbers will not be added to the archive. +.It +Path names in the archive are limited to 255 bytes. +(Shorter if there is no / character in exactly the right place.) +.It +Symbolic links and hard links are stored in the archive with +the name of the referenced file. +This name is limited to 100 bytes. +.It +Extended attributes, file flags, and other extended +security information cannot be stored. +.It +Archive entries are limited to 2 gigabytes in size. +.El +Note that the pax interchange format has none of these restrictions. +.El +.Pp +The libarchive library can also read a variety of commonly-used extensions to +the basic tar format. +In particular, it supports base-256 values in certain numeric fields. +This essentially removes the limitations on file size, modification time, +and device numbers. +.Pp +The first tar program appeared in Seventh Edition Unix in 1979. +The first official standard for the tar file format was the +.Dq ustar +(Unix Standard Tar) format defined by POSIX in 1988. +POSIX.1-2001 extended the ustar format to create the +.Dq pax interchange +format. +.Ss Cpio Formats +The libarchive library can read a number of common cpio variants and can write +.Dq odc +and +.Dq 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. +.Bl -tag -width indent +.It Cm 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. +.It Cm odc +The libarchive library can both read and write this +POSIX-standard 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. +.It Cm 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. +.El +.Pp +Cpio first appeared in PWB/UNIX 1.0, which was released within +AT&T in 1977. +PWB/UNIX 1.0 formed the basis of System III Unix, released outside +of AT&T in 1981. +This makes cpio older than tar, although cpio was not included +in Version 7 AT&T Unix. +As a result, the tar command became much better known in universities +and research groups that used Version 7. +The combination of the +.Nm find +and +.Nm cpio +utilities provided very precise control over file selection. +Unfortunately, the format has many limitations that make it unsuitable +for widespread use. +Only the POSIX format permits files over 4GB, and its 18-bit +limit for most other fields makes it unsuitable for modern systems. +In addition, cpio formats only store numeric UID/GID values (not +usernames and group names), which can make it very difficult to correctly +transfer archives across systems with dissimilar user numbering. +.Ss Shar Formats +A +.Dq shell archive +is a shell script that, when executed on a POSIX-compliant +system, will recreate a collection of file system objects. +The libarchive library can write two different kinds of shar archives: +.Bl -tag -width indent +.It Cm shar +The traditional shar format uses a limited set of POSIX +commands, including +.Xr echo 1 , +.Xr mkdir 1 , +and +.Xr sed 1 . +It is suitable for portably archiving small collections of plain text files. +However, it is not generally well-suited for large archives +(many implementations of +.Xr sh 1 +have limits on the size of a script) nor should it be used with non-text files. +.It Cm shardump +This format is similar to shar but encodes files using +.Xr uuencode 1 +so that the result will be a plain text file regardless of the file contents. +It also includes additional shell commands that attempt to reproduce as +many file attributes as possible, including owner, mode, and flags. +The additional commands used to restore file attributes make +shardump archives less portable than plain shar archives. +.El +.Ss ISO9660 format +Libarchive can read and extract from files containing ISO9660-compliant +CDROM images. +It also has partial support for Rockridge extensions. +In many cases, this can remove the need to burn a physical CDROM. +It also avoids security and complexity issues that come with +virtual mounts and loopback devices. +.Ss Zip format +Libarchive can extract from most zip format archives. +It currently only supports uncompressed entries and entries +compressed with the +.Dq deflate +algorithm. +Older zip compression algorithms are not supported. +.Ss Archive (library) file format +The Unix archive format (commonly created by the +.Xr ar 1 +archiver) is a general-purpose format which is +used almost exclusively for object files to be +read by the link editor +.Xr ld 1 . +The ar format has never been standardised. +There are two common variants: +the GNU format derived from SVR4, +and the BSD format, which first appeared in 4.4BSD. +Libarchive provides read and write support for both variants. +.Sh SEE ALSO +.Xr ar 1 , +.Xr cpio 1 , +.Xr mkisofs 1 , +.Xr shar 1 , +.Xr tar 1 , +.Xr zip 1 , +.Xr zlib 3 , +.Xr cpio 5 , +.Xr mtree 5 , +.Xr tar 5 diff --git a/archivers/libarchive/files/doc/man/libarchive.3 b/archivers/libarchive/files/doc/man/libarchive.3 new file mode 100644 index 00000000000..8c19d008a90 --- /dev/null +++ b/archivers/libarchive/files/doc/man/libarchive.3 @@ -0,0 +1,331 @@ +.\" Copyright (c) 2003-2007 Tim Kientzle +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: src/lib/libarchive/libarchive.3,v 1.11 2007/01/09 08:05:56 kientzle Exp $ +.\" +.Dd August 19, 2006 +.Dt LIBARCHIVE 3 +.Os +.Sh NAME +.Nm libarchive +.Nd functions for reading and writing streaming archives +.Sh LIBRARY +.Lb libarchive +.Sh OVERVIEW +The +.Nm +library provides a flexible interface for reading and writing +streaming archive files such as tar and cpio. +The library is inherently stream-oriented; readers serially iterate through +the archive, writers serially add things to the archive. +In particular, note that there is no built-in support for +random access nor for in-place modification. +.Pp +When reading an archive, the library automatically detects the +format and the compression. +The library currently has read support for: +.Bl -bullet -compact +.It +old-style tar archives, +.It +most variants of the POSIX +.Dq ustar +format, +.It +the POSIX +.Dq pax interchange +format, +.It +GNU-format tar archives, +.It +most common cpio archive formats, +.It +ISO9660 CD images (with or without RockRidge extensions), +.It +Zip archives. +.El +The library automatically detects archives compressed with +.Xr gzip 1 , +.Xr bzip2 1 , +or +.Xr compress 1 +and decompresses them transparently. +.Pp +When writing an archive, you can specify the compression +to be used and the format to use. +The library can write +.Bl -bullet -compact +.It +POSIX-standard +.Dq ustar +archives, +.It +POSIX +.Dq pax interchange format +archives, +.It +POSIX octet-oriented cpio archives, +.It +two different variants of shar archives. +.El +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 +.Xr pax 1 +implementations on many systems as well as several newer implementations of +.Xr 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. +.Pp +The read and write APIs are accessed through the +.Fn archive_read_XXX +functions and the +.Fn archive_write_XXX +functions, respectively, and either can be used independently +of the other. +.Pp +The rest of this manual page provides an overview of the library +operation. +More detailed information can be found in the individual manual +pages for each API or utility function. +.Sh READING AN ARCHIVE +To read an archive, you must first obtain an initialized +.Tn struct archive +object from +.Fn archive_read_new . +You can then modify this object for the desired operations with the +various +.Fn archive_read_set_XXX +and +.Fn archive_read_support_XXX +functions. +In particular, you will need to invoke appropriate +.Fn archive_read_support_XXX +functions to enable the corresponding compression and format +support. +Note that these latter functions perform two distinct operations: +they cause the corresponding support code to be linked into your +program, and they enable the corresponding auto-detect code. +Unless you have specific constraints, you will generally want +to invoke +.Fn archive_read_support_compression_all +and +.Fn archive_read_support_format_all +to enable auto-detect for all formats and compression types +currently supported by the library. +.Pp +Once you have prepared the +.Tn struct archive +object, you call +.Fn archive_read_open +to actually open the archive and prepare it for reading. +There are several variants of this function; +the most basic expects you to provide pointers to several +functions that can provide blocks of bytes from the archive. +There are convenience forms that allow you to +specify a filename, file descriptor, +.Ft "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. +.Pp +Each archive entry consists of a header followed by a certain +amount of data. +You can obtain the next header with +.Fn archive_read_next_header , +which returns a pointer to an +.Tn struct archive_entry +structure with information about the current archive element. +If the entry is a regular file, then the header will be followed +by the file data. +You can use +.Fn archive_read_data +(which works much like the +.Xr read 2 +system call) +to read this data from the archive. +You may prefer to use the higher-level +.Fn archive_read_data_skip , +which reads and discards the data for this entry, +.Fn archive_read_data_to_buffer , +which reads the data into an in-memory buffer, +.Fn archive_read_data_to_file , +which copies the data to the provided file descriptor, or +.Fn archive_read_extract , +which recreates the specified entry on disk and copies data +from the archive. +In particular, note that +.Fn archive_read_extract +uses the +.Tn struct archive_entry +structure that you provide it, which may differ from the +entry just read from the archive. +In particular, many applications will want to override the +pathname, file permissions, or ownership. +.Pp +Once you have finished reading data from the archive, you +should call +.Fn archive_read_close +to close the archive, then call +.Fn archive_read_finish +to release all resources, including all memory allocated by the library. +.Pp +The +.Xr archive_read 3 +manual page provides more detailed calling information for this API. +.Sh WRITING AN ARCHIVE +You use a similar process to write an archive. +The +.Fn archive_write_new +function creates an archive object useful for writing, +the various +.Fn archive_write_set_XXX +functions are used to set parameters for writing the archive, and +.Fn archive_write_open +completes the setup and opens the archive for writing. +.Pp +Individual archive entries are written in a three-step +process: +You first initialize a +.Tn struct archive_entry +structure with information about the new entry. +At a minimum, you should set the pathname of the +entry and provide a +.Va struct stat +with a valid +.Va st_mode +field, which specifies the type of object and +.Va st_size +field, which specifies the size of the data portion of the object. +The +.Fn archive_write_header +function actually writes the header data to the archive. +You can then use +.Fn archive_write_data +to write the actual data. +.Pp +After all entries have been written, use the +.Fn archive_write_finish +function to release all resources. +.Pp +The +.Xr archive_write 3 +manual page provides more detailed calling information for this API. +.Sh DESCRIPTION +Detailed descriptions of each function are provided by the +corresponding manual pages. +.Pp +All of the functions utilize an opaque +.Tn struct archive +datatype that provides access to the archive contents. +.Pp +The +.Tn struct archive_entry +structure contains a complete description of a single archive +entry. +It uses an opaque interface that is fully documented in +.Xr archive_entry 3 . +.Pp +Users familiar with historic formats should be aware that the newer +variants have eliminated most restrictions on the length of textual fields. +Clients should not assume that filenames, link names, user names, or +group names are limited in length. +In particular, pax interchange format can easily accommodate pathnames +in arbitrary character sets that exceed +.Va PATH_MAX . +.Sh RETURN VALUES +Most functions return zero on success, non-zero on error. +The return value indicates the general severity of the error, ranging +from +.Cm ARCHIVE_WARN , +which indicates a minor problem that should probably be reported +to the user, to +.Cm ARCHIVE_FATAL , +which indicates a serious problem that will prevent any further +operations on this archive. +On error, the +.Fn archive_errno +function can be used to retrieve a numeric error code (see +.Xr errno 2 ) . +The +.Fn archive_error_string +returns a textual error message suitable for display. +.Pp +.Fn archive_read_new +and +.Fn archive_write_new +return pointers to an allocated and initialized +.Tn struct archive +object. +.Pp +.Fn archive_read_data +and +.Fn 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 +.Fn archive_errno +and +.Fn archive_error_string +functions can be used to obtain more information. +.Sh ENVIRONMENT +There are character set conversions within the +.Xr archive_entry 3 +functions that are impacted by the currently-selected locale. +.Sh SEE ALSO +.Xr tar 1 , +.Xr archive_entry 3 , +.Xr archive_read 3 , +.Xr archive_util 3 , +.Xr archive_write 3 , +.Xr tar 5 +.Sh HISTORY +The +.Nm libarchive +library first appeared in +.Fx 5.3 . +.Sh AUTHORS +.An -nosplit +The +.Nm libarchive +library was written by +.An Tim Kientzle Aq kientzle@acm.org . +.Sh BUGS +Some archive formats support information that is not supported by +.Tn struct archive_entry . +Such information cannot be fully archived or restored using this library. +This includes, for example, comments, character sets, +or the arbitrary key/value pairs that can appear in +pax interchange format archives. +.Pp +Conversely, of course, not all of the information that can be +stored in an +.Tn struct archive_entry +is supported by all formats. +For example, cpio formats do not support nanosecond timestamps; +old tar formats do not support large device numbers. diff --git a/archivers/libarchive/files/doc/man/libarchive_internals.3 b/archivers/libarchive/files/doc/man/libarchive_internals.3 new file mode 100644 index 00000000000..a84c9406d34 --- /dev/null +++ b/archivers/libarchive/files/doc/man/libarchive_internals.3 @@ -0,0 +1,366 @@ +.\" Copyright (c) 2003-2007 Tim Kientzle +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: src/lib/libarchive/libarchive_internals.3,v 1.1 2007/05/29 01:00:20 kientzle Exp $ +.\" +.Dd April 16, 2007 +.Dt LIBARCHIVE 3 +.Os +.Sh NAME +.Nm libarchive_internals +.Nd description of libarchive internal interfaces +.Sh OVERVIEW +The +.Nm libarchive +library provides a flexible interface for reading and writing +streaming archive files such as tar and cpio. +Internally, it follows a modular layered design that should +make it easy to add new archive and compression formats. +.Sh GENERAL ARCHITECTURE +Externally, libarchive exposes most operations through an +opaque, object-style interface. +The +.Xr archive_entry 1 +objects store information about a single filesystem object. +The rest of the library provides facilities to write +.Xr 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 +.Xr archive_entry 1 +objects from disk as well.) +.Pp +The read and write APIs each have four layers: a public API +layer, a format layer that understands the archive file format, +a compression layer, and an I/O layer. +The I/O layer is completely exposed to clients who can replace +it entirely with their own functions. +.Pp +In order to provide as much consistency as possible for clients, +some public functions are virtualized. +Eventually, it should be possible for clients to open +an archive or disk writer, and then use a single set of +code to select and write entries, regardless of the target. +.Sh READ ARCHITECTURE +From the outside, clients use the +.Xr archive_read 3 +API to manipulate an +.Nm archive +object to read entries and bodies from an archive stream. +Internally, the +.Nm archive +object is cast to an +.Nm 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 +.Xr archive_read_open_memory 3 , +and +.Xr archive_read_open_fd 3 . +The compression layer calls the I/O layer to +read bytes and decompresses them for the format layer. +The format layer unpacks a stream of uncompressed bytes and +creates +.Nm archive_entry +objects from the incoming data. +The API layer tracks overall state +(for example, it prevents clients from reading data before reading a header) +and invokes the format and compression layer operations +through registered function pointers. +In particular, the API layer drives the format-detection process: +When opening the archive, it reads an initial block of data +and offers it to each registered compression handler. +The one with the highest bid is initialized with the first block. +Similarly, the format handlers are polled to see which handler +is the best for each archive. +(Prior to 2.4.0, the format bidders were invoked for each +entry, but this design hindered error recovery.) +.Ss I/O Layer and Client Callbacks +The read API goes to some lengths to be nice to clients. +As a result, there are few restrictions on the behavior of +the client callbacks. +.Pp +The client read callback is expected to provide a block +of data on each call. +A zero-length return does indicate end of file, but otherwise +blocks may be as small as one byte or as large as the entire file. +In particular, blocks may be of different sizes. +.Pp +The client skip callback returns the number of bytes actually +skipped, which may be much smaller than the skip requested. +The only requirement is that the skip not be larger. +In particular, clients are allowed to return zero for any +skip that they don't want to handle. +The skip callback must never be invoked with a negative value. +.Pp +Keep in mind that not all clients are reading from disk: +clients reading from networks may provide different-sized +blocks on every request and cannot skip at all; +advanced clients may use +.Xr 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. +.Ss Decompresssion Layer +The decompression layer not only handles decompression, +it also buffers data so that the format handlers see a +much nicer I/O model. +The decompression API is a two stage peek/consume model. +A read_ahead request specifies a minimum read amount; +the decompression layer must provide a pointer to at least +that much data. +If more data is immediately available, it should return more: +the format layer handles bulk data reads by asking for a minimum +of one byte and then copying as much data as is available. +.Pp +A subsequent call to the +.Fn consume +function advances the read pointer. +Note that data returned from a +.Fn read_ahead +call is guaranteed to remain in place until +the next call to +.Fn read_ahead . +Intervening calls to +.Fn consume +should not cause the data to move. +.Pp +Skip requests must always be handled exactly. +Decompression handlers that cannot seek forward should +not register a skip handler; +the API layer fills in a generic skip handler that reads and discards data. +.Pp +A decompression handler has a specific lifecycle: +.Bl -tag -compact -width indent +.It Registration/Configuration +When the client invokes the public support function, +the decompression handler invokes the internal +.Fn __archive_read_register_compression +function to provide bid and initialization functions. +This function returns +.Cm NULL +on error or else a pointer to a +.Cm struct decompressor_t . +This structure contains a +.Va void * config +slot that can be used for storing any customization information. +.It 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 +.Va decompressor +element of the +.Cm archive_read +object. +The bid function is otherwise stateless. +In particular, it must not perform any I/O operations. +.Pp +The value returned by the bid function indicates its suitability +for handling this data stream. +A bid of zero will ensure that this decompressor is never invoked. +Return zero if magic number checks fail. +Otherwise, your initial implementation should return the number of bits +actually checked. +For example, if you verify two full bytes and three bits of another +byte, bid 19. +Note that the initial block may be very short; +be careful to only inspect the data you are given. +(The current decompressors require two bytes for correct bidding.) +.It Initialize +The winning bidder will have its init function called. +This function should initialize the remaining slots of the +.Va struct decompressor_t +object pointed to by the +.Va decompressor +element of the +.Va archive_read +object. +In particular, it should allocate any working data it needs +in the +.Va 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. +.It Satisfy I/O requests +The format handler will invoke the +.Va read_ahead , +.Va consume , +and +.Va skip +functions as needed. +.It Finish +The finish method is called only once when the archive is closed. +It should release anything stored in the +.Va data +and +.Va config +slots of the +.Va decompressor +object. +It should not invoke the client close callback. +.El +.Ss Format Layer +The read formats have a similar lifecycle to the decompression handlers: +.Bl -tag -compact -width indent +.It Registration +Allocate your private data and initialize your pointers. +.It Bid +Formats bid by invoking the +.Fn read_ahead +decompression method but not calling the +.Fn 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.) +.It 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. +.It Read Data +The read data interface supports sparse files; this requires that +each call return a block of data specifying the file offset and +size. +This may require you to carefully track the location so that you +can return accurate file offsets for each read. +Remember that the decompressor will return as much data as it has. +Generally, you will want to request one byte, +examine the return value to see how much data is available, and +possibly trim that to the amount you can use. +You should invoke consume for each block just before you return it. +.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 +.Fn data_skip +function. +.It Cleanup +On cleanup, the format should release all of its allocated memory. +.El +.Ss API Layer +XXX to do XXX +.Sh WRITE ARCHITECTURE +The write API has a similar set of four layers: +an API layer, a format layer, a compression layer, and an I/O layer. +The registration here is much simpler because only +one format and one compression can be registered at a time. +.Ss I/O Layer and Client Callbacks +XXX To be written XXX +.Ss Compression Layer +XXX To be written XXX +.Ss Format Layer +XXX To be written XXX +.Ss API Layer +XXX To be written XXX +.Sh WRITE_DISK ARCHITECTURE +The write_disk API is intended to look just like the write API +to clients. +Since it does not handle multiple formats or compression, it +is not layered internally. +.Sh GENERAL SERVICES +The +.Nm archive_read , +.Nm archive_write , +and +.Nm archive_write_disk +objects all contain an initial +.Nm 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 +.Nm 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. +.Sh 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. +.Pp +For example, libarchive's ISO9660 support operates very differently +from most ISO9660 readers. +The libarchive support utilizes a work-queue design that +keeps a list of known entries sorted by their location in the input. +Whenever libarchive's ISO9660 implementation is asked for the next +header, checks this list to find the next item on the disk. +Directories are parsed when they are encountered and new +items are added to the list. +This design relies heavily on the ISO9660 image being optimized so that +directories always occur earlier on the disk than the files they +describe. +.Pp +Depending on the specific format, such approaches may not be possible. +The ZIP format specification, for example, allows archivers to store +key information only at the end of the file. +In theory, it is possible to create ZIP archives that cannot +be read without seeking. +Fortunately, such archives are very rare, and libarchive can read +most ZIP archives, though it cannot always extract as much information +as a dedicated ZIP program. +.Sh SEE ALSO +.Xr archive 3 , +.Xr archive_entry 3 , +.Xr archive_read 3 , +.Xr archive_write 3 , +.Xr archive_write_disk 3 +.Sh HISTORY +The +.Nm libarchive +library first appeared in +.Fx 5.3 . +.Sh AUTHORS +.An -nosplit +The +.Nm libarchive +library was written by +.An Tim Kientzle Aq kientzle@acm.org . +.Sh BUGS diff --git a/archivers/libarchive/files/doc/man/mtree.5 b/archivers/libarchive/files/doc/man/mtree.5 new file mode 100644 index 00000000000..613de6a5dae --- /dev/null +++ b/archivers/libarchive/files/doc/man/mtree.5 @@ -0,0 +1,270 @@ +.\" Copyright (c) 1989, 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" From: @(#)mtree.8 8.2 (Berkeley) 12/11/93 +.\" $FreeBSD$ +.\" +.Dd August 20, 2007 +.Dt MTREE 5 +.Os +.Sh NAME +.Nm mtree +.Nd format of mtree dir heirarchy files +.Sh DESCRIPTION +The +.Nm +format is a textual format that describes a collection of filesystem objects. +Such files are typically used to create or verify directory heirarchies. +.Ss General Format +An +.Nm +file consists of a series of lines, each providing information +about a single filesystem object. +Leading whitespace is always ignored. +.Pp +When encoding file or pathnames, any backslash character or +character outside of the 95 printable ASCII characters must be +encoded as a a backslash followed by three +octal digits. +When reading mtree files, any appearance of a backslash +followed by three octal digits should be converted into the +corresponding character. +.Pp +Each line is interpreted independently as one of the following types: +.Bl -tag -width Cm +.It Signature +The first line of any mtree file must begin with +.Dq #mtree . +If a file contains any full path entries, the first line should +begin with +.Dq #mtree v2.0 , +otherwise, the first line should begin with +.Dq #mtree v1.0 . +.It Blank +Blank lines are ignored. +.It Comment +Lines beginning with +.Cm # +are ignored. +.It Special +Lines beginning with +.Cm / +are special commands that influence +the interpretation of later lines. +.It Relative +If the first whitespace-delimited word has no +.Cm / +characters, +it is the name of a file in the current directory. +Any relative entry that describes a directory changes the +current directory. +.It dot-dot +As a special case, a relative entry with the filename +.Pa .. +changes the current directory to the parent directory. +Options on dot-dot entries are always ignored. +.It Full +If the first whitespace-delimited word has a +.Cm / +character after +the first character, it is the pathname of a file relative to the +starting directory. +There can be multiple full entries describing the same file. +.El +.Pp +Some tools that process +.Nm +files may require that multiple lines describing the same file +occur consecutively. +It is not permitted for the same file to be mentioned using +both a relative and a full file specification. +.Ss Special commands +Two special commands are currently defined: +.Bl -tag -width Cm +.It Cm /set +This command defines default values for one or more keywords. +It is followed on the same line by one or more whitespace-separated +keyword definitions. +These definitions apply to all following files that do not specify +a value for that keyword. +.It Cm /unset +This command removes any default value set by a previous +.Cm /set +command. +It is followed on the same line by one or more keywords +separated by whitespace. +.El +.Ss Keywords +After the filename, a full or relative entry consists of zero +or more whitespace-separated keyword definitions. +Each such definitions consists of a key from the following +list immediately followed by an '=' sign +and a value. +Software programs reading mtree files should warn about +unrecognized keywords. +.Pp +Currently supported keywords are as follows: +.Bl -tag -width Cm +.It Cm cksum +The checksum of the file using the default algorithm specified by +the +.Xr cksum 1 +utility. +.It Cm contents +The full pathname of a file whose contents should be +compared to the contents of this file. +.It Cm flags +The file flags as a symbolic name. +See +.Xr chflags 1 +for information on these names. +If no flags are to be set the string +.Dq none +may be used to override the current default. +.It Cm ignore +Ignore any file hierarchy below this file. +.It Cm gid +The file group as a numeric value. +.It Cm gname +The file group as a symbolic name. +.It Cm md5 +The MD5 message digest of the file. +.It Cm md5digest +A synonym for +.Cm md5 . +.It Cm sha1 +The +.Tn FIPS +160-1 +.Pq Dq Tn SHA-1 +message digest of the file. +.It Cm sha1digest +A synonym for +.Cm sha1 . +.It Cm sha256 +The +.Tn FIPS +180-2 +.Pq Dq Tn SHA-256 +message digest of the file. +.It Cm sha256digest +A synonym for +.Cm sha256 . +.It Cm ripemd160digest +The +.Tn RIPEMD160 +message digest of the file. +.It Cm rmd160 +A synonym for +.Cm ripemd160digest . +.It Cm rmd160digest +A synonym for +.Cm ripemd160digest . +.It Cm mode +The current file's permissions as a numeric (octal) or symbolic +value. +.It Cm nlink +The number of hard links the file is expected to have. +.It Cm nochange +Make sure this file or directory exists but otherwise ignore all attributes. +.It Cm uid +The file owner as a numeric value. +.It Cm uname +The file owner as a symbolic name. +.It Cm size +The size, in bytes, of the file. +.It Cm link +The file the symbolic link is expected to reference. +.It Cm time +The last modification time of the file. +.It Cm type +The type of the file; may be set to any one of the following: +.Pp +.Bl -tag -width Cm -compact +.It Cm block +block special device +.It Cm char +character special device +.It Cm dir +directory +.It Cm fifo +fifo +.It Cm file +regular file +.It Cm link +symbolic link +.It Cm socket +socket +.El +.El +.Pp +.Sh SEE ALSO +.Xr cksum 1 , +.Xr find 1 , +.Xr mtree 8 +.Sh BUGS +The +.Fx +implementation of mtree does not currently support +the +.Nm +2.0 +format. +The requirement for a +.Dq #mtree +signature line is new and not yet widely implemented. +.Sh HISTORY +The +.Nm +utility appeared in +.Bx 4.3 Reno . +The +.Tn MD5 +digest capability was added in +.Fx 2.1 , +in response to the widespread use of programs which can spoof +.Xr cksum 1 . +The +.Tn SHA-1 +and +.Tn RIPEMD160 +digests were added in +.Fx 4.0 , +as new attacks have demonstrated weaknesses in +.Tn MD5 . +The +.Tn SHA-256 +digest was added in +.Fx 6.0 . +Support for file flags was added in +.Fx 4.0 , +and mostly comes from +.Nx . +The +.Dq full +entry format was added by +.Nx . diff --git a/archivers/libarchive/files/doc/man/tar.5 b/archivers/libarchive/files/doc/man/tar.5 new file mode 100644 index 00000000000..ab39df3338a --- /dev/null +++ b/archivers/libarchive/files/doc/man/tar.5 @@ -0,0 +1,730 @@ +.\" Copyright (c) 2003-2007 Tim Kientzle +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: src/lib/libarchive/tar.5,v 1.17 2007/01/09 08:05:56 kientzle Exp $ +.\" +.Dd May 20, 2004 +.Dt TAR 5 +.Os +.Sh NAME +.Nm tar +.Nd format of tape archive files +.Sh DESCRIPTION +The +.Nm +archive format collects any number of files, directories, and other +file system objects (symbolic links, device nodes, etc.) into a single +stream of bytes. +The format was originally designed to be used with +tape drives that operate with fixed-size blocks, but is widely used as +a general packaging mechanism. +.Ss General Format +A +.Nm +archive consists of a series of 512-byte records. +Each file system object requires a header record which stores basic metadata +(pathname, owner, permissions, etc.) and zero or more records containing any +file data. +The end of the archive is indicated by two records consisting +entirely of zero bytes. +.Pp +For compatibility with tape drives that use fixed block sizes, +programs that read or write tar files always read or write a fixed +number of records with each I/O operation. +These +.Dq blocks +are always a multiple of the record size. +The most common block size\(emand the maximum supported by historic +implementations\(emis 10240 bytes or 20 records. +(Note: the terms +.Dq block +and +.Dq record +here are not entirely standard; this document follows the +convention established by John Gilmore in documenting +.Nm pdtar . ) +.Ss Old-Style Archive Format +The original tar archive format has been extended many times to +include additional information that various implementors found +necessary. +This section describes the variant implemented by the tar command +included in +.At v7 , +which is one of the earliest widely-used versions of the tar program. +.Pp +The header record for an old-style +.Nm +archive consists of the following: +.Bd -literal -offset indent +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]; +}; +.Ed +All unused bytes in the header record are filled with nulls. +.Bl -tag -width indent +.It Va name +Pathname, stored as a null-terminated string. +Early tar implementations only stored regular files (including +hardlinks to those files). +One common early convention used a trailing "/" character to indicate +a directory name, allowing directory permissions and owner information +to be archived and restored. +.It Va mode +File mode, stored as an octal number in ASCII. +.It Va uid , Va gid +User id and group id of owner, as octal numbers in ASCII. +.It Va 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. +.It Va 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. +.It Va checksum +Header checksum, stored as an octal number in ASCII. +To compute the checksum, set the checksum field to all spaces, +then sum all bytes in the header using unsigned arithmetic. +This field should be stored as six octal digits followed by a null and a space +character. +Note that many early implementations of tar used signed arithmetic +for the checksum field, which can cause interoperability problems +when transferring archives between systems. +Modern robust readers compute the checksum both ways and accept the +header if either computation matches. +.It Va linkflag , Va 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 +.Va linkflag +is set to an ASCII +.Sq 1 +and the +.Va linkname +field holds the first name under which this file appears. +(Note that regular files have a null value in the +.Va linkflag +field.) +.El +.Pp +Early tar implementations varied in how they terminated these fields. +The tar command in +.At v7 +used the following conventions (this is also documented in early BSD manpages): +the pathname must be null-terminated; +the mode, uid, and gid fields must end in a space and a null byte; +the size and mtime fields must end in a space; +the checksum is terminated by a null and a space. +Early implementations filled the numeric fields with leading spaces. +This seems to have been common practice until the +.St -p1003.1-88 +standard was released. +For best portability, modern implementations should fill the numeric +fields with leading zeros. +.Ss Pre-POSIX Archives +An early draft of +.St -p1003.1-88 +served as the basis for John Gilmore's +.Nm 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: +.Bl -bullet -compact -width indent +.It +The magic value is +.Dq ustar\ \& +(note the following space). +The version field contains a space character followed by a null. +.It +The numeric fields are generally filled with leading spaces +(not leading zeros as recommended in the final standard). +.It +The prefix field is often not used, limiting pathnames to +the 100 characters of old-style archives. +.El +.Ss POSIX ustar Archives +.St -p1003.1-88 +defined a standard tar file format to be read and written +by compliant implementations of +.Xr tar 1 . +This format is often called the +.Dq ustar +format, after the magic value used +in the header. +(The name is an acronym for +.Dq Unix Standard TAR . ) +It extends the historic format with new fields: +.Bd -literal -offset indent +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]; +}; +.Ed +.Bl -tag -width indent +.It Va typeflag +Type of entry. +POSIX extended the earlier +.Va linkflag +field with several new type values: +.Bl -tag -width indent -compact +.It Dq 0 +Regular file. +NULL should be treated as a synonym, for compatibility purposes. +.It Dq 1 +Hard link. +.It Dq 2 +Symbolic link. +.It Dq 3 +Character device node. +.It Dq 4 +Block device node. +.It Dq 5 +Directory. +.It Dq 6 +FIFO node. +.It Dq 7 +Reserved. +.It Other +A POSIX-compliant implementation must treat any unrecognized typeflag value +as a regular file. +In particular, writers should ensure that all entries +have a valid filename so that they can be restored by readers that do not +support the corresponding extension. +Uppercase letters "A" through "Z" are reserved for custom extensions. +Note that sockets and whiteout entries are not archivable. +.El +It is worth noting that the +.Va size +field, in particular, has different meanings depending on the type. +For regular files, of course, it indicates the amount of data +following the header. +For directories, it may be used to indicate the total size of all +files in the directory, for use by operating systems that pre-allocate +directory space. +For all other types, it should be set to zero by writers and ignored +by readers. +.It Va magic +Contains the magic value +.Dq ustar +followed by a NULL byte to indicate that this is a POSIX standard archive. +Full compliance requires the uname and gname fields be properly set. +.It Va version +Version. +This should be +.Dq 00 +(two copies of the ASCII digit zero) for POSIX standard archives. +.It Va uname , Va 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. +.It Va devmajor , Va devminor +Major and minor numbers for character device or block device entry. +.It Va 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 +.Pa / +character with the first portion going here. +If the prefix field is not empty, the reader will prepend +the prefix value and a +.Pa / +character to the regular name field to obtain the full pathname. +.El +.Pp +Note that all unused bytes must be set to +.Dv NULL . +.Pp +Field termination is specified slightly differently by POSIX +than by previous implementations. +The +.Va magic , +.Va uname , +and +.Va gname +fields must have a trailing +.Dv NULL . +The +.Va pathname , +.Va linkname , +and +.Va prefix +fields must have a trailing +.Dv NULL +unless they fill the entire field. +(In particular, it is possible to store a 256-character pathname if it +happens to have a +.Pa / +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 +.Dv NULL +characters. +.Pp +Currently, most tar implementations comply with the ustar +format, occasionally extending it by adding new fields to the +blank area at the end of the header record. +.Ss Pax Interchange Format +There are many attributes that cannot be portably stored in a +POSIX ustar archive. +.St -p1003.1-2001 +defined a +.Dq pax interchange format +that uses two new types of entries to hold text-formatted +metadata that applies to following entries. +Note that a pax interchange format archive is a ustar archive in every +respect. +The new data is stored in ustar-compatible archive entries that use the +.Dq x +or +.Dq g +typeflag. +In particular, older implementations that do not fully support these +extensions will extract the metadata into regular files, where the +metadata can be examined as necessary. +.Pp +An entry in a pax interchange format archive consists of one or +two standard ustar entries, each with its own header and data. +The first optional entry stores the extended attributes +for the following entry. +This optional first entry has an "x" typeflag and a size field that +indicates the total size of the extended attributes. +The extended attributes themselves are stored as a series of text-format +lines encoded in the portable UTF-8 encoding. +Each line consists of a decimal number, a space, a key string, an equals +sign, a value string, and a new line. +The decimal number indicates the length of the entire line, including the +initial length field and the trailing newline. +An example of such a field is: +.Dl 25 ctime=1084839148.1212\en +Keys in all lowercase are standard keys. +Vendors can add their own keys by prefixing them with an all uppercase +vendor name and a period. +Note that, unlike the historic header, numeric values are stored using +decimal, not octal. +A description of some common keys follows: +.Bl -tag -width indent +.It Cm atime , Cm ctime , Cm mtime +File access, inode change, and modification times. +These fields can be negative or include a decimal point and a fractional value. +.It Cm uname , Cm uid , Cm gname , Cm 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. +.It Cm linkpath +The full path of the linked-to file. +Note that this is encoded in UTF8 and can thus include non-ASCII characters. +.It Cm path +The full pathname of the entry. +Note that this is encoded in UTF8 and can thus include non-ASCII characters. +.It Cm realtime.* , Cm security.* +These keys are reserved and may be used for future standardization. +.It Cm 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. +.It Cm SCHILY.* +Vendor-specific attributes used by Joerg Schilling's +.Nm star +implementation. +.It Cm SCHILY.acl.access , Cm 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). +.It Cm SCHILY.devminor , Cm SCHILY.devmajor +The full minor and major numbers for device nodes. +.It Cm SCHILY.dev, Cm SCHILY.ino , Cm 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 +.Cm SCHILY.* +extensions can store all of the data from +.Va struct stat . +.It Cm LIBARCHIVE.xattr. Ns Ar namespace Ns . Ns Ar key +Libarchive stores POSIX.1e-style extended attributes using +keys of this form. +The +.Ar key +value is URL-encoded: +All non-ASCII characters and the two special characters +.Dq = +and +.Dq % +are encoded as +.Dq % +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 +.It Cm VENDOR.* +XXX document other vendor-specific extensions XXX +.El +.Pp +Any values stored in an extended attribute override the corresponding +values in the regular tar header. +Note that compliant readers should ignore the regular fields when they +are overridden. +This is important, as existing archivers are known to store non-compliant +values in the standard header fields in this situation. +There are no limits on length for any of these fields. +In particular, numeric fields can be arbitrarily large. +All text fields are encoded in UTF8. +Compliant writers should store only portable 7-bit ASCII characters in +the standard ustar header and use extended +attributes whenever a text value contains non-ASCII characters. +.Pp +In addition to the +.Cm x +entry described above, the pax interchange format +also supports a +.Cm g +entry. +The +.Cm g +entry is identical in format, but specifies attributes that serve as +defaults for all subsequent archive entries. +The +.Cm g +entry is not widely used. +.Pp +Besides the new +.Cm x +and +.Cm 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. +.Ss GNU Tar Archives +The GNU tar program started with a pre-POSIX format similar to that +described earlier and has extended it using several different mechanisms: +It added new fields to the empty space in the header (some of which was later +used by POSIX for conflicting purposes); +it allowed the header to be continued over multiple records; +and it defined new entries that modify following entries +(similar in principle to the +.Cm x +entry described above, but each GNU special entry is single-purpose, +unlike the general-purpose +.Cm x +entry). +As a result, GNU tar archives are not POSIX compatible, although +more lenient POSIX-compliant readers can successfully extract most +GNU tar archives. +.Bd -literal -offset indent +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]; +}; +.Ed +.Bl -tag -width indent +.It Va typeflag +GNU tar uses the following special entry types, in addition to +those defined by POSIX: +.Bl -tag -width indent +.It "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. +.It "D" +This indicates a directory entry. +Unlike the POSIX-standard "5" +typeflag, the header is followed by data records listing the names +of files in this directory. +Each name is preceded by an ASCII "Y" +if the file is stored in this archive or "N" if the file is not +stored in this archive. +Each name is terminated with a null, and +an extra null marks the end of the name list. +The purpose of this +entry is to support incremental backups; a program restoring from +such an archive may wish to delete files on disk that did not exist +in the directory when the archive was made. +.Pp +Note that the "D" typeflag specifically violates POSIX, which requires +that unrecognized typeflags be restored as normal files. +In this case, restoring the "D" entry as a file could interfere +with subsequent creation of the like-named directory. +.It "K" +The data for this entry is a long linkname for the following regular entry. +.It "L" +The data for this entry is a long pathname for the following regular entry. +.It "M" +This is a continuation of the last file on the previous volume. +GNU multi-volume archives guarantee that each volume begins with a valid +entry header. +To ensure this, a file may be split, with part stored at the end of one volume, +and part stored at the beginning of the next volume. +The "M" typeflag indicates that this entry continues an existing file. +Such entries can only occur as the first or second entry +in an archive (the latter only if the first entry is a volume label). +The +.Va size +field specifies the size of this entry. +The +.Va offset +field at bytes 369-380 specifies the offset where this file fragment +begins. +The +.Va realsize +field specifies the total size of the file (which must equal +.Va size +plus +.Va 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. +.It "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 +.Dq Rename %s to %s\en +or +.Dq Symlink %s to %s\en ; +in either case, both +filenames are escaped using K&R C syntax. +.It "S" +This is a +.Dq sparse +regular file. +Sparse files are stored as a series of fragments. +The header contains a list of fragment offset/length pairs. +If more than four such entries are required, the header is +extended as necessary with +.Dq extra +header extensions (an older format that is no longer used), or +.Dq sparse +extensions. +.It "V" +The +.Va name +field should be interpreted as a tape/volume header name. +This entry should generally be ignored on extraction. +.El +.It Va magic +The magic field holds the five characters +.Dq ustar +followed by a space. +Note that POSIX ustar archives have a trailing null. +.It Va version +The version field holds a space character followed by a null. +Note that POSIX ustar archives use two copies of the ASCII digit +.Dq 0 . +.It Va atime , Va ctime +The time the file was last accessed and the time of +last change of file information, stored in octal as with +.Va mtime . +.It Va longnames +This field is apparently no longer used. +.It Sparse Va offset / Va 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. +.It Va isextended +If this is set to non-zero, the header will be followed by additional +.Dq sparse header +records. +Each such record contains information about as many as 21 additional +sparse blocks as shown here: +.Bd -literal -offset indent +struct gnu_sparse_header { + struct { + char offset[12]; + char numbytes[12]; + } sparse[21]; + char isextended[1]; + char padding[7]; +}; +.Ed +.It Va realsize +A binary representation of the file's complete size, with a much larger range +than the POSIX file size. +In particular, with +.Cm 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 +.Va realsize +field will indicate the total size of the file. +.El +.Ss Solaris Tar +XXX More Details Needed XXX +.Pp +Solaris tar (beginning with SunOS XXX 5.7 ?? XXX) supports an +.Dq extended +format that is fundamentally similar to pax interchange format, +with the following differences: +.Bl -bullet -compact -width indent +.It +Extended attributes are stored in an entry whose type is +.Cm X , +not +.Cm x , +as used by pax interchange format. +The detailed format of this entry appears to be the same +as detailed above for the +.Cm x +entry. +.It +An additional +.Cm 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. +.El +.Ss Other Extensions +One common extension, utilized by GNU tar, star, and other newer +.Nm +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. +.Pp +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. +.Sh SEE ALSO +.Xr ar 1 , +.Xr pax 1 , +.Xr tar 1 +.Sh STANDARDS +The +.Nm tar +utility is no longer a part of POSIX or the Single Unix Standard. +It last appeared in +.St -susv2 . +It has been supplanted in subsequent standards by +.Xr pax 1 . +The ustar format is currently part of the specification for the +.Xr pax 1 +utility. +The pax interchange file format is new with +.St -p1003.1-2001 . +.Sh HISTORY +A +.Nm tar +command appeared in Seventh Edition Unix, which was released in January, 1979. +It replaced the +.Nm tp +program from Fourth Edition Unix which in turn replaced the +.Nm tap +program from First Edition Unix. +John Gilmore's +.Nm pdtar +public-domain implementation (circa 1987) was highly influential +and formed the basis of +.Nm GNU tar . +Joerg Shilling's +.Nm star +archiver is another open-source (GPL) archiver (originally developed +circa 1985) which features complete support for pax interchange +format. diff --git a/archivers/libarchive/files/doc/text/archive_entry.3.txt b/archivers/libarchive/files/doc/text/archive_entry.3.txt new file mode 100644 index 00000000000..5201c4f6d5b --- /dev/null +++ b/archivers/libarchive/files/doc/text/archive_entry.3.txt @@ -0,0 +1,350 @@ +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_w, archive_entry_copy_gname, + archive_entry_copy_gname_w, archive_entry_copy_hardlink, + archive_entry_copy_hardlink_w, archive_entry_copy_pathname_w, + 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_stat, + archive_entry_symlink, archive_entry_uid, archive_entry_uname -- func- + tions for manipulating archive entry descriptions + +SYNOPSIS + #include <archive_entry.h> + + void + archive_entry_acl_add_entry(struct archive_entry *, int type, + int permset, int tag, int qual, const char *name); + + void + archive_entry_acl_add_entry_w(struct archive_entry *, int type, + int permset, int tag, int qual, const wchar_t *name); + + void + archive_entry_acl_clear(struct archive_entry *); + + int + archive_entry_acl_count(struct archive_entry *, int type); + + int + archive_entry_acl_next(struct archive_entry *, int want_type, int *type, + int *permset, int *tag, int *qual, const char **name); + + int + archive_entry_acl_next_w(struct archive_entry *, int want_type, + int *type, int *permset, int *tag, int *qual, const wchar_t **name); + + int + archive_entry_acl_reset(struct archive_entry *, int want_type); + + const wchar_t * + archive_entry_acl_text_w(struct archive_entry *, int flags); + + time_t + archive_entry_atime(struct archive_entry *); + + long + archive_entry_atime_nsec(struct archive_entry *); + + struct archive_entry * + archive_entry_clear(struct archive_entry *); + + struct archive_entry * + archive_entry_clone(struct archive_entry *); + + const 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_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 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_w() function parses 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 evalu- + ated, and the bitmaps will be set to reflect every name that is recog- + nized. (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 6.0 December 15, 2003 FreeBSD 6.0 diff --git a/archivers/libarchive/files/doc/text/archive_read.3.txt b/archivers/libarchive/files/doc/text/archive_read.3.txt new file mode 100644 index 00000000000..95b86866b06 --- /dev/null +++ b/archivers/libarchive/files/doc/text/archive_read.3.txt @@ -0,0 +1,395 @@ +archive_read(3) FreeBSD Library Functions Manual archive_read(3) + +NAME + archive_read_new, 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_data, + archive_read_data_block, archive_read_data_skip, + archive_read_data_into_buffer, archive_read_data_into_fd, + archive_read_extract, archive_read_extract_set_progress_callback, + archive_read_close, archive_read_finish -- functions for reading stream- + ing 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_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 **); + + 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); + + 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_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. + 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_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 6.0 August 19, 2006 FreeBSD 6.0 diff --git a/archivers/libarchive/files/doc/text/archive_util.3.txt b/archivers/libarchive/files/doc/text/archive_util.3.txt new file mode 100644 index 00000000000..28b688362ba --- /dev/null +++ b/archivers/libarchive/files/doc/text/archive_util.3.txt @@ -0,0 +1,91 @@ +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 6.0 January 8, 2005 FreeBSD 6.0 diff --git a/archivers/libarchive/files/doc/text/archive_write.3.txt b/archivers/libarchive/files/doc/text/archive_write.3.txt new file mode 100644 index 00000000000..a16d36419bd --- /dev/null +++ b/archivers/libarchive/files/doc/text/archive_write.3.txt @@ -0,0 +1,420 @@ +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_gzip, + archive_write_set_compression_none, + archive_write_set_compression_program, 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 ar- + chives + +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_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_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_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_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, 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, 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 6.0 August 19, 2006 FreeBSD 6.0 diff --git a/archivers/libarchive/files/doc/text/archive_write_disk.3.txt b/archivers/libarchive/files/doc/text/archive_write_disk.3.txt new file mode 100644 index 00000000000..18e4e50c113 --- /dev/null +++ b/archivers/libarchive/files/doc/text/archive_write_disk.3.txt @@ -0,0 +1,253 @@ +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_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 6.0 March 2, 2007 FreeBSD 6.0 diff --git a/archivers/libarchive/files/doc/text/bsdcpio.1.txt b/archivers/libarchive/files/doc/text/bsdcpio.1.txt new file mode 100644 index 00000000000..75e097ea722 --- /dev/null +++ b/archivers/libarchive/files/doc/text/bsdcpio.1.txt @@ -0,0 +1,199 @@ +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 and extract the con- + tents to disk or (if the -t option is specified) list the con- + tents to standard output. + -o Output. Read a list of filenames from standard input and produce + a new archive on standard output containing the specified items. + If one or more file patterns are specified, only files matching + one of the patterns will be extracted. + -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 and p modes) Reset access times on files after they are read. + (Not yet implemented) + + -B (o mode only) Block output to records of 5120 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. + + -f pattern + (i mode only) Ignore files that match pattern. (Not yet imple- + mented.) + + --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 Input mode. See above for description. + + -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. (Not yet implemented.) + + -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. + + -o Output mode. See above for description. + + -p Pass-through mode. See above for description. + + --quiet + (Not yet implemented.) + + -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 to stdout. In input mode, this option is + ignored; bzip2 compression is recognized automatically on input. + + -z (o mode only) Compress the archive with gzip-compatible compres- + sion before writing it to stdout. 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 PWB/UNIX + 1.0, the ``Programmer's Work Bench'' system developed for use within AT&T + and released in 1977. XXX It was first released outside of AT&T as part + of System III Unix in 1981. XXX XXX Need to verify the previous state- + ment. XXX As a result, cpio actually predates tar, even though it was not + well-known outside of AT&T until some time later. XXX When did cpio + first appear in BSD? XXX + + 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. + + This is an early alpha version of cpio. The underlying libarchive + library is quite mature, so the archive format support and creation of + objects on disk should be robust. However, the cpio-specific options and + features are still very new. Known issues that will be fixed soon: + o Options documented above as ``Not yet implemented''. + o Filter arguments to -i, and -it. + +FreeBSD 6.0 August 05, 2007 FreeBSD 6.0 diff --git a/archivers/libarchive/files/doc/text/bsdtar.1.txt b/archivers/libarchive/files/doc/text/bsdtar.1.txt new file mode 100644 index 00000000000..0340a12af81 --- /dev/null +++ b/archivers/libarchive/files/doc/text/bsdtar.1.txt @@ -0,0 +1,450 @@ +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 (-W check-links) + (c and r modes only) Issue a warning message unless all links to + each file are archived. + + --exclude pattern (-W 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 (-W format=format) + (c mode only) Use the specified format for the created archive. + Supported formats include ``cpio'', ``pax'', ``shar'', and + ``ustar''. Other formats may also be supported; see + libarchive-formats(5) for more information about currently-sup- + ported formats. + + -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.) + + --fast-read (-W 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. + + -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 (-W 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. + + -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 If POSIXLY_CORRECT is specified in the environment, this is a + synonym for the --check-links option. Otherwise, an error will + be displayed. Users who desire behavior compatible with GNU tar + should use the --one-file-system option instead. + + -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 (-W newer=date) + (c, r, u modes only) Only include files and directories newer + than the specified date. This compares ctime entries. + + --newer-mtime date (-W newer-mtime=date) + (c, r, u modes only) Like --newer, except it compares mtime + entries instead of ctime entries. + + --newer-than file (-W 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 (-W newer-mtime-than=file) + (c, r, u modes only) Like --newer-than, except it compares mtime + entries instead of ctime entries. + + --nodump (-W nodump) + (c and r modes only) Honor the nodump file flag by skipping this + file. + + --null (-W 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). + + -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 only) Use the user and group of the user running the pro- + gram 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 infor- + mation in the archive will be discarded. + + --one-file-system (-W one-file-system) + (c, r, and u modes) Do not cross mount points. + + -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. + + --strip-components count (-W strip-components=count) + (x and t mode only) Remove the specified number of leading path + elements. Pathnames with fewer elements will be silently + skipped. Note that the pathname is edited after checking inclu- + sion/exclusion patterns but before security checks. + + -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. + + -W longopt=value + Long options (preceded by --) are only supported directly on sys- + tems that have the getopt_long(3) function. The -W option can be + used to access long options on systems that do not support this + function. + + -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. + +ENVIRONMENT + The following environment variables affect the execution of tar: + + LANG The locale to use. See environ(7) for more information. + + POSIXLY_CORRECT + If this environment variable is defined, the -l option will be + interpreted in accordance with ISO/IEC 9945-1:1996 + (``POSIX.1''). + + 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. + + 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''. + +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. + + On systems that support getopt_long(), additional long options are avail- + able 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), 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 + POSIX and GNU violently disagree about the meaning of the -l option. + Because of the potential for disaster if someone expects one behavior and + gets the other, the -l option is deliberately broken in this implementa- + tion. + + 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 6.0 April 13, 2004 FreeBSD 6.0 diff --git a/archivers/libarchive/files/doc/text/cpio.5.txt b/archivers/libarchive/files/doc/text/cpio.5.txt new file mode 100644 index 00000000000..db5da1e9c9b --- /dev/null +++ b/archivers/libarchive/files/doc/text/cpio.5.txt @@ -0,0 +1,235 @@ +CPIO(5) FreeBSD File Formats Manual CPIO(5) + +NAME + cpio -- format of cpio archive files + +DESCRIPTION + The cpio archive format collects any number of files, directories, and + other file system objects (symbolic links, device nodes, etc.) into a + single stream of bytes. + + General Format + Each file system object in a cpio archive comprises a header record with + basic numeric metadata followed by the full pathname of the entry and the + file data. The header record stores a series of integer values that gen- + erally follow the fields in struct stat. (See stat(2) for details.) The + variants differ primarily in how they store those integers (binary, + octal, or hexadecimal). The header is followed by the pathname of the + entry (the length of the pathname is stored in the header) and any file + data. The end of the archive is indicated by a special record with the + pathname ``TRAILER!!!''. + + PWB format + XXX Any documentation of the original PWB/UNIX 1.0 format? XXX + + Old Binary Format + The old binary cpio format stores numbers as 2-byte and 4-byte binary + values. Each entry begins with a header in the following format: + + struct header_old_cpio { + unsigned short c_magic; + unsigned short c_dev; + unsigned short c_ino; + unsigned short c_mode; + unsigned short c_uid; + unsigned short c_gid; + unsigned short c_nlink; + unsigned short c_rdev; + unsigned short c_mtime[2]; + unsigned short c_namesize; + unsigned short c_filesize[2]; + }; + + The unsigned short fields here are 16-bit integer values; the unsigned + int fields are 32-bit integer values. The fields are as follows + + magic The integer value octal 070707. This value can be used to deter- + mine whether this archive is written with little-endian or big- + endian integers. + + dev, ino + The device and inode numbers from the disk. These are used by + programs that read cpio archives to determine when two entries + refer to the same file. Programs that synthesize cpio archives + should be careful to set these to distinct values for each entry. + + mode The mode specifies both the regular permissions and the file + type. It consists of several bit fields as follows: + 0170000 This masks the file type bits. + 0140000 File type value for sockets. + 0120000 File type value for symbolic links. For symbolic links, + the link body is stored as file data. + 0100000 File type value for regular files. + 0060000 File type value for block special devices. + 0040000 File type value for directories. + 0020000 File type value for character special devices. + 0010000 File type value for named pipes or FIFOs. + 0004000 SUID bit. + 0002000 SGID bit. + 0001000 Sticky bit. On some systems, this modifies the behavior + of executables and/or directories. + 0000777 The lower 9 bits specify read/write/execute permissions + for world, group, and user following standard POSIX con- + ventions. + + uid, gid + The numeric user id and group id of the owner. + + nlink The number of links to this file. Directories always have a + value of at least two here. Note that hardlinked files include + file data with every copy in the archive. + + rdev For block special and character special entries, this field con- + tains the associated device number. For all other entry types, + it should be set to zero by writers and ignored by readers. + + mtime Modification time of the file, indicated as the number of seconds + since the start of the epoch, 00:00:00 UTC January 1, 1970. The + four-byte integer is stored with the most-significant 16 bits + first followed by the least-significant 16 bits. Each of the two + 16 bit values are stored in machine-native byte order. + + namesize + The number of bytes in the pathname that follows the header. + This count includes the trailing NULL 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 NULL byte is added after the pathname. The file data + is then appended, padded with NULL 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 NULL 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 NULL 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 sup- + ports only 4 gigabyte files (unlike the older ASCII format, which sup- + ports 8 gigabyte files). + + In this format, hardlinked files are handled by setting the filesize to + zero for each entry except the last one that appears in the archive. + + New CRC Format + The CRC format is identical to the new ASCII format described in the 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 6.0 October 5, 2007 FreeBSD 6.0 diff --git a/archivers/libarchive/files/doc/text/libarchive-formats.5.txt b/archivers/libarchive/files/doc/text/libarchive-formats.5.txt new file mode 100644 index 00000000000..35eb2783bab --- /dev/null +++ b/archivers/libarchive/files/doc/text/libarchive-formats.5.txt @@ -0,0 +1,180 @@ +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. + +SEE ALSO + ar(1), cpio(1), mkisofs(1), shar(1), tar(1), zip(1), zlib(3), cpio(5), + mtree(5), tar(5) + +FreeBSD 6.0 April 27, 2004 FreeBSD 6.0 diff --git a/archivers/libarchive/files/doc/text/libarchive.3.txt b/archivers/libarchive/files/doc/text/libarchive.3.txt new file mode 100644 index 00000000000..f4925f08ae8 --- /dev/null +++ b/archivers/libarchive/files/doc/text/libarchive.3.txt @@ -0,0 +1,185 @@ +LIBARCHIVE(3) FreeBSD Library Functions Manual LIBARCHIVE(3) + +NAME + libarchive -- functions for reading and writing streaming archives + +LIBRARY + Streaming Archive Library (libarchive, -larchive) + +OVERVIEW + The libarchive library provides a flexible interface for reading and + writing streaming archive files such as tar and cpio. The library is + inherently stream-oriented; readers serially iterate through the archive, + writers serially add things to the archive. In particular, note that + there is no built-in support for random access nor for in-place modifica- + tion. + + When reading an archive, the library automatically detects the format and + the compression. The library currently has read support for: + o old-style tar archives, + o most variants of the POSIX ``ustar'' format, + o the POSIX ``pax interchange'' format, + o GNU-format tar archives, + o most common cpio archive formats, + o ISO9660 CD images (with or without RockRidge extensions), + o Zip archives. + The library automatically detects archives compressed with gzip(1), + bzip2(1), or compress(1) and decompresses them transparently. + + When writing an archive, you can specify the compression to be used and + the format to use. The library can write + o POSIX-standard ``ustar'' archives, + o POSIX ``pax interchange format'' archives, + o POSIX octet-oriented cpio archives, + o two different variants of shar archives. + Pax interchange format is an extension of the tar archive format that + eliminates essentially all of the limitations of historic tar formats in + a standard fashion that is supported by POSIX-compliant pax(1) implemen- + tations on many systems as well as several newer implementations of + tar(1). Note that the default write format will suppress the pax + extended attributes for most entries; explicitly requesting pax format + will enable those attributes for all entries. + + The read and write APIs are accessed through the archive_read_XXX() func- + tions and the archive_write_XXX() functions, respectively, and either can + be used independently of the other. + + The rest of this manual page provides an overview of the library opera- + tion. More detailed information can be found in the individual manual + pages for each API or utility function. + +READING AN ARCHIVE + To read an archive, you must first obtain an initialized struct archive + object from archive_read_new(). You can then modify this object for the + desired operations with the various archive_read_set_XXX() and + archive_read_support_XXX() functions. In particular, you will need to + invoke appropriate archive_read_support_XXX() functions to enable the + corresponding compression and format support. Note that these latter + functions perform two distinct operations: they cause the corresponding + support code to be linked into your program, and they enable the corre- + sponding auto-detect code. Unless you have specific constraints, you + will generally want to invoke archive_read_support_compression_all() and + archive_read_support_format_all() to enable auto-detect for all formats + and compression types currently supported by the library. + + Once you have prepared the struct archive object, you call + archive_read_open() to actually open the archive and prepare it for read- + ing. There are several variants of this function; the most basic expects + you to provide pointers to several functions that can provide blocks of + bytes from the archive. There are convenience forms that allow you to + specify a filename, file descriptor, FILE * object, or a block of memory + from which to read the archive data. Note that the core library makes no + assumptions about the size of the blocks read; callback functions are + free to read whatever block size is most appropriate for the medium. + + Each archive entry consists of a header followed by a certain amount of + data. You can obtain the next header with archive_read_next_header(), + which returns a pointer to an struct archive_entry structure with infor- + mation about the current archive element. If the entry is a regular + file, then the header will be followed by the file data. You can use + archive_read_data() (which works much like the read(2) system call) to + read this data from the archive. You may prefer to use the higher-level + archive_read_data_skip(), which reads and discards the data for this + entry, archive_read_data_to_buffer(), which reads the data into an in- + memory buffer, archive_read_data_to_file(), which copies the data to the + provided file descriptor, or archive_read_extract(), which recreates the + specified entry on disk and copies data from the archive. In particular, + note that archive_read_extract() uses the struct archive_entry structure + that you provide it, which may differ from the entry just read from the + archive. In particular, many applications will want to override the + pathname, file permissions, or ownership. + + Once you have finished reading data from the archive, you should call + archive_read_close() to close the archive, then call + archive_read_finish() to release all resources, including all memory + allocated by the library. + + The archive_read(3) manual page provides more detailed calling informa- + tion for this API. + +WRITING AN ARCHIVE + You use a similar process to write an archive. The archive_write_new() + function creates an archive object useful for writing, the various + archive_write_set_XXX() functions are used to set parameters for writing + the archive, and archive_write_open() completes the setup and opens the + archive for writing. + + Individual archive entries are written in a three-step process: You first + initialize a struct archive_entry structure with information about the + new entry. At a minimum, you should set the pathname of the entry and + provide a struct stat with a valid st_mode field, which specifies the + type of object and st_size field, which specifies the size of the data + portion of the object. The archive_write_header() function actually + writes the header data to the archive. You can then use + archive_write_data() to write the actual data. + + After all entries have been written, use the archive_write_finish() func- + tion to release all resources. + + The archive_write(3) manual page provides more detailed calling informa- + tion for this API. + +DESCRIPTION + Detailed descriptions of each function are provided by the corresponding + manual pages. + + All of the functions utilize an opaque struct archive datatype that pro- + vides access to the archive contents. + + The struct archive_entry structure contains a complete description of a + single archive entry. It uses an opaque interface that is fully docu- + mented in archive_entry(3). + + Users familiar with historic formats should be aware that the newer vari- + ants have eliminated most restrictions on the length of textual fields. + Clients should not assume that filenames, link names, user names, or + group names are limited in length. In particular, pax interchange format + can easily accommodate pathnames in arbitrary character sets that exceed + PATH_MAX. + +RETURN VALUES + Most functions return zero on success, non-zero on error. The return + value indicates the general severity of the error, ranging from + ARCHIVE_WARN, which indicates a minor problem that should probably be + reported to the user, to ARCHIVE_FATAL, which indicates a serious problem + that will prevent any further operations on this archive. On error, the + archive_errno() function can be used to retrieve a numeric error code + (see errno(2)). The archive_error_string() returns a textual error mes- + sage suitable for display. + + archive_read_new() and archive_write_new() return pointers to an allo- + cated and initialized struct archive object. + + archive_read_data() and archive_write_data() return a count of the number + of bytes actually read or written. A value of zero indicates the end of + the data for this entry. A negative value indicates an error, in which + case the archive_errno() and archive_error_string() functions can be used + to obtain more information. + +ENVIRONMENT + There are character set conversions within the archive_entry(3) functions + that are impacted by the currently-selected locale. + +SEE ALSO + tar(1), archive_entry(3), archive_read(3), archive_util(3), + archive_write(3), tar(5) + +HISTORY + The libarchive library first appeared in FreeBSD 5.3. + +AUTHORS + The libarchive library was written by Tim Kientzle <kientzle@acm.org>. + +BUGS + Some archive formats support information that is not supported by struct + archive_entry. Such information cannot be fully archived or restored + using this library. This includes, for example, comments, character + sets, or the arbitrary key/value pairs that can appear in pax interchange + format archives. + + Conversely, of course, not all of the information that can be stored in + an struct archive_entry is supported by all formats. For example, cpio + formats do not support nanosecond timestamps; old tar formats do not sup- + port large device numbers. + +FreeBSD 6.0 August 19, 2006 FreeBSD 6.0 diff --git a/archivers/libarchive/files/doc/text/libarchive_internals.3.txt b/archivers/libarchive/files/doc/text/libarchive_internals.3.txt new file mode 100644 index 00000000000..4e398a1b3dc --- /dev/null +++ b/archivers/libarchive/files/doc/text/libarchive_internals.3.txt @@ -0,0 +1,248 @@ +LIBARCHIVE(3) FreeBSD Library Functions Manual LIBARCHIVE(3) + +NAME + libarchive_internals -- description of libarchive internal interfaces + +OVERVIEW + The libarchive library provides a flexible interface for reading and + writing streaming archive files such as tar and cpio. Internally, it + follows a modular layered design that should make it easy to add new ar- + chive and compression formats. + +GENERAL ARCHITECTURE + Externally, libarchive exposes most operations through an opaque, object- + style interface. The archive_entry(1) objects store information about a + single filesystem object. The rest of the library provides facilities to + write archive_entry(1) objects to archive files, read them from archive + files, and write them to disk. (There are plans to add a facility to + read archive_entry(1) objects from disk as well.) + + The read and write APIs each have four layers: a public API layer, a for- + mat layer that understands the archive file format, a compression layer, + and an I/O layer. The I/O layer is completely exposed to clients who can + replace it entirely with their own functions. + + In order to provide as much consistency as possible for clients, some + public functions are virtualized. Eventually, it should be possible for + clients to open an archive or disk writer, and then use a single set of + code to select and write entries, regardless of the target. + +READ ARCHITECTURE + From the outside, clients use the archive_read(3) API to manipulate an + archive object to read entries and bodies from an archive stream. Inter- + nally, the archive object is cast to an archive_read object, which holds + all read-specific data. The API has four layers: The lowest layer is the + I/O layer. This layer can be overridden by clients, but most clients use + the packaged I/O callbacks provided, for example, by + archive_read_open_memory(3), and archive_read_open_fd(3). The compres- + sion layer calls the I/O layer to read bytes and decompresses them for + the format layer. The format layer unpacks a stream of uncompressed + bytes and creates archive_entry objects from the incoming data. The API + layer tracks overall state (for example, it prevents clients from reading + data before reading a header) and invokes the format and compression + layer operations through registered function pointers. In particular, + the API layer drives the format-detection process: When opening the ar- + chive, it reads an initial block of data and offers it to each registered + compression handler. The one with the highest bid is initialized with + the first block. Similarly, the format handlers are polled to see which + handler is the best for each archive. (Prior to 2.4.0, the format bid- + ders were invoked for each entry, but this design hindered error recov- + ery.) + + I/O Layer and Client Callbacks + The read API goes to some lengths to be nice to clients. As a result, + there are few restrictions on the behavior of the client callbacks. + + The client read callback is expected to provide a block of data on each + call. A zero-length return does indicate end of file, but otherwise + blocks may be as small as one byte or as large as the entire file. In + particular, blocks may be of different sizes. + + The client skip callback returns the number of bytes actually skipped, + which may be much smaller than the skip requested. The only requirement + is that the skip not be larger. In particular, clients are allowed to + return zero for any skip that they don't want to handle. The skip call- + back must never be invoked with a negative value. + + Keep in mind that not all clients are reading from disk: clients reading + from networks may provide different-sized blocks on every request and + cannot skip at all; advanced clients may use mmap(2) to read the entire + file into memory at once and return the entire file to libarchive as a + single block; other clients may begin asynchronous I/O operations for the + next block on each request. + + Decompresssion Layer + The decompression layer not only handles decompression, it also buffers + data so that the format handlers see a much nicer I/O model. The decom- + pression API is a two stage peek/consume model. A read_ahead request + specifies a minimum read amount; the decompression layer must provide a + pointer to at least that much data. If more data is immediately avail- + able, it should return more: the format layer handles bulk data reads by + asking for a minimum of one byte and then copying as much data as is + available. + + A subsequent call to the consume() function advances the read pointer. + Note that data returned from a read_ahead() call is guaranteed to remain + in place until the next call to read_ahead(). Intervening calls to + consume() should not cause the data to move. + + Skip requests must always be handled exactly. Decompression handlers + that cannot seek forward should not register a skip handler; the API + layer fills in a generic skip handler that reads and discards data. + + A decompression handler has a specific lifecycle: + Registration/Configuration + When the client invokes the public support function, the decom- + pression handler invokes the internal + __archive_read_register_compression() function to provide bid and + initialization functions. This function returns NULL on error or + else a pointer to a struct decompressor_t. This structure con- + tains a void * config slot that can be used for storing any cus- + tomization information. + Bid The bid function is invoked with a pointer and size of a block of + data. The decompressor can access its config data through the + decompressor element of the archive_read object. The bid func- + tion is otherwise stateless. In particular, it must not perform + any I/O operations. + + The value returned by the bid function indicates its suitability + for handling this data stream. A bid of zero will ensure that + this decompressor is never invoked. Return zero if magic number + checks fail. Otherwise, your initial implementation should + return the number of bits actually checked. For example, if you + verify two full bytes and three bits of another byte, bid 19. + Note that the initial block may be very short; be careful to only + inspect the data you are given. (The current decompressors + require two bytes for correct bidding.) + Initialize + The winning bidder will have its init function called. This + function should initialize the remaining slots of the struct + decompressor_t object pointed to by the decompressor element of + the archive_read object. In particular, it should allocate any + working data it needs in the data slot of that structure. The + init function is called with the block of data that was used for + tasting. At this point, the decompressor is responsible for all + I/O requests to the client callbacks. The decompressor is free + to read more data as and when necessary. + Satisfy I/O requests + The format handler will invoke the read_ahead, consume, and skip + functions as needed. + Finish The finish method is called only once when the archive is closed. + It should release anything stored in the data and config slots of + the decompressor object. It should not invoke the client close + callback. + + Format Layer + The read formats have a similar lifecycle to the decompression handlers: + Registration + Allocate your private data and initialize your pointers. + Bid Formats bid by invoking the read_ahead() decompression method but + not calling the consume() method. This allows each bidder to + look ahead in the input stream. Bidders should not look further + ahead than necessary, as long look aheads put pressure on the + decompression layer to buffer lots of data. Most formats only + require a few hundred bytes of look ahead; look aheads of a few + kilobytes are reasonable. (The ISO9660 reader sometimes looks + ahead by 48k, which should be considered an upper limit.) + Read header + The header read is usually the most complex part of any format. + There are a few strategies worth mentioning: For formats such as + tar or cpio, reading and parsing the header is straightforward + since headers alternate with data. For formats that store all + header data at the beginning of the file, the first header read + request may have to read all headers into memory and store that + data, sorted by the location of the file data. Subsequent header + read requests will skip forward to the beginning of the file data + and return the corresponding header. + Read Data + The read data interface supports sparse files; this requires that + each call return a block of data specifying the file offset and + size. This may require you to carefully track the location so + that you can return accurate file offsets for each read. Remem- + ber that the decompressor will return as much data as it has. + Generally, you will want to request one byte, examine the return + value to see how much data is available, and possibly trim that + to the amount you can use. You should invoke consume for each + block just before you return it. + Skip All Data + The skip data call should skip over all file data and trailing + padding. This is called automatically by the API layer just + before each header read. It is also called in response to the + client calling the public data_skip() function. + Cleanup + On cleanup, the format should release all of its allocated mem- + ory. + + API Layer + XXX to do XXX + +WRITE ARCHITECTURE + The write API has a similar set of four layers: an API layer, a format + layer, a compression layer, and an I/O layer. The registration here is + much simpler because only one format and one compression can be regis- + tered at a time. + + I/O Layer and Client Callbacks + XXX To be written XXX + + Compression Layer + XXX To be written XXX + + Format Layer + XXX To be written XXX + + API Layer + XXX To be written XXX + +WRITE_DISK ARCHITECTURE + The write_disk API is intended to look just like the write API to + clients. Since it does not handle multiple formats or compression, it is + not layered internally. + +GENERAL SERVICES + The archive_read, archive_write, and archive_write_disk objects all con- + tain an initial archive object which provides common support for a set of + standard services. (Recall that ANSI/ISO C90 guarantees that you can + cast freely between a pointer to a structure and a pointer to the first + element of that structure.) The archive object has a magic value that + indicates which API this object is associated with, slots for storing + error information, and function pointers for virtualized API functions. + +MISCELLANEOUS NOTES + Connecting existing archiving libraries into libarchive is generally + quite difficult. In particular, many existing libraries strongly assume + that you are reading from a file; they seek forwards and backwards as + necessary to locate various pieces of information. In contrast, + libarchive never seeks backwards in its input, which sometimes requires + very different approaches. + + For example, libarchive's ISO9660 support operates very differently from + most ISO9660 readers. The libarchive support utilizes a work-queue + design that keeps a list of known entries sorted by their location in the + input. Whenever libarchive's ISO9660 implementation is asked for the + next header, checks this list to find the next item on the disk. Direc- + tories are parsed when they are encountered and new items are added to + the list. This design relies heavily on the ISO9660 image being opti- + mized so that directories always occur earlier on the disk than the files + they describe. + + Depending on the specific format, such approaches may not be possible. + The ZIP format specification, for example, allows archivers to store key + information only at the end of the file. In theory, it is possible to + create ZIP archives that cannot be read without seeking. Fortunately, + such archives are very rare, and libarchive can read most ZIP archives, + though it cannot always extract as much information as a dedicated ZIP + program. + +SEE ALSO + archive(3), archive_entry(3), archive_read(3), archive_write(3), + archive_write_disk(3) + +HISTORY + The libarchive library first appeared in FreeBSD 5.3. + +AUTHORS + The libarchive library was written by Tim Kientzle <kientzle@acm.org>. + +BUGS +FreeBSD 6.0 April 16, 2007 FreeBSD 6.0 diff --git a/archivers/libarchive/files/doc/text/mtree.5.txt b/archivers/libarchive/files/doc/text/mtree.5.txt new file mode 100644 index 00000000000..1e5eb4f42b0 --- /dev/null +++ b/archivers/libarchive/files/doc/text/mtree.5.txt @@ -0,0 +1,158 @@ +MTREE(5) FreeBSD File Formats Manual MTREE(5) + +NAME + mtree -- format of mtree dir heirarchy 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 heirarchies. + + 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 definitions 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 whose contents should be compared + to 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. + + ignore Ignore any file hierarchy below this file. + + gid The file group as a numeric value. + + gname The file group as a symbolic name. + + md5 The MD5 message digest of the file. + + md5digest A synonym for md5. + + 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. + + ripemd160digest + The RIPEMD160 message digest of the file. + + rmd160 A synonym for ripemd160digest. + + rmd160digest + A synonym for ripemd160digest. + + 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. + + uid The file owner as a numeric value. + + uname The file owner as a symbolic name. + + size The size, in bytes, of the file. + + link The file the symbolic link is expected to reference. + + 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 + +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 6.0 August 20, 2007 FreeBSD 6.0 diff --git a/archivers/libarchive/files/doc/text/tar.5.txt b/archivers/libarchive/files/doc/text/tar.5.txt new file mode 100644 index 00000000000..24b77e15984 --- /dev/null +++ b/archivers/libarchive/files/doc/text/tar.5.txt @@ -0,0 +1,534 @@ +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. NULL 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 NULL 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 NULL. + + Field termination is specified slightly differently by POSIX than by pre- + vious implementations. The magic, uname, and gname fields must have a + trailing NULL. The pathname, linkname, and prefix fields must have a + trailing NULL 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 NULL + 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 6.0 May 20, 2004 FreeBSD 6.0 |