contrib/libarchive/libarchive/archive_read_extract.3

   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
  36 Streaming 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
  60 A convenience function that wraps the corresponding
  61 .Xr archive_write_disk 3
  62 interfaces.
  63 The first call to
  64 .Fn archive_read_extract
  65 creates a restore object using
  66 .Xr archive_write_disk_new 3
  67 and
  68 .Xr archive_write_disk_set_standard_lookup 3 ,
  69 then transparently invokes
  70 .Xr archive_write_disk_set_options 3 ,
  71 .Xr archive_write_header 3 ,
  72 .Xr archive_write_data 3 ,
  73 and
  74 .Xr archive_write_finish_entry 3
  75 to create the entry on disk and copy data into it.
  76 The
  77 .Va flags
  78 argument is passed unmodified to
  79 .Xr archive_write_disk_set_options 3 .
  80 .It Fn archive_read_extract2
  81 This is another version of
  82 .Fn archive_read_extract
  83 that allows you to provide your own restore object.
  84 In particular, this allows you to override the standard lookup functions
  85 using
  86 .Xr archive_write_disk_set_group_lookup 3 ,
  87 and
  88 .Xr archive_write_disk_set_user_lookup 3 .
  89 Note that
  90 .Fn archive_read_extract2
  91 does not accept a
  92 .Va flags
  93 argument; you should use
  94 .Fn archive_write_disk_set_options
  95 to set the restore options yourself.
  96 .It Fn archive_read_extract_set_progress_callback
  97 Sets a pointer to a user-defined callback that can be used
  98 for updating progress displays during extraction.
  99 The progress function will be invoked during the extraction of large
 100 regular files.
 101 The progress function will be invoked with the pointer provided to this call.
 102 Generally, the data pointed to should include a reference to the archive
 103 object and the archive_entry object so that various statistics
 104 can be retrieved for the progress display.
 105 .El
 106 .\"
 107 .Sh RETURN VALUES
 108 Most functions return zero on success, non-zero on error.
 109 The 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),
 118 and
 119 .Cm ARCHIVE_FATAL
 120 (there was a fatal error; the archive should be closed immediately).
 121 .Sh ERRORS
 122 Detailed error codes and textual descriptions are available from the
 123 .Fn archive_errno
 124 and
 125 .Fn archive_error_string
 126 functions.
 127 .Sh SEE ALSO
 128 .Xr tar 1 ,
 129 .Xr archive_read 3 ,
 130 .Xr archive_read_data 3 ,
 131 .Xr archive_read_filter 3 ,
 132 .Xr archive_read_format 3 ,
 133 .Xr archive_read_open 3 ,
 134 .Xr archive_read_set_options 3 ,
 135 .Xr archive_util 3 ,
 136 .Xr libarchive 3 ,
 137 .Xr tar 5