Index: stable/7/lib/libarchive/archive_entry.3 =================================================================== --- stable/7/lib/libarchive/archive_entry.3 (revision 179167) +++ stable/7/lib/libarchive/archive_entry.3 (revision 179168) @@ -1,382 +1,422 @@ .\" 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 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_link , +.Nm archive_entry_copy_link_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" +.Fo archive_entry_acl_add_entry +.Fa "struct archive_entry *" +.Fa "int type" +.Fa "int permset" +.Fa "int tag" +.Fa "int qual" +.Fa "const char *name" +.Fc .Ft void -.Fn archive_entry_acl_add_entry_w "struct archive_entry *" "int type" "int permset" "int tag" "int qual" "const wchar_t *name" +.Fo archive_entry_acl_add_entry_w +.Fa "struct archive_entry *" +.Fa "int type" +.Fa "int permset" +.Fa "int tag" +.Fa "int qual" +.Fa "const wchar_t *name" +.Fc .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" +.Fo archive_entry_acl_next +.Fa "struct archive_entry *" +.Fa "int want_type" +.Fa "int *type" +.Fa "int *permset" +.Fa "int *tag" +.Fa "int *qual" +.Fa "const char **name" +.Fc .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" +.Fo archive_entry_acl_next_w +.Fa "struct archive_entry *" +.Fa "int want_type" +.Fa "int *type" +.Fa "int *permset" +.Fa "int *tag" +.Fa "int *qual" +.Fa "const wchar_t **name" +.Fc .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" +.Fo archive_entry_fflags +.Fa "struct archive_entry *" +.Fa "unsigned long *set" +.Fa "unsigned long *clear" +.Fc .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" +.Fo archive_entry_set_fflags +.Fa "struct archive_entry *" +.Fa "unsigned long set" +.Fa "unsigned long clear" +.Fc .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 Index: stable/7/lib/libarchive/archive_read.3 =================================================================== --- stable/7/lib/libarchive/archive_read.3 (revision 179167) +++ stable/7/lib/libarchive/archive_read.3 (revision 179168) @@ -1,524 +1,582 @@ .\" 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 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" +.Fo archive_read_support_compression_program +.Fa "struct archive *" +.Fa "const char *cmd" +.Fc .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 *" +.Fo archive_read_open +.Fa "struct archive *" +.Fa "void *client_data" +.Fa "archive_open_callback *" +.Fa "archive_read_callback *" +.Fa "archive_close_callback *" +.Fc .Ft int -.Fn archive_read_open2 "struct archive *" "void *client_data" "archive_open_callback *" "archive_read_callback *" "archive_skip_callback *" "archive_close_callback *" +.Fo archive_read_open2 +.Fa "struct archive *" +.Fa "void *client_data" +.Fa "archive_open_callback *" +.Fa "archive_read_callback *" +.Fa "archive_skip_callback *" +.Fa "archive_close_callback *" +.Fc .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" +.Fo archive_read_open_filename +.Fa "struct archive *" +.Fa "const char *filename" +.Fa "size_t block_size" +.Fc .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" +.Fo archive_read_data_block +.Fa "struct archive *" +.Fa "const void **buff" +.Fa "size_t *len" +.Fa "off_t *offset" +.Fc .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" +.Fo archive_read_extract +.Fa "struct archive *" +.Fa "struct archive_entry *" +.Fa "int flags" +.Fc .Ft void -.Fn archive_read_extract_set_progress_callback "struct archive *" "void (*func)(void *)" "void *user_data" +.Fo archive_read_extract_set_progress_callback +.Fa "struct archive *" +.Fa "void (*func)(void *)" +.Fa "void *user_data" +.Fc .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 +.It Xo +.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 +.Xc 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 +.It Xo +.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 +.Xc 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" +.Fo archive_read_callback +.Fa "struct archive *" +.Fa "void *client_data" +.Fa "const void **buffer" +.Fc .It .\" #if ARCHIVE_API_VERSION < 2 .Ft typedef int -.Fn archive_skip_callback "struct archive *" "void *client_data" "size_t request" +.Fo archive_skip_callback +.Fa "struct archive *" +.Fa "void *client_data" +.Fa "size_t request" +.Fc .\" #else .\" .Ft typedef off_t -.\" .Fn archive_skip_callback "struct archive *" "void *client_data" "off_t request" +.\" .Fo archive_skip_callback +.\" .Fa "struct archive *" +.\" .Fa "void *client_data" +.\" .Fa "off_t request" +.\" .Fc .\" #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. Index: stable/7/lib/libarchive/archive_util.3 =================================================================== --- stable/7/lib/libarchive/archive_util.3 (revision 179167) +++ stable/7/lib/libarchive/archive_util.3 (revision 179168) @@ -1,146 +1,151 @@ .\" 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 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" "..." +.Fo archive_set_error +.Fa "struct archive *" +.Fa "int error_code" +.Fa "const char *fmt" +.Fa "..." +.Fc .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 . Index: stable/7/lib/libarchive/archive_write.3 =================================================================== --- stable/7/lib/libarchive/archive_write.3 (revision 179167) +++ stable/7/lib/libarchive/archive_write.3 (revision 179168) @@ -1,524 +1,554 @@ .\" 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 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" +.Fo archive_write_set_compression_program +.Fa "struct archive *" +.Fa "const char * cmd" +.Fc .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 *" +.Fo archive_write_open +.Fa "struct archive *" +.Fa "void *client_data" +.Fa "archive_open_callback *" +.Fa "archive_write_callback *" +.Fa "archive_close_callback *" +.Fc .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" +.Fo archive_write_open_memory +.Fa "struct archive *" +.Fa "void *buffer" +.Fa "size_t bufferSize" +.Fa "size_t *outUsed" +.Fc .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 +.It Xo +.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 +.Xc 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 +.It Xo +.Fn archive_write_set_compression_bzip2 , +.Fn archive_write_set_compression_gzip , +.Fn archive_write_set_compression_none +.Xc 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" +.Fo archive_write_callback +.Fa "struct archive *" +.Fa "void *client_data" +.Fa "void *buffer" +.Fa "size_t length" +.Fc .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 #include #include #include #include #include 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. Index: stable/7/lib/libarchive/archive_write_disk.3 =================================================================== --- stable/7/lib/libarchive/archive_write_disk.3 (revision 179167) +++ stable/7/lib/libarchive/archive_write_disk.3 (revision 179168) @@ -1,358 +1,371 @@ .\" 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 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 *)" +.Fo archive_write_disk_set_group_lookup +.Fa "struct archive *" +.Fa "void *" +.Fa "gid_t (*)(void *, const char *gname, gid_t gid)" +.Fa "void (*cleanup)(void *)" +.Fc .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 *)" +.Fo archive_write_disk_set_user_lookup +.Fa "struct archive *" +.Fa "void *" +.Fa "uid_t (*)(void *, const char *uname, uid_t uid)" +.Fa "void (*cleanup)(void *)" +.Fc .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 +.It Xo +.Fn archive_write_disk_set_group_lookup , +.Fn archive_write_disk_set_user_lookup +.Xc 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