.TH MDEX_GET 3 2023-06-20 "LIBRECAST" "Librecast Programmer's Manual"
.SH NAME
mdex_get \- retrieve an entry from a multicast index
.SH LIBRARY
Librecast library
.RI ( liblibrecast ", " \-llibrecast )
.SH SYNOPSIS
.nf
.B #include <librecast/mdex.h>
.PP
.BI "int mdex_get(mdex_t " *mdex ", unsigned char " *hash ", size_t " hashlen ", mdex_entry_t " *entry ");"
.BI "int mdex_getalias(mdex_t " *mdex ", const char " *path ", mdex_entry_t " *entry ");"
.fi
.PP
Compile and link with \fI\-llibrecast\fP.
.SH DESCRIPTION
The
.BR mdex_get
function retrieves an entry from the multicast index
.IR mdex
using
.IR hash
(of length
.IR hashlen )
as the key, and returns a copy of the data in
.IR entry
if provided.
If
.IR entry
is NULL, the return value can be used to check if an entry exists in the index
without retrieving it.
.PP
If no matching entry is found in the index, -1 is returned and errno is set to
.BR ENOENT .
.PP
.IR hashlen
can be shorter than the full length of the hash stored with
.BR mdex_put (3)
and will return the first entry matching the truncated hash.
This allows us to store the full 32 byte hash in the index, but still match against the
truncated hash derived from, say, the 14 bytes of an IPv6 multicast group
address.
.PP
The
.BR mdex_getalias()
function is a wrapper which calls
.BR mdex_get()
with the hash of the NUL-terminated string
.IR path ,
returning the result.
.SH RETURN VALUE
.BR mdex_get ()
returns zero on success.
On error, \-1 is returned, and
.I errno
is set to indicate the error.
.SH ERRORS
.TP
.BR EINVAL
Invalid argument. Both
.IR mdex
and
.IR hash
are required (not NULL), and
.IR hashlen
> 0.
.PP
.BR ENOENT
No entry found matching
.IR hash .
.TP
.BR ELOOP
Infinite loop. Alias points to itself.
.SH SEE ALSO
.BR mdex_init (3),
.BR mdex_free (3),
.BR mdex_put (3),
.BR mdex_del (3),
.BR lc_share (3)