zziplib - 0.13.38

uint32_t
__zzip_get32 (unsigned char * s)
uint16_t
__zzip_get16 (unsigned char * s)
void
__zzip_set32 (unsigned char * s, uint32_t v)
void
__zzip_set16 (unsigned char * s, uint16_t v)

The __zzip_find_disk_trailer function is used by zzip_file_open. It tries to find
the zip's central directory info that is usually a few
bytes off the end of the file.

(../zzip/zip.c)

(zzip/fetch.c)

Make 32 bit value in host byteorder from little-endian mapped octet-data
(works also on machines which SIGBUS on misaligned data access (eg. 68000))

The __zzip_get16 function does the same for a 16 bit value.

The __zzip_set32 function pushes a 32bit value at the specified address

The __zzip_set16 function does the same for a 16 bit value.

(../zzip/fetch.c)

int
__zzip_parse_root_directory (int fd, struct zzip_disk_trailer * trailer, struct zzip_dir_hdr ** hdr_return, zzip_plugin_io_t io)

int
__zzip_try_open (zzip_char_t* filename, int filemode, zzip_strings_t* ext, zzip_plugin_io_t io)

The __zzip_parse_root_directory function is used by zzip_file_open, it is usually called after
__zzip_find_disk_trailer. It will parse the zip's central directory
information and create a zziplib private directory table in
memory.

(../zzip/zip.c)

will attach a .zip extension and tries to open it
the with open(2). This is a helper function for
zzip_dir_open, zzip_opendir and zzip_open.

(../zzip/zip.c)

int
zzip_closedir (ZZIP_DIR* dir)

zzip_char_t*
zzip_compr_str (int compr)

The zzip_closedir function is the equivalent of closedir(3) for a realdir or zipfile.

The zzip_closedir function is magic - if the given arg-ZZIP_DIR
is a real directory, it will call the real closedir(3) and then
free the wrapping ZZIP_DIR structure. Otherwise it will divert
to zzip_dir_close which will free the ZZIP_DIR structure.

(../zzip/dir.c)

ZZIP_DIR*
zzip_createdir (zzip_char_t* name, int o_mode)

return static const string of the known compression methods,
otherwise just "zipped" is returned

(../zzip/info.c)

create a new archive area for writing

The zzip_createdir function will create a new archive area. This may either be a
a new zip archive or a new directory in the filesystem. The returned
parameter is a new "zzip dir" handle that should be saved to a variable
so it can be used a base argument for zzip_file_mkdir and
zzip_file_creat calls. The returned handle wraps both possibilities,
it can be representing a zip central directory that must be
saved to disk using zzip_closedir or it is just a handle for the
name of the real directory that still must be run through
zzip_closedir to release the wrapper around the directory name.

The magic is pushed through the o_mode argument. Using a mode that
has no group-write bit set (S_IWGRP = 0040) then the file is
created as a zip directory. Note that this is unabridged of any
umask value in the system where the argument to the zzip_createdir function could
be 0775 but with an umask of 0755 it turns out as 0755 for a real
directory. Using 0755 directly would not create it as a real directory
but as a zip archive handle.

The zzip_createdir function is not yet implemented, check for #def ZZIP_NO_CREAT
Write-support will extend zzip_closedir with semantics to finalize the
zip-archive by writing the zip-trailer and closing the archive file.

Returns null on error and sets errno. Remember, according to posix
the creat(2) call is equivalent to

  open (path, O_WRONLY | O_CREAT | O_TRUNC, o_mode)

so any previous zip-archive will be overwritten unconditionally and
EEXIST errors from mkdir(2) are suppressed. (fixme: delete the
given subtree? like suggested by O_TRUNC? not done so far!)

(../zzip/write.c)

ZZIP_DIR*
zzip_dir_alloc_ext_io (zzip_strings_t* ext, const zzip_plugin_io_t io)
ZZIP_DIR*
zzip_dir_alloc (zzip_strings_t* fileext)

ZZIP_DIR*
zzip_dir_creat (zzip_char_t* name, int o_mode)
ZZIP_DIR*
zzip_dir_creat_ext_io (zzip_char_t* name, int o_mode, zzip_strings_t* ext, zzip_plugin_io_t io)

allocate a new ZZIP_DIR handle and do basic
initializations before usage by zzip_dir_fdopen
zzip_dir_open zzip_file_open or through
zzip_open
(ext==null flags uses { ".zip" , ".ZIP" } )
(io ==null flags use of posix io defaults)

the zzip_dir_alloc function is obsolete - it was generally used for implementation
and exported to let other code build on it. It is now advised to
use zzip_dir_alloc_ext_io now on explicitly, just set that second
argument to zero to achieve the same functionality as the old style.

(../zzip/zip.c)

create a new zip archive for writing

The zzip_dir_creat function will create a new zip archive. The returned parameter
is a new "zzip dir" handle that should be saved to a variable so it
can be used a base argument for zzip_mkdir and zzip_creat calls.
The returned handle represents a zip central directory that must be
saved to disk using zzip_closedir.

Returns null on error and sets errno. Remember, according to posix
the creat(2) call is equivalent to

  open (path, O_WRONLY | O_CREAT | O_TRUNC, o_mode)

so any previous zip-archive will be overwritten unconditionally and
EEXIST errors from mkdir(2) are suppressed. (fixme: delete the
given subtree? like suggested by O_TRUNC? not done so far!)

