MTBL_READER(3)

💖 MTBL_READER 💖

okay bestie, gather round, because today we're learning about mtbl_reader — the little handle that lets you read an MTBL file. yes, from the mtbl manual, section 3. this is the whole entire page, no skips, no crumbs left behind. 🎀

---

✨ NAME ✨

mtbl_reader — read an MTBL file. that's it, that's the whole job. iconic behavior honestly. 💅

---

🌸 SYNOPSIS 🌸

first things first, you gotta invite the library to the party:

#include <mtbl.h>

🦋 Reader objects

struct mtbl_reader *
mtbl_reader_init(const char *fname, const struct mtbl_reader_options *ropt);

struct mtbl_reader *
mtbl_reader_init_fd(int fd, const struct mtbl_reader_options *ropt);

void
mtbl_reader_destroy(struct mtbl_reader **r);

const struct mtbl_source *
mtbl_reader_source(struct mtbl_reader *r);

const struct mtbl_metadata *
mtbl_reader_metadata(struct mtbl_reader *r);

🦋 Reader options

struct mtbl_reader_options *
mtbl_reader_options_init(void);

void
mtbl_reader_options_destroy(struct mtbl_reader_options **ropt);

void
mtbl_reader_options_set_verify_checksums(
        struct mtbl_reader_options *ropt,
        bool verify_checksums);

void
mtbl_reader_options_set_madvise_random(
        struct mtbl_reader_options *ropt,
        bool madvise_random);

---

👑 DESCRIPTION 👑

so here's the tea. to read an MTBL file you make an mtbl_reader object, then you call mtbl_reader_source() to get yourself an mtbl_source handle, and then you use the whole mtbl_source(3) interface to actually read entries. that's the pipeline, periodt. ✨

you've got two ways to make an mtbl_reader:

• call mtbl_reader_init() with an fname argument — that's the filename you want opened
• or call mtbl_reader_init_fd() with an fd argument — that's an open, readable file descriptor, and yes it must be readable, no cap

and here's the cute part: MTBL files are immutable, so the exact same MTBL file can be opened and read from concurrently by independent threads or processes. literally no drama, no locking, no fighting. sharing is caring. 🫶

if the ropt parameter you hand to mtbl_reader_init() or mtbl_reader_init_fd() is non-NULL, then all the parameters you set in that mtbl_reader_options object get configured into your mtbl_reader object. if it's NULL, you're just running stock. 🙈

file-level metadata? that's the mtbl_metadata(3) interface, and you get to it via the object returned by mtbl_reader_metadata().

⚠️ bestie listen to me: that metadata object is valid only as long as the reader object exists. the moment your reader dips, the metadata is gone. do not be out here holding onto a metadata pointer after the reader is destroyed, i am begging. 😭

🌈 Reader options

⭐ verify_checksums

this one is the vibe check for your data. it specifies whether or not the CRC32C checksum on the index block and each data block should be verified or not.

• if verify_checksums is enabled and there's a checksum mismatch — that's a fatal runtime error. not a warning, not a little note, a whole fatal runtime error. 💀
• the default is to not verify index or data block checksums.

⭐ madvise_random

this one specifies whether the kernel should be advised if the data access patterns are expected to be random or not. and lowkey? this may hurt some workloads but help others. it's giving "it depends". 🤷

• the default is to not set this advisory information.
• this option can be explicitly overridden by setting the environment variable MTBL_READER_MADVISE_RANDOM to the string "0" (force disable) or "1" (force enable). so you can just vibe-check it from the environment if you want.
• and important: this option only has any effect on systems that have the posix_madvise or madvise system calls. if your system doesn't have them, this option is just sitting there looking pretty. 🎀

---

💅 RETURN VALUE 💅

• mtbl_reader_init() and mtbl_reader_init_fd() return NULL on failure, and non-NULL on success.

so like, always check your pointer, bestie. NULL means it did not slay. 🔥

---

that's the whole page, and it came from the MTBL_READER(3) manual, dated 11/14/2022. mwah, go read some files, ily, bye! 💖✨🎀🦋🌸💅🫶