ARCHIVE_READ_DATA(3)

💖 ARCHIVE_READ_DATA 💖

okay bestie, so this is ARCHIVE_READ_DATA(3) — the libarchive streaming-archive-reading girlies. it's from the Library Functions Manual, and it's literally the four functions you need when you want to read data out of a streaming archive. no cap, this is the good stuff.

✨ NAME ✨

archive_read_data, archive_read_data_block, archive_read_data_skip, archive_read_data_into_fd — functions for reading streaming archives 🦋

📚 LIBRARY 📚

Streaming Archive Library (libarchive, -larchive) — link it and slay 💅

🌸 SYNOPSIS 🌸

#include <archive.h>

la_ssize_t
archive_read_data(struct archive *, void *buff, size_t len);

int
archive_read_data_block(struct archive *, const void **buff,
    size_t *len, off_t *offset);

int
archive_read_data_skip(struct archive *);

int
archive_read_data_into_fd(struct archive *, int fd);

like, #include <archive.h> first obviously, that's the vibe check 🎀

👑 DESCRIPTION 👑

okay so here's the tea on each one, bestie:

• archive_read_data() — reads the data associated with the header you just read. internally? it's giving convenience function energy: it calls archive_read_data_block() and then fills any gaps with nulls so that callers see one single continuous stream of data. smooth. continuous. iconic. ✨
• archive_read_data_block() — returns the next available block of data for this entry. and the way that it's different from archive_read_data() is that it avoids copying data and lets you correctly handle sparse files (as supported by some archive formats). the library guarantees that offsets will increase and that blocks will not overlap — periodt. note that the blocks returned from this function can be much larger than the block size read from disk, because of compression and internal buffer optimizations. so don't be shocked, it's normal 💀
• archive_read_data_skip() — a convenience function that repeatedly calls archive_read_data_block() to skip all of the data for this archive entry. and lowkey important: this function is invoked automatically by archive_read_next_header2() if the previous entry was not completely consumed. so it's doing it behind your back, in a helpful way 🫶
• archive_read_data_into_fd() — a convenience function that repeatedly calls archive_read_data_block() to copy the entire entry to the provided file descriptor. easy. clean. main character energy 👑

⭐ RETURN VALUES ⭐

most functions return zero on success, non-zero on error. the possible return codes include:

• 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. like, drop everything. close it. right now. 😭

and archive_read_data() specifically returns a count of bytes actually read, or zero at the end of the entry. on error, it returns a value of ARCHIVE_FATAL, ARCHIVE_WARN, or ARCHIVE_RETRY.

🍓 ERRORS 🍓

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

💀 SEE ALSO 💀

• tar(1)
• archive_read(3)
• archive_read_extract(3)
• archive_read_filter(3)
• archive_read_format(3)
• archive_read_header(3)
• archive_read_open(3)
• archive_read_set_options(3)
• archive_util(3)
• libarchive(3)
• tar(5)

that's the whole page bestie!! 💖 this one came from Debian and it's dated February 2, 2012 — so like, vintage but still slaying. go read some archives, ily, bye!! 🎀✨🦋