If the third argument "ext" has another special meaning here, as it
is used to ensure that a given zip-file is created with the first entry
of the ext-list appended as an extension unless the file-path already
ends with a file-extension registered in the list. Therefore {"",0}
matches all files and creates them as zip-archives under the given
nonmodified name. (Some magic here? If the path ends in the path
separator then make a real directory even in the presence of ext-list?)

The zzip_dir_creat_ext_io function is not yet implemented, check for #def ZZIP_NO_CREAT
Write-support will extend zzip_closedir with semantics to finalize the
zip-archive by writing the zip-trailer and closing the archive file.

(../zzip/write.c)

ZZIP_DIR *
zzip_dir_fdopen (int fd, zzip_error_t * errcode_p)
ZZIP_DIR *
zzip_dir_fdopen_ext_io (int fd, zzip_error_t * errcode_p, zzip_strings_t* ext, const zzip_plugin_io_t io)

int
zzip_dir_free (ZZIP_DIR * dir)
int
zzip_dir_close (ZZIP_DIR * dir)

used by the zzip_dir_open and zzip_opendir(2) call. Opens the
zip-archive as specified with the fd which points to an
already openend file. The zzip_dir_fdopen function then search and parse
the zip's central directory.

NOTE: refcount is zero, so an _open/_close pair will also delete
this _dirhandle

the zzip_dir_fdopen_ext_io function uses explicit ext and io instead of the internal
defaults, setting these to zero is equivalent to zzip_dir_fdopen

(../zzip/zip.c)

ZZIP_DIR*
zzip_dir_open (zzip_char_t* filename, zzip_error_t* e)
ZZIP_DIR*
zzip_dir_open_ext_io (zzip_char_t* filename, zzip_error_t* e, zzip_strings_t* ext, zzip_plugin_io_t io)
int
zzip_dir_read (ZZIP_DIR * dir, ZZIP_DIRENT * d )

will free the zzip_dir handle unless there are still
zzip_files attached (that may use its cache buffer).
This is the inverse of zzip_dir_alloc , and both
are helper functions used implicitly in other zzipcalls
e.g. zzip_dir_close = zzip_close

returns zero on sucess
returns the refcount when files are attached.

zzip_dir_close -
It will also free(2) the ZZIP_DIR-handle given.
the counterpart for zzip_dir_open
see also zzip_dir_free

(../zzip/zip.c)

the zzip_dir_open_ext_io function uses explicit ext and io instead of the internal
defaults. Setting these to zero is equivalent to zzip_dir_open

Opens the zip-archive (if available).
the two ext_io arguments will default to use posix io and
a set of default fileext that can atleast add .zip ext itself.

zzip_dir_read -
fills the dirent-argument with the values and
increments the read-pointer of the dir-argument.

returns 0 if there no entry (anymore).

(../zzip/zip.c)

int
zzip_dir_stat (ZZIP_DIR * dir, zzip_char_t* name, ZZIP_STAT * zs, int flags)
int
zzip_file_stat (ZZIP_FILE* file, ZZIP_STAT* zs)
int
zzip_fstat (ZZIP_FILE* file, ZZIP_STAT* zs)

(zzip/stat.c)

obtain information about a filename in an opened zip-archive without
opening that file first. Mostly used to obtain the uncompressed
size of a file inside a zip-archive. see zzip_dir_open.

The zzip_file_stat function will obtain information about a opened file _within_ a
zip-archive. The file is supposed to be open (otherwise -1 is returned).
The st_size stat-member contains the uncompressed size. The optional
d_name is never set here.

The zzip_fstat function will obtain information about a opened file which may be
either real/zipped. The file is supposed to be open (otherwise -1 is
returned). The st_size stat-member contains the uncompressed size.
The optional d_name is never set here. For a real file, we do set the
d_csize := st_size and d_compr := 0 for meaningful defaults.

(../zzip/stat.c)

ZZIP_DIR *
zzip_dirhandle (ZZIP_FILE * fp)
int
zzip_dirfd (ZZIP_DIR* dir)

char*
zzip_disk_entry_to_data (ZZIP_DISK* disk, struct zzip_disk_entry* entry)
struct zzip_file_header*
zzip_disk_entry_to_file_header (ZZIP_DISK* disk, struct zzip_disk_entry* entry)
char* _zzip_restrict
zzip_disk_entry_strdup_name (ZZIP_DISK* disk, struct zzip_disk_entry* entry)

The zzip_dirhandle function will just return fp->dir

If a ZZIP_FILE is contained within a zip-file that one will be a valid
pointer, otherwise a NULL is returned and the ZZIP_FILE wraps a real file.

The zzip_dirfd function will just return dir->fd

If a ZZIP_DIR does point to a zipfile then the file-descriptor of that
zipfile is returned, otherwise a NULL is returned and the ZZIP_DIR wraps
a real directory DIR (if you have dirent on your system).

(../zzip/info.c)

helper functions for (mmapped) zip access api

The zzip_disk_entry_to_data function augments the other zzip_disk_entry_* helpers: here we move
a disk_entry pointer (as returned by _find* functions) into a pointer to
the data block right after the file_header. Only disk->buffer would be
needed to perform the seek but we check the mmapped range end as well.

