LC_SYNC(3)

🦋 LC_SYNC(3) — bestie edition 🦋

okay so this is page LC_SYNC(3) from the Librecast Programmer's Manual, and it's literally the page where you learn to sync memory or files over multicast. no cap, it's giving main character energy for distributed data. 💅

---

✨ NAME ✨

lc_sync, lc_syncfile — synchronize memory or files over multicast

---

📚 LIBRARY 📚

Librecast library (liblibrecast, -llibrecast)

---

🎀 SYNOPSIS 🎀

#include <librecast/sync.h>

ssize_t lc_sync(lc_ctx_t *lctx, unsigned char *hash, void *data, const size_t len,
                q_t *q, lc_stat_t *stats, lc_sync_options_t *opt, int flags);
ssize_t lc_syncfile(lc_ctx_t *lctx, unsigned char *hash, const char *pathname,
                q_t *q, lc_stat_t *stats, lc_sync_options_t *opt, int flags);
ssize_t lc_syncfilehash(lc_ctx_t *lctx, unsigned char *hash, const char *dst,
                q_t *q, lc_stat_t *stats, lc_sync_options_t *opt, int flags);

Compile and link with -llibrecast.

heads up bestie: when you build, you compile and link with -llibrecast. that's the whole vibe. 🫶

---

💖 DESCRIPTION 💖

so what do these even do

The lc_sync() function synchronizes the memory area pointed to by data of length len with data fetched from the network. 🌈

The lc_syncfile() function synchronizes the file at pathname with data fetched from the network. The file will be created if it does not exist. ✨

The lc_syncfile_hash() function synchronizes the file at pathname with data fetched from the network. The file will be created if it does not exist. If a trailing slash is present it is parsed and removed before calling lc_syncfile(3). Similar to rsync(3), the presence of a trailing slash on the source directory indicates that the directories synced are at the same level. The absence of a trailing slash on the source will cause the directory to be created as a subdirectory on the destination. (yes this is the exact same energy as rsync's slash drama, iykyk 💀)

---

the merkle tree of it all 🌳

hash is used to create the multicast address from which to fetch the merkle tree of the source data. This tree is compared to the merkle tree of the memory at data to find which chunks differ, and these chunks are fetched from the network using their hashes to create the multicast source addresses. obsessed with this actually. 🔥

---

the arguments, one by one 🧚

• lctx — a Librecast context, created with lc_ctx_new(3).
• q — if it's not NULL, it must point to a queue q_t structure previously initialized with q_init(3). This queue will have jobs enqueued to build the tree. This is normally used in conjunction with a threadpool created with q_pool_create(3) with threads all calling q_job_seek(3). 🧵
• q (when it's NULL) — if q is NULL, the creation and destruction of a queue and threadpool will be handled automatically. auto-pilot slay.
• stats — if it's not NULL, transfer statistics will be returned in this structure. 📊
• opt — not used, at present, and must be NULL for compatibility with future versions. don't be cute with it. 🚫
• flags — not used, at present, and must be zero for compatibility with future versions. same deal, bestie. 🚫

⚠️ like, genuinely: opt must be NULL and flags must be 0. it's a future-compatibility thing, not a suggestion. 💀

---

🫶 RETURN VALUE 🫶

These calls return the number of bytes received, or -1 if an error occurred. On error, NULL is returned, and errno is set to indicate the error. 😭

---

💀 ERRORS 💀

• EINVAL — Invalid argument.
• ENOMEM — Not enough space/cannot allocate memory (POSIX.1-2001).
• EACCES — Permission to create a socket of the specified type and/or protocol is denied.

also, lc_syncfile() can also fail with any of the errors for lc_mmapfile(3). so go read that page too, bestie. 🍓

---

👑 NOTES 👑

To restrict syncing to a particular network interface, call lc_ctx_ifx(3) to set the default interface for the Librecast context before calling the appropriate sync function. timing matters!! ⭐

---

🌸 SEE ALSO 🌸

lc_ctx_new(3), lc_ctx_ifx(3), lc_mmapfile(3), lc_share(3), mdex_init(3), mdex_free(3), mdex_add(3), mdex_addfile(3), mdex_alias(3), mdex_get(3), mdex_put(3), mdex_del(3), lcrq(7)

---

and that's the whole page, bestie!! 💜 this one's from the Librecast crew and it's dated 2025-06-09 — go forth and sync your little heart out. mwah. 💅✨🦋