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