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