<html><head><title>zziplib Library Functions</title>
</head><body>
<h2>zziplib Library Functions</h2><p>Version 0.13.62</p><p><big><b><code>#include <zzip/mmapped.h></code></b></big></p><table width="100%"><tr><td valign="top"><code><b><code><a href="#zzip_disk_entry_to_data">zzip_disk_entry_to_data</a></code></b>(ZZIP_DISK * disk, struct zzip_disk_entry * entry)
: zzip_byte_t *
</code></td></tr><tr><td valign="top"><code><b><code><a href="#zzip_disk_entry_to_file_header">zzip_disk_entry_to_file_header</a></code></b>(ZZIP_DISK * disk, struct zzip_disk_entry *entry)
: struct zzip_file_header *
</code></td></tr><tr><td valign="top"><code><b><code><a href="#zzip_disk_entry_strdup_name">zzip_disk_entry_strdup_name</a></code></b>(ZZIP_DISK * disk, struct zzip_disk_entry *entry)
: zzip__new__ char *
</code></td></tr><tr><td valign="top"><code><b><code><a href="#zzip_disk_entry_strdup_comment">zzip_disk_entry_strdup_comment</a></code></b>(ZZIP_DISK * disk, struct zzip_disk_entry *entry)
: zzip__new__ char *
</code></td></tr><tr><td valign="top"><code><b><code><a href="#zzip_disk_findfile">zzip_disk_findfile</a></code></b>(ZZIP_DISK * disk, char *filename,
struct zzip_disk_entry *after, zzip_strcmp_fn_t compare)
: struct zzip_disk_entry *
</code></td></tr><tr><td valign="top"><code><b><code><a href="#zzip_disk_findfirst">zzip_disk_findfirst</a></code></b>(ZZIP_DISK * disk)
: struct zzip_disk_entry *
</code></td></tr><tr><td valign="top"><code><b><code><a href="#zzip_disk_findnext">zzip_disk_findnext</a></code></b>(ZZIP_DISK * disk, struct zzip_disk_entry *entry)
: struct zzip_disk_entry *
</code></td></tr><tr><td valign="top"><code><b><code><a href="#zzip_disk_findmatch">zzip_disk_findmatch</a></code></b>(ZZIP_DISK * disk, char *filespec,
struct zzip_disk_entry *after,
zzip_fnmatch_fn_t compare, int flags)
: struct zzip_disk_entry *
</code></td></tr><tr><td valign="top"><code><b><code><a href="#zzip_disk_fopen">zzip_disk_fopen</a></code></b>(ZZIP_DISK * disk, char *filename)
: zzip__new__ ZZIP_DISK_FILE *
</code></td></tr><tr><td valign="top"><code><b><code><a href="#zzip_disk_entry_fopen">zzip_disk_entry_fopen</a></code></b>(ZZIP_DISK * disk, ZZIP_DISK_ENTRY * entry)
: zzip__new__ ZZIP_DISK_FILE *
</code></td></tr><tr><td valign="top"><code><b><code><a href="#zzip_disk_fread">zzip_disk_fread</a></code></b>(void *ptr, zzip_size_t sized, zzip_size_t nmemb,
ZZIP_DISK_FILE * file)
: zzip_size_t
</code></td></tr><tr><td valign="top"><code><b><code><a href="#zzip_disk_fclose">zzip_disk_fclose</a></code></b>(ZZIP_DISK_FILE * file)
: int
</code></td></tr><tr><td valign="top"><code><b><code><a href="#zzip_disk_feof">zzip_disk_feof</a></code></b>(ZZIP_DISK_FILE * file)
: int
</code></td></tr><tr><td valign="top"><code><b><code><a href="#zzip_disk_mmap">zzip_disk_mmap</a></code></b>(int fd)
: zzip__new__ ZZIP_DISK *
</code></td></tr><tr><td valign="top"><code><b><code><a href="#zzip_disk_init">zzip_disk_init</a></code></b>(ZZIP_DISK * disk, void *buffer, zzip_size_t buflen)
: int
</code></td></tr><tr><td valign="top"><code><b><code><a href="#zzip_disk_new">zzip_disk_new</a></code></b>(void)
: zzip__new__ ZZIP_DISK *
</code></td></tr><tr><td valign="top"><code><b><code><a href="#zzip_disk_munmap">zzip_disk_munmap</a></code></b>(ZZIP_DISK * disk)
: int
</code></td></tr><tr><td valign="top"><code><b><code><a href="#zzip_disk_open">zzip_disk_open</a></code></b>(char *filename)
: zzip__new__ ZZIP_DISK *
</code></td></tr><tr><td valign="top"><code><b><code><a href="#zzip_disk_buffer">zzip_disk_buffer</a></code></b>(void *buffer, size_t buflen) : zzip__new__ ZZIP_DISK *
</code></td></tr><tr><td valign="top"><code><b><code><a href="#zzip_disk_close">zzip_disk_close</a></code></b>(ZZIP_DISK * disk)
: int
</code></td></tr></table><h3>Documentation</h3><dl><dt><table width="100%"><tr><td valign="top"><code><b><a name="zzip_disk_entry_to_data">zzip_disk_entry_to_data</a></b>(ZZIP_DISK * disk, struct zzip_disk_entry * entry)
: zzip_byte_t *
</code></td></tr><tr><td valign="top"><code><b><a name="zzip_disk_entry_to_file_header">zzip_disk_entry_to_file_header</a></b>(ZZIP_DISK * disk, struct zzip_disk_entry *entry)
: struct zzip_file_header *
</code></td></tr><tr><td valign="top"><code><b><a name="zzip_disk_entry_strdup_name">zzip_disk_entry_strdup_name</a></b>(ZZIP_DISK * disk, struct zzip_disk_entry *entry)
: zzip__new__ char *
</code></td></tr><tr><td valign="top"><code><b><a name="zzip_disk_entry_strdup_comment">zzip_disk_entry_strdup_comment</a></b>(ZZIP_DISK * disk, struct zzip_disk_entry *entry)
: zzip__new__ char *
</code></td></tr></table></dt><dd><table width="100%"><tr><td valign="top"><table border="0" width="100%" cellpadding="0" cellspacing="0"><td> <em> helper functions for (mmapped) zip access api</em> </td><td align="right"> <em><small>zzip/mmapped.c</small></em></td></table><p>
The <code>zzip_disk_entry_to_data</code> function augments the other zzip_disk_entry_* helpers: here we move
a disk_entry pointer (as returned by _find* functions) into a pointer to
the data block right after the file_header. Only disk->buffer would be
needed to perform the seek but we check the mmapped range end as well.
</p>
</td></tr><tr><td valign="top"><p> The <code>zzip_disk_entry_to_file_header</code> function does half the job of <code><a href="#zzip_disk_entry_to_data">zzip_disk_entry_to_data</a></code> where it
can augment with <code><u>zzip_file_header_to_data</u></code> helper from format/fetch.h
</p>
</td></tr><tr><td valign="top"><p> The <code>zzip_disk_entry_strdup_name</code> function is a big helper despite its little name: in a zip file the
encoded filenames are usually NOT zero-terminated but for common usage
with libc we need it that way. Secondly, the filename SHOULD be present
in the zip central directory but if not then we fallback to the filename
given in the file_header of each compressed data portion.
</p>
</td></tr><tr><td valign="top"><p> The <code>zzip_disk_entry_strdup_comment</code> function is similar creating a reference to a zero terminated
string but it can only exist in the zip central directory entry.
</p>
</td></tr></table></dd><dt><table width="100%"></table></dt><dd><table width="100%"></table></dd><dt><table width="100%"><tr><td valign="top"><code><b><a name="zzip_disk_findfile">zzip_disk_findfile</a></b>(ZZIP_DISK * disk, char *filename,
struct zzip_disk_entry *after, zzip_strcmp_fn_t compare)
: struct zzip_disk_entry *
</code></td></tr><tr><td valign="top"><code><b><a name="zzip_disk_findfirst">zzip_disk_findfirst</a></b>(ZZIP_DISK * disk)
: struct zzip_disk_entry *
</code></td></tr><tr><td valign="top"><code><b><a name="zzip_disk_findnext">zzip_disk_findnext</a></b>(ZZIP_DISK * disk, struct zzip_disk_entry *entry)
: struct zzip_disk_entry *
</code></td></tr><tr><td valign="top"><code><b><a name="zzip_disk_findmatch">zzip_disk_findmatch</a></b>(ZZIP_DISK * disk, char *filespec,
struct zzip_disk_entry *after,
zzip_fnmatch_fn_t compare, int flags)
: struct zzip_disk_entry *
</code></td></tr></table></dt><dd><table width="100%"><tr><td valign="top"><table border="0" width="100%" cellpadding="0" cellspacing="0"><td> <em> search for files in the (mmapped) zip central directory</em> </td><td align="right"> <em><small>zzip/mmapped.c</small></em></td></table><p>
The <code>zzip_disk_findfile</code> function is given a filename as an additional argument, to find the
disk_entry matching a given filename. The compare-function is usually
strcmp or strcasecmp or perhaps strcoll, if null then strcmp is used.
- use null as argument for "after"-entry when searching the first
matching entry, otherwise the last returned value if you look for other
entries with a special "compare" function (if null then a doubled search
is rather useless with this variant of _findfile).
</p>
</td></tr><tr><td valign="top"><p>
The <code>zzip_disk_findfirst</code> function is the first call of all the zip access functions here.
It contains the code to find the first entry of the zip central directory.
Here we require the mmapped block to represent a real zip file where the
disk_trailer is _last_ in the file area, so that its position would be at
a fixed offset from the end of the file area if not for the comment field
allowed to be of variable length (which needs us to do a little search
for the disk_tailer). However, in this simple implementation we disregard
any disk_trailer info telling about multidisk archives, so we just return
a pointer to the zip central directory.
</p><p>
For an actual means, we are going to search backwards from the end
of the mmaped block looking for the PK-magic signature of a
disk_trailer. If we see one then we check the rootseek value to
find the first disk_entry of the root central directory. If we find
the correct PK-magic signature of a disk_entry over there then we
assume we are done and we are going to return a pointer to that label.
</p><p>
The return value is a pointer to the first zzip_disk_entry being checked
to be within the bounds of the file area specified by the arguments. If
no disk_trailer was found then null is returned, and likewise we only
accept a disk_trailer with a seekvalue that points to a disk_entry and
both parts have valid PK-magic parts. Beyond some sanity check we try to
catch a common brokeness with zip archives that still allows us to find
the start of the zip central directory.
</p>
</td></tr><tr><td valign="top"><p>
The <code>zzip_disk_findnext</code> function takes an existing disk_entry in the central root directory
(e.g. from zzip_disk_findfirst) and returns the next entry within in
the given bounds of the mmapped file area.
</p>
</td></tr><tr><td valign="top"><p>
The <code>zzip_disk_findmatch</code> function uses a compare-function with an additional argument
and it is called just like fnmatch(3) from POSIX.2 AD:1993), i.e.
the argument filespec first and the ziplocal filename second with
the integer-flags put in as third to the indirect call. If the
platform has fnmatch available then null-compare will use that one
and otherwise we fall back to mere strcmp, so if you need fnmatch
searching then please provide an implementation somewhere else.
- use null as argument for "after"-entry when searching the first
matching entry, or the last disk_entry return-value to find the
next entry matching the given filespec.
</p>
</td></tr></table></dd><dt><table width="100%"></table></dt><dd><table width="100%"></table></dd><dt><table width="100%"></table></dt><dd><table width="100%"></table></dd><dt><table width="100%"></table></dt><dd><table width="100%"></table></dd><dt><table width="100%"><tr><td valign="top"><code><b><a name="zzip_disk_fopen">zzip_disk_fopen</a></b>(ZZIP_DISK * disk, char *filename)
: zzip__new__ ZZIP_DISK_FILE *
</code></td></tr><tr><td valign="top"><code><b><a name="zzip_disk_entry_fopen">zzip_disk_entry_fopen</a></b>(ZZIP_DISK * disk, ZZIP_DISK_ENTRY * entry)
: zzip__new__ ZZIP_DISK_FILE *
</code></td></tr><tr><td valign="top"><code><b><a name="zzip_disk_fread">zzip_disk_fread</a></b>(void *ptr, zzip_size_t sized, zzip_size_t nmemb,
ZZIP_DISK_FILE * file)
: zzip_size_t
</code></td></tr><tr><td valign="top"><code><b><a name="zzip_disk_fclose">zzip_disk_fclose</a></b>(ZZIP_DISK_FILE * file)
: int
</code></td></tr><tr><td valign="top"><code><b><a name="zzip_disk_feof">zzip_disk_feof</a></b>(ZZIP_DISK_FILE * file)
: int
</code></td></tr></table></dt><dd><table width="100%"><tr><td valign="top"><table border="0" width="100%" cellpadding="0" cellspacing="0"><td> <em> openening a file part wrapped within a (mmapped) zip archive</em> </td><td align="right"> <em><small>zzip/mmapped.c</small></em></td></table><p>
The <code>zzip_disk_fopen</code> function opens a file found by name, so it does a search into
the zip central directory with <code><a href="#zzip_disk_findfile">zzip_disk_findfile</a></code> and whatever
is found first is given to <code><a href="#zzip_disk_entry_fopen">zzip_disk_entry_fopen</a></code>
</p>
</td></tr><tr><td valign="top"><p>
the ZZIP_DISK_FILE* is rather simple in just encapsulating the
arguments given to the <code>zzip_disk_entry_fopen</code> function plus a zlib deflate buffer.
Note that the ZZIP_DISK pointer does already contain the full
mmapped file area of a zip disk, so open()ing a file part within
that area happens to be a lookup of its bounds and encoding. That
information is memorized on the ZZIP_DISK_FILE so that subsequent
_read() operations will be able to get the next data portion or
return an eof condition for that file part wrapped in the zip archive.
</p>
</td></tr><tr><td valign="top"><p>
The <code>zzip_disk_fread</code> function reads more bytes into the output buffer specified as
arguments. The return value is null on eof or error, the stdio-like
interface can not distinguish between these so you need to check
with <code><a href="#zzip_disk_feof">zzip_disk_feof</a></code> for the difference.
</p>
</td></tr><tr><td valign="top"><p> The <code>zzip_disk_fclose</code> function releases any zlib decoder info needed for decompression
and dumps the ZZIP_DISK_FILE* then.
</p>
</td></tr><tr><td valign="top"><p>
The <code>zzip_disk_feof</code> function allows to distinguish an error from an eof condition.
Actually, if we found an error but we did already reach eof then we
just keep on saying that it was an eof, so the app can just continue.
</p>
</td></tr></table></dd><dt><table width="100%"></table></dt><dd><table width="100%"></table></dd><dt><table width="100%"></table></dt><dd><table width="100%"></table></dd><dt><table width="100%"></table></dt><dd><table width="100%"></table></dd><dt><table width="100%"><tr><td valign="top"><code><b><a name="zzip_disk_mmap">zzip_disk_mmap</a></b>(int fd)
: zzip__new__ ZZIP_DISK *
</code></td></tr><tr><td valign="top"><code><b><a name="zzip_disk_init">zzip_disk_init</a></b>(ZZIP_DISK * disk, void *buffer, zzip_size_t buflen)
: int
</code></td></tr><tr><td valign="top"><code><b><a name="zzip_disk_new">zzip_disk_new</a></b>(void)
: zzip__new__ ZZIP_DISK *
</code></td></tr><tr><td valign="top"><code><b><a name="zzip_disk_munmap">zzip_disk_munmap</a></b>(ZZIP_DISK * disk)
: int
</code></td></tr><tr><td valign="top"><code><b><a name="zzip_disk_open">zzip_disk_open</a></b>(char *filename)
: zzip__new__ ZZIP_DISK *
</code></td></tr><tr><td valign="top"><code><b><a name="zzip_disk_buffer">zzip_disk_buffer</a></b>(void *buffer, size_t buflen) : zzip__new__ ZZIP_DISK *
</code></td></tr><tr><td valign="top"><code><b><a name="zzip_disk_close">zzip_disk_close</a></b>(ZZIP_DISK * disk)
: int
</code></td></tr></table></dt><dd><table width="100%"><tr><td valign="top"><table border="0" width="100%" cellpadding="0" cellspacing="0"><td> <em> turn a filehandle into a mmapped zip disk archive handle</em> </td><td align="right"> <em><small>zzip/mmapped.c</small></em></td></table><p>
The <code>zzip_disk_mmap</code> function uses the given file-descriptor to detect the length of the
file and calls the system <a href="http://www.opengroup.org/onlinepubs/000095399/functions/mmap.html"><code>mmap(2)</code></a> to put it in main memory. If it is
successful then a newly allocated ZZIP_DISK* is returned with
disk->buffer pointing to the mapview of the zipdisk content.
</p>
</td></tr><tr><td valign="top"><p> The <code>zzip_disk_init</code> function does primary initialization of a disk-buffer struct.
</p>
</td></tr><tr><td valign="top"><p> The <code>zzip_disk_new</code> function allocates a new disk-buffer with <a href="http://www.opengroup.org/onlinepubs/000095399/functions/malloc.html"><code>malloc(3)</code></a>
</p>
</td></tr><tr><td valign="top"><p> The <code>zzip_disk_munmap</code> function is the inverse of <code><a href="#zzip_disk_mmap">zzip_disk_mmap</a></code> and using the system
munmap(2) on the buffer area and <a href="http://www.opengroup.org/onlinepubs/000095399/functions/free.html"><code>free(3)</code></a> on the ZZIP_DISK structure.
</p>
</td></tr><tr><td valign="top"><p>
The <code>zzip_disk_open</code> function opens the given archive by name and turn the filehandle
to <code><a href="#zzip_disk_mmap">zzip_disk_mmap</a></code> for bringing it to main memory. If it can not
be <a href="http://www.opengroup.org/onlinepubs/000095399/functions/mmap.html"><code>mmap(2)</code></a>'ed then we slurp the whole file into a newly <a href="http://www.opengroup.org/onlinepubs/000095399/functions/malloc.html"><code>malloc(2)</code></a>'ed
memory block. Only if that fails too then we return null. Since handling
of disk->buffer is ambigous it should not be snatched away please.
</p>
</td></tr><tr><td valign="top"><p> The <code>zzip_disk_buffer</code> function will attach a buffer with a zip image
that was acquired from another source than a file.
Note that if zzip_disk_mmap fails then zzip_disk_open
will fall back and try to read the full file to memory
wrapping a ZZIP_DISK around the memory buffer just as
the <code>zzip_disk_buffer</code> function will do. Note that the <code>zzip_disk_buffer</code> function will not
own the buffer, it will neither be written nor free()d.
</p>
</td></tr><tr><td valign="top"><p>
The <code>zzip_disk_close</code> function will release all data needed to access a (mmapped)
zip archive, including any malloc()ed blocks, sharedmem mappings
and it dumps the handle struct as well.
</p>
</td></tr></table></dd><dt><table width="100%"></table></dt><dd><table width="100%"></table></dd><dt><table width="100%"></table></dt><dd><table width="100%"></table></dd><dt><table width="100%"></table></dt><dd><table width="100%"></table></dd><dt><table width="100%"></table></dt><dd><table width="100%"></table></dd><dt><table width="100%"></table></dt><dd><table width="100%"></table></dd><dt><table width="100%"></table></dt><dd><table width="100%"></table></dd><dt><table width="100%"></table></dt><dd><table width="100%"></table></dd><dt><table width="100%"></table></dt><dd><table width="100%"></table></dd><dt><table width="100%"></table></dt><dd><table width="100%"></table></dd><dt><table width="100%"></table></dt><dd><table width="100%"></table></dd><dt><table width="100%"></table></dt><dd><table width="100%"></table></dd><dt><table width="100%"></table></dt><dd><table width="100%"></table></dd><dt><table width="100%"></table></dt><dd><table width="100%"></table></dd><dt><table width="100%"></table></dt><dd><table width="100%"></table></dd><dt><table width="100%"></table></dt><dd><table width="100%"></table></dd><dt><table width="100%"></table></dt><dd><table width="100%"></table></dd><dt><table width="100%"></table></dt><dd><table width="100%"></table></dd><dt><table width="100%"></table></dt><dd><table width="100%"></table></dd><dt><table width="100%"></table></dt><dd><table width="100%"></table></dd><dt><table width="100%"></table></dt><dd><table width="100%"></table></dd><dt><table width="100%"></table></dt><dd><table width="100%"></table></dd><dt><table width="100%"></table></dt><dd><table width="100%"></table></dd><dt><table width="100%"></table></dt><dd><table width="100%"></table></dd><dt><table width="100%"></table></dt><dd><table width="100%"></table></dd><dt><table width="100%"></table></dt><dd><table width="100%"></table></dd><dt><table width="100%"></table></dt><dd><table width="100%"></table></dd><dt><table width="100%"></table></dt><dd><table width="100%"></table></dd><dt><table width="100%"></table></dt><dd><table width="100%"></table></dd><dt><table width="100%"></table></dt><dd><table width="100%"></table></dd><dt><table width="100%"></table></dt><dd><table width="100%"></table></dd><dt><table width="100%"></table></dt><dd><table width="100%"></table></dd><dt><table width="100%"></table></dt><dd><table width="100%"></table></dd><dt><table width="100%"></table></dt><dd><table width="100%"></table></dd><dt><table width="100%"></table></dt><dd><table width="100%"></table></dd><dt><table width="100%"></table></dt><dd><table width="100%"></table></dd><dt><table width="100%"></table></dt><dd><table width="100%"></table></dd><dt><table width="100%"></table></dt><dd><table width="100%"></table></dd><dt><table width="100%"></table></dt><dd><table width="100%"></table></dd><dt><table width="100%"></table></dt><dd><table width="100%"></table></dd><dt><table width="100%"></table></dt><dd><table width="100%"></table></dd></dl>
</body></html>
