source/libs/zziplib/zziplib-0.13.62/docs/zzip-zip.htm

   1 <section><date> 1. June 2000 </date>
   2 <h2> ZIP Access </h2>    Accessing Zip Archives with ZLib Decompression
   3
   4 <!--border-->
   5
   6 <section>
   7 <h3> The Library </h3>
   8
   9 <P>
  10  The <a href="zziplib.html">zziplib library</a> offers users the
  11  ability to easily extract data from files archived in a single
  12  zip file. This way, programs that use many "read-only" files from
  13  a program specific source directory can have a single zip
  14  archive
  15 </P>
  16 <P>
  17  This library offers only a (free) subset of compression methods
  18  provided in a full implementation but that is well enough. The
  19  idea here is that <tt>zip/unzip</tt> utilities can be used
  20  to create archives that will later be read by using this library.
  21  Yet those programmes (or a library with their functionality)
  22  is not needed in that final operation.
  23 </P>
  24
  25 </section><section>
  26 <h3> Using A Zip-File </h3>
  27
  28 <P>
  29  Before a file in the zip-archive is accessed, the application
  30  must first get a handle to the central directory contained in the
  31  zip-file. This is achived by calling
  32  <a href="zziplib.html#zzip_dir_open"> zzip_dir_open </a>
  33  or
  34  <a href="zziplib.html#zzip_dir_fdopen"> zzip_dir_fdopen </a>.
  35  The directory entries in the zip-archives can be obtained
  36  with
  37  <a href="zziplib.html#zzip_dir_read"> zzip_dir_read </a>.
  38  After being done, the zip-dir handle should be closed with
  39  <a href="zziplib.html#zzip_dir_close"> zzip_dir_close </a>.
  40 </P>
  41 <p><pre> ZZIP_DIR* dir = zzip_dir_open("test.zip",0);
  42  if (dir) {
  43    ZZIP_DIRENT dirent;
  44    if (zzip_dir_read(dir,&amp;dirent) {
  45      /* show info for first file */
  46      print("%s %i/%i", dirent.d_name, dirent.d_csize, dirent.st_size);
  47    }
  48    zzip_dir_close(dir);
  49  }
  50 </pre></p>
  51 <P>
  52  From the zip-dir handle a compressed file can be opened
  53  for reading. This is achieved by using
  54  <a href="zziplib.html#zzip_file_open"> zzip_file_open </a>
  55  and providing it with the dir-handle and a name of the file.
  56  The function
  57  <a href="zziplib.html#zzip_file_read"> zzip_file_read </a>
  58  is used to get pieces of uncompressed data from the file, and
  59  the file-handle should be closed with
  60  <a href="zziplib.html#zzip_file_close"> zzip_file_close </a>
  61 </P>
  62 <p><pre> ZZIP_FILE* fp = zzip_file_open(dir,"README",0);
  63  if (fp) {
  64    char buf[10];
  65    zzip_ssize_t len = zzip_file_read(fp, buf, 10);
  66    if (len) {
  67      /* show head of README */
  68      write(1, buf, len);
  69    }
  70    zzip_file_close(fp);
  71  }
  72 </pre></p>
  73
  74 </section><section>
  75 <h3> Magic Zipped Files </h3>
  76
  77 <P>
  78  There is actually no need to directly use the zip-centric functions
  79  as described above. Instead there are magic replacements for the
  80  posix calls <code>open/read/close</code> and
  81  <code>opendir/readdir/closedir</code>. The prototypes of these
  82  functions had been the guideline for the design of their magic
  83  counterparts of the
  84  <a href="zziplib.html">zziplib library</a>.
  85 </P>
  86 <P>
  87  The magic functions are described in a seperated document on
  88  <a href="zzip-file.html"> Using Zipped Files </a>. In general,
  89  the functions have a prefix <tt>zzip_</tt> and their argument
  90  types have a prefix <tt>ZZIP_</tt> where appropriate. Calls
  91  to the magic functions and the direct functions above can
  92  be mixed as long as the magic functions have not been opening
  93  a real file.
  94 </P>
  95 <P>
  96  To detect a real file (or directory), the info functions
  97  <a href="zziplib.html#zzip_file_real"> zzip_file_real </a>
  98  and
  99  <a href="zziplib.html#zzip_dir_real"> zzip_dir_real </a>
 100  can be used.
 101  If these return a true value, the standard posix functions
 102  are more apropriate. The posix handles can be obtained with
 103  a call to
 104  <a href="zziplib.html#zzip_realdir"> zzip_realdir </a> and
 105  <a href="zziplib.html#zzip_realfd"> zzip_realfd </a> respectivly.
 106 </P>
 107
 108 </section><section>
 109 <h3> Errors &amp; Infos </h3>
 110
 111 <P>
 112  There are a set of error and info functions available. To handle
 113  error conditions specific to the
 114  <a href="zziplib.html">zziplib library</a>
 115  there are these functions:
 116  <a href="zziplib.html#zzip_error"> zzip_error </a>,
 117  <a href="zziplib.html#zzip_seterror"> zzip_seterror </a>
 118  and their string representations with
 119  <a href="zziplib.html#zzip_strerror"> zzip_strerror </a>,
 120  <a href="zziplib.html#zzip_strerror_of"> zzip_strerror_of </a>.
 121  The magic functions will map any of these specific library
 122  error conditions to the more generic system <code>errno</code>
 123  codes with
 124  <a href="zziplib.html#zzip_errno"> zzip_errno </a>.
 125 </P>
 126 <P>
 127  More information on stream can be obtained with
 128  <a href="zziplib.html#zzip_dir_stat"> zzip_dir_stat </a> and
 129  <a href="zziplib.html#zzip_dirhandle"> zzip_dirhandle. </a>
 130  The latter is used to obtain the dir-handle that every zipped file
 131  handle has even if not explicitly opened.
 132 </P>
 133 <P>
 134  The usage of many functions are shown in the example programs
 135  that come along with the
 136  <a href="zziplib.html">zziplib library</a>. See the files
 137  <a href="zzcat.c"> zzcat.c </a> and
 138  <a href="zzdir.c"> zzdir.c </a>. The
 139  <a href="zziptest.c"> zziptest.c </a> program needs the
 140  private header file
 141  <a href="zzip.h"> zzip.h </a> whereas the library installer
 142  will only copy the public include file
 143  <a href="zziplib.h"> zziplib.h </a> to your system's
 144  <tt>include</tt> directory.
 145 </P>
 146 </section></section>