MTBL(7)

💖 MTBL — like, the whole vibe 💖

okay bestie, sit down, hydrate, because we're about to talk about mtbl, aka section 7 of the manual, aka the immutable sorted string library. no cap. it's giving legendary. 🫶

✨ NAME ✨

mtbl — the immutable sorted string library. that's it, that's the name, iconic behavior honestly 👑

🌸 SYNOPSIS 🌸

#include <mtbl.h>

gcc [flags] files -lmtbl [libraries]

like yes, you include it, you link it, you go slay. -lmtbl is the link flag and she is required, do not forget her 💅

🦋 DESCRIPTION 🦋

so the mtbl library hands you interfaces for creating, searching, and merging Sorted String Table (SSTable) files in the MTBL format. and what's the tea with that format? it's an immutable mapping of keys to values. immutable means you can't change it after the fact — it's set in stone, main character energy forever. ✨

Sorted String Tables are compact and they give you fast random access to keys and key ranges. keys and values? arbitrary byte arrays, literally whatever bytes you want. but — and this is important — MTBL SSTables may not contain duplicate keys. not even one. the format said no duplicates, periodt. 💀

okay so the six main interfaces the mtbl library gives you are:

• mtbl_iter(3) — Iterator objects. they give you one consistent interface for iterating over the key-value entries that other interfaces hand back. so no matter who's feeding you data, the iterator vibe is the same 🎀
• mtbl_source(3) — Source objects. these give you functions for getting iterators out of some underlying data source. the mtbl_reader and mtbl_merger interfaces are the ones that hand you references to a source object. and every one of the source methods returns an mtbl_iter object. consistent. we love her. 🌈
• mtbl_reader(3) — Reader objects. read-only access to MTBL files. look, don't touch 🧚
• mtbl_writer(3) — Writer objects. these initialize a brand new MTBL file from a sequence of key-value entries that you the caller provide. but heads up bestie: keys must be in sorted order based on lexicographical byte value, and keys may not be duplicated. sort first, write second, that's the rule 🔥
• mtbl_merger(3) — Merger objects. these take multiple sequences of key-value entries from one or more mtbl_source objects and combine them into one single, sorted sequence. and the combined, merged output sequence? you get it via the mtbl_source interface. gluing it all together, so satisfying 😭
• mtbl_sorter(3) — Sorter objects. these take a sequence of key-value entries from the caller and hand them back in sorted order. but here's the catch — you must provide a callback function to merge values when entries have duplicate keys. you have to tell her what to do with the dupes. then the sorted output sequence can be retrieved via the mtbl_iter interface, or dumped straight into an mtbl_writer object. two paths, both valid 💜
• mtbl_fileset(3) — Fileset objects. these automatically maintain an mtbl_source built on top of the mtbl_merger and mtbl_reader interfaces. and the set of underlying mtbl_reader objects? it stays synchronized with a "setfile" on disk that lists the MTBL files. it keeps itself in sync, lowkey the most self-sufficient one here ⭐

ngl, the original says "six main interfaces" and then lists seven. we are not fixing that, we are simply noting it and moving on. the manpage said what it said 💅

and additionally, several utility interfaces are provided:

• mtbl_crc32c(3) — calculates the CRC32C checksum of a byte array. checksums, checksums, get you a girl who can checksum 🔍
• mtbl_fixed(3) — functions for fixed-width encoding and decoding of 32 and 64 bit integers. 32 and 64. both. she does both 🌟
• mtbl_varint(3) — functions for varint encoding and decoding of 32 and 64 bit integers. yes, also 32 and 64, also both. the fixed and the varint are sisters, iykyk 🍓

👑 the cute lil sign-off 👑

this whole page is dated 01/31/2014 and it comes from the MTBL(7) manual page itself. like, this page has been serving since 2014 and she's still here. legacy. icon. we simply have to respect it 💖

go read the rest, bestie, you got this 🫶✨