ZIP_SOURCE_FILE(3)

💖 zip_source_file — bestie edition 💖

okay so we're doing zip_source_file(3) today and honestly? it's giving library functions manual energy in the best way. this is libzip's little "turn a plain file into a zip data source" duo and it's lowkey iconic. sit down, grab a strawberry 🍓, let's get into it.

---

✨ LIBRARY ✨

libzip — you link it with -lzip and then you're slaying 💅

---

✨ SYNOPSIS ✨

#include <zip.h>

zip_source_t *
zip_source_file(zip_t *archive, const char *fname, zip_uint64_t start,
    zip_int64_t len);

zip_source_t *
zip_source_file_create(const char *fname, zip_uint64_t start,
    zip_int64_t len, zip_error_t *error);

---

🌸 DESCRIPTION 🌸

so both zip_source_file() and zip_source_file_create() do the same lil' thing: they make a zip source out of a file 🎀. they open fname and read len bytes starting at offset start. that's it, that's the job, no cap.

now here's where it gets interesting, bestie, because len is doing a LOT of heavy lifting depending on what you hand it:

• if you pass ZIP_LENGTH_TO_END — or -1, which is deprecated btw, don't do it — then zip_source_file figures out the file size at the moment it's called and uses that as the expected file size 👑. if the file grows between creating the source and reading from it? the extra data is just ignored, she's unbothered 💅. but if the file shrinks, libzip treats it as an error: ZIP_ER_DATA_LENGTH. so like, don't do that 😭.
• if you pass ZIP_LENGTH_UNCHECKED, then zip_source_file just assumes the file's size is unknown. reading from the source returns as much data as happens to be there at that time (usually when you call zip_close(3)). chaos, but make it functional ✨.

and here's the tea ☕: libzip can do a bunch of optimizations when it knows the size of a source at creation time. so ZIP_LENGTH_TO_END is preferable, periodt. if you're dealing with files that are likely to change while you're still processing them, then fine, use ZIP_LENGTH_UNCHECKED — just know it's the less efficient option 🙈.

oh and also! if the file supports seek, the source can be used to open a zip archive from. cute 🦋.

one more thing: the file isn't opened and read right away. it gets opened and read when the data from the source is actually used — usually by zip_close() or zip_open_from_source(). so she's a little bit of a procrastinator, but like, same honestly 💜.

---

✨ RETURN VALUES ✨

if everything goes well, you get the created source back. slay! 🌈

if it doesn't? you get NULL, and the error code in archive or error gets set to tell you what went wrong. not the vibe, but at least it's informative 💀.

---

🎀 ERRORS 🎀

zip_source_file() and zip_source_file_create() fail if:

• [ZIP_ER_INVAL] — fname, start, or len are invalid.
• [ZIP_ER_MEMORY] — required memory could not be allocated.
• [ZIP_ER_OPEN] — opening fname failed.

bestie if you're seeing ZIP_ER_OPEN pls check your path before you blame libzip, i'm just saying 🙈

---

👑 SEE ALSO 👑

libzip(3), zip_file_add(3), zip_file_replace(3), zip_source(5)

---

🌟 HISTORY 🌟

zip_source_file() and zip_source_file_create() were added in libzip 1.0.

ZIP_LENGTH_TO_END and ZIP_LENGTH_UNCHECKED were added in libzip 1.10.1.

---

💜 AUTHORS 💜

Dieter Baron <dillo@nih.at> and Thomas Klausner <wiz@gatalith.at> — absolute legends, fr fr 🫶

---

okay that's the whole page, we ate and left no crumbs 🍽️✨ this was the ZIP_SOURCE_FILE(3) manual, coming to you from the Debian crew, dated June 30, 2023. mwah, go write some zip sources bestie 💖🦋