ZIP_GET_NAME(3)

💖 ZIP_GET_NAME(3) 💖

okay bestie, welcome to ZIP_GET_NAME(3), part of the Library Functions Manual 🎀 — yes this is the libzip girlies' section of the manual, and today we're learning how to get a filename out of a zip archive by index. it's giving gatekeeping the file list? not anymore ✨

---

🌸 NAME 🌸

zip_get_name — get name of file by index 💅

---

📚 LIBRARY 📚

libzip (-lzip) — you already know her 🫶

---

✨ SYNOPSIS ✨

#include <zip.h>

const char *
zip_get_name(zip_t *archive, zip_uint64_t index, zip_flags_t flags);

---

🦋 DESCRIPTION 🦋

so. the zip_get_name() function returns the name of the file sitting at position index inside archive. like, "who's that file at slot 7" and she tells you. 💫

the name comes back in UTF-8 encoding unless you specified ZIP_FL_ENC_RAW (more on that in a sec, keep reading bestie).

if flags is set to ZIP_FL_UNCHANGED, you get the original, untouched filename back. the OG one. and listen — the returned string must not be modified or freed, and it becomes invalid the moment archive is closed. so don't be out here editing it or holding onto it after the archive's gone, that's not the vibe. 💀

and btw, these flags are also supported:

• ZIP_FL_ENC_RAW — return the unmodified names exactly as they are in the ZIP archive. no glow-up, no conversion, raw as she came. 🍓
• ZIP_FL_ENC_GUESS — this is the default ✨. it guesses the encoding of the name in the ZIP archive and converts it to UTF-8 if that's needed. (heads up: only CP-437 and UTF-8 get recognized — the rest are on their own fr.)
• ZIP_FL_ENC_STRICT — follow the ZIP specification properly and expect CP-437 encoded names in the ZIP archive, except when they're explicitly marked as UTF-8. then convert it to UTF-8. 📏

Note: ASCII is a subset of both CP-437 and UTF-8. so like, the overlap is real, iykyk 🧚

---

🔥 RETURN VALUES 🔥

upon successful completion, a pointer to the name is returned. slay. 👑

otherwise? NULL, and the error code inside archive gets set to indicate the error. not the ending we wanted but okay. 😭

---

💀 ERRORS 💀

zip_get_name() fails if:

• [ZIP_ER_DELETED] — index refers to a file that has been deleted (see zip_delete(3)). she's gone, bestie, you can't get her name. 👻
• [ZIP_ER_INVAL] — index is not a valid file index in archive, or index points to an added file and ZIP_FL_UNCHANGED is set. invalid, no cap. 🚫
• [ZIP_ER_MEMORY] — required memory could not be allocated. the RAM said no. 🙈

---

👀 SEE ALSO 👀

libzip(3), zip_name_locate(3) — go read those too, they're icons in their own right 💖

---

📜 HISTORY 📜

zip_get_name() was added in libzip 0.6. then in libzip 0.10 the type of index got changed from int to zip_uint64_t. and in libzip 0.11 the type of flags got changed from int to zip_flags_t. glow-up after glow-up, honestly. ✨

---

👑 AUTHORS 👑

Dieter Baron <dillo@nih.at> and Thomas Klausner <wiz@gatalith.at> — the actual main characters, we stan 🫶💜

---

and that's the whole page babes 💅 this one came from Debian, dated September 22, 2020, and it's filed under ZIP_GET_NAME(3) — go forth and get those names, you got this 🦋🌈⭐