generated 2003-12-12
(C) Guido Draheim
guidod@gmx.de

zziplib -0.10.82.pre2

Documentation

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

 (../zzip/dir.c)

This 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.

(../zzip/dir.c)

ZZIP_DIRENT*
zzip_readdir   1000 (ZZIP_DIR * dir)

 (../zzip/dir.c)

This 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)

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

 (../zzip/dir.c)

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

This 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).

(../zzip/dir.c)

int
zzip_closedir   zzip_closedir (ZZIP_DIR* dir)

 (../zzip/dir.c)

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

This 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_char_t*
zzip_strerror   zzip_strerror (int errcode)
zzip_char_t*
zzip_strerror_of   zzip_strerror_of (ZZIP_DIR* dir)

 (../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

(../zzip/err.c)

int
zzip_errno   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_file_close   zzip_file_close (ZZIP_FILE * fp)

 (../zzip/file.c)

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)

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

 (../zzip/file.c)

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)

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

 (../zzip/file.c)

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

(../zzip/file.c)

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

 (../zzip/file.c)

This 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/file.c)

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

 (../zzip/file.c)

This 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_ssize_t
zzip_read   zzip_read (ZZIP_FILE * fp, char * buf, zzip_size_t len)
zzip_size_t
zzip_fread   zzip_fread (void *ptr, zzip_size_t size, zzip_size_t nmemb, ZZIP_FILE *file)

 (../zzip/file.c)

This 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/file.c)

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

 (../zzip/file.c)

This 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.

(../zzip/file.c)

ZZIP_FILE*
zzip_open   zzip_open (zzip_char_t* filename, int o_flags)
ZZIP_FILE*
zzip_open_ext_io   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_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/file.c)

This function will open(2) 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).

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. This 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

(../zzip/file.c)

int
zzip_rewind   zzip_rewind (ZZIP_FILE *fp)

 (../zzip/file.c)

This 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_seek (ZZIP_FILE * fp, zzip_off_t offset, int whence)

 (../zzip/file.c)

This 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_off_t
zzip_tell   zzip_tell (ZZIP_FILE * fp)

 (../zzip/file.c)

This function will tell(2) the current position in a real/zipped file

It will return the current offset within the real/zipped file,
measured in uncompressed bytes for the zipped-file case.

If the file-handle is wrapping a stat'able file then it will actually just
perform a normal tell(2)-call, otherwise the offset is
calculated from the amount of data left and the total uncompressed
size;

(../zzip/file.c)

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

 (../zzip/info.c)

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

(../zzip/info.c)

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

 (../zzip/info.c)

This 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.

(../zzip/info.c)

zzip_char_t*
zzip_compr_str   zzip_compr_str (int compr)

 (../zzip/info.c)

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

(../zzip/info.c)

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

 (../zzip/info.c)

This 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.

(../zzip/info.c)

int
zzip_init_io   zzip_init_io (struct zzip_plugin_io* io, int flags)
zzip_plugin_io_t
zzip_get_default_io   zzip_get_default_io ()

 (../zzip/plugin.c)

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

(../zzip/plugin.c)

int
zzip_dir_stat   zzip_dir_stat (ZZIP_DIR * dir, zzip_char_t* name, ZZIP_STAT * zs, int flags)

 (../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.

(../zzip/stat.c)

uint32_t
__zzip_get32   __zzip_get32 (unsigned char * s)

 (../zzip/zip.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))

(../zzip/zip.c)

int
__zzip_find_disk_trailer   __zzip_find_disk_trailer (int fd, zzip_off_t filesize, struct zzip_disk_trailer * trailer, zzip_plugin_io_t io)

 (../zzip/zip.c)

This 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)

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

 (../zzip/zip.c)

This 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)

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

 (../zzip/zip.c)

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)

(../zzip/zip.c)

int
zzip_dir_free   zzip_dir_free (ZZIP_DIR * dir)

 (../zzip/zip.c)

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/zip.c)

int
zzip_dir_close   zzip_dir_close (ZZIP_DIR * dir)

 (../zzip/zip.c)

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

(../zzip/zip.c)

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

 (../zzip/zip.c)

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. This function then search and parse
the zip's central directory.

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

(../zzip/zip.c)

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

 (../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)

ZZIP_DIR*
zzip_dir_open   zzip_dir_open (zzip_char_t* filename, zzip_error_t* e)
ZZIP_DIR*
zzip_dir_open_ext_io   zzip_dir_open_ext_io (zzip_char_t* filename, zzip_error_t* e, zzip_strings_t* ext, zzip_plugin_io_t io)

 (../zzip/zip.c)

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/zip.c)

int
zzip_dir_read   zzip_dir_read (ZZIP_DIR * dir, ZZIP_DIRENT * d )

 (../zzip/zip.c)

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)