From 38785ceedd3147c9cecd681eeb064b37f33d4d91 Mon Sep 17 00:00:00 2001 From: Guido Draheim Date: Sat, 8 May 2004 19:40:40 +0000 Subject: [PATCH] using mksite.sh for doc build () --- ChangeLog | 4 + docs/Makefile.am | 14 +- docs/Makefile.in | 16 ++- docs/body.htm | 14 +- docs/mksite.sh | 138 +++++++++++++----- docs/zzip-api.htm | 336 +++---------------------------------------- docs/zzip-basics.htm | 160 +++++++++++++++++++++ docs/zzip-extras.htm | 161 +++++++++++++++++++++ zzip/zzip.h | 11 +- zziplib.spec | 2 +- 10 files changed, 485 insertions(+), 371 deletions(-) create mode 100644 docs/zzip-basics.htm create mode 100644 docs/zzip-extras.htm diff --git a/ChangeLog b/ChangeLog index 5f8cd98..62f18f4 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,7 @@ +2004-05-08 + * remove bogus zzip_file_open_ext_io from zzip.h + * change to use mksite.sh for documentation builds + 2004-03-08 * add link in docs/history.htm to the new appnote.txt whitepaper on zip file format specification. diff --git a/docs/Makefile.am b/docs/Makefile.am index a5cdcc9..b49514d 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -5,7 +5,7 @@ doc_FILES = README.MSVC6 README.SDL COPYING.MPL COPYING.LIB COPYING.ZLIB \ zziplib.html htm_FILES = zzip-index.htm zzip-zip.htm zzip-file.htm zzip-sdl-rwops.htm \ zzip-extio.htm zzip-xor.htm zzip-crypt.htm \ - zzip-api.htm zzip-parse.htm \ + zzip-api.htm zzip-basics.htm zzip-extras.htm zzip-parse.htm \ 64on32.htm future.htm configs.htm sfx-make.htm \ history.htm referentials.htm copying.htm manpages.ar SDL = @top_srcdir@/SDL @@ -18,6 +18,10 @@ EXTRA_DIST = make-doc.py $(doc_FILES) $(htm_FILES) $(SDL_RWOPS) \ CLEANFILES = *.pc *.omf DISTCLEANFILES = zziplib.spec manpages.ar htmpages.ar *.html *.xml +html_FILES = $(htm_FILES:.htm=.html) \ + $(htm_FILES:.htm=.print.html) + site.html site.print.html + default : doc clean-doc clean-docs : clean-unpack - rm $(DISTCLEANFILES) @@ -62,9 +66,9 @@ DOCEXAMPLES = $(bins)/zzdir.c $(bins)/zzcat.c \ $(bins)/zzxordir.c $(bins)/zzxorcat.c \ $(bins)/zzxorcopy.c $(SDL_RWOPS) -install-docu: $(doc_FILES) $(htm_FILES:.htm=.html) $(PACKAGE)-doc.omf +install-docu: $(doc_FILES) site.html $(PACKAGE)-doc.omf $(mkinstalldirs) $(DESTDIR)$(pkgdocdir) - for i in $(htm_FILES) ; do cat $${i}l \ + for i in $(html_FILES) ; do cat $$i \ | sed -e 's:--START-->:-- :' -e 's::-- :' -e 's:

+

+ created with mksite.sh +

