zziplib Library Functions

Version 0.13.49

#include <zzip/lib.h>

Documentation

zzip_error(ZZIP_DIR * dir) : int

zzip_seterror(ZZIP_DIR * dir, int errcode) : void

zzip/info.c 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_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_FILE*

zzip/file.c The zzip_open 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. 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_ext_io function returns a new zzip-handle (use zzip_close to return it). On error the zzip_open_ext_io function will return null setting errno(3).

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. The zzip_open_shared_io function returns a new zzip-handle (use zzip_close to return it). On error the zzip_open_shared_io function will return null setting errno(3).

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) : ZZIP_DIR*

... zzip/dir.c

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_file_real(ZZIP_FILE* fp) : int

zzip_dir_real(ZZIP_DIR* dir) : int

zzip_realdir(ZZIP_DIR* dir) : void*

zzip_realfd(ZZIP_FILE* fp) : int

... zzip/info.c

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_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) : int

... zzip/stat.c

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_strerror(int errcode) : zzip_char_t*

zzip_strerror_of(ZZIP_DIR* dir) : zzip_char_t*

... zzip/err.c

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_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) : ZZIP_DIR*

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

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

fills the dirent-argument with the values and increments the read-pointer of the dir-argument. returns 0 if there no entry (anymore).

zzip_init_io(zzip_plugin_io_handlers_t io, int flags) : int

zzip_get_default_io() : zzip_plugin_io_t

... zzip/plugin.c

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_rewinddir(ZZIP_DIR * dir) : void

zzip_telldir(ZZIP_DIR* dir) : zzip_off_t

zzip_seekdir(ZZIP_DIR* dir, zzip_off_t offset) : void

zzip/dir.c 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_fopen(zzip_char_t* filename, zzip_char_t* mode) : ZZIP_FILE*

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

zzip/file.c 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_fopen function returns a new zzip-handle (use zzip_close to return it). On error the zzip_fopen function will return null setting errno(3).

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. The zzip_freopen function returns a new zzip-handle (use zzip_close to return it). On error the zzip_freopen function will return null setting errno(3).

zzip_dirhandle(ZZIP_FILE * fp) : ZZIP_DIR *

zzip_dirfd(ZZIP_DIR* dir) : int

zzip/info.c 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_read(ZZIP_FILE * fp, void * buf, zzip_size_t len) : zzip_ssize_t

zzip_fread(void *ptr, zzip_size_t size, zzip_size_t nmemb, ZZIP_FILE *file) : zzip_size_t

zzip/file.c 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_dir_free(ZZIP_DIR * dir) : int

zzip_dir_close(ZZIP_DIR * dir) : int

... 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_fclose(ZZIP_FILE * fp) : int

zzip_close(ZZIP_FILE* fp) : int

zzip/file.c 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_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) : ZZIP_DIR *

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

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_readdir(ZZIP_DIR * dir) : ZZIP_DIRENT*

... zzip/dir.c

zzip_closedir(ZZIP_DIR* dir) : int

... zzip/dir.c

zzip_errno(int errcode) : int

... zzip/err.c

zzip_file_close(ZZIP_FILE * fp) : int

... zzip/file.c

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

... zzip/file.c

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

... zzip/file.c

zzip_file_read(ZZIP_FILE * fp, void * buf, zzip_size_t len) : zzip_ssize_t

zzip/file.c 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_rewind(ZZIP_FILE *fp) : int

zzip/file.c 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_seek(ZZIP_FILE * fp, zzip_off_t offset, int whence) : zzip_off_t

zzip/file.c 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_tell(ZZIP_FILE * fp) : zzip_off_t

zzip/file.c The zzip_tell 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_compr_str(int compr) : zzip_char_t*

... zzip/info.c

__zzip_fetch_disk_trailer(int fd, zzip_off_t filesize, struct _disk_trailer * _zzip_restrict trailer, zzip_plugin_io_t io) : int

... zzip/zip.c

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

... zzip/zip.c

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

... zzip/zip.c