contrib/libarchive/libarchive/archive_read_open.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_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
  39 Streaming 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 *" "void *buff" "size_t size"
  71 .Sh DESCRIPTION
  72 .Bl -tag -compact -width indent
  73 .It Fn archive_read_open
  74 The same as
  75 .Fn archive_read_open2 ,
  76 except that the skip callback is assumed to be
  77 .Dv NULL .
  78 .It Fn archive_read_open2
  79 Freeze the settings, open the archive, and prepare for reading entries.
  80 This is the most generic version of this call, which accepts
  81 four callback functions.
  82 Most clients will want to use
  83 .Fn archive_read_open_filename ,
  84 .Fn archive_read_open_FILE ,
  85 .Fn archive_read_open_fd ,
  86 or
  87 .Fn archive_read_open_memory
  88 instead.
  89 The library invokes the client-provided functions to obtain
  90 raw bytes from the archive.
  91 .It Fn archive_read_open_FILE
  92 Like
  93 .Fn archive_read_open ,
  94 except that it accepts a
  95 .Ft "FILE *"
  96 pointer.
  97 This function should not be used with tape drives or other devices
  98 that require strict I/O blocking.
  99 .It Fn archive_read_open_fd
 100 Like
 101 .Fn archive_read_open ,
 102 except that it accepts a file descriptor and block size rather than
 103 a set of function pointers.
 104 Note that the file descriptor will not be automatically closed at
 105 end-of-archive.
 106 This function is safe for use with tape drives or other blocked devices.
 107 .It Fn archive_read_open_file
 108 This is a deprecated synonym for
 109 .Fn archive_read_open_filename .
 110 .It Fn archive_read_open_filename
 111 Like
 112 .Fn archive_read_open ,
 113 except that it accepts a simple filename and a block size.
 114 A NULL filename represents standard input.
 115 This function is safe for use with tape drives or other blocked devices.
 116 .It Fn archive_read_open_memory
 117 Like
 118 .Fn archive_read_open ,
 119 except that it accepts a pointer and size of a block of
 120 memory containing the archive data.
 121 .El
 122 .Pp
 123 A complete description of the
 124 .Tn struct archive
 125 and
 126 .Tn struct archive_entry
 127 objects can be found in the overview manual page for
 128 .Xr libarchive 3 .
 129 .Sh CLIENT CALLBACKS
 130 The 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
 154 The open callback is invoked by
 155 .Fn archive_open .
 156 It should return
 157 .Cm ARCHIVE_OK
 158 if the underlying file or data source is successfully
 159 opened.
 160 If the open fails, it should call
 161 .Fn archive_set_error
 162 to register an error code and message and return
 163 .Cm ARCHIVE_FATAL .
 164 .Pp
 165 The read callback is invoked whenever the library
 166 requires raw bytes from the archive.
 167 The read callback should read data into a buffer,
 168 set the
 169 .Li const void **buffer
 170 argument to point to the available data, and
 171 return a count of the number of bytes available.
 172 The library will invoke the read callback again
 173 only after it has consumed this data.
 174 The library imposes no constraints on the size
 175 of the data blocks returned.
 176 On end-of-file, the read callback should
 177 return zero.
 178 On error, the read callback should invoke
 179 .Fn archive_set_error
 180 to register an error code and message and
 181 return -1.
 182 .Pp
 183 The skip callback is invoked when the
 184 library wants to ignore a block of data.
 185 The return value is the number of bytes actually
 186 skipped, which may differ from the request.
 187 If the callback cannot skip data, it should return
 188 zero.
 189 If the skip callback is not provided (the
 190 function pointer is
 191 .Dv NULL ),
 192 the library will invoke the read function
 193 instead and simply discard the result.
 194 A skip callback can provide significant
 195 performance gains when reading uncompressed
 196 archives from slow disk drives or other media
 197 that can skip quickly.
 198 .Pp
 199 The close callback is invoked by archive_close when
 200 the archive processing is complete.
 201 The callback should return
 202 .Cm ARCHIVE_OK
 203 on success.
 204 On failure, the callback should invoke
 205 .Fn archive_set_error
 206 to register an error code and message and
 207 return
 208 .Cm ARCHIVE_FATAL.
 209 .\" .Sh EXAMPLE
 210 .\"
 211 .Sh RETURN VALUES
 212 These functions return
 213 .Cm ARCHIVE_OK
 214 on success, or
 215 .Cm ARCHIVE_FATAL .
 216 .\"
 217 .Sh ERRORS
 218 Detailed error codes and textual descriptions are available from the
 219 .Fn archive_errno
 220 and
 221 .Fn archive_error_string
 222 functions.
 223 .\"
 224 .Sh SEE ALSO
 225 .Xr tar 1 ,
 226 .Xr libarchive 3 ,
 227 .Xr archive_read 3 ,
 228 .Xr archive_read_data 3 ,
 229 .Xr archive_read_filter 3 ,
 230 .Xr archive_read_format 3 ,
 231 .Xr archive_read_set_options 3 ,
 232 .Xr archive_util 3 ,
 233 .Xr tar 5