Add generated HTML man pages.
diff --git a/man/zip_source_function.html b/man/zip_source_function.html new file mode 100644 index 0000000..7f50206 --- /dev/null +++ b/man/zip_source_function.html
@@ -0,0 +1,265 @@ +<!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>