ZIP_SOURCE_FUNCTION(3)

💖 zip_source_function — create data source from function 💖

okay bestie, so this is from the Library Functions Manual, it's a libzip thing (libzip (-lzip), we love her), and it's all about building your very own zip data source out of a function you write yourself. main character energy fr fr. 🦋

---

✨ NAME ✨

zip_source_function, zip_source_function_create — create data source from function. that's it, that's the whole vibe.

🌸 LIBRARY 🌸

libzip (-lzip) — link against her, she's iconic.

🎀 SYNOPSIS 🎀

#include <zip.h>

zip_source_t *
zip_source_function(zip_t *archive, zip_source_callback fn,
    void *userdata);

zip_source_t *
zip_source_function_create(zip_source_callback fn, void *userdata,
    zip_error_t *error);

💅 DESCRIPTION 💅

so zip_source_function() and zip_source_function_create() both do the same core thing: they take your function fn and turn it into a zip source. and fn has to be exactly this type, no substitutions bestie:

typedef zip_int64_t (*zip_source_callback)(void *userdata, void *data,
zip_uint64_t len, zip_source_cmd_t cmd)

archive or error are just there so errors have somewhere to go — they can be NULL if you don't care. 🙈

when the library calls your function, the first argument is whatever userdata you handed over. the next two are a buffer data of size len — that shows up when data is being passed in or is expected back — otherwise you get NULL and 0. and the last one, cmd, tells your function which action it's supposed to perform. it's giving "you have one job". ✨

depending on how you're using this, there are three useful sets of commands a zip_source_callback() might need to support:

• read source — you're providing streamed data (like for file data added to archives). must support ZIP_SOURCE_OPEN, ZIP_SOURCE_READ, ZIP_SOURCE_CLOSE, ZIP_SOURCE_STAT, and ZIP_SOURCE_ERROR.
  • also: if your source uses any allocated memory (including userdata) it should also implement ZIP_SOURCE_FREE so you don't leak memory. no cap, leaks are not the vibe. 💀
• seekable read source — same as the previous one, but from a source that lets you read from arbitrary offsets (also for a read-only zip archive). must additionally support ZIP_SOURCE_SEEK, ZIP_SOURCE_TELL, and ZIP_SOURCE_SUPPORTS.
• read/write source — same as previous, but now you can write too (also for writable zip archives). must additionally support ZIP_SOURCE_BEGIN_WRITE, ZIP_SOURCE_COMMIT_WRITE, ZIP_SOURCE_ROLLBACK_WRITE, ZIP_SOURCE_SEEK_WRITE, ZIP_SOURCE_TELL_WRITE, and ZIP_SOURCE_REMOVE.
  • and on top of all of that, supporting the pseudo-command ZIP_SOURCE_SUPPORTS_REOPEN lets you call zip_source_open() again after calling zip_source_close(). re-opening era. 🎀

---

🌈 ZIP_SOURCE_ACCEPT_EMPTY 🌈

return 1 if an empty source should be accepted as a valid zip archive. this is the default if this command isn't supported by a source. file system backed sources should return 0.

🦋 ZIP_SOURCE_BEGIN_WRITE 🦋

get the source ready for writing. use this to create any temporary file(s).

⭐ ZIP_SOURCE_BEGIN_WRITE_CLONING ⭐

get the source ready for writing, but keep the first len bytes of the original file. only implement this command if it's actually more efficient than copying the data, and if it doesn't destructively overwrite the original file (you still have to be able to execute ZIP_SOURCE_ROLLBACK_WRITE, so like... be careful bestie).

the next write should happen at byte offset.

💜 ZIP_SOURCE_CLOSE 💜

reading is done. that's it. bye. 👋

🔥 ZIP_SOURCE_COMMIT_WRITE 🔥

finish writing to the source. replace the original data with the newly written data. clean up temporary files or internal buffers. after this, opening and reading from the source should give you the newly written data.

💖 ZIP_SOURCE_ERROR 💖

get error info. data points to an array of two ints, which should be filled with the libzip error code and the corresponding system error code for whatever error happened. see zip_errors(3) for the deets on error codes. if the source stores error information in a zip_error_t, use zip_error_to_data(3) and return its return value. otherwise, return 2 * sizeof(int).

🎀 ZIP_SOURCE_FREE 🎀

clean up and free all the resources, including userdata. the callback function will not be called again — this is the finale, periodt.

🌸 ZIP_SOURCE_GET_FILE_ATTRIBUTES 🌸

provide information about various data. put the data in the appropriate entry in the zip_file_attributes_t argument that got passed in, and the appropriate ZIP_FILE_ATTRIBUTES_* value must be or'ed into the valid member to denote that the corresponding data has been provided. you can initialize a zip_file_attributes_t structure with zip_file_attributes_init(3).

• ASCII mode — if a file is a plaintext file in ASCII. can be used by extraction tools to automatically convert line endings (part of the internal file attributes). member ascii, flag ZIP_FILE_ATTRIBUTES_ASCII.
• General Purpose Bit Flags (limited to Compression Flags) — the general purpose bit flag in the zip in the local and central directory headers contain information about the compression method. member general_purpose_bit_flags and general_purpose_bit_mask to denote which members have been set; flag ZIP_FILE_ATTRIBUTES_GENERAL_PURPOSE_BIT_FLAGS.
• External File Attributes — the external file attributes (usually operating system-specific). member external_file_attributes, flag ZIP_FILE_ATTRIBUTES_EXTERNAL_FILE_ATTRIBUTES.
• Version Needed — a minimum version needed required to unpack this entry (in the usual "major * 10 + minor" format). member version_needed, flag ZIP_FILE_ATTRIBUTES_VERSION_NEEDED.
• Operating System — one of the operating systems as defined by the ZIP_OPSYS_* variables (see zip.h). this value affects the interpretation of the external file attributes. member host_system, flag ZIP_FILE_ATTRIBUTES_HOST_SYSTEM.

