1<!-- Creator : groff version 1.22.4 --> 2<!-- CreationDate: Sun Aug 22 23:03:26 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_OPEN(3) BSD Library Functions Manual 24ARCHIVE_READ_OPEN(3)</p> 25 26<p style="margin-top: 1em"><b>NAME</b></p> 27 28<p style="margin-left:6%;"><b>archive_read_open</b>, 29<b>archive_read_open2</b>, <b>archive_read_open_fd</b>, 30<b>archive_read_open_FILE</b>, 31<b>archive_read_open_filename</b>, 32<b>archive_read_open_memory</b> — functions for 33reading streaming archives</p> 34 35<p style="margin-top: 1em"><b>LIBRARY</b></p> 36 37<p style="margin-left:6%;">Streaming Archive Library 38(libarchive, -larchive)</p> 39 40<p style="margin-top: 1em"><b>SYNOPSIS</b></p> 41 42<p style="margin-left:6%;"><b>#include 43<archive.h></b></p> 44 45<p style="margin-left:6%; margin-top: 1em"><i>int</i></p> 46 47 48<p><b>archive_read_open</b>(<i>struct archive *</i>, 49<i>void *client_data</i>, 50<i>archive_open_callback *</i>, 51<i>archive_read_callback *</i>, 52<i>archive_close_callback *</i>);</p> 53 54<p style="margin-left:6%; margin-top: 1em"><i>int</i></p> 55 56 57<p><b>archive_read_open2</b>(<i>struct archive *</i>, 58<i>void *client_data</i>, 59<i>archive_open_callback *</i>, 60<i>archive_read_callback *</i>, 61<i>archive_skip_callback *</i>, 62<i>archive_close_callback *</i>);</p> 63 64<p style="margin-left:6%; margin-top: 1em"><i>int</i></p> 65 66 67<p style="margin-left:12%;"><b>archive_read_open_FILE</b>(<i>struct archive *</i>, 68<i>FILE *file</i>);</p> 69 70<p style="margin-left:6%; margin-top: 1em"><i>int</i></p> 71 72 73<p style="margin-left:12%;"><b>archive_read_open_fd</b>(<i>struct archive *</i>, 74<i>int fd</i>, <i>size_t block_size</i>);</p> 75 76<p style="margin-left:6%; margin-top: 1em"><i>int</i></p> 77 78 79<p><b>archive_read_open_filename</b>(<i>struct archive *</i>, 80<i>const char *filename</i>, 81<i>size_t block_size</i>);</p> 82 83<p style="margin-left:6%; margin-top: 1em"><i>int</i></p> 84 85 86<p style="margin-left:12%;"><b>archive_read_open_memory</b>(<i>struct archive *</i>, 87<i>const void *buff</i>, 88<i>size_t size</i>);</p> 89 90<p style="margin-top: 1em"><b>DESCRIPTION <br> 91archive_read_open</b>()</p> 92 93<p style="margin-left:17%;">The same as 94<b>archive_read_open2</b>(), except that the skip callback 95is assumed to be NULL.</p> 96 97<p><b>archive_read_open2</b>()</p> 98 99<p style="margin-left:17%;">Freeze the settings, open the 100archive, and prepare for reading entries. This is the most 101generic version of this call, which accepts four callback 102functions. Most clients will want to use 103<b>archive_read_open_filename</b>(), 104<b>archive_read_open_FILE</b>(), 105<b>archive_read_open_fd</b>(), or 106<b>archive_read_open_memory</b>() instead. The library 107invokes the client-provided functions to obtain raw bytes 108from the archive.</p> 109 110<p><b>archive_read_open_FILE</b>()</p> 111 112<p style="margin-left:17%;">Like 113<b>archive_read_open</b>(), except that it accepts a <i>FILE 114*</i> pointer. This function should not be used with tape 115drives or other devices that require strict I/O 116blocking.</p> 117 118<p><b>archive_read_open_fd</b>()</p> 119 120<p style="margin-left:17%;">Like 121<b>archive_read_open</b>(), except that it accepts a file 122descriptor and block size rather than a set of function 123pointers. Note that the file descriptor will not be 124automatically closed at end-of-archive. This function is 125safe for use with tape drives or other blocked devices.</p> 126 127<p><b>archive_read_open_file</b>()</p> 128 129<p style="margin-left:17%;">This is a deprecated synonym 130for <b>archive_read_open_filename</b>().</p> 131 132<p><b>archive_read_open_filename</b>()</p> 133 134<p style="margin-left:17%;">Like 135<b>archive_read_open</b>(), except that it accepts a simple 136filename and a block size. A NULL filename represents 137standard input. This function is safe for use with tape 138drives or other blocked devices.</p> 139 140<p><b>archive_read_open_memory</b>()</p> 141 142<p style="margin-left:17%;">Like 143<b>archive_read_open</b>(), except that it accepts a pointer 144and size of a block of memory containing the archive 145data.</p> 146 147<p style="margin-left:6%; margin-top: 1em">A complete 148description of the struct archive and struct archive_entry 149objects can be found in the overview manual page for 150libarchive(3).</p> 151 152<p style="margin-top: 1em"><b>CLIENT CALLBACKS</b></p> 153 154<p style="margin-left:6%;">The callback functions must 155match the following prototypes:</p> 156 157<p style="margin-left:14%; margin-top: 1em"><i>typedef 158la_ssize_t</i></p> 159 160 161<p><b>archive_read_callback</b>(<i>struct archive *</i>, 162<i>void *client_data</i>, 163<i>const void **buffer</i>)</p> 164 165<p style="margin-left:14%; margin-top: 1em"><i>typedef 166la_int64_t</i></p> 167 168 169<p><b>archive_skip_callback</b>(<i>struct archive *</i>, 170<i>void *client_data</i>, 171<i>off_t request</i>)</p> 172 173<p style="margin-left:14%; margin-top: 1em"><i>typedef 174int</i> <b>archive_open_callback</b>(<i>struct archive 175*</i>, <i>void *client_data</i>)</p> 176 177<p style="margin-left:14%; margin-top: 1em"><i>typedef 178int</i> <b>archive_close_callback</b>(<i>struct archive 179*</i>, <i>void *client_data</i>)</p> 180 181<p style="margin-left:6%; margin-top: 1em">The open 182callback is invoked by <b>archive_open</b>(). It should 183return <b>ARCHIVE_OK</b> if the underlying file or data 184source is successfully opened. If the open fails, it should 185call <b>archive_set_error</b>() to register an error code 186and message and return <b>ARCHIVE_FATAL</b>.</p> 187 188<p style="margin-left:6%; margin-top: 1em">The read 189callback is invoked whenever the library requires raw bytes 190from the archive. The read callback should read data into a 191buffer, set the const void **buffer argument to point to the 192available data, and return a count of the number of bytes 193available. The library will invoke the read callback again 194only after it has consumed this data. The library imposes no 195constraints on the size of the data blocks returned. On 196end-of-file, the read callback should return zero. On error, 197the read callback should invoke <b>archive_set_error</b>() 198to register an error code and message and return -1.</p> 199 200<p style="margin-left:6%; margin-top: 1em">The skip 201callback is invoked when the library wants to ignore a block 202of data. The return value is the number of bytes actually 203skipped, which may differ from the request. If the callback 204cannot skip data, it should return zero. If the skip 205callback is not provided (the function pointer is NULL ), 206the library will invoke the read function instead and simply 207discard the result. A skip callback can provide significant 208performance gains when reading uncompressed archives from 209slow disk drives or other media that can skip quickly.</p> 210 211<p style="margin-left:6%; margin-top: 1em">The close 212callback is invoked by archive_close when the archive 213processing is complete. The callback should return 214<b>ARCHIVE_OK</b> on success. On failure, the callback 215should invoke <b>archive_set_error</b>() to register an 216error code and message and return <b>ARCHIVE_FATAL</b>.</p> 217 218<p style="margin-top: 1em"><b>RETURN VALUES</b></p> 219 220<p style="margin-left:6%;">These functions return 221<b>ARCHIVE_OK</b> on success, or <b>ARCHIVE_FATAL</b>.</p> 222 223<p style="margin-top: 1em"><b>ERRORS</b></p> 224 225<p style="margin-left:6%;">Detailed error codes and textual 226descriptions are available from the <b>archive_errno</b>() 227and <b>archive_error_string</b>() functions.</p> 228 229<p style="margin-top: 1em"><b>SEE ALSO</b></p> 230 231<p style="margin-left:6%;">tar(1), archive_read(3), 232archive_read_data(3), archive_read_filter(3), 233archive_read_format(3), archive_read_set_options(3), 234archive_util(3), libarchive(3), tar(5)</p> 235 236<p style="margin-left:6%; margin-top: 1em">BSD 237February 2, 2012 BSD</p> 238<hr> 239</body> 240</html> 241