1<!-- Creator : groff version 1.22.4 --> 2<!-- CreationDate: Sun Aug 22 23:03:25 2021 --> 3<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 4"http://www.w3.org/TR/html4/loose.dtd"> 5<html> 6<head> 7<meta name="generator" content="groff -Thtml, see www.gnu.org"> 8<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> 9<meta name="Content-Style" content="text/css"> 10<style type="text/css"> 11 p { margin-top: 0; margin-bottom: 0; vertical-align: top } 12 pre { margin-top: 0; margin-bottom: 0; vertical-align: top } 13 table { margin-top: 0; margin-bottom: 0; vertical-align: top } 14 h1 { text-align: center } 15</style> 16<title></title> 17</head> 18<body> 19 20<hr> 21 22 23<p>ARCHIVE_READ(3) BSD Library Functions Manual 24ARCHIVE_READ(3)</p> 25 26<p style="margin-top: 1em"><b>NAME</b></p> 27 28<p style="margin-left:6%;"><b>archive_read</b> — 29functions for reading streaming archives</p> 30 31<p style="margin-top: 1em"><b>LIBRARY</b></p> 32 33<p style="margin-left:6%;">Streaming Archive Library 34(libarchive, -larchive)</p> 35 36<p style="margin-top: 1em"><b>SYNOPSIS</b></p> 37 38<p style="margin-left:6%;"><b>#include 39<archive.h></b></p> 40 41<p style="margin-top: 1em"><b>DESCRIPTION</b></p> 42 43<p style="margin-left:6%;">These functions provide a 44complete API for reading streaming archives. The general 45process is to first create the struct archive object, set 46options, initialize the reader, iterate over the archive 47headers and associated data, then close the archive and 48release all resources.</p> 49 50<p style="margin-left:6%; margin-top: 1em"><b>Create 51archive object</b> <br> 52See archive_read_new(3).</p> 53 54<p style="margin-left:6%; margin-top: 1em">To read an 55archive, you must first obtain an initialized struct archive 56object from <b>archive_read_new</b>().</p> 57 58<p style="margin-left:6%; margin-top: 1em"><b>Enable 59filters and formats</b> <br> 60See archive_read_filter(3) and archive_read_format(3).</p> 61 62<p style="margin-left:6%; margin-top: 1em">You can then 63modify this object for the desired operations with the 64various <b>archive_read_set_XXX</b>() and 65<b>archive_read_support_XXX</b>() functions. In particular, 66you will need to invoke appropriate 67<b>archive_read_support_XXX</b>() functions to enable the 68corresponding compression and format support. Note that 69these latter functions perform two distinct operations: they 70cause the corresponding support code to be linked into your 71program, and they enable the corresponding auto-detect code. 72Unless you have specific constraints, you will generally 73want to invoke <b>archive_read_support_filter_all</b>() and 74<b>archive_read_support_format_all</b>() to enable 75auto-detect for all formats and compression types currently 76supported by the library.</p> 77 78<p style="margin-left:6%; margin-top: 1em"><b>Set 79options</b> <br> 80See archive_read_set_options(3).</p> 81 82<p style="margin-left:6%; margin-top: 1em"><b>Open 83archive</b> <br> 84See archive_read_open(3).</p> 85 86<p style="margin-left:6%; margin-top: 1em">Once you have 87prepared the struct archive object, you call 88<b>archive_read_open</b>() to actually open the archive and 89prepare it for reading. There are several variants of this 90function; the most basic expects you to provide pointers to 91several functions that can provide blocks of bytes from the 92archive. There are convenience forms that allow you to 93specify a filename, file descriptor, <i>FILE *</i> object, 94or a block of memory from which to read the archive data. 95Note that the core library makes no assumptions about the 96size of the blocks read; callback functions are free to read 97whatever block size is most appropriate for the medium.</p> 98 99<p style="margin-left:6%; margin-top: 1em"><b>Consume 100archive</b> <br> 101See archive_read_header(3), archive_read_data(3) and 102archive_read_extract(3).</p> 103 104<p style="margin-left:6%; margin-top: 1em">Each archive 105entry consists of a header followed by a certain amount of 106data. You can obtain the next header with 107<b>archive_read_next_header</b>(), which returns a pointer 108to an struct archive_entry structure with information about 109the current archive element. If the entry is a regular file, 110then the header will be followed by the file data. You can 111use <b>archive_read_data</b>() (which works much like the 112read(2) system call) to read this data from the archive, or 113<b>archive_read_data_block</b>() which provides a slightly 114more efficient interface. You may prefer to use the 115higher-level <b>archive_read_data_skip</b>(), which reads 116and discards the data for this entry, 117<b>archive_read_data_into_fd</b>(), which copies the data to 118the provided file descriptor, or 119<b>archive_read_extract</b>(), which recreates the specified 120entry on disk and copies data from the archive. In 121particular, note that <b>archive_read_extract</b>() uses the 122struct archive_entry structure that you provide it, which 123may differ from the entry just read from the archive. In 124particular, many applications will want to override the 125pathname, file permissions, or ownership.</p> 126 127<p style="margin-left:6%; margin-top: 1em"><b>Release 128resources</b> <br> 129See archive_read_free(3).</p> 130 131<p style="margin-left:6%; margin-top: 1em">Once you have 132finished reading data from the archive, you should call 133<b>archive_read_close</b>() to close the archive, then call 134<b>archive_read_free</b>() to release all resources, 135including all memory allocated by the library.</p> 136 137<p style="margin-top: 1em"><b>EXAMPLES</b></p> 138 139<p style="margin-left:6%;">The following illustrates basic 140usage of the library. In this example, the callback 141functions are simply wrappers around the standard open(2), 142read(2), and close(2) system calls.</p> 143 144<p style="margin-left:14%; margin-top: 1em">void <br> 145list_archive(const char *name) <br> 146{ <br> 147struct mydata *mydata; <br> 148struct archive *a; <br> 149struct archive_entry *entry;</p> 150 151<p style="margin-left:14%; margin-top: 1em">mydata = 152malloc(sizeof(struct mydata)); <br> 153a = archive_read_new(); <br> 154mydata->name = name; <br> 155archive_read_support_filter_all(a); <br> 156archive_read_support_format_all(a); <br> 157archive_read_open(a, mydata, myopen, myread, myclose); <br> 158while (archive_read_next_header(a, &entry) == 159ARCHIVE_OK) { <br> 160printf("%s\n",archive_entry_pathname(entry)); <br> 161archive_read_data_skip(a); <br> 162} <br> 163archive_read_free(a); <br> 164free(mydata); <br> 165}</p> 166 167<p style="margin-left:14%; margin-top: 1em">la_ssize_t <br> 168myread(struct archive *a, void *client_data, const void 169**buff) <br> 170{ <br> 171struct mydata *mydata = client_data;</p> 172 173<p style="margin-left:14%; margin-top: 1em">*buff = 174mydata->buff; <br> 175return (read(mydata->fd, mydata->buff, 10240)); <br> 176}</p> 177 178<p style="margin-left:14%; margin-top: 1em">int <br> 179myopen(struct archive *a, void *client_data) <br> 180{ <br> 181struct mydata *mydata = client_data;</p> 182 183<p style="margin-left:14%; margin-top: 1em">mydata->fd = 184open(mydata->name, O_RDONLY); <br> 185return (mydata->fd >= 0 ? ARCHIVE_OK : ARCHIVE_FATAL); 186<br> 187}</p> 188 189<p style="margin-left:14%; margin-top: 1em">int <br> 190myclose(struct archive *a, void *client_data) <br> 191{ <br> 192struct mydata *mydata = client_data;</p> 193 194<p style="margin-left:14%; margin-top: 1em">if 195(mydata->fd > 0) <br> 196close(mydata->fd); <br> 197return (ARCHIVE_OK); <br> 198}</p> 199 200<p style="margin-top: 1em"><b>SEE ALSO</b></p> 201 202<p style="margin-left:6%;">tar(1), archive_read_data(3), 203archive_read_extract(3), archive_read_filter(3), 204archive_read_format(3), archive_read_header(3), 205archive_read_new(3), archive_read_open(3), 206archive_read_set_options(3), archive_util(3), libarchive(3), 207tar(5)</p> 208 209<p style="margin-top: 1em"><b>HISTORY</b></p> 210 211<p style="margin-left:6%;">The <b>libarchive</b> library 212first appeared in FreeBSD 5.3.</p> 213 214<p style="margin-top: 1em"><b>AUTHORS</b></p> 215 216<p style="margin-left:6%;">The <b>libarchive</b> library 217was written by Tim Kientzle <kientzle@acm.org>.</p> 218 219<p style="margin-top: 1em"><b>BUGS</b></p> 220 221<p style="margin-left:6%;">Many traditional archiver 222programs treat empty files as valid empty archives. For 223example, many implementations of tar(1) allow you to append 224entries to an empty file. Of course, it is impossible to 225determine the format of an empty file by inspecting the 226contents, so this library treats empty files as having a 227special “empty” format.</p> 228 229<p style="margin-left:6%; margin-top: 1em">BSD 230February 2, 2012 BSD</p> 231<hr> 232</body> 233</html> 234