The zzip_disk_entry_to_file_header function does half the job of zzip_disk_entry_to_data where it
can augment with zzip_file_header_to_data helper from format/fetch.h

The zzip_disk_entry_strdup_name function is a big helper despite its little name: in a zip file the
encoded filenames are usually NOT zero-terminated but for common usage
with libc we need it that way. Secondly, the filename SHOULD be present
in the zip central directory but if not then we fallback to the filename
given in the file_header of each compressed data portion.

(../zzip/mmapped.c)

struct zzip_disk_entry*
zzip_disk_findfile (ZZIP_DISK* disk, char* filename, struct zzip_disk_entry* after, zzip_strcmp_fn_t compare)
struct zzip_disk_entry*
zzip_disk_findfirst (ZZIP_DISK* disk)
struct zzip_disk_entry*
zzip_disk_findnext (ZZIP_DISK* disk, struct zzip_disk_entry* entry)
struct zzip_disk_entry*
zzip_disk_findmatch (ZZIP_DISK* disk, char* filespec, struct zzip_disk_entry* after, zzip_fnmatch_fn_t compare, int flags)

search for files in the (mmapped) zip central directory

The zzip_disk_findfile function is given a filename as an additional argument, to find the
disk_entry matching a given filename. The compare-function is usually
strcmp or strcasecmp or perhaps strcoll, if null then strcmp is used.
- use null as argument for "after"-entry when searching the first
matching entry, otherwise the last returned value if you look for other
entries with a special "compare" function (if null then a doubled search
is rather useless with this variant of _findfile).

The zzip_disk_findfirst function is the first call of all the zip access functions here.
It contains the code to find the first entry of the zip central directory.
Here we require the mmapped block to represent a real zip file where the
disk_trailer is _last_ in the file area, so that its position would be at
a fixed offset from the end of the file area if not for the comment field
allowed to be of variable length (which needs us to do a little search
for the disk_tailer). However, in this simple implementation we disregard
any disk_trailer info telling about multidisk archives, so we just return
a pointer to the zip central directory.

For an actual means, we are going to search backwards from the end
of the mmaped block looking for the PK-magic signature of a
disk_trailer. If we see one then we check the rootseek value to
find the first disk_entry of the root central directory. If we find
the correct PK-magic signature of a disk_entry over there then we
assume we are done and we are going to return a pointer to that label.

The return value is a pointer to the first zzip_disk_entry being checked
to be within the bounds of the file area specified by the arguments. If
no disk_trailer was found then null is returned, and likewise we only
accept a disk_trailer with a seekvalue that points to a disk_entry and
both parts have valid PK-magic parts. Beyond some sanity check we try to
catch a common brokeness with zip archives that still allows us to find
the start of the zip central directory.

The zzip_disk_findnext function takes an existing disk_entry in the central root directory
(e.g. from zzip_disk_findfirst) and returns the next entry within in
the given bounds of the mmapped file area.

The zzip_disk_findmatch function uses a compare-function with an additional argument
and it is called just like fnmatch(3) from POSIX.2 AD:1993), i.e.
the argument filespec first and the ziplocal filename second with
the integer-flags put in as third to the indirect call. If the
platform has fnmatch available then null-compare will use that one
and otherwise we fall back to mere strcmp, so if you need fnmatch
searching then please provide an implementation somewhere else.
- use null as argument for "after"-entry when searching the first
matching entry, or the last disk_entry return-value to find the
next entry matching the given filespec.

(../zzip/mmapped.c)

ZZIP_DISK_FILE* _zzip_restrict
zzip_disk_fopen (ZZIP_DISK* disk, char* filename)
ZZIP_DISK_FILE* _zzip_restrict
zzip_disk_entry_fopen (ZZIP_DISK* disk, ZZIP_DISK_ENTRY* entry)
zzip_size_t
zzip_disk_fread (void* ptr, zzip_size_t sized, zzip_size_t nmemb, ZZIP_DISK_FILE* file)
int
zzip_disk_fclose (ZZIP_DISK_FILE* file)
int
zzip_disk_feof (ZZIP_DISK_FILE* file)

openening a file part wrapped within a (mmapped) zip archive

The zzip_disk_fopen function opens a file found by name, so it does a search into
the zip central directory with zzip_disk_findfile and whatever
is found first is given to zzip_disk_entry_fopen

the ZZIP_DISK_FILE* is rather simple in just encapsulating the
arguments given to the zzip_disk_entry_fopen function plus a zlib deflate buffer.
Note that the ZZIP_DISK pointer does already contain the full
mmapped file area of a zip disk, so open()ing a file part within
that area happens to be a lookup of its bounds and encoding. That
information is memorized on the ZZIP_DISK_FILE so that subsequent
_read() operations will be able to get the next data portion or
return an eof condition for that file part wrapped in the zip archive.

The zzip_disk_fread function reads more bytes into the output buffer specified as
arguments. The return value is null on eof or error, the stdio-like
interface can not distinguish between these so you need to check
with zzip_disk_feof for the difference.

The zzip_disk_fclose function releases any zlib decoder info needed for decompression
and dumps the ZZIP_DISK_FILE* then.

The zzip_disk_feof function allows to distinguish an error from an eof condition.
Actually, if we found an error but we did already reach eof then we
just keep on saying that it was an eof, so the app can just continue.

