.TH MDEX_ADD 3 2023-06-20 "LIBRECAST" "Librecast Programmer's Manual"
.SH NAME
mdex_add, mdex_addfile, mdex_alias \- index data, files and directories
.SH LIBRARY
Librecast library
.RI ( liblibrecast ", " \-llibrecast )
.SH SYNOPSIS
.nf
.B #include <librecast/mdex.h>
.PP
.BI "int mdex_add(mdex_t " *mdex ", void " *data ", size_t " len ", q_t " *q ", int " flags ");"
.BI "int mdex_addfile(mdex_t " *mdex ", const char " *path ", q_t " *q ", int " flags ");"
.BI "int mdex_alias(mdex_t " *mdex ", unsigned char " *alias ", size_t " aliaslen ",
.BI "               unsigned char " *hash ", size_t " hashlen ");"
.fi
.PP
Compile and link with \fI\-llibrecast\fP.
.SH DESCRIPTION
The
.BR mdex_add
function builds a merkle tree from
.IR data
with length
.IR len
and adds entries for both the tree and chunks to
.IR mdex .
.PP
The
.BR mdex_addfile
function builds a merkle tree from the file or directory at
.IR path
and adds entries for the trees and chunks to
.IR mdex .
.PP
The
.BR mdex_alias
function adds an entry
.IR alias
of length
.IR aliaslen
which points to the entry
.IR hash
of length
.IR hashlen
which must already exist in
.IR mdex .
.PP
If
.IR q
is not NULL, it must point to a queue
.IR q_t
structure previously initialized with
.BR q_init (3).
This will be passed through to
.BR mtree_build (3)
to build the merkle tree.
This is normally used in conjunction with a threadpool created with
.BR q_pool_create (3)
with threads all calling
.BR q_job_seek (3).
.PP
The
.I flags
argument is the bitwise OR of zero of more of the following flags:
.TP
.BR MDEX_ALIAS
Entry is a pointer to another entry.
.PP
.BR MDEX_RAND
Entry should be sent using random symbols.
.PP
.BR MDEX_RECURSE
Recursively index all files and directories below
.IR path .
(mdex_addfile)
.PP
.BR MDEX_MOUNT
If set, stay within the same filesystem (i.e., do not cross mount points).
.TP
.BR MDEX_SYMLINK
Follow symbolic links when recursively indexing.
.PP
.SH RETURN VALUE
These function return 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 ENOMEM
Not enough space/cannot allocate memory (POSIX.1-2001).
.PP
.SH SEE ALSO
.BR mdex_init (3),
.BR mdex_free (3),
.BR mdex_get (3),
.BR mdex_put (3),
.BR mdex_del (3),
.BR mtree_build (3),
.BR q_init (3),
.BR q_pool_create (3),
.BR q_job_seek (3)
.BR lc_share (3)