LC_SHARE(3)

NAME
lc_share, lc_unshare - share and unshare files over multicast

LIBRARY
Librecast library (liblibrecast, -llibrecast)

SYNOPSIS
#include <librecast/net.h>

lc_share_t *lc_share(lc_ctx_t *lctx, mdex_t *mdex, unsigned int ifx,
                lc_stat_t *stats, lc_sync_options_t *opt, int flags);
void lc_unshare(lc_share_t *share);

lc_share_t *lc_share_acquire(lc_share_t *share);
void lc_share_release(lc_share_t *share);

Compile and link with -llibrecast.

DESCRIPTION
The lc_share function shares the objects indexed in mdex on the interface given by ifx. If ifx is zero, the files are shared on all multicast-capable interfaces.

lc_share starts MLD snooping (see IETF RFC 3810). When a join on a new IPv6 multicast group is detected, this is checked against the index provided by mdex. If a matching object is found, this is added to the sending queue, and the data for this object continues to be sent until MLD reports that there are no more listeners for this group.

The data sent is encoded using RaptorQ Forward Error Correction (see IETF RFC 6330), using the LCRQ library.

If stats is not NULL, transfer statistics will be returned in this structure.

opt is not used, at present, and must be NULL for compatibility with future versions.

The flags argument is the bitwise OR of zero of more of the following flags:

LC_SHARE_LOOPBACK
    Set the loopback option IPV6_MULTICAST_LOOP on the sending socket.

The lc_share_acquire function increments the reader count on the share object. The object will not be freed until the reader count is zero. This is useful for keeping track of readers in a multithreaded program.

lc_share_release decrements the reader count on the share object. If the number of readers is zero, the object will be freed.

RETURN VALUE
lc_share() returns a pointer to a lc_share_t handle, which should be freed by passing to lc_unshare() when done. On error, NULL is returned, and errno is set to indicate the error.

The lc_unshare() function returns no value, and preserves errno.

ERRORS

ENOTSUP
    lc_share() is not supported with your current configuration. This error occurs when the librecast library is built without MLD support.

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.

NOTES
lc_share uses MLD snooping from libmld to detect which multicast groups are active, which uses a raw socket. On Linux, creating a raw socket requires CAP_NET_RAW. See Capabilities(7). On *BSD the creation of a raw socket is restricted to the superuser. An application can drop these privileges after calling lc_share.

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.

SEE ALSO
lc_ctx_new(3), lc_ctx_ifx(3), mdex_init(3), mdex_get(3), mdex_put(3), mdex_del(3), lcrq(7)