(../zzip/mmapped.c)

ZZIP_DISK* _zzip_restrict
zzip_disk_mmap (int fd)
int
zzip_disk_init (ZZIP_DISK* disk, char* buffer, zzip_size_t buflen)
ZZIP_DISK* _zzip_restrict
zzip_disk_new (void)
int
zzip_disk_munmap (ZZIP_DISK* disk)
ZZIP_DISK* _zzip_restrict
zzip_disk_open (char* filename)
int
zzip_disk_close (ZZIP_DISK* disk)

turn a filehandle into a mmapped zip disk archive handle

The zzip_disk_mmap function uses the given file-descriptor to detect the length of the
file and calls the system mmap(2) to put it in main memory. If it is
successful then a newly allocated ZZIP_DISK* is returned with
disk->buffer pointing to the mapview of the zipdisk content.

The zzip_disk_init function does primary initialization of a disk-buffer struct.

The zzip_disk_new function allocates a new disk-buffer with malloc(3)

The zzip_disk_munmap function is the inverse of zzip_disk_mmap and using the system
munmap(2) on the buffer area and free(3) on the ZZIP_DISK structure.

The zzip_disk_open function opens the given archive by name and turn the filehandle
to zzip_disk_mmap for bringing it to main memory. If it can not
be mmap(2)'ed then we slurp the whole file into a newly malloc(2)'ed
memory block. Only if that fails too then we return null. Since handling
of disk->buffer is ambigous it should not be snatched away please.

The zzip_disk_close function will release all data needed to access a (mmapped)
zip archive, including any malloc()ed blocks, sharedmem mappings
and it dumps the handle struct as well.

(../zzip/mmapped.c)

zzip_off_t
zzip_entry_data_offset (ZZIP_ENTRY* entry)
static zzip_off_t
zzip_entry_fread_file_header (ZZIP_ENTRY* entry, struct zzip_file_header* file_header)
char* _zzip_restrict
zzip_entry_strdup_name (ZZIP_ENTRY* entry)

helper functions for (fseeko) zip access api

The zzip_entry_data_offset functions returns the seekval offset of the data portion of the
file referenced by the given zzip_entry. It requires an intermediate
check of the file_header structure (i.e. it reads it from disk). After
this call, the contained diskfile readposition is already set to the
data_offset returned here. On error -1 is returned.

The zzip_entry_fread_file_header functions read the correspoding struct zzip_file_header from
the zip disk of the given "entry". The returned off_t points to the
end of the file_header where the current fseek pointer has stopped.
This is used to immediatly parse out any filename/extras block following
the file_header. The return value is null on error.

The zzip_entry_strdup_name function is a big helper despite its little name: in a zip file the
encoded filenames are usually NOT zero-terminated but for common usage
with libc we need it that way. Secondly, the filename SHOULD be present
in the zip central directory but if not then we fallback to the filename
given in the file_header of each compressed data portion.

(../zzip/fseeko.c)

ZZIP_ENTRY* _zzip_restrict
zzip_entry_findfile (FILE* disk, char* filename, ZZIP_ENTRY* _zzip_restrict entry, zzip_strcmp_fn_t compare)
ZZIP_ENTRY* _zzip_restrict
zzip_entry_findfirst (FILE* disk)
ZZIP_ENTRY* _zzip_restrict
zzip_entry_findnext (ZZIP_ENTRY* _zzip_restrict entry)
int
zzip_entry_free (ZZIP_ENTRY* entry)
ZZIP_ENTRY* _zzip_restrict
zzip_entry_findmatch (FILE* disk, char* filespec, ZZIP_ENTRY* _zzip_restrict entry, zzip_fnmatch_fn_t compare, int flags)

search for files in the (fseeko) zip central directory

The zzip_entry_findfile function is given a filename as an additional argument, to find the
disk_entry matching a given filename. The compare-function is usually
strcmp or strcasecmp or perhaps strcoll, if null then strcmp is used.
- use null as argument for "old"-entry when searching the first
matching entry, otherwise the last returned value if you look for other
entries with a special "compare" function (if null then a doubled search
is rather useless with this variant of _findfile). If no further entry is
found then null is returned and any "old"-entry gets already free()d.

The zzip_entry_findfirst function is the first call of all the zip access functions here.
It contains the code to find the first entry of the zip central directory.
Here we require the stdio handle to represent a real zip file where the
disk_trailer is _last_ in the file area, so that its position would be at
a fixed offset from the end of the file area if not for the comment field
allowed to be of variable length (which needs us to do a little search
for the disk_tailer). However, in this simple implementation we disregard
any disk_trailer info telling about multidisk archives, so we just return
a pointer to the first entry in the zip central directory of that file.

The zzip_entry_findnext function takes an existing "entry" in the central root directory
(e.g. from zzip_entry_findfirst) and moves it to point to the next entry.
On error it returns 0, otherwise the old entry. If no further match is
found then null is returned and the entry already free()d. If you want
to stop searching for matches before that case then please call
zzip_entry_free on the cursor struct ZZIP_ENTRY.

the zzip_entry_free function releases the malloc()ed areas needed for zzip_entry, the
pointer is invalid afterwards. The zzip_entry_free function has #define synonyms of
zzip_entry_findlast(), zzip_entry_findlastfile(), zzip_entry_findlastmatch()

