ARCHIVE_READ_EXTRACT(3)

📦 version 15.1, in freebsd 14.5, freebsd 15.1

💅 ARCHIVE_READ_EXTRACT — Library Functions Manual 💅

ok so bestie, we're in section 3 of the libarchive manual and this page is literally all about the archive_read_extract girlies 🫶 three whole functions, one gorgeous job: pulling entries out of a streaming archive and dropping them onto your disk. no cap.

✨ LIBRARY ✨

Streaming Archive Library (libarchive, -larchive) 🌸

🌈 SYNOPSIS 🌈

#include <archive.h>

int
archive_read_extract(struct archive *, struct archive_entry *,
    int flags);

int
archive_read_extract2(struct archive *src, struct archive_entry *,
    struct archive *dest);

void
archive_read_extract_set_progress_callback(struct archive *,
    void (*func)(void *), void *user_data);

look at those signatures. iconic. copy them exactly, they don't play 💅

🎀 DESCRIPTION 🎀

archive_read_extract(), archive_read_extract_set_skip_file()

okay so this one is the convenience function, the main character fr — it wraps the corresponding archive_write_disk(3) interfaces so you don't have to do it yourself. the very first time you call archive_read_extract(), it creates a restore object for you using archive_write_disk_new(3) and archive_write_disk_set_standard_lookup(3), and then it transparently goes ahead and invokes archive_write_disk_set_options(3), archive_write_header(3), archive_write_data(3), and archive_write_finish_entry(3) to create the entry on disk and copy the data into it. the flags argument gets passed unmodified straight to archive_write_disk_set_options(3). no edits, no vibes-based filtering, just straight through.

archive_read_extract2()

this is the other version of archive_read_extract(), and the whole point is that you provide your own restore object. why would you wanna do that? because it lets you override the standard lookup functions using archive_write_disk_set_group_lookup(3) and archive_write_disk_set_user_lookup(3). slay, custom ownership mapping. 🧚

heads up bestie: archive_read_extract2() does not accept a flags argument. you gotta set the restore options yourself with archive_write_disk_set_options(). don't come crying to me when you pass four args and it gets mad 🙈

archive_read_extract_set_progress_callback()

this one sets a pointer to a user-defined callback that you can use for updating progress displays during extraction. very demure, very progress-bar. 💖

the progress function gets invoked during the extraction of large regular files, and it's invoked with the pointer you handed to this call. generally the data pointed to should include a reference to the archive object and the archive_entry object, so that you can retrieve various statistics for your progress display. give the people a percentage, they deserve it ✨

💜 RETURN VALUES 💜

most functions return zero on success and non-zero on error. the possible return codes are:

  • ARCHIVE_OK — the operation succeeded 🎉
  • ARCHIVE_WARN — the operation succeeded but a non-critical error was encountered 😬
  • ARCHIVE_EOF — end-of-archive was encountered 🌅
  • ARCHIVE_RETRY — the operation failed but can be retried 🔁
  • ARCHIVE_FATAL — there was a fatal error; the archive should be closed immediately 💀
ARCHIVE_FATAL is not a drill. close that archive. right now. periodt.

😭 ERRORS 😭

detailed error codes and textual descriptions are available from the archive_errno() and archive_error_string() functions. go read them, they will absolutely tell you what went wrong 🍓

🦋 SEE ALSO 🦋

and that's the whole page bestie, mwah 💋 this one's from the Debian crew and it's dated February 2, 2012 — so it's vintage, but it still ate, no cap. go extract something iconic 👑✨

📦 where this page comes from