zzip_disk_findfile(3)

🦋 zzip_disk_findfile(3) — the zziplib Function List page, but make it make sense 💖

okay so bestie, this is zzip_disk_findfile(3) from the zziplib Function List, and it's literally the whole "find files inside an mmapped zip central directory" saga. four functions, one mission, zero cap. let's go 🫶

---

✨ NAME ✨

• zzip_disk_findfile, zzip_disk_findfirst, zzip_disk_findnext, zzip_disk_findmatch — searching for files in the (mmapped) zip central directory. that's the whole vibe, no notes. 🎀

---

🌸 SYNOPSIS 🌸

#include <zzip/mmapped.h>

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)

---

💅 DESCRIPTION 💅

🍓 zzip_disk_findfile

so this one gets handed a filename as an extra argument, and its whole job is finding the disk_entry that matches that filename. the compare-function is usually strcmp or strcasecmp or maybe strcoll — and if it's null, then strcmp is what gets used, periodt.

for the after argument: pass null when you're hunting for the first matching entry. otherwise, pass the last returned value if you're looking for more entries with some special compare function. (and ngl, if compare is null then a doubled search is rather useless with this variant of _findfile — like, why even. 💀)

the return value is the entry pointer. it may return null on error. (errno = ENOMEM|EBADMSG|ENOENT) 😭

---

🧚 zzip_disk_findfirst

this is the first call of all the zip access functions here, bestie. it holds the code that finds the first entry of the zip central directory.

heads up though: here we require the mmapped block to actually 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 — except for the comment field, which is allowed to be of variable length, and that's what forces us to do a little search for the disk_tailer. 🙈

also, in this simple implementation we disregard any disk_trailer info that talks about multidisk archives. we just return a pointer to the zip central directory. slay, keep it simple.

so how does it actually work? we 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're done and we return a pointer to that label. ✅

the return value is a pointer to the first zzip_disk_entry, 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 where both parts have valid PK-magic parts. beyond that sanity check we try to catch a common brokeness with zip archives that still lets us find the start of the zip central directory. so yeah, zzip_disk_findfirst may return null, and it sets errno. 🫠

---

🦋 zzip_disk_findnext

this one takes an existing disk_entry in the central root directory (like, one you got from zzip_disk_findfirst) and returns the next entry within the given bounds of the mmapped file area. iconic behaviour honestly.

it returns null if no next entry can be found. it may return null on errors. (errno = ENOENT|EINVAL|EBADMSG) ⭐

---

👑 zzip_disk_findmatch

this cutie uses a compare-function with an additional argument, and it gets called just like fnmatch(3) from POSIX.2 AD:1993) — meaning the argument filespec comes first, the ziplocal filename comes second, and the integer-flags get put in as the third thing to the indirect call. iykyk.

if the platform has fnmatch available then 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. 💖

for after: pass null when searching for the first matching entry, or pass the last disk_entry return-value to find the next entry matching the given filespec.

it returns the matching entry pointer. it may return null on error. (errno = ENOMEM|EBADMSG|ENOENT) 🌈

---

🌟 AUTHOR 🌟

Guido Draheim <guidod@gmx.de> — the main character who wrote all this 🫶

---

💜 COPYRIGHT 💜

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

---

no cap, that's the whole page. go find some zip entries, bestie 💅

zziplib 0.13.72 — this page is zzip_disk_findfile(3), and that's the version + page name sign-off, mwah 🎀✨