The zzip_entry_findmatch function uses a compare-function with an additional argument
and it is called just like fnmatch(3) from POSIX.2 AD:1993), i.e.
the argument filespec first and the ziplocal filename second with
the integer-flags put in as third to the indirect call. If the
platform has fnmatch available then null-compare will use that one
and otherwise we fall back to mere strcmp, so if you need fnmatch
searching then please provide an implementation somewhere else.
- use null as argument for "after"-entry when searching the first
matching entry, or the last disk_entry return-value to find the
next entry matching the given filespec. If no further entry is
found then null is returned and any "old"-entry gets already free()d.

(../zzip/fseeko.c)

ZZIP_ENTRY_FILE* _zzip_restrict
zzip_entry_fopen (ZZIP_ENTRY* entry, int takeover)
ZZIP_ENTRY_FILE* _zzip_restrict
zzip_entry_ffile (FILE* disk, char* filename)
zzip_size_t
zzip_entry_fread (void* ptr, zzip_size_t sized, zzip_size_t nmemb, ZZIP_ENTRY_FILE* file)
int
zzip_entry_fclose (ZZIP_ENTRY_FILE* file)
int
zzip_entry_feof (ZZIP_ENTRY_FILE* file)

open a file within a zip disk for reading

The zzip_entry_fopen function does take an "entry" argument and copies it (or just takes
it over as owner) to a new ZZIP_ENTRY_FILE handle structure. That
structure contains also a zlib buffer for decoding. The zzip_entry_fopen function does
seek to the file_header of the given "entry" and validates it for the
data buffer following it. We do also prefetch some data from the data
buffer thereby trying to match the disk pagesize for faster access later.
The zzip_entry_fread will then read in chunks of pagesizes which is
the size of the internal readahead buffer. If an error occurs then null
is returned.

The zzip_entry_ffile function opens a file found by name, so it does a search into
the zip central directory with zzip_entry_findfile and whatever
is found first is given to zzip_entry_fopen

The zzip_entry_fread function reads more bytes into the output buffer specified as
arguments. The return value is null on eof or error, the stdio-like
interface can not distinguish between these so you need to check
with zzip_entry_feof for the difference.

The zzip_entry_fclose function releases any zlib decoder info needed for decompression
and dumps the ZZIP_ENTRY_FILE struct then.

The zzip_entry_feof function allows to distinguish an error from an eof condition.
Actually, if we found an error but we did already reach eof then we
just keep on saying that it was an eof, so the app can just continue.

(../zzip/fseeko.c)

int
zzip_errno (int errcode)

(zzip/err.c)

map the error code to a system error code. This is used
for the drop-in replacement functions to return a value
that can be interpreted correctly by code sections that
are unaware of the fact they their open(2) call had been
diverted to a file inside a zip-archive.

(../zzip/err.c)

int
zzip_error (ZZIP_DIR * dir)
void
zzip_seterror (ZZIP_DIR * dir, int errcode)

int
zzip_fclose (ZZIP_FILE * fp)
int
zzip_close (ZZIP_FILE* fp)

just returns dir->errcode of the ZZIP_DIR handle
see: zzip_dir_open, zzip_diropen, zzip_readdir, zzip_dir_read

The zzip_seterror function just does dir->errcode = errcode

(../zzip/info.c)

int
zzip_file_close (ZZIP_FILE * fp)

The zzip_fclose function closes the given ZZIP_FILE handle.

If the ZZIP_FILE wraps a normal stat'fd then it is just that int'fd
that is being closed and the otherwise empty ZZIP_FILE gets freed.

zzip_close -

(../zzip/file.c)

ZZIP_FILE*
zzip_file_creat (ZZIP_DIR* dir, zzip_char_t* name, int o_mode)
int
zzip_file_mkdir (ZZIP_DIR* dir, zzip_char_t* name, int o_mode)

the direct function of zzip_close(fp). it will cleanup the
inflate-portion of zlib and free the structure given.

it is called quite from the error-cleanup parts
of the various _open functions.

the .refcount is decreased and if zero the fp->dir is closed just as well.

(../zzip/file.c)

start next file entry in a zip archive

The zzip_file_creat function will create a new file within a zzip archive, the
one given as the primary argument and additionally to the posix
creat(2) - just like zzip_mkdir has an additional argument over
the posix mkdir(2) spec. For the zzip_file_creat function the primary parameter
can be null as well thereby creating a real file instead of a new
one inside the zip-archive otherwise given. If the primary parameter is
not null but wraps a real directory then all new files are also real.

The zzip_file_creat function is not yet implemented, check for #def ZZIP_NO_CREAT

Returns NULL on an error setting errno, and opening a file _within_
a zip archive using O_RDONLY (and similar stuff) will surely lead to
an error.

The zzip_file_mkdir function has an additional primary argument over the posix
mkdir(2) - if it is null then the zzip_file_mkdir function behaves just like
posix mkdir(2). The zzip_dir argument can be set to the result
of a zzip_createdir which allows for some magic that the
given directory name is created as an entry in the zip archive.

If the given dir name argument is not within the basepath of
the zip central directory then a real directory is created.
Any EEXIST errors are not suppressed unlike with zzip_createdir

