Librecast is a project to provide fast, efficient and scalable communication by leveraging IPv6 multicast.
Go to file
Brett A C Sheffield 1a7c68c289 doc: mdex_add(3) - correction 2023-09-13 16:47:48 +02:00
doc doc: mdex_add(3) - correction 2023-09-13 16:47:48 +02:00
include fix function declarations with no prototype (void) 2023-09-13 13:48:46 +02:00
libs remove unused variable 2023-09-13 13:48:46 +02:00
src lc_share: ensure errno is set on error 2023-09-07 16:40:54 +02:00
test fix signedness in test integer comparisons 2023-09-13 14:04:51 +02:00
.gitignore clean up install target 2022-07-13 20:33:03 +02:00 v0.7.0 2023-08-22 18:54:10 +02:00 Propose COC/Contributer Covenant 2020-07-31 18:48:42 +02:00 s/principle/principal/ 2020-09-05 10:37:46 +01:00
COPYING Include both licenses with source 2021-04-21 20:36:03 +02:00 doc: update INSTALL instructions 2023-08-02 13:15:06 +02:00
LICENSE.GPL-2.0-only Include both licenses with source 2021-04-21 20:36:03 +02:00
LICENSE.GPL-3.0-only Include both licenses with source 2021-04-21 20:36:03 +02:00 make realclean 2023-08-16 20:18:25 +02:00 update README with new test runner commands 2023-05-07 19:14:53 +02:00
config.guess Add configure script 2022-07-01 17:34:16 +02:00
config.sub Add configure script 2022-07-01 17:34:16 +02:00
configure additional configure checks 2023-08-19 10:38:24 +02:00 additional configure checks 2023-08-19 10:38:24 +02:00
install-sh Add configure script 2022-07-01 17:34:16 +02:00

Librecast - Distributed Applications with IPv6 Multicast

Open Source Initiative Approved License logo

Librecast Logo

Coverity Scan Build Status Packaging status


Librecast is a project to provide fast, efficient and scalable communication by leveraging IPv6 multicast.

NB: the database functions have been removed from this branch pending a complete rewrite as part of the next milestone.


  • IPv6 and multicast supported from the outset
  • light, fast and simple design
  • scalability a design consideration from the outset

There are separate headers and shared libraries for:

  • IPv6 Multicast messaging
  • local database commands and querying
  • remote (multicast) database commands

The library will be extended soon to provide transitional support and tunnelling such that multicast can function as an overlay network until native multicast becomes more widely available.

Comments, questions, suggestions, bug reports, and patches welcome. See

Brett Sheffield <>


This work is dual-licensed under GPL 2.0 and GPL 3.0.

SPDX-License-Identifier: GPL-2.0-only OR GPL-3.0-only


IRC channel

#librecast on

If you have a question, please be patient. An answer might take a few hours depending on time zones and whether anyone on the team is available at that moment. Feel free to raise an issue on the bug tracker.


You can probably figure most things out by looking at the tests and header files. There are code samples in test/ that will show you how to do the most common things.

Remember to link your program with -llibrecast. If you're using librecast/db.h and librecast/netdb.h you'll also need -llsdb and -llcdb respectively.

Lets run through the basic concepts:

Getting started

In C, we'll need a header. Just the first one will do:

#include <librecast.h>        /* include all functions */

/* or */

#include <librecast/net.h>    /* just the network (multicast) bits */
#include <librecast/db.h>     /* local database functions */
#include <librecast/netdb.h>  /* remote (multicast) database functions */

/* or, if you just need to refer to a Librecast type in another project */

#include <librecast/types.h>  /* Librecast type declarations */

Everything starts with a Librecast Context:

lc_ctx_t *lctx;
lctx = lc_ctx_new();

lc_ctx_free(lctx); /* free it when done */

Then you probably want a Librecast Socket:

lc_socket_t *sock;
sock = lc_socket_new(lctx);

/* you can set whatever underlying socket options you want, such as TTL and LOOPBACK */
/* if you want to receive your own packets, you'll need this: */
lc_socket_setopt(sock, IPV6_MULTICAST_LOOP, &opt, sizeof(opt);

lc_socket_close(sock); /* close this when done */

Sockets aren't much use without Channels. A Channel, in Librecast terms, represents a multicast group. You create channels, bind them to sockets, and join those channels.

lc_channel_t *chan;
chan = lc_channel_new(lctx, "");

lc_channel_bind(sock, chan)  /* bind the channel to a socket */
lc_channel_bind(sock, chan2) /* you can bind more than one */

lc_channel_join(chan) /* we need to join a channel if we want to listen */
/* no need to join if we only want to send */

lc_channel_free(chan); /* free when done */

To listen on a channel and process messages, we can either use a synchronous call, or asyncronous with callbacks:

void callback_msg(lc_message_t *msg) {
	/* do something with message */

void callback_err() {
	/* handle error */

/* this starts a listening thread, with callbacks */
lc_socket_listen(sock, callback_msg, callback_err);

/* or, we can do a blocking recv */
size_t bytes = lc_msg_recv(sock, &msg);     /* blocking recv */

Now lets create a message and send it:

char data[] = "life, the universe, everything";
lc_message_t msg;
lc_msg_init_data(&msg, data, strlen(data), NULL, NULL);
lc_msg_send(chan, &msg);



Compilation and Testing Options

The code compiles using either gcc or clang. There is a make clang target. The default is whatever your default CC is.

NB: Gnu Make is required. On *BSD install and use gmake. The bash shell is also required for make test .


A test runner and a set of test modules exercise the main functions, including common error conditions.

Logs are output in the test directory (the tests tell you where). test/lastlog.log is a symlink to the logs from the last test run.

make test runs all tests. make memcheck runs all tests using valgrind to do leak checking and dynamic analysis.

Other useful make targets:

make test/0004 run a single test.

make memcheck/0004 run a single test with valgrind

make sparse compiles the project using cgcc (the sparse static analyser)

make clang builds the project using clang

make coverity builds the project using the coverity static analyser, creating a librecast.tgz ready to upload to Coverity Scan for analysis.

make net-setup create a virtual pair of connected network interfaces in their own namespaces for testing. (requires CAP_NET_ADMIN / root)

make net-teardown undoes make net-setup (requires CAP_NET_ADMIN / root)

make testshell remind me what to type to enter a test shell in the correct namespace

Questions, Bug reports, Feature Requests

New issues can be raised at:

It's okay to raise an issue to ask a question. You can also email or ask on IRC.

This project was funded through the NGI0 Discovery Fund, a fund established by NLnet with financial support from the European Commission's Next Generation Internet programme, under the aegis of DG Communications Networks, Content and Technology under grant agreement No 825322. *Applications are still open, you can apply today*

Logo NLnet: abstract logo of four people seen from above Logo NGI Zero: letterlogo shaped like a tag