zziplib Library Functions

Version 0.13.68

#include <zzip/mmapped.h>

Documentation

zzip_disk_entry_to_data(ZZIP_DISK * disk, struct zzip_disk_entry * entry) : zzip_byte_t *

zzip_disk_entry_to_file_header(ZZIP_DISK * disk, struct zzip_disk_entry *entry) : struct zzip_file_header *

zzip_disk_entry_strdup_name(ZZIP_DISK * disk, struct zzip_disk_entry *entry) : zzip__new__ char *

zzip_disk_entry_strdup_comment(ZZIP_DISK * disk, struct zzip_disk_entry *entry) : zzip__new__ char *

helper functions for (mmapped) zip access api zzip/mmapped.c 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_data function returns a pointer into disk->buffer or 0 on error (errno).

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_to_file_header function returns a pointer into disk->buffer or 0 on error (errno).

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. The zzip_disk_entry_strdup_name function returns a new string buffer, or null on error. If no name can be found then an empty string is returned.

The zzip_disk_entry_strdup_comment function is similar creating a reference to a zero terminated string but it can only exist in the zip central directory entry. The zzip_disk_entry_strdup_comment function returns a new string buffer, or null on error (errno). If no name can be found then an empty string is returned.

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) : struct zzip_disk_entry *

search for files in the (mmapped) zip central directory zzip/mmapped.c 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_findfile functionreturns the entry pointer. The zzip_disk_findfile function may return null on error. (errno = ENOMEM|EBADMSG|ENOENT)

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.So the zzip_disk_findfirst function may return null and sets errno.

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_findnext function returns null if no next entry can be found. The zzip_disk_findnext function may return null on errors. (errno = ENOENT|EINVAL|EBADMSG)

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. The zzip_disk_findmatch function will return the matching entry pointer. The zzip_disk_findmatch function may return null on error. (errno = ENOMEM|EBADMSG|ENOENT)

zzip_disk_fopen(ZZIP_DISK * disk, char *filename) : zzip__new__ ZZIP_DISK_FILE *

zzip_disk_entry_fopen(ZZIP_DISK * disk, ZZIP_DISK_ENTRY * entry) : zzip__new__ ZZIP_DISK_FILE *

zzip_disk_fread(void *ptr, zzip_size_t sized, zzip_size_t nmemb, ZZIP_DISK_FILE * file) : zzip_size_t

zzip_disk_fclose(ZZIP_DISK_FILE * file) : int

zzip_disk_feof(ZZIP_DISK_FILE * file) : int

openening a file part wrapped within a (mmapped) zip archive zzip/mmapped.c 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_fopen function may return null on errors (errno).

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_entry_fopen function may return null on errors (errno = ENOMEM|EBADMSG).

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_fclose function always returns 0.

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. The zzip_disk_feof function returns EOF in case and 0 when not at the end of file.

zzip_disk_mmap(int fd) : zzip__new__ ZZIP_DISK *

zzip_disk_init(ZZIP_DISK * disk, void *buffer, zzip_size_t buflen) : int

zzip_disk_new(void) : zzip__new__ ZZIP_DISK *

zzip_disk_munmap(ZZIP_DISK * disk) : int

zzip_disk_open(char *filename) : zzip__new__ ZZIP_DISK *

zzip_disk_buffer(void *buffer, size_t buflen) : zzip__new__ ZZIP_DISK *

zzip_disk_close(ZZIP_DISK * disk) : int

turn a filehandle into a mmapped zip disk archive handle zzip/mmapped.c 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_mmap function may return null on errors (errno).

The zzip_disk_init function does primary initialization of a disk-buffer struct. The zzip_disk_init function always returns 0 as success.

The zzip_disk_new function allocates a new disk-buffer with malloc(3) The zzip_disk_new function may return null on errors (errno).

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 ambiguous it should not be snatched away please. The zzip_disk_open function may return null on errors (errno).

The zzip_disk_buffer function will attach a buffer with a zip image that was acquired from another source than a file. Note that if zzip_disk_mmap fails then zzip_disk_open will fall back and try to read the full file to memory wrapping a ZZIP_DISK around the memory buffer just as the zzip_disk_buffer function will do. Note that the zzip_disk_buffer function will not own the buffer, it will neither be written nor free()d. The zzip_disk_buffer function may return null (errno).

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. The zzip_disk_close function returns 0 on success (or whatever munmap says).