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