Standard usage accepts a global/threaded/modular ZZIP_DIR pointer
for all zip archive operations like in:

  ZZIP_DIR* zip = zzip_createdir (sysconfpath, 0755, zip);  
   zzip_file_mkdir (zip, filepath[i], 0755);  
   ZZIP_FILE* file = zzip_file_creat (zip, filename[i], 0644);  
   zzip_write (file, buf, len);  
   zzip_close (file); file = 0;  
   zzip_closedir (zip); zip = 0;

compare with zzip_mkdir inline macro which allows to
collapse the examples script to

  #define zzip_savefile myproject_saveconfig  
   #include <zzip/zzip.h>  
   ZZIP_DIR* zzip_savefile = zzip_createdir (sysconfpath, 0755);  
   zzip_mkdir (filepath[i], 0755);  
   ZZIP_FILE* file = zzip_creat(filepath[i], 0644);  
   zzip_write (file, buf, len);  
   zzip_close (file); file = 0;  
   zzip_closedir (zip_savefile);

(../zzip/write.c)

ZZIP_FILE *
zzip_file_open (ZZIP_DIR * dir, zzip_char_t* name, int o_mode)

zzip_ssize_t
zzip_file_read (ZZIP_FILE * fp, char * buf, zzip_size_t len)

open an ZZIP_FILE from an already open ZZIP_DIR handle. Since
we have a chance to reuse a cached buf32k and ZZIP_FILE memchunk
this is the best choice to unpack multiple files.

Note: the zlib supports 2..15 bit windowsize, hence we provide a 32k
memchunk here... just to be safe.

(../zzip/file.c)

int
zzip_file_real (ZZIP_FILE* fp)
int
zzip_dir_real (ZZIP_DIR* dir)
void*
zzip_realdir (ZZIP_DIR* dir)
int
zzip_realfd (ZZIP_FILE* fp)

The zzip_file_read functions read data from zip-contained file.

It works like read(2) and will fill the given buffer with bytes from
the opened file. It will return the number of bytes read, so if the EOF
is encountered you will be prompted with the number of bytes actually read.

This is the routines that needs the buf32k buffer, and it would have
need for much more polishing but it does already work quite well.

Note: the 32K buffer is rather big. The original inflate-algorithm
required just that but the latest zlib would work just fine with
a smaller buffer.

(../zzip/file.c)

ZZIP_FILE*
zzip_fopen (zzip_char_t* filename, zzip_char_t* mode)
ZZIP_FILE*
zzip_freopen (zzip_char_t* filename, zzip_char_t* mode, ZZIP_FILE* stream)

The zzip_file_real function checks if the ZZIP_FILE-handle is wrapping
a real file or a zip-contained file.
Returns 1 for a stat'able file, and 0 for a file inside a zip-archive.

The zzip_dir_real function checks if the ZZIP_DIR-handle is wrapping
a real directory or a zip-archive.
Returns 1 for a stat'able directory, and 0 for a handle to zip-archive.

The zzip_realdir function returns the posix DIR* handle (if one exists).
Check before with zzip_dir_real if the
the ZZIP_DIR points to a real directory.

The zzip_realfd function returns the posix file descriptor (if one exists).
Check before with zzip_file_real if the
the ZZIP_FILE points to a real file.

(../zzip/info.c)

static int
zzip_inflate_init (ZZIP_FILE * fp, struct zzip_dir_hdr* hdr)

The zzip_fopen function will fopen(3) a real/zipped file.

It has some magic functionality builtin - it will first try to open
the given filename as a normal file. If it does not
exist, the given path to the filename (if any) is split into
its directory-part and the file-part. A ".zip" extension is
then added to the directory-part to create the name of a
zip-archive. That zip-archive (if it exists) is being searched
for the file-part, and if found a zzip-handle is returned.

Note that if the file is found in the normal fs-directory the
returned structure is mostly empty and the zzip_read call will
use the libc read to obtain data. Otherwise a zzip_file_open
is performed and any error mapped to errno(3).

unlike the posix-wrapper zzip_open the mode-argument is
a string which allows for more freedom to support the extra
zzip modes called ZZIP_CASEINSENSITIVE and ZZIP_IGNOREPATH.
Currently, this zzip_fopen call will convert the following
characters in the mode-string into their corrsponding mode-bits:

"r" : O_RDONLY : read-only
"b" : O_BINARY : binary (win32 specific)
"f" : O_NOCTTY : no char device (unix)
"i" : ZZIP_CASELESS : inside zip file
"*" : ZZIP_NOPATHS : inside zip file only

all other modes will be ignored for zip-contained entries
but they are transferred for compatibility and portability,
including these extra sugar bits:

"x" : O_EXCL : fail if file did exist
"s" : O_SYNC : synchronized access
"n" : O_NONBLOCK : nonblocking access
"z#" : compression level : for zlib
"g#" : group access : unix access bits
"u#" : owner access : unix access bits
"o#" : world access : unix access bits

... the access bits are in traditional unix bit format
with 7 = read/write/execute, 6 = read/write, 4 = read-only.

The default access mode is 0664, and the compression level
is ignored since the lib can not yet write zip files, otherwise
it would be the initialisation value for the zlib deflateInit
where 0 = no-compression, 1 = best-speed, 9 = best-compression.

The zzip_freopen function receives an additional argument pointing to
a ZZIP_FILE* being already in use. If this extra argument is
null then the zzip_freopen function is identical with calling zzip_fopen

