trAvis - MANAGER

Edit File: zip_source_function.3

.\" zip_source_function.mdoc -- create data source from function .\" Copyright (C) 2004-2018 Dieter Baron and Thomas Klausner .\" .\" This file is part of libzip, a library to manipulate ZIP archives. .\" The authors can be contacted at <libzip@nih.at> .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in .\" the documentation and/or other materials provided with the .\" distribution. .\" 3. The names of the authors may not be used to endorse or promote .\" products derived from this software without specific prior .\" written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS ``AS IS'' AND ANY EXPRESS .\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE .\" GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER .\" IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR .\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN .\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .Dd December 18, 2017 .Dt ZIP_SOURCE_FUNCTION 3 .Os .Sh NAME .Nm zip_source_function , .Nm zip_source_function_create .Nd create data source from function .Sh LIBRARY libzip (-lzip) .Sh SYNOPSIS .In zip.h .Ft zip_source_t * .Fn zip_source_function "zip_t *archive" "zip_source_callback fn" "void *userdata" .Ft zip_source_t * .Fn zip_source_function_create "zip_source_callback fn" "void *userdata" "zip_error_t *error" .Sh DESCRIPTION The functions .Fn zip_source_function and .Fn zip_source_function_create creates a zip source from the user-provided function .Ar fn , which must be of the following type: .Pp .Ft typedef zip_int64_t .Fo \fR(*\fPzip_source_callback\fR)\fP .Fa "void *userdata" "void *data" "zip_uint64_t len" "zip_source_cmd_t cmd" .Fc .Pp .Ar archive or .Ar error are used for reporting errors and can be .Dv NULL . .Pp When called by the library, the first argument is the .Ar userdata argument supplied to the function. The next two arguments are a buffer .Ar data of size .Ar len when data is passed in or expected to be returned, or else .Dv NULL and 0. The last argument, .Ar cmd , specifies which action the function should perform. .Pp Depending on the uses, there are three useful sets of commands to be supported by a .Fn zip_source_callback : .Bl -tag -width seekable-read-sourceXX .It read source Providing streamed data (for file data added to archives). Must support .Dv ZIP_SOURCE_OPEN , .Dv ZIP_SOURCE_READ , .Dv ZIP_SOURCE_CLOSE , .Dv ZIP_SOURCE_STAT , and .Dv ZIP_SOURCE_ERROR . .It seekable read source Same as previous, but from a source allowing reading from arbitrary offsets (also for read-only zip archive). Must additionally support .Dv ZIP_SOURCE_SEEK , .Dv ZIP_SOURCE_TELL , and .Dv ZIP_SOURCE_SUPPORTS . .It read/write source Same as previous, but additionally allowing writing (also for writable zip archives). Must additionally support .Dv ZIP_SOURCE_BEGIN_WRITE , .Dv ZIP_SOURCE_COMMIT_WRITE , .Dv ZIP_SOURCE_ROLLBACK_WRITE , .Dv ZIP_SOURCE_SEEK_WRITE , .Dv ZIP_SOURCE_TELL_WRITE , and .Dv ZIP_SOURCE_REMOVE . .El .Ss Dv ZIP_SOURCE_BEGIN_WRITE Prepare the source for writing. Use this to create any temporary file(s). .Ss Dv ZIP_SOURCE_BEGIN_WRITE_CLONING Prepare the source for writing, keeping the first .Ar len bytes of the original file. Only implement this command if it is more efficient than copying the data, and if it does not destructively overwrite the original file (you still have to be able to execute .Dv ZIP_SOURCE_ROLLBACK_WRITE ) . .Pp The next write should happen at byte .Ar offset . .Ss Dv ZIP_SOURCE_CLOSE Reading is done. .Ss Dv ZIP_SOURCE_COMMIT_WRITE Finish writing to the source. Replace the original data with the newly written data. Clean up temporary files or internal buffers. Subsequently opening and reading from the source should return the newly written data. .Ss Dv ZIP_SOURCE_ERROR Get error information. .Ar data points to an array of two ints, which should be filled with the libzip error code and the corresponding system error code for the error that occurred. See .Xr zip_errors 3 for details on the error codes. If the source stores error information in a zip_error_t, use .Xr zip_error_to_data 3 and return its return value. Otherwise, return 2 * sizeof(int). .Ss Dv ZIP_SOURCE_FREE Clean up and free all resources, including .Ar userdata . The callback function will not be called again. .Ss Dv ZIP_SOURCE_OPEN Prepare for reading. .Ss Dv ZIP_SOURCE_READ Read data into the buffer .Ar data of size .Ar len . Return the number of bytes placed into .Ar data on success, and zero for end-of-file. .Ss Dv ZIP_SOURCE_REMOVE Remove the underlying file. This is called if a zip archive is empty when closed. .Ss Dv ZIP_SOURCE_ROLLBACK_WRITE Abort writing to the source. Discard written data. Clean up temporary files or internal buffers. Subsequently opening and reading from the source should return the original data. .Ss Dv ZIP_SOURCE_SEEK Specify position to read next byte from, like .Xr fseek 3 . Use .Xr ZIP_SOURCE_GET_ARGS 3 to decode the arguments into the following struct: .Bd -literal struct zip_source_args_seek { zip_int64_t offset; int whence; }; .Ed .Pp If the size of the source's data is known, use .Xr zip_source_seek_compute_offset 3 to validate the arguments and compute the new offset. .Ss Dv ZIP_SOURCE_SEEK_WRITE Specify position to write next byte to, like .Xr fseek 3 . See .Dv ZIP_SOURCE_SEEK for details. .Ss Dv ZIP_SOURCE_STAT Get meta information for the input data. .Ar data points to an allocated .Vt struct zip_stat , which should be initialized using .Xr zip_stat_init 3 and then filled in. .Pp For uncompressed, unencrypted data, all information is optional. However, fill in as much information as is readily available. .Pp If the data is compressed, .Dv ZIP_STAT_COMP_METHOD , .Dv ZIP_STAT_SIZE , and .Dv ZIP_STAT_CRC must be filled in. .Pp If the data is encrypted, .Dv ZIP_STAT_ENCRYPTION_METHOD , .Dv ZIP_STAT_COMP_METHOD , .Dv ZIP_STAT_SIZE , and .Dv ZIP_STAT_CRC must be filled in. .Pp Information only available after the source has been read (e.g., size) can be omitted in an earlier call. .Em NOTE : .Fn zip_source_function may be called with this argument even after being called with .Dv ZIP_SOURCE_CLOSE . .Pp Return sizeof(struct zip_stat) on success. .Ss Dv ZIP_SOURCE_SUPPORTS Return bitmap specifying which commands are supported. Use .Xr zip_source_make_command_bitmap 3 . If this command is not implemented, the source is assumed to be a read source without seek support. .Ss Dv ZIP_SOURCE_TELL Return the current read offset in the source, like .Xr ftell 3 . .Ss Dv ZIP_SOURCE_TELL_WRITE Return the current write offset in the source, like .Xr ftell 3 . .Ss Dv ZIP_SOURCE_WRITE Write data to the source. Return number of bytes written. .Ss Return Values Commands should return \-1 on error. .Dv ZIP_SOURCE_ERROR will be called to retrieve the error code. On success, commands return 0, unless specified otherwise in the description above. .Ss Calling Conventions The library will always issue .Dv ZIP_SOURCE_OPEN before issuing .Dv ZIP_SOURCE_READ , .Dv ZIP_SOURCE_SEEK , or .Dv ZIP_SOURCE_TELL . When it no longer wishes to read from this source, it will issue .Dv ZIP_SOURCE_CLOSE . If the library wishes to read the data again, it will issue .Dv ZIP_SOURCE_OPEN a second time. If the function is unable to provide the data again, it should return \-1. .Pp .Dv ZIP_SOURCE_BEGIN_WRITE or .Dv ZIP_SOURCE_BEGIN_WRITE_CLONING will be called before .Dv ZIP_SOURCE_WRITE , .Dv ZIP_SOURCE_SEEK_WRITE , or .Dv ZIP_SOURCE_TELL_WRITE . When writing is complete, either .Dv ZIP_SOURCE_COMMIT_WRITE or .Dv ZIP_SOURCE_ROLLBACK_WRITE will be called. .Pp .Dv ZIP_SOURCE_STAT can be issued at any time. .Pp .Dv ZIP_SOURCE_ERROR will only be issued in response to the function returning \-1. .Pp .Dv ZIP_SOURCE_FREE will be the last command issued; if .Dv ZIP_SOURCE_OPEN was called and succeeded, .Dv ZIP_SOURCE_CLOSE will be called before .Dv ZIP_SOURCE_FREE , and similarly for .Dv ZIP_SOURCE_BEGIN_WRITE or .Dv ZIP_SOURCE_BEGIN_WRITE_CLONING and .Dv ZIP_SOURCE_COMMIT_WRITE or .Dv ZIP_SOURCE_ROLLBACK_WRITE . .Sh RETURN VALUES Upon successful completion, the created source is returned. Otherwise, .Dv NULL is returned and the error code in .Ar archive or .Ar error is set to indicate the error (unless it is .Dv NULL ) . .Sh ERRORS .Fn zip_source_function fails if: .Bl -tag -width Er .It Bq Er ZIP_ER_MEMORY Required memory could not be allocated. .El .Sh SEE ALSO .Xr libzip 3 , .Xr zip_file_add 3 , .Xr zip_file_replace 3 , .Xr zip_source 3 , .Xr zip_stat_init 3 .Sh HISTORY .Fn zip_source_function and .Fn zip_source_function_create were added in libzip 1.0. .Sh AUTHORS .An -nosplit .An Dieter Baron Aq Mt dillo@nih.at and .An Thomas Klausner Aq Mt tk@giga.or.at