MTBL_MERGE(1)

💖 mtbl_merge — the merge-y one 💖

okay so bestie, this is the mtbl_merge manual page, section 1 of the MTBL fam. sit down, grab a lil drink, we're merging data 💅

---

✨ NAME ✨

mtbl_merge — merge MTBL data from multiple input files into a single output file 🫶

---

🌸 SYNOPSIS 🌸

First up, the user-provided functions, and yes you literally have to write these, they're not optional vibes:

typedef void *
(*mtbl_merge_init_func)(void);

typedef void
(*mtbl_merge_free_func)(void *clos);

typedef void
(*mtbl_merge_func)(void *clos,
        const uint8_t *key, size_t len_key,
        const uint8_t *val0, size_t len_val0,
        const uint8_t *val1, size_t len_val1,
        uint8_t **merged_val, size_t *len_merged_val);

and then the command line tool itself, she's giving very much:

export MTBL_MERGE_DSO="libexample.so.0"
export MTBL_MERGE_FUNC_PREFIX="example_merge"
mtbl_merge [-b SIZE] [-c COMPRESSION] [-l LEVEL] INPUT [INPUT]... OUTPUT

---

🦋 DESCRIPTION 🦋

So mtbl_merge(1) is a command-line driver for the mtbl_merger(3) interface. and here's the thing — the mtbl_merger(3) interface needs a user-provided merge function. like, it cannot function without you. main character energy but for you. that merge function gets loaded from a shared object, and the filename of that shared object comes from the environment variable MTBL_MERGE_DSO. no cap.

Your user-provided merge function has to have the same type as the mtbl_merge_func function type up there in the synopsis 👆. The symbol name of the merge function that gets loaded out of your user-provided DSO is built by appending "_func" to the string you put in the MTBL_MERGE_FUNC_PREFIX environment variable — and that variable must be non-empty, fr fr, don't leave it blank.

Also, bonus round: you can optionally provide two more functions 🎀

1. an "init" function, whose symbol name is "_init" appended to the function prefix
2. a "free" function, whose symbol name is "_free" appended to the function prefix

If the "init" function exists, it gets called at the beginning — before any calls to the merge function — and its return value gets passed as the first argument to the merge function. and if the "free" function exists, it gets called at the end, after any calls to the merge function, and its argument is the return value of the "init" function. cute lil lifecycle, honestly obsessed 💜

And one more: the environment variable MTBL_MERGE_BLOCK_SIZE may optionally be set, if you wanna configure the MTBL block size (in bytes) of the output file. you don't have to! but you can ✨

---

👑 OPTIONS 👑

• -b SIZE — the uncompressed data block size hint for the output file, in bytes. if you don't specify it, the default is 8192 bytes (that's 8 kilobytes, bestie).
• -c COMPRESSION — the compression algorithm to use for data blocks in the output file. if you don't specify it, the default is zlib. wanna know what else you can pick? go read the mtbl_info(1) manpage, it's got the whole list of possible compression algorithms 🌈
• -l LEVEL — the numeric compression level that gets passed to the compression algorithm. and look, the default value and the valid range both depend on which compression algorithm you chose, so check accordingly 🙈

---

🧚 SEE ALSO 🧚

• mtbl_info(1)
• mtbl_merger(3)

---

okay that's the whole page, you ate it, you understood it, periodt 💅✨

this was the MTBL_MERGE(1) page, dated 10/21/2021 — love u, go merge something iconic 🫶🎀🦋