🫶 ZIP_SOURCE_OPEN 🫶

prepare for reading. get comfy. 📖

🍓 ZIP_SOURCE_READ 🍓

read data into the buffer data of size len. return the number of bytes placed into data on success, and zero for end-of-file.

💀 ZIP_SOURCE_REMOVE 💀

remove the underlying file. this gets called if a zip archive is empty when closed.

🧚 ZIP_SOURCE_ROLLBACK_WRITE 🧚

abort writing to the source. discard written data. clean up temporary files or internal buffers. after this, opening and reading from the source should give you back the original data. we love a good undo. ↩️

✨ ZIP_SOURCE_SEEK ✨

specify the position to read the next byte from, like fseek(3). use ZIP_SOURCE_GET_ARGS(3) to decode the arguments into this struct:

struct zip_source_args_seek {
    zip_int64_t offset;
    int whence;
};

if the size of the source's data is known, use zip_source_seek_compute_offset(3) to validate the arguments and compute the new offset.

🎀 ZIP_SOURCE_SEEK_WRITE 🎀

specify the position to write the next byte to, like fseek(3). see ZIP_SOURCE_SEEK for details.

🌟 ZIP_SOURCE_STAT 🌟

get meta information for the input data. data points to an allocated struct zip_stat, which should be initialized using zip_stat_init(3) and then filled in.

for uncompressed, unencrypted data, all information is optional. but like, fill in as much info as is readily available, bestie, it's free.

if the data is compressed, ZIP_STAT_COMP_METHOD, ZIP_STAT_SIZE, and ZIP_STAT_CRC must be filled in.

if the data is encrypted, ZIP_STAT_ENCRYPTION_METHOD, ZIP_STAT_COMP_METHOD, ZIP_STAT_SIZE, and ZIP_STAT_CRC must be filled in.

information that's only available after the source has been read (e.g., size) can be omitted in an earlier call. NOTE: zip_source_function() may be called with this argument even after being called with ZIP_SOURCE_CLOSE. yeah, she's like that.

return sizeof(struct zip_stat) on success.

💜 ZIP_SOURCE_SUPPORTS 💜

return a bitmap specifying which commands are supported. use zip_source_make_command_bitmap(3). if this command isn't implemented, the source is assumed to be a read source without seek support.

🌈 ZIP_SOURCE_TELL 🌈

return the current read offset in the source, like ftell(3).

🦋 ZIP_SOURCE_TELL_WRITE 🦋

return the current write offset in the source, like ftell(3).

🔥 ZIP_SOURCE_WRITE 🔥

write data to the source. return the number of bytes written.

👑 ZIP_SOURCE_SUPPORTS_REOPEN 👑

this command is never actually invoked — support for it just signals the ability to handle multiple open/read/close cycles.

---

💅 Return Values 💅

commands should return -1 on error. ZIP_SOURCE_ERROR will be called to retrieve the error code. on success, commands return 0, unless it says otherwise up in the description above.

🌸 Calling Conventions 🌸

the library will always issue ZIP_SOURCE_OPEN before issuing ZIP_SOURCE_READ, ZIP_SOURCE_SEEK, or ZIP_SOURCE_TELL. when it no longer wants to read from this source, it'll issue ZIP_SOURCE_CLOSE. if the library wants to read the data again, it'll issue ZIP_SOURCE_OPEN a second time. if your function can't provide the data again, it should return -1.

ZIP_SOURCE_BEGIN_WRITE or ZIP_SOURCE_BEGIN_WRITE_CLONING will be called before ZIP_SOURCE_WRITE, ZIP_SOURCE_SEEK_WRITE, or ZIP_SOURCE_TELL_WRITE. when writing is complete, either ZIP_SOURCE_COMMIT_WRITE or ZIP_SOURCE_ROLLBACK_WRITE will be called.

ZIP_SOURCE_ACCEPT_EMPTY, ZIP_SOURCE_GET_FILE_ATTRIBUTES, and ZIP_SOURCE_STAT can be issued at any time.

ZIP_SOURCE_ERROR will only be issued in response to the function returning -1.

ZIP_SOURCE_FREE will be the last command issued; if ZIP_SOURCE_OPEN was called and succeeded, ZIP_SOURCE_CLOSE will be called before ZIP_SOURCE_FREE, and similarly for ZIP_SOURCE_BEGIN_WRITE or ZIP_SOURCE_BEGIN_WRITE_CLONING and ZIP_SOURCE_COMMIT_WRITE or ZIP_SOURCE_ROLLBACK_WRITE. she always cleans up after herself. 💖

---

⭐ 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's NULL).

🚨 ERRORS 🚨

zip_source_function() fails if:

• [ZIP_ER_MEMORY] — required memory could not be allocated. 😭 (this is the only one, bestie)

👀 SEE ALSO 👀

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

📜 HISTORY 📜

zip_source_function() and zip_source_function_create() were added in libzip 1.0. throwback era.

🫶 AUTHORS 🫶

Dieter Baron <dillo@nih.at> and Thomas Klausner <wiz@gatalith.at>. absolute legends, we stan. 👑

---

and that's the whole page, babe — brought to you by the Debian crew, this version is from January 5, 2023, and it lives at ZIP_SOURCE_FUNCTION(3) in the Library Functions Manual. go write your callback, you've got this. 💖✨🎀🦋