Per default, the old file stream is closed and only the internal
structures associated with it are kept. These internal structures
may be reused for the return value, and this is a lot quicker when
the filename matches a zipped file that is incidently in the very
same zip arch as the old filename wrapped in the stream struct.

That's simply because the zip arch's central directory does not
need to be read again. As an extension for the zzip_freopen function, if the
mode-string contains a "q" then the old stream is not closed but
left untouched, instead it is only given as a hint that a new
file handle may share/copy the zip arch structures of the old file
handle if that is possible, i.e when they are in the same zip arch.

(../zzip/file.c)

int
zzip_init_io (zzip_plugin_io_handlers_t io, int flags)
zzip_plugin_io_t
zzip_get_default_io ()

call inflateInit and setup fp's iterator variables,
used by lowlevel _open functions.

(../zzip/file.c)

(zzip/plugin.c)

The zzip_init_io function initializes the users handler struct to default values
being the posix io functions in default configured environments.

The zzip_get_default_io function returns a zzip_plugin_io_t handle to static defaults
wrapping the posix io file functions for actual file access.

(../zzip/plugin.c)

int inline
zzip_mkdir (zzip_char_t* name, int o_mode)
ZZIP_FILE* inline
zzip_creat (zzip_char_t* name, int o_mode)

create a zipped file/directory

The zzip_mkdir function creates a directory entry in the default zip-archive.
If you did not specify a "#define zzip_savefile somevar"
then the default zip-archive is null and all directories are
created as real directories in the filesystem. The zzip_mkdir function is
really a preprocessor macro or preferably an inline function
around zzip_file_mkdir, there is no such symbol generated
into the library. The prototype is modelled after the posix
mkdir(2) call.

  #ifndef zzip_savefile  
   #define zzip_savefile 0  
   #endif  
   #define zzip_mkdir(name,mode) \ -

zzip_file_mkdir(zzip_savefile,name,mode)

The zzip_creat function creates a file in the default zip-archive.
If you did not specify a "#define zzip_savefile somevar"
then the default zip-archive is null and all files are created
as real files. The zzip_creat function is really a preprocessor macro
or preferably an inline function around zzip_file_creat,
there is no such symbol generated into the library. The prototype
is modelled after the posix creat(2) call.

  #ifndef zzip_savefile  
   #define zzip_savefile 0  
   #endif  
   #define zzip_creat(name,mode) \ -

zzip_file_creat(zzip_savefile,name,mode)

(../zzip/write.c)

void inline
zzip_mkfifo (zzip_char_t* name, int o_mode)
void inline
zzip_sync (void)

start writing to the magic zzip_savefile

open a zip archive for writing via the magic zzip_savefile macro
variable. The name and mode are given to zzip_createdir and
the result is stored into zzip_savefile - if the zzip_savefile
did already have a zzip_dir handle then it is automatically
finalized with zzip_sync and the handle closed and the
zzip_savefile variable reused for the new zip archive just started
with this call. - The zzip_mkfifo function is really a preprocessor macro
or preferably an inline function around zzip_dir_create, there
is no such symbol generated into the library.

  #ifndef zzip_savefile  
   #define zzip_savefile 0  
   #endif  
   #define zzip_start(name,mode,ext) \ -

{ if (zzip_savefile) zzip_closedir(zzip_savefile); \ - zzip_savefile = zzip_createdir(name,mode,ext); }
The zzip_mkfifo function returns null on error or a zzip_dir handle on
success. It is perfectly okay to continue with a null in the
zzip_savefile variable since it makes subsequent calls to
zzip_creat and zzip_mkdir to run as creat(2) / mkdir(2)
on the real filesystem.

finalize a zip archive thereby writing the central directory to
the end of the file. If it was a real directory then we do just
nothing - even that the prototype of the call itself is modelled
to be similar to the posix sync(2) call. The zzip_sync function is
really a preprocessor macro or preferably an inline function
around zzip_closedir, there is no such symbol generated
into the library.

  #ifndef zzip_savefile  
   #define zzip_savefile 0  
   #endif  
   #define zzip_sync(name,mode) \ -

{ zzip_closedir(zzip_savefile); zzip_savefile = 0; }

(../zzip/write.c)

ZZIP_FILE*
zzip_open (zzip_char_t* filename, int o_flags)
ZZIP_FILE*
zzip_open_ext_io (zzip_char_t* filename, int o_flags, int o_modes, zzip_strings_t* ext, zzip_plugin_io_t io)
ZZIP_FILE*
zzip_open_shared_io (ZZIP_FILE* stream, zzip_char_t* filename, int o_flags, int o_modes, zzip_strings_t* ext, zzip_plugin_io_t io)

ZZIP_DIR*
zzip_opendir (zzip_char_t* filename)
ZZIP_DIR*
zzip_opendir_ext_io (zzip_char_t* filename, int o_modes, zzip_strings_t* ext, zzip_plugin_io_t io)

The zzip_open function will open(2) a real/zipped file

There was a possibility to transfer zziplib-specific openmodes
through o_flags but you should please not use them anymore and
look into zzip_open_ext_io to submit them down. The zzip_open function
is shallow in that it just extracts the zzipflags and calls

zzip_open_ext_io(filename, o_flags, zzipflags|0664, 0, 0)

