| <!DOCTYPE html> |
| <html> |
| <head> |
| <meta charset="utf-8"/> |
| <style> |
| table.head, table.foot { width: 100%; } |
| td.head-rtitle, td.foot-os { text-align: right; } |
| td.head-vol { text-align: center; } |
| div.Pp { margin: 1ex 0ex; } |
| </style> |
| <link rel="stylesheet" href="../nih-man.css" type="text/css" media="all"/> |
| <title>ZIP_SOURCE_FUNCTION(3)</title> |
| </head> |
| <body> |
| <table class="head"> |
| <tr> |
| <td class="head-ltitle">ZIP_SOURCE_FUNCTION(3)</td> |
| <td class="head-vol">Library Functions Manual</td> |
| <td class="head-rtitle">ZIP_SOURCE_FUNCTION(3)</td> |
| </tr> |
| </table> |
| <div class="manual-text"> |
| <h1 class="Sh" id="NAME">NAME</h1> |
| <b class="Nm">zip_source_function</b>, |
| <b class="Nm">zip_source_function_create</b> — <span class="Nd">create |
| data source from function</span> |
| <h1 class="Sh" id="LIBRARY">LIBRARY</h1> |
| libzip (-lzip) |
| <h1 class="Sh" id="SYNOPSIS">SYNOPSIS</h1> |
| <b class="In">#include <<a class="In">zip.h</a>></b> |
| <div class="Pp"></div> |
| <var class="Ft">zip_source_t *</var> |
| <br/> |
| <b class="Fn">zip_source_function</b>(<var class="Fa" style="white-space: nowrap;">zip_t |
| *archive</var>, |
| <var class="Fa" style="white-space: nowrap;">zip_source_callback fn</var>, |
| <var class="Fa" style="white-space: nowrap;">void *userdata</var>); |
| <div class="Pp"></div> |
| <var class="Ft">zip_source_t *</var> |
| <br/> |
| <b class="Fn">zip_source_function_create</b>(<var class="Fa" style="white-space: nowrap;">zip_source_callback |
| fn</var>, <var class="Fa" style="white-space: nowrap;">void *userdata</var>, |
| <var class="Fa" style="white-space: nowrap;">zip_error_t *error</var>); |
| <h1 class="Sh" id="DESCRIPTION">DESCRIPTION</h1> |
| The functions <b class="Fn">zip_source_function</b>() and |
| <b class="Fn">zip_source_function_create</b>() creates a zip source from the |
| user-provided function <var class="Ar">fn</var>, which must be of the |
| following type: |
| <div class="Pp"></div> |
| <var class="Ft">typedef zip_int64_t</var> |
| <b class="Fn">(*zip_source_callback)</b>(<var class="Fa">void *userdata</var>, |
| <var class="Fa">void *data</var>, <var class="Fa">zip_uint64_t len</var>, |
| <var class="Fa">zip_source_cmd_t cmd</var>); |
| <div class="Pp"></div> |
| <var class="Ar">archive</var> or <var class="Ar">error</var> are used for |
| reporting errors and can be <code class="Dv">NULL</code>. |
| <div class="Pp"></div> |
| When called by the library, the first argument is the |
| <var class="Ar">userdata</var> argument supplied to the function. The next two |
| arguments are a buffer <var class="Ar">data</var> of size |
| <var class="Ar">len</var> when data is passed in or expected to be returned, |
| or else <code class="Dv">NULL</code> and 0. The last argument, |
| <var class="Ar">cmd</var>, specifies which action the function should perform. |
| <div class="Pp"></div> |
| Depending on the uses, there are three useful sets of commands to be supported |
| by a <b class="Fn">zip_source_callback</b>(): |
| <dl class="Bl-tag" style="margin-left: 22.00ex;"> |
| <dt class="It-tag" style="margin-left: -22.00ex;"> </dt> |
| <dd class="It-tag"> </dd> |
| <dt class="It-tag" style="margin-left: -22.00ex;">read source</dt> |
| <dd class="It-tag">Providing streamed data (for file data added to archives). |
| Must support <code class="Dv">ZIP_SOURCE_OPEN</code>, |
| <code class="Dv">ZIP_SOURCE_READ</code>, |
| <code class="Dv">ZIP_SOURCE_CLOSE</code>, |
| <code class="Dv">ZIP_SOURCE_STAT</code>, and |
| <code class="Dv">ZIP_SOURCE_ERROR</code>.</dd> |
| <dt class="It-tag" style="margin-left: -22.00ex;"> </dt> |
| <dd class="It-tag"> </dd> |
| <dt class="It-tag" style="margin-left: -22.00ex;">seekable read source</dt> |
| <dd class="It-tag">Same as previous, but from a source allowing reading from |
| arbitrary offsets (also for read-only zip archive). Must additionally |
| support <code class="Dv">ZIP_SOURCE_SEEK</code>, |
| <code class="Dv">ZIP_SOURCE_TELL</code>, and |
| <code class="Dv">ZIP_SOURCE_SUPPORTS</code>.</dd> |
| <dt class="It-tag" style="margin-left: -22.00ex;"> </dt> |
| <dd class="It-tag"> </dd> |
| <dt class="It-tag" style="margin-left: -22.00ex;">read/write source</dt> |
| <dd class="It-tag">Same as previous, but additionally allowing writing (also |
| for writable zip archives). Must additionally support |
| <code class="Dv">ZIP_SOURCE_BEGIN_WRITE</code>, |
| <code class="Dv">ZIP_SOURCE_COMMIT_WRITE</code>, |
| <code class="Dv">ZIP_SOURCE_ROLLBACK_WRITE</code>, |
| <code class="Dv">ZIP_SOURCE_SEEK_WRITE</code>, |
| <code class="Dv">ZIP_SOURCE_TELL_WRITE</code>, and |
| <code class="Dv">ZIP_SOURCE_REMOVE</code>.</dd> |
| </dl> |
| <h2 class="Ss"><code class="Dv">ZIP_SOURCE_BEGIN_WRITE</code></h2> |
| Prepare the source for writing. Use this to create any temporary file(s). |
| <h2 class="Ss"><code class="Dv">ZIP_SOURCE_BEGIN_WRITE_CLONING</code></h2> |
| Prepare the source for writing, keeping the first <var class="Ar">len</var> |
| 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 |
| <code class="Dv">ZIP_SOURCE_ROLLBACK_WRITE</code>). |
| <div class="Pp"></div> |
| The next write should happen at byte <var class="Ar">offset</var>. |
| <h2 class="Ss"><code class="Dv">ZIP_SOURCE_CLOSE</code></h2> |
| Reading is done. |
| <h2 class="Ss"><code class="Dv">ZIP_SOURCE_COMMIT_WRITE</code></h2> |
| 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. |
| <h2 class="Ss"><code class="Dv">ZIP_SOURCE_ERROR</code></h2> |
| Get error information. <var class="Ar">data</var> 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 |
| <a class="Xr" href="zip_errors.html">zip_errors(3)</a> for details on the |
| error codes. If the source stores error information in a zip_error_t, use |
| <a class="Xr" href="zip_error_to_data.html">zip_error_to_data(3)</a> and |
| return its return value. Otherwise, return 2 * sizeof(int). |
| <h2 class="Ss"><code class="Dv">ZIP_SOURCE_FREE</code></h2> |
| Clean up and free all resources, including <var class="Ar">userdata</var>. The |
| callback function will not be called again. |
| <h2 class="Ss"><code class="Dv">ZIP_SOURCE_OPEN</code></h2> |
| Prepare for reading. |
| <h2 class="Ss"><code class="Dv">ZIP_SOURCE_READ</code></h2> |
| Read data into the buffer <var class="Ar">data</var> of size |
| <var class="Ar">len</var>. Return the number of bytes placed into |
| <var class="Ar">data</var> on success, and zero for end-of-file. |
| <h2 class="Ss"><code class="Dv">ZIP_SOURCE_REMOVE</code></h2> |
| Remove the underlying file. This is called if a zip archive is empty when |
| closed. |
| <h2 class="Ss"><code class="Dv">ZIP_SOURCE_ROLLBACK_WRITE</code></h2> |
| 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. |
| <h2 class="Ss"><code class="Dv">ZIP_SOURCE_SEEK</code></h2> |
| Specify position to read next byte from, like |
| <a class="Xr" href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/fseek.html">fseek(3)</a>. Use |
| <a class="Xr" href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/ZIP_SOURCE_GET_ARGS.html">ZIP_SOURCE_GET_ARGS(3)</a> to |
| decode the arguments into the following struct: |
| <div class="Pp"></div> |
| <div class="Bd" style="margin-left: 0.00ex;"> |
| <pre class="Li"> |
| struct zip_source_args_seek { |
| zip_int64_t offset; |
| int whence; |
| }; |
| </pre> |
| </div> |
| <div class="Pp"></div> |
| If the size of the source's data is known, use |
| <a class="Xr" href="zip_source_seek_compute_offset.html">zip_source_seek_compute_offset(3)</a> |
| to validate the arguments and compute the new offset. |
| <h2 class="Ss"><code class="Dv">ZIP_SOURCE_SEEK_WRITE</code></h2> |
| Specify position to write next byte to, like |
| <a class="Xr" href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/fseek.html">fseek(3)</a>. See |
| <code class="Dv">ZIP_SOURCE_SEEK</code> for details. |
| <h2 class="Ss"><code class="Dv">ZIP_SOURCE_STAT</code></h2> |
| Get meta information for the input data. <var class="Ar">data</var> points to an |
| allocated <var class="Vt">struct zip_stat</var>, which should be initialized |
| using <a class="Xr" href="zip_stat_init.html">zip_stat_init(3)</a> and then |
| filled in. |
| <div class="Pp"></div> |
| For uncompressed, unencrypted data, all information is optional. However, fill |
| in as much information as is readily available. |
| <div class="Pp"></div> |
| If the data is compressed, <code class="Dv">ZIP_STAT_COMP_METHOD</code>, |
| <code class="Dv">ZIP_STAT_SIZE</code>, and |
| <code class="Dv">ZIP_STAT_CRC</code> must be filled in. |
| <div class="Pp"></div> |
| If the data is encrypted, <code class="Dv">ZIP_STAT_ENCRYPTION_METHOD</code>, |
| <code class="Dv">ZIP_STAT_COMP_METHOD</code>, |
| <code class="Dv">ZIP_STAT_SIZE</code>, and |
| <code class="Dv">ZIP_STAT_CRC</code> must be filled in. |
| <div class="Pp"></div> |
| Information only available after the source has been read (e.g., size) can be |
| omitted in an earlier call. <i class="Em">NOTE</i>: |
| <b class="Fn">zip_source_function</b>() may be called with this argument even |
| after being called with <code class="Dv">ZIP_SOURCE_CLOSE</code>. |
| <div class="Pp"></div> |
| Return sizeof(struct zip_stat) on success. |
| <h2 class="Ss"><code class="Dv">ZIP_SOURCE_SUPPORTS</code></h2> |
| Return bitmap specifying which commands are supported. Use |
| <a class="Xr" href="zip_source_make_command_bitmap.html">zip_source_make_command_bitmap(3)</a>. |
| If this command is not implemented, the source is assumed to be a read source |
| without seek support. |
| <h2 class="Ss"><code class="Dv">ZIP_SOURCE_TELL</code></h2> |
| Return the current read offset in the source, like |
| <a class="Xr" href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/ftell.html">ftell(3)</a>. |
| <h2 class="Ss"><code class="Dv">ZIP_SOURCE_TELL_WRITE</code></h2> |
| Return the current write offset in the source, like |
| <a class="Xr" href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/ftell.html">ftell(3)</a>. |
| <h2 class="Ss"><code class="Dv">ZIP_SOURCE_WRITE</code></h2> |
| Write data to the source. Return number of bytes written. |
| <h2 class="Ss" id="Return_Values">Return Values</h2> |
| Commands should return -1 on error. <code class="Dv">ZIP_SOURCE_ERROR</code> |
| will be called to retrieve the error code. On success, commands return 0, |
| unless specified otherwise in the description above. |
| <h2 class="Ss" id="Calling_Conventions">Calling Conventions</h2> |
| The library will always issue <code class="Dv">ZIP_SOURCE_OPEN</code> before |
| issuing <code class="Dv">ZIP_SOURCE_READ</code>, |
| <code class="Dv">ZIP_SOURCE_SEEK</code>, or |
| <code class="Dv">ZIP_SOURCE_TELL</code>. When it no longer wishes to read from |
| this source, it will issue <code class="Dv">ZIP_SOURCE_CLOSE</code>. If the |
| library wishes to read the data again, it will issue |
| <code class="Dv">ZIP_SOURCE_OPEN</code> a second time. If the function is |
| unable to provide the data again, it should return -1. |
| <div class="Pp"></div> |
| <code class="Dv">ZIP_SOURCE_BEGIN_WRITE</code> or |
| <code class="Dv">ZIP_SOURCE_BEGIN_WRITE_CLONING</code> will be called before |
| <code class="Dv">ZIP_SOURCE_WRITE</code>, |
| <code class="Dv">ZIP_SOURCE_SEEK_WRITE</code>, or |
| <code class="Dv">ZIP_SOURCE_TELL_WRITE</code>. When writing is complete, |
| either <code class="Dv">ZIP_SOURCE_COMMIT_WRITE</code> or |
| <code class="Dv">ZIP_SOURCE_ROLLBACK_WRITE</code> will be called. |
| <div class="Pp"></div> |
| <code class="Dv">ZIP_SOURCE_STAT</code> can be issued at any time. |
| <div class="Pp"></div> |
| <code class="Dv">ZIP_SOURCE_ERROR</code> will only be issued in response to the |
| function returning -1. |
| <div class="Pp"></div> |
| <code class="Dv">ZIP_SOURCE_FREE</code> will be the last command issued; if |
| <code class="Dv">ZIP_SOURCE_OPEN</code> was called and succeeded, |
| <code class="Dv">ZIP_SOURCE_CLOSE</code> will be called before |
| <code class="Dv">ZIP_SOURCE_FREE</code>, and similarly for |
| <code class="Dv">ZIP_SOURCE_BEGIN_WRITE</code> or |
| <code class="Dv">ZIP_SOURCE_BEGIN_WRITE_CLONING</code> and |
| <code class="Dv">ZIP_SOURCE_COMMIT_WRITE</code> or |
| <code class="Dv">ZIP_SOURCE_ROLLBACK_WRITE</code>. |
| <h1 class="Sh" id="RETURN_VALUES">RETURN VALUES</h1> |
| Upon successful completion, the created source is returned. Otherwise, |
| <code class="Dv">NULL</code> is returned and the error code in |
| <var class="Ar">archive</var> or <var class="Ar">error</var> is set to |
| indicate the error (unless it is <code class="Dv">NULL</code>). |
| <h1 class="Sh" id="ERRORS">ERRORS</h1> |
| <b class="Fn">zip_source_function</b>() fails if: |
| <dl class="Bl-tag" style="margin-left: 17.00ex;"> |
| <dt class="It-tag" style="margin-left: -17.00ex;"> </dt> |
| <dd class="It-tag"> </dd> |
| <dt class="It-tag" style="margin-left: -17.00ex;">[<code class="Er">ZIP_ER_MEMORY</code>]</dt> |
| <dd class="It-tag">Required memory could not be allocated.</dd> |
| </dl> |
| <h1 class="Sh" id="SEE_ALSO">SEE ALSO</h1> |
| <a class="Xr" href="libzip.html">libzip(3)</a>, |
| <a class="Xr" href="zip_add.html">zip_add(3)</a>, |
| <a class="Xr" href="zip_replace.html">zip_replace(3)</a>, |
| <a class="Xr" href="zip_source.html">zip_source(3)</a>, |
| <a class="Xr" href="zip_stat_init.html">zip_stat_init(3)</a> |
| <h1 class="Sh" id="HISTORY">HISTORY</h1> |
| <b class="Fn">zip_source_function</b>() and |
| <b class="Fn">zip_source_function_create</b>() were added in libzip 1.0. |
| <h1 class="Sh" id="AUTHORS">AUTHORS</h1> |
| <span class="An">Dieter Baron</span> |
| <<a class="Mt" href="mailto:dillo@nih.at">dillo@nih.at</a>> and |
| <span class="An">Thomas Klausner</span> |
| <<a class="Mt" href="mailto:tk@giga.or.at">tk@giga.or.at</a>></div> |
| <table class="foot"> |
| <tr> |
| <td class="foot-date">December 18, 2017</td> |
| <td class="foot-os">NetBSD 8.99.14</td> |
| </tr> |
| </table> |
| </body> |
| </html> |
