"Fossies" - the Fresh Open Source Software Archive

Member "libzip-1.5.2/man/zip_source_function.mdoc" (12 Mar 2019, 9512 Bytes) of package /linux/misc/libzip-1.5.2.tar.xz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "zip_source_function.mdoc": 1.5.1_vs_1.5.2.

    1 .\" zip_source_function.mdoc -- create data source from function
    2 .\" Copyright (C) 2004-2018 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 December 18, 2017
   33 .Dt ZIP_SOURCE_FUNCTION 3
   34 .Os
   35 .Sh NAME
   36 .Nm zip_source_function ,
   37 .Nm zip_source_function_create
   38 .Nd create data source from function
   39 .Sh LIBRARY
   40 libzip (-lzip)
   41 .Sh SYNOPSIS
   42 .In zip.h
   43 .Ft zip_source_t *
   44 .Fn zip_source_function "zip_t *archive" "zip_source_callback fn" "void *userdata"
   45 .Ft zip_source_t *
   46 .Fn zip_source_function_create "zip_source_callback fn" "void *userdata" "zip_error_t *error"
   47 .Sh DESCRIPTION
   48 The functions
   49 .Fn zip_source_function
   50 and
   51 .Fn zip_source_function_create
   52 creates a zip source from the user-provided function
   53 .Ar fn ,
   54 which must be of the following type:
   55 .Pp
   56 .Ft typedef zip_int64_t
   57 .Fo \fR(*\fPzip_source_callback\fR)\fP
   58 .Fa "void *userdata" "void *data" "zip_uint64_t len" "zip_source_cmd_t cmd"
   59 .Fc
   60 .Pp
   61 .Ar archive
   62 or
   63 .Ar error
   64 are used for reporting errors and can be
   65 .Dv NULL .
   66 .Pp
   67 When called by the library, the first argument is the
   68 .Ar userdata
   69 argument supplied to the function.
   70 The next two arguments are a buffer
   71 .Ar data
   72 of size
   73 .Ar len
   74 when data is passed in or expected to be returned, or else
   75 .Dv NULL
   76 and 0.
   77 The last argument,
   78 .Ar cmd ,
   79 specifies which action the function should perform.
   80 .Pp
   81 Depending on the uses, there are three useful sets of commands to be supported by a
   82 .Fn zip_source_callback :
   83 .Bl -tag -width seekable-read-sourceXX
   84 .It read source
   85 Providing streamed data (for file data added to archives).
   86 Must support
   87 .Dv ZIP_SOURCE_OPEN ,
   88 .Dv ZIP_SOURCE_READ ,
   89 .Dv ZIP_SOURCE_CLOSE ,
   90 .Dv ZIP_SOURCE_STAT ,
   91 and
   92 .Dv ZIP_SOURCE_ERROR .
   93 .It seekable read source
   94 Same as previous, but from a source allowing reading from arbitrary
   95 offsets (also for read-only zip archive).
   96 Must additionally support
   97 .Dv ZIP_SOURCE_SEEK ,
   98 .Dv ZIP_SOURCE_TELL ,
   99 and
  100 .Dv ZIP_SOURCE_SUPPORTS .
  101 .It read/write source
  102 Same as previous, but additionally allowing writing (also for writable
  103 zip archives).
  104 Must additionally support
  105 .Dv ZIP_SOURCE_BEGIN_WRITE ,
  106 .Dv ZIP_SOURCE_COMMIT_WRITE ,
  107 .Dv ZIP_SOURCE_ROLLBACK_WRITE ,
  108 .Dv ZIP_SOURCE_SEEK_WRITE ,
  109 .Dv ZIP_SOURCE_TELL_WRITE ,
  110 and
  111 .Dv ZIP_SOURCE_REMOVE .
  112 .El
  113 .Ss Dv ZIP_SOURCE_BEGIN_WRITE
  114 Prepare the source for writing.
  115 Use this to create any temporary file(s).
  116 .Ss Dv ZIP_SOURCE_BEGIN_WRITE_CLONING
  117 Prepare the source for writing, keeping the first
  118 .Ar len
  119 bytes of the original file.
  120 Only implement this command if it is more efficient than copying the
  121 data, and if it does not destructively overwrite the original file
  122 (you still have to be able to execute
  123 .Dv ZIP_SOURCE_ROLLBACK_WRITE ) .
  124 .Pp
  125 The next write should happen at byte
  126 .Ar offset .
  127 .Ss Dv ZIP_SOURCE_CLOSE
  128 Reading is done.
  129 .Ss Dv ZIP_SOURCE_COMMIT_WRITE
  130 Finish writing to the source.
  131 Replace the original data with the newly written data.
  132 Clean up temporary files or internal buffers.
  133 Subsequently opening and reading from the source should return the
  134 newly written data.
  135 .Ss Dv ZIP_SOURCE_ERROR
  136 Get error information.
  137 .Ar data
  138 points to an array of two ints, which should be filled with the libzip
  139 error code and the corresponding system error code for the error that
  140 occurred.
  141 See
  142 .Xr zip_errors 3
  143 for details on the error codes.
  144 If the source stores error information in a zip_error_t, use
  145 .Xr zip_error_to_data 3
  146 and return its return value.
  147 Otherwise, return 2 * sizeof(int).
  148 .Ss Dv ZIP_SOURCE_FREE
  149 Clean up and free all resources, including
  150 .Ar userdata .
  151 The callback function will not be called again.
  152 .Ss Dv ZIP_SOURCE_OPEN
  153 Prepare for reading.
  154 .Ss Dv ZIP_SOURCE_READ
  155 Read data into the buffer
  156 .Ar data
  157 of size
  158 .Ar len .
  159 Return the number of bytes placed into
  160 .Ar data
  161 on success, and zero for end-of-file.
  162 .Ss Dv ZIP_SOURCE_REMOVE
  163 Remove the underlying file.
  164 This is called if a zip archive is empty when closed.
  165 .Ss Dv ZIP_SOURCE_ROLLBACK_WRITE
  166 Abort writing to the source.
  167 Discard written data.
  168 Clean up temporary files or internal buffers.
  169 Subsequently opening and reading from the source should return the
  170 original data.
  171 .Ss Dv ZIP_SOURCE_SEEK
  172 Specify position to read next byte from, like
  173 .Xr fseek 3 .
  174 Use
  175 .Xr ZIP_SOURCE_GET_ARGS 3
  176 to decode the arguments into the following struct:
  177 .Bd -literal
  178 struct zip_source_args_seek {
  179     zip_int64_t offset;
  180     int whence;
  181 };
  182 .Ed
  183 .Pp
  184 If the size of the source's data is known, use
  185 .Xr zip_source_seek_compute_offset 3
  186 to validate the arguments and compute the new offset.
  187 .Ss Dv ZIP_SOURCE_SEEK_WRITE
  188 Specify position to write next byte to, like
  189 .Xr fseek 3 .
  190 See
  191 .Dv ZIP_SOURCE_SEEK
  192 for details.
  193 .Ss Dv ZIP_SOURCE_STAT
  194 Get meta information for the input data.
  195 .Ar data
  196 points to an allocated
  197 .Vt struct zip_stat ,
  198 which should be initialized using
  199 .Xr zip_stat_init 3
  200 and then filled in.
  201 .Pp
  202 For uncompressed, unencrypted data, all information is optional.
  203 However, fill in as much information as is readily available.
  204 .Pp
  205 If the data is compressed,
  206 .Dv ZIP_STAT_COMP_METHOD ,
  207 .Dv ZIP_STAT_SIZE ,
  208 and
  209 .Dv ZIP_STAT_CRC
  210 must be filled in.
  211 .Pp
  212 If the data is encrypted,
  213 .Dv ZIP_STAT_ENCRYPTION_METHOD ,
  214 .Dv ZIP_STAT_COMP_METHOD ,
  215 .Dv ZIP_STAT_SIZE ,
  216 and
  217 .Dv ZIP_STAT_CRC
  218 must be filled in.
  219 .Pp
  220 Information only available after the source has been read (e.g., size)
  221 can be omitted in an earlier call.
  222 .Em NOTE :
  223 .Fn zip_source_function
  224 may be called with this argument even after being called with
  225 .Dv ZIP_SOURCE_CLOSE .
  226 .Pp
  227 Return sizeof(struct zip_stat) on success.
  228 .Ss Dv ZIP_SOURCE_SUPPORTS
  229 Return bitmap specifying which commands are supported.
  230 Use
  231 .Xr zip_source_make_command_bitmap 3 .
  232 If this command is not implemented, the source is assumed to be a
  233 read source without seek support.
  234 .Ss Dv ZIP_SOURCE_TELL
  235 Return the current read offset in the source, like
  236 .Xr ftell 3 .
  237 .Ss Dv ZIP_SOURCE_TELL_WRITE
  238 Return the current write offset in the source, like
  239 .Xr ftell 3 .
  240 .Ss Dv ZIP_SOURCE_WRITE
  241 Write data to the source.
  242 Return number of bytes written.
  243 .Ss Return Values
  244 Commands should return \-1 on error.
  245 .Dv ZIP_SOURCE_ERROR
  246 will be called to retrieve the error code.
  247 On success, commands return 0, unless specified otherwise in the
  248 description above.
  249 .Ss Calling Conventions
  250 The library will always issue
  251 .Dv ZIP_SOURCE_OPEN
  252 before issuing
  253 .Dv ZIP_SOURCE_READ ,
  254 .Dv ZIP_SOURCE_SEEK ,
  255 or
  256 .Dv ZIP_SOURCE_TELL .
  257 When it no longer wishes to read from this source, it will issue
  258 .Dv ZIP_SOURCE_CLOSE .
  259 If the library wishes to read the data again, it will issue
  260 .Dv ZIP_SOURCE_OPEN
  261 a second time.
  262 If the function is unable to provide the data again, it should
  263 return \-1.
  264 .Pp
  265 .Dv ZIP_SOURCE_BEGIN_WRITE
  266 or
  267 .Dv ZIP_SOURCE_BEGIN_WRITE_CLONING
  268 will be called before
  269 .Dv ZIP_SOURCE_WRITE ,
  270 .Dv ZIP_SOURCE_SEEK_WRITE ,
  271 or
  272 .Dv ZIP_SOURCE_TELL_WRITE .
  273 When writing is complete, either
  274 .Dv ZIP_SOURCE_COMMIT_WRITE
  275 or
  276 .Dv ZIP_SOURCE_ROLLBACK_WRITE
  277 will be called.
  278 .Pp
  279 .Dv ZIP_SOURCE_STAT
  280 can be issued at any time.
  281 .Pp
  282 .Dv ZIP_SOURCE_ERROR
  283 will only be issued in response to the function
  284 returning \-1.
  285 .Pp
  286 .Dv ZIP_SOURCE_FREE
  287 will be the last command issued;
  288 if
  289 .Dv ZIP_SOURCE_OPEN
  290 was called and succeeded,
  291 .Dv ZIP_SOURCE_CLOSE
  292 will be called before
  293 .Dv ZIP_SOURCE_FREE ,
  294 and similarly for
  295 .Dv ZIP_SOURCE_BEGIN_WRITE
  296 or
  297 .Dv ZIP_SOURCE_BEGIN_WRITE_CLONING
  298 and
  299 .Dv ZIP_SOURCE_COMMIT_WRITE
  300 or
  301 .Dv ZIP_SOURCE_ROLLBACK_WRITE .
  302 .Sh RETURN VALUES
  303 Upon successful completion, the created source is returned.
  304 Otherwise,
  305 .Dv NULL
  306 is returned and the error code in
  307 .Ar archive
  308 or
  309 .Ar error
  310 is set to indicate the error (unless
  311 it is
  312 .Dv NULL ) .
  313 .Sh ERRORS
  314 .Fn zip_source_function
  315 fails if:
  316 .Bl -tag -width Er
  317 .It Bq Er ZIP_ER_MEMORY
  318 Required memory could not be allocated.
  319 .El
  320 .Sh SEE ALSO
  321 .Xr libzip 3 ,
  322 .Xr zip_file_add 3 ,
  323 .Xr zip_file_replace 3 ,
  324 .Xr zip_source 3 ,
  325 .Xr zip_stat_init 3
  326 .Sh HISTORY
  327 .Fn zip_source_function
  328 and
  329 .Fn zip_source_function_create
  330 were added in libzip 1.0.
  331 .Sh AUTHORS
  332 .An -nosplit
  333 .An Dieter Baron Aq Mt dillo@nih.at
  334 and
  335 .An Thomas Klausner Aq Mt tk@giga.or.at