source/libs/zziplib/zziplib-0.13.62/docs/zzipfseeko.html

   1 <html><head><title>zziplib Library Functions</title>
   2 </head><body>
   3 <h2>zziplib Library Functions</h2><p>Version 0.13.62</p><p><big><b><code>#include &lt;zzip/fseeko.h&gt;</code></b></big></p><table width="100%"><tr><td valign="top"><code><b><code><a href="#zzip_entry_fopen">zzip_entry_fopen</a></code></b>(ZZIP_ENTRY * entry, int takeover)
   4  : zzip__new__ ZZIP_ENTRY_FILE *
   5 </code></td></tr><tr><td valign="top"><code><b><code><a href="#zzip_entry_ffile">zzip_entry_ffile</a></code></b>(FILE * disk, char *filename)
   6  : zzip__new__ ZZIP_ENTRY_FILE *
   7 </code></td></tr><tr><td valign="top"><code><b><code><a href="#zzip_entry_fread">zzip_entry_fread</a></code></b>(void *ptr, zzip_size_t sized, zzip_size_t nmemb,
   8                  ZZIP_ENTRY_FILE * file)
   9  : zzip_size_t
  10 </code></td></tr><tr><td valign="top"><code><b><code><a href="#zzip_entry_fclose">zzip_entry_fclose</a></code></b>(ZZIP_ENTRY_FILE * file)
  11  : int
  12 </code></td></tr><tr><td valign="top"><code><b><code><a href="#zzip_entry_feof">zzip_entry_feof</a></code></b>(ZZIP_ENTRY_FILE * file)
  13  : int
  14 </code></td></tr><tr><td valign="top"><code><b><code><a href="#zzip_entry_data_offset">zzip_entry_data_offset</a></code></b>(ZZIP_ENTRY * entry)
  15  : zzip_off_t
  16 </code></td></tr><tr><td valign="top"><code><b><code><a href="#zzip_entry_fread_file_header">zzip_entry_fread_file_header</a></code></b>(ZZIP_ENTRY * entry,
  17                              struct zzip_file_header *file_header)
  18  : static zzip_off_t
  19 </code></td></tr><tr><td valign="top"><code><b><code><a href="#zzip_entry_strdup_name">zzip_entry_strdup_name</a></code></b>(ZZIP_ENTRY * entry)
  20  : zzip__new__ char *
  21 </code></td></tr><tr><td valign="top"><code><b><code><a href="#zzip_entry_findfile">zzip_entry_findfile</a></code></b>(FILE * disk, char *filename,
  22                     ZZIP_ENTRY * _zzip_restrict entry, zzip_strcmp_fn_t compare)
  23  : zzip__new__ ZZIP_ENTRY *
  24 </code></td></tr><tr><td valign="top"><code><b><code><a href="#zzip_entry_findfirst">zzip_entry_findfirst</a></code></b>(FILE * disk)
  25  : zzip__new__ ZZIP_ENTRY *
  26 </code></td></tr><tr><td valign="top"><code><b><code><a href="#zzip_entry_findnext">zzip_entry_findnext</a></code></b>(ZZIP_ENTRY * _zzip_restrict entry)
  27  : zzip__new__ ZZIP_ENTRY *
  28 </code></td></tr><tr><td valign="top"><code><b><code><a href="#zzip_entry_free">zzip_entry_free</a></code></b>(ZZIP_ENTRY * entry)
  29  : int
  30 </code></td></tr><tr><td valign="top"><code><b><code><a href="#zzip_entry_findmatch">zzip_entry_findmatch</a></code></b>(FILE * disk, char *filespec,
  31                      ZZIP_ENTRY * _zzip_restrict entry,
  32                      zzip_fnmatch_fn_t compare, int flags)
  33  : zzip__new__ ZZIP_ENTRY *
  34 </code></td></tr></table><h3>Documentation</h3><dl><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%"><tr><td valign="top"><code><b><a name="zzip_entry_fopen">zzip_entry_fopen</a></b>(ZZIP_ENTRY * entry, int takeover)
  35  : zzip__new__ ZZIP_ENTRY_FILE *
  36 </code></td></tr><tr><td valign="top"><code><b><a name="zzip_entry_ffile">zzip_entry_ffile</a></b>(FILE * disk, char *filename)
  37  : zzip__new__ ZZIP_ENTRY_FILE *
  38 </code></td></tr><tr><td valign="top"><code><b><a name="zzip_entry_fread">zzip_entry_fread</a></b>(void *ptr, zzip_size_t sized, zzip_size_t nmemb,
  39                  ZZIP_ENTRY_FILE * file)
  40  : zzip_size_t
  41 </code></td></tr><tr><td valign="top"><code><b><a name="zzip_entry_fclose">zzip_entry_fclose</a></b>(ZZIP_ENTRY_FILE * file)
  42  : int
  43 </code></td></tr><tr><td valign="top"><code><b><a name="zzip_entry_feof">zzip_entry_feof</a></b>(ZZIP_ENTRY_FILE * file)
  44  : int
  45 </code></td></tr></table></dt><dd><table width="100%"><tr><td valign="top"><table border="0" width="100%" cellpadding="0" cellspacing="0"><td> &nbsp;<em> open a file within a zip disk for reading</em> </td><td align="right"> <em><small>zzip/fseeko.c</small></em></td></table><p>
  46   The <code>zzip_entry_fopen</code> function does take an "entry" argument and copies it (or just takes
  47   it over as owner) to a new ZZIP_ENTRY_FILE handle structure. That
  48   structure contains also a zlib buffer for decoding. The <code>zzip_entry_fopen</code> function does
  49   seek to the file_header of the given "entry" and validates it for the
  50   data buffer following it. We do also prefetch some data from the data
  51   buffer thereby trying to match the disk pagesize for faster access later.
  52   The <code><a href="#zzip_entry_fread">zzip_entry_fread</a></code> will then read in chunks of pagesizes which is
  53   the size of the internal readahead buffer. If an error occurs then null
  54   is returned.
  55 </p>
  56 </td></tr><tr><td valign="top"><p>
  57   The <code>zzip_entry_ffile</code> function opens a file found by name, so it does a search into
  58   the zip central directory with <code><a href="#zzip_entry_findfile">zzip_entry_findfile</a></code> and whatever
  59   is found first is given to <code><a href="#zzip_entry_fopen">zzip_entry_fopen</a></code>
  60 </p>
  61 </td></tr><tr><td valign="top"><p>
  62   The <code>zzip_entry_fread</code> function reads more bytes into the output buffer specified as
  63   arguments. The return value is null on eof or error, the stdio-like
  64   interface can not distinguish between these so you need to check
  65   with <code><a href="#zzip_entry_feof">zzip_entry_feof</a></code> for the difference.
  66 </p>
  67 </td></tr><tr><td valign="top"><p>  The <code>zzip_entry_fclose</code> function releases any zlib decoder info needed for decompression
  68   and dumps the ZZIP_ENTRY_FILE struct then.
  69 </p>
  70 </td></tr><tr><td valign="top"><p>
  71   The <code>zzip_entry_feof</code> function allows to distinguish an error from an eof condition.
  72   Actually, if we found an error but we did already reach eof then we
  73   just keep on saying that it was an eof, so the app can just continue.
  74 </p>
  75 </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_entry_data_offset">zzip_entry_data_offset</a></b>(ZZIP_ENTRY * entry)
  76  : zzip_off_t
  77 </code></td></tr><tr><td valign="top"><code><b><a name="zzip_entry_fread_file_header">zzip_entry_fread_file_header</a></b>(ZZIP_ENTRY * entry,
  78                              struct zzip_file_header *file_header)
  79  : static zzip_off_t
  80 </code></td></tr><tr><td valign="top"><code><b><a name="zzip_entry_strdup_name">zzip_entry_strdup_name</a></b>(ZZIP_ENTRY * entry)
  81  : zzip__new__ char *
  82 </code></td></tr></table></dt><dd><table width="100%"><tr><td valign="top"><table border="0" width="100%" cellpadding="0" cellspacing="0"><td> &nbsp;<em> helper functions for (fseeko) zip access api</em> </td><td align="right"> <em><small>zzip/fseeko.c</small></em></td></table><p>
  83   The <code>zzip_entry_data_offset</code> functions returns the seekval offset of the data portion of the
  84   file referenced by the given zzip_entry. It requires an intermediate
  85   check of the file_header structure (i.e. it reads it from disk). After
  86   this call, the contained diskfile readposition is already set to the
  87   data_offset returned here. On error -1 is returned.
  88 </p>
  89 </td></tr><tr><td valign="top"><p>  The <code>zzip_entry_fread_file_header</code> functions read the correspoding struct zzip_file_header from
  90   the zip disk of the given "entry". The returned off_t points to the
  91   end of the file_header where the current fseek pointer has stopped.
  92   This is used to immediatly parse out any filename/extras block following
  93   the file_header. The return value is null on error.
  94 </p>
  95 </td></tr><tr><td valign="top"><p>  The <code>zzip_entry_strdup_name</code> function is a big helper despite its little name: in a zip file the
  96   encoded filenames are usually NOT zero-terminated but for common usage
  97   with libc we need it that way. Secondly, the filename SHOULD be present
  98   in the zip central directory but if not then we fallback to the filename
  99   given in the file_header of each compressed data portion.
 100 </p>
 101 </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%"><tr><td valign="top"><code><b><a name="zzip_entry_findfile">zzip_entry_findfile</a></b>(FILE * disk, char *filename,
 102                     ZZIP_ENTRY * _zzip_restrict entry, zzip_strcmp_fn_t compare)
 103  : zzip__new__ ZZIP_ENTRY *
 104 </code></td></tr><tr><td valign="top"><code><b><a name="zzip_entry_findfirst">zzip_entry_findfirst</a></b>(FILE * disk)
 105  : zzip__new__ ZZIP_ENTRY *
 106 </code></td></tr><tr><td valign="top"><code><b><a name="zzip_entry_findnext">zzip_entry_findnext</a></b>(ZZIP_ENTRY * _zzip_restrict entry)
 107  : zzip__new__ ZZIP_ENTRY *
 108 </code></td></tr><tr><td valign="top"><code><b><a name="zzip_entry_free">zzip_entry_free</a></b>(ZZIP_ENTRY * entry)
 109  : int
 110 </code></td></tr><tr><td valign="top"><code><b><a name="zzip_entry_findmatch">zzip_entry_findmatch</a></b>(FILE * disk, char *filespec,
 111                      ZZIP_ENTRY * _zzip_restrict entry,
 112                      zzip_fnmatch_fn_t compare, int flags)
 113  : zzip__new__ ZZIP_ENTRY *
 114 </code></td></tr></table></dt><dd><table width="100%"><tr><td valign="top"><table border="0" width="100%" cellpadding="0" cellspacing="0"><td> &nbsp;<em> search for files in the (fseeko) zip central directory</em> </td><td align="right"> <em><small>zzip/fseeko.c</small></em></td></table><p>
 115   The <code>zzip_entry_findfile</code> function is given a filename as an additional argument, to find the
 116   disk_entry matching a given filename. The compare-function is usually
 117   strcmp or strcasecmp or perhaps strcoll, if null then strcmp is used.
 118   - use null as argument for "old"-entry when searching the first
 119   matching entry, otherwise the last returned value if you look for other
 120   entries with a special "compare" function (if null then a doubled search
 121   is rather useless with this variant of _findfile). If no further entry is
 122   found then null is returned and any "old"-entry gets already free()d.
 123 </p>
 124 </td></tr><tr><td valign="top"><p>
 125   The <code>zzip_entry_findfirst</code> function is the first call of all the zip access functions here.
 126   It contains the code to find the first entry of the zip central directory.
 127   Here we require the stdio handle to represent a real zip file where the
 128   disk_trailer is _last_ in the file area, so that its position would be at
 129   a fixed offset from the end of the file area if not for the comment field
 130   allowed to be of variable length (which needs us to do a little search
 131   for the disk_tailer). However, in this simple implementation we disregard
 132   any disk_trailer info telling about multidisk archives, so we just return
 133   a pointer to the first entry in the zip central directory of that file.
 134 </p><p>
 135   For an actual means, we are going to search backwards from the end
 136   of the mmaped block looking for the PK-magic signature of a
 137   disk_trailer. If we see one then we check the rootseek value to
 138   find the first disk_entry of the root central directory. If we find
 139   the correct PK-magic signature of a disk_entry over there then we
 140   assume we are done and we are going to return a pointer to that label.
 141 </p><p>
 142   The return value is a pointer to the first zzip_disk_entry being checked
 143   to be within the bounds of the file area specified by the arguments. If
 144   no disk_trailer was found then null is returned, and likewise we only
 145   accept a disk_trailer with a seekvalue that points to a disk_entry and
 146   both parts have valid PK-magic parts. Beyond some sanity check we try to
 147   catch a common brokeness with zip archives that still allows us to find
 148   the start of the zip central directory.
 149 </p>
 150 </td></tr><tr><td valign="top"><p>
 151   The <code>zzip_entry_findnext</code> function takes an existing "entry" in the central root directory
 152   (e.g. from zzip_entry_findfirst) and moves it to point to the next entry.
 153   On error it returns 0, otherwise the old entry. If no further match is
 154   found then null is returned and the entry already free()d. If you want
 155   to stop searching for matches before that case then please call
 156   <code><a href="#zzip_entry_free">zzip_entry_free</a></code> on the cursor struct ZZIP_ENTRY.
 157 </p>
 158 </td></tr><tr><td valign="top"><p>  the <code>zzip_entry_free</code> function releases the malloc()ed areas needed for zzip_entry, the
 159   pointer is invalid afterwards. The <code>zzip_entry_free</code> function has #define synonyms of
 160   zzip_entry_findlast(), zzip_entry_findlastfile(), zzip_entry_findlastmatch()
 161 </p>
 162 </td></tr><tr><td valign="top"><p>
 163   The <code>zzip_entry_findmatch</code> function uses a compare-function with an additional argument
 164   and it is called just like fnmatch(3) from POSIX.2 AD:1993), i.e.
 165   the argument filespec first and the ziplocal filename second with
 166   the integer-flags put in as third to the indirect call. If the
 167   platform has fnmatch available then null-compare will use that one
 168   and otherwise we fall back to mere strcmp, so if you need fnmatch
 169   searching then please provide an implementation somewhere else.
 170   - use null as argument for "after"-entry when searching the first
 171   matching entry, or the last disk_entry return-value to find the
 172   next entry matching the given filespec. If no further entry is
 173   found then null is returned and any "old"-entry gets already free()d.
 174 </p>
 175 </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></dl>
 176 </body></html>