source/libs/zziplib/zziplib-0.13.62/docs/memdisk.htm

   1 <section> <date> 2005 </date>
   2 <H2> zzip/memdisk </H2> zip cache for mmapped views
   3
   4 <BLOCKQUOTE>
   5   These routines are fully independent from the traditional zzip
   6   implementation. They build on top of
   7   <a href="mmapped.html">zzip/mmapped</a> that uses a readonly
   8   mmapped sharedmem block. These functions add additional hints
   9   how to parse extension blocks and how to cache the zip central
  10   directory entries which does furthermore allow to convert them
  11   to any host-local format as required.
  12 </BLOCKQUOTE>
  13
  14 <section>
  15 <H3> zzip disk handle </H3>
  16
  17 <P>
  18   Other than with the <a href="fseeko.html">fseeko</a> alternative
  19   interface there is no need to have an actual disk handle to the
  20   zip archive. Instead you can use a bytewise copy of a file or
  21   even use a mmapped view of a file. This is generally the fastest
  22   way to get to the data contained in a zipped file. All it requires
  23   is enough of virtual memory space but a desktop computer with a
  24   a modern operating system will easily take care of that.
  25 </P>
  26
  27 <P>
  28   The zzipmmapped library provides a number of calls to create a
  29   disk handle representing a zip archive in virtual memory. Per
  30   default we use the sys/mmap.h (or MappedView) functionality
  31   of the operating system. See for more details in the
  32    <a href="mmapped.html">zzip/mmapped</a> descriptions.
  33 </P>
  34 <P>
  35   The zzip/memdisk extensions of zzip/mmapped are made to have a
  36   very similar call API - therefore you will find again open and
  37   close functions for filenames or filehandles. However the
  38   direct mmap interface is not re-exported under the zzip_mem_disk
  39   prefix (of the underlying zzip_disk prefix). The "_mem_" part
  40   hints that the central directory of the underlying zzip_disk
  41   is preparsed to a separate memory block.
  42 <PRE>
  43   ZZIP_MEM_DISK*  zzip_mem_disk_open(char* filename);
  44   ZZIP_MEM_DISK*  zzip_mem_disk_fdopen(int fd);
  45   void            zzip_mem_disk_close(ZZIP_MEM_DISK* disk);
  46
  47   int  zzip_mem_disk_load (ZZIP_MEM_DISK* dir, ZZIP_DISK* disk);
  48   void zzip_mem_disk_unload (ZZIP_MEM_DISK* dir);
  49 </PRE>
  50   The last two functions export some parts of the underlying
  51   interface. It is possible to bind an existing ZZIP_MEM_DISK
  52   handle with an arbitrary ZZIP_DISK handle. Upon calling "load"
  53   the central directory will be loaded from the underlying zip
  54   disk content and parsed to an internal mem block. The corresponding
  55   "unload" function will trash that central directory cache but it
  56   leaves the handles intact.
  57 </P>
  58
  59 </section><section>
  60 <H3> reading the central directory </H3>
  61
  62 <P>
  63   All other zzip_mem_disk functions are simply re-exporting the
  64   underlying zzip_disk functions. Note that the first field in
  65   the ZZIP_MEM_DISK is a "ZZIP_DISK* disk" - the header file
  66   zzip/memdisk.h will simply export inline functions where there
  67   is no special zzip_mem_disk function. Therefore, whenever a
  68   function call on a ZZIP_DISK handle is appropriate one can
  69   also use its cousin for a ZZIP_MEM_DISK handle without any
  70   penalties but future compatibility for extra functionality in
  71   zzip/memdisk layer of the zzip/mmapped library.
  72 </P>
  73
  74 <P><small>Note: by default the re-exports are done with the help
  75   of the C precompiler as precompiler macros. Using USE_INLINE
  76   will force to make them real inlines. In the future that may
  77   change in favor of a better autodetection for inline capabilities
  78   of the compiler and/or using a standard cpp-define that enables
  79   the C/C++ inline functions. The inline functions do have the
  80   added value of having strongtyped arguments provoking more
  81   readable warning messages in user application code.</small></P>
  82
  83 <PRE>
  84      inline ZZIP_DISK_ENTRY*
  85 zzip_mem_disk_findfirst(ZZIP_MEM_DISK* dir);
  86      inline ZZIP_DISK_ENTRY*
  87 zzip_mem_disk_findnext(ZZIP_MEM_DISK* dir, ZZIP_DISK_ENTRY* entry);
  88      inline char* _zzip_restrict
  89 zzip_mem_disk_entry_strdup_name(ZZIP_MEM_DISK* dir,
  90                                 ZZIP_DISK_ENTRY* entry);
  91      inline struct zzip_file_header*
  92 zzip_mem_disk_entry_to_file_header(ZZIP_MEM_DISK* dir,
  93                                    ZZIP_DISK_ENTRY* entry);
  94      inline char*
  95 zzip_mem_disk_entry_to_data(ZZIP_MEM_DISK* dir, ZZIP_DISK_ENTRY* entry);
  96      inline ZZIP_DISK_ENTRY*
  97 zzip_mem_disk_findfile(ZZIP_MEM_DISK* dir,
  98                        char* filename, ZZIP_DISK_ENTRY* after,
  99                        zzip_strcmp_fn_t compare);
 100      inline ZZIP_DISK_ENTRY*
 101 zzip_mem_disk_findmatch(ZZIP_MEM_DISK* dir,
 102                         char* filespec, ZZIP_DISK_ENTRY* after,
 103                         zzip_fnmatch_fn_t compare, int flags);
 104      inline ZZIP_DISK_FILE* _zzip_restrict
 105 zzip_mem_disk_entry_fopen (ZZIP_MEM_DISK* dir, ZZIP_DISK_ENTRY* entry);
 106      inline ZZIP_DISK_FILE* _zzip_restrict
 107 zzip_mem_disk_fopen (ZZIP_MEM_DISK* dir, char* filename);
 108      inline _zzip_size_t
 109 zzip_mem_disk_fread (void* ptr, _zzip_size_t size, _zzip_size_t nmemb,
 110                      ZZIP_DISK_FILE* file);
 111      inline int
 112 zzip_mem_disk_fclose (ZZIP_DISK_FILE* file);
 113      inline int
 114 zzip_mem_disk_feof (ZZIP_DISK_FILE* file);
 115 </PRE>
 116 </section></section>