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_read.3 191595 2009-04-27 20:13:13Z kientzle $ 26.\" 27.Dd March 23, 2011 28.Dt ARCHIVE_READ 3 29.Os 30.Sh NAME 31.Nm archive_read 32.Nd functions for reading streaming archives 33.Sh SYNOPSIS 34.In archive.h 35.Sh DESCRIPTION 36These functions provide a complete API for reading streaming archives. 37The general process is to first create the 38.Tn struct archive 39object, set options, initialize the reader, iterate over the archive 40headers and associated data, then close the archive and release all 41resources. 42.\" 43.Ss Create archive object 44See 45.Xr archive_read_new 3 . 46.Pp 47To read an archive, you must first obtain an initialized 48.Tn struct archive 49object from 50.Fn archive_read_new . 51.\" 52.Ss Enable filters and formats 53See 54.Xr archive_read_filter 3 55and 56.Xr archive_read_format 3 . 57.Pp 58You can then modify this object for the desired operations with the 59various 60.Fn archive_read_set_XXX 61and 62.Fn archive_read_support_XXX 63functions. 64In particular, you will need to invoke appropriate 65.Fn archive_read_support_XXX 66functions to enable the corresponding compression and format 67support. 68Note that these latter functions perform two distinct operations: 69they cause the corresponding support code to be linked into your 70program, and they enable the corresponding auto-detect code. 71Unless you have specific constraints, you will generally want 72to invoke 73.Fn archive_read_support_filter_all 74and 75.Fn archive_read_support_format_all 76to enable auto-detect for all formats and compression types 77currently supported by the library. 78.\" 79.Ss Set options 80See 81.Xr archive_read_set_options 3 . 82.\" 83.Ss Open archive 84See 85.Xr archive_read_open 3 . 86.Pp 87Once you have prepared the 88.Tn struct archive 89object, you call 90.Fn archive_read_open 91to actually open the archive and prepare it for reading. 92There are several variants of this function; 93the most basic expects you to provide pointers to several 94functions that can provide blocks of bytes from the archive. 95There are convenience forms that allow you to 96specify a filename, file descriptor, 97.Ft "FILE *" 98object, or a block of memory from which to read the archive data. 99Note that the core library makes no assumptions about the 100size of the blocks read; 101callback functions are free to read whatever block size is 102most appropriate for the medium. 103.\" 104.Ss Consume archive 105See 106.Xr archive_read_header 3 , 107.Xr archive_read_data 3 108and 109.Xr archive_read_extract 3 . 110.Pp 111Each archive entry consists of a header followed by a certain 112amount of data. 113You can obtain the next header with 114.Fn archive_read_next_header , 115which returns a pointer to an 116.Tn struct archive_entry 117structure with information about the current archive element. 118If the entry is a regular file, then the header will be followed 119by the file data. 120You can use 121.Fn archive_read_data 122(which works much like the 123.Xr read 2 124system call) 125to read this data from the archive, or 126.Fn archive_read_data_block 127which provides a slightly more efficient interface. 128You may prefer to use the higher-level 129.Fn archive_read_data_skip , 130which reads and discards the data for this entry, 131.Fn archive_read_data_to_file , 132which copies the data to the provided file descriptor, or 133.Fn archive_read_extract , 134which recreates the specified entry on disk and copies data 135from the archive. 136In particular, note that 137.Fn archive_read_extract 138uses the 139.Tn struct archive_entry 140structure that you provide it, which may differ from the 141entry just read from the archive. 142In particular, many applications will want to override the 143pathname, file permissions, or ownership. 144.\" 145.Ss Release resources 146See 147.Xr archive_read_free 3 . 148.Pp 149Once you have finished reading data from the archive, you 150should call 151.Fn archive_read_close 152to close the archive, then call 153.Fn archive_read_free 154to release all resources, including all memory allocated by the library. 155.\" 156.Sh EXAMPLE 157The following illustrates basic usage of the library. 158In this example, 159the callback functions are simply wrappers around the standard 160.Xr open 2 , 161.Xr read 2 , 162and 163.Xr close 2 164system calls. 165.Bd -literal -offset indent 166void 167list_archive(const char *name) 168{ 169 struct mydata *mydata; 170 struct archive *a; 171 struct archive_entry *entry; 172 173 mydata = malloc(sizeof(struct mydata)); 174 a = archive_read_new(); 175 mydata->name = name; 176 archive_read_support_filter_all(a); 177 archive_read_support_format_all(a); 178 archive_read_open(a, mydata, myopen, myread, myclose); 179 while (archive_read_next_header(a, &entry) == ARCHIVE_OK) { 180 printf("%s\en",archive_entry_pathname(entry)); 181 archive_read_data_skip(a); 182 } 183 archive_read_free(a); 184 free(mydata); 185} 186 187ssize_t 188myread(struct archive *a, void *client_data, const void **buff) 189{ 190 struct mydata *mydata = client_data; 191 192 *buff = mydata->buff; 193 return (read(mydata->fd, mydata->buff, 10240)); 194} 195 196int 197myopen(struct archive *a, void *client_data) 198{ 199 struct mydata *mydata = client_data; 200 201 mydata->fd = open(mydata->name, O_RDONLY); 202 return (mydata->fd >= 0 ? ARCHIVE_OK : ARCHIVE_FATAL); 203} 204 205int 206myclose(struct archive *a, void *client_data) 207{ 208 struct mydata *mydata = client_data; 209 210 if (mydata->fd > 0) 211 close(mydata->fd); 212 return (ARCHIVE_OK); 213} 214.Ed 215.\" .Sh ERRORS 216.Sh SEE ALSO 217.Xr tar 1 , 218.Xr libarchive 3 , 219.Xr archive_read_new 3 , 220.Xr archive_read_data 3 , 221.Xr archive_read_extract 3 , 222.Xr archive_read_filter 3 , 223.Xr archive_read_format 3 , 224.Xr archive_read_header 3 , 225.Xr archive_read_open 3 , 226.Xr archive_read_set_options 3 , 227.Xr archive_util 3 , 228.Xr tar 5 229.Sh HISTORY 230The 231.Nm libarchive 232library first appeared in 233.Fx 5.3 . 234.Sh AUTHORS 235.An -nosplit 236The 237.Nm libarchive 238library was written by 239.An Tim Kientzle Aq kientzle@acm.org . 240.Sh BUGS 241Many traditional archiver programs treat 242empty files as valid empty archives. 243For example, many implementations of 244.Xr tar 1 245allow you to append entries to an empty file. 246Of course, it is impossible to determine the format of an empty file 247by inspecting the contents, so this library treats empty files as 248having a special 249.Dq empty 250format. 251