ZIP_SOURCE_LAYERED(3)

ZIP_SOURCE_LAYERED 💅✨

okay bestie, pull up a chair, we're doing a 3 manpage today — Library Functions Manual energy, section ZIP_SOURCE_LAYERED(3), and it's genuinely one of the cutest little builder functions in the whole libzip lineup. let's get into it 🫶

---

✨ NAME ✨

zip_source_layered, zip_source_layered_create — create layered data source from function

📚 LIBRARY 📚

libzip (-lzip)

🌸 SYNOPSIS 🌸

#include <zip.h>

zip_source_t *
zip_source_layered(zip_t *archive, zip_source_t *source,
    zip_source_layered_callback fn, void *userdata);

zip_source_t *
zip_source_layered_create(zip_source_t *source,
    zip_source_layered_callback fn, void *userdata, zip_error_t *error);

💖 DESCRIPTION 💖

so zip_source_layered() and zip_source_layered_create() are the two besties that create a layered zip source — meaning you hand them a function fn that you wrote, and they wrap it around whatever source is underneath. no cap, that's the whole vibe.

and that function fn has to be exactly this type, no substitutions:

typedef zip_int64_t (*p_source_layered_callback)(zip_source_t *source,
void *userdata, void *data, zip_uint64_t length, zip_source_cmd_t cmd)

archive or error are the spots where errors get reported, and yes, they can be NULL. lowkey convenient.

when the library calls your function, here's the tea on the arguments:

• the first argument is the source of the lower layer 🌈
• the second argument is the userdata argument you supplied to the function 🎀
• the next two arguments are a buffer data of size length — and this is when data is being passed in or expected to be returned. otherwise it's NULL and 0 🙈
• the last argument, cmd, tells the function which action it should perform 👑

want the full rundown of the commands? go read zip_source_function(3). iykyk.

so what's a layered source for? it transforms the data or metadata of the source below it in some way. iconic. but heads up bestie:

layered sources can't support writing and are not sufficient to cleanly add support for additional compression or encryption methods. this may be revised in a later release of libzip. periodt.

on success, the layered source takes ownership of source. the caller should not free it. do not. i'm serious. 💀

and the way it interacts with the lower layer depends entirely on the command:

🦋 ZIP_SOURCE_ACCEPT_EMPTY

if the layered source supports this command, the lower layer is not called automatically. otherwise, the return value of the lower source is used.

🦋 ZIP_SOURCE_CLOSE

the lower layer is closed after the callback returns.

🦋 ZIP_SOURCE_ERROR

the lower layer is not called automatically. if you need to retrieve error information from the lower layer, use zip_error_set_from_source(3) or zip_source_pass_to_lower_layer(3).

🦋 ZIP_SOURCE_FREE

the lower layer is freed after the callback returns.

🦋 ZIP_SOURCE_GET_FILE_ATTRIBUTES

the attributes of the lower layer are merged with the attributes returned by the callback — information set by the callback wins over the lower layer, with these two exceptions:

• the higher version_needed is used
• general_purpose_bit_flags are only overwritten if the corresponding bit is set in general_purpose_bit_mask

🦋 ZIP_SOURCE_OPEN

the lower layer is opened before the callback is called.

🦋 ZIP_SOURCE_READ

the lower layer is not called automatically.

🦋 ZIP_SOURCE_SEEK

the lower layer is not called automatically.

🦋 ZIP_SOURCE_STAT

data contains the stat information from the lower layer when the callback is called.

🦋 ZIP_SOURCE_SUPPORTS

data contains the bitmap of commands supported by the lower layer when the callback is called. since layered sources can't support writing, all commands related to writing are stripped from the returned support bitmap.

🦋 ZIP_SOURCE_TELL

the lower layer is not called automatically.

---

🎀 RETURN VALUES 🎀

upon successful completion, the created source is returned. otherwise, NULL is returned and the error code in archive or error is set to indicate the error (unless it is NULL). 😭

---

🍓 ERRORS 🍓

zip_source_layered() fails if:

• [ZIP_ER_MEMORY] — required memory could not be allocated.

---

👑 SEE ALSO 👑

libzip(3), zip_file_add(3), zip_file_attributes_init(3), zip_file_replace(3), zip_source(5), zip_source_function(3), zip_source_pass_to_lower_layer(3)

---

⭐ HISTORY ⭐

zip_source_layered() and zip_source_layered_create() were added in libzip 1.10.

---

💜 AUTHORS 💜

Dieter Baron <dillo@nih.at> and Thomas Klausner <wiz@gatalith.at>

---

and that's the whole page, bestie 🫶 this Debian build dropped on January 20, 2023, filed under ZIP_SOURCE_LAYERED(3) — slay, go layer some sources, and remember: don't free what you handed over. 💅✨