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