man/zip_source_function.man

   1 .\" Automatically generated from an mdoc input file.  Do not edit.
   2 .\" zip_source_function.mdoc -- create data source from function
   3 .\" Copyright (C) 2004-2022 Dieter Baron and Thomas Klausner
   4 .\"
   5 .\" This file is part of libzip, a library to manipulate ZIP archives.
   6 .\" The authors can be contacted at <libzip@nih.at>
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in
  15 .\"    the documentation and/or other materials provided with the
  16 .\"    distribution.
  17 .\" 3. The names of the authors may not be used to endorse or promote
  18 .\"    products derived from this software without specific prior
  19 .\"    written permission.
  20 .\"
  21 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS ``AS IS'' AND ANY EXPRESS
  22 .\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  23 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  24 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY
  25 .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  26 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
  27 .\" GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  28 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
  29 .\" IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  30 .\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
  31 .\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  32 .\"
  33 .TH "ZIP_SOURCE_FUNCTION" "3" "April 17, 2020" "NiH" "Library Functions Manual"
  34 .nh
  35 .if n .ad l
  36 .SH "NAME"
  37 \fBzip_source_function\fR,
  38 \fBzip_source_function_create\fR
  39 \- create data source from function
  40 .SH "LIBRARY"
  41 libzip (-lzip)
  42 .SH "SYNOPSIS"
  43 \fB#include <zip.h>\fR
  44 .sp
  45 \fIzip_source_t *\fR
  46 .br
  47 .PD 0
  48 .HP 4n
  49 \fBzip_source_function\fR(\fIzip_t\ *archive\fR, \fIzip_source_callback\ fn\fR, \fIvoid\ *userdata\fR);
  50 .PD
  51 .PP
  52 \fIzip_source_t *\fR
  53 .br
  54 .PD 0
  55 .HP 4n
  56 \fBzip_source_function_create\fR(\fIzip_source_callback\ fn\fR, \fIvoid\ *userdata\fR, \fIzip_error_t\ *error\fR);
  57 .PD
  58 .SH "DESCRIPTION"
  59 The functions
  60 \fBzip_source_function\fR()
  61 and
  62 \fBzip_source_function_create\fR()
  63 creates a zip source from the user-provided function
  64 \fIfn\fR,
  65 which must be of the following type:
  66 .PP
  67 \fItypedef zip_int64_t\fR
  68 \fB\fR(*\fPzip_source_callback\fR)\fP\fR(\fIvoid\ *userdata\fR, \fIvoid\ *data\fR, \fIzip_uint64_t\ len\fR, \fIzip_source_cmd_t\ cmd\fR)
  69 .PP
  70 \fIarchive\fR
  71 or
  72 \fIerror\fR
  73 are used for reporting errors and can be
  74 \fRNULL\fR.
  75 .PP
  76 When called by the library, the first argument is the
  77 \fIuserdata\fR
  78 argument supplied to the function.
  79 The next two arguments are a buffer
  80 \fIdata\fR
  81 of size
  82 \fIlen\fR
  83 when data is passed in or expected to be returned, or else
  84 \fRNULL\fR
  85 and 0.
  86 The last argument,
  87 \fIcmd\fR,
  88 specifies which action the function should perform.
  89 .PP
  90 Depending on the uses, there are three useful sets of commands to be supported by a
  91 \fBzip_source_callback\fR():
  92 .TP 24n
  93 read source
  94 Providing streamed data (for file data added to archives).
  95 Must support
  96 \fRZIP_SOURCE_OPEN\fR,
  97 \fRZIP_SOURCE_READ\fR,
  98 \fRZIP_SOURCE_CLOSE\fR,
  99 \fRZIP_SOURCE_STAT\fR,
 100 and
 101 \fRZIP_SOURCE_ERROR\fR.
 102 .TP 24n
 103 seekable read source
 104 Same as previous, but from a source allowing reading from arbitrary
 105 offsets (also for read-only zip archive).
 106 Must additionally support
 107 \fRZIP_SOURCE_SEEK\fR,
 108 \fRZIP_SOURCE_TELL\fR,
 109 and
 110 \fRZIP_SOURCE_SUPPORTS\fR.
 111 .TP 24n
 112 read/write source
 113 Same as previous, but additionally allowing writing (also for writable
 114 zip archives).
 115 Must additionally support
 116 \fRZIP_SOURCE_BEGIN_WRITE\fR,
 117 \fRZIP_SOURCE_COMMIT_WRITE\fR,
 118 \fRZIP_SOURCE_ROLLBACK_WRITE\fR,
 119 \fRZIP_SOURCE_SEEK_WRITE\fR,
 120 \fRZIP_SOURCE_TELL_WRITE\fR,
 121 and
 122 \fRZIP_SOURCE_REMOVE\fR.
 123 .SS "\fRZIP_SOURCE_ACCEPT_EMPTY\fR"
 124 Return 1 if an empty source should be accepted as a valid zip archive.
 125 This is the default if this command is not supported by a source.
 126 File system backed sources should return 0.
 127 .SS "\fRZIP_SOURCE_BEGIN_WRITE\fR"
 128 Prepare the source for writing.
 129 Use this to create any temporary file(s).
 130 .SS "\fRZIP_SOURCE_BEGIN_WRITE_CLONING\fR"
 131 Prepare the source for writing, keeping the first
 132 \fIlen\fR
 133 bytes of the original file.
 134 Only implement this command if it is more efficient than copying the
 135 data, and if it does not destructively overwrite the original file
 136 (you still have to be able to execute
 137 \fRZIP_SOURCE_ROLLBACK_WRITE\fR).
 138 .PP
 139 The next write should happen at byte
 140 \fIoffset\fR.
 141 .SS "\fRZIP_SOURCE_CLOSE\fR"
 142 Reading is done.
 143 .SS "\fRZIP_SOURCE_COMMIT_WRITE\fR"
 144 Finish writing to the source.
 145 Replace the original data with the newly written data.
 146 Clean up temporary files or internal buffers.
 147 Subsequently opening and reading from the source should return the
 148 newly written data.
 149 .SS "\fRZIP_SOURCE_ERROR\fR"
 150 Get error information.
 151 \fIdata\fR
 152 points to an array of two ints, which should be filled with the libzip
 153 error code and the corresponding system error code for the error that
 154 occurred.
 155 See
 156 zip_errors(3)
 157 for details on the error codes.
 158 If the source stores error information in a zip_error_t, use
 159 zip_error_to_data(3)
 160 and return its return value.
 161 Otherwise, return 2 * sizeof(int).
 162 .SS "\fRZIP_SOURCE_FREE\fR"
 163 Clean up and free all resources, including
 164 \fIuserdata\fR.
 165 The callback function will not be called again.
 166 .SS "\fRZIP_SOURCE_GET_FILE_ATTRIBUTES\fR"
 167 Provide information about various data.
 168 Then the data should be put in the appropriate entry in the passed
 169 \fIzip_file_attributes_t\fR
 170 argument, and the appropriate
 171 \fRZIP_FILE_ATTRIBUTES_*\fR
 172 value must be or'ed into the
 173 \fIvalid\fR
 174 member to denote that the corresponding data has been provided.
 175 A
 176 \fIzip_file_attributes_t\fR
 177 structure can be initialized using
 178 zip_file_attributes_init(3).
 179 .TP 12n
 180 ASCII mode
 181 If a file is a plaintext file in ASCII.
 182 Can be used by extraction tools to automatically convert line endings
 183 (part of the internal file attributes).
 184 Member
 185 \fIascii\fR,
 186 flag
 187 \fRZIP_FILE_ATTRIBUTES_ASCII\fR.
 188 .TP 12n
 189 General Purpose Bit Flags (limited to Compression Flags)
 190 The general purpose bit flag in the zip in the local and central
 191 directory headers contain information about the compression method.
 192 Member
 193 \fIgeneral_purpose_bit_flags\fR
 194 and
 195 \fIgeneral_purpose_bit_mask\fR
 196 to denote which members have been set;
 197 flag
 198 \fRZIP_FILE_ATTRIBUTES_GENERAL_PURPOSE_BIT_FLAGS\fR.
 199 .TP 12n
 200 External File Attributes
 201 The external file attributes (usually operating system-specific).
 202 Member
 203 \fIexternal_file_attributes\fR,
 204 flag
 205 \fRZIP_FILE_ATTRIBUTES_EXTERNAL_FILE_ATTRIBUTES\fR.
 206 .TP 12n
 207 Version Needed
 208 A minimum version needed required to unpack this entry (in the usual
 209 "major * 10 + minor" format).
 210 Member
 211 \fIversion_needed\fR,
 212 flag
 213 \fRZIP_FILE_ATTRIBUTES_VERSION_NEEDED\fR.
 214 .TP 12n
 215 Operating System
 216 One of the operating systems as defined by the
 217 \fRZIP_OPSYS_*\fR
 218 variables (see
 219 \fIzip.h\fR).
 220 This value affects the interpretation of the external file attributes.
 221 Member
 222 \fIhost_system\fR,
 223 flag
 224 \fRZIP_FILE_ATTRIBUTES_HOST_SYSTEM\fR.
 225 .SS "\fRZIP_SOURCE_OPEN\fR"
 226 Prepare for reading.
 227 .SS "\fRZIP_SOURCE_READ\fR"
 228 Read data into the buffer
 229 \fIdata\fR
 230 of size
 231 \fIlen\fR.
 232 Return the number of bytes placed into
 233 \fIdata\fR
 234 on success, and zero for end-of-file.
 235 .SS "\fRZIP_SOURCE_REMOVE\fR"
 236 Remove the underlying file.
 237 This is called if a zip archive is empty when closed.
 238 .SS "\fRZIP_SOURCE_ROLLBACK_WRITE\fR"
 239 Abort writing to the source.
 240 Discard written data.
 241 Clean up temporary files or internal buffers.
 242 Subsequently opening and reading from the source should return the
 243 original data.
 244 .SS "\fRZIP_SOURCE_SEEK\fR"
 245 Specify position to read next byte from, like
 246 fseek(3).
 247 Use
 248 ZIP_SOURCE_GET_ARGS(3)
 249 to decode the arguments into the following struct:
 250 .nf
 251 .sp
 252 .RS 0n
 253 struct zip_source_args_seek {
 254     zip_int64_t offset;
 255     int whence;
 256 };
 257 .RE
 258 .fi
 259 .PP
 260 If the size of the source's data is known, use
 261 zip_source_seek_compute_offset(3)
 262 to validate the arguments and compute the new offset.
 263 .SS "\fRZIP_SOURCE_SEEK_WRITE\fR"
 264 Specify position to write next byte to, like
 265 fseek(3).
 266 See
 267 \fRZIP_SOURCE_SEEK\fR
 268 for details.
 269 .SS "\fRZIP_SOURCE_STAT\fR"
 270 Get meta information for the input data.
 271 \fIdata\fR
 272 points to an allocated
 273 \fIstruct zip_stat\fR,
 274 which should be initialized using
 275 zip_stat_init(3)
 276 and then filled in.
 277 .PP
 278 For uncompressed, unencrypted data, all information is optional.
 279 However, fill in as much information as is readily available.
 280 .PP
 281 If the data is compressed,
 282 \fRZIP_STAT_COMP_METHOD\fR,
 283 \fRZIP_STAT_SIZE\fR,
 284 and
 285 \fRZIP_STAT_CRC\fR
 286 must be filled in.
 287 .PP
 288 If the data is encrypted,
 289 \fRZIP_STAT_ENCRYPTION_METHOD\fR,
 290 \fRZIP_STAT_COMP_METHOD\fR,
 291 \fRZIP_STAT_SIZE\fR,
 292 and
 293 \fRZIP_STAT_CRC\fR
 294 must be filled in.
 295 .PP
 296 Information only available after the source has been read (e.g., size)
 297 can be omitted in an earlier call.
 298 \fINOTE\fR:
 299 \fBzip_source_function\fR()
 300 may be called with this argument even after being called with
 301 \fRZIP_SOURCE_CLOSE\fR.
 302 .PP
 303 Return sizeof(struct zip_stat) on success.
 304 .SS "\fRZIP_SOURCE_SUPPORTS\fR"
 305 Return bitmap specifying which commands are supported.
 306 Use
 307 zip_source_make_command_bitmap(3).
 308 If this command is not implemented, the source is assumed to be a
 309 read source without seek support.
 310 .SS "\fRZIP_SOURCE_TELL\fR"
 311 Return the current read offset in the source, like
 312 ftell(3).
 313 .SS "\fRZIP_SOURCE_TELL_WRITE\fR"
 314 Return the current write offset in the source, like
 315 ftell(3).
 316 .SS "\fRZIP_SOURCE_WRITE\fR"
 317 Write data to the source.
 318 Return number of bytes written.
 319 .SS "Return Values"
 320 Commands should return \-1 on error.
 321 \fRZIP_SOURCE_ERROR\fR
 322 will be called to retrieve the error code.
 323 On success, commands return 0, unless specified otherwise in the
 324 description above.
 325 .SS "Calling Conventions"
 326 The library will always issue
 327 \fRZIP_SOURCE_OPEN\fR
 328 before issuing
 329 \fRZIP_SOURCE_READ\fR,
 330 \fRZIP_SOURCE_SEEK\fR,
 331 or
 332 \fRZIP_SOURCE_TELL\fR.
 333 When it no longer wishes to read from this source, it will issue
 334 \fRZIP_SOURCE_CLOSE\fR.
 335 If the library wishes to read the data again, it will issue
 336 \fRZIP_SOURCE_OPEN\fR
 337 a second time.
 338 If the function is unable to provide the data again, it should
 339 return \-1.
 340 .PP
 341 \fRZIP_SOURCE_BEGIN_WRITE\fR
 342 or
 343 \fRZIP_SOURCE_BEGIN_WRITE_CLONING\fR
 344 will be called before
 345 \fRZIP_SOURCE_WRITE\fR,
 346 \fRZIP_SOURCE_SEEK_WRITE\fR,
 347 or
 348 \fRZIP_SOURCE_TELL_WRITE\fR.
 349 When writing is complete, either
 350 \fRZIP_SOURCE_COMMIT_WRITE\fR
 351 or
 352 \fRZIP_SOURCE_ROLLBACK_WRITE\fR
 353 will be called.
 354 .PP
 355 \fRZIP_SOURCE_ACCEPT_EMPTY\fR,
 356 \fRZIP_SOURCE_GET_FILE_ATTRIBUTES\fR,
 357 and
 358 \fRZIP_SOURCE_STAT\fR
 359 can be issued at any time.
 360 .PP
 361 \fRZIP_SOURCE_ERROR\fR
 362 will only be issued in response to the function
 363 returning \-1.
 364 .PP
 365 \fRZIP_SOURCE_FREE\fR
 366 will be the last command issued;
 367 if
 368 \fRZIP_SOURCE_OPEN\fR
 369 was called and succeeded,
 370 \fRZIP_SOURCE_CLOSE\fR
 371 will be called before
 372 \fRZIP_SOURCE_FREE\fR,
 373 and similarly for
 374 \fRZIP_SOURCE_BEGIN_WRITE\fR
 375 or
 376 \fRZIP_SOURCE_BEGIN_WRITE_CLONING\fR
 377 and
 378 \fRZIP_SOURCE_COMMIT_WRITE\fR
 379 or
 380 \fRZIP_SOURCE_ROLLBACK_WRITE\fR.
 381 .SH "RETURN VALUES"
 382 Upon successful completion, the created source is returned.
 383 Otherwise,
 384 \fRNULL\fR
 385 is returned and the error code in
 386 \fIarchive\fR
 387 or
 388 \fIerror\fR
 389 is set to indicate the error (unless
 390 it is
 391 \fRNULL\fR).
 392 .SH "ERRORS"
 393 \fBzip_source_function\fR()
 394 fails if:
 395 .TP 19n
 396 [\fRZIP_ER_MEMORY\fR]
 397 Required memory could not be allocated.
 398 .SH "SEE ALSO"
 399 libzip(3),
 400 zip_file_add(3),
 401 zip_file_attributes_init(3),
 402 zip_file_replace(3),
 403 zip_source(3),
 404 zip_stat_init(3)
 405 .SH "HISTORY"
 406 \fBzip_source_function\fR()
 407 and
 408 \fBzip_source_function_create\fR()
 409 were added in libzip 1.0.
 410 .SH "AUTHORS"
 411 Dieter Baron <\fIdillo@nih.at\fR>
 412 and
 413 Thomas Klausner <\fItk@giga.or.at\fR>