ARCHIVE_READ(3)

💖 ARCHIVE_READ(3) 💖

okay bestie, welcome to the libarchive streaming reader page — the manual name is ARCHIVE_READ and yes we're doing the whole thing together, no skimming, no skipping. grab a boba. 🧋

🌈 LIBRARY 🌈

Streaming Archive Library (libarchive, -larchive) — she's iconic, she's linked with -larchive, periodt. ✨

---

✨ SYNOPSIS ✨

#include <archive.h>

that's it. that's the include. she's low maintenance. 💅

---

🦋 DESCRIPTION 🦋

These functions hand you a complete API for reading streaming archives. The whole vibe is: first you create the struct archive object, set your options, initialize the reader, then you iterate over the archive headers and the data that comes with them, and finally you close the archive and release all the resources. That's the whole arc, bestie. 🌸

🎀 Create archive object

See archive_read_new(3).

To read an archive you literally have to first get yourself an initialized struct archive object from archive_read_new(). No object, no reading. it's giving "prerequisite". 🙈

🔥 Enable filters and formats

See archive_read_filter(3) and archive_read_format(3).

Then you can tweak that object for whatever you wanna do with the various archive_read_set_XXX() and archive_read_support_XXX() functions. And ngl, you will need to call the right archive_read_support_XXX() functions to turn on the compression and format support you want.

⚠️ Important thing to know: those support functions do two separate jobs — they pull the corresponding support code into your program (linking), AND they switch on the corresponding auto-detect code. Two jobs, one function, multitasking queen. 👑

Unless you've got specific constraints, you're gonna want to call archive_read_support_filter_all() and archive_read_support_format_all() so that auto-detect is on for every format and compression type the library currently supports. slay. 💜

🌟 Set options

See archive_read_set_options(3).

💫 Open archive

See archive_read_open(3).

Once your struct archive object is all prepped, you call archive_read_open() to actually open the archive and get it ready for reading. There are several variants of this function, and the most basic one wants you to hand over pointers to several functions that can produce blocks of bytes from the archive. But there are convenience forms too — ones that let you just specify a filename, a file descriptor, a FILE * object, or a block of memory to read the archive data from. 🫶

📝 Note: the core library makes no assumptions about how big the blocks being read are. Your callback functions are free to read whatever block size is most appropriate for the medium. your callback, your rules. ✨

💀 Consume archive

See archive_read_header(3), archive_read_data(3) and archive_read_extract(3).

Every archive entry is a header followed by a certain amount of data. You get the next header with archive_read_next_header(), which returns a pointer to a struct archive_entry structure holding info about the current archive element. If that entry is a regular file, the header is followed by the file data. 🍓

You can read that data from the archive with archive_read_data() — which works a lot like the read(2) system call — or with archive_read_data_block(), which gives you a slightly more efficient interface. ngl you might prefer the higher-level options instead:

• archive_read_data_skip() — reads and discards the data for this entry
• archive_read_data_into_fd() — copies the data to the file descriptor you provide
• archive_read_extract() — recreates the specified entry on disk and copies the data from the archive

👀 Lowkey important: archive_read_extract() uses the struct archive_entry structure you provide it, which may differ from the entry that was just read from the archive. Many applications will want to override the pathname, the file permissions, or the ownership. main character energy: you decide who you are. 💅

🧚 Release resources

See archive_read_free(3).

Once you're done reading data from the archive, you should call archive_read_close() to close the archive, and then call archive_read_free() to release all the resources, including all the memory the library allocated. clean up after yourself, bestie, the library is not your mom. 😭

---

⭐ EXAMPLES ⭐

The following illustrates basic usage of the library. In this example, the callback functions are simply wrappers around the standard open(2), read(2), and close(2) system calls. copy it, run it, obsessed. 🔥

      void
      list_archive(const char *name)
      {
        struct mydata *mydata;
        struct archive *a;
        struct archive_entry *entry;

        mydata = malloc(sizeof(struct mydata));
        a = archive_read_new();
        mydata->name = name;
        archive_read_support_filter_all(a);
        archive_read_support_format_all(a);
        archive_read_open(a, mydata, myopen, myread, myclose);
        while (archive_read_next_header(a, &entry) == ARCHIVE_OK) {
          printf("%s\n",archive_entry_pathname(entry));
          archive_read_data_skip(a);
        }
        archive_read_free(a);
        free(mydata);
      }

      la_ssize_t
      myread(struct archive *a, void *client_data, const void **buff)
      {
        struct mydata *mydata = client_data;

        *buff = mydata->buff;
        return (read(mydata->fd, mydata->buff, 10240));
      }

      int
      myopen(struct archive *a, void *client_data)
      {
        struct mydata *mydata = client_data;

        mydata->fd = open(mydata->name, O_RDONLY);
        return (mydata->fd >= 0 ? ARCHIVE_OK : ARCHIVE_FATAL);
      }

      int
      myclose(struct archive *a, void *client_data)
      {
        struct mydata *mydata = client_data;

        if (mydata->fd > 0)
          close(mydata->fd);
        return (ARCHIVE_OK);
      }

---

👑 SEE ALSO 👑

tar(1), archive_read_data(3), archive_read_extract(3), archive_read_filter(3), archive_read_format(3), archive_read_header(3), archive_read_new(3), archive_read_open(3), archive_read_set_options(3), archive_util(3), libarchive(3), tar(5)

the whole friend group, fr fr. 🫂

---

🌸 HISTORY 🌸

The libarchive library first appeared in FreeBSD 5.3. a true OG. 🎀

---

💜 AUTHORS 💜

The libarchive library was written by Tim Kientzle <kientzle@acm.org>. thank you king, we owe you everything 🙏✨

---

🩷 BUGS 🩷

Many traditional archiver programs treat empty files as valid empty archives. For example, many implementations of tar(1) let you append entries to an empty file. But of course — and this is the whole problem — it is impossible to determine the format of an empty file by inspecting the contents. So this library treats empty files as having a special "empty" format. no cap, that's just how it is. 💀

---

and that's the page bestie!! 💖 this one came from the Debian crew, dated February 2, 2012 — yes she's a 2012 baddie and she still eats. mwah, go read some archives, ily, bye!! 🦋💅✨