you must stop using this extra functionality (not well known
anyway) since zzip_open might be later usable to open files
for writing in which case the _EXTRAFLAGS will get in conflict.

compare with open(2) and zzip_fopen

The zzip_open_ext_io function uses explicit ext and io instead of the internal
defaults, setting them to zero is equivalent to zzip_open

note that the two flag types have been split into an o_flags
(for fcntl-like openflags) and o_modes where the latter shall
carry the zzip_flags and possibly accessmodes for unix filesystems.
Since this version of zziplib can not write zipfiles, it is not
yet used for anything else than zzip-specific modeflags.

The zzip_open_shared_io function takes an extra stream argument - if a handle has been
then ext/io can be left null and the new stream handle will pick up
the ext/io. This should be used only in specific environment however
since zzip_file_real does not store any ext-sequence.

The benefit for the zzip_open_shared_io function comes in when the old file handle
was openened from a file within a zip archive. When the new file
is in the same zip archive then the internal zzip_dir structures
will be shared. It is even quicker, as no check needs to be done
anymore trying to guess the zip archive place in the filesystem,
here we just check whether the zip archive's filepath is a prefix
part of the filename to be opened.

Note that the zzip_open_shared_io function is also used by zzip_freopen that
will unshare the old handle, thereby possibly closing the handle.

(../zzip/file.c)

zzip_ssize_t
zzip_read (ZZIP_FILE * fp, char * buf, zzip_size_t len)
zzip_size_t
zzip_fread (void *ptr, zzip_size_t size, zzip_size_t nmemb, ZZIP_FILE *file)

The zzip_opendir function is the equivalent of opendir(3) for a realdir or zipfile.

The zzip_opendir function has some magic - if the given argument-path
is a directory, it will wrap a real opendir(3) into the ZZIP_DIR
structure. Otherwise it will divert to zzip_dir_open which
can also attach a ".zip" extension if needed to find the archive.

the error-code is mapped to errno(3).

The zzip_opendir_ext_io function uses explicit ext and io instead of the internal
defaults, setting them to zero is equivalent to zzip_opendir

(../zzip/dir.c)

ZZIP_DIRENT*
zzip_readdir (ZZIP_DIR * dir)

The zzip_read function will read(2) data from a real/zipped file.

the replacement for read(2) will fill the given buffer with bytes from
the opened file. It will return the number of bytes read, so if the EOF
is encountered you will be prompted with the number of bytes actually read.

If the file-handle is wrapping a stat'able file then it will actually just
perform a normal read(2)-call, otherwise zzip_file_read is called
to decompress the data stream and any error is mapped to errno(3).

zzip_fread -

(../zzip/file.c)

The zzip_readdir function is the equivalent of a readdir(2) for a realdir
or a zipfile referenced by the ZZIP_DIR returned from zzip_opendir.

The ZZIP_DIR handle (as returned by zzip_opendir) contains a few more
entries than being copied into the ZZIP_DIRENT. The only valid fields in
a ZZIP_DIRENT are d_name (the file name), d_compr (compression), d_csize
(compressed size), st_size (uncompressed size).

(../zzip/dir.c)

int
zzip_rewind (ZZIP_FILE *fp)

void
zzip_rewinddir (ZZIP_DIR * dir)
zzip_off_t
zzip_telldir (ZZIP_DIR* dir)
void
zzip_seekdir (ZZIP_DIR* dir, zzip_off_t offset)

The zzip_rewind function will rewind a real/zipped file.

It seeks to the beginning of this file's data in the zip,
or the beginning of the file for a stat'fd.

(../zzip/file.c)

zzip_off_t
zzip_seek (ZZIP_FILE * fp, zzip_off_t offset, int whence)

The zzip_rewinddir function is the equivalent of a rewinddir(2) for a realdir or
the zipfile in place of a directory. The ZZIP_DIR handle returned from
zzip_opendir has a flag saying realdir or zipfile. As for a zipfile,
the filenames will include the filesubpath, so take care.

The zzip_telldir function is the equivalent of telldir(2) for a realdir or zipfile.

The zzip_seekdir function is the equivalent of seekdir(2) for a realdir or zipfile.

(../zzip/dir.c)

zzip_char_t*
zzip_strerror (int errcode)
zzip_char_t*
zzip_strerror_of (ZZIP_DIR* dir)

The zzip_seek function will perform a lseek(2) operation on a real/zipped file

It will try to seek to the offset specified by offset, relative to whence,
which is one of SEEK_SET, SEEK_CUR or SEEK_END.

If the file-handle is wrapping a stat'able file then it will actually just
perform a normal lseek(2)-call. Otherwise the relative offset
is calculated, negative offsets are transformed into positive ones
by rewinding the file, and then data is read until the offset is
reached. This can make the function terribly slow, but this is
how gzio implements it, so I'm not sure there is a better way
without using the internals of the algorithm.

(../zzip/file.c)

(zzip/err.c)

returns the static string for the given error code. The
error code can be either a normal system error (a
positive error code will flag this), it can be libz
error code (a small negative error code will flag this)
or it can be an error code from libzzip, which is an
negative value lower than ZZIP_ERROR

The zzip_strerror_of function fetches the errorcode from the DIR-handle and
runs it through zzip_strerror to obtain the static string
describing the error.

(../zzip/err.c)

zzip_off_t
zzip_tell (ZZIP_FILE * fp)