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

   1 <section> <date> 1. June 2000 </date>
   2 <h2> ZIP File Access </h2>  Using Zipped Files Transparently
   3
   4 <!--border-->
   5
   6 <section>
   7 <h3>The Typedef</h3>
   8
   9 <P>
  10  The typedef <code>ZZIP_FILE</code> can serve as a replacement
  11  for a normal file descriptor. As long as it is only used
  12  for reading a file, the zzlib-user can actually replace
  13  the posix functions <code>open/read/close</code>
  14  by their counterparts from the
  15  <a href="zziplib.html">zziplib library</a>:
  16  <code>zzip_open/zzip_read/zzip_close</code>.
  17 </P>
  18 <P>
  19  As long as the filename path given to <code>zzip_open</code>
  20  refers to a real file in the filesystem, it will almost
  21  directly forward the call to the respective posix <code>open</code>
  22  call. The returned file descriptor is then stored in
  23  a member-variable of the <code>ZZIP_FILE</code> structure.
  24 </P>
  25 <P>
  26  Any subsequent calls to <code>zzip_read</code> will then
  27  be forwarded to the posix <code>read</code> call on the
  28  memorized file descriptor. The same about <code>zzip_close</code>
  29  which will call the posix <code>close</code> function and then
  30  <code>free</code> the <code>ZZIP_FILE</code> structure.
  31 </P>
  32 <P>
  33  The real benefit of the
  34  <a href="zziplib.html">zziplib library</a>
  35  comes about when the filename argument does actually refer
  36  to a file that is zipped in a zip-archive. It happens that
  37  even both a real file and a zipped file can live under the
  38  same pathname given to the <code>zzip_open</code> call,
  39  whereas the real file is used in preference.
  40 </P>
  41
  42 </section><section>
  43 <h3>Zipped File</h3>
  44
  45 <P>
  46  Suppose you have subdirectory called '<tt>test/</tt>'. In
  47  this directory is just one file, called '<tt>README</tt>'.
  48  Calling the <code>zzip_open</code> function with an
  49  argument of '<i>optional-path/</i> <tt>test/README</tt>',
  50  then it will open that file for subsequent reading with
  51  <code>zzip_read</code>. In this case the real (<i>stat'able</i>)
  52  file is opened.
  53 </P>
  54 <P>
  55  Now you can go to the '<tt>test/</tt>' directory and zip up
  56  the files in there by calling
  57  <nobr><tt>`zip ../test.zip *`</tt></nobr>.
  58  After this, you can delete the '<tt>test/</tt>' directory and
  59  the call to <code>zzip_open</code> will still succeed.
  60  The reason is that the part of the path saying
  61  '<tt>test/README</tt>' will be replaced by sth. like
  62  '<tt>test.zip:README</tt>' - that is the real file '<tt>test.zip</tt>'
  63  is opened and searched for a contained file '<tt>README</tt>'.
  64 </P>
  65 <P>
  66  Calling <code>zzip_read</code> on the zipped '<tt>README</tt>' file
  67  will return the very same data as if it is a real file in a
  68  real directory. If the zipped file is compressed it will be
  69  decompressed on the fly.
  70 </P>
  71
  72 </section><section>
  73 <h3>Zip Directory</h3>
  74
  75 <P>
  76  The same applies to the use of <code>opendir/readdir/closedir</code>
  77  which can safely be replaced with their counterparts from the
  78  <a href="zziplib.html">zziplib library</a> - again their prototype
  79  follows the scheme of the original calls, just prepend <tt>zzip_</tt>
  80  to the function calls and <tt>ZZIP_</tt> to the struct-typedefs.
  81 </P>
  82 <P>
  83  To call <code>zzip_opendir</code> on a real directory will then
  84  return a <code>ZZIP_DIR</code> whose member-variable
  85  <code>realdir</code> points to the actual <code>DIR</code>-structure
  86  returned by the underlying posix <code>opendir</code>-call.
  87 </P>
  88 <P>
  89  If a real directory '<tt>test</tt>' does not exist, then the
  90  <code>zzip_opendir</code> will try to open a file '<tt>test.zip</tt>'
  91  with a call to <code>zzip_dir_open</code>.
  92  Subsequent calls to <code>zzip_readdir</code> will then return
  93  information as being obtained from the central archive directory
  94  of the zip-file.
  95 </P>
  96
  97 </section><section>
  98 <h3>Differences</h3>
  99
 100 <P>
 101  There are no differences between the posix calls and their counterparts
 102  from the      <a href="zziplib.html">zziplib library</a> - well, just
 103  as long as the zip-file contains just the plain files from a directory.
 104 </P>
 105 <P>
 106  If the zip-file contains directory entries you may be prompted with
 107  some awkward behaviour, since in zip-file a directory happens to be
 108  just an empty file. Note that the posix function <code>open</code>
 109  may also open a directory for reading - it will only return
 110  <code>EISDIR</code> if the <code>open</code> mode-argument included
 111  write-access.
 112 </P>
 113 <P>
 114  What the current of version of the
 115  <a href="zziplib.html">zziplib library</a>
 116  can definitly not do: calling zzip_opendir on a directory zippend
 117  <em>inside</em> a zip-file.
 118 </P>
 119 <P>
 120  To prevent the enrollment of directories into the zip-archive, you
 121  can use the <tt>-D</tt> option of the <tt>zip</tt> program. That
 122  is in any <tt>Makefile</tt> you may want to use
 123  <nobr><tt>`cd $(dir) &amp;&amp; zip -D ../$(dir).zip *`</tt></nobr>.
 124 </P>
 125
 126 </section><section>
 127 <h3>Advantages</h3>
 128
 129 <P>
 130  Distribution of a set of files is much easier if it just means
 131  to wrap up a group of files into a zip-archive - and copy that
 132  zip-archive to the respective destination directory.
 133  Even more the files can be compressed and unlike a <tt>tar.gz</tt>
 134  archive there is no need to decompress the archive in temporary
 135  location before accessing a member-file.
 136 </P>
 137 <P>
 138  On the other hand, there is no chance to scatter files around
 139  on the disk like it could easily happen with a set of gzip'ed
 140  man-pages in a single `<tt>man</tt>`-directory. The reader
 141  application does not specifically need to know that the file
 142  is compressed, so that reading a script like
 143  `<tt>share/guile/x.x.x/ice-9/popen.scm</tt>` is done by simple
 144  calls to <code>zzip_read</code> which works on zip-file named
 145  `<tt>share/guile/x.x.x/ice-9.zip</tt>`.
 146 </P>
 147 <P>
 148  A version mismatch between different files in a group is now
 149  obvious: either the opened file belongs to the distribution
 150  archive, or otherwise in resides in a real directory <em>just
 151  next to the zip-archive that contains the original</em>.
 152 </P>
 153
 154 </section><section>
 155 <h3>Issues</h3>
 156
 157 <P>
 158  The  <a href="zziplib.html">zziplib library</a> does not
 159  use any code piece from the <code>zip</code> programs, neither
 160  <em>pkzip</em> nor <em>infozip</em>, so there is no license
 161  issue here. The decompression is done by using the free
 162  <a href="http://www.gzip.org/zlib">zlib library</a> which has no special
 163  issues with respect to licensing.
 164  The  rights to the <a href="zziplib.html">zziplib library</a>
 165  are reserved to the copyright holders, there is a public
 166  license that puts most the sources themselves under
 167  <a href="COPYING.LIB">the GNU Lesser General Public License</a>,
 168  so that the use of a shared library instance of the
 169  <a href="zziplib.html">zziplib library</a>
 170  has no restrictions of interest to application programmers.
 171  For more details and hints about static linking, check
 172  the <a href="copying.html">COPYING</a> information.
 173 </P>
 174 <P>
 175  The only issue you have with the
 176  <a href="zziplib.html">zziplib library</a>
 177  is the fact that you can only <em>read</em> the contained files.
 178  Writing/Compression is not implemented. Even more, a compressed
 179  file is not seekable at the moment although I hope that someone
 180  will stand up to implement that functionality someday.
 181 </P>
 182
 183 </section></section>