1.\" Copyright (c) 2003-2007 Tim Kientzle 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD$ 26.\" 27.Dd February 2, 2012 28.Dt ARCHIVE_UTIL 3 29.Os 30.Sh NAME 31.Nm archive_clear_error , 32.Nm archive_compression , 33.Nm archive_compression_name , 34.Nm archive_copy_error , 35.Nm archive_errno , 36.Nm archive_error_string , 37.Nm archive_file_count , 38.Nm archive_filter_code , 39.Nm archive_filter_count , 40.Nm archive_filter_name , 41.Nm archive_format , 42.Nm archive_format_name , 43.Nm archive_position , 44.Nm archive_set_error 45.Nd libarchive utility functions 46.Sh LIBRARY 47Streaming Archive Library (libarchive, -larchive) 48.Sh SYNOPSIS 49.In archive.h 50.Ft void 51.Fn archive_clear_error "struct archive *" 52.Ft int 53.Fn archive_compression "struct archive *" 54.Ft const char * 55.Fn archive_compression_name "struct archive *" 56.Ft void 57.Fn archive_copy_error "struct archive *" "struct archive *" 58.Ft int 59.Fn archive_errno "struct archive *" 60.Ft const char * 61.Fn archive_error_string "struct archive *" 62.Ft int 63.Fn archive_file_count "struct archive *" 64.Ft int 65.Fn archive_filter_code "struct archive *" "int" 66.Ft int 67.Fn archive_filter_count "struct archive *" "int" 68.Ft const char * 69.Fn archive_filter_name "struct archive *" "int" 70.Ft int 71.Fn archive_format "struct archive *" 72.Ft const char * 73.Fn archive_format_name "struct archive *" 74.Ft int64_t 75.Fn archive_position "struct archive *" "int" 76.Ft void 77.Fo archive_set_error 78.Fa "struct archive *" 79.Fa "int error_code" 80.Fa "const char *fmt" 81.Fa "..." 82.Fc 83.Sh DESCRIPTION 84These functions provide access to various information about the 85.Tn struct archive 86object used in the 87.Xr libarchive 3 88library. 89.Bl -tag -compact -width indent 90.It Fn archive_clear_error 91Clears any error information left over from a previous call. 92Not generally used in client code. 93.It Fn archive_compression 94Synonym for 95.Fn archive_filter_code a 0 . 96.It Fn archive_compression_name 97Synonym for 98.Fn archive_filter_name a 0 . 99.It Fn archive_copy_error 100Copies error information from one archive to another. 101.It Fn archive_errno 102Returns a numeric error code (see 103.Xr errno 2 ) 104indicating the reason for the most recent error return. 105Note that this can not be reliably used to detect whether an 106error has occurred. 107It should be used only after another libarchive function 108has returned an error status. 109.It Fn archive_error_string 110Returns a textual error message suitable for display. 111The error message here is usually more specific than that 112obtained from passing the result of 113.Fn archive_errno 114to 115.Xr strerror 3 . 116.It Fn archive_file_count 117Returns a count of the number of files processed by this archive object. 118The count is incremented by calls to 119.Xr archive_write_header 3 120or 121.Xr archive_read_next_header 3 . 122.It Fn archive_filter_code 123Returns a numeric code identifying the indicated filter. 124See 125.Fn archive_filter_count 126for details of the numbering. 127.It Fn archive_filter_count 128Returns the number of filters in the current pipeline. 129For read archive handles, these filters are added automatically 130by the automatic format detection. 131For write archive handles, these filters are added by calls to the various 132.Fn archive_write_add_filter_XXX 133functions. 134Filters in the resulting pipeline are numbered so that filter 0 135is the filter closest to the format handler. 136As a convenience, functions that expect a filter number will 137accept -1 as a synonym for the highest-numbered filter. 138.Pp 139For example, when reading a uuencoded gzipped tar archive, there 140are three filters: 141filter 0 is the gunzip filter, 142filter 1 is the uudecode filter, 143and filter 2 is the pseudo-filter that wraps the archive read functions. 144In this case, requesting 145.Fn archive_position a -1 146would be a synonym for 147.Fn archive_position a 2 148which would return the number of bytes currently read from the archive, while 149.Fn archive_position a 1 150would return the number of bytes after uudecoding, and 151.Fn archive_position a 0 152would return the number of bytes after decompression. 153.It Fn archive_filter_name 154Returns a textual name identifying the indicated filter. 155See 156.Fn archive_filter_count 157for details of the numbering. 158.It Fn archive_format 159Returns a numeric code indicating the format of the current 160archive entry. 161This value is set by a successful call to 162.Fn archive_read_next_header . 163Note that it is common for this value to change from 164entry to entry. 165For example, a tar archive might have several entries that 166utilize GNU tar extensions and several entries that do not. 167These entries will have different format codes. 168.It Fn archive_format_name 169A textual description of the format of the current entry. 170.It Fn archive_position 171Returns the number of bytes read from or written to the indicated filter. 172In particular, 173.Fn archive_position a 0 174returns the number of bytes read or written by the format handler, while 175.Fn archive_position a -1 176returns the number of bytes read or written to the archive. 177See 178.Fn archive_filter_count 179for details of the numbering here. 180.It Fn archive_set_error 181Sets the numeric error code and error description that will be returned 182by 183.Fn archive_errno 184and 185.Fn archive_error_string . 186This function should be used within I/O callbacks to set system-specific 187error codes and error descriptions. 188This function accepts a printf-like format string and arguments. 189However, you should be careful to use only the following printf 190format specifiers: 191.Dq %c , 192.Dq %d , 193.Dq %jd , 194.Dq %jo , 195.Dq %ju , 196.Dq %jx , 197.Dq %ld , 198.Dq %lo , 199.Dq %lu , 200.Dq %lx , 201.Dq %o , 202.Dq %u , 203.Dq %s , 204.Dq %x , 205.Dq %% . 206Field-width specifiers and other printf features are 207not uniformly supported and should not be used. 208.El 209.Sh SEE ALSO 210.Xr archive_read 3 , 211.Xr archive_write 3 , 212.Xr libarchive 3 , 213.Xr printf 3 214.Sh HISTORY 215The 216.Nm libarchive 217library first appeared in 218.Fx 5.3 . 219.Sh AUTHORS 220.An -nosplit 221The 222.Nm libarchive 223library was written by 224.An Tim Kientzle Aq kientzle@acm.org . 225