313 lines
17 KiB
HTML
313 lines
17 KiB
HTML
|
<!DOCTYPE html>
|
||
|
<html>
|
||
|
<!-- This is an automatically generated file. Do not edit.
|
||
|
zip_source_function.mdoc -- create data source from function
|
||
|
Copyright (C) 2004-2017 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.
|
||
|
-->
|
||
|
<head>
|
||
|
<meta charset="utf-8"/>
|
||
|
<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" title="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
|
||
|
<code class="Nm" title="Nm">zip_source_function</code>,
|
||
|
<code class="Nm" title="Nm">zip_source_function_create</code> —
|
||
|
<div class="Nd" title="Nd">create data source from function</div>
|
||
|
<h1 class="Sh" title="Sh" id="LIBRARY"><a class="permalink" href="#LIBRARY">LIBRARY</a></h1>
|
||
|
libzip (-lzip)
|
||
|
<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
|
||
|
<code class="In" title="In">#include
|
||
|
<<a class="In" title="In">zip.h</a>></code>
|
||
|
<div class="Pp"></div>
|
||
|
<var class="Ft" title="Ft">zip_source_t *</var>
|
||
|
<br/>
|
||
|
<code class="Fn" title="Fn">zip_source_function</code>(<var class="Fa" title="Fa" style="white-space: nowrap;">zip_t
|
||
|
*archive</var>,
|
||
|
<var class="Fa" title="Fa" style="white-space: nowrap;">zip_source_callback
|
||
|
fn</var>, <var class="Fa" title="Fa" style="white-space: nowrap;">void
|
||
|
*userdata</var>);
|
||
|
<div class="Pp"></div>
|
||
|
<var class="Ft" title="Ft">zip_source_t *</var>
|
||
|
<br/>
|
||
|
<code class="Fn" title="Fn">zip_source_function_create</code>(<var class="Fa" title="Fa" style="white-space: nowrap;">zip_source_callback
|
||
|
fn</var>, <var class="Fa" title="Fa" style="white-space: nowrap;">void
|
||
|
*userdata</var>,
|
||
|
<var class="Fa" title="Fa" style="white-space: nowrap;">zip_error_t
|
||
|
*error</var>);
|
||
|
<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
|
||
|
The functions <code class="Fn" title="Fn">zip_source_function</code>() and
|
||
|
<code class="Fn" title="Fn">zip_source_function_create</code>() creates a zip
|
||
|
source from the user-provided function <var class="Ar" title="Ar">fn</var>,
|
||
|
which must be of the following type:
|
||
|
<div class="Pp"></div>
|
||
|
<var class="Ft" title="Ft">typedef zip_int64_t</var>
|
||
|
<code class="Fn" title="Fn">(*zip_source_callback)</code>(<var class="Fa" title="Fa">void
|
||
|
*userdata</var>, <var class="Fa" title="Fa">void *data</var>,
|
||
|
<var class="Fa" title="Fa">zip_uint64_t len</var>,
|
||
|
<var class="Fa" title="Fa">zip_source_cmd_t cmd</var>);
|
||
|
<div class="Pp"></div>
|
||
|
<var class="Ar" title="Ar">archive</var> or
|
||
|
<var class="Ar" title="Ar">error</var> are used for reporting errors and can
|
||
|
be <code class="Dv" title="Dv">NULL</code>.
|
||
|
<div class="Pp"></div>
|
||
|
When called by the library, the first argument is the
|
||
|
<var class="Ar" title="Ar">userdata</var> argument supplied to the function.
|
||
|
The next two arguments are a buffer <var class="Ar" title="Ar">data</var> of
|
||
|
size <var class="Ar" title="Ar">len</var> when data is passed in or expected
|
||
|
to be returned, or else <code class="Dv" title="Dv">NULL</code> and 0. The
|
||
|
last argument, <var class="Ar" title="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 <code class="Fn" title="Fn">zip_source_callback</code>():
|
||
|
<dl class="Bl-tag">
|
||
|
<dt> </dt>
|
||
|
<dd> </dd>
|
||
|
<dt>read source</dt>
|
||
|
<dd>Providing streamed data (for file data added to archives). Must support
|
||
|
<code class="Dv" title="Dv">ZIP_SOURCE_OPEN</code>,
|
||
|
<code class="Dv" title="Dv">ZIP_SOURCE_READ</code>,
|
||
|
<code class="Dv" title="Dv">ZIP_SOURCE_CLOSE</code>,
|
||
|
<code class="Dv" title="Dv">ZIP_SOURCE_STAT</code>, and
|
||
|
<code class="Dv" title="Dv">ZIP_SOURCE_ERROR</code>.</dd>
|
||
|
<dt> </dt>
|
||
|
<dd> </dd>
|
||
|
<dt>seekable read source</dt>
|
||
|
<dd>Same as previous, but from a source allowing reading from arbitrary
|
||
|
offsets (also for read-only zip archive). Must additionally support
|
||
|
<code class="Dv" title="Dv">ZIP_SOURCE_SEEK</code>,
|
||
|
<code class="Dv" title="Dv">ZIP_SOURCE_TELL</code>, and
|
||
|
<code class="Dv" title="Dv">ZIP_SOURCE_SUPPORTS</code>.</dd>
|
||
|
<dt> </dt>
|
||
|
<dd> </dd>
|
||
|
<dt>read/write source</dt>
|
||
|
<dd>Same as previous, but additionally allowing writing (also for writable zip
|
||
|
archives). Must additionally support
|
||
|
<code class="Dv" title="Dv">ZIP_SOURCE_BEGIN_WRITE</code>,
|
||
|
<code class="Dv" title="Dv">ZIP_SOURCE_COMMIT_WRITE</code>,
|
||
|
<code class="Dv" title="Dv">ZIP_SOURCE_ROLLBACK_WRITE</code>,
|
||
|
<code class="Dv" title="Dv">ZIP_SOURCE_SEEK_WRITE</code>,
|
||
|
<code class="Dv" title="Dv">ZIP_SOURCE_TELL_WRITE</code>, and
|
||
|
<code class="Dv" title="Dv">ZIP_SOURCE_REMOVE</code>.</dd>
|
||
|
</dl>
|
||
|
<h2 class="Ss" title="Ss"><code class="Dv" title="Dv">ZIP_SOURCE_BEGIN_WRITE</code></h2>
|
||
|
Prepare the source for writing. Use this to create any temporary file(s).
|
||
|
<h2 class="Ss" title="Ss"><code class="Dv" title="Dv">ZIP_SOURCE_BEGIN_WRITE_CLONING</code></h2>
|
||
|
Prepare the source for writing, keeping the first
|
||
|
<var class="Ar" title="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" title="Dv">ZIP_SOURCE_ROLLBACK_WRITE</code>).
|
||
|
<div class="Pp"></div>
|
||
|
The next write should happen at byte <var class="Ar" title="Ar">offset</var>.
|
||
|
<h2 class="Ss" title="Ss"><code class="Dv" title="Dv">ZIP_SOURCE_CLOSE</code></h2>
|
||
|
Reading is done.
|
||
|
<h2 class="Ss" title="Ss"><code class="Dv" title="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" title="Ss"><code class="Dv" title="Dv">ZIP_SOURCE_ERROR</code></h2>
|
||
|
Get error information. <var class="Ar" title="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" title="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" title="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" title="Ss"><code class="Dv" title="Dv">ZIP_SOURCE_FREE</code></h2>
|
||
|
Clean up and free all resources, including
|
||
|
<var class="Ar" title="Ar">userdata</var>. The callback function will not be
|
||
|
called again.
|
||
|
<h2 class="Ss" title="Ss"><code class="Dv" title="Dv">ZIP_SOURCE_OPEN</code></h2>
|
||
|
Prepare for reading.
|
||
|
<h2 class="Ss" title="Ss"><code class="Dv" title="Dv">ZIP_SOURCE_READ</code></h2>
|
||
|
Read data into the buffer <var class="Ar" title="Ar">data</var> of size
|
||
|
<var class="Ar" title="Ar">len</var>. Return the number of bytes placed into
|
||
|
<var class="Ar" title="Ar">data</var> on success, and zero for end-of-file.
|
||
|
<h2 class="Ss" title="Ss"><code class="Dv" title="Dv">ZIP_SOURCE_REMOVE</code></h2>
|
||
|
Remove the underlying file. This is called if a zip archive is empty when
|
||
|
closed.
|
||
|
<h2 class="Ss" title="Ss"><code class="Dv" title="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" title="Ss"><code class="Dv" title="Dv">ZIP_SOURCE_SEEK</code></h2>
|
||
|
Specify position to read next byte from, like
|
||
|
<a class="Xr" title="Xr" href="fseek.html">fseek(3)</a>. Use
|
||
|
<a class="Xr" title="Xr" href="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">
|
||
|
<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" title="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" title="Ss"><code class="Dv" title="Dv">ZIP_SOURCE_SEEK_WRITE</code></h2>
|
||
|
Specify position to write next byte to, like
|
||
|
<a class="Xr" title="Xr" href="fseek.html">fseek(3)</a>. See
|
||
|
<code class="Dv" title="Dv">ZIP_SOURCE_SEEK</code> for details.
|
||
|
<h2 class="Ss" title="Ss"><code class="Dv" title="Dv">ZIP_SOURCE_STAT</code></h2>
|
||
|
Get meta information for the input data. <var class="Ar" title="Ar">data</var>
|
||
|
points to an allocated <var class="Vt" title="Vt">struct zip_stat</var>, which
|
||
|
should be initialized using
|
||
|
<a class="Xr" title="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" title="Dv">ZIP_STAT_COMP_METHOD</code>,
|
||
|
<code class="Dv" title="Dv">ZIP_STAT_SIZE</code>, and
|
||
|
<code class="Dv" title="Dv">ZIP_STAT_CRC</code> must be filled in.
|
||
|
<div class="Pp"></div>
|
||
|
If the data is encrypted,
|
||
|
<code class="Dv" title="Dv">ZIP_STAT_ENCRYPTION_METHOD</code>,
|
||
|
<code class="Dv" title="Dv">ZIP_STAT_COMP_METHOD</code>,
|
||
|
<code class="Dv" title="Dv">ZIP_STAT_SIZE</code>, and
|
||
|
<code class="Dv" title="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" title="Em">NOTE</i>:
|
||
|
<code class="Fn" title="Fn">zip_source_function</code>() may be called with
|
||
|
this argument even after being called with
|
||
|
<code class="Dv" title="Dv">ZIP_SOURCE_CLOSE</code>.
|
||
|
<div class="Pp"></div>
|
||
|
Return sizeof(struct zip_stat) on success.
|
||
|
<h2 class="Ss" title="Ss"><code class="Dv" title="Dv">ZIP_SOURCE_SUPPORTS</code></h2>
|
||
|
Return bitmap specifying which commands are supported. Use
|
||
|
<a class="Xr" title="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" title="Ss"><code class="Dv" title="Dv">ZIP_SOURCE_TELL</code></h2>
|
||
|
Return the current read offset in the source, like
|
||
|
<a class="Xr" title="Xr" href="ftell.html">ftell(3)</a>.
|
||
|
<h2 class="Ss" title="Ss"><code class="Dv" title="Dv">ZIP_SOURCE_TELL_WRITE</code></h2>
|
||
|
Return the current write offset in the source, like
|
||
|
<a class="Xr" title="Xr" href="ftell.html">ftell(3)</a>.
|
||
|
<h2 class="Ss" title="Ss"><code class="Dv" title="Dv">ZIP_SOURCE_WRITE</code></h2>
|
||
|
Write data to the source. Return number of bytes written.
|
||
|
<h2 class="Ss" title="Ss" id="Return_Values"><a class="permalink" href="#Return_Values">Return
|
||
|
Values</a></h2>
|
||
|
Commands should return -1 on error.
|
||
|
<code class="Dv" title="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" title="Ss" id="Calling_Conventions"><a class="permalink" href="#Calling_Conventions">Calling
|
||
|
Conventions</a></h2>
|
||
|
The library will always issue <code class="Dv" title="Dv">ZIP_SOURCE_OPEN</code>
|
||
|
before issuing <code class="Dv" title="Dv">ZIP_SOURCE_READ</code>,
|
||
|
<code class="Dv" title="Dv">ZIP_SOURCE_SEEK</code>, or
|
||
|
<code class="Dv" title="Dv">ZIP_SOURCE_TELL</code>. When it no longer wishes
|
||
|
to read from this source, it will issue
|
||
|
<code class="Dv" title="Dv">ZIP_SOURCE_CLOSE</code>. If the library wishes to
|
||
|
read the data again, it will issue
|
||
|
<code class="Dv" title="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" title="Dv">ZIP_SOURCE_BEGIN_WRITE</code> or
|
||
|
<code class="Dv" title="Dv">ZIP_SOURCE_BEGIN_WRITE_CLONING</code> will be
|
||
|
called before <code class="Dv" title="Dv">ZIP_SOURCE_WRITE</code>,
|
||
|
<code class="Dv" title="Dv">ZIP_SOURCE_SEEK_WRITE</code>, or
|
||
|
<code class="Dv" title="Dv">ZIP_SOURCE_TELL_WRITE</code>. When writing is
|
||
|
complete, either <code class="Dv" title="Dv">ZIP_SOURCE_COMMIT_WRITE</code> or
|
||
|
<code class="Dv" title="Dv">ZIP_SOURCE_ROLLBACK_WRITE</code> will be called.
|
||
|
<div class="Pp"></div>
|
||
|
<code class="Dv" title="Dv">ZIP_SOURCE_STAT</code> can be issued at any time.
|
||
|
<div class="Pp"></div>
|
||
|
<code class="Dv" title="Dv">ZIP_SOURCE_ERROR</code> will only be issued in
|
||
|
response to the function returning -1.
|
||
|
<div class="Pp"></div>
|
||
|
<code class="Dv" title="Dv">ZIP_SOURCE_FREE</code> will be the last command
|
||
|
issued; if <code class="Dv" title="Dv">ZIP_SOURCE_OPEN</code> was called and
|
||
|
succeeded, <code class="Dv" title="Dv">ZIP_SOURCE_CLOSE</code> will be called
|
||
|
before <code class="Dv" title="Dv">ZIP_SOURCE_FREE</code>, and similarly for
|
||
|
<code class="Dv" title="Dv">ZIP_SOURCE_BEGIN_WRITE</code> or
|
||
|
<code class="Dv" title="Dv">ZIP_SOURCE_BEGIN_WRITE_CLONING</code> and
|
||
|
<code class="Dv" title="Dv">ZIP_SOURCE_COMMIT_WRITE</code> or
|
||
|
<code class="Dv" title="Dv">ZIP_SOURCE_ROLLBACK_WRITE</code>.
|
||
|
<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="permalink" href="#RETURN_VALUES">RETURN
|
||
|
VALUES</a></h1>
|
||
|
Upon successful completion, the created source is returned. Otherwise,
|
||
|
<code class="Dv" title="Dv">NULL</code> is returned and the error code in
|
||
|
<var class="Ar" title="Ar">archive</var> or
|
||
|
<var class="Ar" title="Ar">error</var> is set to indicate the error (unless it
|
||
|
is <code class="Dv" title="Dv">NULL</code>).
|
||
|
<h1 class="Sh" title="Sh" id="ERRORS"><a class="permalink" href="#ERRORS">ERRORS</a></h1>
|
||
|
<code class="Fn" title="Fn">zip_source_function</code>() fails if:
|
||
|
<dl class="Bl-tag">
|
||
|
<dt> </dt>
|
||
|
<dd> </dd>
|
||
|
<dt>[<a class="permalink" href="#ZIP_ER_MEMORY"><code class="Er" title="Er" id="ZIP_ER_MEMORY">ZIP_ER_MEMORY</code></a>]</dt>
|
||
|
<dd>Required memory could not be allocated.</dd>
|
||
|
</dl>
|
||
|
<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
|
||
|
ALSO</a></h1>
|
||
|
<a class="Xr" title="Xr" href="libzip.html">libzip(3)</a>,
|
||
|
<a class="Xr" title="Xr" href="zip_file_add.html">zip_file_add(3)</a>,
|
||
|
<a class="Xr" title="Xr" href="zip_file_replace.html">zip_file_replace(3)</a>,
|
||
|
<a class="Xr" title="Xr" href="zip_source.html">zip_source(3)</a>,
|
||
|
<a class="Xr" title="Xr" href="zip_stat_init.html">zip_stat_init(3)</a>
|
||
|
<h1 class="Sh" title="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
|
||
|
<code class="Fn" title="Fn">zip_source_function</code>() and
|
||
|
<code class="Fn" title="Fn">zip_source_function_create</code>() were added in
|
||
|
libzip 1.0.
|
||
|
<h1 class="Sh" title="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1>
|
||
|
<span class="An" title="An">Dieter Baron</span>
|
||
|
<<a class="Mt" title="Mt" href="mailto:dillo@nih.at">dillo@nih.at</a>>
|
||
|
and <span class="An" title="An">Thomas Klausner</span>
|
||
|
<<a class="Mt" title="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.27</td>
|
||
|
</tr>
|
||
|
</table>
|
||
|
</body>
|
||
|
</html>
|