zzip_entry_findfile(3)

💖 zzip_entry_findfile — bestie's guide to the zziplib Function List 💖

okay so this is zzip_entry_findfile(3), straight out of the zziplib Function List, and we're about to go searching for files in the (fseeko) zip central directory. no cap. grab a snack, we're doing pointer math 🦋

---

✨ NAME ✨

zzip_entry_findfile, zzip_entry_findfirst, zzip_entry_findnext, zzip_entry_free, zzip_entry_findmatch — they all do one iconic thing: search for files in the (fseeko) zip central directory. that's the whole vibe. 👑

---

🌸 SYNOPSIS 🌸

#include <zzip/fseeko.h>

zzip__new__ ZZIP_ENTRY*
zzip_entry_findfile(FILE* disk, char* filename, ZZIP_ENTRY* _zzip_restrict entry,
                    zzip_strcmp_fn_t compare)

zzip__new__ ZZIP_ENTRY*
zzip_entry_findfirst(FILE* disk)

zzip__new__ ZZIP_ENTRY*
zzip_entry_findnext(ZZIP_ENTRY* _zzip_restrict entry)

int
zzip_entry_free(ZZIP_ENTRY* entry)

zzip__new__ ZZIP_ENTRY*
zzip_entry_findmatch(FILE* disk, char* filespec, ZZIP_ENTRY* _zzip_restrict entry,
                     zzip_fnmatch_fn_t compare, int flags)

like... look at all those zzip__new__s. we love a family that allocates together 🫶

---

💅 DESCRIPTION 💅

🎀 zzip_entry_findfile

bestie, this one gets a filename as an additional argument, and its whole job is to find the disk_entry that matches that given filename. the compare-function is usually strcmp or strcasecmp or maybe strcoll — and if it's null then strcmp is what gets used, no discussion.

here's the part you gotta remember: use null as the argument for the "old"-entry when you're searching for the first matching entry. otherwise, pass the last returned value if you're looking for more entries with a special "compare" function. and lowkey — if that compare function is null then a doubled search is rather useless with this variant of _findfile, so don't do that to yourself 💀

if no further entry is found, then null is returned and any "old"-entry gets already free()d. it's giving self-cleaning. periodt.

🦋 zzip_entry_findfirst

this is the first call of all the zip access functions here. main character energy, truly. it contains the code to find the first entry of the zip central directory.

here's the requirement, and it's strict: we need the stdio handle to represent a real zip file where the disk_trailer is _last_ in the file area. that way its position would sit at a fixed offset from the end of the file area — if not for the comment field, which is allowed to be of variable length. (which means we gotta do a little search for the disk_tailer ourselves. yes, they wrote it that way in the original. we respect it. 🎀)

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. simple, clean, slay.

so for an actual means: we're gonna 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. and if we find the correct PK-magic signature of a disk_entry over there, then we assume we are done and we 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. likewise, we only accept a disk_trailer with a seekvalue that points to a disk_entry, and both parts have to have valid PK-magic parts.

and 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. iconic of us honestly 🙈

⚠️ real talk: zzip_entry_findfirst returns null on error, with errno = EINVAL|ENOMEM|EBADMSG|EBADF|ENOENT. that's five whole ways to fail. check your errno bestie 😭

🌈 zzip_entry_findnext

this one takes an existing "entry" in the central root directory (like, one you got from zzip_entry_findfirst) and moves it to point to the next entry.

• on error it returns 0
• otherwise it returns the old entry
• if no further match is found then null is returned and the entry is already free()d

and if you wanna stop searching for matches before that whole case happens, then please call zzip_entry_free on the cursor struct ZZIP_ENTRY. don't just ghost it, that's rude to the malloc 🥺

🍓 zzip_entry_free

this is the lil cleanup queen. it releases the malloc()ed areas needed for zzip_entry, and the pointer is invalid afterwards. like, gone. don't touch it.

oh and also? zzip_entry_free has #define synonyms, which are:

• zzip_entry_findlast()
• zzip_entry_findlastfile()
• zzip_entry_findlastmatch()

cute little aliases, we stan 💜

🧚 zzip_entry_findmatch

this one uses a compare-function with an additional argument, and it gets called just like fnmatch(3) from POSIX.2 AD:1993). so the argument order is: the argument filespec first, the ziplocal filename second, and the integer-flags put in as the third to the indirect call.

if the platform has fnmatch available, then a null-compare will use that one. otherwise we fall back to mere strcmp. so if you need fnmatch searching, then please provide an implementation somewhere else — we're not doing it for you, bestie 🫶

and the cursor rules: use null as the argument for the "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. same energy as before, consistent queen.

---

👑 AUTHOR 👑

Guido Draheim <guidod@gmx.de> — the actual legend behind all of this 🫡

---

🎀 COPYRIGHT 🎀

Copyright (c) Guido Draheim, use under copyleft (LGPL,MPL)

---

and that's the whole page, bestie!! this was zzip_entry_findfile(3) from zziplib, version 0.13.78, dated the same day the manpage footer says so — consider this your cute sign-off, mwah 💖✨ go read your zip central directory responsibly 🦋💅