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: head/lib/libarchive/archive_util.3 201098 2009-12-28 02:58:14Z kientzle $ 26.\" 27.Dd January 8, 2005 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 SYNOPSIS 47.In archive.h 48.Ft void 49.Fn archive_clear_error "struct archive *" 50.Ft int 51.Fn archive_compression "struct archive *" 52.Ft const char * 53.Fn archive_compression_name "struct archive *" 54.Ft void 55.Fn archive_copy_error "struct archive *" "struct archive *" 56.Ft int 57.Fn archive_errno "struct archive *" 58.Ft const char * 59.Fn archive_error_string "struct archive *" 60.Ft int 61.Fn archive_file_count "struct archive *" 62.Ft int 63.Fn archive_filter_code "struct archive *" "int" 64.Ft int 65.Fn archive_filter_count "struct archive *" "int" 66.Ft const char * 67.Fn archive_filter_name "struct archive *" "int" 68.Ft int 69.Fn archive_format "struct archive *" 70.Ft const char * 71.Fn archive_format_name "struct archive *" 72.Ft int64_t 73.Fn archive_position "struct archive *" "int" 74.Ft void 75.Fo archive_set_error 76.Fa "struct archive *" 77.Fa "int error_code" 78.Fa "const char *fmt" 79.Fa "..." 80.Fc 81.Sh DESCRIPTION 82These functions provide access to various information about the 83.Tn struct archive 84object used in the 85.Xr libarchive 3 86library. 87.Bl -tag -compact -width indent 88.It Fn archive_clear_error 89Clears any error information left over from a previous call. 90Not generally used in client code. 91.It Fn archive_compression 92Synonym for 93.Fn archive_filter_code(a, 0) . 94.It Fn archive_compression_name 95Synonym for 96.Fn archive_filter_name(a, 0) . 97.It Fn archive_copy_error 98Copies error information from one archive to another. 99.It Fn archive_errno 100Returns a numeric error code (see 101.Xr errno 2 ) 102indicating the reason for the most recent error return. 103Note that this can not be reliably used to detect whether an 104error has occurred. 105It should be used only after another libarchive function 106has returned an error status. 107.It Fn archive_error_string 108Returns a textual error message suitable for display. 109The error message here is usually more specific than that 110obtained from passing the result of 111.Fn archive_errno 112to 113.Xr strerror 3 . 114.It Fn archive_file_count 115Returns a count of the number of files processed by this archive object. 116The count is incremented by calls to 117.Xr archive_write_header 3 118or 119.Xr archive_read_next_header 3 . 120.It Fn archive_filter_code 121Returns a numeric code identifying the indicated filter. 122See 123.Fn archive_filter_count 124for details of the numbering. 125.It Fn archive_filter_count 126Returns the number of filters in the current pipeline. 127For read archive handles, these filters are added automatically 128by the automatic format detection. 129For write archive handles, these filters are added by calls to the various 130.Fn archive_write_add_filter_XXX 131functions. 132Filters in the resulting pipeline are numbered so that filter 0 133is the filter closest to the format handler. 134As a convenience, functions that expect a filter number will 135accept -1 as a synonym for the highest-numbered filter. 136.Pp 137For example, when reading a uuencoded gzipped tar archive, there 138are three filters: 139filter 0 is the gunzip filter, 140filter 1 is the uudecode filter, 141and filter 2 is the pseudo-filter that wraps the archive read functions. 142In this case, requesting 143.Fn archive_position(a, -1) 144would be a synonym for 145.Fn archive_position(a, 2) 146which would return the number of bytes currently read from the archive, while 147.Fn archive_position(a, 1) 148would return the number of bytes after uudecoding, and 149.Fn archive_position(a, 0) 150would return the number of bytes after decompression. 151.It Fn archive_filter_name 152Returns a textual name identifying the indicated filter. 153See 154.Fn archive_filter_count 155for details of the numbering. 156.It Fn archive_format 157Returns a numeric code indicating the format of the current 158archive entry. 159This value is set by a successful call to 160.Fn archive_read_next_header . 161Note that it is common for this value to change from 162entry to entry. 163For example, a tar archive might have several entries that 164utilize GNU tar extensions and several entries that do not. 165These entries will have different format codes. 166.It Fn archive_format_name 167A textual description of the format of the current entry. 168.It Fn archive_position 169Returns the number of bytes read from or written to the indicated filter. 170In particular, 171.Fn archive_position(a, 0) 172returns the number of bytes read or written by the format handler, while 173.Fn archive_position(a, -1) 174returns the number of bytes read or written to the archive. 175See 176.Fn archive_filter_count 177for details of the numbering here. 178.It Fn archive_set_error 179Sets the numeric error code and error description that will be returned 180by 181.Fn archive_errno 182and 183.Fn archive_error_string . 184This function should be used within I/O callbacks to set system-specific 185error codes and error descriptions. 186This function accepts a printf-like format string and arguments. 187However, you should be careful to use only the following printf 188format specifiers: 189.Dq %c , 190.Dq %d , 191.Dq %jd , 192.Dq %jo , 193.Dq %ju , 194.Dq %jx , 195.Dq %ld , 196.Dq %lo , 197.Dq %lu , 198.Dq %lx , 199.Dq %o , 200.Dq %u , 201.Dq %s , 202.Dq %x , 203.Dq %% . 204Field-width specifiers and other printf features are 205not uniformly supported and should not be used. 206.El 207.Sh SEE ALSO 208.Xr archive_read 3 , 209.Xr archive_write 3 , 210.Xr libarchive 3 , 211.Xr printf 3 212.Sh HISTORY 213The 214.Nm libarchive 215library first appeared in 216.Fx 5.3 . 217.Sh AUTHORS 218.An -nosplit 219The 220.Nm libarchive 221library was written by 222.An Tim Kientzle Aq kientzle@acm.org . 223