+ diff --git a/docs/mksite.sh b/docs/mksite.sh index d58635b..159955f 100644 --- a/docs/mksite.sh +++ b/docs/mksite.sh @@ -20,7 +20,7 @@ # 2. Altered source versions must be plainly marked as such, and must not # be misrepresented as being the original software. # 3. This notice may not be removed or altered from any source distribution. -# $Id: mksite.sh,v 1.1 2004-05-08 17:52:52 guidod Exp $ +# $Id: mksite.sh,v 1.2 2004-05-08 19:37:52 guidod Exp $ # initialize some defaults test ".$SITEFILE" = "." && test -f site.htm && SITEFILE=site.htm @@ -926,41 +926,107 @@ body_for_emailfooter () # marks all interesting lines so they can be checked later # with an sed anchor of (or ) S="\\ \\;" -Hr="
" -He="
" -Hs="" -Br="
" -Pr="
$S" -Rr="
<>" -Bs="
" -Ps="
$S" -Rs="
<>" -Be="
" -Pe="
$S" -Re="
<>" -Eu="" -Es="" -echo "/^$Hr[-|[]*/" > $MK.gets.tmp -echo "/^$He[-|[]*/" >> $MK.gets.tmp -echo "/^$Hs[-|[]*/" >> $MK.gets.tmp -echo "/^$Br[*=][*=]*/" >> $MK.gets.tmp -echo "/^$Br[-|][-|]*/" >> $MK.gets.tmp -echo "/^$Br[/:][/:]*/" >> $MK.gets.tmp -echo "/^$Es[/:,[]*/" >> $MK.gets.tmp -echo "/^$Br[-|[]*/" >> $MK.gets.tmp -echo "/^$Bs[-|[]*/" >> $MK.gets.tmp -echo "/^$Be[-|[]*/" >> $MK.gets.tmp -echo "/^$Eu[-|[]*/" >> $MK.gets.tmp -echo "/^$Br[\\/:]*/" >> $MK.gets.tmp -echo "/^$Pr[\\/:]*/" >> $MK.gets.tmp -echo "/^$Rr[\\/:]*/" >> $MK.gets.tmp -echo "/^$Bs[\\/:]*/" >> $MK.gets.tmp -echo "/^$Ps[\\/:]*/" >> $MK.gets.tmp -echo "/^$Rs[\\/:]*/" >> $MK.gets.tmp -echo "/^$Be[\\/:]*/" >> $MK.gets.tmp -echo "/^$Pe[\\/:]*/" >> $MK.gets.tmp -echo "/^$Re[\\/:]*/" >> $MK.gets.tmp -echo "/^$Es[\\/:,[]*/" >> $MK.gets.tmp +HR1="
" +HR2="$S
" +HR3="<>
" +HE1="
" +HE2="$S
" +HE3="<>
" +HS1="
" +HS2="$S
" +HS3="<>
" +BR1="
" +BR2="$S
" +BR3="<>
" +BE1="
" +BE2="$S
" +BE3="<>
" +QE1="" +QE2="$S" +QE3="<>" +BU1="
" +BU2="$S
" +BU3="<>
" +QU1="" +QU2="$S" +QU3="<>" +BL1="
" +BL2="$S
" +BL3="<>
" +QL1="" +QL2="$S" +QL3="<>" +QR0="" +QR2="$S" +QR3="<>" +h1="[-|[]" +h1m="$S" +h1n="<>" +b1="[*=]" +b2="[-|[]" +b3="[\\/:]" +b3m="$S" +b3n="<>" +q3="[\\/:,[]" +q3m="$S" +q3n="<>" +echo "/^$HR1$h1n/" > $MK.gets.tmp +echo "/^$HR1$h1m/" >> $MK.gets.tmp +echo "/^$HR1$h1*/" >> $MK.gets.tmp +echo "/^$HR2$h1*/" >> $MK.gets.tmp +echo "/^$HR3$h1*/" >> $MK.gets.tmp +echo "/^$HE1$h1*/" >> $MK.gets.tmp +echo "/^$HE2$h1*/" >> $MK.gets.tmp +echo "/^$HE3$h1*/" >> $MK.gets.tmp +echo "/^$HS1$h1*/" >> $MK.gets.tmp +echo "/^$HS2$h1*/" >> $MK.gets.tmp +echo "/^$HS3$h1*/" >> $MK.gets.tmp +echo "/^$BR1$b1$b1*/" >> $MK.gets.tmp +echo "/^$BR2$b1$b1*/" >> $MK.gets.tmp +echo "/^$BR3$b1$b1*/" >> $MK.gets.tmp +echo "/^$BR1$b2$b2*/" >> $MK.gets.tmp +echo "/^$BR2$b2$b2*/" >> $MK.gets.tmp +echo "/^$BR3$b2$b2*/" >> $MK.gets.tmp +echo "/^$BR1$b3$b3*/" >> $MK.gets.tmp +echo "/^$BR2$b3$b3*/" >> $MK.gets.tmp +echo "/^$BR3$b3$b3*/" >> $MK.gets.tmp +echo "/^$QR0$b2$b2*/" >> $MK.gets.tmp +echo "/^$QR2$b2$b2*/" >> $MK.gets.tmp +echo "/^$QR3$b2$b2*/" >> $MK.gets.tmp +echo "/^$QR0$b3$b3*/" >> $MK.gets.tmp +echo "/^$QR2$b3$b3*/" >> $MK.gets.tmp +echo "/^$QR3$b3$b3*/" >> $MK.gets.tmp +echo "/^$QE1$q3*/" >> $MK.gets.tmp +echo "/^$QE2$q3*/" >> $MK.gets.tmp +echo "/^$QE3$q3*/" >> $MK.gets.tmp +echo "/^$BR1$b2*/" >> $MK.gets.tmp +echo "/^$BR2$b2*/" >> $MK.gets.tmp +echo "/^$BR3$b2*/" >> $MK.gets.tmp +echo "/^$BL1$b2*/" >> $MK.gets.tmp +echo "/^$BL2$b2*/" >> $MK.gets.tmp +echo "/^$BL3$b2*/" >> $MK.gets.tmp +echo "/^$BE1$b2*/" >> $MK.gets.tmp +echo "/^$BE2$b2*/" >> $MK.gets.tmp +echo "/^$BE3$b2*/" >> $MK.gets.tmp +echo "/^$QU1$b2*/" >> $MK.gets.tmp +echo "/^$QU2$b2*/" >> $MK.gets.tmp +echo "/^$QU3$b2*/" >> $MK.gets.tmp +echo "/^$BR1$b3n/" >> $MK.gets.tmp +echo "/^$BR1$b3m/" >> $MK.gets.tmp +echo "/^$BR1$b3*/" >> $MK.gets.tmp +echo "/^$BR2$b3*/" >> $MK.gets.tmp +echo "/^$BR3$b3*/" >> $MK.gets.tmp +echo "/^$QR2$b3*/" >> $MK.gets.tmp +echo "/^$QR3$b3*/" >> $MK.gets.tmp +echo "/^$BL1$b3*/" >> $MK.gets.tmp +echo "/^$BL2$b3*/" >> $MK.gets.tmp +echo "/^$BL3$b3*/" >> $MK.gets.tmp +echo "/^$BE1$b3*/" >> $MK.gets.tmp +echo "/^$BE2$b3*/" >> $MK.gets.tmp +echo "/^$BE3$b3*/" >> $MK.gets.tmp +echo "/^$QE1$q3*/" >> $MK.gets.tmp +echo "/^$QE2$q3*/" >> $MK.gets.tmp +echo "/^$QE3$q3*/" >> $MK.gets.tmp $SED -e "s/>\\[/> *[/" ./$MK.gets.tmp > $MK.puts.tmp # the .puts.tmp variant is used to some hrefs which # shall not be used otherwise for being generated - this is nice for diff --git a/docs/zzip-api.htm b/docs/zzip-api.htm index a3632e0..be14100 100644 --- a/docs/zzip-api.htm +++ b/docs/zzip-api.htm @@ -2,317 +2,27 @@ 20. July 2002 -

Basics

- -

- The naming schem of functions in this library follow a simple rule: - if you see a function with a zzip_ prefix followed by - compact name representing otherwise a C library or posix function then - it is a magic wrapper that can automagically handle both real - files/directories or zip-contained files. This includes: -

-
- - - - - - -
zzip_opendir opendir
zzip_readdir readdir
zzip_closedir closedir
zzip_rewinddir rewinddir
zzip_telldir telldir
zzip_seekdir seekdir
-

- The ZZIP_DIR handle can wrap both a real directory or a zip-file. - Note that you can not open a virtual directory within a - zip-file, the ZZIP_DIR is either a real DIR-handle of a real - directory or the reference of ZIP-file but never a DIR-handle - within a ZIP-file - there is no such schema of a SUB-DIR handle - implemented in this library. A ZZIP_DIR does actually represent - the central directory of a ZIP-file, so that each file entry in - this ZZIP-DIR can possibly have a subpath prepended. -

-

- This form of magic has historic reasons as originally the - magic wrappers of this library were not meant to wrap a complete - subtree of a real file tree but only a single directory being - wrapped with into a zip-file and placed instead. Later proposals - and patches were coming in to support subtree wrapping by not - only making a split between the dir-part and file-part but - going recursivly up through all "/"-dirseparators of a filepath - given to zzip_open and looking for zip-file there. -

- -

- To open a zip-file unconditionally one should be using their - respective methods that would return a ZZIP_DIR handle being - the representant memory instance of a ZIP-DIR, the central - directory of a zip-file. From that ZZIP-DIR one can open a - compressed file entry which will be returned as a ZZIP_FILE - pointer. -

-
- - - - - - - - -
zzip_dir_open open a zip-file and parse the central directory - to a memory shadow
zzip_dir_close close a zip-file and free the memory shadow
zzip_dir_fdopen aquire the given posix-file and try to parse it - as a zip-file.
zzip_dir_read return the next info entry of a zip-file's central - directory - this would include a possible subpath
- -

- To unconditionally access a zipped-file (as the counter-part of a - zip-file's directory) you should be using the functions having a - zzip_file_ prefix which are the methods working on - ZZIP_FILE pointers directly and assuming those are references of - a zipped file with a ZZIP_DIR. -

-
- - - - - - -
zzip_file_open open a file within a zip and prepare a zlib - compressor for it - note the ZZIP_DIR argument, - multiple ZZIP_FILE's may share the same central - directory shadow.
zzip_file_close close the handle of zippedfile - and free zlib compressor of it
zzip_file_read decompress the next part of a compressed file - within a zip-file
-

- From here it is only a short step to the magic wrappers for - file-access - when being given a filepath to zzip_open then - the filepath is checked first for being possibly a real file - (we can often do that by a stat call) and if there is - a real file under that name then the returned ZZIP_FILE is - nothing more than a wrapper around a file-descriptor of the - underlying operating system. Any other calls like zzip_read - will see the realfd-flag in the ZZIP_FILE and forward the - execution to the read() function of the underlying operating system. -

- -

- However if that fails then the filepath is cut at last directory - separator, i.e. a filepath of "this/test/README" is cut into the - dir-part "this/test" and a file-part "README". Then the possible - zip-extensions are attached (".zip" and ".ZIP") and we check if - there is a real file under that name. If a file "this/test.zip" - does exist then it is given to zzip_dir_open which will create - a ZZIP_DIR instance of it, and when that was successul (so it - was in zip-format) then we call zzip_file_open which will see - two arguments - the just opened ZZIP_DIR and the file-part. The - resulting ZZIP_FILE has its own copy of a ZZIP_DIR, so if you - open multiple files from the same zip-file than you will also - have multiple in-memory copies of the zip's central directory - whereas otherwise multiple ZZIP_FILE's may share a common - ZZIP_DIR when being opened with zzip_file_open directly - the - zzip_file_open's first argument is the ZZIP_DIR and the second - one the file-part to be looked up within that zip-directory. -

- -
- - - - - - -
zzip_open try the file-path as a real-file, and if not - there, look for the existance of ZZIP_DIR by - applying extensions, and open the file - contained within that one.
zzip_close if the ZZIP_FILE wraps a real-file, then call - read(), otherwise call zzip_file_read()
zzip_close if the ZZIP_FILE wraps a real-file, then call - close(), otherwise call zzip_file_close()
- -

- Up to here we have the original functionality of the zziplib - when I (Guido Draheim) created the magic functions around the work from - Tomi Ollila who wrote the routines to read and decompress files from - a zip archive - unlike other libraries it was quite readable and - intelligible source code (after many changes there is not much - left of the original zip08x source code but that's another story). - Later however some request and proposals and patches were coming in. -

- -

- Among the first extensions was the recursive zzip_open magic. In - the first instance, the library did just do as described above: - a file-path of "this/test/README" might be a zip-file known as - "this/test.zip" containing a compressed file "README". But if - there is neither a real file "this/test/README" and no real - zip-file "this/test.zip" then the call would have failed but - know the zzip_open call will recursivly check the parent - directories - so it can now find a zip-file "this.zip" which - contains a file-part "test/README". -

- -

- This dissolves the original meaning of a ZZIP_DIR and it has lead - to some confusion later on - you can not create a DIRENT-like handle - for "this/test/" being within a "test.zip" file. And actually, I did - never see a reason to implement it so far (open "this.zip" and set - an initial subpath of "test" and let zzip_readdir skip all entries - that do not start with "test/"). This is left for excercie ;-) -

- -

Extras

- -

- The next requests circulated around other file-extensions to - automagically look inside filetypes that have zip-format too but - carry other fileextensions - most famous might be the ".PK3" - files of ID's Quake game. There have been a number of these - requests and in a lot of cases it dawned to me that those guys - may have overlooked the zzip_dir_open functions to travel - through documents of zipformat under any name - that is that the - "magic" was not actually needed but they just wanted to read - files in zipformat with the zziplib. -

- -

- Other requests circulated around encryption but I did reject - those bluntly, always. Instead there have been always examples - for doing some obfuscation around the zip-format so that the - stock zip/unzip tools do not recognize them but a game - software developer can pack/unpack his AI scripts and bitmaps - into such a zipformat-like file. -

- -

- After some dead-end patches (being shipped along with the - zziplib as configure-time compile-options - greetings to - Lutz Sammer and Andreas Schiffler), the general approach - of _ext_io came up, and finally implemented (greetings go - to Mike Nordell). The _open()-calls do now each have a - cousin of _open_ext_io() with two/three additional arguments - being a set of extensions to loop through our magic testing, - a callback-handler plugin-table for obfuscation-means, - and (often) a bit-mask for extra-options - this bitmask even - has "PREFERZIP" and "ONLYZIP" options to skip the real-file - test magic in those zzip_*open functions. -

- -
- - - - - - - - - - -
zzip_open(name,flags) zzip_open_ext_io(name,flags,mode,ext,io)
zzip_opendir(name) zzip_opendir_ext_io(name,mode,ext,io)
zzip_dir_open(name,errp) zzip_dir_open_ext_io(name,errp,ext,io)
zzip_dir_fdopen(fd,errp) zzip_dir_fdopen_ext_io(fd,errp,ext,io)
zzip_file_open(dir,name,mode) zzip_file_open_ext_io(dir,name,mode,ext,io)
- -

- Oh, and note that the mode,ext,io extras are memorized - in the respecitive ZZIP_DIR handle attached, so each - of the other calls like zzip_file_open() - and zzip_read() will be using them. There - are a few helper routines to help setup a new io-plugin - where the init_io will currently just memcopy the - default_io entries into the user-supplied plugin-struct. -

- -
- - - - - - -
zzip_init_io the recommended way to do things
zzip_get_default_io used internally whenever you supply a null - for the io-argument of a _ext_io()-call
zzip_get_default_ext used internally but not exported
- - -

- And last some stdio-like replacements were build but these - happen to be actually just small wrappers around the other - posix-like magic-calls. It just offers some convenience - since wrappers like "SDL_rwops" tend to use a stringised - open-mode - and I took the occasion to fold the zzip-bits - for the _ext_io-calls right in there recognized via - special extensions to the openmode-string of zzip_fopen(). -

- -
- - - - - - -
zzip_fopen convert stringmode and call zzip_open_ext_io
zzip_fread slower way to say zzip_read
zzip_fclose a synonym of zzip_close
- -

- For some reason, people did need the full set of function-calls() - to be working on zzip-wrappers too, so here they are - if the - ZZIP_FILE instance did wrap a real file, then the real posix-call - will be used, otherwise it is simulated on the compressed stream - with a zip-contained file - especially seek() can be - a slow operation: - if the new point is later then just read out more bytes till we - hit that position but if it is an earlier point then rewind to the - beginning of the compressed data and start reading/decompression - until the position is met. -

- -
- - - - - - -
zzip_rewind magic for rewind()
zzip_tell magic for tell()
zzip_seek magic for seek()
- -

- And last not least, there are few informative functions to - use function-calls to read parts of the opaque structures - of zzip-objects and their zzip-factory. -

- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
zzip_dir_stat a stat()-like thing on a file within a ZZIP_DIR
zzip_dir_real check if ZZIP_DIR wraps a stat'able posix-dirent
zzip_file_real check if ZZIP_FILE wraps a stat'able posix-file
zzip_realdir if zzip_dir_real then return the posix-dirent
zzip_realfd if zzip_file_real then return the posix-file
zzip_dirhandle the attached ZZIP_DIR of compressed ZZIP_FILE
zzip_dirfd the attached posix-file of ZZIP_DIR zip-file
zzip_set_error set the last ZZIP_DIR error-code
zzip_error get the last ZZIP_DIR error-code
zzip_strerror convert a zzip_error into a readable string
zzip_strerror_of combine both above zzip_strerror of zzip_error
zzip_errno helper to wrap a zzip-error to a posix-errno
zzip_compr_str helper to wrap a compr-number to a readable string -
zzip_dir_free internally called by zzip_dir_close if the ref-count - of the ZZIP_DIR has gone zero
zzip_freopen to reuse the ZZIP_DIR from another ZZIP_FILE so it does - not need to be parsed again
zzip_open_shared_io the ext/io cousin but it does not close the old ZZIP_FILE - and instead just shares the ZZIP_DIR if possible
- + The zzip library was orginally developped by Tomi Ollila as a + set of zip decoder routines. Guido Draheim did pick it up and + wrapped them under a call synopsis matching their posix + api calls. Therefore zzip_open() has the same + synopsis as open(2) but it can open zipped files. + Later the distinction was made between magic wrappers and apis + for direct access to zip archives and the files contained + in the archive. +

+

+ These (three) functional apis have little helper functions + alongside including those to get the posix filehandle out of a + zzip handle and to get some attributes about the data handle + represented by a zzip handle. Plus checking for error codes + that may have been generated from internal checks. +

+ +
+
Basics
+
Magic Wrappers, Zip Archive Dir access, Zipped File access
+
Extras
+
ext/io init, StdC calls, Error defs, ReOpen, FileStat
+
diff --git a/docs/zzip-basics.htm b/docs/zzip-basics.htm new file mode 100644 index 0000000..d6364e9 --- /dev/null +++ b/docs/zzip-basics.htm @@ -0,0 +1,160 @@ +

ZZIP API Basics

The open/close API description. + + 20. July 2002 + +

Basics

+ +

+ The naming schem of functions in this library follow a simple rule: + if you see a function with a zzip_ prefix followed by + compact name representing otherwise a C library or posix function then + it is a magic wrapper that can automagically handle both real + files/directories or zip-contained files. This includes: +

+
+ + + + + + +
zzip_opendir opendir
zzip_readdir readdir
zzip_closedir closedir
zzip_rewinddir rewinddir
zzip_telldir telldir
zzip_seekdir seekdir
+

+ The ZZIP_DIR handle can wrap both a real directory or a zip-file. + Note that you can not open a virtual directory within a + zip-file, the ZZIP_DIR is either a real DIR-handle of a real + directory or the reference of ZIP-file but never a DIR-handle + within a ZIP-file - there is no such schema of a SUB-DIR handle + implemented in this library. A ZZIP_DIR does actually represent + the central directory of a ZIP-file, so that each file entry in + this ZZIP-DIR can possibly have a subpath prepended. +

+ +

+ This form of magic has historic reasons as originally the + magic wrappers of this library were not meant to wrap a complete + subtree of a real file tree but only a single directory being + wrapped with into a zip-file and placed instead. Later proposals + and patches were coming in to support subtree wrapping by not + only making a split between the dir-part and file-part but + going recursivly up through all "/"-dirseparators of a filepath + given to zzip_open and looking for zip-file there. +

+ +

+ To open a zip-file unconditionally one should be using their + respective methods that would return a ZZIP_DIR handle being + the representant memory instance of a ZIP-DIR, the central + directory of a zip-file. From that ZZIP-DIR one can open a + compressed file entry which will be returned as a ZZIP_FILE + pointer. +

+
+ + + + + + + + +
zzip_dir_open open a zip-file and parse the central directory + to a memory shadow
zzip_dir_close close a zip-file and free the memory shadow
zzip_dir_fdopen aquire the given posix-file and try to parse it + as a zip-file.
zzip_dir_read return the next info entry of a zip-file's central + directory - this would include a possible subpath
+ +

+ To unconditionally access a zipped-file (as the counter-part of a + zip-file's directory) you should be using the functions having a + zzip_file_ prefix which are the methods working on + ZZIP_FILE pointers directly and assuming those are references of + a zipped file with a ZZIP_DIR. +

+
+ + + + + + +
zzip_file_open open a file within a zip and prepare a zlib + compressor for it - note the ZZIP_DIR argument, + multiple ZZIP_FILE's may share the same central + directory shadow.
zzip_file_close close the handle of zippedfile + and free zlib compressor of it
zzip_file_read decompress the next part of a compressed file + within a zip-file
+

+ From here it is only a short step to the magic wrappers for + file-access - when being given a filepath to zzip_open then + the filepath is checked first for being possibly a real file + (we can often do that by a stat call) and if there is + a real file under that name then the returned ZZIP_FILE is + nothing more than a wrapper around a file-descriptor of the + underlying operating system. Any other calls like zzip_read + will see the realfd-flag in the ZZIP_FILE and forward the + execution to the read() function of the underlying operating system. +

+ +

+ However if that fails then the filepath is cut at last directory + separator, i.e. a filepath of "this/test/README" is cut into the + dir-part "this/test" and a file-part "README". Then the possible + zip-extensions are attached (".zip" and ".ZIP") and we check if + there is a real file under that name. If a file "this/test.zip" + does exist then it is given to zzip_dir_open which will create + a ZZIP_DIR instance of it, and when that was successul (so it + was in zip-format) then we call zzip_file_open which will see + two arguments - the just opened ZZIP_DIR and the file-part. The + resulting ZZIP_FILE has its own copy of a ZZIP_DIR, so if you + open multiple files from the same zip-file than you will also + have multiple in-memory copies of the zip's central directory + whereas otherwise multiple ZZIP_FILE's may share a common + ZZIP_DIR when being opened with zzip_file_open directly - the + zzip_file_open's first argument is the ZZIP_DIR and the second + one the file-part to be looked up within that zip-directory. +

+ +
+ + + + + + +
zzip_open try the file-path as a real-file, and if not + there, look for the existance of ZZIP_DIR by + applying extensions, and open the file + contained within that one.
zzip_close if the ZZIP_FILE wraps a real-file, then call + read(), otherwise call zzip_file_read()
zzip_close if the ZZIP_FILE wraps a real-file, then call + close(), otherwise call zzip_file_close()
+ +

+ Up to here we have the original functionality of the zziplib + when I (Guido Draheim) created the magic functions around the work from + Tomi Ollila who wrote the routines to read and decompress files from + a zip archive - unlike other libraries it was quite readable and + intelligible source code (after many changes there is not much + left of the original zip08x source code but that's another story). + Later however some request and proposals and patches were coming in. +

+ +

+ Among the first extensions was the recursive zzip_open magic. In + the first instance, the library did just do as described above: + a file-path of "this/test/README" might be a zip-file known as + "this/test.zip" containing a compressed file "README". But if + there is neither a real file "this/test/README" and no real + zip-file "this/test.zip" then the call would have failed but + know the zzip_open call will recursivly check the parent + directories - so it can now find a zip-file "this.zip" which + contains a file-part "test/README". +

+ +

+ This dissolves the original meaning of a ZZIP_DIR and it has lead + to some confusion later on - you can not create a DIRENT-like handle + for "this/test/" being within a "test.zip" file. And actually, I did + never see a reason to implement it so far (open "this.zip" and set + an initial subpath of "test" and let zzip_readdir skip all entries + that do not start with "test/"). This is left for excercie ;-) +

diff --git a/docs/zzip-extras.htm b/docs/zzip-extras.htm new file mode 100644 index 0000000..14e5dcf --- /dev/null +++ b/docs/zzip-extras.htm @@ -0,0 +1,161 @@ +

ZZIP API extras

The check/init API description. + + 20. July 2002 + +

Extras

+ +

+ The next requests circulated around other file-extensions to + automagically look inside filetypes that have zip-format too but + carry other fileextensions - most famous might be the ".PK3" + files of ID's Quake game. There have been a number of these + requests and in a lot of cases it dawned to me that those guys + may have overlooked the zzip_dir_open functions to travel + through documents of zipformat under any name - that is that the + "magic" was not actually needed but they just wanted to read + files in zipformat with the zziplib. +

+ +

+ Other requests circulated around encryption but I did reject + those bluntly, always. Instead there have been always examples + for doing some obfuscation around the zip-format so that the + stock zip/unzip tools do not recognize them but a game + software developer can pack/unpack his AI scripts and bitmaps + into such a zipformat-like file. +

+ +

+ After some dead-end patches (being shipped along with the + zziplib as configure-time compile-options - greetings to + Lutz Sammer and Andreas Schiffler), the general approach + of _ext_io came up, and finally implemented (greetings go + to Mike Nordell). The _open()-calls do now each have a + cousin of _open_ext_io() with two/three additional arguments + being a set of extensions to loop through our magic testing, + a callback-handler plugin-table for obfuscation-means, + and (often) a bit-mask for extra-options - this bitmask even + has "PREFERZIP" and "ONLYZIP" options to skip the real-file + test magic in those zzip_*open functions. +

+ +
+ + + + + + + + + + +
zzip_open(name,flags) zzip_open_ext_io(name,flags,mode,ext,io)
zzip_opendir(name) zzip_opendir_ext_io(name,mode,ext,io)
zzip_dir_open(name,errp) zzip_dir_open_ext_io(name,errp,ext,io)
zzip_dir_fdopen(fd,errp) zzip_dir_fdopen_ext_io(fd,errp,ext,io)
zzip_file_open(dir,name,mode) zzip_file_open_ext_io(dir,name,mode,ext,io)
+ +

+ Oh, and note that the mode,ext,io extras are memorized + in the respecitive ZZIP_DIR handle attached, so each + of the other calls like zzip_file_open() + and zzip_read() will be using them. There + are a few helper routines to help setup a new io-plugin + where the init_io will currently just memcopy the + default_io entries into the user-supplied plugin-struct. +

+ +
+ + + + + + +
zzip_init_io the recommended way to do things
zzip_get_default_io used internally whenever you supply a null + for the io-argument of a _ext_io()-call
zzip_get_default_ext used internally but not exported
+ + +

+ And last some stdio-like replacements were build but these + happen to be actually just small wrappers around the other + posix-like magic-calls. It just offers some convenience + since wrappers like "SDL_rwops" tend to use a stringised + open-mode - and I took the occasion to fold the zzip-bits + for the _ext_io-calls right in there recognized via + special extensions to the openmode-string of zzip_fopen(). +

+ +
+ + + + + + +
zzip_fopen convert stringmode and call zzip_open_ext_io
zzip_fread slower way to say zzip_read
zzip_fclose a synonym of zzip_close
+ +

+ For some reason, people did need the full set of function-calls() + to be working on zzip-wrappers too, so here they are - if the + ZZIP_FILE instance did wrap a real file, then the real posix-call + will be used, otherwise it is simulated on the compressed stream + with a zip-contained file - especially seek() can be + a slow operation: + if the new point is later then just read out more bytes till we + hit that position but if it is an earlier point then rewind to the + beginning of the compressed data and start reading/decompression + until the position is met. +

+ +
+ + + + + + +
zzip_rewind magic for rewind()
zzip_tell magic for tell()
zzip_seek magic for seek()
+ +

+ And last not least, there are few informative functions to + use function-calls to read parts of the opaque structures + of zzip-objects and their zzip-factory. +

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
zzip_dir_stat a stat()-like thing on a file within a ZZIP_DIR
zzip_dir_real check if ZZIP_DIR wraps a stat'able posix-dirent
zzip_file_real check if ZZIP_FILE wraps a stat'able posix-file
zzip_realdir if zzip_dir_real then return the posix-dirent
zzip_realfd if zzip_file_real then return the posix-file
zzip_dirhandle the attached ZZIP_DIR of compressed ZZIP_FILE
zzip_dirfd the attached posix-file of ZZIP_DIR zip-file
zzip_set_error set the last ZZIP_DIR error-code
zzip_error get the last ZZIP_DIR error-code
zzip_strerror convert a zzip_error into a readable string
zzip_strerror_of combine both above zzip_strerror of zzip_error
zzip_errno helper to wrap a zzip-error to a posix-errno
zzip_compr_str helper to wrap a compr-number to a readable string +
zzip_dir_free internally called by zzip_dir_close if the ref-count + of the ZZIP_DIR has gone zero
zzip_freopen to reuse the ZZIP_DIR from another ZZIP_FILE so it does + not need to be parsed again
zzip_open_shared_io the ext/io cousin but it does not close the old ZZIP_FILE + and instead just shares the ZZIP_DIR if possible
+ diff --git a/zzip/zzip.h b/zzip/zzip.h index 6b46fae..e69f03a 100644 --- a/zzip/zzip.h +++ b/zzip/zzip.h @@ -3,7 +3,7 @@ * Guido Draheim * Tomi Ollila * - * Copyright (c) 1999,2000,2001,2002,2003 Guido Draheim + * Copyright (c) 1999,2000,2001,2002,2003,2004 Guido Draheim * All rights reserved, * usage allowed under the restrictions of the * Lesser GNU General Public License @@ -171,7 +171,7 @@ void zzip_seekdir(ZZIP_DIR * dir, zzip_off_t offset); * zzip/file.c */ _zzip_export -ZZIP_FILE * zzip_file_open(ZZIP_DIR * dir, zzip_char_t* name, int modes); +ZZIP_FILE * zzip_file_open(ZZIP_DIR * dir, zzip_char_t* name, int flags); _zzip_export int zzip_file_close(ZZIP_FILE * fp); _zzip_export @@ -247,16 +247,13 @@ _zzip_export ZZIP_DIR * zzip_opendir_ext_io(zzip_char_t* name, int o_modes, zzip_strings_t* ext, zzip_plugin_io_t io); -_zzip_export -ZZIP_FILE * zzip_file_open_ext_io(ZZIP_DIR * dir, - zzip_char_t* name, int flags, - zzip_strings_t* ext, zzip_plugin_io_t io); - _zzip_export ZZIP_DIR * zzip_dir_open_ext_io(zzip_char_t* filename, zzip_error_t* errcode_p, zzip_strings_t* ext, zzip_plugin_io_t io); +/* zzip_file_open_ext_io => zzip_dir_open_ext_io + zzip_file_open */ + #if defined _ZZIP_WRITE_SOURCE /* ........................................................................ * write support is not yet implemented diff --git a/zziplib.spec b/zziplib.spec index b5fd70f..1285dd8 100644 --- a/zziplib.spec +++ b/zziplib.spec @@ -1,7 +1,7 @@ %define lib lib010 Summary: ZZipLib - libZ-based ZIP-access Library Name: zziplib -Version: 0.13.34 +Version: 0.13.35 Release: 1mdk Serial: 1 Copyright: LGPL -- 2.40.0