man/zip_source_function.mdoc

   1 .\" zip_source_function.mdoc -- create data source from function
   2 .\" Copyright (C) 2004-2014 Dieter Baron and Thomas Klausner
   3 .\"
   4 .\" This file is part of libzip, a library to manipulate ZIP archives.
   5 .\" The authors can be contacted at <libzip@nih.at>
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in
  14 .\"    the documentation and/or other materials provided with the
  15 .\"    distribution.
  16 .\" 3. The names of the authors may not be used to endorse or promote
  17 .\"    products derived from this software without specific prior
  18 .\"    written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS ``AS IS'' AND ANY EXPRESS
  21 .\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  22 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY
  24 .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
  26 .\" GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  27 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
  28 .\" IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  29 .\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
  30 .\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  31 .\"
  32 .Dd November 13, 2014
  33 .Dt ZIP_SOURCE_FUNCTION 3
  34 .Os
  35 .Sh NAME
  36 .Nm zip_source_function
  37 .Nd create data source from function
  38 .Sh LIBRARY
  39 libzip (-lzip)
  40 .Sh SYNOPSIS
  41 .In zip.h
  42 .Ft zip_source_t *
  43 .Fn zip_source_function "zip_t *archive" "zip_source_callback fn" "void *userdata"
  44 .Ft zip_source_t *
  45 .Fn zip_source_function_create "zip_source_callback fn" "void *userdata" "zip_error_t *error"
  46 .Sh DESCRIPTION
  47 The functions
  48 .Fn zip_source_function
  49 and
  50 .Fn zip_source_function_create
  51 creates a zip source from the user-provided function
  52 .Ar fn ,
  53 which must be of the following type:
  54 .Pp
  55 .Ft typedef zip_int64_t
  56 .Fo \fR(*\fPzip_source_callback\fR)\fP
  57 .Fa "void *userdata" "void *data" "zip_uint64_t len" "zip_source_cmd_t cmd"
  58 .Fc
  59 .Pp
  60 .Ar archive
  61 or
  62 .Ar error
  63 are used for reporting errors and can be
  64 .Dv NULL .
  65 .Pp
  66 When called by the library, the first argument is the
  67 .Ar userdata
  68 argument supplied to the function.
  69 The next two arguments are a buffer
  70 .Ar data
  71 of size
  72 .Ar len
  73 when data is passed in or expected to be returned, or else
  74 .Dv NULL
  75 and 0.
  76 The last argument,
  77 .Ar cmd ,
  78 specifies which action the function should perform.
  79 .Pp
  80 Depending on the uses, there are three useful sets of commands to be supported by a
  81 .Fn zip_source_callback :
  82 .Bl -tag -width seekable-read-sourceXX
  83 .It read source
  84 Providing streamed data (for file data added to archives).
  85 Must support
  86 .Dv ZIP_SOURCE_OPEN ,
  87 .Dv ZIP_SOURCE_READ ,
  88 .Dv ZIP_SOURCE_CLOSE ,
  89 .Dv ZIP_SOURCE_STAT ,
  90 and
  91 .Dv ZIP_SOURCE_ERROR .
  92 .It seekable read source
  93 Same as previous, but from a source allowing reading from arbitrary
  94 offsets (also for read-only zip archive).
  95 Must additionally support
  96 .Dv ZIP_SOURCE_SEEK ,
  97 .Dv ZIP_SOURCE_TELL ,
  98 and
  99 .Dv ZIP_SOURCE_SUPPORTS .
 100 .It read/write source
 101 Same as previous, but additionally allowing writing (also for writable
 102 zip archives).
 103 Must additionally support
 104 .Dv ZIP_SOURCE_BEGIN_WRITE ,
 105 .Dv ZIP_SOURCE_COMMIT_WRITE ,
 106 .Dv ZIP_SOURCE_ROLLBACK_WRITE ,
 107 .Dv ZIP_SOURCE_SEEK_WRITE ,
 108 .Dv ZIP_SOURCE_TELL_WRITE ,
 109 and
 110 .Dv ZIP_SOURCE_REMOVE .
 111 .El
 112 .Ss Dv ZIP_SOURCE_BEGIN_WRITE
 113 Prepare the source for writing.
 114 Use this to create any temporary file(s).
 115 .Ss Dv ZIP_SOURCE_CLOSE
 116 Reading is done.
 117 .Ss Dv ZIP_SOURCE_COMMIT_WRITE
 118 Finish writing to the source.
 119 Replace the original data with the newly written data.
 120 Clean up temporary files or internal buffers.
 121 Subsequently opening and reading from the source should return the
 122 newly written data.
 123 .Ss Dv ZIP_SOURCE_ERROR
 124 Get error information.
 125 .Ar data
 126 points to an array of two ints, which should be filled with the libzip
 127 error code and the corresponding system error code for the error that
 128 occurred.
 129 See
 130 .Xr zip_errors 3
 131 for details on the error codes.
 132 If the source stores error information in a zip_error_t, use
 133 .Xr zip_error_to_data 3
 134 and return its return value.
 135 Otherwise, return 2 * sizeof(int).
 136 .Ss Dv ZIP_SOURCE_FREE
 137 Clean up and free all resources, including
 138 .Ar state .
 139 The callback function will not be called again.
 140 .Ss Dv ZIP_SOURCE_OPEN
 141 Prepare for reading.
 142 .Ss Dv ZIP_SOURCE_READ
 143 Read data into the buffer
 144 .Ar data
 145 of size
 146 .Ar len .
 147 Return the number of bytes placed into
 148 .Ar data
 149 on success.
 150 .Ss Dv ZIP_SOURCE_REMOVE
 151 Remove the underlying file.
 152 This is called if a zip archive is empty when closed.
 153 .Ss Dv ZIP_SOURCE_ROLLBACK_WRITE
 154 Abort writing to the source.
 155 Discard written data.
 156 Clean up temporary files or internal buffers.
 157 Subsequently opening and reading from the source should return the
 158 original data.
 159 .Ss Dv ZIP_SOURCE_SEEK
 160 Specify position to read next byte from, like
 161 .Xr fseek 3 .
 162 Use
 163 .Xr ZIP_SOURCE_GET_ARGS 3
 164 to decode the arguments into the following struct:
 165 .Bd -literal
 166 struct zip_source_args_seek {
 167     zip_int64_t offset;
 168     int whence;
 169 };
 170 .Ed
 171 .Pp
 172 If the size of the source's data is known, use
 173 .Xr zip_source_seek_compute_offset 3
 174 to validate the arguments and compute the new offset.
 175 .Ss Dv ZIP_SOURCE_SEEK_WRITE
 176 Specify position to write next byte to, like
 177 .Xr fseek 3 .
 178 See
 179 .Dv ZIP_SOURCE_SEEK
 180 for details.
 181 .Ss Dv ZIP_SOURCE_STAT
 182 Get meta information for the input data.
 183 .Ar data
 184 points to an allocated
 185 .Vt struct zip_stat ,
 186 which should be initialized using
 187 .Xr zip_stat_init 3
 188 and then filled in.
 189 Information only available after the source has been read (e.g. size)
 190 can be omitted in an earlier call.
 191 Return sizeof(struct zip_stat) on success.
 192 .Em NOTE :
 193 .Fn zip_source_function
 194 may be called with this argument even after being called with
 195 .Dv ZIP_SOURCE_CLOSE .
 196 .Ss Dv ZIP_SOURCE_SUPPORTS
 197 Return bitmap specifying which commands are supported.
 198 Use
 199 .Xr zip_source_make_command_bitmap 3 .
 200 If this command is not implemented, the source is assumed to be a
 201 read source without seek support.
 202 .Ss Dv ZIP_SOURCE_TELL
 203 Return the current read offset in the source, like
 204 .Xr ftell 3 .
 205 .Ss Dv ZIP_SOURCE_TELL_WRITE
 206 Return the current write offset in the source, like
 207 .Xr ftell 3 .
 208 .Ss Dv ZIP_SOURCE_WRITE
 209 Write data to the source.
 210 Return number of bytes written.
 211 .Ss Return Values
 212 Commands should return \-1 on error.
 213 .Dv ZIP_SOURCE_ERROR
 214 will be called to retrieve the error code.
 215 On success, commands return 0, unless specified otherwise in the
 216 description above.
 217 .Ss Calling Conventions
 218 The library will always issue
 219 .Dv ZIP_SOURCE_OPEN
 220 before issuing
 221 .Dv ZIP_SOURCE_READ ,
 222 .Dv ZIP_SOURCE_SEEK ,
 223 or
 224 .Dv ZIP_SOURCE_TELL .
 225 When it no longer wishes to read from this source, it will issue
 226 .Dv ZIP_SOURCE_CLOSE .
 227 If the library wishes to read the data again, it will issue
 228 .Dv ZIP_SOURCE_OPEN
 229 a second time.
 230 If the function is unable to provide the data again, it should
 231 return \-1.
 232 .Pp
 233 .Dv ZIP_SOURCE_BEGIN_WRITE
 234 will be called before
 235 .Dv ZIP_SOURCE_WRITE ,
 236 .Dv ZIP_SOURCE_SEEK_WRITE ,
 237 or
 238 .Dv ZIP_SOURCE_TELL_WRITE .
 239 When writing is complete, either
 240 .Dv ZIP_SOURCE_COMMIT_WRITE
 241 or
 242 .Dv ZIP_SOURCE_ROLLBACK_WRITE
 243 will be called.
 244 .Dv
 245 .Pp
 246 .Dv ZIP_SOURCE_STAT
 247 can be issued at any time.
 248 .Pp
 249 .Dv ZIP_SOURCE_ERROR
 250 will only be issued in response to the function
 251 returning \-1.
 252 .Pp
 253 .Dv ZIP_SOURCE_FREE
 254 will be the last command issued;
 255 if
 256 .Dv ZIP_SOURCE_OPEN
 257 was called and succeeded,
 258 .Dv ZIP_SOURCE_CLOSE
 259 will be called before
 260 .Dv ZIP_SOURCE_FREE ,
 261 and similarly for
 262 .Dv ZIP_SOURCE_BEGIN_WRITE
 263 and
 264 .Dv ZIP_SOURCE_COMMIT_WRITE
 265 or
 266 .Dv ZIP_SOURCE_ROLLBACK_WRITE .
 267 .Sh RETURN VALUES
 268 Upon successful completion, the created source is returned.
 269 Otherwise,
 270 .Dv NULL
 271 is returned and the error code in
 272 .Ar archive
 273 or
 274 .Ar error
 275 is set to indicate the error (unless
 276 it is
 277 .Dv NULL ) .
 278 .Sh ERRORS
 279 .Fn zip_source_function
 280 fails if:
 281 .Bl -tag -width Er
 282 .It Bq Er ZIP_ER_MEMORY
 283 Required memory could not be allocated.
 284 .El
 285 .Sh SEE ALSO
 286 .Xr libzip 3 ,
 287 .Xr zip_add 3 ,
 288 .Xr zip_replace 3 ,
 289 .Xr zip_source 3 ,
 290 .Xr zip_stat_init 3
 291 .Sh AUTHORS
 292 .An -nosplit
 293 .An Dieter Baron Aq Mt dillo@nih.at
 294 and
 295 .An Thomas Klausner Aq Mt tk@giga.or.at