ARCHIVE_UTIL(3)

💅 ARCHIVE_UTIL(3) — the libarchive utility functions, bestie edition

okay so this is ARCHIVE_UTIL(3), section 3 of the Library Functions Manual, and it's literally the page where all of libarchive's little helper functions live. they don't do the big dramatic archive stuff, they just hand you the tea about what's going on inside your struct archive object. and honestly? iconic behavior. 🫶

---

📚 LIBRARY

Streaming Archive Library (libarchive, -larchive)

---

✨ SYNOPSIS ✨

#include <archive.h>

void
archive_clear_error(struct archive *);

int
archive_compression(struct archive *);

const char *
archive_compression_name(struct archive *);

void
archive_copy_error(struct archive *, struct archive *);

int
archive_errno(struct archive *);

const char *
archive_error_string(struct archive *);

int
archive_file_count(struct archive *);

int
archive_filter_code(struct archive *, int);

int
archive_filter_count(struct archive *, int);

const char *
archive_filter_name(struct archive *, int);

int
archive_format(struct archive *);

const char *
archive_format_name(struct archive *);

int64_t
archive_position(struct archive *, int);

void
archive_set_error(struct archive *, int error_code, const char *fmt,
    ...);

---

🦋 DESCRIPTION 🦋

so these functions are all about getting information out of the struct archive object you're using with the libarchive(3) library. they're the little side-eye glances into what your archive handle is thinking. no cap. 💜

• archive_clear_error() — wipes any leftover error info from a previous call. bestie, this is not generally used in client code, so don't come for me if you've never touched it. it just clears the slate. ✨
• archive_compression() — literally just a synonym for archive_filter_code(a, 0). same energy, different name.
• archive_compression_name() — synonym for archive_filter_name(a, 0). matching set 🎀
• archive_copy_error() — copies the error info from one archive to another. passing the drama along, respectfully.
• archive_errno() — gives you back a numeric error code (see errno(2)) that tells you why the most recent error return happened. ⚠️ but be careful: this can not be reliably used to detect whether an error has occurred. it's only valid after another libarchive function has already returned an error status. so don't use it as your error detector, use it as your error explainer. iykyk.
• archive_error_string() — returns a textual error message that's suitable for display. and it's usually more specific than what you'd get by passing the result of archive_errno() to strerror(3). so like, it actually tells you what went down instead of being vague. 💅
• archive_file_count() — returns a count of how many files this archive object has processed. the count goes up when you call archive_write_header(3) or archive_read_next_header(3). keeping score fr fr.
• archive_filter_code() — returns a numeric code identifying the filter you point at. see archive_filter_count() for how the numbering works. 🔢
• archive_filter_count() — returns how many filters are in the current pipeline. for read archive handles, these filters get added automatically by the automatic format detection. for write archive handles, they get added by calls to the various archive_write_add_filter_XXX() functions. the filters in the resulting pipeline are numbered so that filter 0 is the filter closest to the format handler. and as a lil convenience, functions that expect a filter number will accept -1 as a synonym for the highest-numbered filter. 🎁

example time, because this is the part that makes it click: when you're reading a uuencoded gzipped tar archive, there are three filters — filter 0 is the gunzip filter, filter 1 is the uudecode filter, and filter 2 is the pseudo-filter that wraps the archive read functions. so in that case, requesting archive_position(a, -1) would be a synonym for archive_position(a, 2), which would return the number of bytes currently read from the archive. meanwhile archive_position(a, 1) would return the number of bytes after uudecoding, and archive_position(a, 0) would return the number of bytes after decompression. layers, bestie. onion energy. 🧅✨

• archive_filter_name() — returns a textual name identifying the indicated filter. again, see archive_filter_count() for the numbering deets. 🏷️
• archive_format() — returns a numeric code indicating the format of the current archive entry. this value gets set by a successful call to archive_read_next_header(). and heads up: it's super common for this value to change from entry to entry. like, a tar archive might have several entries that use GNU tar extensions and several entries that don't — those entries will have totally different format codes. main character entries with main character codes. 👑
• archive_format_name() — a textual description of the format of the current entry. the vibe check of the format, basically. 🌸
• archive_position() — returns the number of bytes read from or written to the indicated filter. specifically, archive_position(a, 0) returns the number of bytes read or written by the format handler, while archive_position(a, -1) returns the number of bytes read or written to the archive. see archive_filter_count() for the numbering details here too. 📏
• archive_set_error() — sets the numeric error code and error description that archive_errno() and archive_error_string() will later hand back. you should use this function within I/O callbacks to set system-specific error codes and error descriptions. it accepts a printf-like format string and arguments. 🚨 but — and this is the important part — you should be careful to use only the following printf format specifiers: %c, %d, %jd, %jo, %ju, %jx, %ld, %lo, %lu, %lx, %o, %u, %s, %x, %%. field-width specifiers and other printf features are not uniformly supported and should not be used. periodt. don't get creative with your format strings, bestie, it will not slay. 💀

---

👀 SEE ALSO

archive_read(3), archive_write(3), libarchive(3), printf(3)

---

🌈 HISTORY

The libarchive library first appeared in FreeBSD 5.3. a whole era. ⭐

---

🫶 AUTHORS

The libarchive library was written by Tim Kientzle <kientzle@acm.org>. ty for your service, king. 👑

---

and that's the whole page, bestie — this version is from Debian, dated February 2, 2012, filed under ARCHIVE_UTIL(3) in section 3 of the Library Functions Manual. go forth and archive responsibly 💖🎀🦋