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_EXTRACT 3 29.Os 30.Sh NAME 31.Nm archive_read_extract , 32.Nm archive_read_extract2 , 33.Nm archive_read_extract_set_progress_callback 34.Nd functions for reading streaming archives 35.Sh LIBRARY 36Streaming Archive Library (libarchive, -larchive) 37.Sh SYNOPSIS 38.In archive.h 39.Ft int 40.Fo archive_read_extract 41.Fa "struct archive *" 42.Fa "struct archive_entry *" 43.Fa "int flags" 44.Fc 45.Ft int 46.Fo archive_read_extract2 47.Fa "struct archive *src" 48.Fa "struct archive_entry *" 49.Fa "struct archive *dest" 50.Fc 51.Ft void 52.Fo archive_read_extract_set_progress_callback 53.Fa "struct archive *" 54.Fa "void (*func)(void *)" 55.Fa "void *user_data" 56.Fc 57.Sh DESCRIPTION 58.Bl -tag -compact -width indent 59.It Fn archive_read_extract , Fn archive_read_extract_set_skip_file 60A convenience function that wraps the corresponding 61.Xr archive_write_disk 3 62interfaces. 63The first call to 64.Fn archive_read_extract 65creates a restore object using 66.Xr archive_write_disk_new 3 67and 68.Xr archive_write_disk_set_standard_lookup 3 , 69then transparently invokes 70.Xr archive_write_disk_set_options 3 , 71.Xr archive_write_header 3 , 72.Xr archive_write_data 3 , 73and 74.Xr archive_write_finish_entry 3 75to create the entry on disk and copy data into it. 76The 77.Va flags 78argument is passed unmodified to 79.Xr archive_write_disk_set_options 3 . 80.It Fn archive_read_extract2 81This is another version of 82.Fn archive_read_extract 83that allows you to provide your own restore object. 84In particular, this allows you to override the standard lookup functions 85using 86.Xr archive_write_disk_set_group_lookup 3 , 87and 88.Xr archive_write_disk_set_user_lookup 3 . 89Note that 90.Fn archive_read_extract2 91does not accept a 92.Va flags 93argument; you should use 94.Fn archive_write_disk_set_options 95to set the restore options yourself. 96.It Fn archive_read_extract_set_progress_callback 97Sets a pointer to a user-defined callback that can be used 98for updating progress displays during extraction. 99The progress function will be invoked during the extraction of large 100regular files. 101The progress function will be invoked with the pointer provided to this call. 102Generally, the data pointed to should include a reference to the archive 103object and the archive_entry object so that various statistics 104can be retrieved for the progress display. 105.El 106.\" 107.Sh RETURN VALUES 108Most functions return zero on success, non-zero on error. 109The possible return codes include: 110.Cm ARCHIVE_OK 111(the operation succeeded), 112.Cm ARCHIVE_WARN 113(the operation succeeded but a non-critical error was encountered), 114.Cm ARCHIVE_EOF 115(end-of-archive was encountered), 116.Cm ARCHIVE_RETRY 117(the operation failed but can be retried), 118and 119.Cm ARCHIVE_FATAL 120(there was a fatal error; the archive should be closed immediately). 121.Sh ERRORS 122Detailed error codes and textual descriptions are available from the 123.Fn archive_errno 124and 125.Fn archive_error_string 126functions. 127.Sh SEE ALSO 128.Xr tar 1 , 129.Xr libarchive 3 , 130.Xr archive_read 3 , 131.Xr archive_read_data 3 , 132.Xr archive_read_filter 3 , 133.Xr archive_read_format 3 , 134.Xr archive_read_open 3 , 135.Xr archive_read_set_options 3 , 136.Xr archive_util 3 , 137.Xr tar 5 138