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