.TH LC_SHARE 3 2023-08-02 "LIBRECAST" "Librecast Programmer's Manual"
.SH NAME
lc_share, lc_unshare \- share and unshare files over multicast
.SH LIBRARY
Librecast library
.RI ( liblibrecast ", " \-llibrecast )
.SH SYNOPSIS
.nf
.B #include <librecast/net.h>
.PP
.BI "lc_share_t *lc_share(lc_ctx_t " *lctx ", mdex_t " *mdex ", unsigned int " ifx ",
.BI "                lc_stat_t " *stats ", lc_sync_options_t " *opt ", int " flags ");"
.BI "void lc_unshare(lc_share_t " *share ");"
.fi
.PP
Compile and link with \fI\-llibrecast\fP.
.SH DESCRIPTION
The
.BR lc_share
function shares the objects indexed in
.BR mdex
on the interface given by
.BR ifx .
If ifx is zero, the files are shared on all multicast-capable interfaces.
.PP
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
.IR 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.
.PP
The data sent is encoded using RaptorQ Forward Error Correction (see IETF RFC
6330), using the LCRQ library.
.PP
If
.IR stats
is not NULL, transfer statistics will be returned in this structure.
.PP
.IR opt
is not used, at present, and must be NULL for compatibility with future versions.
.PP
The
.I flags
argument is the bitwise OR
of zero of more of the following flags:
.TP
.BR LC_SHARE_LOOPBACK
Set the loopback option
.I IPV6_MULTICAST_LOOP
on the sending socket.
.SH RETURN VALUE
.BR lc_share ()
returns a pointer to a
.IR lc_share_t
handle, which should be freed by passing to
.BR lc_unshare ()
when done.
On error, NULL is returned, and
.I errno
is set to indicate the error.
.PP
The
.BR lc_unshare ()
function returns no value, and preserves
.IR errno .
.SH ERRORS
.TP
.BR ENOTSUP
.BR lc_share ()
is not supported with your current configuration. This error occurs
when the librecast library is built without MLD support.
.PP
.BR ENOMEM
Not enough space/cannot allocate memory (POSIX.1-2001).
.PP
.BR EACCES
Permission to create a socket of the specified type and/or protocol is denied.
.PP
.SH NOTES
.BR 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
.BR CAP_NET_RAW .
See
.BR Capabilities (7).
On *BSD the creation of a raw socket is restricted to the superuser.
An application can drop these privileges after calling
.BR lc_share .
.PP
To restrict syncing to a particular network interface, call
.BR lc_ctx_ifx (3)
to set the default interface for the Librecast context before calling the
appropriate sync function.
.PP
.SH SEE ALSO
.BR lc_ctx_new (3),
.BR lc_ctx_ifx (3),
.BR mdex_init (3),
.BR mdex_get (3),
.BR mdex_put (3),
.BR mdex_del (3),
.BR lcrq (7)