zzip_fopen(3)

💖 zzip_fopen — the zziplib function list, bestie edition 💖

okay so real talk, this is the page for zzip_fopen and zzip_freopen from zziplib — yes that's the same crew that brings you the whole zzip function list. it's giving "opening files but make it ✨magical✨". let's get into it 🦋

---

✨ NAME ✨

zzip_fopen, zzip_freopen — start usage. yep, that's literally it, that's the whole vibe, we're starting usage over here 💅

---

🎀 SYNOPSIS 🎀

#include <zzip/lib.h>

ZZIP_FILE*
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)

like look at her, two lil functions, one extra arg, iconic 👑

---

🌸 DESCRIPTION 🌸

so the zzip_fopen function will fopen(3) a real/zipped file. both. it does both. main character energy fr fr.

and here's the magic, no cap — it's got some builtin magic functionality and it goes like this:

1. first it tries to open the given filename as a normal file. just a regular file, nothing fancy.
2. if that file does not exist, then the given path to the filename (if any) gets split into its directory-part and the file-part.
3. then a .zip extension gets added to the directory-part to create the name of a zip-archive.
4. that zip-archive (if it exists, key word if) is being searched for the file-part, and if found, a zzip-handle is returned. slay.

heads up bestie — 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(2) to obtain data. otherwise a zzip_file_open is performed and any error gets mapped to errno(3).

unlike the posix-wrapper zzip_open, the mode-argument here is a string which allows for more freedom to support the extra zzip modes called ZZIP_CASEINSENSITIVE and ZZIP_IGNOREPATH. so much room to be extra, we love that for us 🫶

right now, 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

and 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

... and the access bits are in traditional unix bit format with 7 = read/write/execute, 6 = read/write, 4 = read-only. yes we're doing octal math, stay with me 🌈

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. (imagine, bestie. imagine. but no writing zips yet 😭)

the zzip_fopen function returns a new zzip-handle (use zzip_close to return it, don't be rude). on error the zzip_fopen function will return null setting errno(3).

---

🦋 zzip_freopen, the sequel 🦋

the zzip_freopen function receives an additional argument pointing to a ZZIP_FILE* being already in use. and if this extra argument is null, then the zzip_freopen function is identical with calling zzip_fopen. same girl, different name 💜

per default, the old file stream is closed and only the internal structures associated with it are kept. those internal structures may be reused for the return value, and this is a lot quicker when the filename matches a zipped file that is incidentally in the very same zip arch as the old filename wrapped in the stream struct.

and like... that's simply because the zip arch's central directory does not need to be read again. efficiency queen 👑

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, again, please). on error the zzip_freopen function will return null setting errno(3).

---

👑 AUTHOR 👑

Guido Draheim <guidod@gmx.de> and Tomi Ollila <Tomi.Ollila@iki.fi> — legends, both of them, we stan ⭐

---

💅 COPYRIGHT 💅

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

---

🔥 SEE ALSO 🔥

• fopen(2)

---

and that's the whole page, bestie 💖 this lil writeup came straight out of zziplib 0.13.78 and it's the zzip_fopen(3) page — go forth and open some files, you're gonna do amazing, mwah 🧚✨