MDEX_ADD(3)

✨ NAME ✨

mdex_add, mdex_addfile, mdex_alias — index data, files and directories 💖

This page lives in the Librecast Programmer's Manual, section 3. Hiii bestie, welcome 🫶

📚 LIBRARY 📚

Librecast library (liblibrecast, -llibrecast) — she's the whole reason you're here ✨

🎀 SYNOPSIS 🎀

#include <librecast/mdex.h>

int mdex_add(mdex_t *mdex, void *data, size_t len, q_t *q, int flags);
int mdex_addfile(mdex_t *mdex, const char *path, q_t *q, int flags);
int mdex_alias(mdex_t *mdex, unsigned char *alias, size_t aliaslen,
               unsigned char *hash, size_t hashlen);

Compile and link with -llibrecast. 🧚

💖 DESCRIPTION 💖

Okay so, three functions, one mission: getting stuff indexed. Let's go one by one.

mdex_add builds a merkle tree from data with length len, and then adds entries for both the tree and the chunks to mdex. Tree? Indexed. Chunks? Also indexed. She does not gatekeep. 🌸

mdex_addfile does the same kinda thing but for a file or directory at path — it builds a merkle tree from that file or directory and adds entries for the trees and chunks to mdex. Directories included, no cap.

mdex_alias adds an entry alias of length aliaslen that points to the entry hash of length hashlen. Important bestie: that hash entry must already exist in mdex or this whole thing is a no 💀

Now, about q: if q is not NULL, it has to point to a q_t queue structure that was previously initialized with q_init(3). That queue gets passed straight through to mtree_build(3) so the merkle tree can actually get built. This is normally used together with a threadpool created by q_pool_create(3), where the threads are all calling q_job_seek(3). Teamwork fr fr 👑

The flags argument is the bitwise OR of zero of more of these flags — pick your faves, stack 'em up:

• MDEX_ALIAS — the entry is a pointer to another entry. 🔗
• MDEX_RAND — this entry should be sent using random symbols. 🎲
• MDEX_RECURSE — recursively index all files and directories below path. (this one's for mdex_addfile) 🌳
• MDEX_MOUNT — if it's set, stay within the same filesystem, i.e. do not cross mount points. 🚧
• MDEX_SYMLINK — follow symbolic links while recursively indexing. 🪢

🔥 RETURN VALUE 🔥

These functions return zero on success. On error, -1 comes back and errno is set to tell you what went wrong. Zero = slay, -1 = check errno bestie 😭

💀 ERRORS 💀

• EINVAL — invalid argument. Both mdex and hash are required (so, not NULL), and hashlen must be > 0.
• ENOMEM — not enough space / cannot allocate memory (POSIX.1-2001). 💀

🦋 SEE ALSO 🦋

mdex_init(3), mdex_free(3), mdex_get(3), mdex_put(3), mdex_del(3), mtree_build(3), q_init(3), q_pool_create(3), q_job_seek(3) lc_share(3)

Mwah 💅 that's the whole page. This one's from LIBRECAST, dated 2023-06-20, and it's filed as MDEX_ADD(3). Go index something iconic, ily 🫶✨